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

# WhatsApp Business

> Connect your agent to WhatsApp Business API

## Overview

WhatsApp Business API allows your agent to communicate with customers via WhatsApp - the world's most popular messaging app with 2+ billion users.

<CardGroup cols={2}>
  <Card title="Business Messaging" icon="building">
    Professional customer communication
  </Card>

  <Card title="Rich Media" icon="image">
    Images, videos, documents, location
  </Card>

  <Card title="High Engagement" icon="chart-line">
    98% open rates
  </Card>

  <Card title="Global Reach" icon="globe">
    Available in 180+ countries
  </Card>
</CardGroup>

## Prerequisites

Before connecting WhatsApp, you need:

<Info>
  Meta updates its developer dashboard and Business Suite UI frequently. The steps below describe what you need; for exact, up-to-date clicks, follow Meta's official [WhatsApp Cloud API — Get Started](https://developers.facebook.com/docs/whatsapp/cloud-api/get-started) guide.
</Info>

<Steps>
  <Step title="Meta Business Account">
    Create account at [https://business.facebook.com](https://business.facebook.com)

    <Frame>
      <img src="https://mintcdn.com/luaglobal/5airD3u2P6mv3Ovl/images/channels/meta-business-signup.png?fit=max&auto=format&n=5airD3u2P6mv3Ovl&q=85&s=341dd84e4625e3027dd4f19e4d72ae47" alt="Meta Business signup" width="3006" height="1566" data-path="images/channels/meta-business-signup.png" />
    </Frame>

    *Screenshot: Meta Business account creation page*
  </Step>

  <Step title="WhatsApp Business Account (WABA)">
    In Meta's developer dashboard, create an app and select the **WhatsApp** use case. A WhatsApp Business Account is created for you, and you can open it under **WhatsApp → API Setup**.

    See Meta's official guide: [Create an app with the WhatsApp use case](https://developers.facebook.com/docs/development/create-an-app/whatsapp-use-case/).
  </Step>

  <Step title="Phone Number">
    Add and verify a business phone number, or use the free test number Meta provides for development. See Meta's [Get Started guide](https://developers.facebook.com/docs/whatsapp/cloud-api/get-started) for adding and verifying numbers.
  </Step>

  <Step title="Get Credentials">
    Collect the required information:

    * **Phone Number ID**
    * **WhatsApp Business Account (WABA) ID**
    * **Access Token**

    All three appear on the **WhatsApp → API Setup** page of your app in the [Meta developer dashboard](https://developers.facebook.com/apps). For production, generate a permanent token via a System User — see Meta's [Get Started guide](https://developers.facebook.com/docs/whatsapp/cloud-api/get-started).
  </Step>
</Steps>

## Connection Method 1: CLI

### Step-by-Step CLI Setup

<Steps>
  <Step title="Run Command">
    ```bash theme={null}
    lua channels
    ```
  </Step>

  <Step title="Select Link New Channel">
    ```
    ✅ Using agent: myAgent

    ? What would you like to do?
    ❯ 🔗 Link new channel
    ```
  </Step>

  <Step title="Select WhatsApp">
    ```
    ? Select channel type:
    ❯ 📱 WhatsApp
      💬 Facebook Messenger
      📧 Email
      🔒 Slack (Private)
    ```
  </Step>

  <Step title="Enter Phone Number ID">
    ```
    ? Enter phone number ID: 647834045087314
    ```

    Find this in Meta Business Suite → WhatsApp → Phone Numbers
  </Step>

  <Step title="Enter WABA ID">
    ```
    ? Enter WhatsApp Business Account ID (WABA ID): 1390592278829291
    ```

    Find this in Meta Business Suite → WhatsApp → Settings
  </Step>

  <Step title="Enter Access Token">
    ```
    ? Enter access token: ****
    ```

    Generate in Meta Business Suite → System Users → Generate Token
  </Step>

  <Step title="Success">
    ```
    📡 Creating WhatsApp channel...

    ✅ WhatsApp channel created successfully!

    📱 Phone Number: +15557986280
    📊 Status: CONNECTED
    🌍 Country: USA
    🎯 Webhook URL: https://wa.heylua.ai/whatsapp/webhook/abc123
    ```
  </Step>
</Steps>

### Configure Webhook in Meta

<Steps>
  <Step title="Copy Webhook URL">
    Copy the webhook URL from the CLI output.
  </Step>

  <Step title="Open WhatsApp Configuration">
    In your app's developer dashboard, go to **WhatsApp → Configuration**.
  </Step>

  <Step title="Add Webhook">
    Click **Edit**, paste the webhook URL as the **Callback URL**, enter your **Verify token**, and save.
  </Step>

  <Step title="Subscribe to Events">
    Under **Webhook fields**, click **Manage** and subscribe to `messages` and `message_status`.
  </Step>

  <Step title="Verify">
    Meta sends a verification request to confirm the webhook. A green check confirms it's connected.
  </Step>
</Steps>

<Info>
  Meta's webhook setup UI changes periodically. For the current steps and field names, follow Meta's official guide: [Set up Webhooks for WhatsApp Cloud API](https://developers.facebook.com/docs/whatsapp/cloud-api/guides/set-up-webhooks).
</Info>

## Connection Method 2: Admin Dashboard

### Step-by-Step Dashboard Setup

<Info>
  The dashboard uses Meta's **Embedded Signup**, so you don't enter credentials or configure webhooks by hand. Signing in with Facebook lets Meta provision (or connect) your WhatsApp Business Account, phone number, and webhook automatically. Use the [CLI method](#connection-method-1-cli) instead if you already have credentials and prefer to enter them manually.
</Info>

<Steps>
  <Step title="Open the dashboard">
    ```bash theme={null}
    lua admin
    ```

    Or visit [https://admin.heylua.ai](https://admin.heylua.ai).
  </Step>

  <Step title="Open your agent">
    Click **Agents** in the main side navigation, then select your agent's card.
  </Step>

  <Step title="Add a channel">
    Click the **+** (plus) icon to add a channel, then choose **WhatsApp**.

    <Frame>
      <img src="https://mintcdn.com/luaglobal/5airD3u2P6mv3Ovl/images/channels/admin-add-channel.png?fit=max&auto=format&n=5airD3u2P6mv3Ovl&q=85&s=ab13d8f9a731bc706b9e112cf4226701" alt="Add a channel" width="3016" height="1576" data-path="images/channels/admin-add-channel.png" />
    </Frame>

    *Screenshot: The agent's add-channel (+) control and the WhatsApp option*
  </Step>

  <Step title="Accept terms & connect">
    Tick the box to accept the **Terms of Service** and **Privacy Policy**, then click **Connect**.
  </Step>

  <Step title="Log in with Facebook">
    A Meta **Embedded Signup** popup opens. Log in with your Facebook details and continue the Facebook workflow — select or create your Business account, WhatsApp Business Account, and phone number. Meta handles verification and webhook setup for you.

    <Note>
      This popup is Meta's own UI and changes periodically. See Meta's [Embedded Signup overview](https://developers.facebook.com/docs/whatsapp/embedded-signup) if you get stuck.
    </Note>
  </Step>

  <Step title="Connection success">
    When signup completes, you'll see a **"WhatsApp channel connected"** confirmation and WhatsApp appears in your connected channels.
  </Step>
</Steps>

## Testing Your WhatsApp Channel

<Steps>
  <Step title="Send Test Message">
    From your phone, send WhatsApp message to your business number

    ```
    You: Hi!
    ```
  </Step>

  <Step title="Agent Responds">
    Your agent should respond automatically

    ```
    Agent: Hello! How can I help you today?
    ```
  </Step>

  <Step title="Monitor in Admin">
    View conversation in admin dashboard

    <Frame>
      <img src="https://mintcdn.com/luaglobal/5airD3u2P6mv3Ovl/images/channels/admin-whatsapp-conversation.png?fit=max&auto=format&n=5airD3u2P6mv3Ovl&q=85&s=463be1ac296e32a5105b8210e01d25bf" alt="WhatsApp conversation" width="3018" height="1570" data-path="images/channels/admin-whatsapp-conversation.png" />
    </Frame>

    *Screenshot: Real-time conversation view*
  </Step>
</Steps>

## Message Status Events

When you send messages via WhatsApp (including template messages), Meta sends status updates back to Lua as messages progress through delivery. Lua captures these events and can forward them to your webhooks.

### Status Lifecycle

A typical message goes through these statuses:

```
sent → delivered → read
```

| Status      | Meaning                                                 |
| ----------- | ------------------------------------------------------- |
| `sent`      | Message accepted by WhatsApp servers                    |
| `delivered` | Message delivered to recipient's device                 |
| `read`      | Recipient opened and read the message                   |
| `failed`    | Message could not be delivered (includes error details) |
| `played`    | Recipient played a voice or video message               |

### Tracking Delivery with Webhooks

To receive these events in your code, subscribe a webhook to the event types you need:

```bash theme={null}
lua webhooks subscribe --webhook-name my-tracker --event message.sent
lua webhooks subscribe --webhook-name my-tracker --event message.delivered
lua webhooks subscribe --webhook-name my-tracker --event message.read
lua webhooks subscribe --webhook-name my-tracker --event message.failed
```

Your webhook receives the full status payload including the message ID, recipient, timestamp, conversation context, and pricing information. See the [Webhooks API Reference](/api/luawebhook#event-subscriptions) for the complete payload shape.

<Note>
  Status events are particularly useful when sending template messages via the [Templates API](/api/templates). After sending a campaign, subscribe to `message.delivered` and `message.read` to measure engagement, or `message.failed` to catch delivery issues.
</Note>

### Prerequisites

For status events to flow through, make sure you've subscribed to `messages` **and** `message_status` in your Meta webhook configuration (see [Configure Webhook in Meta](#configure-webhook-in-meta) above).

## Status & Quality

### Connection Status

* 🟢 **CONNECTED** - Working normally
* 🔴 **DISCONNECTED** - Needs reconnection
* 🟡 **PENDING** - Setup in progress

### Quality Rating

Meta assigns quality ratings based on user feedback:

* 🟢 **GREEN** - High quality (good!)
* 🟡 **YELLOW** - Medium quality (watch carefully)
* 🔴 **RED** - Low quality (take action)

<Warning>
  Low quality ratings can result in rate limiting or account restrictions. Monitor quality in admin dashboard.
</Warning>

## Best Practices

<AccordionGroup>
  <Accordion title="Response Time">
    * Respond within 24 hours
    * Quick responses improve quality rating
    * Agent handles this automatically
  </Accordion>

  <Accordion title="Message Templates">
    * Use templates for notifications
    * Required for messages after 24 hours
    * Set up in Meta Business Suite
  </Accordion>

  <Accordion title="Opt-In Required">
    * Users must message you first
    * Cannot send unsolicited messages
    * Respect user privacy
  </Accordion>

  <Accordion title="Monitor Quality">
    ```bash theme={null}
    lua admin
    # Check quality rating regularly
    # Address any user complaints promptly
    ```
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Channel shows DISCONNECTED">
    **Causes:**

    * Token expired
    * WABA disabled
    * Phone number removed

    **Solution:**

    1. Regenerate access token
    2. Update in admin dashboard
    3. Verify WABA is active
  </Accordion>

  <Accordion title="Messages not delivering">
    **Check:**

    * Quality rating (RED = issues)
    * Webhook configured correctly
    * Phone number status in Meta
    * Message templates approved
  </Accordion>

  <Accordion title="Quality rating dropped">
    **Actions:**

    1. Review recent conversations
    2. Check user feedback in Meta
    3. Improve agent responses
    4. Address user complaints
    5. May need to adjust persona
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Facebook Messenger" icon="facebook" href="/channels/facebook-messenger">
    Connect another channel
  </Card>

  <Card title="Test Your Agent" icon="comments" href="/cli/chat-command">
    Test agent behavior
  </Card>

  <Card title="Monitor Channels" icon="chart-line" href="/channels/admin-dashboard">
    View channel analytics
  </Card>

  <Card title="CLI Command Reference" icon="terminal" href="/cli/channels-command">
    Complete CLI guide
  </Card>
</CardGroup>