SMS

SMS Messaging: Overview

For pricing and implementation contact Support.

Overview

SMS Messaging is a quick and easy way to chat with your consumers via text message. Because of its "anytime, anywhere" availability, SMS typically has higher engagement rates compared to other communication channels.

SMS Messaging enables you to do the following:

  • Provide a seamless text messaging experience for your consumers

  • Chat in multiple languages

  • Receive images and videos from consumers

  • Proactively reach out to consumers using outbound SMS

  • Create flexible queues that route consumers to the correct agent

  • Transfer chats between agents

  • Implement multiple SMS support phone numbers for different business lines

Consumer experience

Receiving support through SMS should be like any other texting experience:

  1. A consumer sends a text to your incoming SMS support phone number or short code.

  2. The consumer receives an opt-in message, which covers requirements set forth by consumer privacy laws.

  3. If your SMS queue has multiple menu options, the consumer receives navigation instructions.

  4. An agent assigned to the queue responds to the consumer.

Agent experience

SMS chats are handled by agents in the same Contact Center AI Platform (CCAI Platform) Adapter as Mobile and Web chats. From an agent's perspective, the experience is similar but there are notable differences related to consumer privacy.

Agent stats

SMS stats are included in the following metrics:

  • Group stats:

    • Your Stats

    • Team Average

  • Individual stats:

    • Chats Answered

    • Average Duration

Configuring SMS Chat

Reach out to your CSM or Delivery team member to get started with SMS. Once you have access, complete the following steps.

Step one: Chat settings

  1. Configure Global chat settings:

  • Dismissed chat auto response

  • Chat shortcuts

Turn on SMS Chat

Configure SMS expiration and timeout settings

Configure SMS commands

Add SMS phone numbers

For details, see SMS Messaging: Chat Settings

Step two: Queue settings

  1. Set up SMS queues

  2. Configure queue level settings:

  • Hiding SMS queues

  • Timeout and expiration settings

  • System messages

  • Menu keywords

Assign SMS numbers to queues

Assign agents and teams to SMS queues

For details, see SMS Messaging: Queue Settings

SMS Capabilities

Get a high-level overview of all the platform SMS features' capabilities using the matrix below.

Blended SMS Outbound SMS APIS (session based and session-less)
Wait time SMS In call SMS SMS channel Pre-session SMS deflection Outbound SMS API Session-less SMS API
The platform sends predefined messages x x x x
Agent can send custom messages x x
Agent can send predefined messages x x
Requires active IVR call x x
Starts with IVR, switches to SMS x
EWT threshold setting x x
Associated with an active session x x x x x

CRM updates

When an incoming SMS chat is connected, or an outbound SMS chat is successfully sent, the CRM record is created or updated based on the consumer phone number.

  • If the phone number does not exist in the CRM, a new contact is created.

  • If the phone number exists in the CRM and is associated with a single contact, the CRM record is updated.

  • If the phone number is associated with multiple contacts, the agent is prompted to select an existing contact or create a new contact.

The following information is posted to the CRM record:

  • Chat ID, language, queue

  • Transfer began, failed, ended

  • Chat ended

  • Pictures and videos sent by the consumer

The chat transcript includes all SMS messages sent by the consumer, the agent, and the system (including queue selection messages & greeting messages.)

Monitoring and Reporting

Monitoring

Chat data is available on the following monitoring pages:

Agents > Assigned Channel = Chats

Displays aggregated real-time data from all chat channels.

Chats > Ongoing Chats, Future Chats, Previous Chats

  • Queue column identifies the chat channel

  • Start Type column identifies whether the chat was Manual Answer, Auto Answer, or Outbound.

Queues > Chats

Queue Name column identifies the chat channel

Type Breakdown column identifies the type of chat

Reporting

The following reports provide SMS Chat data:

  • Users & Teams > Chat report

  • Calls & Chats > Chat Report

  • Queues > Chat Report

