Recording Status Callbacks make it easy to manage your Twilio Programmable Voice Call recordings. Call recordings require post-processing, and may not always be ready right away when your call ends. Requesting a callback tells Twilio to reach out to your webhook with a URL for the recording file as soon as it’s ready. Your webhook app can then respond with your own code for forwarding the recording file link, downloading the recording locally, or anything else you need. Read on for more information.
Recording Status Callback Events
Call Recordings have four possible statuses. You can subscribe to webhook events for each of these recording status changes (as described further in the next section):
- In-progress
- Completed
- Absent
- Failed
The In-progress event fires off immediately when the call recording has started.
The Completed event indicates processing for your call recording file has finished, and the file is available for access. Any Completed status recording can be downloaded with the RecordingUrl parameter provided in the callback.
The Absent event indicates there is no recording file available for this call. Recordings with the Absent status indicate one of two possible issues:
- The call recording was too short to be processed.
- The call recording was silent, and your project is set to automatically delete silent recordings (If you wish to change this option, please Contact Support).
Either of these issues would also result in an Error code visible as a property returned in the API Resource response, and a parameter in the RecordingStatusCallback:
- Too Short: Error 16101
- Silent: Error 16102
The Failed event, only applicable if the feature Voice Recording Encryption is enabled on your project, indicates the recording failed encryption and is unavailable due to one of two reasons:
- There was no public key for encryption configured on the project.
- There was an internal system error that resulted in a failed encryption.
Either of these issues would also result in an Error code 16104 visible as a property returned in the API Resource response and as a parameter in the RecordingStatusCallback.
Requesting Recording Status Callbacks and Events
Recording Status Callbacks and Events can be requested whenever you tell Twilio to begin recording a call:
- In your API request for an outgoing call
- In the TwiML for a
<Dial>forwarded call - In the TwiML for a
<Conference>recording - In the TwiML for a
<Record> - In the API request when enabling recording with the Call Recording Controls API
For more examples, including sample code, please see Recording a Phone Call with Twilio.
Managing Recording Files with Recording Status Callbacks
Recording Status Callbacks can be useful for automating your recording file downloading and deleting. This helps make sure you have local access to any recording files as soon as they’re ready, and also helps prevent additional billing for your Twilio call recording file storage.
Call recordings can be downloaded via HTTP GET calls to the Recordings API resource. The recording file can then be removed with an HTTP DELETE call to the same resource. For full details, please see the following resources:
Troubleshooting Recording Status Callbacks
If you run into issues with Recording Status Callbacks, we suggest checking the Recording Details page for your recording in the Console Recording Logs. Scroll down to the request inspector to see the HTTP Response code we received from your callback URL, along with the message in the Body.
In this example, the callback URL returned an HTTP 404 response, with the message 404 - Not Found:
A successful request to your callback URL will return an HTTP 200 response: