Contact Center AI Platform (CCAI Platform) provides the [Outbound SMS](https://docs.cloud.google.com/contact-center/ccai-platform/docs/apps-api-sms#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