SMS Chat data is also identified in both Performance Metrics and Individual Chat History reports.

Performance Metrics: The Type Breakdown column identifies Total SMS, Total Incoming SMS, and Total Outbound SMS.

Individual Chat History: The Type column identifies SMS and Outbound SMS.

API

SMS Messaging sessions can be tracked using the Chats resource.

SMS Product Line Overview

CCAI Platform offers several features and functionalities that leverage the SMS channel. Each option has specific business needs it can solve and slightly different requirements and functionality.

  • Blended SMS: Requires an active IVR call for the duration of the SMS chat interaction.

    • In-call SMS

    • Wait time SMS

  • SMS Channel: SMS chats can be inbound and outbound independent of an IVR call.

    • SMS inbound/outbound: Phone number is provided to consumers and they can initiate SMS chat sessions via text messages on their mobile device. Agents can also initiate outbound SMS chats.

    • Pre-session SMS Deflection: Caller dials into the IVR and then ends the IVR call to switch to the SMS channel.

  • SMS to launch App: Requires the Mobile SDK to already be installed in your company's app(s) and allows agents to prompt the opening of the app to utilize SmartActions.

Blended SMS

Requires an active IVR call for the duration of the SMS chat interaction.

Wait time SMS

This feature allows your team to send SMS messages to callers who are waiting to be connected to an agent. By enabling this feature, the caller will be able to provide necessary and important information to the agent via SMS. Ultimately, by enabling your callers to provide information about the reason for their call, the agent can leverage the information collected for a faster resolution time.

In Call SMS

During IVR calls, messages can be exchanged allowing agents to receive photos, videos, and screenshots from consumers, as well as exchange texts, via MMS and SMS.

For more information see SMS Blending

SMS Channel

SMS chats can be inbound and outbound independent of an IVR call.

SMS Messaging is a quick and easy way to chat with your consumers via text message. Implement multiple SMS support phone numbers for different business lines.

Pre-session SMS: Caller dials into the IVR and then ends the IVR call to switch to the SMS channel

Pre-session SMS Deflection enables you to offer SMS chat support as an alternative option for IVR callers before the call is connected to an agent. This feature is configured at the IVR queue level and can be offered to callers conditionally based on the estimated wait times.

For more information see Pre-session SMS Deflection

Send SMS to Consumers to Download Your App

This feature allows agents to utilize SmartActions by prompting the consumer to launch their app for your company. Once the app is installed and launched, Agents can use these SmartActions with a consumer during an IVR call.

For more information see Send SMS to Consumers to Download Your App and Agent: Send SMS to Launch App for SmartActions during an IVR call.

SMS Messaging: Chat Settings

Overview

To configure SMS Chat, start by reviewing the global and SMS chat settings in the CCAI Platform portal.

Configuring global chat settings

Go to Settings > Chat and review the Global Chat Settings, which apply to all chat channels (Mobile, Web, and SMS):

Dismissed chat auto response

If you turn on the Inactive Chats dismissal feature, a default Dismissed Chat Auto Response is provided. This response is sent only when a consumer replies to a dismissed SMS chat.

Chat shortcuts

In order to help agents comply with consumer privacy regulations, create at least one chat shortcut that covers the requirements of an opt-in message. Agents should use this shortcut as their first message when sending an Outbound SMS chat.

  1. Scroll down to the Chat Shortcuts section and click View all shortcuts:

  2. Click Add Shortcut:

  3. Optionally enter a Category if you want to group this shortcut with others.

  4. Enter a Shortcut Keyword.

  5. Enter your Message text and click Save.

For more information on chat shortcuts, see Chat settings.

Turning on SMS Chat

  1. Go to Settings > Chat.

  2. From the left navigation, click SMS.

  3. Toggle Use SMS Chat to On:

  4. If you want agents to have the ability to initiate SMS chat sessions, scroll down to Outbound SMS and toggle On:

Configuring SMS expiration and timeout settings

SMS Chat has its own expiration and timeout settings:

