Robo call API

Updated 1 year ago by Jane

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

  • true: enable Call recording for this call.
  • false: disable Call recording for this call.

steps*

object

The steps (from start to end) of the call flow, choose one option among:

  • play: Play a message
  • gather: Gather input from user
  • transfer: Transfer the call to another destination.

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:

  • e164 number (e.g. +656123545)
  • "any"
  • "none"
  • "regex pattern"

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:

  • e164
  • extension with ext: prefix . NOTE: 405 must be an existing extension key Bizphone app.
  • +656123545
  • ext:405

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:

  • submitted: The call is submitted.
  • ongoing: The call request is submitted and it is being in progress.
  • finished: The call request ends.

status

string

The status of the call flow. Possible values:

  • onProgress: The call is being in a call flow.
  • finished: Call flow ends.

call_state

string

The current state of this call. Possible values:

  • ongoing: This call has been answered. You should follow up with one of the Middle or End blocks.
  • ended: This call has ended. You should not send any more requests for this call.

call_status

string

The status of the call after it is dialed. Possible values:

  • answered: This call has been answered.
  • unanswered: This call is not answered.
  • busy: This call rings at the recipient and receives a busy signal.

status

string

The status of the execution of the step. Possible values:

  • success_ok: The step is successfully executed.
  • error_concurrent_call_limit_reached: Error occurs. Reason: the call reached the concurrent call limit. You might need to increase the concurrent call by upgrading the subscription or just ignore this error if it is not happening quite frequently.

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:

  • answered: This call has been answered.
  • unanswered: This call is not answered after it is transferred.


How did we do?


Powered by HelpDocs (opens in a new tab)

Powered by HelpDocs (opens in a new tab)