Reference Turnkey Applications Tutorials Visual Designer
Reference Turnkey Applications Tutorials Visual Designer
    • REST API
      • Overview
      • API Endpoint
      • Authentication
      • Requests
      • Responses
      • Paging
      • Reason Codes Dictionary
    • Management APIs
      • Accounts
      • Identity Access Management BETA
        • Identity Access Management Overview
        • Identity Access Management API
          • User Management
            • Create a User
            • Update a User
            • Retrieve a User
            • Delete a User
          • API Keys Management
            • Create an API Key
            • Update an API Key
            • Retrieve an API Key
            • Delete an API Key
      • Applications
      • Clients
        • Create a Client
        • Delete a Client
        • Change Client’s Password
        • Get a List of Available Clients
      • Incoming Phone Numbers
        • IncomingPhoneNumber Instance Resource
        • IncomingPhoneNumbers List Resource
        • Local IncomingPhoneNumber Factory Resource
        • Toll-Free IncomingPhoneNumber Factory Resource
        • Mobile IncomingPhoneNumber Factory Resource
        • Attach a phone number to an application
        • Enable Incoming MMS for an Application
        • Delete a phone number
        • List of Phone Numbers
        • Incoming Phone Number Regex Support
      • Notifications
      • Usage Records
      • Trace Records
    • Voice
      • Calls
        • Call List Resource URI
        • Making a Call
        • Modifying Live Calls
        • Examples
        • List Filter
        • Paging Information
      • Conference Management
        • Supported Operations
        • Conference List Resource URI
      • Conference Participants Management
        • Participants List Resource URI
      • Gather DTMF
      • Gather Speech
      • Say
      • Play
      • Hold
      • Recordings
      • Refers
        • Resource Properties
        • Supported Operations
        • Paging Information
      • Resume
      • SIP Refer Support
    • Messages API - BETA
      • Overview
      • Channel Identities
      • Send Message
      • Status Callback Parameters
      • Status Callback Events
      • Receive Message
        • Incoming Message Request Parameters
      • Get Message List
      • Get Single Message
      • Message Attributes
      • Status Description
    • SMS
      • Messages
        • Send SMS
        • Get SMS List
        • Get single SMS Information
        • SMS Attributes
      • Error Codes
    • Email
    • RCML
      • Overview
        • Interacting with Your Application
        • RCML Verbs
      • Dial
        • Client
        • Conference
        • Number
        • SIP
      • Email
      • Gather
      • Say
      • Play
      • SMS
      • Message - Beta
      • Hold
      • Resume
      • Hangup
      • Pause
      • Redirect
      • Record
      • Reject
      • Refer
    • Visual Designer API
      • List Application Templates
      • :List a Specific Application Template
      • Create a Visual Designer Application
      • Get Application Details
      • Save Application Changes
      • Create Application Parameters
      • List Application Parameters
      • Delete Application Parameters
      • Upload Application Media Files
      • List Application Media Files
      • Play Application Media Files
      • Delete Application Media Files
      • Get Application Logs
      • Delete Application Logs
      • Get Application Settings
      • Modify Application Settings
      • Rename an Application
      • Delete an Application
      • Get Visual Designer Configuration
    • Turnkey Apps APIs
      • Smart 2FA
        • Sending One-Time Passwords
        • Verifying One-Time Passwords
        • Cancel One-Time Passwords
        • Session Detail Record (SDR)
        • Get list of One-Time Passwords
        • Get a Single One-Time Password
        • Usage Record One-Time Passwords
        • Common Response Error Code
        • Limit
          • Create Limit
          • Update Limit
          • Delete Limit
          • Get List of Limits
      • Call Queuing
      • Auto Attendant
        • Users
        • Announcement
        • Auto Attendant System
        • Menu
        • Schedule
        • Phone Number
        • Usage Records
        • Third Party Integration
      • Number Masking
        • Application
        • Mask Number Pool
        • Context
        • Participants
        • Interactions
        • Usage Records
      • Task Router
docs 1.0
  • docs
    • 1.0
  • docs
  • Enterprise:RCML
  • Enterprise:Dial

Dial

Dial

The <Dial> verb connects the current caller to another phone. If the called party picks up, the two parties are connected and can communicate until one hangs up. If the called party does not pick up, if a busy signal is received, or if the number doesn’t exist, the dial verb will finish.

Dial Attributes

Name Allowed Values Default Value

action

relative or absolute URL

no default value for <Dial>

method

GET, POST

POST

timeout

positive integer in seconds

30 seconds

timeLimit

positive integer (seconds)

14400 seconds (4 hours)

callerId

a valid phone number, or client identifier if you are dialing a <Client>.

Caller’s callerId

record

true, false

false

dialMusic

relative or absolute URL. The value 'disabled' will prevent any music.

no default

  • action. The 'action' attribute takes a URL as an argument. When the dialed call ends, CPaaS will make a GET or POST request to this URL including the parameters below. If you provide an 'action' URL, CPaaS will continue the current call after the dialed party has hung up, using the RCML received in your response to the 'action' URL request. Any RCML verbs occuring after a <Dial> which specifies an 'action' attribute are unreachable. If no 'action' is provided, <Dial> will finish and CPaaS will move on to the next RCML verb in the document. If there is no next verb, CPaaS will end the phone call.

Dial Action Request HTTP Parameters

