Send RCS messages with the Fast2SMS API: text, rich card, media and carousel

To send an RCS message with the Fast2SMS API, POST to https://www.fast2sms.com/dev/rcs with your API key, your Bot ID, the mobile number and a type: plain, rich, media or carousel. This guide shows where to find the Bot ID, every field, a ready example for each message type with a button, code in PHP, Python and Node.js, and how RCS charges and refunds work.

Before you start

  • An approved RCS brand with an Active bot. See RCS brand registration and approval.
  • Your API key from API Key under UTILITY.
  • Wallet balance for the messages you plan to send.
  • For images and videos, a public https link to each file.

Send your first RCS message by API

  1. Copy your Bot ID

    Open RCS Manager and click Bots. Each bot shows its name, Bot ID with a copy button, its category (transactional, promotional or OTP), today’s usage and its status. Use the Bot ID of an Active bot.

    RCS Manager Bots page listing three bots with Bot IDs, categories OTP, promotional and transactional, usage counts and Active or Inactive status
    The Bot ID is the value you send as bot_id.
  2. Download the RCS API Excel (optional)

    Go to Account Setting, API Excel, pick RCS and click Download Excel. It has ready API URLs for each of your approved bots, one row per scenario, with the parameters and notes.

    API Excel page with the RCS tab selected showing the RCS API Excel card and a Download Excel button
    The RCS API Excel lists sample requests for your bots.
  3. Send a plain message

    curl -X POST "https://www.fast2sms.com/dev/rcs" \
      -H "authorization: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"bot_id":"demotraders_txn_agent","to":"9999999999","type":"plain",
           "message":"Hi Rahul, your order DT-1042 has been shipped."}'
  4. Save the request_id

    Success looks like this:

    {"return":true,"request_id":"R4Yhz6HA8kATqft","message":["RCS Message will be sent."]}

    The ID starts with R. Use it to find the message in Delivery Report under RCS and to match webhook updates.

All fields

Field Needed for Rules
bot_id All Your Bot ID from RCS Manager. The bot must be yours, approved and active
to All One Indian mobile number, 10 digits starting 6 to 9; +91 or 91 in front is fine
type All plain, rich, media or carousel
message plain, rich The text, up to 3,000 characters
title rich (optional) Up to 100 characters
media_url media (required), rich (optional) Public link to the image or file
suggestion_type Optional button openUrl, dial or viewLocation
suggestion_text With a button Button label, up to 25 characters
suggestion_url openUrl The link the button opens
suggestion_phone dial The number the button calls
latitude, longitude, location_label viewLocation Map point; label up to 100 characters
cards carousel 2 to 10 cards, each with title (up to 255), description (up to 2,000), optional media_url and the same button fields
udf1 to udf3 Optional Your own tracking values, returned in webhooks

Through the API each message, and each carousel card, takes one button. The Bulk RCS page in the panel allows up to 4 buttons per message.

Examples for each message type

Plain text with a website button

curl -X POST "https://www.fast2sms.com/dev/rcs" \
  -H "authorization: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"bot_id":"demotraders_txn_agent","to":"9999999999","type":"plain",
       "message":"Your order DT-1042 is out for delivery today.",
       "suggestion_type":"openUrl","suggestion_text":"Track order",
       "suggestion_url":"https://example.com/track/DT-1042"}'

Rich card: image, title, text and a call button

curl -X POST "https://www.fast2sms.com/dev/rcs" \
  -H "authorization: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"bot_id":"demotraders_promo_agent","to":"9999999999","type":"rich",
       "title":"Festive Sale at Demo Traders",
       "message":"Flat 20% off on kitchenware till 25 Nov. Visit 12 Demo Market, Pune.",
       "media_url":"https://example.com/offers/festive-sale.jpg",
       "suggestion_type":"dial","suggestion_text":"Call store","suggestion_phone":"9999999999"}'

Media only (image, video or PDF)

curl -X POST "https://www.fast2sms.com/dev/rcs" \
  -H "authorization: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"bot_id":"demotraders_txn_agent","to":"9999999999","type":"media",
       "media_url":"https://example.com/invoices/INV-1042.pdf"}'

Carousel with two cards

curl -X POST "https://www.fast2sms.com/dev/rcs" \
  -H "authorization: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"bot_id":"demotraders_promo_agent","to":"9999999999","type":"carousel",
       "cards":[
         {"title":"Steel storage jars","description":"Set of 3, now Rs 499",
          "media_url":"https://example.com/p/jars.jpg",
          "suggestion_type":"openUrl","suggestion_text":"Buy now","suggestion_url":"https://example.com/p/jars"},
         {"title":"Non-stick tawa","description":"28 cm, now Rs 799",
          "media_url":"https://example.com/p/tawa.jpg",
          "suggestion_type":"openUrl","suggestion_text":"Buy now","suggestion_url":"https://example.com/p/tawa"}]}'

Send carousels with POST and a JSON body. Plain, rich and media messages also work with GET, but POST is easier to read and keeps your text out of URLs.

Store location button

