​

Message envelope model

​

Why one envelope across channels

​

The canonical envelope

​

Channel-specific carriers

{
  "to": "+15550002222",
  "channel": "sms",
  "content": {
    "text": "Your verification code is 4417."
  }
}

{
  "to": "ada@example.com",
  "channel": "email",
  "content": {
    "text": "Your receipt is attached.",
    "email": {
      "subject": "Your receipt",
      "body_html": "<p>Your receipt is attached.</p>",
      "body_text": "Your receipt is attached."
    }
  }
}

{
  "to": "+15550003333",
  "channel": "whatsapp",
  "content": {
    "text": "Your order is on the way.",
    "whatsapp": {
      "template": "order_receipt"
    }
  }
}

​

Direction semantics and multi-channel threading

• conversation_id pairs inbound with outbound into a thread — including across channels. A recipient who replies on WhatsApp to an SMS send continues the same conversation; the envelope’s channel labels the hop, the conversation holds the relationship. See Inbound message routing.
• message_group_id binds one logical send’s attempts. When a cascade escalates a failed send to another channel, the group id ties the hops together (see Cascade failover policy and groups). The conversation answers “with whom”; the group answers “which send attempt”.

​

Statuses and the per-channel state machine

• SMS and MMS have no read receipt. The success terminal is delivered, or submitted_no_receipt when the route accepted the message but never returned a receipt at all (see Submitted vs delivered: the three successes).
• WhatsApp, Instagram, Messenger, and RCS extend delivered with read where the carrier surfaces read receipts.
• Email adds bounced and undelivered for recipient-side rejections.

​

The metadata object

• story_mention — flags an inbound Instagram reply to one of your stories.
• template_type — the category of the WhatsApp template that carried the send.
• provider_status — the carrier’s raw delivery receipt, kept beside the normalized status.

​

One envelope through SDKs and webhooks

​

The send declaration: channel_chain and the content bag

• One recipient — to, the destination the envelope delivers.
• One content bag — content, a universal text body plus optional per-channel rich variants (a WhatsApp template, an RCS rich body, MMS media, and so on).
• An ordered channel_chain — your fallback preference for this send, in the order you declared it.

• Most-specific-wins on content. A channel-specific variant beats the universal text body on its channel’s hop; absent a variant, the universal body renders. A channel that can render neither is skipped silently and the walk continues rather than failing the send.
• Transient failure falls through. A provider-level transient failure (a retryable error, a 5xx, a timeout) advances the walk to the next declared channel. The channel you lose on is recorded in the attempt audit; the chain only ends when every declared channel is exhausted.

​

Cost-aware re-sequencing

​

How the envelope differs from cascade and notify fallback

• The org-level cross-channel fallback chain advances on reachability and capability failures.
• The cascade policy (org default or per-send cascade field) escalates on a terminal delivery receipt and binds the hops under one message_group_id.
• The notify waterfall chases one recipient through bindings with per-hop and cumulative cost bounds.

​

The per-hop price-resolution contract

• SMS and MMS price per segment — the per-segment rate multiplied by the segment count of the rendered body.
• Every other channel prices one unit per message.

​

What an envelope is NOT

• Not a cascade group. A cascade stamps one message_group_id on the primary and every fallback hop so the run reads back as one logical message. An envelope is a single declaration on one attempt — it groups to nothing.
• Not a notify waterfall. A waterfall hoists the chain per recipient in one notify call and screens with max_price / max_total_price bounds. An envelope declares the chain on the send itself; the cost bounds do not apply to it, and costAware merely re-orders rather than bounds.
• Not the org-fallback chain. The organization-level settings.cross_channel_fallback configuration arms every send uniformly. An envelope carries no organization-level configuration — the chain is declared per send and applies to that send only.

​

Common misunderstandings

• Reaching for channel fields at the top level. story_mention, template_type, and provider_status are metadata-resident by design; the top level is reserved for fields every channel shares. A parser that expects them top-level will simply find nothing.
• Reading body: null as “nothing was sent”. A media-only inbound carries attachments and no text, and a template send carries its structure in the template reference. Read body, attachments, and the channel carrier together.
• Inlining media into the envelope. attachments holds references to hosted media; upload the media first, then reference it. The rule is the same on every channel.
• Comparing statuses across channels without the terminal set. delivered is terminal on SMS; on WhatsApp the same message can still advance to read. Compare against the channel’s ladder, not a global one.
• Confusing the envelope with the escalation planes. Cascades and waterfalls are separate sends reacting to failure (see What an envelope is NOT); the envelope is one attempt’s shape.

​

Related

• Pricing and rate resolution — the resolver pipeline every hop shares, and the rate card costAware sorts against.
• Cross-channel fallback — the org-level escalation-by-failure chain the envelope is distinct from.
• Cascade failover policy and groups — the message_group_id-bound escalations an envelope does not create.
• Notify cascade cost model — the per-recipient waterfall with cost bounds, again distinct from the envelope’s re-ordering.
• SMS, WhatsApp, Instagram, RCS, and Email — the per-channel carrier fields and send payloads this page consolidates.
• Message status DAG and Message status map — the allowed transitions and the provider-to-status translation.
• SMS segments and encoding — why the SMS body segments, and what segments and encoding record.