API Dialplan

Servetel offers Number Masking feature which allows two parties to communicate over an intermediate number, thereby preventing either party from knowing other's phone numbers.

Number Masking can be used by configuring HTTP Method, URL, Request body and a Failover Destination.

Request Variables

When a call is received on our server, the below data is sent to the customerโ€™s API that was specified during API dialplan configuration.

๐Ÿ“˜

Kindly contact Servetel support team to enable API Dialplan on Servetel portal for your account.

Variable Name

Description

Format

Data Type

$uuid

Unique ID of the call

String

$call_to_number

Dialed number

String

$caller_id_number

Caller number

Country code followed by caller number

String

$start_stamp

Start time of the call

YYYY-mm-dd HH:mm:ss
(For example - 2019-12-02 00:00:00)

String

$last_dtmf

DTMF inputs received

Array

$call_flow

Call flow executed

Array of objects

In return, we expect a response in the below format

๐Ÿšง

In case of any kind of failure in receiving an appropriate response from API, the action selected in the Failover destination field will be executed.

[
  {
    "recording": {
      "type": "system",
      "data": 7611,
      "dtmf":{
        "timeout": 6000,
        "maxLength" : 4
      }
    }
  },
  {
    "recording": {
      "type": "url",
      "data": "http://sample_url.com/abcxy/214/032b32463.mp3"
    }
  },
  {
    "transfer": {
      "type": "number",
      "data": 9876543210
    }
  },
  {
    "transfer": {
      "type": "agent",
      "data": "50746745"
    }
  }
]

The response from API will describe the series of actions to be performed, there are two acceptable keys: recording and transfer, containing information about the source of recording and where the call is to be transferred respectively.
In the given sample response, the two recordings will be played sequentially and the call will be transferred to the given number and agent afterwards.

Response Variables

Below are the expected response variables.

Variable Name

Description

Data Type

recording

Required if playing recording is the action to be performed

Object

transfer

Required if call transfer is the action to be performed

Object

api_dialplan

Required if another API Dial plan is to be executed as action

Object

Recording

recording object has below two properties

Variable Name

Description

Data Type

Field Type

type

Source of recording

String

Required

data

Data required for recording to be played (example: unique ID of recording, url of recording)

String

Required

dtmf

If a DTMF is needed over recording

Object

Optional

[{
    "recording": {
        "type": "system",
        "data": 1234,
        "dtmf": {
            "timeout": 6000,
            "maxLength": 4,
            "retry": 2
        }
    }
}]

type can be one of the below fields

Variable Name

Description

Data Type

system

Required if source of recording is the recording present in the servetel's web portal

String

url

Required if source of recording is an external url

String

dtmf object can have following 3 properties

Variable Name

Description

Field Type

Field Type

timeout

Digit timeout while entering DTMF, to be provided in Milliseconds

Integer

Optional

maxLength

Maximum length of input to be captured

Integer

Optional

retry

Number of retries to take input over recording in case of timeout

Integer

Optional

๐Ÿ“˜

If these keys are not provided, by default, 5000, 10 and 0 will be used for timeout, maxLength and retry, respectively. Maximum number of allowed retries is 5.

Transfer

transfer object has below two properties

Variable Name

Description

Data Type

Field Type

type

Destination for transfer
(Available transfer types are discussed in next section)

String

Required

data

Number or ID for destination depending on transfer type

Array/String

Required

ring_type

Ring strategy in case of multiple numbers/agents in number/agent/intercom transfer types
Can have one of the following values :

  1. order_by
  2. simultaneous

String

Optional

[{
    "transfer": {
        "type": "agent",
        "data": ["12345", "23456", "34567"],
        "ring_type": "order_by"
    }
}]

Refer following table for available transfer types and information on their corresponding data fields

Variable Name

Description

Data Type

number

Required if call is to be transferred to one or more mobile numbers

Array of 10 digit mobile number(s)

agent

Required if call is to be transferred to one or more agents

Array of agent ID(s)

intercom

Required if call is to be transferred to one or more agents using their intercom

Array of intercom of agent(s)

department

Required if call is to be transferred to a department,
ID of Department to be provided in data key

String

ivr

Required if call is to be transferred to an IVR,
ID of IVR to be provided in data key

String

auto_attendant

Required if call is to be transferred to an auto attendant,
ID of Auto Attendant to be provided in data key

String

API Dialplan (api_dialplan)

This object has following property

Variable Name

Description

Data Type

data

ID of API Dial plan to be executed
This ID can be found on edit API Dial plan page

String

[{
    "api_dialplan": {
        "data": "sample_api_dialplan_id123ab"
    }
}]

๐Ÿ“˜

Up to 3 API dial plans can be nested at a time

๐Ÿ‘

Upcoming Features in API Dial plan

Soon, individual retries on invalid input and timeout, recordings to be played on invalid input and timeout, recordings for prompting for retry and destinations for both these cases, minLength of input, and destinations over specific inputs could be configured on API dial plan as well. With this update, the DTMF object in recording action will look like the example given below.

[{
    "dtmf": {
        "maxLength": 5,
        "minLength": 2,
        "invalid": {
            "invalid_recording": {
                "type": "system",
                "data": 514
            },
            "invalid_retry_recording": {
                "type": "system",
                "data": 515
            },
            "retry": 1,
            "destination": {
                "type": "ivr",
                "data": 1111
            }
        },
        "timeout": {
            "timeout_recording": {
                "type": "system",
                "data": 516
            },
            "timeout_retry_recording": {
                "type": "system",
                "data": 515
            },
            "retry": 2,
            "destination": {
                "type": "department",
                "data": 1254
            }
        },
        "destination": {
            "1": {
                "type": "IVR",
                "id": "121"
            },
            "25": {
                "type": "api_dialplan",
                "id": "sample_api_dialplan_id456cde"
            }
        }
    }
}]