> ## 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.

# MessageBird

> Route conversations from a Bird (MessageBird) workspace to your agent and reply with WhatsApp buttons, lists, and images

After this guide, messages that arrive in a Bird (formerly MessageBird) Conversations workspace reach your [agent](/concepts/agents), 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](/channels/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.

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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`.
  </Step>
</Steps>

## Channel behavior

| Capability                           | Supported                                                                                                                                                                                |
| ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Inbound text and interactive replies | Yes; a tapped button or list row arrives as its title                                                                                                                                    |
| Inbound media                        | Images, video, audio, and files, re-hosted on the Lua CDN; stickers and unsupported types are ignored                                                                                    |
| Outbound text                        | Yes                                                                                                                                                                                      |
| Images                               | Up to 3 per reply, one message each                                                                                                                                                      |
| List items                           | Two or more become a WhatsApp interactive list (up to 10 rows) with the reply text as its body; one becomes its image plus text                                                          |
| Actions                              | Up to 3 become interactive buttons with labels cut to 20 characters; more become a numbered text list                                                                                    |
| Payment links and documents          | Text with the URL                                                                                                                                                                        |
| Reactions                            | Text fallback                                                                                                                                                                            |
| Proactive sends                      | Not in `Channels.send`; `user.send()` reaches a contact whose most recent conversation with the agent is on this channel, and the admin dashboard can reply to a user who has written in |
| Identity                             | The Bird contact id; the contact's phone number is recorded when present                                                                                                                 |

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

| Limit                            | Value                   |
| -------------------------------- | ----------------------- |
| Images per reply                 | 3                       |
| Interactive buttons              | 3, labels 20 characters |
| Interactive list rows            | 10                      |
| Retries after a failed delivery  | 2                       |
| Catch-all channels per workspace | 1                       |

## Troubleshooting

<AccordionGroup>
  <Accordion title="MessageBird channels [...] are already connected in workspace <id>">
    Another agent already owns one of the channel ids you listed. Remove the overlap, or disconnect that channel from the other agent first.
  </Accordion>

  <Accordion title="A catch-all MessageBird config already exists for workspace <id>">
    Only one agent can answer a workspace's unlisted channels. List specific channel ids for this agent, or remove the existing catch-all.
  </Accordion>

  <Accordion title="Messages arrive in Bird but the agent never replies">
    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`.
  </Accordion>
</AccordionGroup>

## Next steps

<Columns cols={2}>
  <Card title="WhatsApp" href="/channels/whatsapp">Connect a WhatsApp Business number directly.</Card>
  <Card title="Response formatting" href="/channels/formatting/overview">Components that become buttons and lists.</Card>
  <Card title="About channels" href="/concepts/channels">Inbound and outbound channel vocabularies.</Card>
  <Card title="Channels overview" href="/channels/overview">Every channel and where it is set up.</Card>
</Columns>