Dashboard

The dashboard will contain the information about the SMS that you have sent using 8x8. Below is a view of the entire dashboard page, in the following sections we will break down each section's contents.

Statistics

The Dashboard for SMS will show you the following statistics over the given time period which is set to the current week.

Below is a screenshot of the statistics section in the Dashboard.

Charts

There will be the following 3 charts available:

• SMS: Shows the amount of SMS sent across the given time period for each of the days

• Delivery Rate: Shows how the delivery rate changes across the given time period for each of the days

• Cost: Shows how the average cost of the SMS changes on a given day

Destination Countries

This section will break down the amount of SMS sent to each country as well as the SMS operator responsible for sending the message.

Campaigns

This area will show the amount of SMS campaigns sent and a link to view the individual details of each campaign.

Clicking on the campaigns link will take you to the Campaigns tab of the Dashboard which will contain information about individual campaigns sent.

Reports

The Reports page for SMS will show a further breakdown as compared to the dashboard and allow you to further filter the data. You will also be able to export the information as CSV file from the page to import the data into your own analytics systems.

Besides containing statistics for messages sent via the SMS API, it also contains information relevant for the Verification API, SMS Engage and Short URLs.

SMS Messages

The SMS Messages section will allow you to filter your SMS sent by the following options

Daily Report

It will also feature a Daily Report Section where it will have the following stats about messages.

Here is a list of the columns in the Daily Report and their meaning.

Export

You can choose to export the daily report immediately which will send a URL link to the specified email.

There is also the option to schedule an export to be sent periodically to the specified email.

SMS Conversions

This reports page allows you to see conversions relevant to the Verification API, specifically for SMS sent using the service.

The main graph will show how many SMS have been sent using the service over time and what percentage have been successfully converted. This is useful for OTP use cases to track if there are any OTP conversion issues for example.

There is also a more detailed reports section on the same page which will show a detailed breakdown of the status of each verification attempt, conversion rate and cost. You can also export the report as a CSV file as well.

SMS Engage

This section will contain statistics on SMS Engage Surveys sent. Please see the section on SMS Engage for more details.

Short URLs

8x8 offers a URL Shortening service that can redirect from your chosen domain to our URL shortening domain. This feature allows us to offer click tracking. These Short URLs can be sent as part of SMS API messages or SMS Engage Surveys that you send with 8x8. The statistics for click tracking can been see in this section of the Reports.

For further details on how to set up Short URLs, reach out to your Account Manager.

Logs

SMS Message List

Below is the SMS logs in the Connect Dashboard which shows a record of the SMS that were sent and received by this account.

The SMS Logs above shown shares information about individual SMS messages sent including:

Individual SMS Record

Inside each SMS record, the following information is available:

This table shows a description of each of the fields in the SMS record.

POST requests are sent by the 8x8 platform in JSON format to the webhook URL configured for your account.

📘

You can configure a default webhook URL for your account by contacting 8x8 support team.

Webhook Validity Period

If we do not receive a response for the SMS engage survey promptly, our platform will continue checking for up to 48 hours. If the response is recorded after 48 hours, there will be no SMS engage response webhook sent.

Webhook format

Request body description

Template variable object

Answer object

Sample of SMS Engage webhook

{
"umid":"84e7ee9a-5c41-e811-814c-020897df5459",
"surveyId":"test-surveyid",
"surveyStartedAt":"2018-04-16T09:59:48Z",
"surveySubmittedAt":"2018-04-16T10:00:14Z",
"templateVariables":[
{
"name":"firstname",
"value":"John"
},
{
"name":"order_nr",
"value":"1010101"
}
],
"answers":[
{
"questionId":"3",
"answerId":"10003",
"question":"Dear [url('FirstName')],<br />\nOrder [url('order_nr')] was found as a duplication, please confirm below or your order will be cancelled",
"answer":"Cancel Now"
},
{
"questionId":"16",
"answerId":null,
"question":"Full Name",
"answer":"John"
},
{
"questionId":"4",
"answerId":"10005",
"question":"Do you confirm your response?",
"answer":"Yes"
}
]
}

📘

The number of questions and their types will depend on the survey you have in place for your SMS Engage campaign.

SMS - SMPP TLVs

📘Optional Parameters are fields, which may be optionally included in an SMPP message. (SMPP v3.4 Spec, section 5.3). These fields contain 3 parts, namely Tag, Length and Value.

Some TLVs are defined by the SMPP protocol and then there is room for vendors to create their own TLVs. Below are the vendor specific TLVs defined by 8x8. These TLVs are supported only when using SMPP to make requests to 8x8

Mo Message Id

A unique 36 alphanumeric character string (UUID v4) to identify the MO message at the SMSC. This message ID can be used when contacting 8x8 support regarding the message.

Destination Mcc and Destination Mnc

Mobile Country Code (mcc) and the Mobile Network Code (mnc) values of the destination phone number corresponding to a particular DLR (in Delivered state).

8x8 supports SMPP (Short Message Peer-to-Peer), a mature binary protocol widely used in carrier-grade SMS infrastructure. Unlike REST APIs, SMPP uses persistent TCP connections and is designed for sustained, high-volume message throughput with low latency.

This connection method is a good fit if you are running enterprise messaging software, an SMS gateway, or any platform that natively speaks SMPP. For new integrations without an existing SMPP requirement, the 8x8 SMS API offers a simpler REST-based alternative.

The 8x8 SMPP environment runs on a high-availability cluster designed for enterprise-scale traffic. Connecting to our regional hostnames provides automatic failover and intelligent load balancing to ensure optimal performance.

Protocol Specification

Version: SMPP v3.4
Format: All PDUs must conform to the standard v3.4 binary specification.

Connection Details

The hostname depends on the platform deployment region your account is provisioned in.

Security & Compliance

• IP Whitelisting: For enhanced security, SMPP binds are strictly controlled via IP Whitelisting. Please provide your source IP addresses to your account manager during onboarding to enable access.
• Encryption: Port 2775 is maintained for legacy compatibility and transmits in plaintext. Use Port 2776 (TLS v1.3) for all production environments to ensure data integrity.
• IPSec: For enhanced network-level security, 8x8 also supports IPSec Tunnel binds. Contact support for setup details.

Binding & Architecture

A bind is a persistent TCP session between your application and the 8x8 SMPP server. The bind type determines the direction of message flow:

• bind_transmitter: Dedicated to sending messages (MT traffic).
• bind_receiver: Dedicated to receiving messages and delivery receipts (MO and DLRs).
• bind_transceiver: Supports bidirectional traffic on a single connection.

Performance Optimization

For high-throughput integrations, we recommend splitting traffic into dedicated transmitter and receiver binds. This architecture prevents "head-of-line blocking," ensuring that a high volume of outbound submissions (submit_sm) does not delay the processing of inbound delivery receipts (deliver_sm).

Session Management

• Capacity: Accounts are typically provisioned with a baseline of 4 concurrent binds per system_id.
• Elasticity: For customers requiring higher parallelization, additional binds can be allocated to meet your architecture's needs.
• DLR Routing: 8x8 intelligently routes delivery receipts (deliver_sm) to any active bind sharing the same system_id, ensuring consistent updates regardless of which session originated the message.

Throughput & Performance

The 8x8 platform is engineered to handle massive, carrier-grade message volumes. To ensure a smooth integration, we apply the following performance baselines:

• Baseline Throughput: By default, connections start at 50 messages per second (MPS) per bind.
• Enterprise Scaling: We routinely scale MPS limits significantly higher for high-volume customers. Your account manager can adjust these limits to match your specific production requirements.
• Asynchronous Windowing: To achieve maximum performance, we recommend using an asynchronous windowing approach, allowing you to submit multiple PDUs without waiting for individual responses.

