Dialplan Verbs

SAY verb

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 verb

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"
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.
repeat	Defines the number of repetitions.
fileURL*	The url of the prerecorded file to Play (in .WAV format).

DIAL verb (only 1 DIAL Verb per Dialplan).

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 defined, in the DIAL verb, recipient.

{
  "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]:55080)
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 "record" object you are able to record a call between the caller and the callee 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 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 verb

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 verb

With the COLLECT verb, you can interact with your audience, by 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 define.
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, by returning and executing a new dialplan.

{
    "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 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.

*The DTMF tones during a DIAL verb are not collected.