Dial

Definition

The Dial verb connects the calling party with the dialed party. Once the call is set up, the participants can start talking.

When the call is ended successfully, or the dialed number is not reached, or the call is terminated, CarrierX will make a POST or GET request to the action URL.

warning

The verbs listed after the Dial verb, which has an action URL specified, will not be executed.

If no action URL is set, the call flow will move to the next verbs in the FlexML instructions.

You can also place a phone number inside the Number noun. This is done to allow specifying the additional parameters (e.g., sendDigits) when dialing a phone number. Refer to the this section for more information about the Number noun.

Additionally, you can use the Number noun for the simultaneous ring to several numbers feature.

When to Use

Use Dial when you want to connect the current caller to another phone number, SIP endpoint, or multiple phone numbers or SIP endpoints at once. Dial controls what happens if the call is answered, not answered, or terminated.

info

Dial can record a call, stream a call, or do both at the same time.

• To record a call, use the record attributes.
• To stream a call, use the stream attributes.

tip

• Dial works with regular phone numbers, SIP URIs, or a mix of both using the Number noun.
• Always handle your action URL to manage what happens next when a Dial ends, so you can gracefully redirect, play a message, or log the result.

Supported Attributes

These attributes can be used to modify the Dial verb. They are inserted as name-value pairs in the start-tag.

Attribute	Data Type	Description
action	string	The link to another set of FlexML instructions. A request will be made to this URL when the call is ended or if the dialed party is not available. If no action URL is set, the rest of the verbs in the current FlexML instructions will be executed. The URL can be absolute or relative.
callerId	string	The phone number that will appear on the caller ID of the called party. This phone number must be on the account, or have custom permission set up.
callerName	string	The calling party CNAME that is used in the from field.
confirmKey	string	The key that the called party must press to start the phone talk. Values accepted in this field are: 1, 2, 3, 4, 5, 6, 7, 8, 9, 0, #, and *.
confirmSound	string	The URL of the audio that contains the instructions for the key from the confirmKey field. It informs the called party which key they must press to start the talk.
containerSid	string	The secure ID of the container to which the recording will be written.
hangupOnStar	boolean	If this value is set to true, pressing * will hang up the call with the dialed number, and continue with the next FlexML instructions. Until * is pressed, the rest of the FlexML instructions will not be executed.
method	string	The type of request made to the action URL. Values accepted in this field are POST or GET. The default value is POST.
record	string	Determines whether or not to record the outbound call until hangup. Values accepted in this field are: do-not-record for the call not to be recorded (the same effect as when the record attribute is not specified). record-from-answer for recording to start from the moment the call is answered. record-from-ringing for the recording to start from the moment the ringing begins. The default value is do-not-record.
recordDirection	string	The direction of the call that will be recorded. Values accepted in this field are: any to allow recording of both called and calling parties. in to allow recording of the calling party only. out to allow recording of the called party only. The default value is any.
recordingStatusCallback	string	A callback is sent to this URL after the recording has ended.
recordingStatusCallbackEvent	string	The comma-separated list of events to be notified about. Options are completed, to indicate that the recording is successful, and failed, to indicate that the recording has failed. The default value is "completed,failed".
recordingStatusCallbackMethod	string	The method, either POST or GET that the callback to recordingStatusCallback is sent. The default value is POST.
ringing	string	Phone ringing management. Values accepted in this field are: false to return the 200 OK success response and send the data to the calling party from the dialed party; no music or ringing is generated. music to playback the default music. true to return the 180 Ringing informational response, the ringing sound must be generated by the party that receives this response.
stream	string	Determines whether or not to stream the outbound call audio. Values accepted in this field are: do-not-stream for the call not to be streamed (the same effect as when the stream attribute is not specified). stream-from-answer for streaming to start from the moment the call is answered. stream-from-ringing for streaming to start from the moment the ringing begins. The default value is do-not-stream.
streamMaxLength	integer	The maximum length of the stream, in seconds.
streamName	string	A unique identifier for the stream.
streamTimestampStart	string	Defines how the timestamp attribute of the streamed media is represented. Values accepted in this field are: relative (default) absolute
streamTrack	string	The audio track(s) to stream. Values accepted in this field are: inbound outbound both mixed
streamUrl	string	The relative or absolute URL of the WebSocket server. Both ws and wss protocols are supported.
timeLimit	integer	The maximum number of seconds that the call will last. The default value is 0, meaning that the call time is not limited.
timeout	integer	The number of seconds to wait for the destination number to answer. After the call times out, a request is made to the action URL. The default value is 30.
trim	string	Determines whether or not silence is removed from the beginning or ending of a recording. To trim the silence in the recording, set this field to trim-silence. The default value is do-not-trim.

