Dialplan Verbs

Dialplan verbs

SAY

With SAY verb, you are able to convert your desired text (Text to Speech) into a voice message, in a variety of languages.

{
  "type":"SAY",
  "message":{
    "text": string,
    "gender":string,
    "language":string
  },
  "bargeIn":boolean,
  "repeat":int
}

Key

Description

type*

"SAY"

repeat

Defines the number of repetitions.

bargeIn

If it is true then the first DTMF tone will interrupt the current execution. All the collected tones of the call, including the tone that interrupted execution, are sent to the COLLECT eventUrl.
Default value: false.

message*

message.text*

The text of the voice message.

message.gender

The gender of the voice.
VALUES: "male", "female"

message.language*

The language of the voice message.
VALUES: "en-US", "de-DE", "fr-FR", "it-IT", "pt-BR", "es-ES", "es-LA", "en-GB", "el-GR", "bg-BG", "pl-PL", "hu-HU", "sv-SE", "ru-RU"

Barge In

The "bargeIn" parameter is useful in implementing cloud IVR solutions.
You can use "bargeIn" parameter to interupt the active PLAY or SAY verb execution and send the collected DTMF tones to the specified eventUrl.

PLAY

When a PLAY verb is present in a dialplan, your defined audio file (in .wav format) will be played.

{
  "type": "PLAY",
  "fileURL":string,
  "repeat": int,
  "bargeIn": boolean
}

Key

Description

type*

"PLAY"

repeat

Defines the number of repetitions.

bargeIn

If it is true then the first DTMF tone will interrupt the current execution. All the collected tones of the call, including the tone that interrupted execution, are sent to the COLLECT eventUrl.
Default value: false.

fileURL*

The URL of the pre-recorded file to Play (in .WAV format).

DIAL

With DIAL verb, you can connect another recipient to the call. The recipient of the conversation (in case of outbound conversation) or the caller of the conversation (in case of inbound) will be connected to the recipient defined in the DIAL verb. Only one dial verb can be used inside a Dialplan.

{
  "type": "DIAL",
  "from":string,
  "to": object,
  "hangupDelay": int,
  "maxDuration":int,
  "callback": object,
  "record": boolean,
  "recordingFormat": string,
  "recordingCallbackUrl": string,
  "machineDetection":object
}

Key

Description

type*

"DIAL"

from*

The sender Id for this call.

to*

The recipient of this call.

to.phone

A valid phone number (mobile or landline)

to.sip

A valid SIP URI.
(ex: [email protected]test.com:55080)

to.viber

A valid phone number with Viber App installed (e.g. 306971234567)

hangupDelay

The time in seconds to wait for the second call of the bridge to be answered.
The default value is to wait for the network to terminate the call in case the call is not answered.

maxDuration

Call time length after bridge.

callback

Defines the notification callback information for this call. Check here for more information.

callback.url

The URL that Routee will POST to the callback information.

callback.strategy

Defines when the URL will be called.
Two possible values: on every status change (OnChange) or when a final status arrives (OnCompletion).

record

If the value is true, the conversation will be recorded.

recordingFormat

The format of the recorded file (WAV or MP3).
Default value is MP3

recordingCallbackUrl

The URL that Routee will POST to the information about the recorded file.

machineDetection

It is used to detect if the call is answered by human or machine and define the desired actions (in case of machine).

machineDetection.strategy

The strategy to follow when a machine has been detected.
Possible values: "Hangup" (terminate the call) or "Continue" (give another dialplan to execute)

machineDetection.eventUrl

The URL that Routee will POST to when a machine is detected (only for "Continue" strategy). A valid dialplan is expected as response.

Recording a call

With the "record" object you are able to record a call between the caller and the caller leg and choose between .mp3 or .wav audio format.
You are able to retrieve the recorded file from the provided "recordingCallbackUrl" parameter or from the Conversation Tracking endpoints Retrieve Conversation Tracking

Handle the ringing and call duration with hangupDelay & maxDuration

With the "hangupDelay" parameter you can specify the max time a call will stay in ringing mode (until the recipient answers the call) or until the carrier terminates the call.
With the "maxDuration" parameter you can specify the maximum duration of the actual call.

How Machine Detection Works

With Machine Detection you are able to recognize whether a Human or a Machine (eg Voicemail system) has answered the call and set specific actions (Strategy) for those cases.
You can enable machineDetection when executing a Voice Conversation or when using the Dial Verb inside a Dialplan.
In order to enable the Detect Machine, you have to set the machineDetection.strategy parameter to "Hangup" or "Continue".
In case machineDetection.strategy is set to Hangup, the call will be terminated when a Machine answers the call on the other side. A Callback with the detectMachineStatus is sent to the specified machineDetection.eventUrl. A Dialplan is expected as a response from the machineDetection.eventUrl.
In case machineDetection.strategy is set to Continue, the call will not be terminated and will continue instead. A Callback with the detectMachineStatus is sent to the specified machineDetection.eventUrl.

##PAUSE

With PAUSE verb, you are able to temporarily stop the execution of the Dialplan for a specified time.

{
  "type":"PAUSE",
  "duration": int
}

Key

Description

type*

"PAUSE"

duration

The duration of the pause in seconds.
Default value: 1

COLLECT

With the COLLECT verb, you can interact with your audience, with the use of DTMF tones. If a COLLECT verb is placed anywhere inside a Dialplan, all the pressed DTMF tones will be gathered and sent to the URL that you have defined.
You are able to change the Dialplan according to the input of your customers. This is possible by providing a new valid Dialplan at the eventUrl parameter of the COLLECT verb.

{
    "type":"COLLECT",
    "submitOnHash":boolean,
    "eventUrl":string,
    "maxDigits":int
}

KEY

DESCRIPTION

type*

"COLLECT"

eventUrl

Define the URL that the collected tones will be sent to. A new valid Dialplan may be set as a response, in order to change the current one.

maxDigits

Define the maximum collected digits.
Default value: 30.

submitOnHash

If true the collected tones are sent to the eventUrl after pressing #.
Default value: false.