One can create a room with recording enabled and a webhook_event_url using the following request:
curl -X "POST" "https://api.telnyx.com/v2/rooms" \
-H 'Authorization: Bearer <my-telnyx-api-key>' \
-H 'Content-Type: application/json; charset=utf-8' \
-d $'{
"enable_recording": true,
"webhook_event_url": "<my-webhook-url>",
"unique_name": "my-unique-room-name"
}'If successful, you'll get the room id in the response.
It's also possible to enable recording for an existing room with:
curl -X "PATCH" "https://api.telnyx.com/v2/rooms/<my-room-id>" \
-H 'Authorization: Bearer <my-telnyx-api-key>' \
-H 'Content-Type: application/json; charset=utf-8' \
-d $'{
"enable_recording": true
}'Please note any currently active session in the room will NOT have recording enabled, and it only enables recording for new sessions created after.
Also if the room doesn't already have webhook_event_url set, one can update it and add one:
curl -X "PATCH" "https://api.telnyx.com/v2/rooms/<my-room-id>" \
-H 'Authorization: Bearer <my-telnyx-api-key>' \
-H 'Content-Type: application/json; charset=utf-8' \
-d $'{
"webhook_event_url": "<my-webhook-url>"
}'If webhook_event_url is set for the room and there is no active session for the room, when the first participant joins, a new session will be created and you should receive a session started webhook event, which looks like this:
{
"data": {
"event_type": "video.room.session.started",
"id": "529eac66-5992-46fc-9758-2a80765bb714",
"occurred_at": "2022-03-01T02:38:52.038150Z",
"payload": {
"room_id": "fbd8f77f-5d8c-4e24-90a9-ca31ca97a0d4",
"session_id": "cedd5466-3189-4aad-8b8b-52bd5094a906"
},
"record_type": "event"
},
"meta": {
"attempt": 1,
"delivered_to": "https://webhook.site/ae2228cb-b414-4428-ac5a-950a7e6603bc"
}
}And that would be a convenient way to get the session id.
If webhook_event_url is not set for the room, you can get the session id while the session is active with:
curl "https://api.telnyx.com/v2/rooms/<my-room-id>" \
-H 'Authorization: Bearer <my-telnyx-api-key>'There is a active_session_id field in the response, which is the id of the currently active session.
If webhook_event_url is set for the room, when participants join and start video, you would receive recording started webhook events for video recordings:
{
"data": {
"event_type": "video.room.recording.started",
"id": "3e2f1093-b0e2-4676-94f1-f388146bdd2f",
"occurred_at": "2022-03-01 05:49:19.679223Z",
"payload": {
"participant_id": "77082c8c-9fff-4ba9-a7e9-46be410eb2c6",
"recording_id": "3e8512e2-65d2-43ce-86d8-fb0016cf7a01",
"room_id": "2201b930-bc70-450a-91e7-795d95303662",
"session_id": "e4aa5752-208d-4e3e-bc10-cea1b60eee04",
"type": "video"
},
"record_type": "event"
},
"meta": {
"attempt": 1,
"delivered_to": "https://webhook.site/ae2228cb-b414-4428-ac5a-950a7e6603bc"
}
}You can collect the relevant recording ids, which will be used as video_sources when creating a video composition later.
Note: if a participant unmute mic, you'd also receive a recording started event for the particpant's audio recording. But at this stage we are using mixed audio recording in composition, so you can ignore those events for the purpose of video composition.
If webhook_event_url is not set for the room, you can get the recording ids with:
curl "https://api.telnyx.com/v2/room_recordings/?filter\[session_id\]=<my-session-id>" \
-H 'Authorization: Bearer <my-telnyx-api-key>'You'll get a list of recordings in the response. Please make sure that all of video recordings have status as completed before creating a video composition for the session.
A video composition can be created with the following request:
curl -X "POST" "https://api.telnyx.com/v2/room_compositions" \
-H 'Authorization: Bearer <my-telnyx-api-key>' \
-H 'Content-Type: application/json; charset=utf-8' \
-d $'{
"session_id": "<my-session-id>",
"video_layout": {
"presentation": {
"z_pos": "1",
"video_sources": [
<recording id for sceensharing>
]
},
"participants": {
"z_pos": "2",
"x_pos": "10",
"y_pos": "530",
"width": "1260",
"height": "160",
"max_rows": "2",
"video_sources": <list of ids for participant's video recordings>
}
},
"webhook_event_url": "<my-webhook-url>",
"resolution": "1280x720"
}'Note: at this stage, you can only create a video composition after the session has ended and all the recordings are available.
If webhook_event_url is set for the composition, you would receive a composition completed event with Amazon S3 download url for the resulting video:
{
"data": {
"event_type": "video.room.composition.completed",
"id": "f7543d82-b7c2-49ea-b44c-0d1fb90aa8cb",
"occurred_at": "2022-03-02 02:32:29.713160Z",
"payload": {
"composition_id": "2f9521f7-2cb5-4eec-b9f1-09e448d9b234",
"download_url": "[REDACTED AWS S3 URL]",
"duration_secs": 154,
"format": "mp4",
"resolution": null,
"room_id": "2201b930-bc70-450a-91e7-795d95303662",
"session_id": "e4aa5752-208d-4e3e-bc10-cea1b60eee04",
"size_mb": 9.5
},
"record_type": "event"
},
"meta": {
"attempt": 1,
"delivered_to": "https://webhook.site/ae2228cb-b414-4428-ac5a-950a7e6603bc"
}
}Note: webhook_event_url for a composition is independent of the webhook_event_url for a room. If you want to receive composition related webhook events, you'll need to set it when creating the composition even if it's the same url.
If webhook_event_url is not set for the composition, you can retrieve the composition with this request:
curl "https://api.telnyx.com/v2/room_compositions/<my-composition-id>" \
-H 'Authorization: Bearer <my-telnyx-api-key>'Once composition is completed, the response will have the AWS S3 download url for the resulting video.
Note: the AWS S3 download url is valid for an hour after it's generated.