RCS API for
Developers
Send RCS messages from your website, app or CRM with one POST request: plain text, rich cards, media or carousels from your verified brand. Get delivered, read and reply events on your webhook. ₹0.35 per message, the same as the panel.
- Same API key as SMS
- 4 message types, 1 endpoint
- Read receipts on webhook
- Failed numbers refunded
What is an RCS API?
An RCS API is a web address your software calls to send an RCS business message without anyone opening a panel. Your server sends the customer's number and the message to Fast2SMS over HTTPS. Fast2SMS checks your bot, charges ₹0.35 from your wallet and delivers the message to the customer's Android Messages app, where it shows your brand name, logo and verified tick.
Developers use it for messages that depend on something happening in their own system: an order ships, a payment fails, an appointment is booked, a policy is about to lapse. Each call is one number, so each customer can get their own name, amount, link and button. The answer comes back at once with a request_id, and the delivery, read and failed updates follow on your webhook.
If you only need to send the same offer to a list, you do not need code: the Bulk RCS page in the panel takes a CSV file. Both use the same bots, the same wallet and the same price.
RCS API integration in five steps
Most teams send their first test message within an hour of their bot being approved.
- 1
Get an approved bot
Register your brand in RCS Manager. Our team prepares the application with you and follows up with the operator for free. Only approved, active bots can send.
- 2
Copy your API key
Open API Key under UTILITY in the panel. The same key works for SMS, WhatsApp and RCS. Keep it on your server, never in a browser or app.
- 3
Copy the Bot ID
Open RCS Manager, then Bots. Each bot shows its Bot ID with a copy button, its category (promotional, transactional or OTP) and its status.
- 4
Send a test message
POST to /dev/rcs with your Bot ID, your own mobile number and type plain. Save the request_id that comes back; it starts with R.
- 5
Add your webhook
Add a webhook URL for RCS in the panel and choose the events. Sent, delivered, read, failed and replies then reach your server with your udf values.
Endpoint and fields
POST https://www.fast2sms.com/dev/rcs with the header authorization: YOUR_API_KEY and a JSON body.
| Field | Needed for | Rule |
|---|---|---|
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 with 6 to 9. +91 or 91 in front is fine. |
type | All, unless template_id | plain, rich, media or carousel. |
message | plain, rich | The text, up to 3,000 characters. |
title | rich (optional) | Card title, up to 100 characters. |
media_url | media; rich (optional) | Public https link to the image, video, audio or PDF. |
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 | viewLocation | Map point for the button. location_label up to 100 characters. |
cards | carousel | 2 to 10 cards. Each has title (up to 255), description (up to 2,000), optional media_url and the same button fields. |
template_id | Optional | Resend a message you sent before (Previous Template) to a new number. The bot must match. |
udf1, udf2, udf3 | Optional | Your own values, such as an order ID. They come back in the webhook. |
Every field with examples: RCS API guide · API documentation
Send each RCS message type
Replace YOUR_API_KEY, the bot_id and the number. Sample values only.
curl -X POST "https://www.fast2sms.com/dev/rcs" \
-H "authorization: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"bot_id":"demostore_txn","to":"9999999999",
"type":"plain",
"message":"Your order DS-1042 is out for delivery today.",
"suggestion_type":"openUrl",
"suggestion_text":"Track order",
"suggestion_url":"https://example.com/t/DS-1042",
"udf1":"DS-1042"}'
curl -X POST "https://www.fast2sms.com/dev/rcs" \
-H "authorization: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"bot_id":"demostore_promo","to":"9999999999",
"type":"rich",
"title":"Festive Sale at Demo Store",
"message":"Flat 20% off on kitchenware till 25 Nov.",
"media_url":"https://example.com/sale.jpg",
"suggestion_type":"dial",
"suggestion_text":"Call store",
"suggestion_phone":"9999999999"}'
curl -X POST "https://www.fast2sms.com/dev/rcs" \
-H "authorization: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"bot_id":"demostore_promo","to":"9999999999",
"type":"carousel",
"cards":[
{"title":"Steel jars","description":"Set of 3, Rs 499",
"media_url":"https://example.com/jars.jpg",
"suggestion_type":"openUrl","suggestion_text":"Buy now",
"suggestion_url":"https://example.com/p/jars"},
{"title":"Non-stick tawa","description":"28 cm, Rs 799",
"media_url":"https://example.com/tawa.jpg",
"suggestion_type":"openUrl","suggestion_text":"Buy now",
"suggestion_url":"https://example.com/p/tawa"}]}'
# an invoice as a PDF
-d '{"bot_id":"demostore_txn","to":"9999999999",
"type":"media",
"media_url":"https://example.com/inv/INV-1042.pdf"}'
# a pickup message that opens the map
-d '{"bot_id":"demostore_txn","to":"9999999999",
"type":"plain",
"message":"Your parcel is ready for pickup.",
"suggestion_type":"viewLocation",
"suggestion_text":"Open map",
"latitude":18.5204,"longitude":73.8567,
"location_label":"Demo Store, Pune"}'
# resend an earlier message to a new number
-d '{"bot_id":"demostore_promo","to":"9999999999",
"template_id":48213}'
Send RCS from PHP, Python and Node.js
The same plain message in three languages. Read the API key from an environment variable, not from your code.
$msg = [
"bot_id" => "demostore_txn",
"to" => "9999999999",
"type" => "plain",
"message" => "Your order DS-1042 has shipped.",
];
$ch = curl_init("https://www.fast2sms.com/dev/rcs");
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"authorization: " . getenv("FAST2SMS_API_KEY"),
"Content-Type: application/json"],
CURLOPT_POSTFIELDS => json_encode($msg),
CURLOPT_TIMEOUT => 30,
]);
$res = json_decode(curl_exec($ch), true);
echo $res["request_id"] ?? json_encode($res["errors"]);
import os, requests
msg = {
"bot_id": "demostore_txn",
"to": "9999999999",
"type": "plain",
"message": "Your order DS-1042 has shipped.",
}
r = requests.post(
"https://www.fast2sms.com/dev/rcs",
headers={"authorization":
os.environ["FAST2SMS_API_KEY"]},
json=msg, timeout=30)
data = r.json()
print(data["request_id"] if data.get("return")
else data.get("errors"))
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: "demostore_txn",
to: "9999999999",
type: "plain",
message: "Your order DS-1042 has shipped.",
}),
});
const data = await res.json();
console.log(data.return ? data.request_id : data.errors);
Success, errors and what to do
A good request returns at once. A bad one returns HTTP 400 with the field names in errors_keys, so your code can tell what to fix.
{
"return": true,
"request_id": "R4Yhz6HA8kATqft",
"message": ["RCS Message will be sent."]
}
{
"return": false,
"errors_keys": ["bot_id"],
"errors": {
"bot_id": ["Invalid or inactive RCS bot"]
}
}
| Error message | Field | Fix |
|---|---|---|
| Invalid or inactive RCS bot | bot_id | The Bot ID is wrong, belongs to another account, or the bot is not approved yet. Copy it again from RCS Manager. |
| Mobile Number format is invalid. | to | Send one Indian mobile number per call, 10 digits starting with 6 to 9. Arrays of numbers are not accepted. |
| The type field is required. | type | Add type, or send a template_id to reuse an earlier message. |
| The cards must have at least 2 items. | cards | A carousel needs 2 to 10 cards, each with a title and description. |
| Previous template not found. | template_id | The ID is not one of your earlier RCS messages. |
| Bot does not match this previous template. | bot_id | Send the template from the same bot that sent it first. |
| Insufficient wallet balance | wallet | Recharge the wallet. Every message is charged when it is accepted and refunded if it fails. |
More failure reasons and fixes: RCS errors and failed reasons.
Delivery, read and replies, pushed to your server
Add an RCS webhook in the panel, pick the events and the format (JSON, form or XML), and choose which fields to send. Fast2SMS then calls your URL for every status change. Match updates to your records with request_id or with the udf1 to udf3 values you sent.
- Events: sent, delivered, read, failed
- Customer replies as incoming messages, with media links
- Failure reason on failed messages
- Your udf1, udf2 and udf3 returned on every event
{
"request_id": "R4Yhz6HA8kATqft",
"mobile": "9999999999",
"status": "read",
"description": "Read",
"failure_reason": "",
"timestamp": 1763532120,
"webhook_type": "status_update",
"udf1": "DS-1042"
}
{
"webhook_type": "incoming_message",
"from": "9999999999",
"message_type": "text",
"body": "Paid already",
"status": "received"
}
RCS API vs Bulk RCS panel
Same bots, same wallet, same price. Pick by the job.
| RCS API | Bulk RCS panel | |
|---|---|---|
| Best for | Order, booking, payment and OTP messages from your software | Campaigns to a list you already have |
| Numbers per request | One number per call | Lakhs, from a list, Address Book or CSV |
| Personal content | Yes, a different message for each customer | Same message to every number |
| Buttons | One per message, one per carousel card | Up to 4 per message or per card |
| Scheduling | Your software decides when to call | Schedule in the panel |
| Status updates | Webhook to your server, plus Delivery Report | Delivery Report, Excel download, webhook |
| Price | ₹0.35 per message | ₹0.35 per message |
Many businesses use both: the API for order and payment updates, the panel for offers.
No API fee. Pay per message.
Calls to the RCS API are free. Each message that is accepted costs ₹0.35, whether it is plain text, a rich card, media or a carousel, and the amount comes back to your wallet if the number cannot receive RCS. Replies from customers are free. There is no setup fee, no monthly fee and no minimum volume.
- ₹0.35 per messageSame for every type, panel or API.
- Recharge from ₹100One wallet for RCS, SMS and WhatsApp.
- Webhooks includedStatus updates and replies at no charge.
- Automatic refundsFailed numbers back in your wallet within 48 hours.
Your data is encrypted and stays yours
Your customers' numbers and messages are business data. We treat them that way: encrypted on the wire and in the database, visible only to the people you allow, on infrastructure that is audited every year.
See our certificates- Encrypted in transitEvery panel page and API call runs over HTTPS (TLS 1.2+). Your API key is sent in a header, never in a page.
- Encrypted at restSensitive fields such as API keys, templates and reports are encrypted in our database, with keys kept outside the application.
- Access you controlPer-user API keys you can rotate any time, IP allow-listing, OTP on login, and agents who see only what you assign.
- Audited and certifiedISO 27001 and SOC 2 Type 2 certified, VAPT tested by an external team, MSME registered.
RCS API: questions answered
What is an RCS API?
An RCS API lets your website, app or CRM send RCS business messages by itself, without anyone opening a panel. Your server makes an HTTPS request with the number and the message, and the RCS message arrives in the customer's Android Messages app from your verified brand. Status updates come back to your server on a webhook.
What is the Fast2SMS RCS API endpoint?
POST https://www.fast2sms.com/dev/rcs with your API key in the authorization header and a JSON body. Plain, rich and media messages also work as a GET request, but POST keeps your text out of URLs and is required for carousels.
How much does the RCS API cost?
There is no charge for the API itself. Each message sent through the API costs the same ₹0.35 as a message sent from the panel, for every type. Numbers that cannot receive RCS are refunded within 48 hours. There is no setup fee and no monthly fee.
Which message types can I send with the RCS API?
Four: plain text up to 3,000 characters, rich cards with an optional title, text, media and a button, media messages with an image, video, audio or PDF, and carousels of 2 to 10 cards, each with its own media and button.
Where do I find my Bot ID?
In RCS Manager, under Bots. Each bot shows its Bot ID with a copy button, its category and whether it is active. Send that value as bot_id. Older numeric bot IDs still work.
Can I send to many numbers in one API call?
No. Each call sends to one number, so every customer can get their own text, order number or link. To send one message to a whole list, use the Bulk RCS page in the panel, or loop over your list and call the API for each number.
How many buttons can an API message have?
One per message, and one per card in a carousel. The button can open a URL, dial a number or show a location on the map. Button text can be up to 25 characters. The Bulk RCS page in the panel allows up to four buttons.
Does the RCS API return a message ID?
Yes. A successful call returns "return": true and a request_id that starts with R. Use it to find the message in Delivery Report under RCS and to match webhook updates to your records.
How do I get delivery and read reports from the API?
Add an RCS webhook URL in the panel. Fast2SMS posts each status to it: sent, delivered, read and failed, plus customer replies as incoming messages. Each event carries the request_id, mobile number, status, time, failure reason and your udf1 to udf3 values.
Can customers reply to messages sent by API?
Yes. Replies arrive in the RCS Live Chat inbox in the panel and, if you set a webhook, at your server as an incoming message with the sender's number, message type, text and any media link.
Can I send OTPs with the RCS API?
Yes, from an OTP bot. Your own app creates and checks the code. RCS reaches only Android phones with RCS on, so for logins that must work on every phone, Smart OTP is the safer choice because it can use WhatsApp or SMS.
Is DLT needed to use the RCS API?
No. RCS does not use DLT headers or templates. Your brand bot is verified and approved for RCS instead.
What happens if the number cannot receive RCS?
The webhook reports it as failed and the ₹0.35 is refunded to your wallet automatically within 48 hours. iPhones cannot receive RCS business messages through Fast2SMS at the time of writing.
Does the RCS API fall back to SMS automatically?
Not today. Automatic SMS fallback is coming with Campaigns. Until then, when your webhook reports a failed RCS, your software can send the same customer an SMS through the Fast2SMS SMS API with the same API key.
Can I personalise each RCS message?
Yes. Because each API call is one number, you can put the customer's name, order number, amount or link into the message and the button. That is the main reason to use the API instead of a bulk campaign.
Can I reuse a message I sent before?
Yes. Send template_id with the ID of an earlier RCS message instead of the message fields, together with bot_id and to. The message must have been sent from the same bot.
Is there an RCS API sample I can download?
Yes. In the panel, open Account Setting, then API Excel, pick RCS and download. The file has ready request URLs for each of your approved bots with notes for every scenario.
Which languages can I use with the RCS API?
Any language that can make an HTTPS request: PHP, Python, Node.js, Java, C#, Go and others, or a no-code tool that supports webhooks and HTTP calls. This page has ready examples for PHP, Python and Node.js.
Is the RCS API secure?
Every call uses HTTPS and is tied to your API key and your own approved bots. Keep the key on your server, regenerate it in the panel if it leaks, and never place it in a web page or mobile app. Fast2SMS is ISO 27001 and SOC 2 Type 2 certified.
How do I test the RCS API before going live?
Send a plain message to your own Android phone from an approved bot and check the request_id in Delivery Report. Then test a rich card and a carousel with your real images, and point the webhook at a test URL before switching it to production.
Why choose Fast2SMS as an RCS API provider in India?
One endpoint for all four message types, the same API key as SMS and WhatsApp, webhooks with read receipts and replies, no API or monthly fee, ₹0.35 per message, automatic refunds for failed numbers, free brand onboarding, and support on chat, phone and email.
Same API key as SMS and WhatsApp. ₹0.35 per message, no API or monthly fee.