Authentication

All requests require HTTP Basic Authentication using your username and password.

Tips

• Optional fields (like callbackURL and failover objects) can be left out for simpler requests.
• Use choices in cards and carousels to make messages interactive.
• Fallback objects (smsFailover, mmsFailover) help ensure message delivery if RCS is unavailable.

Send RCS Texts

Send a simple text message to a recipient. Rich Communication Services text message with optional interactive choices.

⚠️ Important: RCS is not available for phone numbers. The source field must be a valid RCS sender (e.g., “CONVEY”). If you have questions about RCS sender availability or setup, please contact support.

To send an RCS Text:

• Send a POST request to /v5/messages.
• Include sender, recipient, and your message text.
• Include “RCS_TEXT” as the messageType.
• Optionally, add a callback URL for delivery status and SMS failover info.

RCS Text Elements

Element	Required?	Description
messageType	Required	Type of message, always “RCS_TEXT” for text messages.
source	Required	The sender’s address or phone number.
destination	Required	The recipient’s address or phone number.
messageText	Required	The text content to send.
enabled	Required	Set to true to enable SMS fallback.
failoverSource	Required	Sender address for the fallback SMS.
fallbackText	Required	Text to send if fallback is triggered.
callbackURL	Optional	URL to receive delivery status updates.
choices	Optional	Array of choice objects (see RCS Choice Types section). All choice types are supported (REPLY, OPEN_URL, DIAL_PHONE, SHOW_LOCATION, REQUEST_LOCATION, CREATE_CALENDAR_EVENT)
smsFailover	Optional	Object for SMS fallback if RCS delivery fails.

Example

json

{
  "messageType": "RCS_TEXT",
  "source": "CONVEY",
  "destination": "15559876543",
  "messageText": "Hello from RCS!",
  "choices": [
    {
      "type": "REPLY",
      "title": "Yes",
      "postbackData": "yes_response"
    },
    {
      "type": "OPEN_URL",
      "title": "Learn More",
      "postbackData": "learn_more",
      "url": "https://example.com/info",
      "application": "BROWSER",
      "webviewViewMode": "FULL"
    }
  ],
  "smsFailover": {
    "enabled": true,
    "failoverSource": "15551234567",
    "fallbackText": "Fallback message if RCS fails"
  }
}

Send RCS Media Messages

RCS message with media content and optional interactive choices.

To send RCS Media Messages:

• Send a POST request to /v5/messages.
• Provide sender, recipient, and the following required fields: mediaUrl, thumbnailUrl, filenameOverride
• Include “RCS_MEDIA” as the messageType.
• Optionally, add a callback URL and MMS failover info.

RCS Media Message Elements

Element	Required?	Description
messageType	Required	Type of message, always “RCS_MEDIA” for media messages.
source	Required	The sender’s address or phone number.
destination	Required	The recipient’s address or phone number.
mediaUrl	Required	URL of the media file to send (image, video, etc.).
thumbnailUrl	Required	URL of the thumbnail image for the media.
filenameOverride	Required	Custom filename for the media file.
enabled	Required	Set to true to enable MMS fallback.
failoverSource	Required	Sender address for the fallback MMS.
fallbackText	Required	Text to send if fallback is triggered.
subject	Required	Subject line for the fallback MMS.
callbackURL	Optional	URL to receive delivery status updates.
choices	Optional	Array of choice objects (see RCS Choice Types section). All choice types are supported (REPLY, OPEN_URL, DIAL_PHONE, SHOW_LOCATION, REQUEST_LOCATION, CREATE_CALENDAR_EVENT)
mmsFailover	Optional	Object for MMS fallback if RCS delivery fails.

Example

json

