API Dialplan

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:

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.

📘

Important!

Please put API Dialplan as a destination under the My Numbers section in the Smartflo panel.

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 contact Tata Cloud Telephony services 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:

Recording can be one of the following fields:

DTMF object can have 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.

[{
	"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:

🚧

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.
  
  
  Sample transfer objects

  [{
  	"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.
  
  
  Sample transfer objects

  [{
  	"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.
  
  
  Sample transfer objects

  [{
  	"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.
  
  
  Sample transfer objects

  [{
  	"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.
    
    
    Sample transfer objects

    [{
    	"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.
    
    
    Sample transfer objects

    [{
    	"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 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:

    sample api dialplan object

    [{
    	"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.

    sample new dtmf object

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