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.
    1. Allow registered users to connect with agents, instead of being directed to IVR, to offer accentuated customer service.

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

    1. 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:
FieldDescription
NameThe name of the API Dialplan for easy identification.
DescriptionA brief explanation of the API Dialplan's purpose or functionality.
URLThe endpoint where API requests will be sent.
Request MethodThe HTTP method used for the API call, such as GET or POST.
ActionOptions to Edit or Delete the API Dialplan configuration.
  1. 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:

Field

Description

Name

Specify a unique name for the API Dialplan for easy identification.

Description

Provide a brief description of the API Dialplan’s purpose or functionality.

URL

Enter the endpoint where the API requests will be sent for processing.

Failover Destination

Define the fallback destination (e.g., an agent or queue) if the primary action fails.

Request Method

Select the HTTP method for the request. Options include GET or POST.

Ring Timeout

Set the duration of time (Seconds) for the call to ring on the agent.

Request Body

Define the JSON payload that will be sent with the API request. Example fields include:

uuid: Unique identifier for the request. call_to_number: The number to which the call will be made. caller_id_number: The number of the caller. start_stamp: Timestamp for the call initiation. last_dtmf: DTMF entered by the caller call_flow: The journey of the call. call_id: The unique ID for the call.

Insert Example

Button to insert a predefined example structure into the request body for reference.

Advanced Settings

Section to configure additional HTTP headers for the API request.

Header (Key/Value)

Add custom header key-value pairs (e.g., authentication tokens) with a max length of 1024 characters.

  1. Click Save.

  2. 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.
Variable NameDescriptionData Type
$uuidThe unique ID of the call. For example, 7611.String
$call_to_numberThe dialed number. For example, +91-XXXXXXXXXX.String
$caller_id_numberThe caller number. For example, +91-XXXXXXXXXX.String
$start_stampThe start time of the call. For example, YYYY-mm-dd HH: mm: ss.String
$last_dtmfDTMF entered by the callerString
$call_flowThe journey of the callString
$call_idThe call ID available in call detail records. For example, 1642XXXX.XXX012.String

Request Body

Response Variables

  • The response variables can be either a recording or a transfer along with the API Dialplan.
Variable NameDescriptionData Type
recordingRequired, if play recording is the action to be performed.Object
transferRequired, if call transfer is the action to be performed.Object
api_dialplanRequired, if another API Dialplan is to be executed as an action.Object

📘

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:
Variable NameDescriptionData TypeField Type
typeThe source of the recording.StringRequired
dataThe data required for recording to be played (example: unique ID of recording, URL of recording).StringRequired
dtmfThe DTMF if needed over recording.ObjectOptional
  • Recording can be one of the following fields:
Variable NameDescriptionData Type
systemRequired, if the source of recording is the recording present on TATA's web portal.String
urlRequired, if the source of recording is an external URL.String
  • DTMF object can have the following three properties:
Variable NameDescriptionData TypeField Type
timeoutThe digit timeout while entering DTMF, is to be provided in milliseconds.IntegerOptional
maxlengthThe maximum length of input to be captured.IntegerOptional
retryThe number of retries to take input over recording in case of timeout.IntegerOptional

📘

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:
Variable NameDescriptionData Type
Agent numberRequired if the call is to be transferred to one or more agent's mobile number.Array of 10-digit mobile number(s)
Agent IDRequired if the call is to be transferred to one or more agents using agent ID.Array of agent ID(s)
Agent ExtensionRequired if the call is to be transferred to the agent extensions.Array of agent extension ID(s)
IVRRequired if the call is to be transferred to an IVR.String
Auto AttendantRequired if the call is to be transferred to an auto-attendant.String
DepartmentRequired if the call is to be transferred to a department.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.

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:

Variable Name

Description

Data Type

Field Type

type

The destination for transfer.

String

Required

data

The number or ID for the destination depends on the 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:

  • *1. Order by
  1. Simultaneous**

String

Optional

moh

Plays music or recording when a call is placed on hold.

String

Optional

skip_active

By default false
True or false

Boolean

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.

📘

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.

Variable Name

Description

Data Type

api_dialplan

Represents the configuration and structure of the API Dialplan used to define call flows and integration with external systems.

data

The ID of API Dialplan.

  • *Note:** This ID can be found on the Smartflo 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": "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"
   }
 }]
]