All API updates are backwards compatible. We reserve the right to introduce new JSON keys in existing API responses at any time. We recommend handling responses defensively by disregarding any unrecognized keys to ensure continued functionality.
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”
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
The system limits requests to a rate of 1 request per second per customer.
A call object is created for every single call that is made into, or out of the system.
{
"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 the system 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 |
| 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) |
| menu_id | FALSE | String / Integer | Selected menu id for outbound call to grab settings from queue instead of global settings | |
| 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}} |
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
| 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) |
| menu_id | FALSE | String / Integer | Selected menu id for outbound call to grab settings from queue instead of global settings | |
| 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}} |
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
| 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}} |
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
| Parameter | Required | Data Type | Definition | Postman Variable |
|---|---|---|---|---|
| call_type | TRUE | String | Call type to create. Use “Voice Scheduled (API)” or “ScheduledCall” (deprecated) to create a 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}} |
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
| Parameter | Required | Data Type | Definition | Postman Variable |
|---|---|---|---|---|
| call_type | TRUE | String | Call type to create. Use “Voice Scheduled (API)” or “ScheduledCall” (deprecated) to create a 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}} |
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Create a new scheduled callback. IVR menus skip the scheduled_call_enabled check since the setting is not yet available in IVR queue settings.
original_call_id is the canonical request-body field for the ID of the original call that triggered this scheduled callback. UJET stores this reference and makes it available to downstream virtual agent and CRM integrations as the original_call_id data parameter. call_id and parent_call_id are kept as deprecated legacy aliases for backwards compatibility — when multiple aliases are sent, resolution order is original_call_id -> call_id -> parent_call_id. Prefer original_call_id for new integrations.
Selected request fields
end_user_number (required, string) — E.164; the consumer number to call back.scheduled_at (required, string) — ISO 8601; must be in the future.menu_id (integer) — required unless one of original_call_id / call_id / parent_call_id is supplied.ani (string, optional) — E.164 caller line identity. Honored only when phone-number retention is enabled for the tenant; otherwise ignored. Duplicate detection also matches on ani. Supplying ani inside custom_parameters does NOT populate the ANI field.recording_permission — one of recording_permission_not_asked, recording_permission_granted, recording_permission_denied.user_authenticated — Y or N.The response includes a callback_data object echoing the callback metadata (including ani, ticket_id, and call_id).
Error responses
400 — invalid menu/language/call reference (menu_id is required, queue {id} does not exist, Only mobile, web, and IVR menu IDs are permitted, Language '{lang}' is not available).422 — request validation failed, or a booking conflict; body is { "message": "<text>" }. One of:end_user_number / dnis / ani, malformed scheduled_at, invalid enum, Queue ID does not exist)Scheduled time is before minimum wait time. Minimum scheduled time: {iso8601}Scheduled time is outside business hoursA scheduled callback already exists for this phone number (matched on end_user_number or ani)409 — slot at capacity — { "code": "slot_unavailable", "sub_code": "at_capacity", "message": "slot_at_capacity", "display_message": "The selected time slot is no longer available." }Note: the reschedule (PATCH) endpoint does not re-run the minimum-wait, hours-of-operation, or capacity checks.
Used to update the end_user associated with the current active call session. Additionally, it also updates the contact information linked to the CRM ticket. _Identifier is required, while name, email, and phone are optional. Note: If a phone number is already set, providing a phone parameter will not update the phone number.
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
| Key | Value | Description |
|---|---|---|
| call_id |
| Key | Value | Description |
|---|---|---|
| id | integer | (Required) |
| Key | Value | Description |
|---|---|---|
| id | integer | (Required) |
| Key | Value | Description |
|---|---|---|
| id | integer | (Required) |
Adds a third party participant to an existing call. The agent must be connected to the call to initiate the third party dial.
| Parameter | Required | Data Type | Definition | Postman Variable |
|---|---|---|---|---|
| agent_email | TRUE | String | Email address of the agent who is connected to the call and initiating the third party dial | {{agent_email}} |
| phone_number | TRUE | String | Phone number of the third party to dial. Can be formatted (e.g., +1 (226) 336-1437) or unformatted (e.g., 12263361437) |
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
| Key | Value | Description |
|---|---|---|
| id | 123 | Call ID |
| 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}} |
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
| 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]}} |
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
| 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]}} |
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
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. |
| Key | Value | Description |
|---|---|---|
| file |
| Key | Value | Description |
|---|---|---|
| id | {{job_id}} | |
| file |
| Key | Value | Description |
|---|---|---|
| id | {{job_id}} |
A campaign refers to an outbound auto-dialer feature that sequentially reaches out to a list of contacts, initiates outbound calls, and connects each contact to an available agent. Campaign endpoints provide access to campaign-related data, allowing retrieval of campaign and contact objects.
Currently, the campaign endpoints allow users to add, update, and delete contacts of an existing campaign. In future releases, the campaign endpoints will allow users to create, edit and delete campaigns.
[
{
"assigned_call_id": 32001,
"assigned_participant_id": 54321,
"campaign_id": 240,
"created_at": "2023-04-01T17:15:38.000Z",
"id": 16312,
"name": "string",
"outbound_number": null,
"priority": null,
"status": "Upcoming",
"unique_id": "string",
"updated_at": "2023-04-01T17:15:38.000Z"
},
{
"assigned_call_id": 32002,
"assigned_participant_id": 54330,
"campaign_id": 240,
"created_at": "2023-04-01T17:15:38.000Z",
"id": 16313,
"name": "string",
"outbound_number": null,
"priority": null,
"status": "Finished",
"unique_id": "string",
"updated_at": "2023-04-01T17:25:00.000Z"
}
]
The status field can be in any of the following states
| Campaign Contact Status | Description |
|---|---|
| Upcoming | Contact is next to be dialed. |
| Dialing | Contact is right now being dialed. |
| Queued | Call for a given contact is queued. |
| Connected | Contact is connected with an agent. |
| Finished | Call has completed. |
| Transferred | Call has been transferred. |
| Transferred and Finished | Call has been transferred and then completed. |
| Not Picked Up | No answer from end user or never reached the end user. |
| Not Reached to Contact | Call never reached the contact . |
| Abandoned by Contact | For preview, end user hangs up before connected to an agent. For both progessive and predictive, end user hangs up the call within 5 seconds after connecting to the agent. |
| Skipped | Contact has been skipped by agent and will be available to be connected to another agent. |
| Skipped & Closed | On Preview, agent skips and close a contact. This contact should now be always skipped in this campaign. |
| Invalid Number | Contact with invalid phone number. |
| Carrier Error | This error is driven by carrier. |
| Abandoned by Dialer | Contact has been abandoned by dialer. |
| Voicemail Hung Up | On Predictive, the dialer determines the end user is a machine (ie. voicemail). |
| Dialer General Error | Call failed due to dialer error. |
| Redial Scheduled | Temporary status. Redial scheduled in the future. |
| Do Not Call | The number was in Do-Not-Call number list. |
| Invalid Outbound Number | Contact with invalid outbound number. |
| Blocked Phone Number | Contact with invalid/blocked international number. |
| Key | Value | Description |
|---|---|---|
| file | some/path/to/multi_contacts.json |
Agent Status Endpoint
The Agent Status endpoint allows you to modify the status of agents. It enables changes to and from ‘Available’ to any custom status. Transitions to and from system-defined statuses like ‘In-Call’ will trigger an error. Additionally, this endpoint supports bulk updates, allowing status modifications for entire teams or selected groups of agents simultaneously.
Force Logout Agents Endpoint
The Force Logout Agents endpoint provides the functionality to forcibly log out online agents. Agents engaged in active calls or chats will be logged out automatically upon the completion of their current interactions, whereas idle agents are logged out immediately. This endpoint supports forced logouts of specific agents, entire teams, or agents identified by IP addresses with CIDR notation, a list of IPv4/IPv6 addresses, or IP ranges (see the request examples). For a large number of agents, a background job is created to manage the logout process efficiently.
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
| Key | Value | Description |
|---|---|---|
| id |
Creates or updates an end user based on a given identifier
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json | |
| Accept | application/json |
Get End User external identifier and internal ID, given one of the fields
| Key | Value | Description |
|---|---|---|
| Accept | application/json |
| Key | Value | Description |
|---|---|---|
| id | integer | Internal ID for the End User |
| identifier | string | External identifier for the End User |
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json | |
| Accept | application/json |
| Key | Value | Description |
|---|---|---|
| id | integer | (Required) |
Send a message in a chat.
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
| Key | Value | Description |
|---|---|---|
| id | integer | (Required) |
Escalate a chat from a Virtual Agent to a Human Agent
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json | |
| Accept | application/json |
| Key | Value | Description |
|---|---|---|
| chat_id | integer | (Required) Chat ID to escalate |
Used only for selecting deflection channel currently.
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json | |
| Accept | application/json |
| Key | Value | Description |
|---|---|---|
| chat_id | integer | (Required) |
| id | integer | (Required) |
Add a photo that has been uploaded to media storage to a chat
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json | |
| Accept | application/json |
| Key | Value | Description |
|---|---|---|
| chat_id | integer | (Required) |
Retrieves media ID’s and storage url’s for all photos attached to the chat
| Key | Value | Description |
|---|---|---|
| Accept | application/json |
| Key | Value | Description |
|---|---|---|
| chat_id |
Used for fetching a presigned upload URL
| Key | Value | Description |
|---|---|---|
| Accept | application/json |
| Key | Value | Description |
|---|---|---|
| chat_id | integer | (Required) |
Add a video that has been uploaded to media storage to a chat
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
| Key | Value | Description |
|---|---|---|
| chat_id | integer | (Required) |
Retrieves media ID’s and storage url’s for all videos attached to the chat
| Key | Value | Description |
|---|---|---|
| Accept | application/json |
| Key | Value | Description |
|---|---|---|
| chat_id |
Fetches a single media file (photo, video, audio, document) attached to the chat and returns the raw binary content. The response exposes the file name via the X-File-Name header.
| Key | Value | Description |
|---|---|---|
| Accept | application/json |
| Key | Value | Description |
|---|---|---|
| media_id | {{media_id}} | (Required) |
| media_type | {{media_type}} | (Required) photo / video / audio / document |
| Key | Value | Description |
|---|---|---|
| chat_id | integer | (Required) |
Used for fetching a presigned upload URL for the company’s configured cloud storage service
| Key | Value | Description |
|---|---|---|
| Accept | application/json |
| Key | Value | Description |
|---|---|---|
| chat_id | integer | (Required) |
Start a new chat
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json | |
| Accept | application/json |
| Key | Value | Description |
|---|---|---|
| Accept | application/json |
| Key | Value | Description |
|---|---|---|
| id | integer | (Required) |
If a chat has been dismissed for inactivity, an end user may resume the same chat. Chat status must be “dismissed” or “va_dismissed”
| Key | Value | Description |
|---|---|---|
| Accept | application/json |
| Key | Value | Description |
|---|---|---|
| id | integer | (Required) |
| Key | Value | Description |
|---|---|---|
| Accept | application/json |
| Key | Value | Description |
|---|---|---|
| id | integer | (Required) |
| Key | Value | Description |
|---|---|---|
| id | integer | (Required) |
| Key | Value | Description |
|---|---|---|
| id | integer | (Required) |
Send custom data in a chat
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
| Key | Value | Description |
|---|---|---|
| id | (Required) |
Used to update the end_user associated with the current active chat session. Additionally, it also updates the contact information linked to the CRM ticket. _Identifier is required, while name, email, and phone are optional. Note: If a phone number is already set, providing a phone parameter will not update the phone number.
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
| Key | Value | Description |
|---|---|---|
| chat_id |
| Key | Value | Description |
|---|---|---|
| chat_id |
Returns CSAT eligibility for a finished chat along with localized survey messages.
Call this after PATCH /apps/api/v1/chats/:chat_id/end. When eligible is true, present the survey using the strings in messages, then submit via PATCH /apps/api/v1/chats/:chat_id/rating.
Eligibility gates (evaluated in order):
1. chat-api-csat feature flag is ON (else 404)
2. Operation Management CSAT is enabled
3. Chat is finished
4. Chat has not already been rated
5. Queue-level chat_api_csat resolves to true (Global > Parent > Queue inheritance)
Optional per-request message overrides:
Callers may supply an optional messages map to override any of the five admin-configured survey strings on a per-request basis. Each override key is independent — omitted keys fall back to the admin-configured Audible value. Unknown keys are silently dropped (forward-compat); empty or whitespace-only values fall back to the admin value rather than blanking the field.
Wire format is deepObject query parameters, e.g. ?messages[form_title]=Rate%20your%20chat&messages[result_subtitle]=Thanks!.
Override validation rules:
- Recognized keys: form_title, form_feedback, result_title, result_subtitle, feedback_label
- Each value: must be a string, max 300 raw characters
- Forbidden characters: Unicode control characters (category Cc) except TAB, LF, CR. Zero-width chars, BIDI controls, joiners, BOM, and emoji ZWJ sequences are accepted.
- Override values are HTML-escaped server-side before being returned in messages. Admin-resolved (non-override) values pass through raw.
- Validation failures return 400 with validation_errors[] listing each offending field and a wire-format code (invalid_type, too_long, invalid_characters). Partner integrations may parse the code values directly.
Override of a null admin value flips a previously-ineligible chat to eligible — but a per-field override cannot rescue an entirely absent admin config (the 5-field completeness check still ineligibles out if messages cannot be fully resolved).
Response keys:
- eligible (boolean): whether to show the CSAT survey
- messages (object|null): localized strings keyed by form_title, form_feedback, result_title, result_subtitle, feedback_label. null when ineligible. form_feedback and feedback_label are omitted when feedback_enabled is false.
- feedback_enabled (boolean): client-side presentation hint sourced from Operation Management csat_settings.feedback_enabled. Not enforced server-side.
| Key | Value | Description |
|---|---|---|
| chat_id |
Returns the current CSAT rating for a chat.
Response body:
- rating (number|null): float between 0 and 5 (e.g. 4.0, 3.7), or null until the consumer submits one via PATCH /apps/api/v1/chats/:chat_id/rating.
Returns 404 when the chat-api-csat feature flag is OFF or the chat is not found.
| Key | Value | Description |
|---|---|---|
| chat_id |
Submits a CSAT rating for a finished chat.
Request body:
- rating (number, required): 0 to 5. Float values are accepted (e.g. 3.7).
- feedback (string, optional): free-text feedback. Stored regardless of feedback_enabled; the toggle only controls whether the survey UI prompts for it.
Server re-runs the same eligibility checks as GET /apps/api/v1/chats/:chat_id/csat. A stale or hostile client cannot submit a rating to a chat the eligibility endpoint would refuse.
Errors:
- 400 — rating is missing or not a number
- 404 — feature flag OFF or chat not found
- 422 — eligibility check failed; rating out of range; chat became unfinished or was rated between eligibility check and submit; or rating not permitted by company CSAT settings / time window
On success the chat’s chat_csat_submitted event is created and the rating is forwarded to CRM and reporting.
| Key | Value | Description |
|---|---|---|
| chat_id |
Customer-side ingress for Chat DAP (Direct Access Point) webhook-response routing mode.
Flow
1. End-user SDK calls GET /v2/menus and the platform places the chat on hold.
2. Platform fires an outbound webhook to the customer with chat_dap_id and callback_url.
3. Customer does its own lookup (CRM, segmentation, business rules) and POSTs the result back to this endpoint.
4. Platform resolves the hold against the company’s DAP routing_logic_order (api_response → general_access_point_label → user_segmentation) and the SDK’s polling on /v2/menus?chat_dap_id=... unblocks.
Gated by the chat-api-dap feature flag.
HTTP Basic, same as the rest of Apps API.
- Username: company subdomain ({{username}})
- Password: API token from Settings → Developer Settings → API Credentials ({{password}})
| Header | Required | Notes |
|---|---|---|
Authorization | yes | Set automatically by Postman from the Basic auth above. |
Content-Type: application/json | yes | Body must be JSON. |
Accept: application/json | no | Recommended. |
UJET-SUBDOMAIN | no | Tenant identifier. Normally inferred from the host; only needed when calling through a host that does not carry the tenant subdomain. Disabled by default. |
| Field | Type | Required | Notes |
|---|---|---|---|
chat_dap_id | string | yes | Opaque hold id returned to the SDK by /v2/menus. Max 128 chars. |
key_value_pairs | object | yes | Routing payload. Keys are matched against the company’s DAP routing configuration. Max 16 KB serialized, max nesting depth 5. |
error | string | null | no | Optional customer-side error message recorded on the inbound audit row. Max 1024 chars; non-string values are ignored. |
Minimal example:
{
"chat_dap_id": "a3f8e2c5d9b6f4e2a1c8b3a5d7f9e2b4",
"key_value_pairs": {
"region": "us-east"
}
}
The success body is intentionally minimal — the webhook caller only needs an ACK:
{
"ack": "ok"
}
Hold-resolution detail (dap_state, direct_access_key_id, matched_step) is not returned to the customer. It is surfaced to the end-user SDK via its polling on GET /v2/menus?chat_dap_id=..., and recorded server-side on the inbound audit row and in structured logs ([ChatDap] callback resolved) for ops visibility. The customer system has no need for that state.
| Code | When |
|---|---|
400 | chat_dap_id missing/empty/oversized, or key_value_pairs is not an object / exceeds 16 KB / exceeds depth 5. Size and depth violations both surface as key_value_pairs exceeded size limits since validation is a single JSON-generate pass. |
401 | Basic auth credentials missing or invalid. |
404 | chat_dap_id is unknown or expired beyond the Redis grace window, or the chat-api-dap feature flag is off for this tenant. |
The endpoint is idempotent. Repeat callbacks with the same chat_dap_id no-op on the hold transition (only the first pending → ready wins). Customers may safely retry on network failure — the response is the same ACK regardless.
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json | Required. Body must be JSON. |
| Accept | application/json | Recommended. |
The Company DNC (Do Not Call) list will allow blocking direct, manual, outbound calls as well as outbound and scheduled calls created by the Apps API depending on configuration.
Currently, the Company DNC endpoints allow users to:
add multiple phone numbers to the DNC list
remove phone numbers from the DNC list
check whether a phone number is in the DNC list
| Key | Value | Description |
|---|---|---|
| phone_number | {{$randomPhoneNumber}} |
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Queue Status Endpoint: Provides the status of a specific queue, allowing you to check the queue’s status before deflection.
Returns comprehensive, real-time status for one or more leaf queues, including the callback time slots a virtual agent can offer for scheduling a callback.
Query parameters
menu_id[] (required) — 1–10 leaf menu IDs, e.g. menu_id[]=1&menu_id[]=2.lang (required) — ISO 639-1 language code enabled for the company.menu_type (required) — one of ivr_menu, mobile_menu, web_menu.callback_period_hours (optional, integer 1–24) — length of the future window for which callback slots are returned.callback_start_from (optional, ISO 8601) — start of the callback search window; must be in the future.Response
Each queue object includes callback_periods[] and a scheduling_config object.
callback_periods[]: date (yyyyMMdd), start_time / end_time (HH:mm, queue timezone), scheduled_calls (booked count), max_slots, and available_slots (max_slots - scheduled_calls, floored at 0). When capacity is unlimited, callback_periods is [] and max_slots / available_slots are null.scheduling_config: scheduled_callback_enabled, availability_interval (minutes; null = unlimited), availability_days, capacity_type (calculated | static | unlimited), calculated_capacity_percentage, enforce_minimum_wait_time_ewt, minimum_wait_time_minutes.Errors: 400 invalid/missing params; 404 menu not found / not a leaf.
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json | |
| Accept | application/json |
| Key | Value | Description |
|---|---|---|
| lang | {{lang}} | (ISO 639-1 string, required) The language code for the queue, e.g., |
| menu_id[] | {{menu_id}} | (string, required) A single Queue ID or an array of multiple Queue IDs. |
| menu_type | {{menu_type}} | (string, required) One of |
| callback_period_hours | (integer, optional, 1–24) Total future window length in hours for which to return callback-slot periods. | |
| callback_start_from | (ISO 8601 datetime string in queue/company timezone, optional) Start of the callback-slot search window. If omitted, defaults to “now” (server time converted to queue/company timezone). Must not be in the past. |
Fetches availability information for a specific queue.
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json | |
| Accept | application/json |
| Key | Value | Description |
|---|---|---|
| menu_id | {{menu_id}} | (integer, required) The ID of the menu to fetch availability for. |
| lang | {{lang}} | (string, required) The language code (e.g., ‘en’) |
| channel_type | {{channel_type}} | (string, required) The channel type, either call or chat. |
The API user is able to:
manage Contact lists via API
create a Custom Contact List
edit a Custom Contact List
delete a Custom Contact List
manage custom and global Contact List entries
add entries
edit entries
delete entries
| Key | Value | Description |
|---|---|---|
| id | integer | The ID of updating contact list |
| Key | Value | Description |
|---|---|---|
| id | integer | The ID of deleting contact list |
| Key | Value | Description |
|---|---|---|
| contact_list_id | integer | The ID of selected contact list |
| Key | Value | Description |
|---|---|---|
| contact_list_id | integer | The ID of contact list |
| id | integer | The ID of updating contact record |
| Key | Value | Description |
|---|---|---|
| contact_list_id | integer | The ID of contact list |
| id | integer | The ID of deleting contact record |
| Key | Value | Description |
|---|---|---|
| menu_id | Interger | (Required) The ID of the menu to fetch availability for |
| lang | string | (Required) The language code (e.g., “en”) |
| channel_type | string | (Required) The channel type, either call or chat |
Users Endpoints provide a means to get user objects. Each user object represents a single user inside of our platform. Please review the model below to see which fields may be considered PII.
Default page size is 100 if no page parameters are sent.
{
"id": 1,
"email": "string", //This may be considered PII
"first_name": "string", //This may be considered PII
"last_name": "string", //This may be considered PII
"agent_number": "string",
"location": "string",
"max_chat_limit": 5,
"max_chat_limit_enabled": false,
"unrestricted_international_calling": true,
"deactivated_at": "2018-05-30T20:46:31.333Z",
"ucaas_user_name": "string",
"ucaas_sip_uri": "string",
"external_user": false,
"phone_numbers": ["string"],
"extension_numbers": [
0
],
"teams": [
{
"name": "string"
}
],
"roles": [
{
"name": "string"
}
]
}
| Response Code | Meaning |
|---|---|
| 200 | The API request has been successful |
| 400 | Invalid page size request - check to ensure the max page size is a valid integer less than 1000 |
| 400 | Cannot paginate filtered results - ensure that you are not using a filter and pagination parameters |
| 400 | Only one filter should be configured at a time |
| 400 | Ensure you are not filtering more than 1000 values at a time |
| Parameter | Required | Data Type | Definition | Postman Variable |
|---|---|---|---|---|
| page | FALSE | String | Pairs with per to note what page of records. For instance if per is made to be 200 and page is 2, the response would contain record 201-400, as page 1 would contain 1-200. | {{page}} |
| per | FALSE | String | Pairs with page to note how many records would be included in a page of records. For instance if per is made to be 200 and page is 2, the response would contain record 201-400, as page 1 would contain 1-200. | {{per}} |
| id[] | FALSE | Array[String] | Array[Strings]. Id of records to search and return | {{id[]}} |
| agent_number[] | FALSE | Array[String] | Agent numbers as assigned by the admin at the time of creating an agent | {{agent_number[]}} |
| status_id[] | FALSE | Array[String] | Filters by agent status | {{status_id[]}} |
| online[] | FALSE | Boolean | Filter by if agents are online or not | {{online[]}} |
| wrap_up[] | FALSE | Boolean | Filter by if agents are in wrap up status | {{wrap_up[]}} |
| location[] | FALSE | Array[String] | Filters by agent location | {{location[]}} |
| last_login_time[from] | FALSE | Time in UTC | creates a lower bound of the last login time field. All records returned will be after the inputted value. | {{last_login_time[from]}} |
| last_login_time[to] | FALSE | Time in UTC | creates a upper bound of the last login time field. All records returned will be before the inputted value. | {{last_login_time[to]}} |
| status_updated_at[from] | FALSE | Time in UTC | creates a lower bound of the status updated at field. All records returned will be after the inputted value. | {{status_updated_at[from]}} |
| status_updated_at[to] | FALSE | Time in UTC | creates a upper bound of the status updated at field. All records returned will be before the inputted value. | {{status_updated_at[to]}} |
Send a custom data in a call.
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
| Key | Value | Description |
|---|---|---|
| id | (Required) |
Get Call List.
Introduced in version 3.39.
Get a Call
Introduced in version 3.39.
| Key | Value | Description |
|---|---|---|
| call_id | integer | call_id to search |
Cancel a Scheduled Call
Introduced in version 3.39.
| Key | Value | Description |
|---|---|---|
| call_id | integer | call_id to cancel |
Cancel Multi Scheduled Call
Introduced in version 3.39.
Update an existing scheduled callback. Allows modifying the scheduled time, end user number, recording permission, and other IVR-specific parameters. Requires the Scheduled Callback API to be enabled for your account.
ani (optional, E.164) is only validated and stored when phone-number retention is enabled for your account; otherwise it is ignored. The reschedule endpoint does not re-run the minimum-wait, hours-of-operation, or capacity checks that apply on create.
| Key | Value | Description |
|---|---|---|
| call_id | 8788 | Scheduled call ID to update |
Retrieve details of an existing scheduled callback by ID. Requires the Scheduled Callback API to be enabled for your account.
| Key | Value | Description |
|---|---|---|
| call_id | 8788 | Scheduled call ID |
List scheduled callbacks with optional filters. Requires the Scheduled Callback API to be enabled for your account.
| Key | Value | Description |
|---|---|---|
| end_user_number | string | End user phone number to filter scheduled calls |
| call_id | 8788 | Filter by parent call ID |
| id | 8788 | Filter by call ID |
| scheduled_from | 1977-03-22T23:59:59.670Z | Filter scheduled calls from this time (ISO8601 timestamp, inclusive) |
| scheduled_to | 1977-03-22T23:59:59.670Z | Filter scheduled calls up to this time (ISO8601 timestamp, inclusive). Time window between scheduled_from and scheduled_to must be at least 1 minute and at most 24 hours. |
| menu_id | 8788 | Filter by menu ID |
| lang | string | Filter by language code (e.g., en, es, fr) |
| ticket_id | string | Filter by ticket ID |
| page | 8788 | Page number for pagination (default: 1) |
| per_page | 8788 | Number of results per page (default: 100) |
| status | failed | Filter by callback status. Values: scheduled, completed, attempted (callback has remaining retries), failed (system attempted maximum number of retries), cancelled |
Get a Job state of Cancel Multi Scheduled Call
Introduced in version 3.39.
| Key | Value | Description |
|---|---|---|
| job_id | integer | job_id to search |
Retrieves the real-time status of a specific call in a queue, including its position and estimated wait time.
Introduced in version 3.42.
| field | description |
|---|---|
| position_in_queue | The current position of the call in the queue. The call at the front of the queue has a value of 1 (1-based). |
| ewt | The estimated wait time in seconds until the call is expected to be picked up from its current queue. |
| wait_duration_in_queue | The total time in seconds the call has been waiting in the queue since it was added. |
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
| Key | Value | Description |
|---|---|---|
| call_id | The ID of the call used to get its current state in the queue. |
Retrieves the real-time status of a specific call in a queue, including its position and estimated wait time.
Introduced in version 3.42.
| field | description |
|---|---|
| position_in_queue | The current position of the call in the queue. The call at the front of the queue has a value of 1 (1-based). |
| ewt | The estimated wait time in seconds until the call is expected to be picked up from its current queue. |
| wait_duration_in_queue | The total time in seconds the call has been waiting in the queue since it was added. |
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
| Key | Value | Description |
|---|---|---|
| call_id | :id |
Enable or disable emergency shutdown on one or more queues. This API allows external systems to remotely control queue availability during emergency situations.
| Parameter | Required | Data Type | Definition |
|---|---|---|---|
| menu_id | TRUE | Array | Array of Queue IDs to update |
| language | TRUE | String | ISO 639-1 language code (e.g., “en”, “es”) |
| emergency_shutdown.enabled | TRUE | Boolean | Enable (true) or disable (false) emergency shutdown |
| emergency_shutdown.message.type | FALSE | String | Message type: “tts” (text-to-speech) or “audio” (audio URL) |
| emergency_shutdown.message.content | FALSE | String | TTS text or audio file URL. Required if message.type is provided |
| emergency_shutdown.in_progress_calls | FALSE | String | How to handle in-progress calls: “allow_finish”, “end_and_redirect_to_after_hours”, “end_and_redirect_to_overcapacity” |
| emergency_shutdown.queued_calls | FALSE | String | How to handle queued calls: “disconnect”, “redirect_to_after_hours”, “redirect_to_overcapacity” |
Notes:
- If no message is provided when enabling, the global default emergency shutdown message will be used.
- The in_progress_calls and queued_calls parameters are optional; if not provided, global settings are inherited.
- The API requires the Emergency Shutdown feature to be enabled and Remote Shutdown API access to be enabled for the company.
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json | |
| Accept | application/json |
Returns the full forest of all active root-level disposition lists for the tenant and their descendants. Callers can identify roots by parent_path == "/" (or level == 1); root_list is null because no single list is selected.
Feature flag: Gated behind update-previous-acw. Returns 404 when the flag is off.
| Parameter | Required | Data Type | Definition |
|---|---|---|---|
| channel | FALSE | String | “voice_call” or “chat”. Default: “voice_call” |
| call_direction | FALSE | String | “inbound” or “outbound”. Default: “inbound”. Ignored for chat |
| lang | FALSE | String | ISO 639-1 language code. Default: “en” |
| page | FALSE | Integer | Pagination page (default 1) |
| per_page | FALSE | Integer | Items per page (default 100, max 100) |
Notes:
- The name field returned per code/list is the stored admin-authored string. lang selects the per-language assignment but does NOT translate names.
- Pagination is exposed via standard headers (Total, Per-Page, Link).
| Key | Value | Description |
|---|---|---|
| Accept | application/json |
| Key | Value | Description |
|---|---|---|
| channel | voice_call | Channel for the tree. One of “voice_call” or “chat”. Defaults to “voice_call”. |
| call_direction | inbound | Call direction for voice_call. One of “inbound” or “outbound”. Defaults to “inbound”. Ignored when channel is “chat” but must still be a valid value if provided. |
| lang | en | Language code used to select the language-specific queue assignment. Defaults to “en”. Does NOT translate the returned code or list names — values are the admin-authored strings regardless of lang. |
| page | 1 | Page number for the disposition_codes array (default 1). |
| per_page | 100 | Items per page (default 100, max 100). Pagination metadata is returned via RFC-5988 response headers (Total, Per-Page, Link). |
Returns the disposition tree for a specific queue (menu). Resolves the most-specific enabled Menu::CodeMenuAssignment up the menu hierarchy and falls back to the tenant’s channel-scoped global list (voice-inbound / voice-outbound / chat) when no assignment is found.
Feature flag: Gated behind update-previous-acw. Returns 404 when the flag is off OR when the menu doesn’t exist.
| Parameter | In | Required | Data Type | Definition |
|---|---|---|---|---|
| menu_id | path | TRUE | Integer | Queue (menu) ID |
| channel | query | FALSE | String | “voice_call” or “chat”. Default “voice_call” |
| call_direction | query | FALSE | String | “inbound” or “outbound”. Default “inbound”. Ignored for chat |
| lang | query | FALSE | String | ISO 639-1. Default “en” |
| page | query | FALSE | Integer | Pagination page (default 1) |
| per_page | query | FALSE | Integer | Items per page (default 100, max 100) |
| Key | Value | Description |
|---|---|---|
| Accept | application/json |
| Key | Value | Description |
|---|---|---|
| channel | voice_call | “voice_call” or “chat”. Default: “voice_call”. |
| call_direction | inbound | “inbound” or “outbound”. Default: “inbound”. Ignored for chat. |
| lang | en | ISO 639-1. Default: “en”. Selects the per-language queue assignment; does NOT translate names. |
| page | 1 | |
| per_page | 100 |
| Key | Value | Description |
|---|---|---|
| menu_id | 123 | Queue (menu) ID |
Returns the disposition tree that applies to a specific session, resolved from the session’s comm via the same logic the agent UI uses. The response channel, call_direction, and lang are derived from the resolved comm; query-param overrides for those fields are NOT honored on this endpoint.
Feature flag: Gated behind update-previous-acw. Returns 404 when the flag is off, when the session doesn’t exist, or when the session has no resolvable comm.
| Parameter | In | Required | Data Type | Definition |
|---|---|---|---|---|
| session_id | path | TRUE | Integer | Session ID |
| comm_type | query | FALSE* | String | “call” or “chat”. *Required when the session has both a call and a chat. |
| page | query | FALSE | Integer | Pagination page (default 1) |
| per_page | query | FALSE | Integer | Items per page (default 100, max 100) |
| Key | Value | Description |
|---|---|---|
| Accept | application/json |
| Key | Value | Description |
|---|---|---|
| comm_type | call | “call” or “chat”. Required when the session is omnichannel (has both a call and a chat); otherwise auto-resolves. |
| page | 1 | |
| per_page | 100 |
| Key | Value | Description |
|---|---|---|
| session_id | 9876 | Session ID |
Updates the disposition code and/or notes of a previously completed session. At least one of disposition_code or notes must be present in the request body.
Writes: - CRM: a new note record is attached on every call (additive, never an overwrite of prior notes). - External Storage: the existing session-metadata file is overwritten with the latest disposition state.
Feature flag: Gated behind update-previous-acw. Returns 404 when the flag is off.
| Field | In | Required | Data Type | Definition |
|---|---|---|---|---|
| session_id | path | TRUE | Integer | Session ID |
| comm_type | query | FALSE* | String | “call” or “chat”. *Required when the session is omnichannel. |
| disposition_code.id | body | conditional | Integer | Disposition code id from the read API. Use -1 for the synthetic Do-Not-Call sentinel (only valid when the tenant has DNC + DNC-disposition enabled). |
| disposition_code.full_path | body | conditional | String | parent_path of the membership (e.g. “/100/200”). Required when disposition_code is provided. |
| notes | body | conditional | String | Note text. Empty string is treated as an explicit clear; an omitted field leaves the prior note unchanged. |
Notes:
- Either disposition_code or notes must be present (or both).
- The resolved code’s canonical name is returned in the response; callers do NOT need to send a name field.
- The id == -1 sentinel triggers DNC list processing in addition to persisting the disposition row.
- Returns 422 if the resolved comm is still active (the CRM/storage writes only run after the comm has ended).
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json | |
| Accept | application/json |
| Key | Value | Description |
|---|---|---|
| comm_type | call | “call” or “chat”. Required when the session is omnichannel (has both a call and a chat); otherwise auto-resolves. |
| Key | Value | Description |
|---|---|---|
| session_id | 9876 | Session ID |
Read-only Apps API for retrieving parsed email data (ESC-2542). Two endpoints:
GET /apps/api/v1/email/sessions/:email_support_id — session metadata + its email_threads list.GET /apps/api/v1/email/messages/:email_thread_id — a single parsed message + email_attachments metadata.HTTP Basic auth; gated by email-parsed-data-api (off → 404 not_found).
Returns metadata for a single email support session plus its (non-draft) threads, ordered by received_at ascending. DB-only lookup.
Authentication: HTTP Basic — username = Apps API user name, password = API token.
Feature flag: email-parsed-data-api (off → 404 not_found).
| Name | Type | Required | Description |
|---|---|---|---|
email_support_id | integer | Yes | Numeric EmailSupport id. |
Call this, then for each email_threads[].email_thread_id call GET /apps/api/v1/email/messages/:email_thread_id.
| Status | Body | When |
|---|---|---|
| 400 | { "error": "invalid_email_support_id" } | email_support_id ≤ 0 |
| 401 | — | Missing/invalid credentials |
| 404 | { "error": "not_found" } | Not found in tenant, or feature flag off |
| Key | Value | Description |
|---|---|---|
| Accept | application/json |
| Key | Value | Description |
|---|---|---|
| email_support_id | 12345 | (Required) Numeric EmailSupport id. |
Returns a single parsed email message — headers, body, and attachment metadata.
Authentication: HTTP Basic — username = Apps API user name, password = API token.
Feature flag: email-parsed-data-api (off → 404 not_found).
| Name | Type | Required | Description |
|---|---|---|---|
email_thread_id | integer | Yes | Numeric EmailThread id (the email_thread_id from the sessions endpoint’s email_threads[]). The RFC 5322 Message-ID is returned separately as message_id. |
email_attachments[].url is null until the attachment-URL prerequisite (ESC-3036) ships.email_attachments[].data (base64) or body_formatted field.to/cc/bcc are always arrays.| Status | Body | When |
|---|---|---|
| 400 | { "error": "invalid_email_thread_id" } | email_thread_id ≤ 0 |
| 401 | — | Missing/invalid credentials |
| 404 | { "error": "not_found" } | Not found in tenant, draft, or feature flag off |
| Key | Value | Description |
|---|---|---|
| Accept | application/json |
| Key | Value | Description |
|---|---|---|
| email_thread_id | 9001 | (Required) Numeric EmailThread id (from sessions’ email_threads[].email_thread_id). Not the RFC 5322 Message-ID — that is |
Agent Skills API — the tenant skills roster: create, list, update, and delete skills. Per-agent assignments are under User Skills; per-queue requirements are under Menu Skill Requirements.
Returns the tenant skills roster with per-skill aggregates (agent count, average proficiency, in-queue usage).
Authentication: HTTP Basic — username = Apps API user key, password = Apps API token.
| Key | Value | Description |
|---|---|---|
| Accept | application/json |
Creates a skill in the tenant roster. Returns 409 when the skill name already exists.
Authentication: HTTP Basic — username = Apps API user key, password = Apps API token.
| Key | Value | Description |
|---|---|---|
| Accept | application/json | |
| Content-Type | application/json |
Updates an existing skill. Returns 404 when the skill does not exist.
Authentication: HTTP Basic — username = Apps API user key, password = Apps API token.
| Key | Value | Description |
|---|---|---|
| Accept | application/json | |
| Content-Type | application/json |
| Key | Value | Description |
|---|---|---|
| id | 5 | (Required) Skill ID |
Replaces an existing skill (PUT equivalent of the PATCH update).
Authentication: HTTP Basic — username = Apps API user key, password = Apps API token.
| Key | Value | Description |
|---|---|---|
| Accept | application/json | |
| Content-Type | application/json |
| Key | Value | Description |
|---|---|---|
| id | 5 | (Required) Skill ID |
Deletes a skill from the tenant roster. Returns 409 when the skill is still used by a queue requirement.
Authentication: HTTP Basic — username = Apps API user key, password = Apps API token.
| Key | Value | Description |
|---|---|---|
| Accept | application/json |
| Key | Value | Description |
|---|---|---|
| id | 5 | (Required) Skill ID |
Agent Skills API — per-agent skill assignments: upsert (assign) or remove a skill for a user.
Creates or updates one skill assignment for the agent. Returns 404 if the user or skill is not found, 422 if the level is out of range.
Authentication: HTTP Basic — username = Apps API user key, password = Apps API token.
| Key | Value | Description |
|---|---|---|
| Accept | application/json | |
| Content-Type | application/json |
| Key | Value | Description |
|---|---|---|
| user_id | 42 | (Required) Agent (user) ID |
Removes a single skill assignment from the agent.
Authentication: HTTP Basic — username = Apps API user key, password = Apps API token.
| Key | Value | Description |
|---|---|---|
| Accept | application/json |
| Key | Value | Description |
|---|---|---|
| user_id | 42 | (Required) Agent (user) ID |
| skill_id | 5 | (Required) Skill ID |
Agent Skills API — per-queue skill requirements: upsert (set) or remove a skill requirement on a menu cascade queue group.
Creates or updates a skill requirement term on a queue cascade group.
Authentication: HTTP Basic — username = Apps API user key, password = Apps API token.
| Key | Value | Description |
|---|---|---|
| Accept | application/json | |
| Content-Type | application/json |
| Key | Value | Description |
|---|---|---|
| menu_id | 12 | (Required) Menu (queue) ID |
Removes a skill requirement term from a queue cascade group.
Authentication: HTTP Basic — username = Apps API user key, password = Apps API token.
| Key | Value | Description |
|---|---|---|
| Accept | application/json |
| Key | Value | Description |
|---|---|---|
| menu_id | 12 | (Required) Menu (queue) ID |
| cascade_group_id | 101 | (Required) Cascade group ID |
| skill_id | 5 | (Required) Skill ID |
Bulk email status management Apps API. Transition one or more email sessions to a target status in a single call, with per-session results.
Bulk-transition one or more email sessions to a single target status. Returns a per-session result array (one entry per input id, in request order). HTTP 200 is returned even when some items fail, so inspect each result.
Authentication: HTTP Basic — username = Apps API user name, password = API token.
| Name | Type | Required | Description |
|---|---|---|---|
session_ids | string or string[] | Yes | One or more email session ids (numeric EmailSupport ids as strings, e.g. “12345”). Max 100 per request. |
new_email_status | string | Yes | Target status: active, paused, resolved, or closed. |
existing_email_status | string | No | Optional expected current status. If it does not match the session’s actual status, that item is reported stale_state and left unchanged. |
active → paused, resolved · paused → active, closed · resolved → closed · unopened → active · reopened → active. Any other pair is reported invalid_transition.
Each results[] entry has a result of:
- success — transitioned (from_status, to_status).
- noop — already at the target status (current_status).
- failure — not applied, with reason: not_found, invalid_transition (current_status), or stale_state (current_status).
| Status | Body | When |
|---|---|---|
| 400 | { "message": "..." } | Missing/invalid session_ids, invalid new_email_status / existing_email_status, or more than 100 ids |
| 401 | { "message": "Not Authorized" } | Missing/invalid credentials |
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json | |
| Accept | application/json |
| Key | Value | Type |
|---|---|---|
| subdomain | ||
| domain | string | |
| 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 |