Call endpoints

The call API endpoints provide access to the call objects. A call object is created for every call that is made to and from Contact Center AI Platform (CCAI Platform).

The following are the call API endpoints:

Call object

The following is an example of the call object:

[
  {
    "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"
      }
    ]
  }
]

Call status definitions

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 using 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.

Call type definitions

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.

Common API response codes

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

Outbound call - end_user_number

Parameter Required Data Type Definition
call_tye TRUE String Call tye to create. "Voice Outbound (API)", "OutboundCall" (deprecated) are available for now
agent_email TRUE String Email address for the agent who will be assigned to the outbound call.
ticket_id FALSE String CRM ticket ID and it will dial to the end user who is tied to the ticket.
end_user_number FALSE String End user phone number which will be dialing. ticket_id has a higher priority than 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
lang FALSE String Language of the call. Uses ISO 639-1 codes. (Default: "en")

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"
}

Example request and responses

The following sections provide example requests to the endpoint.

Error : Agent is not available to take this call

This example demonstrates the failure scenario when the agent is not available to receive the call.

Request

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"
}
Response: Error : Agent is not available to take this call
{
    "message": "Agent is not available to take this call"
}

Status Code: 400

Create an outbound call with end-user number

This example demonstrates how to make an outbound call for a specific end-user number.

Request

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"
}
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

Create an outbound call with ticket ID

This example demonstrates the creation of an outbound call with a specific ticket ID.

Request

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"
}
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

Error : ticket ID or end-user number required

This example demonstrates the failure case where the ticket ID or end-user number are required but not provided.

Request

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"
}

Response: Error : ticket_id or end_user_number required

{
    "message": "ticket_id or end_user_number required"
}

Status Code: 400

Error : Not a valid agent email

This example demonstrates the failure when the provided email address for an agent is not valid.

Request

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"
}

Response: Error : Not a valid agent email

{
    "message": "Not a valid agent email"
}

Status Code: 400

Error : Agent email required

This example demonstrates the failure when an email address is not provided for the agent.

Request

Headers:

Key Value Description
Content-Type application/json

Body:

{
    "call_type": "Voice Outbound (API)",
    "end_user_number": "+1 205-123-4567",
    "lang": "en"
}

Response: Error : Agent email required

{
    "message": "Agent email required"
}

Status Code: 400

Error : Agent does not have access to make calls

This example demonstrates the failure when the specified agent is not permitted to be able to make outgoing calls.

Request

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"
}
Response: Error : Agent does not have access to make calls
{
    "message": "Agent does not have access to make calls"
}

Status Code: 400

Error : end_user_number is not well-formed

This example demonstrates the failure scenario where the provided end-user number is not correctly formatted.

Request

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"
}
Response: Error : end_user_number is not well-formed
{
    "message": "end_user_number is not well-formed"
}

Status Code: 400

Error : Contact not found

This example demonstrates the failure scenario where the provided contact does not exist.

Request

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"
}
Response: Error : Contact not found
{
    "message": "Contact not found"
}

Status Code: 400

Accepted : Need to choose an outbound number

In this example, the outbound call is accepted but the agent must choose the outbound number to use before the call is placed.

Request

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"
}
Response
{
    "call_type": "Voice Outbound (API)",
    "agent_email": "allen@somedomain.com",
    "end_user_number": "+1 205-123-4567",
    "lang": "en"
}

Status Code: 200

Error : Invalid call type

This example demonstrates the failure scenario where the call type provided is invalid.

Request

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"
}
Response: Error : Invalid call type
{
    "message": "Invalid call type"
}

Status Code: 400

Prompt the call adapter by multiple outbound numbers

In this scenario the call adapter is prompted with multiple outbound numbers.

Request

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"
}
Response
{
    "call_type": "Voice Outbound (API)",
    "agent_email": "admin@somedomain.com",
    "end_user_number": "+1 859-657-9625",
    "lang": "en"
}

Status Code: 200

