Skip to main content

​
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; for the concepts, see Proactive Messaging.

​
Capability matrix

ChannelFree-form outboundCold startAddress byTime windowNotes
WhatsAppIn-window onlyTemplate onlyuserId, phoneNumber24h since last inboundOutside the window, use an approved template
SMSAny time✅ phoneNumberuserId, phoneNumberNoneCarrier opt-out (STOP/HELP/START); regional rules
EmailAny time✅ emailuserId, emailNoneSubject, HTML, cc/bcc, attachments
Web chatTo known user—userIdNoneRenders the full formatting component set
TeamsTo known user—userIdNoneWarm-only — needs an existing conversation
InstagramTo known user—userIdNoneWarm-only
MessengerTo known user—userIdNoneWarm-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

24-hour window

Free-form messages are allowed only within 24 hours of the user’s last inbound message (a Meta rule).

Templates outside the window

Use an approved template via Channels.whatsapp.sendTemplate to start or re-open a conversation.
  • 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.

​
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 for the full shape.

​
Web chat

​
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).
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() to reach them on their active channel.

​
Next steps

Channels API

The send methods and their full input/output shapes

Proactive Messaging

The model behind agent-initiated messages