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"
			}
		}
	}
}]

Request Variables

📘

🚧

Response Variables

Recording

📘

Transfer

API Dialplan (api_dialplan)

📘

👍Upcoming Features in API Dial plan

👍
Upcoming Features in API Dial plan