SMS endpoints

Contact Center AI Platform (CCAI Platform) provides the Outbound SMS endpoint for the SMS channel.

Outbound SMS

Parameter	Required	Data Type	Definition
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"
}

Example requests and responses

The following sections provide example requests to the endpoint.

Create an outbound SMS chat with ticket ID

This example demonstrates how to create an outbound SMS to an end-user that is associated with a ticket ID.

Request

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

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

Create an outbound SMS chat and assign it to an agent using agent ID

This example demonstrates how to create an outbound SMS that is assigned to an agent based on the provided agent ID.

Request

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",
    "agentId": 1
}

Response: Create an outbound SMS chat and assign it to an agent using agentId

{
    "id": 114,
    "lang": "en",
    "chat_type": "Messaging (SMS)",
    "status": "assigned",
    "created_at": "2021-10-04T17:20:51.000Z",
    "queued_at": null,
    "assigned_at": "2021-10-04T17:20:53.000Z",
    "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": {
        "id": 1,
        "agent_number": 9,
        "email": "john.doe@foo.com",
        "name": "John Doe",
        "first_name": "John",
        "last_name": "Doe",
        "avatar_url": "https://foobar.com/johndoe"
    },
    "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"
        },
        {
            "id": 206,
            "type": "agent",
            "status": "connected",
            "chat_id": 114,
            "user_id": 1,
            "end_user_id": null,
            "chat_duration": null,
            "connected_at": "2021-10-04T17:20:53.000Z",
            "ended_at": null,
            "fail_reason": "nothing"
        }
    ],
    "offer_type": null,
    "offer_events": [],
    "answer_type": "manual",
    "outbound_number": "+16285550199"
}

Status Code: 200

Create an outbound SMS chat and assign it to an agent email

This example demonstrates how to create an outbound SMS chat session and associate it with an agent based on providing the agent email address.

Request

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",
    "agentEmail": "john.doe@foo.com"
}

Response: Create an outbound SMS chat and assign it to an agent using agentId

{
    "id": 114,
    "lang": "en",
    "chat_type": "Messaging (SMS)",
    "status": "assigned",
    "created_at": "2021-10-04T17:20:51.000Z",
    "queued_at": null,
    "assigned_at": "2021-10-04T17:20:53.000Z",
    "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"
        },
        {
            "id": 206,
            "type": "agent",
            "status": "connected",
            "chat_id": 114,
            "user_id": 1,
            "end_user_id": null,
            "chat_duration": null,
            "connected_at": "2021-10-04T17:20:53.000Z",
            "ended_at": null,
            "fail_reason": "nothing"
        }
    ],
    "offer_type": null,
    "offer_events": [],
    "answer_type": "manual",
    "outbound_number": "+16285550199"
}

Status Code: 200

Create an outbound SMS chat without ticket ID

This example demonstrates how to create an outbound SMS without associating it to a ticket ID.

Request

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

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

Error : chat_type needs to be provided

This example demonstrates the failure scenario where the 'chat_type' was not provided but is required.

Request

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

Response: Error : chat_type needs to be provided

{
    "message": "chat_type needs to be provided"
}

Status Code: 400

Error : valid chat type needs to be provided

This example demonstrates the failure scenario where the chat type needs to be provided but was missing.

Request

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

Response: Error : valid chat type needs to be provided

{
    "message": "valid chat type needs to be provided"
}

Status Code: 400

Error : SMS is not enabled

This example demonstrates the failure scenario where an outbound SMS is initiated but SMS is not enabled.

Request

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

Response: Error : SMS is not enabled

{
    "message": "SMS is not enabled"
}

Status Code: 400

Error : Outbound SMS is not enabled

This example demonstrates the failure scenario where an SMS session is initiated but fails as the SMS channel is not enabled.

Request

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

Response: Error : Outbound SMS is not enabled

{
    "message": "Outbound SMS is not enabled"
}

Status Code: 400

Error : end-user number is required

This example demonstrates the failure scenario where the end-user number was not provided but is required.

Request

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

Response: Error : end_user_number is required

{
    "message": "end_user_number is required"
}

Status Code: 400

Error : End-user number is invalid

This example demonstrates the failure scenario where the provided end-user number is invalid.

Request

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

Response: Error : end_user_number is invalid

{
    "message": "end_user_number is invalid"
}

Status Code: 400

Error : Non-US phone number not allowed

This example demonstrates the failure scenario where the provided number is not a US phone number and is prohibited.

Request

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

Response: Error : Non-US phone number not allowed

{
    "message": "Non-US phone number not allowed"
}

Status Code: 400

Error : Outbound number is required

This example demonstrates the failure scenario where the outbound number was not provided but is required.

Request

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

Response: Error : outbound_number is required

{
    "message": "outbound_number is required"
}

Status Code: 400

Error : Outbound number is invalid

This example demonstrates the failure scenario where the provided outbound number is invalid.

Request

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

Response: Error : outbound_number is invalid

{
    "message": "outbound_number is invalid"
}

Status Code: 400

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

Response: Error : outbound_number is not found

{
    "message": "outbound_number is not found"
}

Status Code: 400

Error : message is required

This example demonstrates the failure scenario where the message was not provided in the requires but is required.

Request

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

Response: Error : message is required

{
    "message": "message is required"
}

Status Code: 400

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

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