Chat expiration applies to only incoming SMS chats. These global settings are overridden if you set them on the queue level.

Configuring SMS Commands

In order to comply with consumer privacy laws, certain SMS command words are preconfigured and cannot be changed, as shown in the first three rows of this table:
Consumer command Behavior
STOP, STOPALL, UNSUBSCRIBE, CANCEL, END, QUIT Turn off all messages and be placed on a do not contact list
START, YES, UNSTOP Opt in to receiving messages. If previously placed on a do not contact list, be removed from that list
HELP, INFO Receive support contact information
BACK (configurable) Go back to the previous menu selection
EXIT (configurable) End the chat. If "exit" is the first message sent by the consumer, no chat is created

Two default command words, BACK and EXIT, are provided to help consumers navigate SMS queues. Administrators can change or add to these keywords:

  1. Go to Settings > Chat.

  2. From the left navigation, click SMS.

  3. Go to SMS End User Commands.

  4. Enter command words then click SET COMMANDS:

Use any combination of characters as long as they don't conflict with queue names or protected words, as listed in the above table.

Adding SMS phone numbers

Add and verify the numbers on the Phone Number Management page.

Upon your first-time activating a valid US (+1) phone number, the following section displays. Enter your number in the field and click Activate. This section does not display if you have already enabled SMS messaging and entered a valid number.

Keep these points in mind:

  • If you are using the In Call SMS feature, you cannot reuse those phone numbers for SMS Chat.

  • Each incoming number can be assigned to one queue only. Each queue can have multiple incoming numbers, as long as each number is unique.

  • Incoming numbers can be used as outbound numbers but not vice versa.

  • Outbound numbers can be assigned to multiple queues and each queue can have multiple outbound numbers.

  • SMS numbers can have different sending limits.

To add the SMS phone numbers:

  1. Go to Chat > Settings.

  2. From the left navigation, click SMS.

  3. Go to SMS Phone Number Settings and click Phone Number Management:

  4. On the Phone Number Management page, click Add a Number:

  5. Add the unique phone number including country code:

    • Leave Set as the global outbound number unchecked.

    • Add a Label that helps you identify the number.

    • Repeat for each phone number.

  6. Select all of your new phone numbers and click Verify. A number must be verified before you can assign it to a queue.

    Once the system has verified a phone number, the status is displayed as, Verified for Only SMS Messaging.

SMS Blending: Wait Time SMS

Overview

This feature allows your team to send SMS messages to callers who are waiting to be connected to an agent. By enabling this feature, the caller will be able to provide necessary and important information to the agent via SMS. Ultimately, by enabling your callers to provide information about the reason they are calling in, the agent can leverage the information collected for a faster resolution time.

Key features and advantages

  • Sending preset, custom text messages while the caller is waiting in queue on IVR calls via SMS.

  • Make the best use of your caller's time by using time spent waiting in queue proactively.

  • Opening the SMS channel for the caller to send multimedia messages with relevant content.

  • By enabling the customer to provide crucial information to agent/company before connecting with an agent, you can expect a decrease in average handle time.

User flows

The caller and the agent have a unique experience while using this feature. While the agent's experience is always the same, the caller has the option of whether or not they will take part in the SMS exchange.

Caller

  1. Caller dials into your IVR.

  2. Caller enters the queue after selecting the queue or being placed in a queue by a direct access point. More info in Direct Access Points.

  3. Overcapacity limit has been reached by the queue (settings can be adjusted in Call settings).

  4. Caller is played the configured overcapacity options (settings can be adjusted in Call Settings) and selects "keep waiting."

    • IF anything but "keep waiting" is selected, the caller will not continue on this flow (for example if Callback is selected).

  5. Caller is played Ask for Consent to Send Wait Time SMS message.

    • IF response = No, the caller stays in queue and is not asked again.

    • IF response = YES, the "Wait Time SMS Sent" message is played.

  6. Caller is sent an SMS with the content of Global Wait Time SMS Message Sent to Caller's Device message.

  7. The caller can reply with any number of text or multimedia messages.

  8. The call is assigned to an agent and connected with the information they shared available to the agent in the agent's CRM ticket.

