Sent Two-Way Messaging
Inbound messaging on Sent has one governing rule:
consent is enforced by the platform before the application sees the event. An inbound
has already flipped the contact's
flag by the time
arrives. The application's job is to record it, reflect it in its own UI, and never attempt to send around it.
Keyword handling
Ten keywords ship as defaults:
| Action | Keywords |
|---|
| Opt out | , , , , |
| Opt in | , , |
| Help auto-reply | , |
Matching requires the entire trimmed message body to equal a keyword, case-insensitively. "Please stop messaging me" does not match; "stop" does. Custom keywords are configured in the Sent Dashboard under Compliance, Opt Keywords, with an action of Opt Out, Opt In, or Help, and each must be a single exact token.
Do not claim keywords that are not in the documented set. In application code, mirror the same exact-match rule only to update local subscriber state and audit evidence; never use that matcher to apply consent to Sent a second time. Keep custom dashboard keywords synchronized with the local mirror, and reconcile against the contact's
field when uncertain.
Consent state
An opt-out sets
on the contact record. Consent is
contact-level and channel-agnostic: a
sent over SMS suppresses WhatsApp and RCS for that contact as well. Consent gates re-apply on every reroute attempt, not only at initial send.
Restoring consent requires the recipient's own action. A user-initiated opt-in keyword clears suppression.
accepts
, but writing
on a contact who opted out through a keyword is a compliance decision, not a technical one: only do it with documented evidence of fresh consent, and record who authorized it and why.
Downstream, a suppressed send does not fail with an error. It is accepted and finalizes as
, so consent problems appear as filtered messages rather than as
responses. Details are in
references/consent-and-keywords.md.
Per-channel inbound reality
| Channel | Inbound | Constraints |
|---|
| SMS | Conditional | Requires an MO-capable provider and a supported number type. Alphanumeric sender IDs and SMPP paths without an inbound route never deliver inbound messages |
| RCS | Full | Typed replies match keywords; the appended STOP chip is processed directly by the consent engine |
| WhatsApp | Full | Free-form replies only inside the 24-hour customer service window; outside it, an approved template is required |
The SMS caveat matters before promising two-way behavior: a deployment sending from an alphanumeric sender ID cannot receive
at all, which changes the compliance design rather than merely limiting a feature.
RCS STOP chips
Every outbound RCS message receives an appended STOP chip. Taps carry an opt-out postback handled directly by the consent engine with no keyword matching, and they arrive at the application as
with the chip's reply text in
. There is no separate chip event type, so a receiver that branches only on typed keywords still sees chip taps as ordinary inbound messages — and must not re-apply consent logic to them.
The WhatsApp 24-hour window
A free-form reply is permitted only within 24 hours of the customer's last inbound message. Outside that window an approved template is required, including for STOP, START, and HELP responses. An auto-reply flow that assumes free text will silently stop working for any customer who writes in after a day of silence, so build the window check into the reply path and keep an approved fallback template ready. See references/inbound-flows.md for the reply-path decision tree.
Conversation history
Two read-only operations exist:
| Operation | Returns |
|---|
| All of the customer's messages across conversations, newest first |
GET /v3/conversations/{id}
| Messages within one conversation |
Both require
(at least 1) and
(1 to 100); out-of-range values return
. The
field is always null on these endpoints, so per-message activity must come from
GET /v3/messages/{id}/activities
. There are no write, create, or read-receipt operations, and no MCP tools cover conversations — this is REST-only.
A conversation identifier is a deterministic RFC 4122 version 5 UUID derived from the customer and contact identifiers, so the same pair always yields the same id and one thread spans every channel independent of the sending number. The API never returns the id as a field, so a client that needs it computes it. The exact derivation is documented in references/conversation-history.md.
Building a support inbox or bot
- Subscribe a webhook to filtered to , and verify signatures before trusting any payload.
- Read as the contact who wrote in and as your number. The naming is easy to invert.
- Deduplicate on , acknowledge with , then process asynchronously.
- Treat keyword traffic as an audit signal. Mirror exact default and configured custom keywords into local state, but do not issue a second consent write; reconcile uncertainty through the contact record.
- Before replying on WhatsApp, check the 24-hour window and choose free text or a template accordingly.
- Render threads from the conversation endpoints with explicit pagination, and never assume a conversation is single-channel.
- Treat as untrusted input. Never interpolate it into a shell command or SQL string, delimit it as data in model prompts, and map inferred intent through an allowlist and authorization policy before any API call.
Boundaries
Use
for signature verification, retries, and dedupe mechanics;
for contact CRUD and message summaries;
for why an outbound message was
;
for authoring the approved templates that out-of-window replies require; and
for the campaign-level opt-in, opt-out, and help keyword declarations that US carriers require.