Two-Way Conversations

Sent's conversation window lets you hold a free-form, two-way conversation with a contact without managing per-channel session rules yourself. Sent owns the transport: the window state, cross-channel continuity, and compliance teardown. Your own agent (human or AI) owns the dialogue, integrating over webhooks and the freeform-send API.

The 24-hour Window

The 24-hour window applies to WhatsApp only.

When you send a message and the contact replies, WhatsApp opens a 24-hour window from the moment their reply is received. While that window is open, you can respond with free-form text, no template required.

If the contact does not reply within 24 hours, the window closes and you must use a template to send the next message.

If the contact replies with any compliance keyword (see Keyword Detection), it does not trigger the two-way conversation window. No free-text reply is sent; the keyword is handled by the compliance engine only.

SMS and RCS have no time window. As long as you have received an inbound message from the contact, you can reply with free text.

---

How Inbound Messages Work

1. Account Resolution

Sent matches an inbound message to your account using the receiving number on that channel:

• SMS: matched via the phone number provisioned to your account
• WhatsApp: matched via your WhatsApp number's PhoneNumberId

If the receiving number isn't provisioned to any account on that channel, the inbound message is dropped. No account match, no storage.

If a message arrives from a contact you have never interacted with or don't have registered, Sent automatically creates the contact record before responding. If the contact already exists, Sent replies directly without any additional steps.

2. Every Inbound Is Stored

Once the number resolves to your account, all inbound messages are stored as RECEIVED in the Sent backend, including keyword messages like STOP or HELP. Only non-keyword replies are surfaced in the message log and visible in the dashboard.

If you have no provider configured for the inbound channel, that channel's conversation handling does not run and nothing is stored.

3. Reply From Same Sender Routing

When an inbound arrives, Sent records the channel, provider, and sender number it came in on. Future outbound messages to that contact will prefer the same sender, so your reply comes from the same number the contact originally wrote to.

---

Keyword Detection

Sent enforces CTIA/TCPA rules for keyword handling. The rules are strict by design.

Keywords fall into three groups: opt-out keywords such as STOP and CANCEL, opt-in keywords such as START, and help keywords such as HELP. The full default list and matching rules live in the Two-Way Messaging Reference.

Custom Opt-Out Keywords

You can extend the defaults with words that fit your brand or audience. For example, instead of STOP you could configure NDALO or any word your contacts are more likely to use.

Custom keywords are configured in the dashboard under Compliance → Opt Keywords. The same exact-match rule applies: the entire trimmed message body must equal the configured keyword. Default keywords are seeded for every account and remain active alongside any custom keywords you add.

RCS Suggestion Chips

Sent appends a STOP suggestion chip to every outbound RCS message, so recipients can opt out with a single tap. Chip taps arrive as message.received events with the chip's reply text in payload.text. There is no separate event type, so handle them in the same webhook handler as typed replies.

Taps on the built-in STOP chip carry opt-out postback data and are processed by the consent engine directly: the contact's opt_out flag is flipped without relying on keyword matching. Typed RCS replies go through standard keyword detection.

STOP: Always Honored

When a contact sends STOP (or any opt-out keyword), opt-out is recorded unconditionally. Sent does not check whether the receiving number is currently active or assigned. Consent suppression always wins.

Timing: The auto-reply confirmation is sent before the consent write. This is intentional: TCPA permits one final message to confirm opt-out, so the reply goes out first, then the opt-out flag is set.

START: Always Honored

When a contact sends START (or any opt-in keyword), opt-in is recorded unconditionally. If the sending number is not yet a contact, Sent creates the contact record first, then writes the opt-in consent, then sends the auto-reply.

Cross-Channel Opt-Out

Opt-out is contact-level and channel-agnostic. A STOP received on any channel (SMS, RCS, or WhatsApp) suppresses the contact across all channels. Consent lives in one place: the opt_out flag on the contact record in your account. All outbound messages, including auto-replies, check this flag before sending, regardless of which channel they use. If you mirror consent into your own systems, see Handling Opt-Outs and Consent.

---

Auto-Replies

Auto-replies are not special-cased messages. They go through the same send pipeline as any outbound message. That means they require:

• An approved template configured for the action (STOP reply, START reply, HELP reply)
• Consent to be valid (checked after the opt-out write for START; before for STOP)
• A matching message route with a valid E.164 sender number

Routing Auto-Replies

Auto-replies are routed through the standard routing engine: the provider and sender number are resolved by the same routing rules as any outbound message (see Channel Routing). Phone numbers must be in canonical E.164 format (for example, +14155551234) on both the stored route and the contact record for a match to succeed.

