sent-routing-strategist

name: sent-routing-strategist description: Decides how a Sent message should reach the recipient — automatic routing versus a pinned channel, what the channel array actually does, how fallback and reroute work, and why a message ended as FAILED, FILTERED, BLOCKED, or channel "auto". Use when choosing the channel field, expecting WhatsApp-to-SMS fallback, debugging an unexpected route or duplicate charges from multiple channels, or interpreting message status and activity evidence.

Sent Routing Strategist

Routing is where the most expensive Sent misconceptions live. Two facts govern almost every decision:

1. The channel array is a broadcast list, not a preference order. ["whatsapp", "sms"] with two recipients creates four messages and four charges. There is no fallback field and no ordered-preference syntax.
2. Automatic routing is the fallback mechanism. Omit channel, or send ["sent"], and the platform selects a route, then reroutes across up to three distinct channel-and-provider pairs when a route-level failure occurs.

Decide the channel value

Any value outside sent, sms, whatsapp, and rcs returns 400. When a user asks for ordered fallback, name the misconception explicitly before writing code, because the failure mode is duplicate delivery and duplicate cost rather than an error.

What a pinned channel gives up

Pinning restricts route matching to the named channel. Rules without a channel constraint still match and resolve to the pinned channel, so pinning does not require channel-specific rules to exist. A pinned send never crosses to a different channel, though same-channel provider hops remain possible when a rule permits them. If no route exists on the pinned channel, the message ends FAILED with no route matched — it does not silently fall back.

Pin when a compliance, contractual, or content constraint requires a specific channel. Otherwise prefer automatic routing.

Reading the outcome

POST /v3/messages returns 202 with per-recipient message_id values. For automatic routing, the echoed per-recipient channel is not a resolved route and is never updated afterward. Resolve the truth from evidence:

Terminal status interpretation

An outcome whose channel is auto means the message ended before any route was attempted. The causes are no matching route, invalid template parameters, a consent block, or an account precondition. Account preconditions do not reject the send request: it is accepted with 202 and the affected messages surface as BLOCKED.

Sent records internal send-time reason codes on the message for these cases, but does not return them in API responses or webhooks, so diagnosis relies on the status-and-channel combination plus the activity history. The mapping from observable evidence to root cause is tabulated in references/routing-diagnosis.md.

Reroute behavior

A failed route is retried only when the terminal failure signals a route or carrier problem another route might overcome: undeliverable by this route, provider service unavailable, provider timeout, or transport error. Every other failure stays FAILED.

Reroute reuses the same message_id and re-runs the pipeline, so message.queued and message.routed fire again, consent gates re-apply on every attempt, and already-attempted routes are excluded. The ceiling is three distinct channel-and-provider pairs across the initial send and all reroutes.

The WhatsApp-to-SMS behavior customers ask about is a specific case of this: a WhatsApp message accepted and then failed for a recipient-side reason reroutes and records a recipient-scoped rule that WhatsApp is not deliverable for that number, so subsequent automatic sends skip WhatsApp for that recipient. It requires automatic routing; a pinned WhatsApp send cannot produce it.

How automatic routing selects a route

Routes come from platform-maintained rules evaluated at send time against recipient attributes (country, number prefix, exact number, carrier, number type, ported state), sender, template attributes, channel, and whether the destination is international. Ordering is: exact-recipient rules first, then account-scoped before global, then match specificity, then rule priority, then longer number prefix, then the older rule. Inactive, deleted, expired, and below-threshold rules are excluded. Candidates whose template has an explicit non-approved review status on that channel are dropped, while a channel with no recorded review is not blocked. The first surviving candidate wins and the rest remain available as fallback routes.

There is no fixed channel preference order, so never promise "RCS first, then WhatsApp, then SMS." Read references/routing-model.md before making any claim about why a specific route was chosen.

Cost and volume consequences

Because broadcast multiplies messages by recipients, review any multi-channel array against expected spend before sending. A 1,000-recipient send with two channels is 2,000 messages. The per-request recipient ceiling is 1,000, and documented pacing pairs full batches with roughly one request per second to stay inside the 200-requests-per-minute budget.

RCS today carries text plus up to four suggestion chips, mapped from template buttons, and every outbound RCS message receives an appended STOP chip. Do not design an RCS-pinned flow that depends on rich cards, carousels, or media.

Boundaries

Use sent-messaging to execute a single send with confirmation, sent-two-way-messaging for consent and inbound keyword semantics, messaging-performance-analyzer for aggregate delivery-rate regressions, and sent-webhook-engineer for receiving and deduplicating the events this skill teaches you to read.