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.

Conversation Windows

Free-form text (a message sent with text instead of template) is only allowed while a conversation with the contact is open. Two separate windows govern that, with two different clocks, and which ones apply depends on the channel.

The two are independent. A send pinned to channel: "whatsapp" answers to Meta's window alone, so Sent's rule cannot rescue it and a template never opens it. Everything else answers to Sent's rule alone.

Sent's conversation rule (SMS, RCS, auto-detect)

Once the contact has replied to you even once, free-form stays available indefinitely. A reply is consent to converse and it does not expire, so a contact who answered you months ago is still reachable with free-form text today. Only an opt-out ends it.

The 7-day clock applies only to contacts who have never replied. It exists to stop a one-sided stream of free-form content riding on the back of a single template: with no reply, free-form is allowed for 7 days after the last approved template you sent, and then the conversation lapses until another template re-opens it.

Three things deliberately do not count:

• Your own free-form messages. Only a reply from the contact or an outbound template counts, so sending free-form text every few days cannot extend the 7-day window of a contact who has never answered.
• A STOP exchange. Neither an inbound opt-out keyword nor the opt-out confirmation you send back counts as engagement. START and HELP are treated as genuine engagement instead, and either leg of that exchange counts: the contact's inbound keyword does, and so does the auto-reply you send back, because it is an ordinary approved template and only opt-out auto-replies are excluded. Separately, Sent's compliance auto-replies are exempt from the gate itself, so an opt-out confirmation always goes out even when the contact's first-ever message is a STOP.
• An opt-out. Consent is enforced before this gate, so an opted-out contact is blocked outright no matter how recently they replied.

WhatsApp's 24-hour window

The 24-hour window applies to WhatsApp only, and it is Meta's rule rather than Sent's.

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

An outbound template does not open Meta's window: only the contact can. This is why a past reply is not enough on WhatsApp the way it is on SMS and RCS. Meta requires a recent one, so a reply from last month leaves Meta's window shut even though Sent's rule is satisfied.

If the contact replies with an opt-out keyword (see Keyword Detection), it does not open a window. No free-text reply is sent; the keyword is handled by the compliance engine only.

When WhatsApp's window is shut

On a send with channel omitted, Sent treats WhatsApp as unreachable while Meta's window is closed and falls back to RCS or SMS, so the message still goes out on the strength of Sent's rule. A send pinned to channel: "whatsapp" has nowhere to fall back to and fails with WHATSAPP_TEMPLATE_REQUIRED; see Free-Form Send Errors.

---

How Inbound Messages Work

The chart follows a contact's reply, so Sent's rule is satisfied by definition on every path through it: the inbound is the reply that unlocks free-form. The lapsed case only arises for a contact who has never replied; see Free-form send blocked after a quiet period.

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. A free-form send pinned to channel: "whatsapp" is governed by Meta's 24-hour customer-service window alone; auto-replies are delivered as free-form text inside the 24-hour 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, gated by Sent's conversation rule, and every outbound RCS message carries a built-in STOP chip (see RCS Suggestion Chips).
• SMS two-way messaging is gated by the same conversation rule as RCS, and 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.

Free-form send blocked after a quiet period

This only affects contacts who have never replied. If the contact has answered you at any point, free-form stays available and a quiet period changes nothing. For a contact who has never replied, the conversation lapses 7 days after the last approved template you sent, and free-form sends are blocked with CONVERSATION_TEMPLATE_REQUIRED on SMS, RCS, and auto-detect until another template re-opens it. Your own free-form messages do not refresh that window, so a one-way stream of free-form text cannot keep it open.

If a contact was reachable yesterday and is not today, check whether they have ever replied to you, and if not, when they last received a template; see Conversation Windows.

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