Basic authentication
Requests use basic authentication. To create API credentials go to Settings-> Developer Settings-> API Credentials.
- The subdomain is used as the username ({{username}} variable)
- The token is used as the password ({{password}} variable)
Every installation will have their own subdomain. To find the subdomain, locate the URL in your browser. It should look like:
Take that subdomain, the most left value, and substitute it into the {{subdomain}} variable. The remainder would be substituted into the {{domain}} variable.
In the above example, {{subdomain}} would be "customer" and {{domain}} would be "rest.of.url.com"
Base URL
The API uses the following base URL for all of its API requests
https://{{subdomain}}.{{domain}}/apps/api/v1
where a mention to "/calls" means https://{{subdomain}}.{{domain}}/apps/api/v1/calls
Rate Limits
The system limits requests to a rate of 1 request per second per customer.
Variables
| Key | Value | Type |
|---|---|---|
| subdomain | ||
| username | ||
| password | ||
| call_type | ||
| agent_email | ||
| ticket_id | ||
| end_user_number | ||
| outbound_number | ||
| lang | ||
| menu_id | ||
| wait[from] | ||
| wait[to] | ||
| channel_type | ||
| menu_type | ||
| recording_permission | ||
| job_id |
Calls Endpoints
A call object is created for every single call that is made into, or out of CCAI Platform.
{
"id": 0,
"parent_id": 0,
"lang": "en",
"call_type": "Voice Scheduled (API)",
"status": "scheduled",
"created_at": "2018-06-07T19:49:52.896Z",
"queued_at": "2018-06-07T19:49:52.896Z",
"assigned_at": "2018-06-07T19:49:52.896Z",
"connected_at": "2018-06-07T19:49:52.896Z",
"ends_at": "2018-06-07T19:49:52.896Z",
"scheduled_at": "2018-06-07T19:49:52.896Z",
"wait_duration": 0,
"call_duration": 0,
"hold_duration": 0,
"rating": 0,
"has_feedback": true,
"voip_provider": "voip_provider_twilio",
"out_ticket_id": "string",
"out_ticket_url": "string",
"verified": true,
"recording_url": "string",
"recording_permission": "not_asked",
"voicemail_reason": "not_voicemail",
"deflection": "no_deflection",
"disconnected_by": "disconnected_by_unknown",
"fail_details": "string",
"fail_reason": "nothing",
"support_number": "string",
"selected_menu": {
"id": 0,
"name": "string",
"parent_id": 0,
"position": 0,
"deleted": true,
"hidden": "string",
"menu_type": "ivr_menu",
"output_msg": "string"
},
"menu_path": {
"items_count": 0,
"name": "string",
"materialized_path": "string"
},
"agent_info": {
"id": 0,
"name": "string",
"last_name": "string",
"first_name": "string",
"agent_number": "string",
"avatar_url": "string"
},
"end_user": {
"id": 0,
"identifier": "string",
"out_contact_id": "string"
},
"photos": [
{
"id": 0,
"photo_type": "photo",
"url": "string"
}
],
"videos": [
{
"id": 0,
"url": "string"
}
],
"transfers": [
{
"id": 0,
"status": "transferring",
"fail_reason": "nothing",
"created_at": "2018-06-07T19:49:52.896Z",
"from_menu": {
"items_count": 0,
"name": "string",
"materialized_path": "string"
},
"to_menu": {
"items_count": 0,
"name": "string",
"materialized_path": "string"
},
"from_agent": {
"id": 0,
"name": "string",
"last_name": "string",
"first_name": "string",
"agent_number": "string",
"avatar_url": "string"
},
"to_agent": {
"id": 0,
"name": "string",
"last_name": "string",
"first_name": "string",
"agent_number": "string",
"avatar_url": "string"
}
}
],
"participants": [
{
"id": 0,
"type": "end_user",
"status": "waiting",
"call_id": 0,
"user_id": 0,
"end_user_id": 0,
"call_duration": 0,
"hold_duration": 0,
"connected_at": "2018-06-07T19:49:52.896Z",
"ended_at": "2018-06-07T19:49:52.896Z",
"fail_reason": "nothing"
}
]
}
]
The status field can be in any of the following states
| Call Status | Description |
|---|---|
| Selecting | State that occurs when an end user has called into the contact center, but is still navigating the menu options prior to being placed in a leaf menu. |
| Queued | State that occurs after the end user has selected a leaf menu node and initiated a call request to be deltcasted or multicasted to an agent. |
| Assigned | State that occurs when an agent is selected to receive the end user call. This occurs when a call is picked up by an agent. |
| Connecting | State that occurs after an agent is assigned, and a connection is being established between the end user and the agent. |
| Connected | State that occurs when the call has established a connection and the agent and end user are both placed into a call. |
| Finished | State that occurs when a call ends after it has been connected. |
| Failed | State that occurs when a call ends before it was successfully connected. A fail reason will also be provided for additional details. |
| Switching | State that occurs when a call fails while trying to connect and CCAI Platform attempts to connect the call with a different VOIP provider. |
| Recovered | State that occurs when a failed call is called back. This new call is a child to the original call. Recovered notes that the call back is finished without error. |
| Scheduled | State that occurs when an end user has scheduled a future call via In-Web or In-App. |
| Action Only | State that occurs when a call that is handled by our client's own telephony provider is connected to our iOS or Android SDK. |
| Action Only Finished | State that occurs when a call that is handled by our client's own telephony provider is connected to our iOS or Android SDK and finishes |
| Deflected | State that occurs based on the configuration for overcapacity queues or after hour calls. Deflection options include voicemail, schedule call among others. Deflection will vary based on channel (In-app, IVR, In-web) |
| Voicemail | State that occurs when an end user is deflected to a voicemail option, and opts to leave a voicemail message to listened to later. This state is present when the end user is leaving the voicemail |
| Voicemail Received | State that occurs after an end user has left a voicemail and an agent has not listened to the voicemail |
| Voicemail Read | State that occurs when an agent has opened the voicemail to listen to. |
The call_type field can only be one of the following values
| Call Type | Description |
|---|---|
| Voice Outbound (API) | Call made from Outbound Call API. |
| Voice Inbound (API) | Call made from Incoming Call API. |
| Voice Scheduled (API) | Call made from Scheduled Call API. |
The following are the most common API Responses:
| Response Code | Meaning |
|---|---|
| 201 | The API request has been successful and will create a call |
| 202 | The API request has been successful, but manual intervention is required inside of the widget to complete the action |
| 400 | invalid call type - ensure call_type is supported |
| 400 | Agent is not available to take this call |
| 400 | Missing parameter - check to ensure that the required parameters have been added |
| 404 | Resource not found - Please check your subdomain |
1. Outbound Call - end_user_number
| Parameter | Required | Data Type | Definition | Postman Variable |
|---|---|---|---|---|
| call_type | TRUE | String | Call type to create. "Voice Outbound (API)", "OutboundCall" (deprecated) are available for now | Voice Outbound (API) |
| agent_email | TRUE | String | Email address for the agent who will be assigned to the outbound call. | {{agent_email}} |
| ticket_id | FALSE | String | CRM ticket ID and it will dial to the end user who is tied to the ticket. | {{ticket_id}} |
| end_user_number | FALSE | String | End user phone number which will be dialing. ticket_id has a higher priority than end_user_number. | {{end_user_number}} |
| outbound_number | FALSE | String | Well-formed outbound number which is managed from Settings > Phone Numbers > Phone Number Management. Default outbound number will be used when empty | {{outbound_number}} |
| lang | FALSE | String | Language of the call. Uses ISO 639-1 codes. (Default: "en") | {{lang}} |
Endpoint:
Method: POST
Type: RAW
URL: https://{{subdomain}}.{{domain}}/apps/api/v1/calls
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Body:
{
"call_type": "Voice Outbound (API)",
"agent_email": "agent@somedomain.com",
"outbound_number": "+1 760-867-5309",
"end_user_number": "123123",
"lang": "en"
}
More example Requests/Responses:
I. Example Request: Error : Agent is not available to take this call
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Body:
{
"call_type": "Voice Outbound (API)",
"agent_email": "agent@somedomain.com",
"end_user_number": "+1 205-123-4567",
"lang": "en"
}
I. Example Response: Error : Agent is not available to take this call
{
"message": "Agent is not available to take this call"
}
Status Code: 400
II. Example Request: Create an outbound call with end_user_number
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Body:
{
"call_type": "Voice Outbound (API)",
"agent_email": "admin@somedomain.com",
"end_user_number": "+1 859-657-9625",
"outbound_number": "+1 339-219-5276",
"lang": "en"
}
II. Example Response: Create an outbound call with end_user_number
{
"id": 397,
"lang": "en",
"call_type": "Voice Outbound (API)",
"status": "assigned",
"created_at": "2019-06-07T01:27:30.406Z",
"queued_at": null,
"assigned_at": "2019-06-07T01:27:30.441Z",
"connected_at": null,
"ends_at": null,
"scheduled_at": null,
"wait_duration": 0,
"call_duration": 0,
"hold_duration": 0,
"rating": null,
"has_feedback": false,
"voip_provider": "voip_provider_twilio",
"out_ticket_id": null,
"out_ticket_url": null,
"verified": false,
"recording_url": null,
"recording_permission": "not_asked",
"voicemail_reason": "not_voicemail",
"deflection": "no_deflection",
"disconnected_by": "disconnected_by_unknown",
"fail_reason": "nothing",
"fail_details": null,
"support_number": null,
"selected_menu": null,
"menu_path": null,
"agent_info": {
"id": 1,
"agent_number": null,
"name": "Admin UJET",
"last_name": "UJET",
"first_name": "Admin",
"avatar_url": "https://somedomain.com/avatar.jpg"
},
"end_user": null,
"photos": [],
"videos": [],
"transfers": [],
"deflection_details": [],
"participants": [
{
"id": 610,
"type": "agent",
"status": "waiting",
"call_id": 397,
"user_id": 1,
"end_user_id": null,
"call_duration": null,
"hold_duration": null,
"connected_at": null,
"ended_at": null,
"fail_reason": "nothing"
},
{
"id": 611,
"type": "end_user",
"status": "waiting",
"call_id": 397,
"user_id": null,
"end_user_id": null,
"call_duration": null,
"hold_duration": null,
"connected_at": null,
"ended_at": null,
"fail_reason": "nothing"
}
],
"offer_type": null,
"offer_events": [],
"answer_type": "manual",
"outbound_number": "+1 339-219-5276"
}
Status Code: 201
III. Example Request: Create an outbound call with ticket_id
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Body:
{
"call_type": "Voice Outbound (API)",
"agent_email": "agent@somedomain.com",
"ticket_id": "71450",
"outbound_number": "+1 339-219-5276",
"lang": "en"
}
III. Example Response: Create an outbound call with ticket_id
{
"id": 398,
"lang": "en",
"call_type": "Voice Outbound (API)",
"status": "assigned",
"created_at": "2019-06-07T01:28:47.955Z",
"queued_at": null,
"assigned_at": "2019-06-07T01:28:47.971Z",
"connected_at": null,
"ends_at": null,
"scheduled_at": null,
"wait_duration": 0,
"call_duration": 0,
"hold_duration": 0,
"rating": null,
"has_feedback": false,
"voip_provider": "voip_provider_twilio",
"out_ticket_id": "71450",
"out_ticket_url": null,
"verified": false,
"recording_url": null,
"recording_permission": "not_asked",
"voicemail_reason": "not_voicemail",
"deflection": "no_deflection",
"disconnected_by": "disconnected_by_unknown",
"fail_reason": "nothing",
"fail_details": null,
"support_number": null,
"selected_menu": null,
"menu_path": null,
"agent_info": {
"id": 1,
"agent_number": null,
"name": "Admin UJET",
"last_name": "UJET",
"first_name": "Admin",
"avatar_url": "https://somedomain.com/avatar.png"
},
"end_user": {
"id": 67,
"identifier": null,
"out_contact_id": "381630957514"
},
"photos": [],
"videos": [],
"transfers": [],
"deflection_details": [],
"participants": [
{
"id": 612,
"type": "agent",
"status": "waiting",
"call_id": 398,
"user_id": 1,
"end_user_id": null,
"call_duration": null,
"hold_duration": null,
"connected_at": null,
"ended_at": null,
"fail_reason": "nothing"
},
{
"id": 613,
"type": "end_user",
"status": "waiting",
"call_id": 398,
"user_id": null,
"end_user_id": 67,
"call_duration": null,
"hold_duration": null,
"connected_at": null,
"ended_at": null,
"fail_reason": "nothing"
}
],
"offer_type": null,
"offer_events": [],
"answer_type": "manual",
"outbound_number": "+1 339-219-5276"
}
Status Code: 201
IV. Example Request: Error : ticket_id or end_user_number required
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Body:
{
"call_type": "Voice Outbound (API)",
"agent_email": "allen@somedomain.com",
"end_user_number": "+1 205-123-4567",
"lang": "en"
}
IV. Example Response: Error : ticket_id or end_user_number required
{
"message": "ticket_id or end_user_number required"
}
Status Code: 400
V. Example Request: Error : Not a valid agent email
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Body:
{
"call_type": "Voice Outbound (API)",
"agent_email": "admin@somedomain.com",
"end_user_number": "+1 205-123-4567",
"lang": "en"
}
V. Example Response: Error : Not a valid agent email
{
"message": "Not a valid agent email"
}
Status Code: 400
VI. Example Request: Error : Agent email required
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Body:
{
"call_type": "Voice Outbound (API)",
"end_user_number": "+1 205-123-4567",
"lang": "en"
}
VI. Example Response: Error : Agent email required
{
"message": "Agent email required"
}
Status Code: 400
VII. Example Request: Error : Agent does not have access to make calls
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Body:
{
"call_type": "Voice Outbound (API)",
"agent_email": "allen@somedomain.com",
"end_user_number": "+1 205-123-4567",
"lang": "en"
}
VII. Example Response: Error : Agent does not have access to make calls
{
"message": "Agent does not have access to make calls"
}
Status Code: 400
VIII. Example Request: Error : end_user_number is not well-formed
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Body:
{
"call_type": "Voice Outbound (API)",
"agent_email": "allen@somedomain.com",
"outbound_number": "+1 760-410-8538",
"end_user_number": "123123",
"lang": "en"
}
VIII. Example Response: Error : end_user_number is not well-formed
{
"message": "end_user_number is not well-formed"
}
Status Code: 400
IX. Example Request: Error : Contact not found
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Body:
{
"call_type": "Voice Outbound (API)",
"agent_email": "allen@somedomain.com",
"outbound_number": "+1 760-410-8538",
"ticket_id": 1,
"lang": "en"
}
IX. Example Response: Error : Contact not found
{
"message": "Contact not found"
}
Status Code: 400
X. Example Request: Accepted : Need to choose an outbound number
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Body:
{
"call_type": "Voice Outbound (API)",
"agent_email": "allen@somedomain.com",
"end_user_number": "+1 205-123-4567",
"lang": "en"
}
Status Code: 202
XI. Example Request: Error : Invalid call type
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Body:
{
"call_type": "Voice Outbound (API)",
"agent_email": "allen@somedomain.com",
"outbound_number": "+1 760-410-8538",
"end_user_number": "123123",
"lang": "en"
}
XI. Example Response: Error : Invalid call type
{
"message": "Invalid call type"
}
Status Code: 400
XII. Example Request: Prompt the call widget by multiple outbound numbers
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Body:
{
"call_type": "Voice Outbound (API)",
"agent_email": "admin@somedomain.com",
"end_user_number": "+1 859-657-9625",
"lang": "en"
}
Status Code: 202
XIII. Example Request: Accepted : Agent must make an outbound call with ticket id
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Body:
{
"call_type": "Voice Outbound (API)",
"agent_email": "allen@somedomain.com",
"end_user_number": "+1 205-123-4567",
"lang": "en"
}
Status Code: 202
2. Outbound Call - ticket_id
| Parameter | Required | Data Type | Definition | Postman Variable |
|---|---|---|---|---|
| call_type | TRUE | String | Call type to create. "Voice Outbound (API)", "OutboundCall" (deprecated) are available for now | Voice Outbound (API) |
| agent_email | TRUE | String | Email address for the agent who will be assigned to the outbound call. | {{agent_email}} |
| ticket_id | FALSE | String | CRM ticket ID and it will dial to the end user who is tied to the ticket. | {{ticket_id}} |
| end_user_number | FALSE | String | End user phone number which will be dialing. ticket_id has a higher priority than end_user_number. | {{end_user_number}} |
| outbound_number | FALSE | String | Well-formed outbound number which is managed from Settings > Phone Numbers > Phone Number Management. Default outbound number will be used when empty | {{outbound_number}} |
| lang | FALSE | String | Language of the call. Uses ISO 639-1 codes. (Default: "en") | {{lang}} |
Endpoint:
Method: POST
Type: RAW
URL: https://{{subdomain}}.{{domain}}/apps/api/v1/calls
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Body:
{
"call_type": "Voice Outbound (API)",
"agent_email": "allen@somedomain.com",
"outbound_number": "+1 760-867-5309",
"ticket_id": "123123",
"lang": "en"
}
More example Requests/Responses:
I. Example Request: Error : ticket_id or end_user_number required
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Body:
{
"call_type": "Voice Outbound (API)",
"agent_email": "allen@somedomain.com",
"end_user_number": "+1 205-123-4567",
"lang": "en"
}
I. Example Response: Error : ticket_id or end_user_number required
{
"message": "ticket_id or end_user_number required"
}
Status Code: 400
II. Example Request: Error : Agent email required
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Body:
{
"call_type": "Voice Outbound (API)",
"end_user_number": "+1 205-123-4567",
"lang": "en"
}
II. Example Response: Error : Agent email required
{
"message": "Agent email required"
}
Status Code: 400
III. Example Request: Create an outbound call with end_user_number
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Body:
{
"call_type": "Voice Outbound (API)",
"agent_email": "admin@somedomain.com",
"end_user_number": "+1 859-657-9625",
"outbound_number": "+1 339-219-5276",
"lang": "en"
}
III. Example Response: Create an outbound call with end_user_number
{
"id": 397,
"lang": "en",
"call_type": "Voice Outbound (API)",
"status": "assigned",
"created_at": "2019-06-07T01:27:30.406Z",
"queued_at": null,
"assigned_at": "2019-06-07T01:27:30.441Z",
"connected_at": null,
"ends_at": null,
"scheduled_at": null,
"wait_duration": 0,
"call_duration": 0,
"hold_duration": 0,
"rating": null,
"has_feedback": false,
"voip_provider": "voip_provider_twilio",
"out_ticket_id": null,
"out_ticket_url": null,
"verified": false,
"recording_url": null,
"recording_permission": "not_asked",
"voicemail_reason": "not_voicemail",
"deflection": "no_deflection",
"disconnected_by": "disconnected_by_unknown",
"fail_reason": "nothing",
"fail_details": null,
"support_number": null,
"selected_menu": null,
"menu_path": null,
"agent_info": {
"id": 1,
"agent_number": null,
"name": "Admin UJET",
"last_name": "UJET",
"first_name": "Admin",
"avatar_url": "https://somedomain.com/default-profile.png"
},
"end_user": null,
"photos": [],
"videos": [],
"transfers": [],
"deflection_details": [],
"participants": [
{
"id": 610,
"type": "agent",
"status": "waiting",
"call_id": 397,
"user_id": 1,
"end_user_id": null,
"call_duration": null,
"hold_duration": null,
"connected_at": null,
"ended_at": null,
"fail_reason": "nothing"
},
{
"id": 611,
"type": "end_user",
"status": "waiting",
"call_id": 397,
"user_id": null,
"end_user_id": null,
"call_duration": null,
"hold_duration": null,
"connected_at": null,
"ended_at": null,
"fail_reason": "nothing"
}
],
"offer_type": null,
"offer_events": [],
"answer_type": "manual",
"outbound_number": "+1 339-219-5276"
}
Status Code: 201
IV. Example Request: Error : Invalid call type
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Body:
{
"call_type": "ScheduledCall",
"agent_email": "allen@somedomain.com",
"outbound_number": "+1 760-410-8538",
"end_user_number": "123123",
"lang": "en"
}
IV. Example Response: Error : Invalid call type
{
"message": "Invalid call type"
}
Status Code: 400
V. Example Request: Prompt the call widget by multiple outbound numbers
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Body:
{
"call_type": "Voice Outbound (API)",
"agent_email": "admin@somedomain.com",
"end_user_number": "+1 859-657-9625",
"lang": "en"
}
Status Code: 202
VI. Example Request: Accepted : Agnet must make an outbound call with ticket id
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Body:
{
"call_type": "Voice Outbound (API)",
"agent_email": "allen@somedomain.com",
"end_user_number": "+1 205-123-4567",
"lang": "en"
}
Status Code: 202
VII. Example Request: Error : Agent does not have access to make calls
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Body:
{
"call_type": "Voice Outbound (API)",
"agent_email": "allen@somedomain.com",
"end_user_number": "+1 205-123-4567",
"lang": "en"
}
VII. Example Response: Error : Agent does not have access to make calls
{
"message": "Agent does not have access to make calls"
}
Status Code: 400
VIII. Example Request: Create an outbound call with ticket_id
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Body:
{
"call_type": "Voice Outbound (API)",
"agent_email": "admin@somedomain.com",
"ticket_id": "71450",
"outbound_number": "+1 339-219-5276",
"lang": "en"
}
VIII. Example Response: Create an outbound call with ticket_id
{
"id": 398,
"lang": "en",
"call_type": "Voice Outbound (API)",
"status": "assigned",
"created_at": "2019-06-07T01:28:47.955Z",
"queued_at": null,
"assigned_at": "2019-06-07T01:28:47.971Z",
"connected_at": null,
"ends_at": null,
"scheduled_at": null,
"wait_duration": 0,
"call_duration": 0,
"hold_duration": 0,
"rating": null,
"has_feedback": false,
"voip_provider": "voip_provider_twilio",
"out_ticket_id": "71450",
"out_ticket_url": null,
"verified": false,
"recording_url": null,
"recording_permission": "not_asked",
"voicemail_reason": "not_voicemail",
"deflection": "no_deflection",
"disconnected_by": "disconnected_by_unknown",
"fail_reason": "nothing",
"fail_details": null,
"support_number": null,
"selected_menu": null,
"menu_path": null,
"agent_info": {
"id": 1,
"agent_number": null,
"name": "Admin UJET",
"last_name": "UJET",
"first_name": "Admin",
"avatar_url": "https://somedomain.com/default-profile.png"
},
"end_user": {
"id": 67,
"identifier": null,
"out_contact_id": "381630957514"
},
"photos": [],
"videos": [],
"transfers": [],
"deflection_details": [],
"participants": [
{
"id": 612,
"type": "agent",
"status": "waiting",
"call_id": 398,
"user_id": 1,
"end_user_id": null,
"call_duration": null,
"hold_duration": null,
"connected_at": null,
"ended_at": null,
"fail_reason": "nothing"
},
{
"id": 613,
"type": "end_user",
"status": "waiting",
"call_id": 398,
"user_id": null,
"end_user_id": 67,
"call_duration": null,
"hold_duration": null,
"connected_at": null,
"ended_at": null,
"fail_reason": "nothing"
}
],
"offer_type": null,
"offer_events": [],
"answer_type": "manual",
"outbound_number": "+1 339-219-5276"
}
Status Code: 201
IX. Example Request: Accepted : Need to choose an outbound number
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Body:
{
"call_type": "Voice Outbound (API)",
"agent_email": "allen@somedomain.com",
"end_user_number": "+1 205-123-4567",
"lang": "en"
}
Status Code: 202
X. Example Request: Error : Agent is not available to take this call
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Body:
{
"call_type": "Voice Outbound (API)",
"agent_email": "allen@somedomain.com",
"end_user_number": "+1 205-123-4567",
"lang": "en"
}
X. Example Response: Error : Agent is not available to take this call
{
"message": "Agent is not available to take this call"
}
Status Code: 400
XI. Example Request: Error : end_user_number is not well-formed
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Body:
{
"call_type": "Voice Outbound (API)",
"agent_email": "allen@somedomain.com",
"outbound_number": "+1 760-410-8538",
"end_user_number": "123123",
"lang": "en"
}
XI. Example Response: Error : end_user_number is not well-formed
{
"message": "end_user_number is not well-formed"
}
Status Code: 400
XII. Example Request: Error : Not a valid agent email
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Body:
{
"call_type": "Voice Outbound (API)",
"agent_email": "admin@somedomain.com",
"end_user_number": "+1 205-123-4567",
"lang": "en"
}
XII. Example Response: Error : Not a valid agent email
{
"message": "Not a valid agent email"
}
Status Code: 400
XIII. Example Request: Error : Contact not found
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Body:
{
"call_type": "Voice Outbound (API)",
"agent_email": "allen@somedomain.com",
"outbound_number": "+1 760-410-8538",
"ticket_id": 1,
"lang": "en"
}
XIII. Example Response: Error : Contact not found
{
"message": "Contact not found"
}
Status Code: 400
3. Incoming Call
| Parameter | Required | Data Type | Definition | Postman Variable |
|---|---|---|---|---|
| call_type | TRUE | String | Call type to create. Use "Voice Inbound (API)" or "IncomingCall" (deprecated) to create an incoming call. | Voice Inbound (API) |
| menu_id | TRUE | Integer | The ID of the menu to attribute the call to. Only IVR and Web menu IDs are accepted. | {{menu_id}} |
| end_user_number | TRUE | String | The end user phone number that will be dialed. If both a ticket_id and end_user_number are passed in, the ticket_id will take precedence. | {{end_user_number}} |
| lang | FALSE | String | Language of the call. Uses ISO 639-1 codes. (Default: "en") | {{lang}} |
| ticket_id | FALSE | String | CRM ticket ID. The end user phone number tied to the ticket will be dialed. If both a ticket_id and end_user_number are passed in, the ticket_id will take precedence. | {{ticket_id}} |
| outbound_number | FALSE | String | The outbound phone number to be used for the call. The default global outbound phone number will be used if input is not passed in or invalid. Outbound numbers are managed from Settings > Queue > EDIT / VIEW > Select a queue > Outbound Phone Numbers. | {{outbound_number}} |
| recording_permission | FALSE | String | The value is only evaluated if the "Call Recording Options" feature is set to "Ask User for Permission to Record". Configurable at Settings > Queue > EDIT / VIEW > Select a queue > Call Recording Options. If the value is either "recording_permission_not_asked" (default) or "recording_permission_denied", the call will not be recorded. If the value is "recording_permission_granted", the call will be recorded. | {{recording_permission}} |
Endpoint:
Method: POST
Type: RAW
URL: https://{{subdomain}}.{{domain}}/apps/api/v1/calls
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Body:
{
"call_type": "Voice Inbound (API)",
"lang": "en",
"menu_id": 9,
"ticket_id": "76517",
"end_user_number": "+1 859-657-9625",
"recording_permission": "recording_permission_granted"
}
More example Requests/Responses:
I. Example Request: Error : end_user_number is not well formed
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Body:
{
"call_type": "Voice Inbound (API)",
"lang": "en",
"menu_id": 9,
"end_user_number": "+1 999-657-12",
"recording_permission": "recording_permission_granted"
}
I. Example Response: Error : end_user_number is not well formed
{
"message": "end_user_number is not well formed"
}
Status Code: 400
II. Example Request: Error : Menu is in 'manual redirection' state, can't accept calls
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Body:
{
"call_type": "Voice Inbound (API)",
"lang": "en",
"menu_id": 9,
"end_user_number": "+1 859-657-9625",
"recording_permission": "recording_permission_granted"
}
II. Example Response: Error : Menu is in 'manual redirection' state, can't accept calls
{
"message": "Menu is in 'manual redirection' state, can't accept calls"
}
Status Code: 400
III. Example Request: Error : Invalid call type
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Body:
{
"call_type": "InvalidCallType",
"lang": "en",
"menu_id": 9,
"end_user_number": "+1 859-657-9625",
"recording_permission": "recording_permission_granted"
}
III. Example Response: Error : Invalid call type
{
"message": "Invalid call type"
}
Status Code: 400
IV. Example Request: Error : menu_id is required
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Body:
{
"call_type": "Voice Inbound (API)",
"lang": "en",
"end_user_number": "+1 859-657-9625",
"recording_permission": "recording_permission_granted"
}
IV. Example Response: Error : menu_id is required
{
"message": "menu_id is required"
}
Status Code: 400
V. Example Request: Error : Only IVR and web menu IDs are permitted
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Body:
{
"call_type": "Voice Inbound (API)",
"lang": "en",
"menu_id": 50,
"end_user_number": "+1 859-657-9625",
"recording_permission": "recording_permission_granted"
}
V. Example Response: Error : Only IVR and web menu IDs are permitted
{
"message": "Only IVR and web menu IDs are permitted"
}
Status Code: 400
VI. Example Request: Create an incoming call with end_user_number
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Body:
{
"call_type": "Voice Inbound (API)",
"lang": "en",
"menu_id": 9,
"end_user_number": "+82-10-6861-2345",
"recording_permission": "recording_permission_granted"
}
VI. Example Response: Create an incoming call with end_user_number
{
"id": 515,
"lang": "en",
"call_type": "Voice Inbound (API)",
"status": "queued",
"created_at": "2019-09-10T00:19:14.000Z",
"queued_at": "2019-09-10T00:19:14.421Z",
"assigned_at": null,
"connected_at": null,
"ends_at": null,
"scheduled_at": null,
"wait_duration": 0,
"call_duration": 0,
"hold_duration": 0,
"rating": null,
"has_feedback": false,
"out_ticket_id": null,
"out_ticket_url": null,
"verified": false,
"recording_url": null,
"recording_permission": "not_asked",
"voicemail_reason": "not_voicemail",
"deflection": "no_deflection",
"disconnected_by": "disconnected_by_unknown",
"fail_reason": "nothing",
"fail_details": null,
"support_number": null,
"selected_menu": {
"id": 9,
"name": "Lock Star",
"parent_id": null,
"position": 0,
"deleted": false,
"menu_type": "ivr_menu",
"output_msg": "You selected Lock Star.",
"hidden": false
},
"menu_path": {
"items_count": 1,
"name": "Lock Star",
"materialized_path": "9"
},
"agent_info": null,
"end_user": {
"id": 75,
"identifier": null,
"out_contact_id": "389391400633"
},
"photos": [],
"videos": [],
"transfers": [],
"deflection_details": [],
"participants": [
{
"id": 820,
"type": "end_user",
"status": "waiting",
"call_id": 515,
"user_id": null,
"end_user_id": 75,
"call_duration": null,
"hold_duration": null,
"connected_at": null,
"ended_at": null,
"fail_reason": "nothing"
}
],
"offer_type": "cascade",
"offer_events": [
{
"casting_time": "2019-09-10T00:19:14.000Z",
"group": "Group 1"
}
],
"answer_type": "manual",
"outbound_number": "+1 339-219-5276"
}
Status Code: 201
VII. Example Request: Error : Menu is in 'after hours' state, can't accept incoming calls
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Body:
{
"call_type": "Voice Inbound (API)",
"lang": "en",
"menu_id": 9,
"end_user_number": "+1 859-657-9625",
"recording_permission": "recording_permission_granted"
}
VII. Example Response: Error : Menu is in 'after hours' state, can't accept incoming calls
{
"message": "Menu is in 'after hours' state, can't accept incoming calls"
}
Status Code: 400
VIII. Example Request: Error : Language is not available
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Body:
{
"call_type": "Voice Inbound (API)",
"lang": "fr",
"menu_id": 9,
"end_user_number": "+1 859-657-9625",
"recording_permission": "recording_permission_granted"
}
VIII. Example Response: Error : Language is not available
{
"message": "Language 'fr' is not available"
}
Status Code: 400
IX. Example Request: Create an incoming call with ticket_id
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Body:
{
"call_type": "Voice Inbound (API)",
"lang": "en",
"menu_id": 9,
"ticket_id": "76517",
"end_user_number": "+1 859-657-9625",
"recording_permission": "recording_permission_granted"
}
IX. Example Response: Create an incoming call with ticket_id
{
"id": 519,
"lang": "en",
"call_type": "Voice Inbound (API)",
"status": "queued",
"created_at": "2019-09-10T05:12:26.000Z",
"queued_at": "2019-09-10T05:12:26.295Z",
"assigned_at": null,
"connected_at": null,
"ends_at": null,
"scheduled_at": null,
"wait_duration": 0,
"call_duration": 0,
"hold_duration": 0,
"rating": null,
"has_feedback": false,
"out_ticket_id": "76517",
"out_ticket_url": null,
"verified": false,
"recording_url": null,
"recording_permission": "not_asked",
"voicemail_reason": "not_voicemail",
"deflection": "no_deflection",
"disconnected_by": "disconnected_by_unknown",
"fail_reason": "nothing",
"fail_details": null,
"support_number": null,
"selected_menu": {
"id": 9,
"name": "Lock Star",
"parent_id": null,
"position": 0,
"deleted": false,
"menu_type": "ivr_menu",
"output_msg": "You selected Lock Star.",
"hidden": false
},
"menu_path": {
"items_count": 1,
"name": "Lock Star",
"materialized_path": "9"
},
"agent_info": null,
"end_user": {
"id": 75,
"identifier": null,
"out_contact_id": "389391400633"
},
"photos": [],
"videos": [],
"transfers": [],
"deflection_details": [],
"participants": [
{
"id": 826,
"type": "end_user",
"status": "waiting",
"call_id": 519,
"user_id": null,
"end_user_id": 75,
"call_duration": null,
"hold_duration": null,
"connected_at": null,
"ended_at": null,
"fail_reason": "nothing"
}
],
"offer_type": "cascade",
"offer_events": [
{
"casting_time": "2019-09-10T05:12:26.000Z",
"group": "Group 1"
}
],
"answer_type": "manual",
"outbound_number": "+1 339-219-5276"
}
Status Code: 201
X. Example Request: Error : Language is not found
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Body:
{
"call_type": "Voice Inbound (API)",
"lang": "xy",
"menu_id": 9,
"end_user_number": "+1 859-657-9625",
"recording_permission": "recording_permission_granted"
}
X. Example Response: Error : Language is not found
{
"message": "Language 'xy' is not found"
}
Status Code: 400
XI. Example Request: Error : menu_id is not found
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Body:
{
"call_type": "Voice Inbound (API)",
"lang": "en",
"menu_id": 9999,
"end_user_number": "+1 859-657-9625",
"recording_permission": "recording_permission_granted"
}
XI. Example Response: Error : menu_id is not found
{
"message": "menu_id 9999 is not found"
}
Status Code: 400
XII. Example Request: Error : menu_id is not well formed
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Body:
{
"call_type": "Voice Inbound (API)",
"lang": "en",
"menu_id": "menu_999",
"end_user_number": "+1 859-657-9625",
"recording_permission": "recording_permission_granted"
}
XII. Example Response: Error : menu_id is not well formed
{
"message": "menu_id is not well formed"
}
Status Code: 400
XIII. Example Request: Error : end_user_number is required
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Body:
{
"call_type": "Voice Inbound (API)",
"lang": "en",
"menu_id": 9,
"recording_permission": "recording_permission_granted"
}
XIII. Example Response: Error : end_user_number is required
{
"message": "end_user_number is required"
}
Status Code: 400
4. Scheduled Call
| Parameter | Required | Data Type | Definition | Postman Variable |
|---|---|---|---|---|
| call_type | TRUE | String | Call type to create. Use "Voice Scheduled (API)" or "ScheduledCall" (deprecated) to create an scheduled call. | Voice Scheduled (API) |
| menu_id | TRUE | Integer | The ID of the menu to attribute the call to. Only Mobile and Web menu IDs are accepted. | {{menu_id}} |
| call_id | FALSE | Integer | Call ID of previous call, which will be linked as the parent call of the new created scheduled call. When call ID is being used, menu_id can be optional. | {{call_id}} |
| end_user_number | TRUE | String | The end user phone number that will be dialed. If both a ticket_id and end_user_number are passed in, the ticket_id will take precedence. | {{end_user_number}} |
| lang | FALSE | String | Language of the call. Uses ISO 639-1 codes. (Default: "en") | {{lang}} |
| ticket_id | FALSE | String | CRM ticket ID. The end user phone number tied to the ticket will be dialed. If both a ticket_id and end_user_number are passed in, the ticket_id will take precedence. | {{ticket_id}} |
| scheduled_at | TRUE | String | Scheduled time of the call. Uses ISO 8601 format to a valid future time. | {{scheduled_at}} |
| recording_permission | FALSE | String | The value is only evaluated if the "Call Recording Options" feature is set to "Ask User for Permission to Record". Configurable at Settings > Queue > EDIT / VIEW > Select a queue > Call Recording Options. If the value is either "recording_permission_not_asked" (default) or "recording_permission_denied", the call will not be recorded. If the value is "recording_permission_granted", the call will be recorded. | {{recording_permission}} |
Endpoint:
Method: POST
Type: RAW
URL: https://{{subdomain}}.{{domain}}/apps/api/v1/calls
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Body:
{
"call_type": "Voice Scheduled (API)",
"lang": "en",
"menu_id": 9,
"ticket_id": "76517",
"end_user_number": "+1 859-657-9625",
"scheduled_at": "2019-09-15T00:19:14.421Z",
"recording_permission": "recording_permission_granted"
}
More example Requests/Responses:
I. Example Request: Error : end_user_number is not well formed
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Body:
{
"call_type": "Voice Scheduled (API)",
"lang": "en",
"menu_id": 9,
"end_user_number": "+1 999-657-12",
"scheduled_at": "2019-09-15T00:19:14.421Z",
"recording_permission": "recording_permission_granted"
}
I. Example Response: Error : end_user_number is not well formed
{
"message": "end_user_number is not well formed"
}
Status Code: 400
II. Example Request: Error : Menu is in 'manual redirection' state, can't accept calls
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Body:
{
"call_type": "Voice Scheduled (API)",
"lang": "en",
"menu_id": 9,
"end_user_number": "+1 859-657-9625",
"scheduled_at": "2019-09-15T00:19:14.421Z",
"recording_permission": "recording_permission_granted"
}
II. Example Response: Error : Menu is in 'manual redirection' state, can't accept calls
{
"message": "Menu is in 'manual redirection' state, can't accept calls"
}
Status Code: 400
III. Example Request: Error : Invalid call type
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Body:
{
"call_type": "InvalidCallType",
"lang": "en",
"menu_id": 9,
"end_user_number": "+1 859-657-9625",
"scheduled_at": "2019-09-15T00:19:14.421Z",
"recording_permission": "recording_permission_granted"
}
III. Example Response: Error : Invalid call type
{
"message": "Invalid call type"
}
Status Code: 400
IV. Example Request: Error : menu_id is required
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Body:
{
"call_type": "Voice Scheduled (API)",
"lang": "en",
"end_user_number": "+1 859-657-9625",
"scheduled_at": "2019-09-15T00:19:14.421Z",
"recording_permission": "recording_permission_granted"
}
IV. Example Response: Error : menu_id is required
{
"message": "menu_id is required"
}
Status Code: 400
V. Example Request: Error : Only mobile and web menu IDs are permitted
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Body:
{
"call_type": "Voice Scheduled (API)",
"lang": "en",
"menu_id": 50,
"end_user_number": "+1 859-657-9625",
"scheduled_at": "2019-09-15T00:19:14.421Z",
"recording_permission": "recording_permission_granted"
}
V. Example Response: Error : Only mobile and web menu IDs are permitted
{
"message": "Only mobile and web menu IDs are permitted"
}
Status Code: 400
VI. Example Request: Create an scheduled call with menu id
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Body:
{
"call_type": "Voice Scheduled (API)",
"lang": "en",
"menu_id": 9,
"end_user_number": "+82-10-6861-2345",
"scheduled_at": "2019-09-15T00:19:14.421Z",
"recording_permission": "recording_permission_granted"
}
VI. Example Response: Create an scheduled call with menu id
{
"id": 515,
"lang": "en",
"call_type": "Voice Inbound (API)",
"status": "queued",
"created_at": "2019-09-10T00:19:14.000Z",
"queued_at": null,
"assigned_at": null,
"connected_at": null,
"ends_at": null,
"scheduled_at": "2019-09-15T00:19:14.421Z",
"wait_duration": 0,
"call_duration": 0,
"hold_duration": 0,
"rating": null,
"has_feedback": false,
"out_ticket_id": null,
"out_ticket_url": null,
"verified": false,
"recording_url": null,
"recording_permission": "not_asked",
"voicemail_reason": "not_voicemail",
"deflection": "no_deflection",
"disconnected_by": "disconnected_by_unknown",
"fail_reason": "nothing",
"fail_details": null,
"support_number": null,
"selected_menu": {
"id": 9,
"name": "Lock Star",
"parent_id": null,
"position": 0,
"deleted": false,
"menu_type": "ivr_menu",
"output_msg": "You selected Lock Star.",
"hidden": false
},
"menu_path": {
"items_count": 1,
"name": "Lock Star",
"materialized_path": "9"
},
"agent_info": null,
"end_user": {
"id": 75,
"identifier": null,
"out_contact_id": "389391400633"
},
"photos": [],
"videos": [],
"transfers": [],
"deflection_details": [],
"participants": [
{
"id": 820,
"type": "end_user",
"status": "waiting",
"call_id": 515,
"user_id": null,
"end_user_id": 75,
"call_duration": null,
"hold_duration": null,
"connected_at": null,
"ended_at": null,
"fail_reason": "nothing"
}
],
"offer_type": "cascade",
"offer_events": [
{
"casting_time": "2019-09-10T00:19:14.000Z",
"group": "Group 1"
}
],
"answer_type": "manual",
"outbound_number": "+1 339-219-5276"
}
Status Code: 201
VII. Example Request: Create an scheduled call with call id
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Body:
{
"call_type": "Voice Scheduled (API)",
"lang": "en",
"call_id": 514,
"end_user_number": "+82-10-6861-2345",
"scheduled_at": "2019-09-15T00:19:14.421Z",
"recording_permission": "recording_permission_granted"
}
VII. Example Response: Create an scheduled call with call id
{
"id": 515,
"lang": "en",
"call_type": "Voice Inbound (API)",
"status": "queued",
"created_at": "2019-09-10T00:19:14.000Z",
"queued_at": null,
"assigned_at": null,
"connected_at": null,
"ends_at": null,
"scheduled_at": "2019-09-15T00:19:14.421Z",
"wait_duration": 0,
"call_duration": 0,
"hold_duration": 0,
"rating": null,
"has_feedback": false,
"out_ticket_id": null,
"out_ticket_url": null,
"verified": false,
"recording_url": null,
"recording_permission": "not_asked",
"voicemail_reason": "not_voicemail",
"deflection": "no_deflection",
"disconnected_by": "disconnected_by_unknown",
"fail_reason": "nothing",
"fail_details": null,
"support_number": null,
"selected_menu": {
"id": 9,
"name": "Lock Star",
"parent_id": null,
"position": 0,
"deleted": false,
"menu_type": "ivr_menu",
"output_msg": "You selected Lock Star.",
"hidden": false
},
"menu_path": {
"items_count": 1,
"name": "Lock Star",
"materialized_path": "9"
},
"agent_info": null,
"end_user": {
"id": 75,
"identifier": null,
"out_contact_id": "389391400633"
},
"photos": [],
"videos": [],
"transfers": [],
"deflection_details": [],
"participants": [
{
"id": 820,
"type": "end_user",
"status": "waiting",
"call_id": 515,
"user_id": null,
"end_user_id": 75,
"call_duration": null,
"hold_duration": null,
"connected_at": null,
"ended_at": null,
"fail_reason": "nothing"
}
],
"offer_type": "cascade",
"offer_events": [
{
"casting_time": "2019-09-10T00:19:14.000Z",
"group": "Group 1"
}
],
"answer_type": "manual",
"outbound_number": "+1 339-219-5276"
}
Status Code: 201
VIII. Example Request: Error : Menu is in 'after hours' state, can't accept incoming calls
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Body:
{
"call_type": "Voice Scheduled (API)",
"lang": "en",
"menu_id": 9,
"end_user_number": "+1 859-657-9625",
"scheduled_at": "2019-09-15T00:19:14.421Z",
"recording_permission": "recording_permission_granted"
}
VIII. Example Response: Error : Menu is in 'after hours' state, can't accept incoming calls
{
"message": "Menu is in 'after hours' state, can't accept incoming calls"
}
Status Code: 400
IX. Example Request: Error : Language is not available
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Body:
{
"call_type": "Voice Scheduled (API)",
"lang": "fr",
"menu_id": 9,
"end_user_number": "+1 859-657-9625",
"scheduled_at": "2019-09-15T00:19:14.421Z",
"recording_permission": "recording_permission_granted"
}
IX. Example Response: Error : Language is not available
{
"message": "Language 'fr' is not available"
}
Status Code: 400
X. Example Request: Error : Language is not found
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Body:
{
"call_type": "Voice Scheduled (API)",
"lang": "xy",
"menu_id": 9,
"end_user_number": "+1 859-657-9625",
"scheduled_at": "2019-09-15T00:19:14.421Z",
"recording_permission": "recording_permission_granted"
}
X. Example Response: Error : Language is not found
{
"message": "Language 'xy' is not found"
}
Status Code: 400
XI. Example Request: Error : menu_id is not found
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Body:
{
"call_type": "Voice Scheduled (API)",
"lang": "en",
"menu_id": 9999,
"end_user_number": "+1 859-657-9625",
"scheduled_at": "2019-09-15T00:19:14.421Z",
"recording_permission": "recording_permission_granted"
}
XI. Example Response: Error : menu_id is not found
{
"message": "menu_id 9999 is not found"
}
Status Code: 400
XII. Example Request: Error : menu_id is not well formed
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Body:
{
"call_type": "Voice Scheduled (API)",
"lang": "en",
"menu_id": "menu_999",
"end_user_number": "+1 859-657-9625",
"scheduled_at": "2019-09-15T00:19:14.421Z",
"recording_permission": "recording_permission_granted"
}
XII. Example Response: Error : menu_id is not well formed
{
"message": "menu_id is not well formed"
}
Status Code: 400
XIII. Example Request: Error : end_user_number is required
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Body:
{
"call_type": "Voice Scheduled (API)",
"lang": "en",
"menu_id": 9,
"scheduled_at": "2019-09-15T00:19:14.421Z",
"recording_permission": "recording_permission_granted"
}
XIII. Example Response: Error : end_user_number is required
{
"message": "end_user_number is required"
}
Status Code: 400
XIV. Example Request: Error : scheduled_at is required
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Body:
{
"call_type": "Voice Scheduled (API)",
"lang": "en",
"menu_id": 9,
"end_user_number": "+1 859-657-9625",
"recording_permission": "recording_permission_granted"
}
XIV. Example Response: Error : scheduled_at is required
{
"message": "scheduled_at is required"
}
Status Code: 400
SMS
1. Outbound SMS
| Parameter | Required | Data Type | Definition | Postman Variable |
|---|---|---|---|---|
| chat_type | TRUE | String | Chat type to create. "Messaging (API)", "SMS" (deprecated) are available for now | Messaging (API) |
| end_user_number | TRUE | String | Number the text message is to be sent to | {{end_user_number}} |
| outbound_number | TRUE | String | Outbound phone number to be used for sending the SMS message | {{outbound_number}} |
| message | TRUE | String | SMS message to be sent to consumer | {{message}} |
| ticket_id | FALSE | String | CRM ticket ID that will be associated with session | {{ticket_id}} |
Endpoint:
Method: POST
Type: RAW
URL: https://{{subdomain}}.{{domain}}/apps/api/v1/sms
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Body:
{
"chat_type": "Messaging (SMS)",
"end_user_number": "+1 415-555-0100",
"outbound_number": "+1 628-555-0199",
"message": "lorem ipsum",
"ticket_id": "5006x00000XXxxxXXX"
}
More example Requests/Responses:
I. Example Request: Create an outbound SMS chat with ticket_id
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Body:
{
"chat_type": "Messaging (SMS)",
"end_user_number": "+1 415-555-0100",
"outbound_number": "+1 628-555-0199",
"message": "lorem ipsum",
"ticket_id": "5006x00000XXxxxXXX"
}
I. Example Response: Create an outbound SMS chat with ticket_id
{
"id": 114,
"lang": "en",
"chat_type": "Messaging (SMS)",
"status": "selecting",
"created_at": "2021-10-04T17:20:51.000Z",
"queued_at": null,
"assigned_at": null,
"ends_at": null,
"wait_duration": 0,
"chat_duration": 0,
"rating": null,
"has_feedback": false,
"out_ticket_id": null,
"out_ticket_url": null,
"verified": false,
"disconnected_by": "disconnected_by_unknown",
"fail_reason": null,
"selected_menu": null,
"menu_path": null,
"agent_info": null,
"end_user": {
"id": 87,
"identifier": null,
"out_contact_id": null
},
"photos": [],
"videos": [],
"transfers": [],
"participants": [
{
"id": 205,
"type": "end_user",
"status": "connected",
"chat_id": 114,
"user_id": null,
"end_user_id": 87,
"chat_duration": null,
"connected_at": "2021-10-04T17:20:51.000Z",
"ended_at": null,
"fail_reason": "nothing"
}
],
"offer_type": null,
"offer_events": [],
"answer_type": "manual",
"outbound_number": "+16285550199"
}
Status Code: 200
II. Example Request: Create an outbound SMS chat without ticket_id
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Body:
{
"chat_type": "Messaging (SMS)",
"end_user_number": "+1 415-555-0100",
"outbound_number": "+1 628-555-0199",
"message": "lorem ipsum",
"ticket_id": "5006x00000XXxxxXXX"
}
II. Example Response: Create an outbound SMS chat without ticket_id
{
"id": 114,
"lang": "en",
"chat_type": "Messaging (SMS)",
"status": "selecting",
"created_at": "2021-10-04T17:20:51.000Z",
"queued_at": null,
"assigned_at": null,
"ends_at": null,
"wait_duration": 0,
"chat_duration": 0,
"rating": null,
"has_feedback": false,
"out_ticket_id": null,
"out_ticket_url": null,
"verified": false,
"disconnected_by": "disconnected_by_unknown",
"fail_reason": null,
"selected_menu": null,
"menu_path": null,
"agent_info": null,
"end_user": {
"id": 87,
"identifier": null,
"out_contact_id": null
},
"photos": [],
"videos": [],
"transfers": [],
"participants": [
{
"id": 205,
"type": "end_user",
"status": "connected",
"chat_id": 114,
"user_id": null,
"end_user_id": 87,
"chat_duration": null,
"connected_at": "2021-10-04T17:20:51.000Z",
"ended_at": null,
"fail_reason": "nothing"
}
],
"offer_type": null,
"offer_events": [],
"answer_type": "manual",
"outbound_number": "+16285550199"
}
Status Code: 200
III. Example Request: Error : chat_type needs to be provided
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Body:
{
"end_user_number": "+1 415-555-0100",
"outbound_number": "+1 628-555-0199",
"message": "lorem ipsum",
"ticket_id": "5006x00000XXxxxXXX"
}
III. Example Response: Error : chat_type needs to be provided
{
"message": "chat_type needs to be provided"
}
Status Code: 400
IV. Example Request: Error : valid chat type needs to be provided
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Body:
{
"chat_type": "In-app",
"end_user_number": "+1 415-555-0100",
"outbound_number": "+1 628-555-0199",
"message": "lorem ipsum",
"ticket_id": "5006x00000XXxxxXXX"
}
IV. Example Response: Error : valid chat type needs to be provided
{
"message": "valid chat type needs to be provided"
}
Status Code: 400
V. Example Request: Error : SMS is not enabled
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Body:
{
"chat_type": "Messaging (SMS)",
"end_user_number": "+1 415-555-0100",
"outbound_number": "+1 628-555-0199",
"message": "lorem ipsum",
"ticket_id": "5006x00000XXxxxXXX"
}
V. Example Response: Error : SMS is not enabled
{
"message": "SMS is not enabled"
}
Status Code: 400
VI. Example Request: Error : Outbound SMS is not enabled
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Body:
{
"chat_type": "Messaging (SMS)",
"end_user_number": "+1 415-555-0100",
"outbound_number": "+1 628-555-0199",
"message": "lorem ipsum",
"ticket_id": "5006x00000XXxxxXXX"
}
VI. Example Response: Error : Outbound SMS is not enabled
{
"message": "Outbound SMS is not enabled"
}
Status Code: 400
VII. Example Request: Error : end_user_number is required
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Body:
{
"chat_type": "Messaging (SMS)",
"outbound_number": "+1 628-555-0199",
"message": "lorem ipsum",
"ticket_id": "5006x00000XXxxxXXX"
}
VII. Example Response: Error : end_user_number is required
{
"message": "end_user_number is required"
}
Status Code: 400
VIII. Example Request: Error : end_user_number is invalid
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Body:
{
"chat_type": "Messaging (SMS)",
"end_user_number": "12345",
"outbound_number": "+1 628-555-0199",
"message": "lorem ipsum",
"ticket_id": "5006x00000XXxxxXXX"
}
VIII. Example Response: Error : end_user_number is invalid
{
"message": "end_user_number is invalid"
}
Status Code: 400
IX. Example Request: Error : Non-US phone number not allowed
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Body:
{
"chat_type": "Messaging (SMS)",
"end_user_number": "+1 415-555-0100",
"outbound_number": "+82 000-000-0000",
"message": "lorem ipsum",
"ticket_id": "5006x00000XXxxxXXX"
}
IX. Example Response: Error : Non-US phone number not allowed
{
"message": "Non-US phone number not allowed"
}
Status Code: 400
X. Example Request: Error : outbound_number is required
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Body:
{
"chat_type": "Messaging (SMS)",
"end_user_number": "+1 415-555-0100",
"message": "lorem ipsum",
"ticket_id": "5006x00000XXxxxXXX"
}
X. Example Response: Error : outbound_number is required
{
"message": "outbound_number is required"
}
Status Code: 400
XI. Example Request: Error : outbound_number is invalid
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Body:
{
"chat_type": "Messaging (SMS)",
"end_user_number": "+1 415-555-0100",
"outbound_number": "12345",
"message": "lorem ipsum",
"ticket_id": "5006x00000XXxxxXXX"
}
XI. Example Response: Error : outbound_number is invalid
{
"message": "outbound_number is invalid"
}
Status Code: 400
XII. Example Request: Error : outbound_number is not found
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Body:
{
"chat_type": "Messaging (SMS)",
"end_user_number": "+1 415-555-0100",
"outbound_number": "+1 628-555-0199",
"message": "lorem ipsum",
"ticket_id": "5006x00000XXxxxXXX"
}
XII. Example Response: Error : outbound_number is not found
{
"message": "outbound_number is not found"
}
Status Code: 400
XIII. Example Request: Error : message is required
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Body:
{
"chat_type": "Messaging (SMS)",
"end_user_number": "+1 415-555-0100",
"outbound_number": "+1 628-555-0199",
"message": "",
"ticket_id": "5006x00000XXxxxXXX"
}
XIII. Example Response: Error : message is required
{
"message": "message is required"
}
Status Code: 400
XIV. Example Request: Error : Outbound SMS failed. Consumer is already in an active SMS session.
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Body:
{
"chat_type": "Messaging (SMS)",
"end_user_number": "+1 415-555-0100",
"outbound_number": "+1 628-555-0199",
"message": "lorem ipsum",
"ticket_id": "5006x00000XXxxxXXX"
}
XIV. Example Response: Error : Outbound SMS failed. Consumer is already in an active SMS session.
{
"message": "Outbound SMS failed. Consumer is already in an active SMS session."
}
Status Code: 400
Wait Times
1. Wait Times
| Parameter | Required | Data Type | Definition | Postman Variable |
|---|---|---|---|---|
| lang | TRUE | String | Language code of the queue. (e.g. 'en') | {{lang}} |
| menu_id | FALSE | Integer | Response will filter all menus in that menu's subtree, including that menu. | {{menu_id}} |
| menu_type | FALSE | String | Returns menus of specific types. Possible values: ivr_menu, mobile_menu, web_menu). | {{menu_type}} |
| channel_type | FALSE | String | Returns menus of a specific channel. Possible values: voice_call, chat). | {{channel_type}} |
| wait[from] | FALSE | Integer | Returns records if they have a wait greater than the value. | {{wait[from]}} |
| wait[to] | FALSE | Integer | Returns records if they have a wait less than the value. | {{wait[to]}} |
Endpoint:
Method: GET
Type:
URL: https://{{subdomain}}.{{domain}}/apps/api/v1/wait_times
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
More example Requests/Responses:
I. Example Request: Wait Times for Mobile queues
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Query:
| Key | Value | Description |
|---|---|---|
| lang | en | |
| menu_type | mobile_menu |
Body: None
I. Example Response: Wait Times for Mobile queues
[
{
"menu_id": 29,
"menu_type": "mobile_menu",
"chat": 10,
"voice_call": 10,
"materialized_path": "Laptop"
},
{
"menu_id": 42,
"menu_type": "mobile_menu",
"chat": 10,
"voice_call": 10,
"materialized_path": "Desktop"
},
{
"menu_id": 43,
"menu_type": "mobile_menu",
"chat": 10,
"voice_call": 10,
"materialized_path": "Smart Phone"
}
]
Status Code: 200
II. Example Request: Wait Times between wait[from] to wait[to]
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Query:
| Key | Value | Description |
|---|---|---|
| lang | en | |
| wait[from] | 5 | |
| wait[to] | 15 |
Body: None
II. Example Response: Wait Times between wait[from] to wait[to]
[
{
"menu_id": 3,
"menu_type": "web_menu",
"chat": 10,
"voice_call": 10,
"materialized_path": "Web App"
},
{
"menu_id": 29,
"menu_type": "mobile_menu",
"chat": 10,
"voice_call": 10,
"materialized_path": "Laptop"
},
{
"menu_id": 42,
"menu_type": "mobile_menu",
"chat": 10,
"voice_call": 10,
"materialized_path": "Desktop"
},
{
"menu_id": 44,
"menu_type": "web_menu",
"chat": 10,
"voice_call": 10,
"materialized_path": "Mobile App"
},
{
"menu_id": 43,
"menu_type": "mobile_menu",
"chat": 10,
"voice_call": 10,
"materialized_path": "Smart Phone"
}
]
Status Code: 200
III. Example Request: Wait Times of the voice call for Mobile queues greater than 5 seconds
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Query:
| Key | Value | Description |
|---|---|---|
| lang | en | |
| menu_type | mobile_menu | |
| channel_type | voice_call | |
| wait[from] | 5 |
Body: None
III. Example Response: Wait Times of the voice call for Mobile queues greater than 5 seconds
[
{
"menu_id": 29,
"menu_type": "mobile_menu",
"voice_call": 10,
"materialized_path": "Laptop"
},
{
"menu_id": 42,
"menu_type": "mobile_menu",
"voice_call": 10,
"materialized_path": "Desktop"
},
{
"menu_id": 43,
"menu_type": "mobile_menu",
"voice_call": 10,
"materialized_path": "Smart Phone"
}
]
Status Code: 200
IV. Example Request: Wait Times for a specific menu
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Query:
| Key | Value | Description |
|---|---|---|
| lang | en | |
| menu_id | 9 |
Body: None
IV. Example Response: Wait Times for a specific menu
[
{
"menu_id": 9,
"menu_type": "ivr_menu",
"voice_call": 10,
"materialized_path": "Death Star"
}
]
Status Code: 200
V. Example Request: Wait Times for all voice calls
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Query:
| Key | Value | Description |
|---|---|---|
| lang | en | |
| channel_type | voice_call |
Body: None
V. Example Response: Wait Times for all voice calls
[
{
"menu_id": 3,
"menu_type": "web_menu",
"voice_call": 10,
"materialized_path": "Web App"
},
{
"menu_id": 9,
"menu_type": "ivr_menu",
"voice_call": 10,
"materialized_path": "Death Star"
},
{
"menu_id": 29,
"menu_type": "mobile_menu",
"voice_call": 10,
"materialized_path": "Laptop"
},
{
"menu_id": 41,
"menu_type": "ivr_menu",
"voice_call": 10,
"materialized_path": "Lock Star"
},
{
"menu_id": 42,
"menu_type": "mobile_menu",
"voice_call": 10,
"materialized_path": "Desktop"
},
{
"menu_id": 44,
"menu_type": "web_menu",
"voice_call": 10,
"materialized_path": "Mobile App"
},
{
"menu_id": 43,
"menu_type": "mobile_menu",
"voice_call": 10,
"materialized_path": "Smart Phone"
}
]
Status Code: 200
VI. Example Request: Wait Times for English queues
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Query:
| Key | Value | Description |
|---|---|---|
| lang | en |
Body: None
VI. Example Response: Wait Times for English queues
[
{
"menu_id": 3,
"menu_type": "web_menu",
"chat": 10,
"voice_call": 10,
"materialized_path": "Web App"
},
{
"menu_id": 9,
"menu_type": "ivr_menu",
"voice_call": 10,
"materialized_path": "Death Star"
},
{
"menu_id": 29,
"menu_type": "mobile_menu",
"chat": 10,
"voice_call": 10,
"materialized_path": "Laptop"
},
{
"menu_id": 41,
"menu_type": "ivr_menu",
"voice_call": 10,
"materialized_path": "Lock Star"
},
{
"menu_id": 42,
"menu_type": "mobile_menu",
"chat": 10,
"voice_call": 10,
"materialized_path": "Desktop"
},
{
"menu_id": 44,
"menu_type": "web_menu",
"chat": 10,
"voice_call": 10,
"materialized_path": "Mobile App"
},
{
"menu_id": 43,
"menu_type": "mobile_menu",
"chat": 10,
"voice_call": 10,
"materialized_path": "Smart Phone"
}
]
Status Code: 200
2. crm/contact_data
| Parameter | Required | Data Type | Definition | Postman Variable |
|---|---|---|---|---|
| lang | TRUE | String | Language code of the queue. (e.g. 'en') | {{lang}} |
| menu_id | FALSE | Integer | Response will filter all menus in that menu's subtree, including that menu. | {{menu_id}} |
| menu_type | FALSE | String | Returns menus of specific types. Possible values: ivr_menu, mobile_menu, web_menu). | {{menu_type}} |
| channel_type | FALSE | String | Returns menus of a specific channel. Possible values: voice_call, chat). | {{channel_type}} |
| wait[from] | FALSE | Integer | Returns records if they have a wait greater than the value. | {{wait[from]}} |
| wait[to] | FALSE | Integer | Returns records if they have a wait less than the value. | {{wait[to]}} |
Endpoint:
Method: POST
Type: RAW
URL: https://{{subdomain}}.{{domain}}/apps/api/v1/crm/contact_data
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Body:
{
"call_id" : "1917",
"agent_id" : "1",
"lcm_key" : "2922|1|2|39|2|0|1",
"dnis" : "8001992999",
"org_id" : "tenant1",
"contact" : {
"first_name" : "Alex",
"last_name" : "Phil",
"account_no" : "10002-2989",
"crm_id" : "220-39307-92",
"address" : "",
"city" : "",
"loan_type" : "",
"due_date" : ""
},
"pacing_mode" : "Predictive",
"call_type" : "OB_Regular"
}
More example Requests/Responses:
I. Example Request: Wait Times between wait[from] to wait[to]
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Query:
| Key | Value | Description |
|---|---|---|
| lang | en | |
| wait[from] | 5 | |
| wait[to] | 15 |
Body: None
I. Example Response: Wait Times between wait[from] to wait[to]
[
{
"menu_id": 3,
"menu_type": "web_menu",
"chat": 10,
"voice_call": 10,
"materialized_path": "Web App"
},
{
"menu_id": 29,
"menu_type": "mobile_menu",
"chat": 10,
"voice_call": 10,
"materialized_path": "Laptop"
},
{
"menu_id": 42,
"menu_type": "mobile_menu",
"chat": 10,
"voice_call": 10,
"materialized_path": "Desktop"
},
{
"menu_id": 44,
"menu_type": "web_menu",
"chat": 10,
"voice_call": 10,
"materialized_path": "Mobile App"
},
{
"menu_id": 43,
"menu_type": "mobile_menu",
"chat": 10,
"voice_call": 10,
"materialized_path": "Smart Phone"
}
]
Status Code: 200
II. Example Request: Wait Times for English queues
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Query:
| Key | Value | Description |
|---|---|---|
| lang | en |
Body: None
II. Example Response: Wait Times for English queues
[
{
"menu_id": 3,
"menu_type": "web_menu",
"chat": 10,
"voice_call": 10,
"materialized_path": "Web App"
},
{
"menu_id": 9,
"menu_type": "ivr_menu",
"voice_call": 10,
"materialized_path": "Death Star"
},
{
"menu_id": 29,
"menu_type": "mobile_menu",
"chat": 10,
"voice_call": 10,
"materialized_path": "Laptop"
},
{
"menu_id": 41,
"menu_type": "ivr_menu",
"voice_call": 10,
"materialized_path": "Lock Star"
},
{
"menu_id": 42,
"menu_type": "mobile_menu",
"chat": 10,
"voice_call": 10,
"materialized_path": "Desktop"
},
{
"menu_id": 44,
"menu_type": "web_menu",
"chat": 10,
"voice_call": 10,
"materialized_path": "Mobile App"
},
{
"menu_id": 43,
"menu_type": "mobile_menu",
"chat": 10,
"voice_call": 10,
"materialized_path": "Smart Phone"
}
]
Status Code: 200
III. Example Request: Wait Times for a specific menu
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Query:
| Key | Value | Description |
|---|---|---|
| lang | en | |
| menu_id | 9 |
Body: None
III. Example Response: Wait Times for a specific menu
[
{
"menu_id": 9,
"menu_type": "ivr_menu",
"voice_call": 10,
"materialized_path": "Death Star"
}
]
Status Code: 200
IV. Example Request: Wait Times of the voice call for Mobile queues greater than 5 seconds
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Query:
| Key | Value | Description |
|---|---|---|
| lang | en | |
| menu_type | mobile_menu | |
| channel_type | voice_call | |
| wait[from] | 5 |
Body: None
IV. Example Response: Wait Times of the voice call for Mobile queues greater than 5 seconds
[
{
"menu_id": 29,
"menu_type": "mobile_menu",
"voice_call": 10,
"materialized_path": "Laptop"
},
{
"menu_id": 42,
"menu_type": "mobile_menu",
"voice_call": 10,
"materialized_path": "Desktop"
},
{
"menu_id": 43,
"menu_type": "mobile_menu",
"voice_call": 10,
"materialized_path": "Smart Phone"
}
]
Status Code: 200
V. Example Request: Wait Times for Mobile queues
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Query:
| Key | Value | Description |
|---|---|---|
| lang | en | |
| menu_type | mobile_menu |
Body: None
V. Example Response: Wait Times for Mobile queues
[
{
"menu_id": 29,
"menu_type": "mobile_menu",
"chat": 10,
"voice_call": 10,
"materialized_path": "Laptop"
},
{
"menu_id": 42,
"menu_type": "mobile_menu",
"chat": 10,
"voice_call": 10,
"materialized_path": "Desktop"
},
{
"menu_id": 43,
"menu_type": "mobile_menu",
"chat": 10,
"voice_call": 10,
"materialized_path": "Smart Phone"
}
]
Status Code: 200
VI. Example Request: Wait Times for all voice calls
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Query:
| Key | Value | Description |
|---|---|---|
| lang | en | |
| channel_type | voice_call |
Body: None
VI. Example Response: Wait Times for all voice calls
[
{
"menu_id": 3,
"menu_type": "web_menu",
"voice_call": 10,
"materialized_path": "Web App"
},
{
"menu_id": 9,
"menu_type": "ivr_menu",
"voice_call": 10,
"materialized_path": "Death Star"
},
{
"menu_id": 29,
"menu_type": "mobile_menu",
"voice_call": 10,
"materialized_path": "Laptop"
},
{
"menu_id": 41,
"menu_type": "ivr_menu",
"voice_call": 10,
"materialized_path": "Lock Star"
},
{
"menu_id": 42,
"menu_type": "mobile_menu",
"voice_call": 10,
"materialized_path": "Desktop"
},
{
"menu_id": 44,
"menu_type": "web_menu",
"voice_call": 10,
"materialized_path": "Mobile App"
},
{
"menu_id": 43,
"menu_type": "mobile_menu",
"voice_call": 10,
"materialized_path": "Smart Phone"
}
]
Status Code: 200
Bulk User Management
Create/Update a large number of users through the Bulk User Management collection.
Supports JSON files. Sample json data can be obtained through the Template API.
Only api_user authentication is supported. You must enter the api user token in the password variable. Lagacy authentication(using a company secret) is not supported.
When a JSON file is uploaded through the upload API, a job is created and validates the json file scheme.
The JSON file format is shown below and also can be checked through the GET Template API.
| Field(s) name | Values | Required | Validation |
|---|---|---|---|
| String(Email) | Yes | Must be a valid email. Must be unique within the file within Email column (no duplicates). so only 1 update per email address per file | |
| new_email | String(Email) | No | Must be a valid email. Must be unique within the file within New Email column (no duplicates). so only 1 update per email address per file |
| agent_number | String | No | A string with no validation |
| first_name | String | Yes | Non-empty string |
| last_name | String | Yes | Non-empty string |
| status | Active, Inactive, Empty | No | Must be "Active", "Inactive", or empty |
| location | A string that is a location name, Empty, Null | No | Must exactly match one of the existing locations (case-insensitive), or Null, or empty |
| max_chat_limit | 1 to X (where X is configured value), Empty | No | Must be 1 to X (inclusively), or empty |
| max_chat_limit_enabled | 0, 1, Empty | No | Must be 0, 1 or empty |
| roles | name: Role name / value: 0, 1, Empty | No | Must be 0, 1 or empty |
| teams | name: Team name / value: 0, 1, Empty | No | Must be 0, 1 or empty |
When the scheme check is successful, the Proceed API can be executed, and user creation/modification work is in progress.
Upload and Proceed are asynchronously performed by the worker, and you can check the status through the Job API with a job_id.
The status field of Job can be in any of the following states.
| Job status | Description |
|---|---|
| created | A job is created and waiting for validation. |
| valid_scheme | Scheme validation is successful and proceed is possible. |
| invalid_scheme | Scheme validation failed. Detailed information can be checked through the Scheme error log API. |
| in_progress | Performing bulk user update/create. |
| finished | Bulk user update/create complete. |
1. Template
Endpoint:
Method: GET
Type:
URL: https://{{subdomain}}.{{domain}}/apps/api/v1/bulk/users/template
More example Requests/Responses:
I. Example Request: Template
Body: None
I. Example Response: Template
[
{
"email": "user1@somedomain.com",
"new_email": "user1@somedomain.com",
"agent_number": "A-001",
"first_name": "James",
"last_name": "Bond",
"status": "Active",
"location": "Mexico",
"max_chat_limit": "2",
"max_chat_limit_enabled": "0",
"roles": [
{
"name": "Admin",
"value": 0
},
{
"name": "Manager",
"value": 0
},
{
"name": "Agent",
"value": 0
},
{
"name": "Developer",
"value": 0
},
{
"name": "Manager Admin",
"value": 0
},
{
"name": "Manager Team",
"value": 0
},
{
"name": "Manager Data",
"value": 0
}
],
"teams": [
{
"name": "test team_1",
"value": 0
},
{
"name": "test Team 2",
"value": 0
},
{
"name": "test team 3",
"value": 0
}
]
},
{
"email": "user2@somedomain.com",
"new_email": "user3@somedomain.com",
"agent_number": "A-002",
"first_name": "John",
"last_name": "Doe",
"status": "Inactive",
"location": "",
"max_chat_limit": "",
"max_chat_limit_enabled": "1",
"roles": [
{
"name": "Admin",
"value": 0
},
{
"name": "Manager",
"value": 0
},
{
"name": "Agent",
"value": 0
},
{
"name": "Developer",
"value": 0
},
{
"name": "Manager Admin",
"value": 0
},
{
"name": "Manager Team",
"value": 0
},
{
"name": "Manager Data",
"value": 0
}
],
"teams": [
{
"name": "test team_1",
"value": 0
},
{
"name": "test Team 2",
"value": 0
},
{
"name": "test team 3",
"value": 0
}
]
},
{
"email": "user3@somedomain.com",
"new_email": "user2@somedomain.com",
"agent_number": "A-003",
"first_name": "Jane",
"last_name": "Doe",
"status": "",
"location": "null",
"max_chat_limit": "1",
"max_chat_limit_enabled": "",
"roles": [
{
"name": "Admin",
"value": 0
},
{
"name": "Manager",
"value": 0
},
{
"name": "Agent",
"value": 0
},
{
"name": "Developer",
"value": 0
},
{
"name": "Manager Admin",
"value": 0
},
{
"name": "Manager Team",
"value": 0
},
{
"name": "Manager Data",
"value": 0
}
],
"teams": [
{
"name": "test team_1",
"value": 0
},
{
"name": "test Team 2",
"value": 0
},
{
"name": "test team 3",
"value": 0
}
]
}
]
Status Code: 200
2. Jobs
Endpoint:
Method: GET
Type:
URL: https://{{subdomain}}.{{domain}}/apps/api/v1/bulk/users/jobs/{{job_id}}
More example Requests/Responses:
I. Example Request: Job detail
Body: None
I. Example Response: Job detail
{
"id": 1,
"created_at": "2022-01-07T06:06:45.000Z",
"process_requested_at": null,
"filename": "100row.csv",
"total_rows": 100,
"affected_rows": 0,
"failed_rows": 0,
"status": "created",
"uploaded_user_name": null,
"proceed_user_name": null,
"uploaded_api_user_name": "zdco_admin",
"proceed_api_user_name": null,
"scheme_errors": [],
"update_errors": []
}
Status Code: 200
II. Example Request: Job list
Body: None
II. Example Response: Job list
[
{
"id": 3,
"created_at": "2022-01-07T06:21:10.000Z",
"process_requested_at": "2022-01-07T06:22:25.000Z",
"filename": "100row_new.csv",
"total_rows": 100,
"affected_rows": 0,
"failed_rows": 0,
"status": "in_progress",
"uploaded_user_name": null,
"proceed_user_name": null,
"uploaded_api_user_name": "zdco_admin",
"proceed_api_user_name": "zdco_admin",
"scheme_errors": [],
"update_errors": []
},
{
"id": 2,
"created_at": "2022-01-07T06:17:09.000Z",
"process_requested_at": null,
"filename": "100row.csv",
"total_rows": 100,
"affected_rows": 0,
"failed_rows": 0,
"status": "created",
"uploaded_user_name": null,
"proceed_user_name": null,
"uploaded_api_user_name": "zdco_admin",
"proceed_api_user_name": null,
"scheme_errors": [],
"update_errors": []
},
{
"id": 1,
"created_at": "2022-01-07T06:06:45.000Z",
"process_requested_at": null,
"filename": "100row.csv",
"total_rows": 100,
"affected_rows": 0,
"failed_rows": 0,
"status": "created",
"uploaded_user_name": null,
"proceed_user_name": null,
"uploaded_api_user_name": "zdco_admin",
"proceed_api_user_name": null,
"scheme_errors": [],
"update_errors": []
}
]
Status Code: 200
III. Example Request: Job created
Body: None
III. Example Response: Job created
{
"id": 1,
"created_at": "2022-01-07T06:39:59.000Z",
"process_requested_at": null,
"filename": "100row_new.csv",
"total_rows": 100,
"affected_rows": 0,
"failed_rows": 0,
"status": "created",
"uploaded_user_name": null,
"proceed_user_name": null,
"uploaded_api_user_name": "zdco_admin",
"proceed_api_user_name": null,
"scheme_errors": [],
"update_errors": []
}
Status Code: 200
IV. Example Request: Job validating success
Body: None
IV. Example Response: Job validating success
{
"id": 1,
"created_at": "2022-01-07T06:40:34.000Z",
"process_requested_at": null,
"filename": "100row_new.csv",
"total_rows": 100,
"affected_rows": 0,
"failed_rows": 0,
"status": "valid_scheme",
"uploaded_user_name": null,
"proceed_user_name": null,
"uploaded_api_user_name": "zdco_admin",
"proceed_api_user_name": null,
"scheme_errors": [],
"update_errors": []
}
Status Code: 200
V. Example Request: Job validating fails
Body: None
V. Example Response: Job validating fails
{
"id": 1,
"created_at": "2022-01-07T06:40:34.000Z",
"process_requested_at": null,
"filename": "100row_new.csv",
"total_rows": 100,
"affected_rows": 0,
"failed_rows": 0,
"status": "invalid_scheme",
"uploaded_user_name": null,
"proceed_user_name": null,
"uploaded_api_user_name": "zdco_admin",
"proceed_api_user_name": null,
"scheme_errors": [
"scheme error detail 1",
"scheme error detail 2",
"scheme error detail 3"
],
"update_errors": []
}
Status Code: 200
VI. Example Request: Job updating
Body: None
VI. Example Response: Job updating
{
"id": 1,
"created_at": "2022-01-07T06:40:34.000Z",
"process_requested_at": "2022-01-07T06:42:59.000Z",
"filename": "100row_new.csv",
"total_rows": 100,
"affected_rows": 52,
"failed_rows": 0,
"status": "in_progress",
"uploaded_user_name": null,
"proceed_user_name": null,
"uploaded_api_user_name": "zdco_admin",
"proceed_api_user_name": "zdco_admin",
"scheme_errors": [],
"update_errors": []
}
Status Code: 200
VII. Example Request: Job update finish without errors
Body: None
VII. Example Response: Job update finish without errors
{
"id": 1,
"created_at": "2022-01-07T06:40:34.000Z",
"process_requested_at": "2022-01-07T06:42:59.000Z",
"filename": "100row_new.csv",
"total_rows": 100,
"affected_rows": 100,
"failed_rows": 0,
"status": "finished",
"uploaded_user_name": null,
"proceed_user_name": null,
"uploaded_api_user_name": "zdco_admin",
"proceed_api_user_name": "zdco_admin",
"scheme_errors": [],
"update_errors": []
}
Status Code: 200
VIII. Example Request: Job update finish with errors
Body: None
VIII. Example Response: Job update finish with errors
{
"id": 1,
"created_at": "2022-01-07T06:40:34.000Z",
"process_requested_at": "2022-01-07T06:42:59.000Z",
"filename": "100row_new.csv",
"total_rows": 100,
"affected_rows": 100,
"failed_rows": 0,
"status": "finished",
"uploaded_user_name": null,
"proceed_user_name": null,
"uploaded_api_user_name": "zdco_admin",
"proceed_api_user_name": "zdco_admin",
"scheme_errors": [],
"update_errors": [
"update error detail 1",
"update error detail 2",
"update error detail 3"
]
}
Status Code: 200
IX. Example Request: Error: Invalid job_id
Body: None
IX. Example Response: Error: Invalid job_id
{
"message": "Not Found"
}
Status Code: 404
3. Upload
Endpoint:
Method: POST
Type: FORMDATA
URL: https://{{subdomain}}.{{domain}}/apps/api/v1/bulk/users/upload
Body:
| Key | Value | Description |
|---|---|---|
| file |
More example Requests/Responses:
I. Example Request: Job created
Body:
| Key | Value | Description |
|---|---|---|
| file |
I. Example Response: Job created
{
"id": 1,
"status": "created",
"link": "https://{{subdomain}}.{{domain}}/apps/api/v1/bulk/users/jobs/1"
}
Status Code: 200
4. Upload
Endpoint:
Method: PUT
Type: FORMDATA
URL: https://{{subdomain}}.{{domain}}/apps/api/v1/bulk/users/upload
Body:
| Key | Value | Description |
|---|---|---|
| id | {{job_id}} | |
| file |
More example Requests/Responses:
I. Example Request: Replace JSON file
Body:
| Key | Value | Description |
|---|---|---|
| id | {{job_id}} | |
| file |
I. Example Response: Replace JSON file
{
"id": 1,
"status": "created",
"link": "https://{{subdomain}}.{{domain}}/apps/api/v1/bulk/users/jobs/1"
}
Status Code: 200
II. Example Request: Error: Invalid job_id
Body:
| Key | Value | Description |
|---|---|---|
| id | {{job_id}} | |
| file |
II. Example Response: Error: Invalid job_id
{
"message": "Not Found"
}
Status Code: 404
III. Example Request: Error: Upload when finished
Body:
| Key | Value | Description |
|---|---|---|
| id | {{job_id}} | |
| file |
III. Example Response: Error: Upload when finished
{
"message": "Can't update JSON. job status: finished"
}
Status Code: 404
5. Proceed
Endpoint:
Method: POST
Type: FORMDATA
URL: https://{{subdomain}}.{{domain}}/apps/api/v1/bulk/users/proceed
Body:
| Key | Value | Description |
|---|---|---|
| id | {{job_id}} |
More example Requests/Responses:
I. Example Request: Proceed success
Body:
| Key | Value | Description |
|---|---|---|
| id | {{job_id}} |
I. Example Response: Proceed success
{
"id": 1,
"status": "valid_scheme",
"link": "https://{{subdomain}}.{{domain}}/apps/api/v1/bulk/users/jobs/1"
}
Status Code: 200
II. Example Request: Error: Proceed when before validation
Body:
| Key | Value | Description |
|---|---|---|
| id | {{job_id}} |
II. Example Response: Error: Proceed when before validation
{
"message": "This job cannot proceed update. status: created"
}
Status Code: 400
III. Example Request: Error: Proceed when in progress
Body:
| Key | Value | Description |
|---|---|---|
| id | {{job_id}} |
III. Example Response: Error: Proceed when in progress
{
"message": "Update is already in progress."
}
Status Code: 400
6. Scheme errors
Endpoint:
Method: GET
Type:
URL: https://{{subdomain}}.{{domain}}/apps/api/v1/bulk/users/errors/scheme/{{job_id}}
More example Requests/Responses:
I. Example Request: Scheme errors
Body: None
I. Example Response: Scheme errors
[
{
"message": "scheme error message 1",
"column": null,
"row": 1
},
{
"message": "scheme error message 2",
"column": null,
"row": 2
}
]
Status Code: 200
II. Example Request: No errors
Body: None
II. Example Response: No errors
[]
Status Code: 200
7. Update errors
Endpoint:
Method: GET
Type:
URL: https://{{subdomain}}.{{domain}}/apps/api/v1/bulk/users/errors/update/{{job_id}}
More example Requests/Responses:
I. Example Request: Update errors
Body: None
I. Example Response: Update errors
[
{
"message": "update error messsage 1",
"column": 1,
"row": 1,
"error_type": "error"
},
{
"message": "update error messsage 2",
"column": null,
"row": 2,
"error_type": "error"
},
{
"message": "update warning messsage 1",
"column": 3,
"row": 3,
"error_type": "warning"
},
{
"message": "update warning messsage 2",
"column": null,
"row": 4,
"error_type": "warning"
}
]
Status Code: 200
II. Example Request: No errors
Body: None
II. Example Response: No errors
[]
Status Code: 200
Company Do Not Call (DNC) list
The Company DNC (Do Not Call) list lets you block direct, manual outbound calls as well as outbound and scheduled calls created by the Apps API.
Add phone numbers to the DNC list
Example request:
POST URL: https://{subdomain}.{domain}/apps/api/v1/outbound_dialer/dnc
{
"contacts": [
{
"phone_number": "+1-7187309219",
"expires_at": "2022-10-29 00:00:00 UTC"
},
{
"phone_number": "+1-(358)-213-1634"
},
{
"phone_number": "+1-4151113333",
"expires_at": "2022-10-30 00:00:00 UTC"
},
{
"phone_number": "+1-4151115555"
},
{
"phone_number": "+1-7187309219",
"expires_at": "2022-10-27 00:00:00 UTC"
},
{
"phone_number": "sssssss"
},
{
"phone_number": "911",
"expires_at": "2023-02-05 00:00:00 UTC"
}
]
}
Example response:
[
{
"phone_number": "+1-7187309219",
"expires_at": "2022-10-29 00:00:00 UTC",
"status": "created"
},
{
"phone_number": "+1-(358)-213-1634",
"status": "created"
},
{
"phone_number": "+1-4151113333",
"expires_at": "2022-10-30 00:00:00 UTC",
"status": "updated"
},
{
"phone_number": "+1-4151115555",
"status": "updated"
},
{
"phone_number": "+1-7187309219",
"expires_at": "2022-10-27 00:00:00 UTC",
"error": "expires_at cannot be past date/time",
"status": "failed"
},
{
"phone_number": "sssssss",
"error": "phone_number is invalid",
"status": "failed"
},
{
"phone_number": "911",
"expires_at": "2023-02-05 00:00:00 UTC",
"error": "emergency phone number is not allowed",
"status": "failed"
}
]
Code: 200
Remove numbers from the DNC list
Example request:
POST https://{subdomain}.{domain}/apps/api/v1/outbound_dialer/dnc/remove
{
"phone_numbers": [
"1-415-111-1111",
"1-415-222-2222",
"1-415-333-333-3333"
]
}
Check whether a phone number is on the DNC list
Example request:
| Key | Value |
|---|---|
phone_number |
{PHONE_NUMBER} (Number) The end-user's phone number. |
GET https://{subdomain}.{domain}/apps/api/v1/outbound_dialer/dnc/check?phone_number={PHONE_NUMBER}
Example response:
{
"phone_number": "1-415-111-1111",
"expired_at": "2023-08-05 22:02:36.362009 +0000"
"do_not_call": true
}
Code: 200