Agent RCS messages
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.
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 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.
Queued is not delivered
An accepted request returns HTTP 202 after Apostra saves the message to the
outbound queue:
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.
RCS messages count toward the line’s
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.
