Menu

Rate this page:

Thanks for rating this page!

We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

Status Callbacks

Rooms Status Callbacks

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.

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

Rooms Status Callback Events

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

Event Description
room-created Room created.
room-ended Room completed. (Note: Rooms created by the REST API will fire room-ended event when room is empty for 5 minutes.)
participant-connected Participant joined the Room.
participant-disconnected Participant left the Room.
track-added Participant added a Track.
track-removed Participant removed a Track.
track-enabled Participant unpaused a Track.
track-disabled Participant paused a Track.
recording-started Recording for a Track began
recording-completed Recording for a Track completed
recording-failed Failure during a recording operation request

Example

A curl example of configuring the StatusCallback URL.

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

Rooms Status Callback request parameters

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

Parameter Event Description
AccountSid All The AccountSid associated with this Room
RoomName All The UniqueName of the Room generating this event.
RoomSid All The Sid of the Room generating this event.
RoomStatus All The Status of the Room generating this event.
StatusCallbackEvent All The Room event. For example, room-created. See Rooms Status Callback Events for the complete list.
Timestamp All Time of the event, conformant to UTC ISO 8601 Timestamp.
ParticipantSid All Participant and Track Events The Sid for the Participant generating this event.
ParticipantStatus All Participant and Track Events The current Status of the Participant generating this event - either connected or disconnected.
ParticipantDuration Only on participant-disconnected event The total duration the Participant remained connected to the Room.
ParticipantIdentity All Participant and Track Events The Identity of the Participant generating this event. Participant identities are set via the Participant's Access Token
RoomDuration Only on room-ended The total duration of the Room, in seconds.
TrackSid All Track events The Sid of the Track.

Recordings Status Callback request parameters

The parameters below are included in the recording-* related events.

Parameter Event type Description
AccountSid All recording-* events Twilio Account SID.
RecordingSid All recording-* events RecordingSID.
Timestamp All recording-* events Time of the event, conformant to UTC ISO 8601 Timestamp.
StatusCallbackEvent All recording-* events The Room event. For example, recording-started.
RoomSid All recording-* events The Sid of the Room generating this recording.
RoomName All recording-* events The given name of the Room generating this recording.
ParticipantSid All recording-* events The Sid of the Participant generating this recording.
SourceSid All recording-* events This recording’s source TrackSID, MTxxx.
RecordingUri All recording-* events The relative URL to retrieve this recording's metadata.
MediaUri Only on recording-completed URL to fetch the generated media.
Duration Only on recording-completed Duration of the recording.
Size Only on recording-completed Total number of bytes recorded.
Container All recording-* events Container of the recording. Container used are mka for audio recordings and mkv for video recordings.
Codec All recording-* events Codec used for this recording. This could be PCMU or OPUS for audio recordings, and VP8 or H264 for video recordings.
ParticipantIdentity All recording-* events The Identity of the Participant generating this event. Participant identities are set via the Participant's Access Token.
TrackName All recording-* events The name that was given to the source track of this recording. If no name is given, the SourceSid is used.
FailedOperation Only on recording-failed Operation that failed: RecordingStart | RecordingComplete | RecordingUpload.

Compositions Status Callback events

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

Event Description
composition-started The media processing task started.
composition-available The media processing tasks completed and the Composition media file can be downloaded.
composition-progress Progress report for the media composition task, sent approximately every 10%.
composition-failed The media processing task failed.

Compositions Status Callback request parameters

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

Parameter Event type Description
AccountSid All composition-* events Twilio Account SID.
CompositionSid All composition-* events SID of the Composition.
CompositionUri All composition-* events The relative URL to retrieve the Composition's metadata.
MediaUri Only on composition-available The relative URL to fetch the composed media.
Duration Only on composition-available Duration of the composition.
Size Only on composition-available Total number of bytes of the resulting composition.
PercentageDone Only on composition-progress Percentage of composition done.
SecondsRemaining Only on composition-progress Estimated time remaining for the composition job to be finished (in seconds).
FailedOperation Only on composition-failed Operation that failed.
ErrorMessage Only on composition-failed Human-readable message that provides more information about the error.
StatusCallbackEvent All composition-* events The Composition event. For example, composition-started.
Timestamp All composition-* events Time of the event, conformant to UTC ISO 8601 Timestamp.
                                             |

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the Twilio tag on Stack Overflow.

Loading Code Sample...