This guide walks you through sending your first RCS message using the InstaMessage Messaging API.

RCS (Rich Communication Services) is the next generation of SMS. It shows your verified brand name and logo, and supports images, video, files, rich cards and suggested reply buttons, all in the recipient's native messaging app.

You'll learn how to authenticate, send RCS text, media and rich messages, personalise content using injected_fields, and understand the API response.

To send RCS messages through InstaMessage, you'll need the following:

If you're new to InstaMessage, contact our sales team to set up your account:

[email protected]

RCS messages are sent from an RCS agent (your verified brand sender), not a phone number.

Each agent must be registered and approved by Google and the mobile carriers before it can send messages. This includes your brand name, logo, colour, description and use case.

To get your RCS agent set up, contact our team:

[email protected]

Once approved, the agent is connected to your InstaMessage account and becomes the sender for all RCS messages sent via the API. You don't pass a sender in your requests.

Carrier approval and country availability apply. RCS can only be delivered to recipients whose device and carrier support RCS.

You can find your API key in the InstaMessage dashboard:

1. Go to Admin → API
2. Select Show Key under API Live Key
3. Copy your API Key

Your API key is tied to your InstaMessage account and authorises access to all InstaMessage APIs.

Important: Treat your API key like a password. Never share it publicly or commit it to source control.

Each account has a single active API key. Subaccounts and environments will be supported in future.

InstaMessage uses API key authentication.

Each API request must include a valid API key issued to your account.

Authorization: Bearer YOUR_API_KEY

All RCS messages are sent using the unified messaging endpoint:

POST https://api.instamessage.co.uk/v1/messages

Required fields

Conditional fields

Media URLs must be publicly accessible over HTTPS and up to 2,000 characters; longer URLs are rejected with error 4045. Media files can be up to 100 MB. Captions are not supported on RCS media messages; send a separate text message if you need one.

Templates (message_type: "template") and audio messages are not supported on RCS.

{
  "channel": "rcs",
  "to": "+447123456789",
  "message_type": "image",
  "image": {
    "url": "https://example.com/images/order-12345.png"
  }
}

{
  "channel": "rcs",
  "to": "+447123456789",
  "message_type": "video",
  "video": {
    "url": "https://example.com/videos/how-to-return.mp4"
  }
}

{
  "channel": "rcs",
  "to": "+447123456789",
  "message_type": "file",
  "file": {
    "url": "https://example.com/invoices/INV-12345.pdf"
  }
}

Use message_type: "custom" to send rich cards, carousels and suggested replies or actions.

The custom object must contain a contentMessage, following the Google RCS Business Messaging (RBM) AgentContentMessage format. InstaMessage checks it against the rich content limits, then passes it through to the recipient unchanged.

A message can carry up to 11 suggestions. When the recipient taps a suggested reply, it arrives as an inbound message.

{
  "channel": "rcs",
  "to": "+447123456789",
  "message_type": "custom",
  "custom": {
    "contentMessage": {
      "text": "Your delivery is booked for tomorrow. Does that work?",
      "suggestions": [
        { "reply": { "text": "Yes, thanks", "postbackData": "CONFIRM" } },
        { "reply": { "text": "Reschedule", "postbackData": "RESCHEDULE" } },
        {
          "action": {
            "text": "Track order",
            "postbackData": "TRACK",
            "openUrlAction": { "url": "https://example.com/track/12345" }
          }
        }
      ]
    }
  }
}

{
  "channel": "rcs",
  "to": "+447123456789",
  "message_type": "custom",
  "custom": {
    "contentMessage": {
      "richCard": {
        "standaloneCard": {
          "cardOrientation": "VERTICAL",
          "cardContent": {
            "title": "Your order is on its way",
            "description": "Order 12345 will arrive today between 10:00 and 12:00.",
            "media": {
              "height": "MEDIUM",
              "contentInfo": {
                "fileUrl": "https://example.com/images/van.png",
                "forceRefresh": false
              }
            },
            "suggestions": [
              {
                "action": {
                  "text": "Track order",
                  "postbackData": "TRACK",
                  "openUrlAction": { "url": "https://example.com/track/12345" }
                }
              }
            ]
          }
        }
      }
    }
  }
}