Supported PDUs

Data Encoding

When sending messages, set the correct Data Coding Scheme (DCS) value in your submit_sm PDU:

Multi-channel Sender

The Multi-Channel Sender (MCS) campaign creation feature in Connect

The Multi-Channel Sender (MCS), or just Sender, is a powerful campaign creation feature within Connect that lets you send various message types. You can use it to dispatch SMS, SMS Engage, WhatsApp, Viber, and Voice (text-to-speech) messages.

You'll find it conveniently located in the top left navigation menu, right after "Overview."

Video Guide

Below is a video guide that covers how to send an SMS message which serves to accompany the content presented on this documentation page.

Sending SMS

You can personalise, schedule and send up to a million SMS in one go.

Steps on sending SMS

(For this tutorial we will highlight the method for uploading a file since it is the most popular way to send SMS)

1. Select "SMS" as your channel and select your subaccount.

(After you sign up, a sub-account is created and pre-selected for you. You may change this if you have different sub-accounts, which can be created by submitting a request to cpaas-support@8x8.com)

1. Click "Add recipients and you will be redirected to Recipients page to enter your destination number(s).

There are four(4) ways you can do this.

a. Upload a file

b. Type a mobile number

c. Add contacts from your contact list

d. Add group from your contact groups

1. You can upload your contact list by either clicking the "Drag & drop to upload" icon or simply dragging and dropping your file directly. For best results, we recommend using a .csv file formatted according to our default layout (you can find a sample file in this step for reference).

1. Once you've uploaded your contacts, you can easily adjust the column labels to match your data.

You'll find standard options like Mobile, FirstName, LastName, and ClientmessageId ready for selection. Need something more specific? Just type in a custom field name and press Enter to create and then select it..

Creating a custom field (From the screenshot below, the user typed and entered a new field called Nickname)

1. Click "Process contacts" to review your contact list. On this screen, you can verify all the fields you've selected, check country destinations, and see the total valid numbers, as well as any duplicates. If you want specific contacts to receive the same message multiple times, you can choose to "include duplicates."

Handling Mixed Country Codes in Destination Lists

If your destination list has phone numbers with different country codes than your current selection for local numbers, a notification will pop up under the Destinations card. You'll get an option to force apply the selected country code to all numbers.

1. Next, click "Compose a message" to start writing your message.

Before crafting your message, always enter your Sender ID. We'll automatically save it for you, so next time, just search and pick it from the dropdown list.

📘 Note:

Some countries don't support alphanumeric Sender IDs, and even when they do, pre-registration is often required. We also advise against using single-character spacing in your Sender ID, as this can negatively impact message delivery. The impact of single spacing can vary significantly between operators and countries.

For any assistance with your Sender IDs, please reach out to our support team.

Compose your message in the text area. To personalize it, simply click on a field from the "Insert custom field" list below.

SMS Character Encoding Warning

Our system helps you manage message length and cost when composing SMS. You'll see a warning if your message contains non-GSM7 characters and uses 2 or more SMS parts, just to raise awareness of your increased campaign cost.

Warning Indicators

When these conditions are met, you'll see:

• A warning banner.
• The text area border turns yellow.
• A yellow warning icon appears next to the SMS Parts counter.

What You Can Do

The warning banner won't stop you from proceeding; the "Next: Confirm and save" button remains active. You have three options:

• Close (X) button: Hides the banner. The yellow border and warning icon remain. This isn't saved, so the warning will reappear for future messages under the same conditions.
• Remove non-GSM7 characters: Cleans your message by removing non-GSM7 characters. The banner dismisses, the text area border resets, and the warning icon disappears. This isn't saved, so the warning will reappear for future messages under the same conditions.
• Do not show this warning again: Hides the banner, resets the text area, and removes the warning icon. This preference is saved in your cookies, so the warning won't appear again for future messages if you're creating messages on the same device.

You can also simply proceed to the next step without interacting with the banner at all.

1. Once your message is ready, click "Send your message(s)". Every message you send, regardless of quantity, is treated as a campaign. A campaign name is generated for you by default, but you're welcome to change it.

You'll also need to decide when to send your message: "Send message now" is pre-selected for immediate delivery, or you can schedule it for a later time.

❗️ Scheduled messages

Keep in mind you can only cancel scheduled messages up to 3 minutes before their send time. Messages cannot be cancelled if this deadline is missed.

Advanced SMS campaign settings - Control send speed to match your capacity

This feature gives you greater control over your SMS campaigns by helping you manage the delivery speed of your messages. It's designed to prevent a sudden flood of customer responses that could overwhelm your support team. By using this throttling mechanism, you can ensure a steady and manageable flow of customer engagement.

To control the send rate, you must enable the Limit sending speed over time toggle in the "Confirm and save" page during SMS campaign creation for both "Send Now" or "Schedule for later" campaigns.

Once enabled, you can configure the following fields:

• Number of messages: Set the maximum number of messages to be sent within a specific time unit.
• Time Unit: Choose from a dropdown menu with options: Minute, Hour, or Day. This selection determines the rate at which messages are sent.
• Delivery Window: Set a Start Time and End Time to define the hours when messages will be sent. This is useful if you don’t want to disturb your audience during the night or if you want to send messages during a specific time window for optimal conversions.
The start and end times will be set according to the time zone of the capital city of your recipients’ countries.

• Days: The system defaults to 5 days starting from the campaign creation or scheduled date. You can select or deselect days within this dynamic five-day window. The maximum duration for message throttling is a 120-hour (5-day) delivery window.

📘 Message sending limits

If your configured send rate won't reach all recipients within the 120-hour delivery window, a validation error will appear, and the "Submit" button will be disabled.

For example, if you set a rate of 2 messages per day for 3 days to a list of 10 recipients, only 6 messages will be sent, meaning your campaign will be incomplete. To fix this, you can increase the number of messages, change the time unit, extend the delivery window, or reduce the total number of recipients (e.g. split the campaign into multiple smaller ones)

1. Click "Send" to process and send your message. If you need to re-enter all the fields, simply click "Cancel".
2. After submitting, you'll be redirected to the list of Campaigns where you can see the last campaign created and its status right at the top of the list.

📘 Campaign status with controlled sending speed over time

After you submit a campaign that has limited sending speed over time (see above feature), it's added to the Campaign list with a "Processing" status.

The campaign details page may show an empty state if messages haven't started sending yet. Once messages begin to send, a partial state will be displayed, including a "Delivery in progress" note and a "Partial" cost label showing the running cost.

Message Status Update Timing
All messages campaigns will have their status updated every 5 mins for their first day. After that, on the second and succeeding days, status will only be updated once a day at 18:00 UTC (2:00 AM Singapore Time).

To send a single SMS using the 8x8 SMS API you need to submit a JSON object to the URL https://sms.8x8.com/api/v1/subaccounts/{subAccountId}/messages.

The JSON object has the following properties:

Parameters overview

Below is a more detailed description of the parameters in the SMS request body (JSON object submitted to the API)

destination

• This property is mandatory.
• This is the destination phone number for the SMS.
• The destination should be submitted following the international format and should include the country code (the leading + sign can be omitted but this is not an obligation).

Valid examples: +12025550308, 12025550308

👍

We also accept national formats (for national you have to specify the country in the dedicated field).

text