note

• recordDirection, recordingStatusCallback, recordingStatusCallbackEvent, recordingStatusCallbackMethod, and trim are applicable only when record is set to record-from-answer or record-from-ringing.

• streamTrack, streamMaxLength, streamName, streamTimestampStart, and streamUrl are applicable only when stream is set to stream-from-answer or stream-from-ringing.

Example

To simply dial the number, include it directly inside the Dial verb without using the Number noun. In this case, FlexML instructions cannot include any additional parameters for the dialed number. In this example, the phone number inside the Dial tags will be dialed. The call total time will be limited to 15 seconds. The called party will be able to hang up by pressing the * key. If an action URL is added to the Dial verb as an attribute, a request will be made to that URL if the phone number cannot be reached, or when the call ends.

<Response>
  <Dial timeLimit="15" hangupOnStar="true">15162065340</Dial>
</Response>

Example with Streaming

In this example, the Dial verb streams the call audio to a WebSocket server after the call is answered.

<Response>
  <Dial stream="stream-from-answer" streamUrl="wss://example.com/stream" streamName="myStream" streamTrack="both"></Dial>
</Response>

Number Noun

The Number noun can be nested inside the Dial verb. It contains the DID number to be dialed. It supports the following attributes:

Attribute	Data Type	Description
sendDigits	string	The DTMF tones that will be played when the call is answered. This is especially useful when dialing a phone number with an extension. Values accepted in this field are: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, #, *, ,, and the combinations of these characters. Each comma character defines a 0.5-second delay.

CarrierX allows dialing to several numbers at once using the Number noun. Refer to the Simultaneous Ring to Several Numbers section of the Dial verb for more information about this.

Query Arguments

In this example, two X- headers will be sent when dialing the phone number specified in the Number noun nested inside the Dial verb.

<Response>
  <Dial>
    <Number>15162065340?X-CustomHeader1=ABC&amp;X-CustomHeader2=DEF</Number>
  </Dial>
</Response>

The additional query arguments can be used to send custom headers inside the Number noun. Use the ? character after the phone number to add these headers. Several headers are joined with the XML-encoded & character.

info

Only X- headers are accepted as query arguments, any other headers or strings will be filtered out and not sent.

note

If you choose to send custom headers when dialing a phone number, you will need to additionally set the relay_sip_headers parameter of the Trunk object associated with your FlexML endpoint to successfully pass these headers to the destination.

Example

In this example, once the call is answered, the wait of two seconds will be performed (the total length of four , characters, each equal to 0.5-second delay), after that the 1928 DTMF tones will be played to the dialed number.

<Response>
  <Dial>
    <Number sendDigits=",,,,1928">15162065340</Number>
  </Dial>
</Response>

Simultaneous Ring to Several Numbers

CarrierX supports dialing to several numbers at once. You need to specify the numbers in the Number noun tags inside the Dial verb. The first person to answer will be connected to the calling party. The calls to the other numbers will be hung up.

note

CarrierX supports up to 10 concurrent rings using the FlexML Dial verb.

tip

You can see an example of the code that uses the simultaneous rings feature in our sample application, which is a part of the No-code CarrierX Apps collection.

Example 1

In this example, the phone numbers in the Number tags will be dialed all at the same time. The first person to answer is connected to the calling party.

<Response>
  <Dial>
    <Number>12345645585</Number>
    <Number>96846465465</Number>
    <Number>98133217461</Number>
  </Dial>
</Response>

Example 2

In this example, multiple phone numbers inside the Number tags will be dialed simultaneously. The first person to answer will be connected to the calling party, and they must press 1 (as instructed by the audio at confirmSound) to start the conversation. The call will be recorded starting from when it is answered, and the total call time is limited to 30 seconds.

<Response>
  <Dial confirmKey="1" confirmSound="https://example.com/instructions.mp3" record="record-from-answer" timeLimit="30">
    <Number>1234567890</Number>
    <Number>0987654321</Number>
  </Dial>
</Response>

Common Pitfalls

• If action is set, any verbs after Dial won't run until the action URL is requested.
• To pass SIP headers or custom headers, use ?X-Header=Value in the Number noun.
• Remember to set relay_sip_headers in your Trunk if you pass custom SIP headers.

Nesting Rules

• You can nest the Number noun within the Dial verb.
• You cannot nest the Dial verb within other FlexML verbs.

Learn more

• Connect — Start a bidirectional stream with a WebSocket.
• Record — Record the entire call or only part of it.
• Stream — Stream audio to a WebSocket.
• Start / Stop — Control unidirectional streams.