Accepted : Agent must make an outbound call with ticket ID

This example demonstrates a request where the agent must make an outbound call based on the provided ticket ID.

Request

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

Outbound Call - ticket_id

Parameter Required Data Type Definition
call_type TRUE String Call type to create. "Voice Outbound (API)", "OutboundCall" (deprecated) are available for now
agent_email TRUE String Email address for the agent who will be assigned to the outbound call.
ticket_id FALSE String CRM ticket ID and it will dial to the end user who is tied to the ticket.
end_user_number FALSE String End user phone number which will be dialing. ticket_id has a higher priority than 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
lang FALSE String Language of the call. Uses ISO 639-1 codes. (Default: "en")

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"
}

Example request and responses

The following sections provide example requests to the endpoint.

Error : ticket ID or end-user number required

In this example the failure scenario of the ticket ID or end-user number are missing but required.

Request

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"
}

Response: Error : ticket_id or end_user_number required

{
    "message": "ticket_id or end_user_number required"
}

Status Code: 400

Error : Agent email required

In this example we show the failure scenario where the agent email is not provided but is required.

Request

Headers:

Key Value Description
Content-Type application/json

Body:

{
    "call_type": "Voice Outbound (API)",
    "end_user_number": "+1 205-123-4567",
    "lang": "en"
}
Response: Error : Agent email required
{
    "message": "Agent email required"
}

Status Code: 400

Create an outbound call with end-user number

In this example we show how to create an outbound call by providing the end-user number.

Request

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"
}
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_reaso": "not_voicemail",
    "deflection": "n_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

Error : Invalid call type

In this example we show the failure scenario where the call type provided is invalid.

Request

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"
}
Response: Error : Invalid call type
{
    "message": "Invalid call type"
}

Status Code: 400

Prompt the call adapter by multiple outbound numbers

In this example we show how to prompt the call adapter with multiple outbound phone numbers.

Request

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

Accepted : Agent must make an outbound call with ticket ID

In this example we show how to make an outbound call with a ticket ID and the agent accepts the request.

Request

Headers:

Key Value Description
Content-Type application/json
***Body:*** ```json { "call_type": "Voice Outbound (API)", "agent_email": "allen@somedomain.com", "end_user_number": "+1 205-123-4567", "lang": "en" } ``` ***Status Code:*** 202 #### Error : Agent does not have access to make calls In this example we show the failure scenario where a call creation request is submitted but the agent does not have access to be able to make outbound calls. ##### Request ***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"
}
Response: Error : Agent does not have access to make calls
{
    "message": "Agent does not have access to make calls"
}

Status Code: 400

Create an outbound call with ticket ID.

In this example we show the scenario of creating an outbound call with a ticket ID.

Request

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"
}
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

Accepted : Need to choose an outbound number

In this example we show the scenario where an outbound call request is created with the need to choose an outbound number and then is accepted.

Request

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

Error : Agent is not available to take this call

In this example we show the failure scenario where a call is created but the agent is not available to accept the call.

Request

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"
}
Response: Error : Agent is not available to take this call
{
    "message": "Agent is not available to take this call"
}

Status Code: 400

Error : end-user number is not well-formed

In this example we show the failure scenario where the provided end-user phone number is incorrectly formed.

Request

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"
}
Response: Error : end_user_number is not well-formed
{
    "message": "end_user_number is not well-formed"
}

Status Code: 400

Error : Not a valid agent email

In this example we show the failure scenario where the provided agent email is invalid.

Request

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"
}
Response: Error : Not a valid agent email
{
    "message": "Not a valid agent email"
}

Status Code: 400

Error : Contact not found

In this example we show the failure scenario where the provided contact couldn't be located.

Request

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"
}
Response: Error : Contact not found
{
    "message": "Contact not found"
}

Status Code: 400

Incoming Call

