Skip to contentSkip to navigationSkip to topbar
On this page

SIPREC



Start/Stop SIPREC

startstop-siprec page anchor

The SIPREC Resource allows you to start a stream on a phone call and send that stream to one of the available partners via a configured SIPREC Connector(link takes you to an external page). You can also stop streams started via the <Siprec> TwiML instruction.

Twilio operates as a Session Recording Client (SRC) for SIPREC, while Twilio's partners, such as Gridspace, operate as Session Recording Servers (SRS). Alternatively, you can provision your own SRS using the Twilio SIPREC Connector(link takes you to an external page).

The SRC sends the SIPREC media to be recorded to the SRS. The SRS is responsible for storing/processing the media.

Twilio forks the audio stream of the current call and sends it in real-time to the configured connector.

There are a maximum of four forked streams allowed per call. By default, <Siprec> uses two forked streams: one for the inbound track and one for the outbound track.

Dual-Tone Multi-Frequency (DTMF) tones aren't sent to the connector.

Any communication issues encountered while streaming media to the partner will be reported in the Twilio Debugger with additional information about the failure.

Property nameTypeRequiredDescriptionChild properties
sidSID<SR>

Optional

Not PII

The SID of the Siprec resource.

Pattern: ^SR[0-9a-fA-F]{32}$Min length: 34Max length: 34

account_sidSID<AC>

Optional

The SID of the Account that created this Siprec resource.

Pattern: ^AC[0-9a-fA-F]{32}$Min length: 34Max length: 34

call_sidSID<CA>

Optional

The SID of the Call the Siprec resource is associated with.

Pattern: ^CA[0-9a-fA-F]{32}$Min length: 34Max length: 34

namestring

Optional

The user-specified name of this Siprec, if one was given when the Siprec was created. This may be used to stop the Siprec.


statusenum<string>

Optional

The status - one of stopped, in-progress

Possible values:
in-progressstopped

date_updatedstring<date-time-rfc-2822>

Optional

The date and time in GMT that this resource was last updated, specified in RFC 2822(link takes you to an external page) format.


uristring

Optional

The URI of the resource, relative to https://api.twilio.com.


Configuring a SIPREC Connector

configure-siprec-connector page anchor

Connectors are configured in Marketplace to ensure that the credentials needed to send the stream to a partner are stored securely. You can install and manage connectors in the Stream Connectors Console page in Marketplace(link takes you to an external page) or via the Marketplace API using the InstalledAddOns Resource.

(information)

Info

If you'd like to use a specific partner and don't find them in the available Stream Connectors(link takes you to an external page) list, contact Twilio Support directly with details about your desired partner through the Console(link takes you to an external page) or Help Center(link takes you to an external page) to submit a ticket.

Twilio's SIPREC Connector

twilios-siprec-connector page anchor

Configure your SIPREC Connector using the parameters below.

Parameter NameDescription
Installed Add-On SIDThe unique identifier for your connector. It's automatically configured when you install a connector.
Unique NameThe unique name to use for your SIPREC Connector. This is the name you will use when initiating the the <Siprec> TwiML instruction or using the API.
Use InSepcifies that the connector is available to your Voice Applications.
Session Recording ServerThe SIP URI of the server you want to stream the media to. This should be a standard SIP URI. For example, sip:name@example.com:5060.
Credentials Header NameThe SIP header name that your recording service uses to pass the Authorization credentials. For example, X-Auth-Token.
CredentialsThe credential token or value for Authorization to be sent to your recording service. This value will be hidden when entered in the text box.

Using Twilio's SIPREC Connector provides some additional SIP features. The SIP URI within the Session Recording Server parameter supports additional parameters: secure which enables Secure Real-time Transport Protocol (SRTP), as well as, edge which allows you to control which Twilio edge your SIPREC connections egress by.

For example, to enable SRTP and set the edge location to the ashburn edge, you would provide populate SIP URI below as the Session Recording Server address:

sip:your-domain.com;secure=true&edge=ashburn


POST https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Calls/{CallSid}/Siprec.json