curl -X POST "https://www.fast2sms.com/dev/rcs" \
  -H "authorization: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"bot_id":"demotraders_txn_agent","to":"9999999999","type":"plain",
       "message":"Your parcel is ready for pickup at our store.",
       "suggestion_type":"viewLocation","suggestion_text":"Open map",
       "latitude":18.5204,"longitude":73.8567,"location_label":"Demo Traders, Pune"}'

Code examples

PHP

<?php
$msg = [
    "bot_id"          => "demotraders_txn_agent",
    "to"              => "9999999999",
    "type"            => "plain",
    "message"         => "Your order DT-1042 is out for delivery today.",
    "suggestion_type" => "openUrl",
    "suggestion_text" => "Track order",
    "suggestion_url"  => "https://example.com/track/DT-1042",
];
$ch = curl_init("https://www.fast2sms.com/dev/rcs");
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ["authorization: YOUR_API_KEY", "Content-Type: application/json"],
    CURLOPT_POSTFIELDS     => json_encode($msg),
    CURLOPT_TIMEOUT        => 30,
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);
echo ($data["return"] ?? false) === true ? $data["request_id"] : json_encode($data["errors"] ?? $data);

Python

import requests

msg = {
    "bot_id": "demotraders_txn_agent",
    "to": "9999999999",
    "type": "plain",
    "message": "Your order DT-1042 is out for delivery today.",
    "suggestion_type": "openUrl",
    "suggestion_text": "Track order",
    "suggestion_url": "https://example.com/track/DT-1042",
}
r = requests.post("https://www.fast2sms.com/dev/rcs",
                  headers={"authorization": "YOUR_API_KEY"}, json=msg, timeout=30)
data = r.json()
print(data["request_id"] if data.get("return") else data.get("errors"))

Node.js

const res = await fetch("https://www.fast2sms.com/dev/rcs", {
  method: "POST",
  headers: { authorization: process.env.FAST2SMS_API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    bot_id: "demotraders_txn_agent",
    to: "9999999999",
    type: "plain",
    message: "Your order DT-1042 is out for delivery today.",
    suggestion_type: "openUrl",
    suggestion_text: "Track order",
    suggestion_url: "https://example.com/track/DT-1042",
  }),
});
const data = await res.json();
console.log(data.return === true ? data.request_id : data.errors);

The API takes one number per request. To send to a list, loop over the numbers in your code, or upload the list on the Bulk RCS page. See send bulk RCS messages.

Charges, refunds and delivery

  • Price by type: plain, rich, media and carousel each have a rate. A plain message longer than 160 bytes is charged at the rich rate. See current rates on the RCS pricing page.
  • When you pay: the amount comes off your wallet when the message is sent.
  • Refunds: messages that fail, and numbers that turn out not to support RCS (shown as Non-RCS), are refunded automatically within 48 hours. A message that stays at Sent is not refunded.
  • No SMS fallback: if the phone does not support RCS, no SMS is sent in its place.
  • Expiry: a message not delivered within 6 hours expires and is marked failed, “Not Reachable”.
  • Promotional bots: at the time of writing, promotional RCS is limited to 4 messages per number per month and to sending hours of 7:00 AM to 10:00 PM. Transactional bots are for informative messages only.

Details are in RCS delivery report, statuses and refunds and RCS promotional vs transactional rules.

Get delivery status and replies

Create an RCS webhook from Webhook, RCS to get sent, delivered, read and failed updates and incoming replies on your URL. Choose your Bot ID as the identity to limit it to one bot. Webhooks fire for messages sent by API. See webhooks in Fast2SMS.

Common problems and fixes

“Invalid or inactive RCS bot”

The Bot ID is wrong, belongs to another account, or the bot is Inactive or not approved. Copy it again from RCS Manager, Bots, and use an Active bot.

“Mobile Number format is invalid.”

Send one 10-digit Indian mobile number starting with 6 to 9. Lists are not accepted in to.

Validation errors for message, cards or buttons

Check the limits: message up to 3,000 characters, title up to 100, button text up to 25, a carousel needs 2 to 10 cards with a title and description each, and openUrl needs suggestion_url.

Insufficient wallet balance

Recharge and send again.

Status is Non-RCS

The phone or network does not support RCS. The charge is refunded. See which phones support RCS messages.

Frequently asked questions

Where do I find my RCS Bot ID?

In RCS Manager, Bots. Each bot has a Bot ID with a copy button.

Do I need a DLT template for RCS?

No. RCS messages are sent from your approved bot without DLT templates. See is DLT needed for WhatsApp, RCS and voice.

Can I send RCS to many numbers in one API call?

No. The API takes one number per call. Loop in your code, or use Bulk RCS in the panel for a list.

Can I add more than one button?

The API takes one button per message or carousel card. For up to 4 buttons, use the Bulk RCS page.

What happens if the customer’s phone has no RCS?

The message is marked Non-RCS and the charge is refunded. No SMS is sent automatically.

Is RCS delivered on iPhone?

RCS support depends on the phone, its messaging app and the network. Check which phones support RCS.