Skip to contentSkip to navigationSkip to topbar
On this page

TwiML™️ Voice: <Siprec>


The <Siprec> TwiML instruction 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).

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.

The most basic use of <Siprec> is:

1
<?xml version="1.0" encoding="UTF-8"?>
2
<Response>
3
<Start>
4
<Siprec connectorName="my_addon_connector" />
5
</Start>
6
</Response>

This TwiML instructs Twilio to fork the audio stream of the current call and send 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.

<Siprec> starts the audio stream asynchronously and immediately continues with the next TwiML instruction. If there is no instruction, the call will be disconnected. In order to avoid this, provide a TwiML instruction to continue the call.

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


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.

If you use Twilio's SIPREC Connector, the SIP URI within the Session Recording Server parameter supports the following optional parameters:

  • secure: Enables Secure Real-time Transport Protocol (SRTP).
  • edge: Specifies which Twilio edge your SIPREC connections will egress from.

For example, to enable SRTP and set the edge location to the ashburn edge, you can set Session Recording Server to sip:example.com;secure=true&edge=ashburn.


<Siprec> supports the following attributes:

Attribute NameDescriptionDefault Value
nameOptional. Unique name for the Stream.none
connectorNameUnique name used when configuring the connector via Marketplace Add-on.none
trackOptional. inbound_track, outbound_track, both_tracksinbound_track
statusCallbackOptional. Absolute URL of the status callback.none
statusCallbackMethodOptional. The http method for the statusCallback (one of GET, POST).none

Providing a name will allow you to reference the SIPREC stream directly. This name must be unique per Call SID.

For instance by naming the Stream my_first_siprec_stream:

1
<Start>
2
<Siprec name="my_first_siprec_stream" connectorName="my_addon_connector" />
3
</Start>

You can later use the unique name of my_first_siprec_stream to stop the stream.

1
<Stop>
2
<Siprec name="my_first_siprec_stream" />
3
</Stop>

The connectorName attribute must contain a unique name corresponding to the SIPREC Stream Connector installed in your Twilio Marketplace Account in the Twilio Console. Learn more in the Configuring a SIPREC Connector section.

For example, to use Gridspace Connector, use connectorName="Gridspace_1", where Gridspace_1 is the unique name specified when configuring Gridspace Connector in the Stream Connectors page. In order to start a SIPREC session, you must first configure a SIPREC Connector.

The track attribute allows you to optionally request to receive a specific track of a call. On any given active call within Twilio there are inbound and outbound tracks, the former represents the audio Twilio receives from the call, and the latter represents the audio generated by Twilio to the call. By default Twilio always streams the inbound track of a call. To request Twilio to stream audio it generates use outbound_track, or to receive both tracks of a call use both_tracks. If both_tracks is used, you will receive both the inbound and outbound media event.

SIPREC is a protocol that enables recording and sending streams to one of the available partners via the SIPREC connector configuration. With a status callback, you can monitor SIPREC session statuses to quickly detect and troubleshoot issues like failures or interruptions. You can subscribe to status callbacks by adding the statusCallback and statusCallbackMethod as attributes.

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

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 occurs, additional parameters SiprecError and SiprecErrorCode will provide details about the issue with the SIPREC resource.


Passing Custom Parameters

passing-custom-parameters page anchor

SIPREC partners often require additional metadata along with the audio stream. You can provide custom data by using <Parameter>

1
<Start>
2
<Siprec name="my_stream_1" connectorName="Gridspace_1" track="outbound_track">
3
<Parameter name="Custom1" value ="Bob" />
4
<Parameter name="Custom2" value ="Blah" />
5
<Parameter name="Custom3" value ="Alice" />
6
</Siprec>
7
</Start>

The exact names of parameters vary from partner to partner. Refer to the appropriate partner tile in the Stream Connectors page(link takes you to an external page) to identify the custom parameters that need to be passed.


Start a new SIPREC stream with the name of My SIPREC Stream and a connector of Gridspace_1.

