Voice

Sip

View as Markdown

<Dial> verb’s <Sip> noun permits the set up of VoIP sessions using SIP (Session Initiation Protocol). You can send a call to any SIP endpoint.

When dialing an SIP endpoint, the transport defaults to TLS. If the SIP destination does not support TLS, you can set the transport to UDP or TCP by setting the transport manually. For example: sip:alice@example.com;transport=udp.

The <Sip> noun supports all of the <Dial> verb’s attributes with one exception: callerId is supported but not limited to a valid E.164 number. When using the <Sip> noun, the callerId attribute can be any alphanumeric string and include the following characters: +-_., but no whitespace.

For example, one can dial to a SIP destination with:

1<?xml version="1.0" encoding="UTF-8"?>
2<Response>
3    <Dial>
4        <Sip>sip:alice@example.com</Sip>
5    </Dial>
6</Response>

Noun attributes

codecs
stringDefaults to PCMU,PCMA

A comma separated list of codecs to offer to the SIP user agent. Select from PCMU, PCMA, G722, G729, and OPUS. Codecs are offered in the order specified.

method
stringDefaults to POST

The method attribute specifies whether the request to action is a GET or a POST. Valid values are GET or POST.

password
string

Password for SIP authentication.

sessionTimeout
integer

Non-negative value, in seconds, to use for the SIP Session-Expires header. If 0 or unset, SignalWire will pick the default (typically 600).

statusCallback
string

The URL to make requests to for each statusCallbackEvent event. See below for request parameters.

statusCallbackEvent
string

The current status of the call. The call moves from initiated to ringing when the phone starts ringing. It moves from ringing to answered when the phone call is answered. Finally, it moves from answered to completed when the call is terminated. The status will be set to completed through the following reasons: busy, canceled, completed, failed, or no-answer. To specify multiple events, separate each one with a space. See below for the different call statuses.

statusCallbackMethod
stringDefaults to POST

The type of HTTP request to use when requesting a statusCallback.

url
string

A specified URL for a document that runs on the callee’s end after the dialed number answers but before the call is connected. This allows the caller to provide information to the dialed number, giving them the opportunity to decline the call, before they answer the call. See below for request parameters.

username
string

Username for SIP authentication.

After a Dial attempt is made, SignalWire can make a request to the <Dial> verb’s action attribute. In addition to the Standard Request Parameters, the following are parameters passed back to your application when SignalWire makes the request.

DialSipCallId
string

The SIP call ID header of the request made to the remote SIP infrastructure.

DialSipHeader_
string

The name or value of any X-headers returned in the 200 response to the SIP INVITE request.

DialSipResponseCode
string

The SIP response code to the INVITE attempt.

Request parameters for sip_url

In addition to the Standard Request Parameters, the following are parameters passed back to your application when SignalWire makes a request to the <Sip> noun’s url attribute.

SipCallId
string

The SIP call ID header of the request made to the remote SIP infrastructure.

SipHeader
string

The name or value of any X-headers returned in the 200 response to the SIP INVITE request.

Status values for statusCallbackEvent

The statusCallbackEvent attribute has the following call status values:

ValueDescription
initiatedDialing of a call has begun.
ringingThe call has begun ringing.
answeredThe call has been answered.
completedThe call has been terminated. The status will be set to completed through the following reasons: busy, canceled, completed, failed, or no-answer.

Request parameters for the statusCallback URL

Payload
1{
2  "AccountSid": "b3877c40-da60-4998-90ad-b792e98472af",
3  "ApiVersion": "2010-04-01",
4  "AudioInAveragePtime": 20,
5  "AudioInDtmfPacketCount": 0,
6  "AudioInFlushPacketCount": 2,
7  "AudioInJitterMaxVariance": 8,
8  "AudioInJitterMinVariance": 1,
9  "AudioInLargestJbSize": 4,
10  "AudioInMos": "4.3",
11  "AudioInMediaPacketCount": 1842,
12  "AudioInSkipPacketCount": 1,
13  "AudioOutDtmfPacketCount": 0,
14  "AudioOutMediaPacketCount": 1840,
15  "CallbackSource": "call-progress-events",
16  "CallSid": "b3877c40-da60-4998-90ad-b792e98472ca",
17  "CallStatus": "completed",
18  "Direction": "outbound-api",
19  "From": "+15551234567",
20  "SequenceNumber": 4,
21  "Timestamp": "Thu, 04 Apr 2024 18:32:15 +0000",
22  "To": "+15559876543"
23}

Examples

Dialing to a SIP endpoint

1<?xml version="1.0" encoding="UTF-8"?>
2<Response>
3    <Dial>
4        <Sip>sip:alice@example.com</Sip>
5    </Dial>
6</Response>

In this example, in order to connect to alice@example.com we have to nest a <Sip> within a <Dial>.

Dialing to a SIP endpoint with authentication

1<?xml version="1.0" encoding="UTF-8"?>
2<Response>
3    <Dial>
4        <Sip username="admin" password="1234">sip:bob@example.com</Sip>
5    </Dial>
6</Response>

Now, in order to connect to bob@example.com, you have to have the proper authentication credentials.

Passing custom headers

Pass custom headers to the SIP endpoint.

1<?xml version="1.0" encoding="UTF-8"?>
2<Response>
3    <Dial>
4        <Sip>sip:charlie@example.com?customheader=foo&amp;othercustomheader=bar</Sip>
5    </Dial>
6</Response>

Dialing a SIP endpoint with Dial attributes

The Sip Noun supports of <Dial> attributes and can be used together.

1<?xml version="1.0" encoding="UTF-8"?>
2<Response>
3    <Dial
4     record="record-from-answer"
5     callerId="alice"
6     method="GET"
7     action="https://www.example.com/after_dial">
8        <Sip
9          url="https://www.example.com/whisper_audio"
10          statusCallbackEvent='ringing answered'
11          statusCallback='https://www.example.com/dial_events'>
12            sip:dan@example.com?customheader=foo
13        </Sip>
14    </Dial>
15</Response>

Notes on usage

  • SIP INVITE message includes CallSid, AccountSid, and the API version; can also pass custom SIP headers in the INVITE message.
  • You can have up to 10 <Sip>s within a <Dial>.
  • You cannot add other nouns in a <Dial> that contains a <Sip>.