Dial plan

Dial plan description

The dial plan contains the handling of the voice call.

You can create custom dial plans that fit your needs. You are able to use a combination of prerecorded audio files, text to speech, connection to another recipient. It is possible to change a dial plan dynamically through the use of DTMF tones.

A dial plan can be set:

  • In the body of the Conversation request ("dialPlan" parameter).
  • In an external URL that you define in the body of the conversation request ("dialPlanUrl" parameter - in Numbers).
  • In the URL that accepts the collected tones ("eventUrl" parameter in the "COLLECT" verb)

In order to handle the Voice inbound calls, you have to set a URL (when you rent or update a Number) that returns a valid dial plan ("voiceInboundStrategy.dialplanUrl" parameter).

A valid dial plan is constructed by the "verbs" array of verb objects, in JSON format (you can check the example below).

The supported action verbs of a dial plan are the following:

  • SAY (text to speech)
  • PLAY (prerecorded audio file)
  • DIAL (connection to another recipient) *only 1 DIAL Verb per Dialplan
  • PAUSE (temporarily stop the dial plan execution)
  • COLLECT (DTMF tones gathering)

The "verbs" array cannot be empty and it contains the verbs that are going to be executed. It may contain many SAY, PLAY and PAUSE verbs, but only one DIAL. If COLLECT verb is included anywhere inside a dial plan, then the DTMF tones are collected.

An example of a valid dial plan with all the supported verbs is the following:

      "type" : "SAY",
      "message" : {
        "language" : "en-US",
        "gender" : "male",
        "text" : "Hello. This is an example of a valid dialplan"
      "type" : "PLAY",
      "fileURL" : "http://an-example-wav-file.wav"
      "type": "DIAL",
      "to": {

What’s Next