---

Channel Scope

Two-way conversation features are not uniform across channels. The feature matrix and provider support tables enumerate exactly what each channel supports; the short version:

• WhatsApp runs the same keyword detection, opt-out, and auto-reply pipeline as SMS and RCS. Auto-replies are delivered as free-form text inside the 24-hour conversation window, and the configured auto-reply template must still be approved for the reply to send. Meta also enforces its own opt-out natively (in-app block and report, quality rating); this is in addition to Sent's pipeline, not instead of it.
• RCS supports the full two-way pipeline, and every outbound RCS message carries a built-in STOP chip (see RCS Suggestion Chips).
• SMS two-way messaging depends on the provider and number type. Only long codes and short codes on MO-capable providers can receive inbound messages; alphanumeric sender IDs and SMPP providers are send-only.

If you are using an alphanumeric sender ID or an SMPP provider and contacts send keywords (STOP, START, HELP), those messages never reach Sent.

---

Common Failure Scenarios

These are the most frequent reasons two-way conversation handling silently stops working.

SMS channel removed or unprovisioned

If your SMS channel is removed or the provisioned number is no longer assigned, inbound messages on that number cannot be matched to your account. The opt-out (or any other keyword) is dropped. It is never processed. Channel resolution must succeed before anything else runs.

If contacts are texting in and nothing is happening, verify that the SMS provider and number are still active and assigned under your channel settings.

SMS provider or number type does not support inbound

Two-way messaging on SMS requires both an MO-capable provider and a supported number type.

MO (Mobile Originated) refers to a message that originates from a contact's phone and travels toward your app. An MO path is the provider's ability to receive those inbound messages and forward them to Sent. Providers that only support MT (Mobile Terminated) can deliver messages to a phone but cannot receive replies from one, making two-way messaging impossible on those routes.

Two common silent failure points:

• SMPP providers: support delivery receipts only. No inbound message is received, stored, or keyword-processed on these routes.
• Alphanumeric sender IDs: send-only by design. Contacts cannot reply to an alphanumeric sender; any attempt is dropped at the carrier level before it reaches Sent.

If contacts are sending keywords and nothing is happening, verify that your route uses a long code or short code on an MO-capable provider. The SMS provider support table lists which providers have an inbound path.

Free-form opt-out phrases are not recognized

Messages like "Cancel my subscription", "Please remove me", or "I don't want these anymore" do not trigger opt-out. Only an exact keyword match does. Contacts who send free-form messages will continue to receive outbound messages until they send an exact keyword (STOP, CANCEL, or a configured custom keyword).

If your contacts are likely to use natural language, consider adding a custom keyword that matches a common phrase, but it must still be a single, exact token, not a sentence.

Auto-reply template not approved

If the template configured for a STOP, START, or HELP auto-reply is in DRAFT or PAUSED status, the keyword is still processed (the opt-out is written) but no confirmation reply is sent. Contacts will not receive any acknowledgement.

Resolve this by publishing the template in the dashboard. See Working with Templates for approval steps.

---

Receiving Inbound Messages via Webhook

Subscribe to message.received events to be notified in real time when a contact replies. The webhook fires for every inbound message, keywords included, and carries the message text, channel, and sender number. Use message_id as your idempotency key, because the same event can be delivered more than once.

Receiving Inbound Messages walks through a complete handler: acknowledging deliveries, deduplicating, storing the message, and skipping compliance keywords. Payload fields are documented in the Events Reference.

---

Retrieving Conversations

Sent groups the messages between you and a single contact into a conversation: one continuous thread across every channel. The conversation id is deterministic, computed from your account's customer id and the contact id, so the same pair always produces the same id no matter which sender number or channel carried the messages. The reason for this design is continuity: a contact who replies over SMS today and WhatsApp tomorrow is still one conversation.

Two endpoints expose conversation history, GET /v3/conversations and GET /v3/conversations/{id}. Parameters, response shapes, and the id derivation are documented in the conversation history endpoints reference.

---

Where to Go Next

Sent owns the transport of a two-way conversation: inbound matching and storage, keyword compliance, auto-replies, and cross-channel continuity. You own the dialogue, through webhooks and the send API.

• Receiving Inbound Messages: build the webhook handler for contact replies
• Two-Way Messaging Reference: keywords, channel support, and conversation endpoints
• Handling Opt-Outs and Consent: mirror consent state into your own systems
• Working with Templates: publish the templates that auto-replies depend on