<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:[email protected];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 version="1.0" encoding="UTF-8"?>
<Response>
    <Dial>
        <Sip>sip:[email protected]</Sip>
    </Dial>
</Response>
const { RestClient } = require('@signalwire/node')
const response = new RestClient.LaML.VoiceResponse()

dial = response.dial()
dial.sip('sip:[email protected]')
console.log(response.toString())
<?php
  use SignalWire\LaML;
  $response = new LaML;

  $dial = $response->dial();
  $dial->sip('sip:[email protected]');
  echo $response;
?>
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:[email protected]"));
        response.Append(dial);

        Console.WriteLine(response.ToString());
    }
}
from signalwire.voice_response import VoiceResponse, Dial, Sip

response = VoiceResponse()
dial = Dial()
dial.sip('sip:[email protected]')
response.append(dial)

print(response)
require 'signalwire/sdk'

response = Signalwire::Sdk::VoiceResponse.new do |response|
  response.dial do |dial|
    dial.sip('sip:[email protected]')
  end
end

puts response.to_s

Noun Attributes

Attribute
codecs optionalA 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 optionalA 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 optionalThe 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 optionalThe 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 optionalThe URL to make requests to for each statusCallbackEvent event. See below for request parameters.
statusCallbackMethod optionalThe type of HTTP request to use when requesting a statusCallback. Default is POST.
username optionalUsername for SIP authentication
password optionalPassword for SIP authentication

After a Dial attempt is made, SignalWire can make a request to the `` verb's `action` attribute. In addition to the [Standard Request Parameters](ref:voice-xml#request-parameters), the following are parameters passed back to your application when SignalWire makes the request.
Parameter
DialSipCallId stringThe SIP call ID header of the request made to the remote SIP infrastructure.
DialSipResponseCode stringThe SIP response code to the INVITE attempt.
DialSipHeader_ stringThe 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 stringThe SIP call ID header of the request made to the remote SIP infrastructure.
SipHeader stringThe 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 stringThe source of the status callback.
CallDuration integerThe duration, in seconds, of the finished call. Only present on the completed event.
Timestamp stringThe timestamp, in RFC 2822 format, of when the event occurred.

Examples

Dialing to a SIP Endpoint

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Dial>
        <Sip>sip:[email protected]</Sip>
    </Dial>
</Response>
const { RestClient } = require('@signalwire/node')
const response = new RestClient.LaML.VoiceResponse()

dial = response.dial()
dial.sip('sip:[email protected]')
console.log(response.toString())
<?php
  use SignalWire\LaML;
  $response = new LaML;

  $dial = $response->dial();
  $dial->sip('sip:[email protected]');
  echo $response;
?>
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:[email protected]"));
        response.Append(dial);

        Console.WriteLine(response.ToString());
    }
}
from signalwire.voice_response import VoiceResponse, Dial, Sip

response = VoiceResponse()
dial = Dial()
dial.sip('sip:[email protected]')
response.append(dial)

print(response)
require 'signalwire/sdk'

response = Signalwire::Sdk::VoiceResponse.new do |response|
  response.dial do |dial|
    dial.sip('sip:[email protected]')
  end
end

puts response.to_s

In this example, in order to connect to '[email protected]' we have to nest a <Sip> within a <Dial>.

Dialing to a SIP Endpoint With Authentication

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Dial>
        <Sip username="admin" password="1234">sip:[email protected]</Sip>
    </Dial>
</Response>
const { RestClient } = require('@signalwire/node')
const response = new RestClient.LaML.VoiceResponse()

dial = response.dial()
dial.sip({ username: 'admin', password: '1234' }, 'sip:[email protected]')
console.log(response.toString())
<?php
  use SignalWire\LaML;
  $response = new LaML;

  $dial = $response->dial();
  $dial->sip('sip:[email protected]', array( 'username' => 'admin', 'password' => '1234' ));
  echo $response;
?>
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:[email protected]"), 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:[email protected]', 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:[email protected]', username:'admin', password:'1234')
  end
end

puts response.to_s

Now, in order to connect to '[email protected]', you have to have the proper authentication credentials.

Passing Custom Headers

Pass custom headers to the SIP endpoint.

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Dial>
        <Sip>sip:[email protected]?customheader=foo&amp;othercustomheader=bar</Sip>
    </Dial>
</Response>
const { RestClient } = require('@signalwire/node')
const response = new RestClient.LaML.VoiceResponse()

dial = response.dial()
dial.sip('sip:[email protected]?customheader=foo&amp;othercustomheader=bar')
console.log(response.toString())
<?php
  use SignalWire\LaML;
  $response = new LaML;

  $dial = $response->dial();
  $dial->sip('sip:[email protected]?customheader=foo&amp;othercustomheader=bar');
  echo $response;
?>
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:[email protected]?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:[email protected]?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:[email protected]?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 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:[email protected]?customheader=foo
        </Sip>
    </Dial>
</Response>
const { RestClient } = require('@signalwire/node')
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:[email protected]?customheader=foo')
console.log(response.toString())
<?php
  use SignalWire\LaML;
  $response = new LaML;

  $dial = $response->dial( array( 'record' => 'record-from-answer', 'callerId' => 'alice', 'method' => 'GET', 'action' => 'https://www.example.com/after_dial' ));
  $dial->sip('sip:[email protected]?customheader=foo', array( 'url' => 'https://www.example.com/whisper_audio', 'statusCallbackEvent' => 'ringing answered', 'statusCallback' => 'https://www.example.com/dial_events' ));
  echo $response;
?>
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:[email protected]?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:[email protected]?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:[email protected]?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>.