Aerialink RCS Messages API Documentation

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

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

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

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

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.

Example (json)

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

Launch URL

Opens a URL in browser or webview.

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.

Example (json)

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

Display Map Location

Displays a location on a map.

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.

Example (json)

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

Create Calendar Event

Creates a calendar event.

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:

Failover Options

SMS Failover

Fallback to SMS if RCS message fails.

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.

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