Apps API Documentation

Stay organized with collections Save and categorize content based on your preferences.

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:

https://customer.rest.of.url.com

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

Endpoints


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
email 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