Parameter Required Data Type Definition
call_type TRUE String Call type to create. Use "Voice Inbound (API)" or "IncomingCall" (deprecated) to create an incoming call.
menu_id TRUE Integer The ID of the menu to attribute the call to. Only IVR and Web menu IDs are accepted.
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.
lang FALSE String Language of the call. Uses ISO 639-1 codes. (Default: "en")
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.
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.
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 won't be recorded. If the value is "recording_permission_granted", the call will be recorded.

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"
}

Example request and responses

The following sections provide example requests to the endpoint.

Error : end-user number is not well formed

In this example we show the failure scenario where an incoming call is created but that the provided end-user number is incorrectly formed.

Request

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"
}
Response: Error : end_user_number is not well formed
{
    "message": "end_user_number is not well formed"
}

Status Code: 400

Error : Menu is in 'manual redirection' state, can't accept calls

In this example we show the failure scenario where a call is routed to a menu ID but that the menu is in manual redirection state and as such cannot receive incoming calls.

Request

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"
}
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

Error : Invalid call type

In this example we show the failure scenario where an incoming call is created but the provided call type is invalid.

Request

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"
}
Response: Error : Invalid call type
{
    "message": "Invalid call type"
}

Status Code: 400

Error : menu ID is required

In this example we show the failure scenario where an incoming call is created but the provided menu ID is invalid.

Request

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"
}
Response: Error : menu_id is required
{
    "message": "menu_id is required"
}

Status Code: 400

Error : Only IVR and mobile menu IDs are permitted

In this example we show the failure scenario where an incoming call is created but the provided menu ID is not an IVR or mobile menu ID.

Request

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"
}
Response: Error : Only IVR and mobile menu IDs are permitted
{
    "message": "Only IVR and mobile menu IDs are permitted"
}

Status Code: 400

Create an incoming call with end-user number

This example demonstrates how to create an incoming call with a specific end-user number.

Request

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"
}
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

Error : Menu is in 'after hours' state, can't accept incoming calls

This example demonstrates the failure when the provided menu ID is in after hours state.

Request

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"
}
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

Error : Language is not available

This example demonstrates the failure request when the specified language is not available.

Request

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"
}
Response: Error : Language is not available
{
    "message": "Language 'fr' is not available"
}

Status Code: 400

Create an incoming call with ticket ID

This example demonstrates the request to create an incoming call with an associated ticket ID.

Request

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"
}
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

Error : Language is not found

This example demonstrates the failure when the provided language is not found.

Request

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"
}
Response: Error : Language is not found
{
    "message": "Language 'xy' is not found"
}

Status Code: 400

Error : menu_id is not found

This example demonstrates the failure when the provided menu ID is not found.

Request

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"
}
Response: Error : menu_id is not found
{
    "message": "menu_id 9999 is not found"
}

Status Code: 400

Error : menu_id is not well formed

This example demonstrates the failure when the provided menu ID is not correct.

Request

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"
}
Response: Error : menu_id is not well formed
{
    "message": "menu_id is not well formed"
}

Status Code: 400

Error : end-user number is required

In this example we show the failure scenario where an incoming call is created but the end-user phone number was not provided.

Request

Headers:

Key Value Description
Content-Type application/json

Body:

{
    "call_type": "Voice Inbound (API)",
    "lang": "en",
    "menu_id": 9,
    "recording_permission": "recording_permission_granted"
}
Response: Error : end_user_number is required
{
    "message": "end_user_number is required"
}

Status Code: 400

Scheduled call

Parameter Required Data Type Definition
call_type TRUE String Call type to create. Use "Voice Scheduled (API)" or "ScheduledCall" (deprecated) to create an scheduled call.
menu_id TRUE Integer The ID of the menu to attribute the call to. Only Mobile and Web menu IDs are accepted.
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.
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.
lang FALSE String Language of the call. Uses ISO 639-1 codes. (Default: "en")
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.
scheduled_at TRUE String Scheduled time of the call. Uses ISO 8601 format to a valid future time.
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 won't be recorded. If the value is "recording_permission_granted", the call will be recorded.

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"
}

