The API Dialplan offers custom solutions for the clients to implement various other features which are not possible through standard version or from user-interface. It is based on request, response and action to be performed.

API Dialplan acts upon user's API and provides a response in return describing the series of actions to be performed.

We provide four custom API Dialplan solutions as explained below:

Allow two parties to communicate with each other with enhanced security without disclosing their numbers.

Allow registered users to connect with agents, instead of being directed to IVR, to offer accentuated customer service.

Ensure customers connect with agents of their local region and help them hear recordings based on their geographical locations.

Allow customers to connect with delivery agents for enhanced coordination for a smooth delivery process.

👍
Summary
Hence, we provide 3 key custom solutions, which are:

Playing custom Recording as per calling user (contains information about the source of the recording)

Transferring calls as per location (contains information about where call is to be transferred)

Implementing nested API Dialplans (contains information about dialplans to be included)

📘
Important!
Before we begin, note that the * sign denotes the mandatory variables in each table.

📘
Important!
Please put API Dialplan as a destination under the My Numbers section in the Acefone panel.

Request Variables

The below data is retrieved from the customer’s API that was specified during API dialplan configuration.

Variable Name	Description	Data Type
$uuid	The unique ID of the call. For example, 7611.	String
$call_to_number	The dialed number. For example, +91-XXXXXXXXXX.	String
$call_id	The call ID available in call detail records. For example, 1642XXXX.XXX012.	String
$caller_id_number	The caller number. For example, +91-XXXXXXXXXX.	String
$start_stamp	The start time of the call. For example, YYYY-mm-dd HH: mm: ss.	String

Request Body

Response Variables

The response variables can be either a recording or a transfer along with the API Dialplan.

Variable Name	Description	Data Type
recording	Required, if play recording is the action to be performed. For example, 1.	Object
transfer	Required, if call transfer is the action to be performed. For example, 12.	Object
api_dialplan	Required, if another API Dialplan is to be executed as an action. For example, 711.	Object

📘
Note:
Kindly contact support team to enable API Dialplan on portal for your account.

Recording

A System Recording can be used as pre-recorded message in Auto-Attendant and IVR. We integrate custom recordings provided by client and play them based on the DTMF response received for specific numbers.

Let's understand these response variables:

Variable Name	Description	Data Type	Field Type
type	The source of recording.	String	Required
data	The data required for recording to be played (example: unique ID of recording, URL of recording).	String	Required
dtmf	The DTMF if needed over recording.	Object	Optional

Recording can be one of the following fields:

Variable Name	Description	Data Type
system	Required, if source of recording is the recording present on web portal.	String
url	Required, if source of recording is an external URL.	String

DTMF object can have following three properties:

Variable Name	Description	Data Type	Field Type
timeout	The digit timeout while entering DTMF, to be provided in milliseconds.	Integer	Optional
maxlength	The maximum length of input to be captured.	Integer	Optional
retry	The number of retries to take input over recording in case of timeout.	Integer	Optional

📘
Note
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.

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

Transfer

Call transfer based on call queues strategies allows us to transfer calls based on client requirements. It is used along with recordings and API Dialplan to provide customized call transfers using client's API.

This object has the following properties:

Variable Name	Description	Data Type	Field Type
type	The destination for transfer.	String	Required
data	The number or ID for destination depending on transfer type.	Array/String	Required
ring type	The ring strategy in case of multiple numbers/agents in number/agent/intercom transfer types can have one of the following values: Order by Simultaneous	String	Optional

🚧
Note
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.

The Call transfer to the agent can be done in three ways:

Number
Agent ID
Agent extension

Call transfer based on Agent number

Enter the 10 digit phone number to transfer the call to the specific agent.
The below example code shows transfer based on Number.

[{
	"transfer": {
		"type": "number",
		"data": ["9898981111"]
	}
}]

Call transfer based on Agent ID

Enter the Agent ID to transfer the call to the specific agent.
The below example code shows transfer based on ID.

[{
	"transfer": {
		"type": "agent",
		"data": ["05000001"]
	}
}]

Call transfer based on Agent Extensions

Enter the Agent Extension to transfer the call to the specific agent.
The below example code shows transfer based on Agent Extension.

[{
	"transfer": {
		"type": "agent",
		"data": ["06047530001"]
	}
}]

Call transfer using IVR

Enter the IVR id to transfer the call to the specific IVR.
The below example code shows transfer based on IVR.

[{
	"transfer": {
		"type": "ivr",
		"data": ["22590"]
	}
}]

The Call transfer to the agent in a Department can be done in two ways:

Number
Agent ID

Call transfer to Department with agents created on panel.

Enter the Agent ID to transfer the call to the specific Department.
The below example code shows transfer in the Department using Agent ID.

[{
	"transfer": {
		"type": "agent",
		"data": ["05000001", "05000002", "05000003"],
		"ring_type": "order_by",
		"moh": "1235"
	}
}]

Call transfer to Department with agents not created on panel.

Enter the Agent number to transfer the call to Department.
The below example code shows transfer in the Department using number.

[{
	"transfer": {
		"type": "number",
		"data": ["9988776655", "9988776654", "9988776653"],
		"ring_type": "order_by",
		"moh": "1235"
	}
}]

📘
Music on Hold in Transfer
The 'moh' key expects ID of the system recording to be used as MOH during transfer. It is required that this recording is marked as MOH.
A non MOH marked recording will be treated as an invalid input.

Refer to the below 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. For example, 9180XXXXXXX6.	Array of 10 digit mobile number(s)
agent	Required if call is to be transferred to one or more agents. For example, agent 4552.	Array of agent ID(s)
intercom	Required if call is to be transferred to one or more agents using their intercom. For example, extension 5624.	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. For example, department 965.	String
ivr	Required if call is to be transferred to an IVR, ID of IVR to be provided in data key. For example, ivr 236.	String
auto_attendant	Required if call is to be transferred to an auto-attendant, ID of Auto Attendant to be provided in data key. For example, auto_attendant 123.	String

📘
Note:
For number and agent types, in the above table, multiple values are supported, whereas for the rest only a single value will be accepted. The response schema displayed below mentions the value for number and agent types.

API Dialplan

The existing API Dialplan that needs to be executed to perform necessary actions. You can add multiple API Dialplan to perform various actions.

Variable Name	Description	Data Type
data	The ID of API Dialplan. Note: This ID can be found on Acefone portal.	String

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

In return, we expect a response in the below format:

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

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