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 .

Noun Attributes

<Sip> noun supports the following attributes that modify its behavior:
Attribute Name
Allowed Values
Default Value
name
String
none
url
any url
none
method
GET, POST
POST
statusCallbackEvent
initiated, ringing, answered, completed
none
statusCallback
any url
none
statusCallbackMethod
GET, POST
POST

name

The 'name' attribute allows you to inform the SIP URI who will answer to a video call. This attribute should be used only when <Video> noun is nested, otherwise the SIP URI should be informed as value of the tag <Sip>.
Sip URI (name) without <Video> noun nesting.
1
<Sip>sip:[email protected]:5080</Sip>
Copied!
Sip URI (name) with <Video> noun nesting.
1
<Sip name="sip:[email protected]:5080">
2
<Video enable=”true”></Video>
3
</Sip>
Copied!

url

The 'url' attribute allows you to specify a url for a RCML document that will run on the called party’s end, after she answers, but before the 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 and . The current caller will continue to hear ringing while the RCML document executes on the other end. RCML documents executed in this manner are not allowed to contain the verb. method

method

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

statusCallbackEvent

When dialing out to a SIP URI using <Dial>, an outbound call is initiated. The call transitions from the initiated state to the ringing state when the phone starts ringing. It transitions to the answered state when the call is picked up, and finally to the completed state when the call is over. With statusCallbackEvent, you can subscribe to receive webhooks for the different call progress events: initiated, ringing, answered, or completed for a given call.
The statusCallbackEvent attribute allows you to specify which events calls.teleapi should webhook on. To specify multiple events separate them with a comma: initiated,ringing,answered,completed. If a statusCallback is provided and no status callback events are specified the completed event will be sent by default.
As opposed to creating an outbound call via the API, outbound calls created using <Dial> are initiated right away and never queued. The following shows a timeline of possible call events that can be returned and the different call statuses that a <Dial> leg may experience:
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 sip URIS at once. The first Sip URI to accept the incoming connection is connected to the call and the other connection attempts are canceled.
Event
Description
initiated
The initiated event is fired when calls.teleapi starts dialing the call.
ringing
The ringing event is fired when the call starts ringing.
answered
The answered event is fired when the call is answered.
completed
The completed event is fired when the call is completed regardless of the termination status: busy, canceled, completed, failed, or no-answer. If no statusCallbackEvent is specified, completed will be fired by default.

statusCallback

The statusCallback attribute allows you to specify a URL for calls.teleapi to send webhook requests to on each event specified in the statusCallbackEvent attribute.

statusCallbackMethod

The statusCallbackMethod attribute allows you to specify which HTTP method calls.teleapi should use when requesting the URL in the statusCallback attribute. The default is POST.

Status Callback HTTP Parameters

The parameters calls.teleapi passes to your application in its asynchronous request to the StatusCallback URL include all parameters passed in a synchronous request to retrieve RCML when calls.teleapi receives a call to one of your calls.teleapi numbers. The full list of parameters and descriptions of each are in the RCML Voice Request documentation.
When the call progress events are fired, the Status Callback request also passes these additional parameters:
Parameter
Description
CallSid
A unique identifier for this call, generated by calls.teleapi. You can use the CallSid to modify the child call by POSTing to Calls/{CallSid} with a new RCML URL.
CallStatus
A descriptive status for the call. The value is one of queued, initiated, ringing, in-progress, busy, failed, or no-answer. See the CallStatus section for more details.
CallDuration
The duration in seconds of the just-completed call. Only present in the completed event.
Timestamp
The timestamp when the event was fired, given as UTC in RFC 2822 format.
CallbackSource
A string that describes the source of the webhook. This is provided to help disambiguate why the webhook was made. On Status Callbacks, this value is always call-progress-events.
SequenceNumber
The order in which the events were fired, starting from 0. Although events are fired in order, they are made as separate HTTP requests and there is no guarantee they will arrive in the same order.

Example

1
<Response>
2
<Dial>
3
<Sip>sip:[email protected]:5080</Sip>
4
</Dial>
5
</Response>
Copied!

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

Example

1
<Response>
2
<Dial>
3
<Sip username="alice" password="secret">sip:[email protected]</Sip>
4
</Dial>
5
</Response>
Copied!

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:
1
<?xml version="1.0" encoding="UTF-8"?>
2
<Response>
3
<Dial>
4
<Sip>
5
sip:[email protected]?mycustomheader=tata&myotherheader=toto
6
</Sip>
7
</Dial>
8
</Response>
Copied!

Character Limit

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

Transport

1
<?xml version="1.0" encoding="UTF-8"?>
2
<Response>
3
<Dial>
4
<Sip>
5
sip:[email protected];transport=tcp
6
</Sip>
7
</Dial>
8
</Response>
Copied!
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, calls.teleapi 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
url. 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 calls.teleapi should use when requesting the URL specified in the url attribute. The default is POST.

Call Screening HTTP parameters

When a call is answered, calls.teleapi 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.
1
<?xml version="1.0" encoding="UTF-8"?>
2
<Response>
3
<Dial
4
record="true"
5
timeout="10"
6
hangupOnStar="true"
7
callerId="bob"
8
method="POST"
9
action="/handle_post_dial">
10
<Sip
11
method="POST"
12
url="/handle_screening_on_answer">
13
sip:[email protected]?customheader=foo
14
</Sip>
15
</Dial>
16
</Response>
Copied!
Last modified 1yr ago