> ## Documentation Index
> Fetch the complete documentation index at: https://docs.heylua.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Channel Capabilities

> What each channel supports for outbound messaging — windows, cold start, recipients, and limits

## Overview

Channels differ in what they allow for **agent-initiated** (outbound) messages: some let you message anyone any time, some require a prior conversation, and some enforce platform-specific time windows. This page is the reference matrix. For the API itself, see [Channels API](/api/channels); for the concepts, see [Proactive Messaging](/channels/proactive-messaging).

## Capability matrix

| Channel       | Free-form outbound | Cold start      | Address by              | Time window            | Notes                                             |
| ------------- | ------------------ | --------------- | ----------------------- | ---------------------- | ------------------------------------------------- |
| **WhatsApp**  | In-window only     | Template only   | `userId`, `phoneNumber` | 24h since last inbound | Outside the window, use an approved template      |
| **SMS**       | Any time           | ✅ `phoneNumber` | `userId`, `phoneNumber` | None                   | Carrier opt-out (STOP/HELP/START); regional rules |
| **Email**     | Any time           | ✅ `email`       | `userId`, `email`       | None                   | Subject, HTML, cc/bcc, attachments                |
| **Web chat**  | To known user      | —               | `userId`                | None                   | Renders the full formatting component set         |
| **Teams**     | To known user      | —               | `userId`                | None                   | **Warm-only** — needs an existing conversation    |
| **Instagram** | To known user      | —               | `userId`                | None                   | **Warm-only**                                     |
| **Messenger** | To known user      | —               | `userId`                | None                   | **Warm-only**                                     |

* **Cold start** — reach a recipient who has *never* messaged your agent (by raw `phoneNumber` / `email`).
* **Warm-only** — you can only message a user who already has a conversation with your agent (address them by `userId`).

## WhatsApp

<CardGroup cols={2}>
  <Card title="24-hour window" icon="clock">
    Free-form messages are allowed only within 24 hours of the user's last inbound message (a Meta rule).
  </Card>

  <Card title="Templates outside the window" icon="whatsapp" iconType="brands">
    Use an approved template via `Channels.whatsapp.sendTemplate` to start or re-open a conversation.
  </Card>
</CardGroup>

* **Cold start:** only via an approved template — you cannot free-form message a number that hasn't messaged you.
* **Closed-window default:** `Channels.send` queues the message and prompts the recipient to opt in; the queued text delivers once they re-engage (`queued: true`). Override with `options.whatsapp.onClosedWindow: 'fail'` to handle the fallback yourself.
* **US (+1) recipients:** the opt-in prompt is a marketing-category template that Meta may not deliver to US numbers — send a utility template directly for reliable US outreach.
* **Media & rich templates:** image/video/document headers and buttons are supported — see [Templates API](/api/templates#media-headers).

## SMS

* **No time window** — you can send any time.
* **Cold start:** ✅ via `phoneNumber`.
* **Opt-out compliance:** recipients can reply `STOP` (opt out), `HELP` (info), or `START` (opt back in). Opted-out recipients are suppressed automatically — a send to a suppressed number is rejected.
* **Branding & regional rules:** outbound SMS is brand-prefixed and includes the required disclosures; delivery is subject to regional allow-lists and carrier (10DLC) registration.
* **Sender number:** resolved automatically — your agent's own SMS number if configured, otherwise a shared Lua number matched to the recipient's country, otherwise a shared fallback. You don't need a dedicated number to send.

## Email

* **No time window.**
* **Cold start:** ✅ via `email`.
* **Rich content:** subject, plain-text and/or HTML body, `cc`/`bcc`, and attachments (fetched from a public URL at send time; combined cap 28 MB).
* **Threading:** replies thread back to the agent's conversation via standard email reply headers.
* Use [`Channels.email.send`](/api/channels#channels-email-send) for the full shape.

## Web chat

* **Warm delivery** to a known user (`userId`) — delivered to the user's embedded [chat widget](/chat-widget/introduction).
* Renders the full set of [response formatting components](/formatting/introduction).

## Teams, Instagram, Messenger

* **Warm-only.** You can message a user only if they already have a conversation with your agent — address them by `userId`. There is no cold-start path on these channels.

## Recipient resolution

When you pass `to: { userId }`, the channel-native address (phone number, email, page-scoped ID, etc.) is resolved from the user's conversation history with your agent. When you pass a raw `phoneNumber` or `email`, it's used directly (cold start, where the channel supports it).

<Note>
  A recipient must be reachable on the channel you choose. Sending WhatsApp to a `userId` who has only ever used email will fail to resolve a WhatsApp address — pick a channel the user is actually on, or use [`user.send()`](/api/user#send) to reach them on their active channel.
</Note>

## Next steps

<CardGroup cols={2}>
  <Card title="Channels API" icon="paper-plane" href="/api/channels">
    The send methods and their full input/output shapes
  </Card>

  <Card title="Proactive Messaging" icon="bell" href="/channels/proactive-messaging">
    The model behind agent-initiated messages
  </Card>
</CardGroup>