• This property is mandatory
• The text or the message (or SMS body) is the main part of your SMS: it is what is going to be displayed on the destination handset.
• It can contain characters from the GSM7 character set or from the UNICODE character set (see next section for more information).
• According to the encoding of the SMS, the number of SMS accounted per message will be proportional to the length of the text:
  • For GSM7 messages:
    • if the total length of the message is inferior or equal to 160 characters then the first and only message part can accommodate 160 characters.
    • If the total length is superior to 160 characters then each message part can contain 153 characters (fewer characters can be fit into one part as extra data space is taken to concatenate the SMS on the destination handset)
  • For Unicode messages:
    • if the total length of the message is inferior or equal to 70 characters then the first and only message part can accommodate 70 characters.
    • If the total length is superior to 70 characters then each message part can contain 67 characters (fewer characters can be fit into one part as extra data space is taken to concatenate the SMS on the destination handset)
  • For Unicode messages, 70 characters = 1 SMS (1 part)
• The maximum length for a message is 10 message parts. Longer messages will be truncated to this limit and sent.

source

• This value is optional.
• The source value can also be called senderID or TPOA.
• It is the from address that will be used when delivering the SMS to the handset.
• It can take different formats:
  • Alphanumeric (example: Acme Corp): this is the case when a source is composed of an alphanumeric string (max 11 characters: letters from the ASCII character set, digits and the space character). Alphanumeric sources are generally used for branded SMS to help the SMS receiver to identify the brand or services which originated the SMS.
  • Numeric (example: +6512345678): this the case when a source is composed of a string made purely of digits (max 17 chars). It can also start with the + sign. Numeric sources are generally used when the originator intends to receive an answer to the SMS as it is interpreted as a regular phone number by the destination handset.

🚧 Limitations

According to the country where the SMS is sent to, the sources can be overwritten in order to ensure better delivery. If you have some specific inquiries related to the type of source available for your account towards a specific destination, please contact your account manager.

clientMessageId

• This value is optional.
• If used, the ClientMessageId allows you to submit SMS associated to your custom message ID. That way, you are able to match the information contained in the API response with the ID from your own business logic. You can later read ClientMessageId from delivery reports.
• The maximum length allowed for the ClientMessageId is 350 characters.

encoding

AUTO, GSM7 or UCS2

• This property is optional. The default value is AUTO.
• AUTO: the API will analyze the content of your SMS text and select the correct encoding according to the characters used: if your SMS text contains UNICODE characters, then UNICODE will be selected, otherwise it will be GSM7
• GSM7: by using GSM7, you are forcing the encoding in use to be GSM 7 bit: it will render correctly any of the characters from the character set (See a complete list here). 8x8 SMS API considers each block of 160 GSM 7 bit characters as 1 SMS unit.
• UCS2: by using UCS2, you are forcing the encoding in use to be UNICODE: it will render correctly any of the characters from the UNICODE character set (See a complete list here). 8x8 SMS API considers each block of 70 UNICODE characters as 1 SMS unit.

scheduled

• This property is optional.
• The scheduled parameter should be used if you wish to schedule your message up to 7 days in advance. The SMS will be stored on the 8x8 SMS platform and sent out at the predefined time and date. You can specify the scheduling timestamp using the standard ISO 8601 format (which includes and specifies the timezone offset to use):

Example: 2016-11-07T19:20:30+08:00

expiry

• This property is optional.
• The expiry parameter should be used if you wish to specify a maximum time and date for the SMS to be sent. If for any reason the 8x8 SMS platform fails to send the message before the date and time predefined, the SMS will be discarded. You can specify the expiry timestamp using the standard ISO 8601 format (which includes and specifies the timezone offset to use):

Example: 2016-11-07T19:20:30+08:00

dlrCallbackUrl

• This property is optional.
• The dlrCallbackUrl allows specifying a webhook URL (a.k.a callback URL) that will be used to POST the delivery reports for the SMS sent in the request
• If included in the request, the webhook URL in the request will be used instead of your default account webhook

👍

We strongly recommend to set a default webhook (a.k.a callback URL) for your account using a Webhooks Configuration API

Response

8x8 API returns the following response:

Status object description

📘 Downloading SMS APIs (OAS File)

You can download the OAS File - Click Here

Please do take note that the file provides all the SMS APIs so please look through the .OAS file and select the specific SMS API(s) required.

Multi-channel Sender(MCS) allows users to send single or bulk SMS, Chat Apps and Voice messages. It has a capacity to let you send a message to over 500,000 contacts in a single campaign.

This guide will walk you through the entire process of connecting Salesforce to the 8x8 SMS API to send messages directly from your Salesforce environment from Flow Builder, by utilizing External Services. You can also follow the same invocable actions in Orchestrator, Einstein bots, or OmniStudio Assets.

We will accomplish this using Salesforce's declarative tools, which allow you to build robust integrations without writing complex code.

Prerequisites and Requirements

Before you begin, ensure your Salesforce environment and 8x8 account meet the following requirements.

Salesforce Platform Requirements

This guide utilizes Salesforce External Services. According to the official Salesforce documentation, the compatibility and permissions for this feature are as follows:

• Salesforce Experience: Available in Lightning Experience.
• Required Editions: Available in Enterprise, Performance, Unlimited, and Developer Editions.
• Feature Integration: The actions created from an External Service can be used in declarative tools like Flow Builder, Orchestrator, Einstein bots, or Omnistudio.
• User Permissions Needed:
  • To define an external service: The user needs Modify All Data OR Modify Metadata Through Metadata API Functions permissions.
  • To invoke an external service action from a flow: The user needs the Run Flows permission.

8x8 Account Requirements

• 8x8 Connect Account: An active account with SMS services enabled.
• API Credentials: Your 8x8 Subaccount ID and your API Key (Bearer Token), which you can generate from your 8x8 Connect customer portal.
• OpenAPI Specification (OAS) File: You will need the OAS file for the SMS API. You can find and download it from the Send SMS API Reference page.

Part 1: The Foundation - Setting Up Authentication

First, we need to securely store your 8x8 API credentials in Salesforce.

Step 1.1: Create the External Credential

The External Credential is a secure vault for your API key.

1. Navigate to Setup ⚙️. In the Quick Find box, type External Credentials and select it.
2. Click New.
3. Enter the following details:

• Label: 8x8 CPaaS Authentication
• Name: X8x8_CPaaS_Authentication
• Authentication Protocol: Select Custom.

1. Click Save.

Step 1.2: Create the Principal

The Principal holds the actual secret Bearer Token.

1. On the External Credential page you just saved, scroll down to Principals and click New.
2. Enter the following details:

• Principal Name: 8x8 API Key Principal
• Sequence Number: 1

1. Under Authentication Parameters, click Add Parameter.

• Name: Authorization
• Value: Bearer YOUR_API_TOKEN (Replace with your actual API key).

1. Click Save.

Create Principal

Step 1.3: Create the Named Credential for SMS

The Named Credential links the SMS API's specific address (URL) to the authentication secret.

1. Navigate to Setup ⚙️. In the Quick Find box, type Named Credentials and select it.
2. Click New.
3. Enter the following details:

• Label: 8x8 SMS API
• Name: X8x8_SMS_API
• URL: https://sms.8x8.com
• External Credential: Select the 8x8 CPaaS Authentication credential.
• Ensure the Generate Authorization Header checkbox is checked.

1. Click Save.

Completed Named Credential and External Credential

Part 2: Defining the SMS API Operations

Now, we will use your SMS OAS file to teach Salesforce about the specific API call to send an SMS.

1. Navigate to Setup ⚙️. In the Quick Find box, type External Services and select it.
2. Click Add External Service.
3. Select From API Specification.
4. Configure the service:

• Service Name: CPaaSSMS
• Named Credential: Select the 8x8 SMS API Named Credential you just created.
• Service Schema: Select Complete JSON and upload your SMS-specific OAS .json file.
• Service Schema:
  • Select Upload from local and upload the complete OAS .json file or
  • Select "Complete Schema" and paste the schema below (contains only send single SMS and send batch SMS)