Example request and responses

The following sections provide example requests to the endpoint.

Error : end_user_number is not well formed

This example demonstrates the failure due to the end_user_namber not being correctly formatted.

Request

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"
}
Response: Error : end_user_number is not well formed
{
    "message": "end_user_number is not well formed"
}

Status Code: 400

Error : Menu is in 'manual redirection' state, can't accept calls

This example demonstrates the failure when the specified menu ID is set to menu redirection and is unable to accept calls.

Request

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"
}
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

Error : Invalid call type

This example demonstrates the failure when a request is made and the call type is invalid.

Request

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"
}
Response: Error : Invalid call type
{
    "message": "Invalid call type"
}

Status Code: 400

Error : menu_id is required

This example demonstrates the request and response when a menu ID is not provided but is required.

Request

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"
}
Response: Error : menu_id is required
{
    "message": "menu_id is required"
}

Status Code: 400

Error : Only mobile and web menu IDs are permitted

This example demonstrates a request that fails when a menu ID is provided that is not a web or mobile menu ID.

Request

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"
}
Response: Error : Only mobile and web menu IDs are permitted
{
    "message": "Only mobile and web menu IDs are permitted"
}

Status Code: 400

Create a scheduled call with menu ID

This example demonstrates how to create a scheduled call with a specific menu ID.

Request

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"
}
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

Create a scheduled call with call ID

This example demonstrates how to create a scheduled call with a specific call ID.

Request

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"
}
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

Error : Menu is in 'after hours' state, can't accept incoming calls

In this example we show the failure scenario where a scheduled call is created but that the provided menu is out of hours and as such cannot receive incoming calls.

Request

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"
}
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

Error : Language is not available

This example demonstrates the failure when the specified language is invalid.

Request

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"
}
Response: Error : Language is not available
{
    "message": "Language 'fr' is not available"
}

Status Code: 400

Error : Language is not found

In this example we show the failure scenario where a scheduled call is created but that the language is invalid or not available.

Request

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"
}
Response: Error : Language is not found
{
    "message": "Language 'xy' is not found"
}

Status Code: 400

Error : menu ID is not found

In this example we show the failure scenario where a scheduled call is created but that the provided menu ID is invalid and not found.

Request

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"
}
Response: Error : menu ID is not found
{
    "message": "menu_id 9999 is not found"
}

Status Code: 400

Error : menu ID is not well formed

In this example we show the failure scenario where a scheduled call is created but that the provided menu ID is incorrectly formed.

Request

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"
}
Response: Error : menu_id is not well formed
{
    "message": "menu_id is not well formed"
}

Status Code: 400

Error : end-user number is required

In this example we show the failure scenario where a scheduled call is created but that the end-user number was not provided.

Request

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"
}
Response: Error : end_user_number is required
{
    "message": "end_user_number is required"
}

Status Code: 400

Error : scheduled_at is required

In this example we show the failure scenario where a scheduled call is created but that scheduled at value is missing but required.

Request

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"
}
Response: Error : scheduled_at is required
{
    "message": "scheduled_at is required"
}

Status Code: 400

Get reserved data attributes during a call

Endpoint

Method: GET
Type: RAW
URL: https://{subdomain}.{domain}/apps/api/v1/calls/:id/customer_flag

Example request and responses

This section contains an example request and response for the endpoint.

Success

This example shows a successful call.

Request

URL variables

Key Value Description
id integer (Required)
Response
{
    "verified_customer": "boolean",
    "bad_actor": "boolean",
    "repeat_customer": "boolean"
}

Status code 0

Update reserved data attributes during a call

Endpoint

Method: PATCH
Type: RAW
URL: https://{subdomain}.{domain}/apps/api/v1/calls/:id/customer_flag

URL variables

Key Value Description
id integer (Required)

Body

{
    "verified_customer": "boolean",
    "bad_actor": "boolean",
    "repeat_customers": "boolean"
}