User flow: agent

  1. Agent is assigned a call.

  2. Agent will see a banner on the call adapter alerting "Wait Time SMS Received."

  3. Agent can click on the green banner to view the messages.

    OR

  4. Agent can view the messages sent as comments in the CRM ticket.

CCAI Platform portal configuration

Steps to set up this feature:

  1. Enable and configure global setting

  2. Set up messages and configurations

  3. Enable queue level settings

Enable and configure global settings

  1. Go to Settings > In Call SMS.

  2. Enable In Call SMS, and Wait Time SMS.

  3. The interval at which the wait time SMS consent message will be played is based on the global announcement setting. Click Edit announcement intervals and you will be taken to the Call Settings page. This setting is called Universal Caller Announcement Intervals.

  4. Check the box to limit the number of times the SMS consent message is played. When enabled, set the threshold for the number of times the caller will hear the message.

  5. For more specific controls of when callers should receive the option to use Wait Time SMS, enable the below option by clicking the box. Then set the minimum and maximum wait time that needs to be reached, based on estimated wait time for the caller to hear the option to use Wait Time SMS.

CRM record creation and abandoned call settings

CCAI Platform creates a record when the call is initiated, and not before. Depending on your settings (Operation Management), CCAI Platform may create a CRM record for all abandoned calls, so even if no call takes place you have a record of this.

In an ideal scenario, the caller will call in, choose to participate in Wait Time SMS, and the messages will be shared with the Agent - however, this is not always how things play out. In the scenario where the caller chooses to participate in Wait Time SMS, then abandons the call before being connected to an agent, you can choose to create a ticket if the system otherwise wouldn't create one.

  1. Go to Settings > Operation Management.

  2. To enable ticket/case creation for abandoned calls only when SMS has been received, mark the box next to Create CRM ticket for abandoned calls and also mark Abandoned calls with SMS data.

Setting up messages

Default message setup is made from the In Call SMS settings, but can also be customized for each queue. Individual queue settings/messages will override general messages and settings.

  1. Go to Settings > In Call SMS .

  2. If you are using multiple languages in your IVR, repeat the below steps for each active language you will be using SMS for. Please reference the Global Numbers section of In call SMS for more information.

  3. Set up the Ask for Consent Message by either entering text to be read to the caller, or by uploading a custom file by clicking on Upload in the bottom-right. The message must contain two options for the caller - "press 1" to approve SMS messages be sent to their phone, and "press 2" to deny SMS messages be sent to their phone. More information on the Consent message below this section.

  4. Set up the Wait Time SMS Sent message by either entering text to be read to the caller, or by uploading a custom file by clicking on Upload in the bottom right. The content of this message should inform the caller that they will receive a message based on the phone number they dialed in from, and to check that message for the next steps.

  5. Compose the text message which will be sent once the caller accepts the SMS message channel by entering text in the text box. Use your brand name, and ask for important details as specifically as possible.

  • The call is deflected to other option rather than "keep waiting"

  • Wait Time SMS is disabled globally or for the selected queue

  • Caller already allowed or denied Wait Time SMS

  • The max number of tries is reached

Caller text input after consent message

Below you will find how the caller's text responses are received and processed by CCAI Platform.

  • Digit=1, the caller has allowed SMS

    • wait_time_sms_status = allowed

      wait_time_sms_status = allowed

    • Send SMS

    • Call stays in queue

  • Digit=2, the caller has denied SMS

    • wait_time_sms_status = denied

    • Call stays in queue

  • Other Digits, considered wrong selection

    • "Incorrect Selected Number" message is played

    • Consent message repeated

  • No Digits, caller has made no selection

    • 10 seconds response time is allowed

      10 seconds response time is allowed

    • wait_time_sms_status = no_response

    • Call is sent back to queue

    • If applicable, message will be repeated at the interval set by the Universal Caller Announcement setting.

