RCS

RCS is rich messaging for phones: Android users get it in Google Messages, and iPhone users in Messages on iOS 18 and later. Your messages arrive under a checked business identity with your name, logo, banner and a verified badge, not from an anonymous number. They can carry cards, carousels and buttons, and you see when they are read. In Pozy you register an RCS agent, then send with POST /v1/rcs/messages. Replies land in the Inbox with the platform id rcs.

#What you can do

#Connect

Carriers approve two things before an agent can send:

• Brand: the company that is legally responsible for what is sent, with its registered name, tax id, address and a contact person. Several agents can share one brand.
• Agent: the sender identity on the phone, with a display name, description, logo, banner, colour and contact buttons. An agent sits in one profile, which gets an inbox account for it.

The workspace needs a plan with the inbox, usage-based billing and a saved card. Pozy reviews every request first; carriers see nothing and you pay nothing before that review is done.

{
  "profileId": "66a1f0c2a4b9d3e8f1a2b3c4",
  "displayName": "Acme Deliveries",
  "useCase": "TRANSACTIONAL",
  "brand": {
    "displayName": "Acme",
    "legalName": "Acme Logistics LLC",
    "legalEntityType": "LIMITED_LIABILITY_COMPANY",
    "organizationType": "PRIVATE_PROFIT",
    "websiteUrl": "https://acme.example.com",
    "taxId": "12-3456789",
    "address": { "line1": "100 Market St", "city": "San Francisco", "state": "CA", "postalCode": "94105", "country": "US" },
    "contact": { "firstName": "Dana", "lastName": "Lee", "email": "dana@acme.example.com", "phone": "+14155550100" }
  },
  "profile": {
    "description": "Delivery updates from Acme",
    "logoUrl": "https://pozy.ai/media/acme-logo.png",
    "heroUrl": "https://pozy.ai/media/acme-banner.png",
    "brandColor": "#1A3D8F",
    "privacyPolicyUrl": "https://acme.example.com/privacy",
    "termsUrl": "https://acme.example.com/terms",
    "phone": { "number": "+14155550100", "label": "Call us" }
  }
}

Follow progress with the rcs.agent.status_updated webhook rather than polling.

Side exits are changes_requested, rejected (with declineReason) and deactivated. The launch market is the country of the brand's address. Supported countries include the US, UK, Austria, Bangladesh, Brazil, DR Congo, France, Germany, India, Italy, Mexico, the Netherlands, Nigeria, Norway, Portugal, Singapore, South Africa, Spain and Sweden. Spanish carriers have paused new launches for now; Spanish agents are filed once they reopen.

#Sending messages

You can send once the agent is testing (to accepted test phones) or live (to any RCS phone). Pass text for a plain message or content for anything richer.

curl -X POST https://api.pozy.ai/v1/rcs/messages \
  -H "Authorization: Bearer $POZY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: delivery-A10423-out" \
  -d '{
    "agentId": "66c4d2e1f0a9b8c7d6e5f4a3",
    "to": "+13105551234",
    "content": {
      "type": "text",
      "text": "Your parcel A-10423 is out for delivery today.",
      "suggestions": [
        { "type": "reply", "text": "Track it", "postbackData": "track:A-10423" },
        { "type": "openUrl", "text": "Change delivery", "url": "https://acme.example.com/d/A-10423" },
        { "type": "dial", "text": "Call driver", "phoneNumber": "+14155550142" }
      ]
    },
    "fallbackText": "Your parcel A-10423 is out for delivery today. Track: https://acme.example.com/d/A-10423"
  }'

const res = await fetch("https://api.pozy.ai/v1/rcs/messages", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.POZY_API_KEY}`,
    "Idempotency-Key": "delivery-A10423-out",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    agentId: "66c4d2e1f0a9b8c7d6e5f4a3",
    to: "+13105551234",
    content: {
      type: "text",
      text: "Your parcel A-10423 is out for delivery today.",
      suggestions: [
        { type: "reply", text: "Track it", postbackData: "track:A-10423" },
        { type: "openUrl", text: "Change delivery", url: "https://acme.example.com/d/A-10423" },
        { type: "dial", text: "Call driver", phoneNumber: "+14155550142" },
      ],
    },
    fallbackText: "Your parcel A-10423 is out for delivery today. Track: https://acme.example.com/d/A-10423",
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(data.error);
console.log(data.id, data.conversationId);

import os, requests

resp = requests.post(
    "https://api.pozy.ai/v1/rcs/messages",
    headers={
        "Authorization": f"Bearer {os.environ['POZY_API_KEY']}",
        "Idempotency-Key": "delivery-A10423-out",
    },
    json={
        "agentId": "66c4d2e1f0a9b8c7d6e5f4a3",
        "to": "+13105551234",
        "content": {
            "type": "text",
            "text": "Your parcel A-10423 is out for delivery today.",
            "suggestions": [
                {"type": "reply", "text": "Track it", "postbackData": "track:A-10423"},
                {"type": "openUrl", "text": "Change delivery", "url": "https://acme.example.com/d/A-10423"},
                {"type": "dial", "text": "Call driver", "phoneNumber": "+14155550142"},
            ],
        },
        "fallbackText": "Your parcel A-10423 is out for delivery today. Track: https://acme.example.com/d/A-10423",
    },
)
print(resp.json())

content.type picks the layout. Every type takes up to 11 suggestions (buttons) under the message.

Keep labels to 25 characters. postbackData is your own string of up to 2,048 characters (JSON works) that Pozy hands back as is on a tap; without it you get the label. Set ttlSeconds if a message that has not been delivered by then should be dropped.

#SMS fallback

Set smsFallbackFrom on the agent to one of your numbers that can text, and phones without RCS still get the message, as an SMS from that number. The SMS body is your fallbackText if you send one; if not, Pozy uses the message text, or for a card its title, description and media link. With no fallback number, phones without RCS get nothing.

To check ahead of time, call Check RCS capability with up to 100 numbers. Each result has rcsCapable and the rich features the phone supports.

#Media requirements

#Limits

A few things are refused. You cannot send while the agent is in neither testing nor live. The brand contact cannot be a Gmail address or a generic info@ or support@ mailbox. The contact buttons need more than a website. Replies sent from the inbox are plain RCS text only; for cards and buttons, use POST /v1/rcs/messages.

#Analytics

RCS has no post analytics. Each message reports delivery and reads as webhooks, and conversation metrics are in Inbox analytics.

#Inbox

Replies thread into the agent's inbox conversation, keyed by the person's phone number, with platform: "rcs". Every inbound message fires message.received; the first message of a new thread also fires conversation.started.

Match on postbackPayload, not the label: labels are for people and may change. Your sends report message.delivered, message.read and message.failed, including messages that went out through the SMS fallback. STOP (and STOPALL, UNSUBSCRIBE, CANCEL, END, QUIT) opts the person out and later sends return 409. Only their START opts them back in.

#Pricing

An RCS agent has a setup fee when it is submitted, a one-time fee on US carrier approval, and a monthly fee from the day it goes live (never while it is in review). Messages are billed per message, sent and received, by destination. See Pricing for the current amounts.

#Errors you may see

Errors covers the error format.

#Endpoints

#Webhook events