{
  "messageType": "RCS_MEDIA",
  "source": "CONVEY",
  "destination": "15559876543",
  "mediaUrl": "https://example.com/media.jpg",
  "thumbnailUrl": "https://example.com/thumbnail.jpg",
  "filenameOverride": "custom_name.jpg",
  "choices": [
    {
      "type": "DIAL_PHONE",
      "title": "Call Us",
      "postbackData": "call_action",
      "phoneNumber": "15551234567"
    }
  ],
  "mmsFailover": {
    "enabled": true,
    "failoverSource": "15551234567",
    "fallbackText": "Fallback message",
    "mediaUrl": "https://example.com/fallback_media.jpg",
    "subject": "Fallback Media Subject"
  }
}

Send RCS Card Message

RCS card message with title, description, media, and interactive choices (maximum 4 choices).

To do this:

• Send a POST request to /v5/messages.
• Include sender, recipient, card title, description, and image URLs.
• Include “RCS_CARD” as the messageType.
• Add choices for user interaction (4 choices max).
• Optionally, add a callback URL and MMS failover info.

RCS Card Message Elements

Element	Required?	Description
messageType	Required	Type of message, always “RCS_CARD” for card messages.
source	Required	The sender’s address or phone number.
destination	Required	The recipient’s address or phone number.
title	Required	Title of the card.
description	Required	Description text for the card.
height	Required	Card height; possible values are SHORT, MEDIUM, TALL.
mediaUrl	Required	URL of the main image for the card.
choices	Required	Array of interactive choices for the user (10 max).
title	Required	Title of the choice.
description	Required	Description of the choice.
postbackData	Required	Data sent back when the choice is selected.
enabled	Required	Set to true to enable MMS fallback.
failoverSource	Required	Sender address for the fallback MMS.
fallbackText	Required	Text to send if fallback is triggered.
mediaUrl	Required	URL of the fallback media file.
subject	Required	Subject line for the fallback MMS.
callbackURL	Optional	URL to receive delivery status updates.
choices	Optional	Array of choice objects (see RCS Card Choices section).
filenameOverride	Optional	Custom filename for the card image.
mmsFailover	Optional	Object for MMS fallback if RCS delivery fails.
thumbnailUrl	Optional	URL of the thumbnail image for the card.

Example

json

{
  "messageType": "RCS_CARD",
  "source": "CONVEY",
  "destination": "15559876543",
  "title": "Welcome!",
  "description": "This is a card message with media and choices.",
  "height": "MEDIUM",
  "mediaUrl": "https://example.com/media.jpg",
  "thumbnailUrl": "https://example.com/thumbnail.jpg",
  "filenameOverride": "custom_name.jpg",
  "choices": [
    {
      "type": "OPEN_URL",
      "title": "Learn More",
      "postbackData": "learn_more",
      "url": "https://example.com/info",
      "application": "WEBVIEW",
      "webviewViewMode": "FULL"
    },
    {
      "type": "DIAL_PHONE",
      "title": "Contact Us",
      "postbackData": "contact_us",
      "phoneNumber": "15551234567"
    }
  ],
  "mmsFailover": {
    "enabled": true,
    "failoverSource": "15551234567",
    "fallbackText": "Fallback message if RCS fails",
    "mediaUrl": "https://example.com/fallback_media.jpg",
    "subject": "Fallback Media Subject"
  }
}

Send RCS Carousel Message

Send a carousel of multiple cards, each with images and choices.

To do this:

• Send a POST request to /v5/messages.
• Include sender, recipient, and an array of cards (10 cards max).
• Include “RCS_CAROUSEL” as the messageType.
• Each card can have its own title, description, images, and choices.
• Optionally, add a callback URL and MMS failover info.

RCS Carousel Message Elements