{
"openapi":"3.0.1",
"info":{
"title":"SMS API",
"description":"API to send SMS messages",
"version":"1"
},
"servers":[
{
"url":"https://sms.8x8.com",
"description":"Asia-Pacific region"
},
{
"url":"https://sms.us.8x8.com",
"description":"North America region"
},
{
"url":"https://sms.8x8.uk",
"description":"Europe region"
},
{
"url":"https://sms.8x8.id",
"description":"Indonesia region"
}
],
"paths":{
"/api/v1/subaccounts/{subAccountId}/messages":{
"post":{
"summary":"Send SMS",
"description":"Send a single SMS message.",
"operationId":"Send-Sms-Single",
"parameters":[
{
"name":"subAccountId",
"in":"path",
"required":true,
"schema":{
"type":"string"
}
}
],
"requestBody":{
"required":true,
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/SmsRequest"
}
}
}
},
"responses":{
"200":{
"description":"SMS accepted and queued",
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/SmsResponse"
}
}
}
}
},
"security":[
{
"apiKey":[]
}
]
}
},
"/api/v1/subaccounts/{subAccountId}/messages/batch":{
"post":{
"summary":"Send SMS Batch",
"description":"Send multiple SMS messages in a single batch.",
"operationId":"Send-Many-Sms",
"parameters":[
{
"name":"subAccountId",
"in":"path",
"required":true,
"schema":{
"type":"string"
}
}
],
"requestBody":{
"required":true,
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/BatchSmsRequest"
}
}
}
},
"responses":{
"200":{
"description":"Batch accepted and processed",
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/BatchSmsResponse"
}
}
}
}
},
"security":[
{
"apiKey":[]
}
]
}
}
},
"components":{
"securitySchemes":{
"apiKey":{
"type":"http",
"scheme":"bearer"
}
},
"schemas":{
"SmsRequest":{
"type":"object",
"required":[
"destination",
"text"
],
"properties":{
"destination":{
"type":"string",
"description":"MSISDN destination number"
},
"text":{
"type":"string",
"description":"Message body"
},
"source":{
"type":"string"
},
"encoding":{
"type":"string",
"enum":[
"AUTO",
"GSM7",
"UCS2"
]
},
"scheduled":{
"type":"string",
"format":"date-time"
},
"expiry":{
"type":"string",
"format":"date-time"
}
}
},
"SmsStatus":{
"type":"object",
"properties":{
"code":{
"type":"string",
"enum":[
"QUEUED",
"REJECTED"
]
},
"description":{
"type":"string"
}
}
},
"SmsResponse":{
"type":"object",
"required":[
"umid",
"destination",
"status",
"encoding"
],
"properties":{
"umid":{
"type":"string"
},
"destination":{
"type":"string"
},
"encoding":{
"type":"string",
"enum":[
"AUTO",
"GSM7",
"UCS2"
]
},
"clientMessageId":{
"type":"string"
},
"status":{
"$ref":"#/components/schemas/SmsStatus"
}
}
},
"BatchSmsRequest":{
"type":"object",
"required":[
"messages"
],
"properties":{
"clientBatchId":{
"type":"string"
},
"messages":{
"type":"array",
"items":{
"$ref":"#/components/schemas/SmsRequest"
}
},
"destinations":{
"type":"array",
"items":{
"type":"string"
}
},
"template":{
"$ref":"#/components/schemas/SmsTemplateFull"
},
"includeMessagesInResponse":{
"type":"boolean"
}
}
},
"BatchSmsResponse":{
"type":"object",
"required":[
"batchId",
"acceptedCount",
"rejectedCount"
],
"properties":{
"batchId":{
"type":"string"
},
"clientBatchId":{
"type":"string"
},
"acceptedCount":{
"type":"integer"
},
"rejectedCount":{
"type":"integer"
},
"messages":{
"type":"array",
"items":{
"$ref":"#/components/schemas/SmsResponse"
}
}
}
},
"SmsTemplateFull":{
"type":"object",
"properties":{
"source":{
"type":"string"
},
"text":{
"type":"string"
},
"encoding":{
"type":"string",
"enum":[
"AUTO",
"GSM7",
"UCS2"
]
},
"scheduled":{
"type":"string",
"format":"date-time"
},
"expiry":{
"type":"string",
"format":"date-time"
}
}
}
}
}
}

1. Click Save & Next,
2. In Select Operations , select the Send-Many-Sms and Send-Sms-Single operations then Next, and Finish.

Salesforce will now parse the file and make the Send-Sms-Single and Send-Many-Sms operations available as actions in Flow Builder.

Part 3: Building the SMS Flow

The body for an SMS message is much simpler than other channels, which makes the Flow easier to build.

Step 3.1: Create the Flow and Body Variable

1. Navigate to Setup ⚙️ > Flows and click New Flow. Select Autolaunched Flow.
2. From the toolbox on the left, create one variable by clicking New Resource.
3. • Variable: The SMS Body

• Resource Type: Variable
• API Name: smsBody
• Data Type: Apex-Defined
• Apex Class: Search for and select the auto-generated class for the SMS request body. It will be named similar to ExternalService__CPaaSSMS_SmsRequest.

Configuring the first Variable smsBody

Step 3.2: Assignment - Set SMS Properties

We only need one Assignment element to construct the SMS message.

1. On the flow canvas, click the + icon after the Start element and add an Assignment element.
2. Label: Set SMS Body
3. Configure the following assignments.