Enable and configure queue-specific settings

  1. Go to Settings > Queue > IVR > Edit / View button

  2. Click the name of the queue to select it.

  3. Toggle In Call SMS to On (if it isn't already).

  4. Mark the checkbox to enable Wait Time SMS.

  5. If you want to use a queue-specific setting and messages, click Customize for this queue. There you can customize:

    - Wait Time SMS based on estimated wait time (Custom)

    - Audible Messages

    - The Wait time SMS message

SMS Blending: Enabling and Configuring In Call SMS

Overview

SMS Blending enables SmartActions during IVR calls for MMS capable numbers, allowing agents to receive photos, videos, and screenshots from consumers, as well as exchange texts, via MMS and SMS respectively.

Key features and details

  • SMS usage is tracked in performance metrics, call history reports, and API data

  • Sending messages

    • Agents can send preset or custom text messages during IVR calls via SMS (without the caller having a mobile app installed)

    • SMS messages can only be received by phones that can receive and send text messages

      • Agents should confirm consumer's device is capable of receiving SMS before initiating the session

    • Agents can send text messages and links to mobile-friendly webpages (no pictures or videos at this time)

  • Receiving messages from Callers

    • Text messages, videos, and images (jpg, png, and gif) can be received

Enabling and configuring

  1. Go to Settings > In Call SMS.

  2. Enable In Call SMS by toggling the switch to ON.

Adding SMS phone numbers

Add and verify the numbers on the Phone Number Management page.

Upon your first-time activating a valid US (+1) phone number, the following section displays. Enter your number in the field and click Activate. This section does not display if you have already enabled SMS messaging and entered a valid number.

Keep these points in mind:

  • If you are using the In Call SMS feature, you cannot reuse those phone numbers for SMS Chat.

  • Each incoming number can be assigned to one queue only. Each queue can have multiple incoming numbers, as long as each number is unique.

  • Incoming numbers can be used as outbound numbers but not vice versa.

  • Outbound numbers can be assigned to multiple queues and each queue can have multiple outbound numbers.

  • SMS numbers can have different sending limits.

To add the SMS phone numbers:

  1. Go to Chat > Settings.

  2. From the left navigation, click SMS.

  3. Go to SMS Phone Number Settings and click Phone Number Management:

  4. On the Phone Number Management page, click Add a Number:

  5. Add the unique phone number including country code:

    • Leave Set as the global outbound number unchecked.

    • Add a Label that helps you identify the number.

    • Repeat for each phone number.

  6. Select all of your new phone numbers and click Verify. A number must be verified before you can assign it to a queue.

    Once the system has verified a phone number, the status is displayed as, Verified for Only SMS Messaging.

Set up feature options and messages

Non-US phone number Configurations

As outlined in the CCAI Platform portal, there may be conflicts when sending messages out to non-US numbers, based on the global carrier's unique settings. Since it's not possible for CCAI Platform to know or predict compatibility, you choose to enable or disable this feature for non-US numbers.

Mark the settings below for either In Call SMS or Wait Time SMS, respectively, then click Set.

Preset messages by Admins

Messages set up in the CCAI Platform portal will be available for all Agents from within the Chat Adapter. The Agent will see the list of created messages and be able to click on each message to send when appropriate.

  1. Go to Settings > In Call SMS.

  2. Scroll to the In Call SMS Session > Preset Messages by Admin section.

  3. When enabled, the agent will only be able to select from the messages created by an Admin.

  4. To add new messages, first select the language of the message. If you are using multiple languages in your IVR, repeat the below steps for each active language you will be using SMS for.

  5. Click Add SMS Message.

  6. Enter the label of the SMS message as the Agent will see it in their widget/adapter, then enter the SMS message content and click Save. Be mindful of the character count of the message as most SMS messages cannot contain more than 160 characters in one message.

  7. Repeat these steps for each message you would like to be available for agents.

Custom messages by Agent

Aside from the messages set up by an admin, the Agent can also create their own text-based messages during the SMS exchange. To enable this feature, select the checkbox and click Set.

Max characters per SMS message the agent can send: currently 918 characters.

Finished In Call SMS Session Messages

SMS sessions are ended as soon as the call has ended, regardless of the reason for the call termination, and no new messages will be added to the ticket/case or available in the agent Adapter. Below are two optional but recommended messages that can be customized and sent by default after the SMS session has completed.

  1. Go to Settings > In Call SMS.

  2. Click the checkbox to enable and select the language for the Closing SMS message.

  3. Compose the Closing SMS message to be sent to the caller as soon as the call has ended.

  4. Click Set to save the message and settings.

  5. Click the checkbox to enable and select the language for the SMS Auto Response message. This message will prevent any confusion that the caller may have if they try to start a new conversation or continue the existing conversation after the call has ended.

  6. Compose the SMS Auto Response message to be sent to the caller if they try to send any messages after the call has ended.

  7. Click Set to save the message and settings.

Individual queue configuration

Once enabled for the environment, you can configure this feature on a queue-by-queue basis. Enable the feature for your desired queue by going to **Settings > Queue > IVR, then clicking on the specific queue to enable.**

Outbound SMS API

Overview

The Outbound SMS API provides an endpoint for initiating outbound SMS messages. This enables 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 will not 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 Session-less Outbound SMS API is that with session-less, 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/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**

Authentication

Add an API credential

  1. Go to Settings > Developer Settings > API Credential management.

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

  3. Enter the desired Name.

  4. Click Create.

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

Body and Params

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

Field Name

Type

Required

Description

Values

Notes

agent_id

Integer

No

The agent corresponding to this ID will be assigned to a new chat if a chat does not exist between the provided numbers. If the agent is connected to an existing chat the message will be sent on their behalf.

agent_email

String

No

The agent's email address.

chat_type

String

Yes

SMS message

SMSAP

chat_subtype

String

Yes

api_initiated

end_user_number

String

Yes

Number the text message is to be sent to

Validation: valid phone number; e.g.: "+18882468888" for a US phone number

outbound_ number

String

Yes

Outbound phone number to be used for sending the SMS message

Validation:a)phone number needs to be an SMS phone number associated with the tenant, b) missing phone number, c) phone number is incorrect format, e.g.: "+18882468888" for a US phone number