Element	Required?	Description
messageType	Required	Type of message, always “RCS_CAROUSEL” for carousel messages.
source	Required	The sender’s address or phone number.
destination	Required	The recipient’s address or phone number.
cards	Required	Array of card objects (10 max), each representing a card in the carousel. (see Carousel Cards section)
title	Required	Title of the card.
description	Required	Description text for the card.
height	Required	Card height; possible values are SHORT, MEDIUM, TALL.
mediaUrl	Required	URL of the main image for the card.
thumbnailUrl	Required	URL of the thumbnail image for the card.
filenameOverride	Required	Custom filename for the card image.
choices	Required	Array of interactive choices for the user. (see RCS Card Choices section).
title	Required	Title of the choice.
description	Required	Description of the choice.
postbackData	Required	Data sent back when the choice is selected.
enabled	Required	Set to true to enable MMS fallback.
failoverSource	Required	Sender address for the fallback MMS.
fallbackText	Required	Text to send if fallback is triggered.
subject	Required	Subject line for the fallback MMS.
callbackURL	Optional	URL to receive delivery status updates.
mmsFailover	Optional	Object for MMS fallback if RCS delivery fails.

Example

json

{
  "messageType": "RCS_CAROUSEL",
  "source": "CONVEY",
  "destination": "15559876543",
  "cards": [
    {
      "title": "Card 1",
      "description": "First card in the carousel.",
      "height": "MEDIUM",
      "mediaUrl": "https://example.com/media1.jpg",
      "thumbnailUrl": "https://example.com/thumb1.jpg",
      "filenameOverride": "media1.jpg",
      "choices": [
        {
          "type": "OPEN_URL",
          "title": "View",
          "postbackData": "view_card_1",
          "url": "https://example.com/details",
          "application": "WEBVIEW",
          "webviewViewMode": "TALL"
        }
      ]
    },
    {
      "title": "Card 2",
      "description": "Second card in the carousel.",
      "height": "SHORT",
      "mediaUrl": "https://example.com/media2.jpg",
      "thumbnailUrl": "https://example.com/thumb2.jpg",
      "filenameOverride": "media2.jpg",
      "choices": [
        {
          "type": "DIAL_PHONE",
          "title": "Call Now",
          "postbackData": "call_now",
          "phoneNumber": "15551234567"
        }
      ]
    }
  ],
  "mmsFailover": {
    "enabled": true,
    "failoverSource": "15551234567",
    "fallbackText": "Fallback message if RCS fails",
    "mediaUrl": "https://example.com/fallback_media.jpg",
    "subject": "Fallback Media Subject"
  }
}

---

RCS Choice Types

Choices are available for all RCS message types (RCS_TEXT, RCS_MEDIA, RCS_CARD, RCS_CAROUSEL).

All RCS choices use the same format with a type field that determines the required fields.

PLEASE NOTE:

• For RCS_TEXT and RCS_MEDIAChoices are optional, no maximum limit
• For RCS_CARD and RCS_CAROUSELChoices are optional, maximum 4 choices per card
• All choices require title, postbackData, and type fields
• Additional fields are required based on the type value

Each choice must have a type field that determines the required fields. The following types are supported for all RCS message types:

Reply Button

Includes a simple reply button within the RCS interaction.

Field	Required?	Description
type	Required	“REPLY”
title	Required	Button text (max 25 characters)
postbackData	Required	Data sent when choice is selected (max 2048 characters)

Example (json)

{
  "type": "REPLY",
  "title": "Yes",
  "postbackData": "yes_response"
}

Launch URL

Opens a URL in browser or webview.

Field	Required?	Description
type	Required	“OPEN_URL”
title	Required	Button text (max 25 characters)
postbackData	Required	Data sent when choice is selected (max 2048 characters)
url	Required	URL to open (max 2048 characters, must be valid URI)
application	Required	“BROWSER” or “WEBVIEW”
webviewViewMode	Required	“FULL”, “HALF”, or “TALL”

Example (json)

{
  "type": "OPEN_URL",
  "title": "Learn More",
  "postbackData": "learn_more",
  "url": "https://example.com/info",
  "application": "BROWSER",
  "webviewViewMode": "FULL"
}

Launch Phone Call

Initiates a phone call.

