API Dialplan

API Dialplan Overview

• The API Dialplan feature allows clients to implement advanced functionalities that are not available in the standard version or user interface. It operates on a request-response model, processing user requests and providing responses to define the actions that need to be performed. This enables seamless integration of customized workflows tailored to specific business requirements.

  • We provide four custom API Dialplan solutions as explained below:

  1. Allow two parties to communicate with each other with enhanced security without disclosing their numbers.
  
  2. Allow registered users to connect with agents, instead of being directed to IVR, to offer accentuated customer service.

  

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

  

  4. 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.

  Getting Started with API Dialplan

• To go to API Dialplan to your Smartflo account, first log in using your unique User ID and Password. Once logged in, you will be directed to the main dashboard. From there, locate the navigation menu on the left-hand side of the screen and click on "API Connect". A set of options opens up. One of these options is the “API Dialplan".

1. List of all API Dialplan

• The table displays a list of all API Dialplan with the following information:

2. Add API Dialplan

• To add API Dialplan, follow the below steps:

1. Click on the API Connect tab on the side navigation.
2. Click on API Dialplan.
3. A list of all the API Dialplan appears along with the relevant details.
4. Click on Add API Dialplan.

• The following screen will appear, prompting you to complete the necessary fields as shown in the screenshot below.

• Here is a table explaining the fields from the Add API Dialplan interface based on the screenshot:

5. Click Save.

6. Assign API Dialplan to a DID

i. Go to Services - My Numbers to assign API Dialplan to a DID.

ii. Click Select an Action and then click Edit.

iii. Select Destination as your API Dialplan and click SAVE.

Request Variables

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

Request Body

Response Variables

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

📘

Note:

Kindly rasie a Service Request (SR) to Tata Cloud Telephony support team to enable API Dialplan on portal for your account.

Recording

• A System Recording can be used as a pre-recorded message in Auto-Attendant and IVR. We integrate custom recordings provided by the client and play them based on the DTMF response received for specific numbers.
• Let's understand these response variables:

• Recording can be one of the following fields:

• DTMF object can have the following three properties:

📘

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.

🚧

Note

The response from the URL should be in a single line. Below is an example of the expected response format:

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

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

• Refer to the below table for available transfer types and information on their corresponding data fields:

📘

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.

Transfer

• Call transfer based on call queue 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 the client's API.
• This object has the following properties:

🚧

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.

📘

Note:

The default ring strategy for transfers is set to "Order by Ring Strategy."

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": ["981XXXXXXX"],
    "ring_type":"order_by",
    "skip_active":true
	}
}]

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"],
    "ring_type":"order_by",
    "skip_active":true
	}
}]

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"],
    "ring_type":"order_by",
    "skip_active":true
	}
}]

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

Call transfer using Auto Attendant

• Enter the Auto Attendant ID to transfer the call to the specific Auto Attendant. The below example code shows a transfer based on Auto Attendant.

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

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

1. Number:
2. 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 a transfer in the Department using Agent ID.

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

Call transfer to Department with agents not created on panel.

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

[{
	"transfer": {
		"type": "number",
		"data": ["9988776655", "9988776654", "9988776653"],
		"ring_type": "order_by",
    "skip_active":true,
		"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.

Nested API Dialplan

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

📘

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": "6140fff5dba07c19f853ac81"
	}
}]

STEP 1 - 1st API Dialplan:
Request: 
{
  "uuid": "$uuid",
  "call_id": "$call_id",
  "call_to_number": "$call_to_number",
  "caller_id_number": "$caller_id_number",
  "start_stamp": "$start_stamp"
}
 
Expected Response: [
[{
"recording": {
"type": "system",
"data": 156848,
"dtmf":{
       "timeout": 6000,
       "maxLength": 4,
       "retry": 2
   }
 } 
}],
[{
   "api_dialplan": {"data": "6733074ecbb570864f06bc14"
   }
 }]
]
 
STEP 2 - 2nd API Dialplan:
Request: 
{
  "uuid": "$uuid",
  "call_id": "$call_id",
  "call_to_number": "$call_to_number",
  "caller_id_number": "$caller_id_number",
  "start_stamp": "$start_stamp",
  "last_dtmf": "$last_dtmf"
}
Expected Response: [
[{
"recording": {
"type": "system",
"data": 156849,
"dtmf":{
       "timeout": 6000,
       "maxLength": 4,
       "retry": 2
   }
 } 
}],
[{
   "api_dialplan": {"data": "6733074ecbb570864f06bc14"
   }
 }]
]

STEP 3 - 3rd API Dialplan:
Request: 
{
  "uuid": "$uuid",
  "call_id": "$call_id",
  "call_to_number": "$call_to_number",
  "caller_id_number": "$caller_id_number",
  "start_stamp": "$start_stamp",
  "last_dtmf": "$last_dtmf"
}
Expected Response: [
[{
"recording": {
"type": "system",
"data": 156850,
"dtmf":{
       "timeout": 6000,
       "maxLength": 4,
       "retry": 2
   }
 } 
}],
[{
   "api_dialplan": {"data": "6733074ecbb570864f06bc14"
   }
 }]
]