> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apostra.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent RCS messages

> Queue a plain-text RCS message from a provisioned agent line and retry safely

# Agent RCS messages

<Warning>
  Agent phone lines are in limited rollout. This command returns `404` until
  Apostra enrolls your Seller Account in agent phone lines, and `400` until
  Apostra binds a verified RCS agent to the line.
</Warning>

`POST /api/v2/communications/rcs/messages` queues a plain-text RCS message
from an agent line. It is the only command that sends RCS.
[`POST /api/v2/communications/messages`](/v2/reference/agent-sms) sends SMS
only. Both commands use the same outbound queue, opt-out record, sending limits
and request IDs.

RCS (Rich Communication Services) is the carrier-branded text channel in RCS
messaging apps such as Google Messages. An RCS message shows your verified
business name and logo in the conversation instead of a bare telephone number,
and reports read receipts where the recipient's carrier and handset support
them. It does not turn an iPhone message bubble blue; Apple reserves that for
iMessage.

The API credential needs `interchange:write` and must belong to the same
Seller Account as the line. Apostra takes the account from the credential,
never from the request body.

```bash theme={null}
curl -X POST "https://api.apostra.com/api/v2/communications/rcs/messages" \
  -H "Authorization: Bearer $INTERCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "requestId": "df3b1f38-77ad-4e2e-ad67-594433cf1be7",
    "endpointId": "123",
    "to": "+12025550101",
    "text": "Your proposal is ready."
  }'
```

| Field | Required | Description |
| - | - | - |
| `requestId` | Yes | UUID for this intended message. Reuse it only to retry the same message. |
| `endpointId` | Yes | Apostra text-line ID, represented as a numeric string. |
| `to` | Yes | Recipient telephone number in E.164 format. |
| `text` | Yes | Plain text, from 1 to 1,600 characters. |

## Queued is not delivered

An accepted request returns HTTP `202` after Apostra saves the message to the
outbound queue:

```json theme={null}
{
  "data": {
    "message": {
      "outboxId": "92",
      "channel": "rcs",
      "status": "pending",
      "duplicate": false
    }
  },
  "error": null
}
```

`pending` means Apostra has durably queued the message. It does not mean the
carrier accepted it or the recipient received it. A later carrier failure does
not change the `202` you already received. This command does not currently
provide a public status lookup; keep the `outboxId` for support.

## Before a line can send RCS

* **The line has a verified RCS agent.** Apostra binds a carrier-approved RCS
  agent to the line. Without one, this command returns `400` and nothing is
  queued. SMS from the line is unaffected.
* **The recipient can receive RCS.** That depends on the recipient's handset
  and operating system version, their carrier supporting RCS business messages
  and having provisioned your agent, and RCS being switched on. A recipient
  missing any of these cannot receive the message.

**RCS delivery and read status needs a dedicated Messaging Profile.** Apostra
records RCS delivery and read status only for a line that is the only line on
its Messaging Profile. On a shared profile, or a profile that carries more than
one line, the carrier's RCS status reports cannot yet be matched to a line.
Apostra discards them, and the message stays `submitted` even after the
recipient receives or reads it. Ask Apostra which kind of profile your line
uses.

**There is no automatic SMS fallback.** An RCS message to a recipient who
cannot receive it fails and stops there. Apostra does not re-send it as SMS or
MMS. Send SMS with `POST /api/v2/communications/messages` when reaching the
recipient matters more than the branding.

**Consent is shared with SMS.** A line keeps one opt-out record per recipient
for both channels. After a recipient texts `STOP` to the line, this command
returns `400` for that recipient until they text `START`. See
[Opt-out keywords](/v2/reference/agent-sms#opt-out-keywords).

RCS messages count toward the line's
[sending limits](/v2/reference/agent-sms#sending-limits), shared with SMS: the
same destinations, rate and daily spend. An RCS message is counted in segments
exactly like an SMS text of the same content. Rich cards, carousels and
suggested replies are not available yet.

## Retries and errors

A retry with the same `requestId`, line, destination and text returns the same
`outboxId` with `duplicate: true`. Reusing the UUID with different details
returns `409`. That includes a UUID already used for an SMS message through
`POST /api/v2/communications/messages`.

If a request returns `503`, or the network drops before you see a response,
retry with the **same** `requestId`. Apostra never sends a message twice on the
strength of an uncertain result: an unresolved carrier submission is held for
an operator to reconcile rather than re-sent.

| Status | Meaning | Action |
| - | - | - |
| `400` | A field is invalid, the destination is outside the sending limits, the line is inactive, the line has no verified RCS agent, or the recipient opted out. | Correct the request or ask Apostra to register an RCS agent. Do not message an opted-out recipient. |
| `401` or `403` | The credential is missing, invalid, or lacks `interchange:write`. | Use an authorised credential for this account. |
| `404` | The Seller Account is not enrolled in agent phone lines. | Ask Apostra to verify enrollment and provisioning. |
| `409` | The request UUID was already used with different message details or on SMS. | Keep the original details or use a new UUID for a different message. |
| `503` | The service cannot safely protect or queue the message. | Retry the same request ID after the service recovers. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.