Field	Required?	Description
type	Required	“DIAL_PHONE”
title	Required	Button text (max 25 characters)
postbackData	Required	Data sent when choice is selected (max 2048 characters)
phoneNumber	Required	Phone number to dial (max 20 characters)

Example (json)

{
  "type": "DIAL_PHONE",
  "title": "Call Us",
  "postbackData": "call_action",
  "phoneNumber": "15551234567"
}

Display Map Location

Displays a location on a map.

Field	Required?	Description
type	Required	“SHOW_LOCATION”
title	Required	Button text (max 25 characters)
postbackData	Required	Data sent when choice is selected (max 2048 characters)
latitude	Required	Number between -90 and 90 (6 decimal precision)
longitude	Required	Number between -180 and 180 (6 decimal precision)
label	Optional	Label text for the location marker

Example (json)

{
  "type": "SHOW_LOCATION",
  "title": "Show Location",
  "postbackData": "show_location",
  "latitude": 37.7749,
  "longitude": -122.4194,
  "label": "Our Office"
}

Request Location

Requests the user’s current location.

Field	Required?	Description
type	Required	“REQUEST_LOCATION”
title	Required	Button text (max 25 characters)
postbackData	Required	Data sent when choice is selected (max 2048 characters)

Example (json)

{
  "type": "REQUEST_LOCATION",
  "title": "Share Location",
  "postbackData": "request_location"
}

Create Calendar Event

Creates a calendar event.

Field	Required?	Description
type	Required	“CREATE_CALENDAR_EVENT”
title	Required	Button text (max 25 characters)
postbackData	Required	Data sent when choice is selected (max 2048 characters)
startTime	Required	ISO 8601 date string (e.g., “2030-03-03T15:00:00.000+01:00” or “2030-03-03T15:00:00Z”)
endTime	Required	ISO 8601 date string (same format as startTime)
eventTitle	Required	Event title (max 100 characters)
description	Optional	Event description (max 500 characters)

Date Format Examples

• “2030-03-03T15:00:00.000+01:00” - With timezone offset
• “2030-03-03T15:00:00Z” - UTC timezone (Zulu time)
• “2030-03-03T15:00:00-05:00” - With negative timezone offset

Example (json)

{
  "type": "CREATE_CALENDAR_EVENT",
  "title": "Add to Calendar",
  "postbackData": "create_event",
  "startTime": "2030-03-03T15:00:00.000+01:00",
  "endTime": "2030-03-03T16:00:00.000+01:00",
  "eventTitle": "Meeting",
  "description": "Team meeting to discuss project"
}

RCS Card Choices

NOTE: Choices for RCS_CARD and RCS_CAROUSEL use the same format as RCS choices (see RCS Choice Types above), with the following differences:

• Maximum 4 choices per card (for RCS_CARD and RCS_CAROUSEL only)
• All choice types are supported (REPLY, OPEN_URL, DIAL_PHONE, SHOW_LOCATION, REQUEST_LOCATION, CREATE_CALENDAR_EVENT)
• Same conditional field requirements based on type

Example for RCS_CARD with different choice types (json):
{
“choices”: [
{
“type”: “OPEN_URL”,
“title”: “View Details”,
“postbackData”: “view_details”,
“url”: “https://example.com/details",
“application”: “WEBVIEW”,
“webviewViewMode”: “HALF”
},
{
“type”: “DIAL_PHONE”,
“title”: “Call Now”,
“postbackData”: “call_now”,
“phoneNumber”: “15551234567”
},
{
“type”: “REPLY”,
“title”: “Yes”,
“postbackData”: “yes_response”
}
]
}

Carousel Cards

Each card in a carousel (RCS_CAROUSEL) has the following structure:

Field	Required?	Description
title	Required	Card title (max 100 characters)
description	Required	Card description (max 500 characters)
height	Required	“SHORT”, “MEDIUM”, or “TALL”
mediaUrl	Required	Media URL (must be valid URI)
thumbnailUrl	Optional	Thumbnail image URL (must be valid URI)
filenameOverride	Optional	Custom filename (max 100 characters)
choices	Optional	Array of choice objects (max 4, see RCS Choice Types above)