• {!smsBody.to} | Equals | +65xxxxxxxxxx (The recipient's phone number)
• {!smsBody.from} | Equals | 8x8 (Your 8x8-registered SMS Sender ID or phone number)
• {!smsBody.text} | Equals | This is an SMS message.

Step 3.3: The Action - Make the API Call

1. Click the final + and add an Action element.
2. Search for your SmsApi actions and select the action for sending an SMS.
3. Label: Send SMS
4. Configure the inputs:

• subAccountId: Enter your 8x8 Subaccount ID string here.
• body: Select your main variable, {!smsBody}.

Part 4: Permissions and Testing

This final step ensures your user can run the flow and execute the callout.

Step 4.1: Assign Permissions

1. Navigate to Setup ⚙️ > Permission Sets and create a New Permission Set.
2. Label: CPaaS API Access
3. In the new Permission Set, find and click on External Credential Principal Access.
4. Click Edit. Add the 8x8 CPaaS Authentication : 8x8 API Key Principal from the available list to the enabled list. Click Save.
5. Manage Assignments for the Permission Set and assign it to your user.

Step 4.2: Debug the Flow

1. Return to your saved Flow.
2. Click the Debug button.
3. Click Run.
4. Check the debug log on the right for a success message ("All done.") and check your test device for the SMS.

You have now successfully built a low-code integration to send SMS with the 8x8 SMS API from Salesforce.

This guide will walk you through the entire process of connecting Salesforce to the 8x8 Business Messaging API (e.g. for WhatsApp) to send messages directly from your Salesforce environment from Flow Builder, by utilizing External Services. You can also follow the same invocable actions in Orchestrator, Einstein bots, or OmniStudio Assets.

We will accomplish this using Salesforce's declarative tools, which allow you to build robust integrations without writing complex code.

👍 Good to know

While this guide focuses on WhatsApp Authentication template, you can use the same approach for other WhatsApp templates, or other supported messaging apps following their respective schema. For SMS, refer to this guide

Prerequisites and Requirements

Before you begin, ensure your Salesforce environment and 8x8 account meet the following requirements.

Salesforce Platform Requirements

• Salesforce Experience: Lightning Experience.
• Required Editions: Enterprise, Performance, Unlimited, and Developer Editions.
• Feature Integration: The actions created from an External Service can be used in declarative tools like Flow Builder, Orchestrator, Einstein bots, or Omnistudio.
• User Permissions Needed:
  • To define an external service: The user needs Modify All Data OR Modify Metadata Through Metadata API Functions permissions.
  • To invoke an external service action from a flow: The user needs the Run Flows permission.

8x8 Account Requirements

• 8x8 Connect Account: An active account with access to the messaging channels you wish to use.
• API Credentials: Your 8x8 Subaccount ID and your API Key (Bearer Token).

Part 1: The Foundation - Setting Up Authentication

First, we need to teach Salesforce how to securely authenticate with the 8x8 Messaging API. This involves creating a secure chain of credentials. A Named Credential specifies the callout endpoint's URL and its required authentication parameters in one definition.

Step 1.1: Create the External Credential

The External Credential is a secure vault that will hold your API key.

1. Navigate to Setup ⚙️. In the Quick Find box, type External Credentials and select it.
2. Click New.
3. Enter the following details:

• Label: 8x8 CPaaS Authentication
• Name: 8x8_CPaaS_Authentication (this will auto-populate)
• Authentication Protocol: Select Custom.

1. Click Save.

Step 1.2: Create the Principal

The Principal represents the specific identity and secret used for authentication.

1. On the External Credential page you just saved, scroll down to Principals and click New.
2. Enter the following details:

• Principal Name: 8x8 API Key Principal
• Sequence Number: 1

1. Under Authentication Parameters, click Add Parameter.

• Name: Authorization
• Value: Bearer YOUR_API_TOKEN (Replace YOUR_API_TOKEN with the actual API key from this page).

1. Click Save.

Create Principal

Step 1.3: Create the Named Credential

The Named Credential links the API's address (URL) to the authentication secret you just stored.

1. Navigate to Setup ⚙️. In the Quick Find box, type Named Credentials and select it.
2. Click New.
3. Enter the following details:

• Label: 8x8 Messaging API
• Name: 8x8_Messaging_API
• URL: https://chatapps.8x8.com (Asia-Pacific deployment region; see full list of regions
• External Credential: Select the 8x8 CPaaS Authentication credential you created above.
• Ensure the Generate Authorization Header checkbox is checked.

1. Click Save.

ℹ️ Sending SMS

For SMS, use the corresponding sms endpoint (default is sms.8x8.com) and the appropriate SMS OAS accordingly

Completed Named Credential and External Credential

Part 2: Defining the API Operations

Next, we will use your OAS file to teach Salesforce about the specific 8x8 API calls.

1. Navigate to Setup ⚙️. In the Quick Find box, type External Services and select it.
2. Click Add External Service.
3. Select From API Specification.
4. Configure the service:

• Service Name: CPaasMessagingApps
• Named Credential: Select the 8x8 Messaging API Named Credential you just created.
• Service Schema: Select Upload from local and upload the complete OAS .json file or select "Complete Schema" and paste the schema below (contains only send single and send batch API)

{
"openapi":"3.0.0",
"info":{
"title":"8x8 Send Message API (Single and Batch)",
"version":"1.0",
"description":"A minimal OpenAPI spec for the 8x8 Send Message and Send Message Batch operations."
},
"servers":[
{
"url":"https://chatapps.8x8.com",
"description":"Asia-Pacific region"
},
{
"url":"https://chatapps.us.8x8.com",
"description":"North America region"
},
{
"url":"https://chatapps.8x8.uk",
"description":"Europe region"
},
{
"url":"https://chatapps.8x8.id",
"description":"Indonesia region"
}
],
"paths":{
"/api/v1/subaccounts/{subAccountId}/messages":{
"post":{
"summary":"Send message",
"description":"This endpoint is used to send Messaging Apps messages individually (1 request per message).",
"tags":[
"Send Message API"
],
"operationId":"Send-Message",
"security":[
{
"apiKey":[]
}
],
"parameters":[
{
"name":"subAccountId",
"in":"path",
"description":"You must replace *{subAccountId}* with the subaccountid that you want to use.",
"required":true,
"schema":{
"type":"string"
}
}
],
"requestBody":{
"description":"Messaging API: request model for send single message",
"required":true,
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/single-message-request"
}
}
}
},
"responses":{
"200":{
"description":"Success response",
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/single-message-response"
}
}
}
},
"400":{
"description":"Bad Request"
},
"401":{
"description":"Unauthorized"
},
"500":{
"description":"Internal Server Error"
}
}
}
},
"/api/v1/subaccounts/{subAccountId}/messages/batch":{
"post":{
"summary":"Send message batch",
"description":"This endpoint is used to send Messaging Apps messages by batches (1 request for multiple messages) with personalized contents/properties. Using this API, it is possible to send up to 1,000 messages per request.",
"tags":[
"Send Message API"
],
"operationId":"send-message-many",
"security":[
{
"apiKey":[]
}
],
"parameters":[
{
"name":"subAccountId",
"in":"path",
"description":"You must replace *{subAccountId}* with the subaccountid that you want to use.",
"required":true,
"schema":{
"type":"string"
}
}
],
"requestBody":{
"description":"Messaging API: request model for send batch of messages",
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/batch-message-request"
}
}
}
},
"responses":{
"200":{
"description":"Success response",
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/batch-message-response"
}
}
}
},
"400":{
"description":"Bad Request"
},
"401":{
"description":"Unauthorized"
},
"500":{
"description":"Internal Server Error"
}
}
}
}
},
"components":{
"securitySchemes":{
"apiKey":{
"type":"http",
"scheme":"bearer",
"description":"8x8 Messaging API accepts an ApiKey Bearer Token authentication method."
}
},
"schemas":{
"user":{
"type":"object",
"properties":{
"msisdn":{
"type":"string"
},
"country":{
"type":"string"
}
}
},
"channel-override":{
"type":"object",
"properties":{
"channel":{
"$ref":"#/components/schemas/channel-type"
},
"fallbackAfter":{
"type":"integer"
},
"successStatus":{
"$ref":"#/components/schemas/success-status"
}
}
},
"content":{
"type":"object",
"properties":{
"text":{
"type":"string"
},
"url":{
"type":"string",
"format":"uri"
},
"fallbackText":{
"type":"string"
},
"sms":{
"$ref":"#/components/schemas/sms-settings"
},
"location":{
"$ref":"#/components/schemas/location"
},
"interactive":{
"$ref":"#/components/schemas/interactive"
},
"video":{
"$ref":"#/components/schemas/video"
},
"template":{
"type":"object",
"properties":{
"name":{
"type":"string"
},
"language":{
"type":"string"
},
"components":{
"type":"array",
"items":{
"type":"object",
"properties":{
"type":{
"type":"string",
"enum":[
"header",
"footer",
"body",
"button"
]
},
"parameters":{
"type":"array",
"items":{
"type":"object",
"properties":{
"type":{
"type":"string",
"enum":[
"text",
"image",
"video",
"document",
"location",
"payload",
"couponCode"
]
},
"text":{
"type":"string"
},
"url":{
"type":"string"
},
"location":{
"type":"object",
"properties":{
"latitude":{
"type":"number"
},
"longitude":{
"type":"number"
},
"name":{
"type":"string"
},
"address":{
"type":"string"
}
}
},
"payload":{
"type":"string"
},
"couponCode":{
"type":"string"
}
}
}
},
"index":{
"type":"integer"
},
"subType":{
"type":"string",
"enum":[
"QuickReply",
"Url",
"CopyCode"
]
}
}
}
}
}
}
}
},
"content-type":{
"type":"string",
"enum":[
"Text",
"Audio",
"Video",
"Image",
"Location",
"File",
"Template"
]
},
"channel-type":{
"type":"string",
"enum":[
"SMS",
"WhatsApp",
"Facebook",
"RCS",
"Viber",
"Line",
"WeChat",
"Zalo",
"Instagram"
]
},
"success-status":{
"type":"string",
"enum":[
"Accepted",
"Sent",
"Delivered",
"Read"
]
},
"sms-settings":{
"type":"object",
"properties":{
"encoding":{
"type":"string"
},
"source":{
"type":"string"
}
}
},
"location":{
"type":"object",
"properties":{
"latitude":{
"type":"number"
},
"longitude":{
"type":"number"
},
"name":{
"type":"string"
},
"address":{
"type":"string"
}
}
},
"video":{
"type":"object",
"properties":{
"thumbnail":{
"type":"string"
},
"filesize":{
"type":"number"
},
"duration":{
"type":"number"
}
}
},
"interactive":{
"type":"object",
"properties":{
"type":{
"type":"string",
"enum":["button","list","product","product_list"]
},
"action":{
"type":"object"
},
"header":{
"type":"object"
},
"body":{
"type":"object"
},
"footer":{
"type":"object"
}
}
},
"single-message-response":{
"type":"object",
"properties":{
"status":{
"type":"object",
"properties":{
"state":{
"type":"string"
},
"timestamp":{
"type":"string",
"format":"date-time"
}
}
},
"umid":{
"type":"string",
"format":"uuid"
},
"user":{
"$ref":"#/components/schemas/user"
},
"clientMessageId":{
"type":"string"
}
}
},
"batch-message-response":{
"type":"object",
"properties":{
"batchId":{
"type":"string",
"format":"uuid"
},
"clientBatchId":{
"type":"string"
},
"acceptedCount":{
"type":"integer"
},
"rejectedCount":{
"type":"integer"
},
"messages":{
"type":"array",
"items":{
"$ref":"#/components/schemas/single-message-response"
}
}
}
},
"single-message-request":{
"type":"object",
"required":[
"user",
"type",
"content"
],
"properties":{
"user":{
"$ref":"#/components/schemas/user"
},
"clientMessageId":{
"type":"string"
},
"type":{
"$ref":"#/components/schemas/content-type"
},
"content":{
"$ref":"#/components/schemas/content"
},
"scheduled":{
"type":"string",
"format":"date-time"
},
"expiry":{
"type":"string",
"format":"date-time"
},
"dlrCallbackUrl":{
"type":"string",
"format":"uri"
},
"channels":{
"type":"array",
"items":{
"$ref":"#/components/schemas/channel-override"
}
}
}
},
"batch-message-request":{
"type":"object",
"required":[
"messages"
],
"properties":{
"clientBatchId":{
"type":"string"
},
"template":{
"$ref":"#/components/schemas/batch-message-template"
},
"messages":{
"type":"array",
"items":{
"$ref":"#/components/schemas/single-message-request"
}
},
"includeMessagesInResponse":{
"type":"boolean",
"default":false
}
}
},
"batch-message-template":{
"type":"object",
"properties":{
"type":{
"$ref":"#/components/schemas/content-type"
},
"content":{
"$ref":"#/components/schemas/content"
},
"dlrCallbackUrl":{
"type":"string",
"format":"uri"
},
"channels":{
"type":"array",
"items":{}
}
}
}
}
}
}