Start a new SIPREC StreamLink to code sample: Start a new SIPREC Stream
1
const VoiceResponse = require('twilio').twiml.VoiceResponse;
2
3
const response = new VoiceResponse();
4
const start = response.start();
5
start.siprec({
6
name: 'My SIPREC Stream',
7
connectorName: 'Gridspace_1'
8
});
9
10
console.log(response.toString());

Output

1
<?xml version="1.0" encoding="UTF-8"?>
2
<Response>
3
<Start>
4
<Siprec name="My SIPREC Stream" connectorName="Gridspace_1" />
5
</Start>
6
</Response>

Global Media IP Gateways

global-media-ip-gateways page anchor

Public Connections - Global Media IP Range

The Public Connections Destination IP Ranges and Port Ranges are now identical across all locations:

Secure Media (ICE/STUN/SRTP) Edge LocationsProtocolSource IPSource Port †Destination IP RangesDestination Port Range
sydney (au1 )
sao-paulo (br1 )
dublin (ie1 )
frankfurt (de1 )
tokyo (jp1 )
singapore (sg1 )
ashburn (us1 )
umatilla (us2 )
roaming (gll )
UDPANYANY168.86.128.0/1810,000 - 60,000

† The SDK will select any available port from the ephemeral range. On most machines, this means the port range 1,024 to 65,535.

Regional Signaling IP Gateways

regional-signaling-ip-gateways page anchor

To receive SIPREC streams from Twilio, you must allow ALL of Twilio's following IP address ranges and ports on your firewall for signaling traffic. Twilio doesn't guarantee which edge location the media will egress from, without using the edge parameter since it can depend on which PSTN-SIP Gateway delivers the call to which Twilio edge location.

(information)

Info

These IP addresses are provided only for firewall configuration purposes. Not all of these IP addresses will host active gateways at a given time. However, your infrastructure must always be prepared to accept signaling traffic from any of these IP addresses.

North America Virginia Gateways

north-america-virginia-gateways page anchor
1
54.172.60.0/30 which translates to:
2
54.172.60.0
3
54.172.60.1
4
54.172.60.2
5
54.172.60.3
6
Ports: 5060 (UDP/TCP), 5061 (TLS)
7

North America Oregon Gateways

north-america-oregon-gateways page anchor
1
54.244.51.0/30 which translates to:
2
54.244.51.0
3
54.244.51.1
4
54.244.51.2
5
54.244.51.3
6
Ports: 5060 (UDP/TCP), 5061 (TLS)
7
1
54.171.127.192/30 which translates to:
2
54.171.127.192
3
54.171.127.193
4
54.171.127.194
5
54.171.127.195
6
Ports: 5060 (UDP/TCP), 5061 (TLS)
7

Europe Frankfurt Gateways

europe-frankfurt-gateways page anchor
1
35.156.191.128/30 which translates to:
2
35.156.191.128
3
35.156.191.129
4
35.156.191.130
5
35.156.191.131
6
Ports: 5060 (UDP/TCP), 5061 (TLS)
7

Asia-Pacific Tokyo Gateways

asia-pacific-tokyo-gateways page anchor
1
54.65.63.192/30 which translates to:
2
54.65.63.192
3
54.65.63.193
4
54.65.63.194
5
54.65.63.195
6
Ports: 5060 (UDP/TCP), 5061 (TLS)
7

Asia-Pacific Singapore Gateways

asia-pacific-singapore-gateways page anchor
1
54.169.127.128/30 which translates to:
2
54.169.127.128
3
54.169.127.129
4
54.169.127.130
5
54.169.127.131
6
Ports: 5060 (UDP/TCP), 5061 (TLS)
7

Asia-Pacific Sydney Gateways

asia-pacific-sydney-gateways page anchor
1
54.252.254.64/30 which translates to:
2
54.252.254.64
3
54.252.254.65
4
54.252.254.66
5
54.252.254.67
6
Ports: 5060 (UDP/TCP), 5061 (TLS)
7

South America São Paulo Gateways

south-america-são-paulo-gateways page anchor
1
177.71.206.192/30 which translates to:
2
177.71.206.192
3
177.71.206.193
4
177.71.206.194
5
177.71.206.195
6
Ports: 5060 (UDP/TCP), 5061 (TLS)
7