---

Failover Options

SMS Failover

Fallback to SMS if RCS message fails.

Field	Required?	Description
enabled	Required	Boolean - Enable/disable SMS failover
failoverSource	Required	String (max 50) - SMS source number (required if enabled)
fallbackText	Required	String (max 160) - SMS text to send (required if enabled)

NOTE: The failoverSource number must be on the same connection as the main message source.

Example (json)

{
  "smsFailover": {
    "enabled": true,
    "failoverSource": "15551234567",
    "fallbackText": "Fallback message if RCS fails"
  }
}

MMS Failover

Fallback to MMS if RCS message fails.

Field	Required?	Description
enabled	Required	Boolean - Enable/disable MMS failover
failoverSource	Required	String (max 50) - MMS source number (required if enabled)
fallbackText	Required	String (max 160) - MMS text to send (required if enabled)
mediaUrl	Required	String (URI) - Media URL for MMS (required if enabled)
subject	Required	String (max 100) - MMS subject (required if enabled)

NOTE: The failoverSource number must be on the same connection as the main message source.

Example (json)

{
  "mmsFailover": {
    "enabled": true,
    "failoverSource": "15551234567",
    "fallbackText": "Fallback message if RCS fails",
    "mediaUrl": "https://example.com/fallback_media.jpg",
    "subject": "Fallback Media Subject"
  }
}

---

Response Format

Success Response

Status Code: 200 OK

(json)
{
“status”: “success”,
“message”: “Message successfully queued”,
“data”: {
“results”: [
{
“messageGUID”: “550e8400-e29b-41d4-a716-446655440000”,
“destination”: “15559876543”,
“status”: “success”
}
]
}
}

Error Response

Status Code: 400 Bad Request
The error response includes a data array containing detailed validation errors. Each error object has:

• field - The field path where the error occurred (e.g., “choices.1.postbackData” for nested errors)
• description - A human-readable description of the field
• message - The specific validation error message

Simple Error Example:
(json)
{
“status”: “error”,
“message”: “Missing or invalid parameters in body”,
“data”: [
{
“field”: “messageText”,
“description”: “Message Text”,
“message”: “‘messageText’ is required”
}
]
}

Nested Error Example (Choices):
(json)
{
“status”: “error”,
“message”: “Missing or invalid parameters in body”,
“data”: [
{
“field”: “choices.0.webviewViewMode”,
“description”: “webviewViewMode”,
“message”: “When choice type is OPEN_URL, ‘webviewViewMode’ is required”
},
{
“field”: “choices.1.postbackData”,
“description”: “postbackData”,
“message”: “‘postbackData’ is required”
},
{
“field”: “choices.2.phoneNumber”,
“description”: “phoneNumber”,
“message”: “When choice type is DIAL_PHONE, ‘phoneNumber’ is required”
}
]
}

Nested Error Example (Carousel Cards):
(json)
{
“status”: “error”,
“message”: “Missing or invalid parameters in body”,
“data”: [
{
“field”: “cards.0.mediaUrl”,
“description”: “mediaUrl”,
“message”: “‘mediaUrl’ is required”
},
{
“field”: “cards.1.choices.0.url”,
“description”: “url”,
“message”: “When choice type is OPEN_URL, ‘url’ is required”
},
{
“field”: “cards.2.choices.1.latitude”,
“description”: “latitude”,
“message”: “When choice type is SHOW_LOCATION, ‘latitude’ is required”
}
]
}

---

Validation Rules

Field Lengths

• messageTextRequired for SMS and RCS_TEXT
• title (in all RCS choices): Max 25 characters
• postbackData (in all RCS choices): Max 2048 characters
• title (card): Max 100 characters
• description (card): Max 500 characters