<Sip> noun

<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:

XML
JavaScript
C#
Python
Ruby

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Dial>
        <Sip>sip:alice@example.com</Sip>
    </Dial>
</Response>

const { RestClient } = require("@signalwire/compatibility-api");
const response = new RestClient.LaML.VoiceResponse();

dial = response.dial();
dial.sip("sip:alice@example.com");
console.log(response.toString());

using System;
using Twilio.TwiML;
using Twilio.TwiML.Voice;

class Example
{
    static void Main()
    {
        var response = new VoiceResponse();
        var dial = new Dial();
        dial.Sip(new Uri("sip:alice@example.com"));
        response.Append(dial);

        Console.WriteLine(response.ToString());
    }
}

from signalwire.voice_response import VoiceResponse, Dial, Sip

response = VoiceResponse()
dial = Dial()
dial.sip('sip:alice@example.com')
response.append(dial)

print(response)

require 'signalwire/sdk'

response = Signalwire::Sdk::VoiceResponse.new do |response|
  response.dial do |dial|
    dial.sip('sip:alice@example.com')
  end
end

puts response.to_s

Noun Attributes

Attribute
`codecs` optional	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. Default value is `PCMU,PCMA`
`url` optional	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.
`method` optional	The `method` attribute specifies whether the request to action is a `GET` or a `POST`. Valid values are `GET` or `POST`. Default value is `POST`.
`statusCallbackEvent` optional	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.
`statusCallback` optional	The URL to make requests to for each `statusCallbackEvent` event. See below for request parameters.
`statusCallbackMethod` optional	The type of HTTP request to use when requesting a `statusCallback`. Default is `POST`.
`username` optional	Username for SIP authentication
`password` optional	Password for SIP authentication
`sessionTimeout` optional	Non-negative value, in seconds, to use for the SIP `Session-Expires` header. If 0 or unset, SignalWire will pick the default (typically 600).

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.

Parameter
`DialSipCallId` string	The SIP call ID header of the request made to the remote SIP infrastructure.
`DialSipResponseCode` string	The SIP response code to the INVITE attempt.
`DialSipHeader_` string	The name or value of any X-headers returned in the 200 response to the SIP INVITE request.

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.

