Robo call API
openapi: 3.0.2
version: 1.0.0
https://{baseOpenAPI}}/v1
Queue up calls request
- HTTP method: POST
- URL: /call
- Content type: application/json
- operationId: queueUpCall
- header: x-credential-api-key
This API will trigger a call with a configured call flow (including Play message, Gather input from user, or Transfer call) to a bulk of [E.164] phone number destinations.
- Click here to know E.164 format: https://en.wikipedia.org/wiki/E.164
All the calls will be queued sequentially. The number of calls triggered at a point of time equals to the number of free concurrent calls your organization at that moment.
- Your organization has 6 concurrent calls, and 100 calls are queued with request id _call_request_1
- At moment t1, your organization has 2 ongoing calls from BizPhone app then 4 queued calls will be triggered.
- At moment t2, your organization has 5 ongoing calls from BizPhone app then 1 queued call will be triggered.
- The process continue until all queued calls are triggered
Robo: Check status of an submitted call request
- HTTP method: GET
- URL: /status/{requestId}
- Content type: application/json
- Description: The API provides the status of a specific request and also status of all its calls
- operationId: checkCallStatus
Parameters
Name | Type | Description | Example |
x-credential-api-key | string (header) | Application ID assigned to your application. | |
requestId* | string | The request Id that is submitted when making a call. This ID is unique. | call_request_11 |
destinations* | Detailed information of a phone number, including phone number, caller and any additional properties. | ||
phone | string | pattern: ^\+?[1-9]\d{1,14}$ Destination [E.164] phone number | +6588893322 |
caller | string | pattern: ^\+?[1-9]\d{1,14}$ Caller id of the call (the [E.164] phone number will display on destination phone/app screen | +623882772 |
properties (place holder) | Placeholders can be put into the message and be replaced with properties of each destination. | Dear {{name}}, you are owning us {{amount}} and the due date is {{dueDate}}. | |
name | string | Name of the customer. | Alex |
dueDate | string | Due date of the payment. | August 20th, 2020 |
amount | string | Amount that the recipient needs to pay. | 200,000$ |
enableCallRecording | boolean | Enable call recording feature, values are
| |
steps* | object | The steps (from start to end) of the call flow, choose one option among:
| |
message* | object | The message that you want to play after the call is answered. | |
msg* | string | The message that you want to play after the call is answered. Max 1000 characters. | |
language | string | Language used in the call. | language chosen is English: "lang": "en" |
gender | string | The gender of the voice used in the call. Possible values: male, female | |
pitch | integer | The degree of highness or lowness of a tone; from 0 (lowest) to 9 (highest). Default value = 5 | |
rate | integer | Reading rate of voice message; from 0 (slowest) to 9 (fastest). Default value = 5 | |
maxRetries | integer | The maximum times that the recipient can give a value. Default value is 3. | |
branches* | object | Next step after gather branch depending on user input | |
digit | string | string The digit that the recipient needs to press in order to move to the next step. Possible values:
| |
default | default | If the branch is the default branch of the gather step | |
destination* | string | The destination that a call is transferred to. Possible formats:
|
|
Example value
{
"requestId": "request_10",
"destinations": [
{
"phone": "+84917660247",
"caller": "+6582674904",
"properties": {
"name": "Alex",
"dueDate": "August 20th, 2020",
"amount": "200,000$"
}
},
{
"phone": "+84912860330",
"caller": "+6582674904",
"properties": {
"name": "Alex",
"dueDate": "August 20th, 2020",
"amount": "200,000$"
}
}
],
"enableCallRecording": true,
"callFlow": {
"steps": [
{
"name": "play",
"message": {
"msg": "thanks {{name}}",
"lang": "en",
"gender": "male"
}
},
{
"name": "gather",
"message": {
"msg": "Dear Mr {{name}}, the amount of {{amount}} will be due on {{dueDate}}"
},
"branches": [
{
"digit": "1",
"default": "false",
"callFlow": {
"steps": [
{
"name": "gather",
"message": {
"msg": "message need to play",
"lang": "en",
"gender": "female"
},
"branches": [
{
"default": "true",
"callFlow": {
"steps": [
{
"name": "play",
"message": {
"msg": "msg need to play"
}
}
]
}
}
]
}
]
}
},
{
"digit": "0",
"default": "true",
"callFlow": {
"steps": [
{
"name": "transfer",
"destination": "Ext:1000"
}
]
}
}
]
}
]
}}
Response result
Result | Description |
200 | Request is successfully added and being processed |
400 | Bad request |
Example of successful result
{
"requestId": "string",
"status": "submitted",
"details": [
{
"requestId": "string",
"caller": "string",
"destination": "string",
"status": "onProgress",
"callFlowSteps": [
{
"stepName": "string",
"info": {
"call_state": "ongoing",
"call_status": "answered",
"status": "sucess_ok error_concurrent_call_limit_reache",
"userPressedDigits": "string",
"transfer_status": "answered"
}
}
],
"monitorData": [
{
"uuid": "string",
"type": "string",
"dest": "+6591991191 1000"
}
]
}
]}
Example of bad result
{
"status": "string",
"message": "string"}
Call detail parameters
Name | Description |
status | string The status of the call request. Possible values:
|
status | string The status of the call flow. Possible values:
|
call_state | string The current state of this call. Possible values:
|
call_status | string The status of the call after it is dialed. Possible values:
|
status | string The status of the execution of the step. Possible values:
|
userPressedDigits | string The user's response. This parameter may be empty if the user did not input anything before the timeout and attempts is reached. |
transfer_status | string The status of the transfer step. Possible values:
|