message

String

Yes

SMS message to be sent to consumer

Long messages: break long messages into multiple messages (should be covered in existing outbound SMS capability)

Validation:

a) missing message, b) message exceeds maximum number of characters (by [x])

ticket_id

id

No

Will associate session to a specific CRM ticket ID

Note: invalid ticket IDs will be ignored.

Error and Success

Case

Expected Result

Copy

SMS service is enabled

Outbound SMS service is enabled

chat_type value is 'OutboundSMSAPI'

end_user_number is provided and well formed

outbound_number is provided and well formed

For non US phone numbers: non US phone number is enabled

Message is provided

No active chat between outbound_ number and end_user_number

success

 (200) Success Response Sample { "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" }

Agent id and agent email are provided

error

Only one of `agent_id` or `agent_email` can be provided.

Agent id or agent email is provided

Agent is not connected to existing chat

error

Outbound SMS failed. Agent is not connected to chat.

SMS service is not enabled

error

"SMS service is not enabled".

Outbound SMS service is not enabled

error

"Outbound SMS service is not enabled"

chat_type is not provided

error

"chat_type needs to be provided"

chat_type is provided but is not set to 'sms'

error

"Valid chat_type needs to be provided"

end_user_number is provided but not well formed

error

"end_user_number is invalid"

(note: valid phone number; e.g.: "+18882468888" for a US phone number)

end_user_number is not provided

error

"end_user_number is required"

outbound_number is provided but not well formed

error