Parameter
`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:

Value
`initiated`	Dialing of a call has begun.
`ringing`	The call has begun ringing.
`answered`	The call has been answered.
`completed`	The 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

The statusCallback request contains the Standard Request Parameters as well as:

Parameter
`CallbackSource` string	The source of the status callback.
`CallDuration` integer	The duration, in seconds, of the finished call. Only present on the `completed` event.
`Timestamp` string	The timestamp, in RFC 2822 format, of when the event occurred.

Examples

Dialing to a SIP Endpoint

XML
JavaScript
C#
Python
Ruby

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Dial>
        <Sip>sip:alice@example.com</Sip>
    </Dial>
</Response>

const { RestClient } = require("@signalwire/compatibility-api");
const response = new RestClient.LaML.VoiceResponse();

dial = response.dial();
dial.sip("sip:alice@example.com");
console.log(response.toString());

using System;
using Twilio.TwiML;
using Twilio.TwiML.Voice;

class Example
{
    static void Main()
    {
        var response = new VoiceResponse();
        var dial = new Dial();
        dial.Sip(new Uri("sip:alice@example.com"));
        response.Append(dial);

        Console.WriteLine(response.ToString());
    }
}

from signalwire.voice_response import VoiceResponse, Dial, Sip

response = VoiceResponse()
dial = Dial()
dial.sip('sip:alice@example.com')
response.append(dial)

print(response)

require 'signalwire/sdk'

response = Signalwire::Sdk::VoiceResponse.new do |response|
  response.dial do |dial|
    dial.sip('sip:alice@example.com')
  end
end

puts response.to_s

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

XML
JavaScript
C#
Python
Ruby

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

const { RestClient } = require("@signalwire/compatibility-api");
const response = new RestClient.LaML.VoiceResponse();

dial = response.dial();
dial.sip({ username: "admin", password: "1234" }, "sip:bob@example.com");
console.log(response.toString());

using System;
using Twilio.TwiML;
using Twilio.TwiML.Voice;

class Example
{
    static void Main()
    {
        var response = new VoiceResponse();
        var dial = new Dial();
        dial.Sip(new Uri("sip:bob@example.com"), username: "admin",
            password: "1234");
        response.Append(dial);

        Console.WriteLine(response.ToString());
    }
}

from signalwire.voice_response import VoiceResponse, Dial, Sip

response = VoiceResponse()
dial = Dial()
dial.sip('sip:bob@example.com', username='admin', password='1234')
response.append(dial)

print(response)

require 'signalwire/sdk'

response = Signalwire::Sdk::VoiceResponse.new do |response|
  response.dial do |dial|
    dial.sip('sip:bob@example.com', username:'admin', password:'1234')
  end
end

puts response.to_s

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.

XML
JavaScript
C#
Python
Ruby

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

const { RestClient } = require("@signalwire/compatibility-api");
const response = new RestClient.LaML.VoiceResponse();

dial = response.dial();
dial.sip("sip:charlie@example.com?customheader=foo&amp;othercustomheader=bar");
console.log(response.toString());

using System;
using Twilio.TwiML;
using Twilio.TwiML.Voice;

class Example
{
    static void Main()
    {
        var response = new VoiceResponse();
        var dial = new Dial();
        dial
            .Sip(new Uri("sip:charlie@example.com?customheader=foo&amp;othercustomheader=bar"));
        response.Append(dial);

        Console.WriteLine(response.ToString());
    }
}

from signalwire.voice_response import VoiceResponse, Dial, Sip

response = VoiceResponse()
dial = Dial()
dial.sip('sip:charlie@example.com?customheader=foo&amp;othercustomheader=bar')
response.append(dial)

print(response)

require 'signalwire/sdk'

response = Signalwire::Sdk::VoiceResponse.new do |response|
  response.dial do |dial|
    dial.sip('sip:charlie@example.com?customheader=foo&amp;othercustomheader=bar')
  end
end

puts response.to_s

Dialing a SIP Endpoint with Dial attributes

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

XML
JavaScript
C#
Python
Ruby

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Dial
     record="record-from-answer"
     callerId="alice"
     method="GET"
     action="https://www.example.com/after_dial">
        <Sip
          url="https://www.example.com/whisper_audio"
          statusCallbackEvent='ringing answered'
          statusCallback='https://www.example.com/dial_events'>
            sip:dan@example.com?customheader=foo
        </Sip>
    </Dial>
</Response>

const { RestClient } = require("@signalwire/compatibility-api");
const response = new RestClient.LaML.VoiceResponse();

dial = response.dial({
  record: "record-from-answer",
  callerId: "alice",
  method: "GET",
  action: "https://www.example.com/after_dial",
});
dial.sip(
  {
    url: "https://www.example.com/whisper_audio",
    statusCallbackEvent: "ringing answered",
    statusCallback: "https://www.example.com/dial_events",
  },
  "sip:dan@example.com?customheader=foo"
);
console.log(response.toString());

using System;
using Twilio.TwiML;
using Twilio.TwiML.Voice;


class Example
{
    static void Main()
    {
        var response = new VoiceResponse();
        var dial = new Dial(record: Dial.RecordEnum.RecordFromAnswer,
            callerId: "alice", method: Twilio
            .Http.HttpMethod.Get, action: new Uri("https://www.example.com/after_dial"));
        dial.Sip(new Uri("sip:dan@example.com?customheader=foo"),
            statusCallbackEvent: new []{Sip.EventEnum.Ringing, Sip.EventEnum.Answered}.ToList(),
            statusCallback: new Uri("https://www.example.com/dial_events"),
            url: new Uri("https://www.example.com/whisper_audio"));
        response.Append(dial);

        Console.WriteLine(response.ToString());
    }
}

from signalwire.voice_response import VoiceResponse, Dial, Sip

response = VoiceResponse()
dial = Dial(record='record-from-answer', caller_id='alice', method='GET', action='https://www.example.com/after_dial')
dial.sip('sip:dan@example.com?customheader=foo', url='https://www.example.com/whisper_audio', status_callback_event='ringing answered', status_callback='https://www.example.com/dial_events')
response.append(dial)

print(response)

require 'signalwire/sdk'

response = Signalwire::Sdk::VoiceResponse.new do |response|
  response.dial(record:'record-from-answer', caller_id:'alice', method:'GET', action:'https://www.example.com/after_dial') do |dial|
    dial.sip('sip:dan@example.com?customheader=foo', url:'https://www.example.com/whisper_audio', status_callback_event:'ringing answered', status_callback:'https://www.example.com/dial_events')
  end
end

puts response.to_s

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>.

Noun Attributes​

Request parameters for sip_url​

Status values for statusCallbackEvent​

Request parameters for the statusCallback URL​

Examples​

Dialing to a SIP Endpoint​

Dialing to a SIP Endpoint With Authentication​

Passing Custom Headers​

Dialing a SIP Endpoint with Dial attributes​

Notes on Usage​