• Select the checkboxes next to the operation names, Save, then Done.

Salesforce will now parse the file and make the Send-Message and send-message-many operations available as actions in Flow Builder.

External Services created for both API operations

Part 3: Building the Automation in Flow Builder

This is where we build the logic to construct the message and send it. In this example we'll be sending a WhatsApp Authentication template message.

Step 3.1: Create the Flow and Key Variables

1. Navigate to Setup ⚙️ > Flows and click New Flow. Select Autolaunched Flow.
2. From the toolbox on the left, create the following three variables by clicking New Resource. These will be used to build the complex request body.
3. • Variable 1: The Main Body

• Resource Type: Variable
• API Name: messageBody
• Data Type: Apex-Defined
• Apex Class: Search for and select the auto-generated class for the request body. It will be named similar to ExternalService__CPaaSMessagingApps_singlex2dmessagex2drequest.

Configuring the first Variable messageBody

Repeat the same steps for the rest of the variables as shown below

• Variable 2: A Single Component

  • Resource Type: Variable
  • API Name: componentVariable
  • Data Type: Apex-Defined
  • Apex Class: Search for the auto-generated class for a component. It will be named similar to ExternalService__CPaaSMessagingApps_content_template_components.

• Variable 3: A Single Parameter

  • Resource Type: Variable
  • API Name: parameterVariable
  • Data Type: Apex-Defined
  • Apex Class: Search for the auto-generated class for a parameter. It will be named similar to ExternalService__CPaaSMessagingApps_content_template_components_parameters.

Step 3.2: First Assignment - Set Core Message Properties

1. On the flow canvas, click the + icon after the Start element and add an Assignment element.
2. Label: Set Core Message Body
3. Configure the following assignments:

• {!messageBody.user.msisdn} | Equals | +6512345678 (A test phone number)
• {!messageBody.type} | Equals | template
• {!messageBody.content.template.name} | Equals | your_authentication_template_name
• {!messageBody.content.template.language} | Equals | en_US

Step 3.3: Second Assignment - Build the "Body" Component

1. Click the + on the canvas after the first assignment and add a new Assignment element.
2. Label: Build and Add Body Component
3. Configure the assignments to build the component from the inside out:

• {!parameterVariable.type} | Equals | text
• {!parameterVariable.text} | Equals | 123456 (Your sample OTP code)
• {!componentVariable.type} | Equals | body
• {!componentVariable.parameters} | Add | {!parameterVariable}
• {!messageBody.content.template.components} | Add | {!componentVariable}

Step 3.4: Third Assignment - Build the "Button" Component

1. Click the + again and add a final Assignment element.
2. Label: Build and Add Button Component
3. This time, we must first clear our helper variable before reusing it. Configure as follows:

• {!componentVariable.parameters} | Equals | {!$GlobalConstant.EmptyString}
• {!parameterVariable.type} | Equals | text
• {!parameterVariable.text} | Equals | 123456
• {!componentVariable.type} | Equals | Button
• {!componentVariable.subType} | Equals | url
• {!componentVariable.index} | Equals | 0
• {!componentVariable.parameters} | Add | {!parameterVariable}
• {!messageBody.content.template.components} | Add | {!componentVariable}

Step 3.5: The Action - Make the API Call

1. Click the final + and add an Action element.
2. Search for your CPaasMessagingApps actions and select Send-Message.
3. Label: Send WhatsApp Message
4. Configure the inputs:

• subAccountId: Enter your 8x8 Subaccount ID string here.
• body: Select your main variable, {!messageBody}.

Part 4: Permissions and Testing

This final step ensures your user can run the flow and execute the callout.

Step 4.1: Assign Permissions

1. Navigate to Setup ⚙️ > Permission Sets and create a New Permission Set.
2. Label: CPaaS API Access
3. In the new Permission Set, find and click on External Credential Principal Access.
4. Click Edit. Add the 8x8 CPaaS Authentication : 8x8 API Key Principal from the available list to the enabled list. Click Save.
5. Manage Assignments for the Permission Set and assign it to your user.

Step 4.2: Debug the Flow

1. Return to your saved Flow.
2. Click the Debug button.
3. Click Run.
4. Check the debug log on the right for a success message ("All done.") and check your phone for the WhatsApp message.

You have now successfully built a low-code integration to send messages with the 8x8 Messaging API from Salesforce.

Please see Messaging API for the full API reference.

Text Message

Content: Text only

Character Limit: Up to 3072 characters

Use Cases: OTP codes, simple alerts

Payload sample

