Skip to main content
After this guide, end users who message your WhatsApp Business number talk to your agent, and the agent can message them first with Channels.send or an approved WhatsApp message template. You need a Meta Business account with a WhatsApp Business Account (WABA) and a phone number in it. The dashboard creates or connects those through Meta’s Embedded Signup; the CLI takes credentials you already hold. Verified against lua-cli 3.33.0. Before you begin
  • A Meta Business account and a WhatsApp Business Account with a phone number, following Meta’s Cloud API getting-started guide. Meta’s free test number is enough for development.
  • For the CLI path: the phone number ID, the WABA ID, and an access token from WhatsApp → API Setup in your Meta app. For production, generate a permanent token through a system user.
  • An agent with a promoted production version; see Release an agent.
1

Link the number

Pick one path. Both register the number with the Cloud API and subscribe the WhatsApp Business Account to the app that issued the token.
In the admin dashboard open Agents, select the agent, select + in the Channels section of its Overview tab, and choose WhatsApp in Connect a channel. Tick I accept the Terms of Service and Privacy Policy and select Connect. Meta’s Embedded Signup opens: sign in with Facebook, then select or create the Business account, the WhatsApp Business Account, and the phone number. When it closes, the channel is connected and the webhook is already configured.
2

Provider console: point your app's webhook at Lua

Skip this step on the admin dashboard path. On the CLI path, Meta delivers messages to the app that issued the token, so that app’s webhook must point at Lua. In the Meta app dashboard open WhatsApp → Configuration, set the callback URL to https://wa.heylua.ai/whatsapp/webhook, enter the verify token, and subscribe the messages webhook field.The verify token is Lua’s, not one you choose, and the CLI doesn’t print it.
If the CLI prints the webhook URL with /webhook twice, use the single /webhook form.
3

Verify

From a phone, send hello to the business number. The agent replies in the same chat. lua channels list then shows a WHATSAPP entry with the number, and the list’s detail view shows Meta’s status and quality rating for it.

​
Channel behavior

user.send() also reaches an end user whose most recent conversation with the agent is on WhatsApp; Meta applies the same 24-hour rule to it. To receive receipts in code, subscribe a webhook to the events you want.

​
Limits

  • Free-form sends: 24 hours after the end user’s last inbound message. Message templates have no window but need Meta’s approval.
  • Closed-window queueing to a +1 (US or Canada) number: Meta blocks the marketing-category opt-in prompt, so the send still returns queued: true with a warning and the prompt may never arrive. Send an approved WhatsApp message template to those recipients instead.
  • Reactions: the target message must be at most 30 days old.
  • A number connects to one agent at a time. Linking it again, to this or another agent, is refused with Channel already exists.
  • Meta’s messaging tiers and quality rating govern volume. The rating appears in the channel’s detail view in lua channels and in the admin dashboard.

​
Troubleshooting

The number is already linked to an agent. Run lua channels list to see whether it is this one; to move it to another agent, disconnect it in the admin dashboard first.
The phone number ID isn’t in the WhatsApp Business Account you gave. Copy both IDs from WhatsApp → API Setup of the same Meta app.
Meta rejected the stored token (a revoked system user, a password change, a disabled WABA). Reconnect from the admin dashboard; on the CLI path, generate a new token and link again.
The app that issued the token isn’t delivering to Lua. Check the callback URL, the verify token, and that the messages field is subscribed and the WhatsApp Business Account is subscribed to that app.

​
Next steps

Send proactive messages

Reminders and notices, the 24-hour window, and WhatsApp message templates.

Channels reference

send, whatsapp.sendTemplate, whatsapp.sendReaction, and delivery status.

Response formatting

What each component becomes on WhatsApp.

About channels

The inbound and outbound channel vocabularies.