Skip to main content
After this guide, messages that arrive in a Bird (formerly MessageBird) Conversations workspace reach your agent, and replies go back through Bird with WhatsApp interactive buttons and lists where the channel supports them. Use this when your WhatsApp number or other messaging channels already live in Bird; otherwise connect WhatsApp directly. You need a Bird workspace with an access key. Setup is in the admin dashboard or over the admin REST API; there is no CLI command. Verified against lua-cli 3.33.0. Before you begin
  • The Bird workspace id and an access key for the Conversations API.
  • The webhook signing key for the workspace. Without it, Lua can’t verify deliveries.
  • Optionally, the ids of the Bird channels (for example one WhatsApp number) this agent should answer.
1

Dashboard: add the MessageBird channel

Add a channel of type MessageBird to the agent (POST /admin/agents/<agentId>/channels with type: "messagebird" and a messagebird object). workspaceId and accessKey are required; add signingKey. Leave channels empty to make this agent the catch-all for the whole workspace, or list channel ids to bind only those; several agents can share one workspace as long as their channel lists don’t overlap and only one of them is a catch-all.Set createWebhook: true to have Lua register a message.created webhook for each listed channel using your access key. Secrets are stored and never returned.
2

Provider console: point the webhook at Lua

If you didn’t let Lua create the webhooks, create one in Bird for each channel with the URL https://wa.heylua.ai/messagebird/webhook and the message.created event . Add message.updated too if you want delivery receipts and failures recorded.
3

Verify

Send a message to one of the bound Bird channels. The reply comes back from sender “Lua” in the same conversation; Lua.request.channel inside your tools is messagebird. Confirm with lua logs --type agent_response.

​
Channel behavior

Interactive lists and buttons are WhatsApp message types. When Bird rejects one, the same content is resent as plain text. Each Bird contact shares one conversation across messages. Delivery statuses sent, delivered, and read from message.updated events are recorded against the reply; a failed send is retried up to 2 times.

​
Limits

​
Troubleshooting

Another agent already owns one of the channel ids you listed. Remove the overlap, or disconnect that channel from the other agent first.
Only one agent can answer a workspace’s unlisted channels. List specific channel ids for this agent, or remove the existing catch-all.
Deliveries are matched by workspace and channel id: a message on a channel that isn’t listed and has no catch-all is dropped, and a delivery whose signature can’t be verified with the stored signing key is rejected. Check the channel list and the signing key, then look for the inbound turn in lua logs --type user_message.

​
Next steps

WhatsApp

Connect a WhatsApp Business number directly.

Response formatting

Components that become buttons and lists.

About channels

Inbound and outbound channel vocabularies.

Channels overview

Every channel and where it is set up.