{
"user":{
"msisdn":"+10000000000"
},
"type":"Text",
"content":{
"text":":wave: Hi Sarah! Just a reminder—your appointment at Wellness Dental is scheduled for tomorrow at 10:30 AM"
}
}

The corresponding message the user will receive:

Sending a Rich Media Message

• Media Types Supported: Images, videos, documents
• File formats: .ogx, .pdf, .aac, .mp3, .mpeg, .mp3, .mp4, .mp4, .3gp, .jpeg, .jpg, .gif, .png, .h263, .m4v, .mp4, .mp4, .mpeg, .webm
• Text Caption: Up to 2,000 UTF-8 characters
• File Size Limits: 100MB
• File URL limit: 2,048 characters

Image & text

{
"user":{
"msisdn":"+10000000000"
},
"type":"Image",
"content":{
"url":"https://www.example.com/image.jpg",
"text":"Hi James! Your order #ORD-8821 has shipped and is on its way. Estimated delivery: tomorrow by 6 PM."
}
}

The corresponding message the user will receive:

Video & text

{
"user":{
"msisdn":"+10000000000"
},
"type":"Video",
"content":{
"url":"https://www.example.com/video.mp4",
"text":"Hi Emma! Your account setup guide is ready. Watch this short video to get started in minutes."
}
}

The corresponding message the user will receive:

Audio & text

{
"user":{
"msisdn":"+10000000000"
},
"type":"Audio",
"content":{
"url":"https://www.example.com/audio.mp3",
"text":"Hi Alex! You have a new voice message from our support team regarding your recent request."
}
}

The corresponding message the user will receive:

File & text

{
"user":{
"msisdn":"+10000000000"
},
"type":"Text",
"content":{
"url":"https://example.com/links/Invoice-october-2025.pdf",
"text":"Hey John! Here's your monthly invoice for October. Contact our team if you have any questions. Thank you"
}
}

The corresponding message the user will receive:

Rich Card

A Rich Card bundles a title, description, a single media asset (image or video), and up to four in-card suggestions into one interactive message. Use rich cards for product promotions, appointment confirmations, order summaries, or any scenario where visual content needs to be paired with clear calls to action.

Content: Title + description + media + in-card suggestions + optional message-level suggestions

Card Orientation: vertical or horizontal

Media Height (vertical cards only): SHORT, MEDIUM, or TALL

Use Cases: Product showcase, booking confirmation, loyalty reward, order summary

Rich Card — Vertical

A vertical card displays the media at the top, followed by the title, description, and in-card suggestions. Use MEDIUM or TALL media height when the image is the primary content; use SHORT when the text is the primary content.

Payload sample

{
"user":{
"msisdn":"+441234567890"
},
"type":"RichCard",
"content":{
"richCard":{
"cardOrientation":"vertical",
"title":"Hey Melissa! New year, new shoes? 👟",
"description":"Check out our latest arrivals, including the AirPulse, perfect for your next run! Plus, get a free gait analysis with any purchase this week.",
"media":{
"height":"SHORT",
"contentInfo":{
"fileUrl":"https://www.example.com/rich_card_vertical.jpg",
"thumbnailUrl":"https://www.example.com/rich_card_vertical.jpg",
"forceRefresh":false
}
},
"suggestions":[
{
"reply":{
"text":"🛍️ View new arrivals",
"postbackData":"view_new_arrivals"
}
},
{
"reply":{
"text":"📋 Book Gait Analysis",
"postbackData":"book_gait_analysis"
}
},
{
"action":{
"text":"👗 Shop now",
"postbackData":"shop_now",
"openUrlAction":{
"url":"https://developer.8x8.com/connect/docs/rcs/message-types",
"application":"WEBVIEW",
"webviewViewMode":"FULL",
"description":"Shop Bridgepoint Runners"
},
"fallbackUrl":"https://developer.8x8.com/connect/docs/rcs/message-types"
}
}
]
},
"suggestions":[
{
"reply":{
"text":"Check my orders",
"postbackData":"check_my_orders"
}
},
{
"reply":{
"text":"Not interested",
"postbackData":"not_interested"
}
}
]
}
}

The corresponding message the user will receive:

The annotations map directly to the payload:

• Media → content.richCard.media
• Title text → content.richCard.title
• Description text → content.richCard.description
• Primary suggestions → content.richCard.suggestions (in-card, up to 4)
• Secondary suggestions → content.suggestions (message-level, up to 7)

Rich Card — Horizontal

A horizontal card displays the media to the left or right of the text block. Use it when the text is the primary content and the image plays a supporting role (e.g. confirmations, itineraries, compact receipts). Horizontal cards do not use media.height — the carrier sizes the media to the text block.

Payload sample

{
"user":{
"msisdn":"+441234567890"
},
"type":"RichCard",
"content":{
"richCard":{
"thumbnailImageAlignment":"right",
"cardOrientation":"horizontal",
"title":"Your reservation at Ebi",
"description":"We're springing into action to get your table ready for 5:00 PM! 🕔 Have any questions before you arrive?",
"media":{
"contentInfo":{
"fileUrl":"https://www.example.com/rich_card_horizontal.jpg",
"thumbnailUrl":"https://www.example.com/rich_card_horizontal.jpg",
"forceRefresh":false
}
},
"suggestions":[
{
"action":{
"text":"Ebi location",
"postbackData":"ebi_location",
"viewLocationAction":{
"latLong":{
"latitude":37.7749,
"longitude":-122.4194
},
"label":"Ebi Restaurant"
}
}
},
{
"action":{
"text":"Call us",
"postbackData":"call_ebi",
"dialAction":{
"phoneNumber":"+12025551234"
}
}
}
]
},
"suggestions":[]
}
}

The corresponding message the user will receive:

Suggestions: in-card vs. message-level

A rich card supports two separate suggestion arrays:

Together, a single message can expose up to 11 suggestions (4 in-card + 7 message-level).

Rich Card field reference

Limits

Best practices

• Keep titles short and scannable; use the description for supporting detail.
• Pair every card with at least one suggestion so users have a clear next step.
• Provide a fallbackUrl on every openUrlAction for clients that cannot open the webview.
• Serve media over HTTPS from a stable, publicly reachable URL — the carrier may cache the asset.
• Use message-level suggestions for persistent actions (e.g. "Check my orders") and keep in-card suggestions tied to the card's specific offer.

Carousel

A Carousel is a horizontally swipeable collection of rich cards delivered in a single message. Use carousels to present multiple comparable items — product variants, tour packages, available appointment slots, or menu choices — so the user can browse options inline without leaving the conversation.

Each card in the carousel follows the same content model as a standalone rich card (title, description, media, in-card suggestions), but cards in a carousel share a common cardWidth and are always rendered vertically.

Content: List of 2–10 cards + optional message-level suggestions

Card Width: small or medium — applied to every card in the carousel

Use Cases: Product catalogue, tour or package selection, menu, appointment slots, booking options

Payload sample