The CPaaS parameters passed to your application in its asynchronous request to the Dial action URL. The full list of Request Parameters can be found in the RCML Voice Request documentation.

The Status Callback request also passes these additional parameters:

Parameter Description

DialCallStatus

The outcome of the <Dial> attempt. See the DialCallStatus section below for details.

DialCallSid

The call sid of the new call leg. This parameter is not sent after dialing a conference.

DialCallDuration

The duration in seconds of the dialed call. This parameter is not sent after dialing a conference.

DialRingDuration

The duration in seconds of the dialed call ringing time. This parameter is not sent after dialing a conference.

RecordingUrl

The URL of the recorded audio. This parameter is only sent if record="true" is set on the Dial verb, and does not include recordings from the Record verb or Record=True on REST API calls. The recording file may not yet be accessible when the action callback is sent.

ReferTarget

Refer-To parameter of REFER if a call is created after a call transfer

Transferor

Contact parameter of REFER if a call is created after a call transfer

Transferee

To parameter of REFER if a call is created after a call transfer

FailureReason (optional)

Provides more information about failure reason where Dial Number/Sip/Client. This parameter is optional and will only be present when call status is Failed.

SipHeader_*

A set of optional field with custom SIP headers that are present in INVITE SIP request or in a last SIP response

DialSipCallId

Optional parameter: sipCallId from a response in a last SIP response if a last SIP response code >=400

DialSipResponseCode

Optional parameter: statusCode in a last SIP response if a last SIP response code >=400

DialSipHeader_*

A set of optional field with custom SIP headers that are present in a last SIP response

DialCallStatus Values

Parameter Description

completed

The called party answered the call and was connected to the caller.

busy

CPaaS received a busy signal when trying to connect to the called party.

no-answer

The called party did not pick up before the timeout period passed.

failed

CPaaS was unable to route to the given phone number. This is frequently caused by dialing a properly formated but non-existent phone number.

canceled

The call was canceled via the REST API before it was answered.

  • method. The 'method' attribute takes the value 'GET' or 'POST'. This tells CPaaS whether to request the 'action' URL via HTTP GET or POST. This attribute is modeled after the HTML form 'method' attribute.

  • timeout. The 'timeout' attribute sets the limit in seconds that <Dial> waits for the called party to answer the call.

  • timelimit. The 'timeLimit' attribute sets the maximum duration of the <Dial> in seconds.

  • callerId. The 'callerId' attribute lets you specify the caller ID that will appear to the called party when CPaaS calls. By default, when you put a <Dial> in your RCML response to CPaaS's inbound call request, the caller ID that the dialed party sees is the inbound caller’s caller ID. If you are dialing to a <Client>, you can set a client identifier as the callerId attribute. For instance, if you’ve set up a client for incoming calls and you are dialing to it, you could set the callerId attribute to client:thomas.

  • record. The 'record' attribute lets you specify whether the call will be recorded or not. By default, the call is not recorded. If you set the attribute to 'true' CPaaS will start recording when the two calls are bridged

  • dialMusic. The 'dialMusic' attribute lets you specify a custom RingBack tone to be played. The attribute value is a valid URL pointing to WAV file. Optionally the special value "Disabled" will prevent playing any sound.

The current release of CPaaS doesn’t support recording for Dial Conference. This feature will be available in the next release
  • Nesting. You can nest the following nouns within <Dial>: <Number>, <Client>, <Conference>

Examples

For examples of how to use the <Dial> verb see below.

Dial a phone number.

<Response>
    <Dial>1-444-555-6666</Dial>
</Response>

Dial a phone number and record the call.

<Response>
    <Dial record="true">1-444-555-6666</Dial>
</Response>

Dial a phone number with set callerdId and record the call.

<Response>
    <Dial callerId="15556667777" record="true">1-444-555-6666</Dial>
</Response>

Sequential Dial

You may want dial phone numbers, clients, SIP URIs and conference rooms in a sequence. In that case, you can specify a timeout limit during which a single dial will last. Optionally you can set a <Pause> between the dials.

In the example below, every dial lasts for 30 seconds. In addition, there is a pause of 4 seconds in between. If the first dialed party does not pick up, the sequence continues to the second one and so on, till one of the parties answers the call.

<Response>
  <Say>This is a sequential Dial example.</Say>
  <Dial timeout="30">
    <Number>12223334444</Number>
  </Dial>
  <Pause length="4"/>
  <Dial timeout="30">
    <Number>15556667777</Number>
  </Dial>
  <Pause length="4"/>
  <Dial>
    <Client>jane</Client>
  </Dial>
</Response>

Dial Call Flows

The following flow diagrams illustrate the possible call flow scenarios for the RCML <Dial> verb.

Single Destination Dial

The diagram below outlines dialing to a single destination. There you can see how all the possible states (answered, failed, busy etc.) are handled.

Answer Delay Dial forking Call Flow

Dial Forking

The following diagram illustrates a dial forking scenario, where multiple clients are dialed. When one of the clients answers, the call is cancelled for the rest of the dialed clients.

Answer Delay Call Flow
Platform

Programmable Voice

Programmable SMS

Turnkey Applications

Smart 2FA

Call Queue

Auto Attendant

Number Masking

Task Router

Campaign Manager

Learn

Terms And Conditions

About

ABOUT

CONTACT US

© 2020, All rights reserved.