Menu

Expand
Rate this page:

Status Callbacks

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.

We recommend migrating your application to the API provided by our preferred video partner, Zoom. We've prepared this migration guide to assist you in minimizing any service disruption.

Overview

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”.

Contents

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.

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 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-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 above-listed events 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.
RoomType All The Type 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.
SequenceNumber All This 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.
TrackSid All Track events The Sid of the Track.
TrackKind All Track events The Kind of the Track (data, audio or video).

Recordings Status Callback request parameters

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

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.
RoomType All The Type of the Room generating this event.
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.
MediaExternalLocation Only on recording-completed URL to fetch the generated media if stored in external storage.
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.
Type All recording-* events The type of track for this recording, audio or video.
FailedOperation Only on recording-failed Operation that failed: RecordingStart | RecordingComplete | RecordingUpload.

Compositions Status Callbacks

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

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

Event Description
composition-enqueued A 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-failed The Hook failed to create a new Composition.
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.
RoomSid All composition-* events SID of the Group Room being the source of tracks for this Composition
HookSid composition-enqueued and composition-hook-failed SID of the Composition Hook
HookUri composition-enqueued and composition-hook-failed The relative URL to retrieve the Composition Hook metadata.
HookFriendlyName composition-enqueued and composition-hook-failed The friendly name of the Composition Hook.
CompositionSid All composition-* events except for composition-hook-failed SID of the Composition.
CompositionUri All composition-* events except for composition-hook-failed 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.
MediaExternalLocation Only on composition-available URL to fetch the generated media if stored in external storage.
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 composition-failed and composition-hook-failed Operation that failed.
ErrorMessage composition-failed and composition-hook-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.
Rate this page:

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 by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.

Loading Code Sample...
        
        
        

        Thank you for your feedback!

        Please select the reason(s) for your feedback. The additional information you provide helps us improve our documentation:

        Sending your feedback...
        🎉 Thank you for your feedback!
        Something went wrong. Please try again.

        Thanks for your feedback!

        thanks-feedback-gif