{
"user":{
"msisdn":"+441234567890"
},
"type":"Carousel",
"content":{
"carousel":{
"cardWidth":"medium",
"cards":[
{
"title":"Catamaran day-trip",
"description":"Snorkel, sushi, & sunset cocktails. $99, 6 spots left!",
"media":{
"height":"short",
"contentInfo":{
"fileUrl":"https://www.example.com/catamaran.jpg",
"thumbnailUrl":"https://www.example.com/catamaran.jpg",
"forceRefresh":false
}
},
"suggestions":[
{
"action":{
"text":"Buy now",
"postbackData":"buy_catamaran",
"openUrlAction":{
"url":"https://developer.8x8.com/connect/docs/rcs/message-types",
"application":"WEBVIEW",
"webviewViewMode":"FULL",
"description":"Buy catamaran day-trip"
},
"fallbackUrl":"https://developer.8x8.com/connect/docs/rcs/message-types"
}
},
{
"reply":{
"text":"More details",
"postbackData":"details_catamaran"
}
}
]
},
{
"title":"Jungle ATV tour",
"description":"Explore off-road with an expert guide. $99, limited spots!",
"media":{
"height":"short",
"contentInfo":{
"fileUrl":"https://www.example.com/atv.png",
"thumbnailUrl":"https://www.example.com/atv.png",
"forceRefresh":false
}
},
"suggestions":[
{
"action":{
"text":"Buy now",
"postbackData":"buy_atv_tour",
"openUrlAction":{
"url":"https://developer.8x8.com/connect/docs/rcs/message-types",
"application":"WEBVIEW",
"webviewViewMode":"FULL",
"description":"Buy jungle ATV tour"
},
"fallbackUrl":"https://developer.8x8.com/connect/docs/rcs/message-types"
}
},
{
"reply":{
"text":"More details",
"postbackData":"details_atv_tour"
}
}
]
}
]
},
"suggestions":[
{
"reply":{
"text":"Check my orders",
"postbackData":"check_my_orders"
}
},
{
"reply":{
"text":"Not interested",
"postbackData":"not_interested"
}
}
]
}
}

The corresponding message the user will receive:

The annotations map directly to the payload:

• Rich card carousel → content.carousel.cards (the swipeable cards themselves)
• Suggestion chips → content.suggestions (message-level, shown below the carousel)

Carousel field reference

Limits

Best practices

• Keep cardWidth consistent with the content density — use small when titles and descriptions are short; use medium when you need room for longer copy or larger media.
• Keep the number of cards manageable. 3–5 cards typically convert best; 10 cards is the absolute ceiling.
• Lead with the most relevant card — users often only browse the first two or three before making a decision.
• Use the same suggestion pattern on every card (e.g. "Buy now" + "More details") so users learn the pattern quickly.
• Serve media over HTTPS from a stable, publicly reachable URL — the carrier may cache the asset.
• Use message-level suggestions for actions that apply to the whole conversation ("Check my orders", "Not interested") rather than to a specific card.

Suggested Actions

Suggestions in RCS Business Messaging provide interactive buttons, chips, or quick replies that guide users seamlessly through rich conversational experiences. By using suggestions, brands can streamline user journeys, enhance engagement, improve conversions, and gather immediate user feedback.

Available Suggestion Types

Best practices

• Limit to 4‑5 suggestions per message to avoid cognitive overload.
• Use clear, action‑oriented labels (e.g. "Track Order" instead of "Order").
• Always set postback data so downstream systems can act on replies.
• Include capability fallback (SMS or URL) when the user's client does not support a given action.
• Instrument analytics to track tap‑through and optimise suggestion wording.

Implementation Example

{
"user":{
"msisdn":"+441234567890"
},
"type":"Text",
"content":{
"text":"👋 Hi Sarah! Just a reminder—your appointment at Wellness Dental is scheduled for tomorrow at 10:30 AM",
"suggestions":[
{
"reply":{
"text":"Confirm",
"postbackData":"user_confirmed"
}
},
{
"reply":{
"text":"Reschedule",
"postbackData":"user_rescheduled"
}
},
{
"action":{
"text":"Add to Calendar",
"postbackData":"add_event_to_calendar",
"createCalendarEventAction":{
"title":"Dental Appointment",
"description":"Appointment at Wellness Dental",
"startTime":"2026-02-15T10:30:00Z",
"endTime":"2026-02-15T11:00:00Z"
}
}
},
{
"action":{
"text":"View Location",
"postbackData":"view_clinic_location",
"viewLocationAction":{
"latLong":{
"latitude":37.7749,
"longitude":-122.4194
},
"label":"Wellness Dental"
}
}
},
{
"action":{
"text":"Visit Website",
"postbackData":"open_website",
"openUrlAction":{
"url":"https://developer.8x8.com/connect/docs/rcs/message-types",
"application":"WEBVIEW",
"webviewViewMode":"FULL",
"description":"Visit our website"
},
"fallbackUrl":"https://developer.8x8.com/connect/docs/rcs/message-types"
}
}
]
}
}

Overview of file types and limits

Supported File formats are

Limits

Overview

This guide will take you through how to integrate 8x8's SMS API into Okta as an authenticator method using an Okta Inline Hook. Specifically we will be using Okta's Telephony Inline Hook to add 8x8's SMS API as an option.

For Okta's own guide on bringing your own telephony provider, refer to Okta's reference guide here and use Option 2.

The diagram below explains how the flow will look like from using Okta together with the Node.js server we will be building in this tutorial to send OTPs via 8x8 SMS API.

Video Demo

This Video Demo shows the integration in action and explains a high level of the setup steps in this guide. We recommend referring to this text guide for the full setup.

Requirements

• Okta Account (an Okta Dev Account is fine for testing).
• 8x8 Account and Subaccount with a SMS Sender.
• JavaScript Knowledge for running the sample code.
• API Endpoint for Okta to send a HTTP request. Required as part of their Inline Hook integration.

Setup

Setup Backend Code

We will need an example endpoint for Okta to send it's HTTP request to. We have provided some example Node.js server code below for you to use:

const express =require('express');
const bodyParser =require('body-parser');
const axios =require('axios');
const{ apiKey, subaccount, sender, authKey }=require('./config');
const app =express();
constPORT=3000;
// Middleware to parse JSON bodies
app.use(bodyParser.json());
// Function to send a successful response to Okta
constsendSuccessResponse=(res, umid, transactionMetadata)=>{
    res.status(200).json({
commands:[
{
type:"com.okta.telephony.action",
value:[
{
status:"SUCCESSFUL",
provider:"8x8",
transactionId: umid,
transactionMetadata:JSON.stringify(transactionMetadata)
}
]
}
]
});
};
// Function to send an error response to Okta
constsendErrorResponse=(res, errorData)=>{
const errorSummary =`8x8 Error Code: ${errorData.code}. 8x8 Error Message: ${errorData.message}`;
    res.status(500).json({
error:{
errorSummary: errorSummary
}
});
};
app.post('/telephony-hook',async(req, res)=>{
// Print the request body
console.log('Received request body:', req.body);
// Check if the Authorization header is correct
const authHeader = req.headers['authorization'];
if(authHeader !== authKey){
console.log('Unauthorized request');
return res.status(401).json({error:'Unauthorized'});
}
// Check if the required fields are present
const{ msgTemplate, phoneNumber }= req.body.data.messageProfile;
if(!msgTemplate ||!phoneNumber){
console.log('Invalid request data:', req.body.data);
return res.status(400).json({error:'Invalid request data'});
}
// Send OTP using 8x8's SMS API
try{
const response =await axios.post(
`https://sms.8x8.com/api/v1/subaccounts/${subaccount}/messages`,
{
source: sender,
destination: phoneNumber,
text: msgTemplate,
encoding:"AUTO"
},
{
headers:{
'Authorization':`Bearer ${apiKey}`
}
}
);
// Print successful response
console.log('OTP sent successfully:', response.data);
// Respond with a successful delivery response
sendSuccessResponse(res, response.data.umid, response.data);
}catch(error){
// Print error response
console.log('Failed to send OTP:', error.message);
// Handle errors from the SMS API and respond with an error delivery response
if(error.response&& error.response.data){
sendErrorResponse(res, error.response.data);
}else{
sendErrorResponse(res,{code:'UNKNOWN',message:'An unknown error occurred'});
}
}
});
app.listen(PORT,()=>{
console.log(`Server is running on port ${PORT}`);
});