SIP

The <Sip> noun specifies a SIP URI to dial. You can use multiple <Sip> nouns within a <Dial> verb to simultaneously attempt a connection with many user agents at once. The first user agent to accept the incoming connection is connected to the call and the other connection attempts are canceled.

The Dial verb’s Sip noun lets you set up VoIP sessions by using SIP — Session Initiation Protocol. With this feature, you can send a call to any SIP endpoint. Set up your RCML to use the Sip noun within the Dial verb.

Currently, only one Sip noun may be specified per Dial, and the INVITE message may be sent to only one SIP endpoint. Also, you cannot add any other nouns (eg Number, Client) in the same Dial as the SIP. If you want to use another noun, set up a callback on the Dial to use alternate methods .

Examples

For an example of how to use the <Sip> noun see below.

<Response>
    <Dial>
    <Sip>sip:alice@127.0.0.1:5080</Sip>
    </Dial>
</Response>

Authentication

Send username and password attributes for authentication to your SIP infrastructure as attributes on the Sip noun.

Request Parameters

Attribute Name Values

username

Username for SIP authentication.

password

Password for SIP authentication

Authentication Example

<Response>
    <Dial>
    <Sip username="alice" password="secret">sip:alice@example.com</Sip>
    </Dial>
</Response>

Custom headers

Send custom headers by appending them to the SIP URI — just as you’d pass headers in a URI over HTTP. For example:

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

Character Limit

While the SIP URI itself must be under 255 chars, the headers must be under 1024 characters.

Transport

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

Set a parameter on your SIP URI to specify what transport protocol you want to use. Currently, this is limited to TCP and UDP. By default, Restcomm sends your SIP INVITE over UDP. Change this by using the transport parameter:

Attributes

Request Parameters

Attribute Name Allowed Values Default Value

url

call screening url.

none.

method

GET, POST

POST

The url attribute allows you to specify a url for a RCML document that runs on the called party’s end, after they answer, but before the two parties are connected. You can use this RCML to privately Play or Say information to the called party, or provide a chance to decline the phone call using Gather and Hangup. The current caller continues to hear ringing while the RCML document executes on the other end. RCML documents executed in this manner cannot contain the Dial verb.

method

The method attribute allows you to specify which HTTP method Restcomm should use when requesting the URL specified in the url attribute. The default is POST.

Call Screening HTTP parameters

When a call is answered, Restcomm passes the following parameters with its request to your screening URL (in addition to the standard RCML Voice request parameters):

Request Parameters
Attribute Name Values

SipCallId

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

SipHeader

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

Dial Action HTTP parameters

Use the action callback parameters to modify your application based on the results of the SIP dial attempt:

Request Parameters
Attribute Name Values

DialSipCallId

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

DialSipResponseCode

The SIP response code as a result of the INVITE attempt.

DialSipHeader_

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

Dial with Multiple Examples.

A more complex Dial, specifying custom settings as attributes on Dial, including call screening and setting the protocol to TCP.

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Dial
        record="true"
        timeout="10"
        hangupOnStar="true"
        callerId="bob"
        method="POST"
        action="/handle_post_dial">
            <Sip
                method="POST"
                url="/handle_screening_on_answer">
                sip:alice@example.com?customheader=foo
            </Sip>
    </Dial>
</Response>