SMS API

With Contact Center AI Platform (CCAI Platform), you can use the SMS API to handle inbound and outbound SMS messages.

Authentication

To use the SMS API, you need a credential.

To create a credential for the SMS API, follow these steps:

1. In the CCAI Platform portal, click Settings > Developer Settings > API Credential management.

2. Click the + Add API Credential button. An Add API Credential message will open.

3. Enter a Name for the Credential.

4. Click Create.

Outbound SMS API

The Outbound SMS API provides an endpoint for initiating outbound SMS messages. This lets you to programmatically send SMS messages to consumers.

There are three key points to consider when using this API:

• This service is not designed to send out tens of thousands of messages at once. The aim is event- driven messaging.

• Consumers can respond to the SMS message and initiate a support session.

• This API won't work if you need to send multiple SMS messages to the same number within the same day.

Use Cases

Outbound SMS API sample use cases are event-based. For example, if you want to notify the consumer that their order is ready for pickup AND give them the option to respond. An active session is created when an outbound SMS is sent; when the customer responds, he or she is routed to an agent.

The difference between this and Sessionless Outbound SMS API is that with sessionless, you only send the notification and if the consumer responds, they receive a default message (if configured) and are not routed to an agent.

Other potential use cases:

• Account login.
• Account activity.
• Important account usage events.
• Connected device issue detection.
• ETA Notifications for on demand services, like deliveries and ride shares.
• Appointment reminders.
• Proactive service or account alerts.
• Two factor authentication (requires customer has an existing code generator and service process).

Outbound SMS API endpoint

The base URI for this new endpoint is:

POST https://<subdomain>.<domain>/apps/api/v1/sms

Inbound SMS support

Should an environment want to support inbound SMS responses, the outbound number also needs to be set up as an inbound SMS number that is assigned to a queue. Each SMS phone number can only be assigned to one queue. For more information see: General SMS Chat Config.

If an end-user replies to an SMS configured this way, they will be brought to the SMS queue menu that the inbound SMS phone number is assigned to. For more information see SMS Messaging Chat Settings - Phone Number.

API Operations

This section outlines the API operations, body parameters and response codes.

Body and Params

The following fields should be included in the body of the API request:

Error and Success

{ 
  "id": 2415,
   "lang": "en",
   "chat_type": "SMS",
   "status": "selecting",
   "created_at": "2021-10-12T19:28:43.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": 131,
       "identifier": null,
       "out_contact_id": null
   },
       "photos": [],
   "videos": [],
   "transfers": [],
   "participants":
 [
       {
           "id": 5594,
           "type": "end_user",
           "status": "connected",
           "chat_id": 2415,
           "user_id": null,
           "end_user_id": 131,
           "chat_duration": null,
           "connected_at": "2021-10-12T19:28:43.000Z",
           "ended_at": null,
           "fail_reason": "nothing"
       }
   ],
   "offer_type": null,
   "offer_events": [],
   "answer_type": "manual",
   "outbound_number": "+14151234567"
}

SMS expiration

Outbound SMS messages are active as soon as they are sent.

Any SMS chat needs to end before a new SMS chat session can be established between a given outbound and consumer phone number. This includes outbound SMS messages sent using the API. Any outbound SMS will fail if there is an existing, active chat between the outbound and consumer phone numbers.

Automatic chat timeout options

Automatic chat timeout options are configured in the Settings > Chat > SMS Expiration & Global Timeout. This provides controls for how long a chat session will remain active if there is no activity or progress in the chat session flow.

Chat status distinctions

The following are distinctions between chat process state changes:

• Queue selecting state Chat ExpirationOutbound chats sent using the API are considered in the queue selecting state until the consumer replies

  Any chat session that has not progressed beyond the queue selection state. This includes sent outbound SMS messages to which a consumer has not replied. It is possible to define how long a chat can remain in this state before it expires (message sent & consumer does not respond within timer - chat expires).

• Unanswered SMS chat expiration (during hours of operation)The length of time a chat can remain unanswered in a queue before it expires within the set operation hours for the specific queue.

• Unanswered SMS chat expiration (during after hours)The length of time a chat can remain unanswered in a queue before it expires outside of the set operation hours for the specific queue.

• Outbound SMS chat timeout Outbound SMS chat sessions will automatically expire if there is no activity for [x] minutes.

Chat status details

• When an outbound SMS is sent using the API the chat is considered active but not connected

• These active outbound SMS chats are considered to be in the queue selecting state until the consumer replies

• Chats are considered connected once the consumer replies and an Agent is assigned to the chat

Chat status impact on applied timers

• Active chats sent using the API that have not had a response from the consumer are subject to the Queue selecting state timer

• Chats connected to an agent are subject to the Outbound expiration timer

• If a consumer replies to the initial message but an Agent is never assigned, the chat is not connected and is subject to the Unanswered Chat Expiration timer, inside or after operation hours

Example API message flow and statuses:

1. SMS message is sent using the API to consumer - chat is in queue selecting state and is not connected to an Agent

2. Queue selecting state chat expiration timer starts. Chat times out and is ended if the consumer does not reply within the timer threshold.

3. Consumer replies to chat - chat is now connected to an Agent.

4. Consumer sends last message - Outbound SMS chat timeout timer starts.

5. Outbound SMS chat timeout timer threshold reached - chat is ended.

No chat dismissal timer - for API initiated outbound SMS sessions, the chat dismissal timer does not operate so a chat dismissal event won't occur even after that chat comes in as an inbound chat when a consumer replies to the message.

Response Definition

The API responds with a single call object, as seen in the model from /calls.

Sessionless Outbound SMS API

CCAI Platform offers an Outbound SMS API that can support outbound SMS messages without any linked sessions.

This API call initiates non-session linked SMS messages that can be triggered during an existing workflow using CCAI Platform.

A sessionless sms is preferred in instances where just a one-time message is sent out to consumers and there is no need for a CRM ticket to open.

This Outbound SMS API provides the ability to send up to 500 messages per API call.

Use Cases

Common use cases for a sessionless SMS can include the following:

• One-time password setup.

• Verification code.

• Appointment reminders.

• Feedback links.

• Marketing or promotional messages.

Sessionless Outbound API and Outbound SMS API vary in that with Outbound SMS when a consumer responds, an active session is initiated and they can be routed to an agent. While they share similar use cases (delivery notifications, appointment reminders), the difference is in what happens when the consumer responds. They may receive a default don't reply notification with sessionless, but with outbound SMS, they will be routed to an agent.

Sessionless Outbound SMS API endpoint

The base URI for this endpoint is:

POST https://<subdomain>.<domain>/apps/api/v1/sessionless_sms

Add an API credential

1. In the CCAI Platform portal, go to Settings > Developer Settings > API Credential management.

2. Click the + Add API Credential button. An Add API Credential message will open.

3. Enter a name for the credential Name.

4. Click Create.

Sending SMS messages

To send a sessionless outbound SMS, call POST https://<subdomain>.<domain>/apps/api/v1/sessionless_sms and pass the following request parameters:

{
  "from_phone": <string>,
  "to_phones": <array[string]>,
  "messages": <array[string]>
}

API Responses

If the API call is successful, you will see:

• code: 200

• Request ID

  Make sure you log the request ID in your system records. In case you need to troubleshoot an issue, support will need the request ID to assist.

If the API call fails, you will see:

• code: 4xx

• Error message

SMS Limitations

• The API processes a maximum of 300 messages per minute.

• All unprocessed messages will expire in 2 hours.