{
  "channel": "rcs",
  "to": "+447123456789",
  "message_type": "custom",
  "custom": {
    "contentMessage": {
      "richCard": {
        "carouselCard": {
          "cardWidth": "MEDIUM",
          "cardContents": [
            {
              "title": "Classic Hoodie",
              "description": "£45.00",
              "media": {
                "height": "MEDIUM",
                "contentInfo": { "fileUrl": "https://example.com/images/hoodie.png" }
              },
              "suggestions": [
                { "reply": { "text": "Buy hoodie", "postbackData": "BUY_HOODIE" } }
              ]
            },
            {
              "title": "Everyday Tee",
              "description": "£20.00",
              "media": {
                "height": "MEDIUM",
                "contentInfo": { "fileUrl": "https://example.com/images/tee.png" }
              },
              "suggestions": [
                { "reply": { "text": "Buy tee", "postbackData": "BUY_TEE" } }
              ]
            }
          ]
        }
      }
    }
  }
}

InstaMessage checks custom against the Google RBM and Vonage limits before accepting the message. A payload that breaks a limit is rejected with a 400 and error 4044, and the message names the rule, so nothing is sent or charged.

Other fields are passed through as sent. A field set to null counts as not set.

{
  "code": 4044,
  "message": "Invalid RCS rich content: carouselCard.cardContents must have 2-10 cards"
}

Rich card media must be an image or video. PDFs can't be used in cards.

These checks cover the payload's structure only. Media file types and sizes are checked when the message is sent, so an unsupported file still fails at delivery.

• injected_fields are applied at send time and do not modify stored contact data.
• If a contact exists, InstaMessage can also use stored contact fields and custom attributes.
• If a field exists in both places, injected_fields takes precedence.

• Contact first_name = "Adam"
• You send injected_fields.first_name = "Eve"
• {{first_name}} renders as "Eve"

How an RCS message is charged depends on your agent's billing category and the content you send.

Per-message pricing (default)

• Basic message: a text message of up to 160 characters
• Rich message: a text message over 160 characters, or any image, video, file or custom message

Conversational agents

If your agent is registered as conversational, a reply from the recipient opens a 24-hour conversation window:

• The first message you send inside the window is charged a single conversation fee
• Every further message you send in that window is free
• Messages sent outside a window use per-message pricing

Contact your account manager for RCS pricing in your region.

• RCS messages are sent immediately
• Messages are sent from your approved RCS agent. You can't choose a different sender per message
• The recipient's device and carrier must support RCS
• Media URLs must be publicly reachable when the message is sent

InstaMessage reports delivery outcomes and inbound replies using account-level webhooks.

Webhooks are configured once per account and apply to all messages sent via the API.

Delivery status webhooks

When a message status updates (such as delivered, read or failed), InstaMessage sends a delivery status webhook to your configured webhook URL.

Replies and suggestion taps from the recipient are delivered as inbound message webhooks.

{
  "event_type": "message.status",
  "message_id": "abc123XYZ789def",
  "conversation_id": "conv456ABC123",
  "channel": "rcs",
  "to": "+447123456789",
  "status": "delivered",
  "timestamp": "2026-01-14T12:03:11Z"
}

If you miss a webhook delivery, you can retrieve the latest delivery status using the message ID returned when the message was created.

See: Delivery tracking → Delivery Receipts & Message Status

This endpoint acts as a recovery mechanism if a webhook delivery is missed.

{
  "message_id": "abc123XYZ789def",
  "conversation_id": "conv456ABC123",
  "channel": "rcs",
  "to": "+447123456789",
  "status": "delivered",
  "created_at": "2026-01-14T12:02:10Z",
  "delivered_at": "2026-01-14T12:03:11Z"
}

Below is a basic example in multiple languages.

curl -X POST "https://api.instamessage.co.uk/v1/messages" \
  -H "Authorization: Bearer $IM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "rcs",
    "to": "+447123456789",
    "message_type": "text",
    "text": "Your delivery is on its way."
  }'

Use placeholders inside your text and supply values via injected_fields.

{
  "channel": "rcs",
  "to": "+447123456789",
  "message_type": "text",
  "text": "Hi {{first_name}}, your order {{order}} is out for delivery today.",
  "injected_fields": {
    "first_name": "Alex",
    "order": "12345"
  }
}

Rendered output:

Hi Alex, your order 12345 is out for delivery today.

{
  "message_id": "abc123XYZ789def",
  "conversation_id": "conv456ABC123"
}

Delivery status and timestamps are provided asynchronously via webhooks or can be retrieved using the message ID.

Requests that fail validation return HTTP 400 with a code and message. No message is created and nothing is charged.

Now that you can send RCS, you may want to:

• Delivery tracking → Delivery Receipts & Message Status
• Customer replies → Inbound Messages & Replies
• Webhooks → Webhook Quick-Start
• Rich content reference → Google RBM: Send messages