Send your first RCS message

Send an appointment card to your own test phone, open its link and return a suggested reply. This walkthrough uses the RCS Channels API, with an access key, workspace ID and installed RCS channel.

Download the Node.js, Python and cURL examples.

1. Prepare your sender

In Bird, follow Create an RCS agent and install its channel. Provide the business name, public website, agent description and brand images customers will recognize.

Open the agent's Test Agent tab, add your own phone number and accept the tester invitation on that phone. Test the agent before completing Launch Countries for customer traffic. The launch questionnaire records the business contact, use case, opt-in and opt-out journey, experience evidence, and target countries and carriers. Follow the testing and launch procedure.

Object	Ready for this walkthrough
Agent	Brand details saved and your tester invitation accepted.
Channel	Installed for that agent; its ID belongs to the workspace used below.
Access key	Authorized to send and read messages for that workspace and channel.
Recipient	Your test phone number in E.164 format, including + and country code.
Application	An HTTPS appointment page you control; signing in returns to the appointment.

Create an access key and export these values in your terminal. Replace every placeholder. Keep the key on your server. Install jq and cURL; the language options also use Node.js 22+ or Python 3.

Ejemplo de código

export BIRD_ACCESS_KEY='replace-with-your-access-key'
export BIRD_WORKSPACE_ID='replace-with-your-workspace-id'
export RCS_CHANNEL_ID='replace-with-your-rcs-channel-id'
export RCS_RECIPIENT='replace-with-your-own-e164-number'
export APPOINTMENT_URL='https://your-app.example/appointments/demo'

2. Create one rich card

The Channels API represents a single RCS card as a carousel body containing one item. Create rcs-message.json with this command. Replace the sample appointment details before sending.

Ejemplo de código

jq -n --arg to "$RCS_RECIPIENT" --arg url "$APPOINTMENT_URL" '{
  receiver: {contacts: [{identifierKey: "phonenumber", identifierValue: $to}]},
  reference: "appointment-demo-001",
  body: {
    type: "carousel",
    carousel: {
      items: [{
        title: "Your studio visit",
        description: "Tuesday, 10:00. Riverside Studio.",
        actions: [
          {type: "link", link: {text: "View appointment", url: $url}},
          {type: "postback", postback: {
            text: "Change my time", payload: "appointment-demo/change"
          }}
        ]
      }]
    }
  }
}' > rcs-message.json

The URL opens your application. The postback returns a stable choice for your rescheduling workflow. The reference helps correlate this send with your records; it is not an idempotency key. The rich-message guide adds media, multiple cards and published templates.

3. Send to your test device

Choose one example below. Each reads the same JSON file and sends one message to POST /workspaces/{workspaceId}/channels/{channelId}/messages. These are standard HTTP examples, so no Bird SDK installation is needed.

Save the Node.js example as send-rcs.mjs and run node send-rcs.mjs, or save the Python example as send_rcs.py and run python3 send_rcs.py. Run the cURL option directly in the same terminal.

A 202 response accepts processing. Keep the returned id with your appointment record. If the request fails, examine the HTTP response; cURL keeps it in rcs-response.json. If the response is lost, reconcile the existing attempt in channel logs by recipient and time before sending again. Reusing reference does not make another POST safe to retry.

4. Inspect the result

After the card arrives, tap View appointment and confirm the correct page opens. Then tap Change my time. Read the message and its interactions using the ID saved above:

delivered is the message's reported delivery result. read and clicked are separate interactions. A postback click carries the selected value in metadata.button.payload; the receiving-message reference also shows its inbound text message. Use the reply processing recipe to turn the choice into an application task once.

Check the booking result in your application separately. For customer rollout, finish the agent's launch workflow and test your RCS-to-SMS navigator with an unsupported recipient as a second case.

Next steps

import { readFile, writeFile } from "node:fs/promises";

const { BIRD_ACCESS_KEY, BIRD_WORKSPACE_ID, RCS_CHANNEL_ID } = process.env;
if (!BIRD_ACCESS_KEY || !BIRD_WORKSPACE_ID || !RCS_CHANNEL_ID) {
  throw new Error("Set BIRD_ACCESS_KEY, BIRD_WORKSPACE_ID and RCS_CHANNEL_ID");
}
const url = `https://api.bird.com/workspaces/${BIRD_WORKSPACE_ID}/channels/${RCS_CHANNEL_ID}/messages`;
const response = await fetch(url, {
  method: "POST",
  headers: {
    Authorization: `AccessKey ${BIRD_ACCESS_KEY}`,
    "Content-Type": "application/json",
  },
  body: await readFile("rcs-message.json", "utf8"),
});
const text = await response.text();
if (response.status !== 202) throw new Error(`HTTP ${response.status}: ${text}`);
const message = JSON.parse(text);
if (!message.id) throw new Error("Accepted response has no message ID; reconcile this attempt");
await writeFile("rcs-result.json", JSON.stringify(message, null, 2));
console.log({ id: message.id, status: message.status });

import json
import os
from pathlib import Path
from urllib.request import Request, urlopen

workspace = os.environ["BIRD_WORKSPACE_ID"]
channel = os.environ["RCS_CHANNEL_ID"]
request = Request(
    f"https://api.bird.com/workspaces/{workspace}/channels/{channel}/messages",
    data=Path("rcs-message.json").read_bytes(),
    headers={
        "Authorization": f"AccessKey {os.environ['BIRD_ACCESS_KEY']}",
        "Content-Type": "application/json",
    },
    method="POST",
)
with urlopen(request, timeout=30) as response:
    if response.status != 202:
        raise RuntimeError(f"Unexpected HTTP status: {response.status}")
    message = json.load(response)
if not message.get("id"):
    raise RuntimeError("Accepted response has no message ID; reconcile this attempt")
Path("rcs-result.json").write_text(json.dumps(message, indent=2))
print({"id": message["id"], "status": message.get("status")})

status=$(curl --silent --show-error --output rcs-response.json --write-out '%{http_code}' \
  --request POST \
  "https://api.bird.com/workspaces/$BIRD_WORKSPACE_ID/channels/$RCS_CHANNEL_ID/messages" \
  --header "Authorization: AccessKey $BIRD_ACCESS_KEY" \
  --header 'Content-Type: application/json' \
  --data-binary @rcs-message.json) &&
  test "$status" = '202' &&
  jq -e '.id' rcs-response.json &&
  cp rcs-response.json rcs-result.json

RCS_MESSAGE_ID=$(jq -er '.id' rcs-result.json)
curl --fail-with-body --silent --show-error \
  "https://api.bird.com/workspaces/$BIRD_WORKSPACE_ID/channels/$RCS_CHANNEL_ID/messages/$RCS_MESSAGE_ID" \
  --header "Authorization: AccessKey $BIRD_ACCESS_KEY" > rcs-status.json
jq '{id, status, reason, failure}' rcs-status.json

curl --fail-with-body --silent --show-error \
  "https://api.bird.com/workspaces/$BIRD_WORKSPACE_ID/channels/$RCS_CHANNEL_ID/messages/$RCS_MESSAGE_ID/interactions" \
  --header "Authorization: AccessKey $BIRD_ACCESS_KEY" > rcs-interactions.json
jq '.results[] | {id, type, messageId, details, metadata}' rcs-interactions.json

Recursos relacionados

Continúa con la documentación, guías y ejemplos sobre este tema. Los recursos están en inglés.

Comprender el conceptoWhat Is RCS for Business?Explorar la funcionalidadRCS

Obtener un resumen de implementación