Send RCS messages

RCS messages are sent through the same endpoint as SMS, MMS, and WhatsApp, POST /api/messaging/messages. Setting from to the ID of your RCS agent routes the message over RCS. The Agent ID is shown on the agent’s page in the Dashboard.

For the full request schema and authentication, see the Send a message API reference. To send SMS and MMS from the same endpoint, see Send and receive messages.

The Relay SDK sends RCS the same way: pass your agent’s ID as the sender, and the rules and errors on this page apply. To answer an inbound RCS message from a SWML script, see Reply with SWML.

Messaging rules

• to must be a US phone number. Numbers in any other country, including Canada and US territories such as Puerto Rico, are rejected with rcs_recipient_country_not_supported. The examples below use +1555 placeholders, so replace them with a real US number.
• The agent must be in_review, launching, or launched.
• Send either body for plain text or content for rich content, never both.
• media and message_type are not supported. Send media with a content of type media instead.
• status_callback and custom_variables work the same way as for SMS, as described in Track delivery via REST.

Until the agent is launched, it can reach only the test device numbers registered on it. This isn’t checked when you send: a message to any other number is accepted with status: queued and isn’t delivered, so watch its delivery status rather than expecting a 422.

Content types

Set content.type to one of the following. Each value determines the other fields of content.

Suggestions in actions take one of these types:

Examples

Plain text

{
  "to": "+15551234567",
  "from": "<YOUR_AGENT_ID>",
  "body": "Your appointment is confirmed for tomorrow at 2pm."
}

Text with suggested replies

{
  "to": "+15551234567",
  "from": "<YOUR_AGENT_ID>",
  "content": {
    "type": "suggestions",
    "text": "Can you make your appointment tomorrow at 2pm?",
    "actions": [
      { "type": "reply", "title": "Yes, confirm" },
      { "type": "reply", "title": "Reschedule" },
      { "type": "call", "title": "Call us", "phone": "+15557654321" }
    ]
  }
}

Rich card

A card has a title and, optionally, a subtitle, a media URL, and suggestions.

{
  "to": "+15551234567",
  "from": "<YOUR_AGENT_ID>",
  "content": {
    "type": "card",
    "title": "Your order has shipped",
    "subtitle": "Order #12345 arrives Thursday.",
    "media": "https://example.com/images/package.png",
    "actions": [
      { "type": "url", "title": "Track your order", "url": "https://example.com/orders/12345" }
    ]
  }
}

Carousel

A carousel holds up to 10 cards and up to 3 suggestions under them.

{
  "to": "+15551234567",
  "from": "<YOUR_AGENT_ID>",
  "content": {
    "type": "carousel",
    "cards": [
      {
        "title": "Classic sneaker",
        "subtitle": "$89",
        "media": "https://example.com/images/classic.png",
        "actions": [{ "type": "url", "title": "Buy", "url": "https://example.com/products/classic" }]
      },
      {
        "title": "Trail runner",
        "subtitle": "$119",
        "media": "https://example.com/images/trail.png",
        "actions": [{ "type": "url", "title": "Buy", "url": "https://example.com/products/trail" }]
      }
    ],
    "actions": [
      { "type": "reply", "title": "Show me more" }
    ]
  }
}

Verify the send

A successful request returns the message with kind: rcs and status: queued. For a rich message, body in the response holds your content serialized as a JSON string. Set status_callback to follow the message as its status changes, as described in Receive RCS messages.

When the request is rejected with a 422, the code says why. The RCS-specific codes, and the general messaging codes an RCS send most often hits, are:

For every other code, see Error codes.

Next steps