Skip to contentSkip to navigationSkip to topbar
Rate this page:
On this page

Status Callbacks


(warning)

Warning

This page is for reference only. We are no longer onboarding new customers to Programmable Video. Existing customers can continue to use the product until December 5, 2024(link takes you to an external page).
We recommend migrating your application to the API provided by our preferred video partner, Zoom. We've prepared this migration guide(link takes you to an external page) to assist you in minimizing any service disruption.


Overview

overview page anchor

Status Callbacks allow you to receive events related to the REST resources managed by Twilio: Rooms, Recordings and Compositions.

All HTTP requests set the "Content-Type" header to “application/x-www-form-urlencoded”.


Rooms Status Callbacks

rooms-callbacks page anchor

Rooms Status Callbacks allow you to receive events related to your Rooms via HTTP request. Configure a StatusCallback URL when creating a Room using the REST API, and Twilio will make an HTTP request (webhook) to that URL whenever an event takes place in the Room.

The Rooms API will generate the following Status Callback events.

Rooms Status Callback Events

rooms-callback-events page anchor

The following events are dispatched to webhook URL specified at Room creation.

EventDescription
room-createdRoom created.
room-endedRoom completed. (Note: Rooms created by the REST API will fire a room-ended event when the room is empty for the amount of time configured as the "unused room timeout" or "empty room timeout" value. Both the unused room timeout and empty room timeout values are 5 minutes by default. See Understanding Video Rooms for more information.)
participant-connectedParticipant joined the Room.
participant-disconnectedParticipant left the Room.
track-addedParticipant added a Track.
track-removedParticipant removed a Track.
track-enabledParticipant unpaused a Track.
track-disabledParticipant paused a Track.
recording-startedRecording for a Track began
recording-completedRecording for a Track completed
recording-failedFailure during a recording operation request

Example

example page anchor

A curl example of configuring the StatusCallback URL.


_10
curl -XPOST 'https://video.twilio.com/v1/Rooms' \
_10
-u '{API Key SID}:{API Secret}' \
_10
-d 'UniqueName=DailyStandup' \
_10
-d 'StatusCallback=https://hooks.yoursite.com/room-events' \
_10
-d 'StatusCallbackMethod=POST' \
_10
-d 'Type=peer-to-peer'

Rooms Status Callback request parameters

rooms-event-parameters page anchor

Twilio passes the following parameters in each of the above-listed events whenever it makes an HTTP request to the StatusCallback URL you've set:

ParameterEventDescription
AccountSidAllThe AccountSid associated with this Room
RoomNameAllThe UniqueName of the Room generating this event.
RoomSidAllThe Sid of the Room generating this event.
RoomStatusAllThe Status of the Room generating this event.
RoomTypeAllThe Type of the Room generating this event.
StatusCallbackEventAllThe Room event. For example, room-created. See Rooms Status Callback Events for the complete list.
TimestampAllTime of the event, conformant to UTC ISO 8601 Timestamp(link takes you to an external page).
ParticipantSidAll Participant and Track EventsThe Sid for the Participant generating this event.
ParticipantStatusAll Participant and Track EventsThe current Status of the Participant generating this event - either connected or disconnected.
ParticipantDurationOnly on participant-disconnected eventThe total duration the Participant remained connected to the Room.
ParticipantIdentityAll Participant and Track EventsThe Identity of the Participant generating this event. Participant identities are set via the Participant's Access Token
RoomDurationOnly on room-endedThe total duration of the Room, in seconds.
SequenceNumberAllThis is an internal field and does not represent the true order of this event in the Room. Use the Timestamp field to track the order of this event in relation to other Room events.
TrackSidAll Track eventsThe Sid of the Track.
TrackKindAll Track eventsThe Kind of the Track (data, audio or video).

Recordings Status Callback request parameters

recordings-event-parameters page anchor

The parameters below are included only in events related to Recordings.

