Status Callbacks
Overview
Status Callbacks allow you to receive events related to the REST resources managed by Twilio: MediaProcessors and PlayerStreamers.
All HTTPS requests set the "Content-Type" header to “application/x-www-form-urlencoded”.
Contents
MediaProcessors Status Callbacks
MediaProcessors Status Callbacks allow you to receive events related to your MediaProcessor via HTTPS request. Configure a StatusCallback URL when creating a MediaProcessor using the REST API, and Twilio will make an HTTPS request (webhook) to that URL whenever an event takes place in the MediaProcessor.
MediaProcessors Status Callback Events
The following events are dispatched to webhook URL specified at MediaProcessor creation.
| Event | Description |
|---|---|
| media-processor-started | MediaProcessor started sending media to the Outputs. |
| media-processor-ended | MediaProcessor stopped sending media to the Outputs. |
| media-processor-failed | MediaProcessor failed; see ErrorMessage and EndedReason for details. |
Example
A curl example of configuring the StatusCallback URL.
curl -X POST 'https://media.twilio.com/v1/MediaProcessors' \
-u 'SKXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:your_api_key_secret' \
-d 'Extension=video-composer-v2' \
-d 'ExtensionContext={"room": {"name": "RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"}, "outputs": ["VJXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"]}' \
-d 'StatusCallback=https://hooks.yoursite.com/mediaprocessor-events' \
-d 'StatusCallbackMethod=POST'
MediaProcessors Status Callback request parameters
Twilio passes the following parameters in each of the MediaProcessors Status Callback events whenever it makes an HTTPS request to the StatusCallback URL you've set:
| Parameter | Event | Description |
|---|---|---|
| AccountSid | All | The AccountSid associated with this MediaProcessor. |
| MediaProcessorSid | All | The Sid of the MediaProcessor generating this event. |
| Extension | All | The name or URL of your extension. |
| ExtensionContext | All | The extension context JSON dictionary. |
| StatusCallbackEvent | All | The MediaProcessor event. For example, media-processor-started. See MediaProcessors Status Callback Events for the complete list. |
| Timestamp | All | Time of the event, given as a UTC ISO 8601 Timestamp. |
| Url | All | The absolute URL of the MediaProcessor resource. |
| Duration | media-processor-ended, media-processor-failed |
The total duration of the MediaProcessor session, in seconds. |
| ErrorMessage | Only on media-processor-failed |
A human readable message providing additional information about the error. |
| EndedReason | media-processor-ended, media-processor-failed |
The reason for the MediaProcessor termination. See MediaProcessors EndedReason values. |
PlayerStreamer Status Callbacks
PlayerStreamer Status Callbacks allow you to receive events related to your PlayerStreamer via HTTPS request. Configure a StatusCallback URL when creating a PlayerStreamer using the REST API, and Twilio will make an HTTPS request (webhook) to that URL whenever an event takes place in the PlayerStreamer.
PlayerStreamer Status Callback Events
The following events are dispatched to webhook URL specified at MediaProcessor creation.
| Event | Description |
|---|---|
| stream-started | The stream has started and it is available to Player SDKs. |
| stream-ended | The stream has stopped and will and will no longer be playable. |
| stream-failed | The stream has stopped due to a failure and will no longer be playable. |
Example
A curl example of configuring the StatusCallback URL.
curl -X POST 'https://video.twilio.com/v1/PlayerStreamers' \
-u '{API Key SID}:{API Secret}' \
-d 'StatusCallback=https://hooks.yoursite.com/playerstreamer-events' \
-d 'StatusCallbackMethod=POST'
PlayerStreamer Status Callback request parameters
Twilio passes the following parameters in each of the above-listed events whenever it makes an HTTPS request to the StatusCallback URL you've set:
| Parameter | Event | Description |
|---|---|---|
| AccountSid | All | The AccountSid associated with this PlayerStreamer. |
| PlayerStreamerSid | All | The Sid of the PlayerStreamer generating this event. |
| StatusCallbackEvent | All | The PlayerStreamer event. For example, stream-started. See PlayerStreamer Status Callback Events for the complete list. |
| Timestamp | All | Time of the event, given as a UTC ISO 8601 Timestamp. |
| Source | All | The source of the media stream. |
| Url | All | The absolute URL of the PlayerStreamer resource. |
| Duration | player-streamer-ended, player-streamer-failed |
The total duration of the PlayerStreamer session, in seconds. |
| ErrorMessage | Only on player-streamer-failed |
A human readable message providing additional information about the error. |
| EndedReason | player-streamer-ended, player-streamer-failed |
The reason for the PlayerStreamer termination. See PlayerStreamer EndedReason values. |
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.