ParameterTypeDescription
AccountSid PathSID<AC>The SID of the Account that created this Siprec resource. Not PII
CallSid PathSID<CA>The SID of the Call the Siprec resource is associated with. Not PII
Name OptionalstringThe user-specified name of this Siprec, if one was given when the Siprec was created. This may be used to stop the Siprec. Not PII
ConnectorName OptionalstringUnique name used when configuring the connector via Marketplace Add-on. Not PII
Track OptionalstringOne of inbound_track, outbound_track, both_tracks. Not PII
StatusCallback OptionaluriAbsolute URL of the status callback. Not PII
StatusCallbackMethod Optionalhttp_methodThe http method for the StatusCallback (one of GET, POST). Not PII
Parameter1.Name OptionalstringParameter name Not PII
Parameter1.Value OptionalstringParameter value Not PII

Using the SIPREC status callback

using-the-siprec-status-callback page anchor

SIPREC is a protocol that enables recording and sending streams to one of the available partners via the SIPREC connector configuration. With the addition of a status callback, you can now get detailed information about the status of a SIPREC session. This feature can be used to quickly detect and troubleshoot any unexpected issues with a SIPREC session, such as an unexpected failure or interruption.

There are two ways to use SIPREC status callback:

From <Siprec> TwiML, for example:

1
<Start>
2
<Siprec name="my-first-siprec" connectorName="Gridspace1" statusCallback="https://87b252436d40.ngrok.app" statusCallbackMethod="GET"/>
3
</Start>

From Start/Stop SIPREC API, for example:

1
curl -u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN -XPOST https://api.twilio.com/2010-04-01/Accounts/$TWILIO_ACCOUNT_SID/Calls/CAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Siprec.json --data-urlencode \
2
"Name=my-first-siprec" --data-urlencode "ConnectorName=Gridspace1" --data-urlencode "StatusCallback=https://XXXXXXXX.ngrok.app" --data-urlencode "StatusCallbackMethod=GET"

The request to the status callback contains the standard TwiML request parameters and the following parameters:

ParameterDescription
AccountSidThe SID of the Account that created this Siprec resource. Not PII
CallSidThe SID of the Call the Siprec resource is associated with. Not PII
SiprecSidThe SID of the Siprec resource is associated with. Not PII
SiprecNameThe Name of the Siprec resource is associated with. Not PII
SiprecEventThe Event of the Siprec callback. Values can be: siprec-started, siprec-stopped, siprec-error Not PII
TimestampThe timestamp of when the Siprec callback was made. Not PII

If an error has occurred, additional parameters SiprecError, SiprecErrorCode will be set as well. These params will provide context on the error that has occurred with the SIPREC resource.


Update a Siprec resource

update-a-siprec-resource page anchor

POST https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Calls/{CallSid}/Siprec/{Sid}.json

Property nameTypeRequiredPIIDescription
AccountSidSID<AC>required

The SID of the Account that created this Siprec resource.

Pattern: ^AC[0-9a-fA-F]{32}$Min length: 34Max length: 34

CallSidSID<CA>required

The SID of the Call the Siprec resource is associated with.

Pattern: ^CA[0-9a-fA-F]{32}$Min length: 34Max length: 34

Sidstringrequired

The SID of the Siprec resource, or the name used when creating the resource

Encoding type:application/x-www-form-urlencoded
SchemaExample
Property nameTypeRequiredDescriptionChild properties
Statusenum<string>required
Possible values:
stopped
Update a SiprecLink to code sample: Update a Siprec
1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4
// Find your Account SID and Auth Token at twilio.com/console
5
// and set the environment variables. See http://twil.io/secure
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9
10
async function updateSiprec() {
11
const siprec = await client
12
.calls("CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
13
.siprec("Sid")
14
.update({ status: "stopped" });
15
16
console.log(siprec.sid);
17
}
18
19
updateSiprec();

Output

1
{
2
"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3
"call_sid": "CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
4
"sid": "Sid",
5
"name": null,
6
"status": "stopped",
7
"date_updated": "Thu, 30 Jul 2015 20:00:00 +0000",
8
"uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Siprec/SRaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json"
9
}