ParameterEvent typeDescription
AccountSidAll recording-* eventsTwilio Account SID.
RecordingSidAll recording-* eventsRecordingSID.
TimestampAll recording-* eventsTime of the event, conformant to UTC ISO 8601 Timestamp(link takes you to an external page).
StatusCallbackEventAll recording-* eventsThe Room event. For example, recording-started.
RoomSidAll recording-* eventsThe Sid of the Room generating this recording.
RoomNameAll recording-* eventsThe given name of the Room generating this recording.
RoomTypeAllThe Type of the Room generating this event.
ParticipantSidAll recording-* eventsThe Sid of the Participant generating this recording.
SourceSidAll recording-* eventsThis recording's source TrackSID, MTxxx.
RecordingUriAll recording-* eventsThe relative URL to retrieve this recording's metadata.
MediaUriOnly on recording-completedURL to fetch the generated media.
DurationOnly on recording-completedDuration of the recording.
SizeOnly on recording-completedTotal number of bytes recorded.
MediaExternalLocationOnly on recording-completedURL to fetch the generated media if stored in external storage.
ContainerAll recording-* eventsContainer of the recording. Container used are mka for audio recordings and mkv for video recordings.
CodecAll recording-* eventsCodec used for this recording. This could be PCMU or OPUS for audio recordings, and VP8 or H264 for video recordings.
ParticipantIdentityAll recording-* eventsThe Identity of the Participant generating this event. Participant identities are set via the Participant's Access Token.
TrackNameAll recording-* eventsThe name that was given to the source track of this recording. If no name is given, the SourceSid is used.
OffsetFromTwilioVideoEpochAll recording-* eventsThe time in milliseconds elapsed between an arbitrary point in time, common to all group rooms, and the moment when the source room of this track started. This information provides a synchronization mechanism for recordings belonging to the same room.
TypeAll recording-* eventsThe type of track for this recording, audio or video.
FailedOperationOnly on recording-failedOperation that failed: RecordingStart, RecordingComplete, RecordingUpload.

Compositions Status Callbacks

compositions-callbacks page anchor

Composition Status Callbacks allow you to receive events related to your Compositions via HTTP request. You can configure the StatusCallback URL to receive your callbacks using two mechanisms:

  • When you create a Composition using directly the REST API, you can set the StatusCallback URL as a POST parameter. In this case, at that URL you will only receive events related to that specific Composition.
  • When you create a Composition Hook, you can set the StatusCallback URL at such Hook. In this case, at that URL you will receive events regarding that Hook as well as events regarding all Compositions created by such Hook.

Twilio will generate the following Status Callback events regarding your Compositions and Composition Hooks.

Compositions Status Callback Events

compositions-events page anchor

The following events are dispatched to Compositions and Composition Hooks StatusCallback URLs.

EventDescription
composition-enqueuedA new Composition has been created and enqueued for processing, but processing has not yet started. This event is only fired when the Composition is created through a Composition Hook.
composition-hook-failedThe Hook failed to create a new Composition.
composition-startedThe media processing task started.
composition-availableThe media processing tasks completed and the Composition media file can be downloaded.
composition-progressProgress report for the media composition task, sent approximately every 10%.
composition-failedThe media processing task failed.

Compositions Status Callback request parameters

compositions-event-parameters page anchor

The parameters below are included in the composition-* events.

ParameterEvent typeDescription
AccountSidAll composition-* eventsTwilio Account SID.
RoomSidAll composition-* eventsSID of the Group Room being the source of tracks for this Composition
HookSidcomposition-enqueued and composition-hook-failedSID of the Composition Hook
HookUricomposition-enqueued and composition-hook-failedThe relative URL to retrieve the Composition Hook metadata.
HookFriendlyNamecomposition-enqueued and composition-hook-failedThe friendly name of the Composition Hook.
CompositionSidAll composition-* events except for composition-hook-failedSID of the Composition.
CompositionUriAll composition-* events except for composition-hook-failedThe relative URL to retrieve the Composition's metadata.
MediaUriOnly on composition-availableThe relative URL to fetch the composed media.
DurationOnly on composition-availableDuration of the composition.
SizeOnly on composition-availableTotal number of bytes of the resulting composition.
MediaExternalLocationOnly on composition-availableURL to fetch the generated media if stored in external storage.
PercentageDoneOnly on composition-progressPercentage of composition done.
SecondsRemainingOnly on composition-progressEstimated time remaining for the composition job to be finished (in seconds).
FailedOperationcomposition-failed and composition-hook-failedOperation that failed.
ErrorMessagecomposition-failed and composition-hook-failedHuman-readable message that provides more information about the error.
StatusCallbackEventAll composition-* eventsThe Composition event. For example, composition-started.
TimestampAll composition-* eventsTime of the event, conformant to UTC ISO 8601 Timestamp(link takes you to an external page).

Rate this page: