Messaging

Send RCS messages

RCS is the rich messaging channel built into Android messaging apps: your verified brand name and logo, images, cards, carousels and buttons, with automatic SMS fallback.

Before you start

RCS messages come from a verified sender: your brand name, logo, colour and description, approved before first use. Request one from the dashboard. Its ID is the sender in every request.

POST/rcs/2/messages

Text with suggestions

The simplest RCS message is text with suggestion chips under it. A tapped chip comes back to your inbound webhook with its postbackData.

send-rcs.ts

await pulsr("POST", "/rcs/2/messages", {  messages: [    {      sender: "YourBrand",      destinations: [{ to: "33639981234" }],      content: {        type: "TEXT",        text: "Your table for 2 is booked for Friday at 20:00.",        suggestions: [          { type: "REPLY", text: "Confirm", postbackData: "booking_confirm" },          { type: "REPLY", text: "Cancel", postbackData: "booking_cancel" },          {            type: "DIAL_PHONE",            text: "Call us",            postbackData: "call",            phoneNumber: "33199004242",          },        ],      },    },  ],});

Response · 200 OK

{  "bulkId": "a28dd97c-2222-4fcf-99f1-0b557ed381da",  "messages": [    {      "messageId": "a28dd97c-1ffb-4fcf-99f1-0b557ed381da",      "status": {        "groupId": 1,        "groupName": "PENDING",        "id": 26,        "name": "PENDING_ACCEPTED",        "description": "Message sent to next instance"      },      "destination": "33639981234"    }  ]}

Rich cards

A card combines an image or video, a title, a description and up to four buttons. Set orientation to VERTICAL or HORIZONTAL, and media.height to SHORT, MEDIUM or TALL.

send-card.ts

await pulsr("POST", "/rcs/2/messages", {  messages: [    {      sender: "YourBrand",      destinations: [{ to: "33639981234" }],      content: {        type: "CARD",        orientation: "VERTICAL",        alignment: "LEFT",        content: {          title: "New in: the spring drop",          description: "Twelve new pieces, shipped free this week.",          media: {            file: { url: "https://yourapp.com/spring.jpg" },            height: "MEDIUM",          },          suggestions: [            {              type: "OPEN_URL",              text: "Shop now",              postbackData: "shop",              url: "https://yourapp.com/new",            },            { type: "REPLY", text: "Stop", postbackData: "opt_out" },          ],        },      },    },  ],});

Carousels

A carousel is a row of cards people swipe through, each with its own buttons. cardWidth is SMALL or MEDIUM.

send-carousel.ts

const products = [  { id: 1, name: "Linen shirt" },  { id: 2, name: "Canvas tote" },  { id: 3, name: "Straw hat" },];const shop = "https://yourapp.com/p";await pulsr("POST", "/rcs/2/messages", {  messages: [    {      sender: "YourBrand",      destinations: [{ to: "33639981234" }],      content: {        type: "CAROUSEL",        cardWidth: "MEDIUM",        contents: products.map((p) => ({          title: p.name,          media: { file: { url: `${shop}/${p.id}.jpg` }, height: "MEDIUM" },          suggestions: [            {              type: "OPEN_URL",              text: "View",              postbackData: `view_${p.id}`,              url: `${shop}/${p.id}`,            },          ],        })),      },    },  ],});

Suggestion types

Every suggestion has a type, a text shown on the button and a postbackData returned when it is tapped.

type	Extra fields	What it does
`REPLY`	none	Sends the text back as the person’s reply.
`OPEN_URL`	`url`, `application` (`BROWSER` or `WEBVIEW`)	Opens a link.
`DIAL_PHONE`	`phoneNumber`	Starts a call to that number.
`SHOW_LOCATION`	`latitude`, `longitude`, `label`	Opens a map at that place.
`REQUEST_LOCATION`	none	Asks the person to share their location.
`CREATE_CALENDAR_EVENT`	`startTime`, `endTime`, `title`, `description`	Adds an event to their calendar.

Not every phone supports RCS. Add options.smsFailover and the message goes out as an SMS when RCS is unavailable or not delivered within validityPeriod. Keep the fallback text self-contained, since buttons and images will not be there.

send-rcs.ts

await pulsr("POST", "/rcs/2/messages", {  messages: [    {      sender: "YourBrand",      destinations: [{ to: "33639981234" }],      content: { type: "TEXT", text: "Your parcel arrives today, 14:00–16:00." },      options: {        validityPeriod: { amount: 30, timeUnit: "MINUTES" },        // Sent as an SMS if RCS is unavailable or not delivered in time        smsFailover: {          sender: "YourBrand",          text: "Your parcel arrives today, 14:00–16:00.",        },      },      webhooks: {        delivery: { url: "https://yourapp.com/hooks/dlr?token=…" },        seen: { url: "https://yourapp.com/hooks/seen?token=…" },      },    },  ],});

Delivery and seen reports

webhooks.delivery.url receives delivery reports in the same format as SMS, with interactionType and conversation added. webhooks.seen.url receives an event when the person opens the message.

Replies and button taps

Set the inbound webhook URL on your RCS sender in the dashboard. Each event says who wrote (sender), and message.type tells you what it is: TEXT, FILE, LOCATION, or SUGGESTION for a tapped button.

POST to your webhook

{  "results": [    {      "sender": "33639981234",      "to": "YourBrand",      "integrationType": "RCS",      "receivedAt": "2026-10-19T14:22:30.000+0000",      "interactionType": "BASIC_MESSAGE",      "rcsCount": 1,      "messageId": "msg-abc123",      "pairedMessageId": "a28dd97c-1ffb-4fcf-99f1-0b557ed381da",      "message": {        "type": "SUGGESTION",        "text": "Confirm",        "postbackData": "booking_confirm"      },      "price": { "trafficType": "BASIC", "pricePerMessage": 0.005, "currency": "EUR" },      "conversation": { "canInitiate": false, "id": "conv-xyz789" }    }  ],  "messageCount": 1,  "pendingMessageCount": 0}

app/webhooks/rcs/route.ts

export async function POST(req: Request) {  // Check the token first, see the Webhooks guide  const { results } = await req.json();  for (const event of results) {    const user = event.sender; // the person's phone number    const msg = event.message;    switch (msg.type) {      case "SUGGESTION":        // A button was tapped: route on the postbackData you set        if (msg.postbackData === "booking_confirm") await bookings.confirm(user);        if (msg.postbackData === "booking_cancel") await bookings.cancel(user);        break;      case "TEXT":        await inbox.add(user, msg.text);        break;      case "LOCATION":        await deliveries.setLocation(user, msg.latitude, msg.longitude);        break;      case "FILE":        await inbox.addFile(user, msg.url, msg.contentType);        break;    }  }  return new Response(null, { status: 200 });}

Messaging

Send RCS messages

RCS is the rich messaging channel built into Android messaging apps: your verified brand name and logo, images, cards, carousels and buttons, with automatic SMS fallback.

Before you start

RCS messages come from a verified sender: your brand name, logo, colour and description, approved before first use. Request one from the dashboard. Its ID is the sender in every request.

POST/rcs/2/messages

Text with suggestions

The simplest RCS message is text with suggestion chips under it. A tapped chip comes back to your inbound webhook with its postbackData.

send-rcs.ts

await pulsr("POST", "/rcs/2/messages", {  messages: [    {      sender: "YourBrand",      destinations: [{ to: "33639981234" }],      content: {        type: "TEXT",        text: "Your table for 2 is booked for Friday at 20:00.",        suggestions: [          { type: "REPLY", text: "Confirm", postbackData: "booking_confirm" },          { type: "REPLY", text: "Cancel", postbackData: "booking_cancel" },          {            type: "DIAL_PHONE",            text: "Call us",            postbackData: "call",            phoneNumber: "33199004242",          },        ],      },    },  ],});

Response · 200 OK

{  "bulkId": "a28dd97c-2222-4fcf-99f1-0b557ed381da",  "messages": [    {      "messageId": "a28dd97c-1ffb-4fcf-99f1-0b557ed381da",      "status": {        "groupId": 1,        "groupName": "PENDING",        "id": 26,        "name": "PENDING_ACCEPTED",        "description": "Message sent to next instance"      },      "destination": "33639981234"    }  ]}

Rich cards

A card combines an image or video, a title, a description and up to four buttons. Set orientation to VERTICAL or HORIZONTAL, and media.height to SHORT, MEDIUM or TALL.

send-card.ts

await pulsr("POST", "/rcs/2/messages", {  messages: [    {      sender: "YourBrand",      destinations: [{ to: "33639981234" }],      content: {        type: "CARD",        orientation: "VERTICAL",        alignment: "LEFT",        content: {          title: "New in: the spring drop",          description: "Twelve new pieces, shipped free this week.",          media: {            file: { url: "https://yourapp.com/spring.jpg" },            height: "MEDIUM",          },          suggestions: [            {              type: "OPEN_URL",              text: "Shop now",              postbackData: "shop",              url: "https://yourapp.com/new",            },            { type: "REPLY", text: "Stop", postbackData: "opt_out" },          ],        },      },    },  ],});

Carousels

A carousel is a row of cards people swipe through, each with its own buttons. cardWidth is SMALL or MEDIUM.

send-carousel.ts

const products = [  { id: 1, name: "Linen shirt" },  { id: 2, name: "Canvas tote" },  { id: 3, name: "Straw hat" },];const shop = "https://yourapp.com/p";await pulsr("POST", "/rcs/2/messages", {  messages: [    {      sender: "YourBrand",      destinations: [{ to: "33639981234" }],      content: {        type: "CAROUSEL",        cardWidth: "MEDIUM",        contents: products.map((p) => ({          title: p.name,          media: { file: { url: `${shop}/${p.id}.jpg` }, height: "MEDIUM" },          suggestions: [            {              type: "OPEN_URL",              text: "View",              postbackData: `view_${p.id}`,              url: `${shop}/${p.id}`,            },          ],        })),      },    },  ],});

Suggestion types

Every suggestion has a type, a text shown on the button and a postbackData returned when it is tapped.

type	Extra fields	What it does
`REPLY`	none	Sends the text back as the person’s reply.
`OPEN_URL`	`url`, `application` (`BROWSER` or `WEBVIEW`)	Opens a link.
`DIAL_PHONE`	`phoneNumber`	Starts a call to that number.
`SHOW_LOCATION`	`latitude`, `longitude`, `label`	Opens a map at that place.
`REQUEST_LOCATION`	none	Asks the person to share their location.
`CREATE_CALENDAR_EVENT`	`startTime`, `endTime`, `title`, `description`	Adds an event to their calendar.

SMS fallback

send-rcs.ts

await pulsr("POST", "/rcs/2/messages", {  messages: [    {      sender: "YourBrand",      destinations: [{ to: "33639981234" }],      content: { type: "TEXT", text: "Your parcel arrives today, 14:00–16:00." },      options: {        validityPeriod: { amount: 30, timeUnit: "MINUTES" },        // Sent as an SMS if RCS is unavailable or not delivered in time        smsFailover: {          sender: "YourBrand",          text: "Your parcel arrives today, 14:00–16:00.",        },      },      webhooks: {        delivery: { url: "https://yourapp.com/hooks/dlr?token=…" },        seen: { url: "https://yourapp.com/hooks/seen?token=…" },      },    },  ],});

Delivery and seen reports

webhooks.delivery.url receives delivery reports in the same format as SMS, with interactionType and conversation added. webhooks.seen.url receives an event when the person opens the message.

Replies and button taps

POST to your webhook

{  "results": [    {      "sender": "33639981234",      "to": "YourBrand",      "integrationType": "RCS",      "receivedAt": "2026-10-19T14:22:30.000+0000",      "interactionType": "BASIC_MESSAGE",      "rcsCount": 1,      "messageId": "msg-abc123",      "pairedMessageId": "a28dd97c-1ffb-4fcf-99f1-0b557ed381da",      "message": {        "type": "SUGGESTION",        "text": "Confirm",        "postbackData": "booking_confirm"      },      "price": { "trafficType": "BASIC", "pricePerMessage": 0.005, "currency": "EUR" },      "conversation": { "canInitiate": false, "id": "conv-xyz789" }    }  ],  "messageCount": 1,  "pendingMessageCount": 0}

app/webhooks/rcs/route.ts

export async function POST(req: Request) {  // Check the token first, see the Webhooks guide  const { results } = await req.json();  for (const event of results) {    const user = event.sender; // the person's phone number    const msg = event.message;    switch (msg.type) {      case "SUGGESTION":        // A button was tapped: route on the postbackData you set        if (msg.postbackData === "booking_confirm") await bookings.confirm(user);        if (msg.postbackData === "booking_cancel") await bookings.cancel(user);        break;      case "TEXT":        await inbox.add(user, msg.text);        break;      case "LOCATION":        await deliveries.setLocation(user, msg.latitude, msg.longitude);        break;      case "FILE":        await inbox.addFile(user, msg.url, msg.contentType);        break;    }  }  return new Response(null, { status: 200 });}