"outbound_number is invalid"

(note: valid phone number; e.g.: "+18882468888" for a US phone number)

outbound_number is provided but does not exist for that tenant

error

"outbound_number is not found"

outbound_number is not provided

error

"outbound_number is required"

outbound_number is a non US phone number and 'non US phone number service' is not enabled

error

"Non US phone number service is not enabled"

Note:depends on Non-US phone number setting at Settings > In Call SMS > Non-US Phone Number Configurations

Message is empty

error

"message is required"

Active chat between outbound_ number and end_user_number

error

"Outbound SMS failed. Consumer is already in an active SMS session."

ticket_id is filled but does not exist in CRM

error

"Ticket is not found"

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 via 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 via 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 via 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 via 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 via 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 currently never kicks in 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.

Session-less 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 via CCAI Platform.

A session-less 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 enables you to send up to 500 messages per API call.

Use Cases

Common use cases for a session-less SMS can include the following:

  • One-time password setup

  • Verification code

  • Appointment reminders

  • Feedback links

  • Marketing/Promotional messages

Session-less 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 do not reply notification with session-less, but with outbound SMS, they will be routed to an agent.

Session-less Outbound SMS API end-point

The base URI for this end-point is:

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

Add an API credential

  1. Go to Settings > Developer Settings > API Credential management.

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

  3. Enter the desired Name.

  4. Click Create.

Sending SMS messages

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

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

Field Name

Type

Required

Description

Notes

from_phone

String

Yes

The phone number from which the messages will be sent.

Must be a valid US number.

The API call will return an error if:

  • the phone number is not an SMS phone number associated with the tenant

  • the from_phone field is empty

  • the phone number does not follow the correct format. For example, the following number is a valid US phone number:

    "+18882468888"

to_phones

Array [String]

Yes

The phone numbers to which the messages will be sent.

To ensure the API call succeeds:

  • Confirm you have a valid phone number, such as "+18882468888"

The maximum count of phone numbers is 100 per API call.

messages

Array [String]

Yes

The messages to be sent.

The maximum count of separate messages you can send is 5.

Each message has a limit of 320 characters and cannot exceed that limit.

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.

Send SMS to Consumers to Download Your App

Overview

SmartActions (receiving photos, videos, screenshots, verifying customers, and receiving text input) are not typically available during an IVR call. You can use SmartActions by prompting the consumer to launch their app for your company. Once the app is installed and launched, you can use these SmartActions with a consumer during an IVR call.

The Agent on the IVR call will need to take action to either send an SMS that provides a link to download or a link to launch the app. You may have an indicator in your CRM, or the Agent can ask the caller if they already have the app installed on a device they have nearby.

*If you are using multiple mobile apps, these settings are now available in Settings > DeveloperSettings > Multiple Mobile Apps.*

Requirements for setup

  • Existing iOS and or Android mobile app with the CCAI Platform SDK integrated

  • Deep links are required from your mobile development team for iOS and Android app to open URLs (steps 4 and 6 below). Deep-linking allows for a consumer to tap on the link from their mobile device and the device will then launch the already installed app.

CCAI Platform portal configuration

In order for Agents to have an SMS to send with your app links, first the download and launch link need to be configured in the CCAI Platform portal. These links will be added to the SMS messages Agents send, Agents will not need to enter the link manually.

  1. Go to Settings > Operation Management.

  2. Enables sending SMS to consumers to download your app by toggling the switch to On.

  3. iOS App Store URL: Insert the iOS App Store URL for your app. This link can be provided by your mobile development team or gathered directly from the App store.

  4. iOS App Open URL: Insert the deep-link to your iOS app. This link should be supplied by your mobile development team.

  5. Google Play Store App Store URL: Insert the Google Play Store URL for your app. This link can be provided by your mobile development team or gathered directly from the Play Store.

  6. Android App open URL: Insert the deep-link to your Android App. This is supplied by your mobile development team.

  7. Set: Saves #2-6.