> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zavu.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# WhatsApp Business App Connection

> Use your existing WhatsApp Business App phone number with Cloud API

Connect your existing WhatsApp Business App to Zavu and use the same phone number for both personal conversations (via the app) and automated messaging (via Cloud API).

## What is WhatsApp Business App Connection?

When you connect an existing WhatsApp Business App account, you enable **coexistence mode** - the ability to use a single phone number across two platforms:

| Platform                  | Use Case                                              |
| ------------------------- | ----------------------------------------------------- |
| **WhatsApp Business App** | Personal conversations, 1:1 messaging from your phone |
| **Cloud API (via Zavu)**  | Automated messages, broadcasts, integrations          |

<Info>
  This is different from a standard Cloud API registration where the number can only be used via API. With coexistence, you keep using the WhatsApp Business App on your phone while also sending messages programmatically through Zavu.
</Info>

## Benefits

* **Keep using your phone**: Continue managing conversations directly from the WhatsApp Business App
* **Add automation**: Send automated messages, templates, and broadcasts through Zavu
* **Unified inbox**: All conversations appear in both the app and Zavu
* **No number migration**: Use your existing business number without changes

## Limitations

Before enabling coexistence, be aware of these limitations:

| Limitation                | Details                                                                 |
| ------------------------- | ----------------------------------------------------------------------- |
| **Throughput**            | Fixed at 80 messages per second (vs up to 1000 for dedicated Cloud API) |
| **Countries**             | Not available in Nigeria and South Africa                               |
| **Companion devices**     | Maximum 4 linked devices                                                |
| **Message features**      | Edit and revoke messages disabled in the app                            |
| **Disappearing messages** | Not supported                                                           |

## Connecting via Dashboard

### Step 1: Navigate to Senders

1. Log in to your [Zavu Dashboard](https://dashboard.zavu.dev)
2. Go to **Senders** in the navigation
3. Click **New Sender** or edit an existing sender

### Step 2: Connect WhatsApp

1. In the Channels section, click **Configure** on WhatsApp
2. Select **Connect WhatsApp Business App**

<Tip>
  Choose this option if you're already using WhatsApp Business App and want to keep using it alongside Cloud API.
</Tip>

### Step 3: Complete Meta Signup

1. Click **Connect with Meta** to open the embedded signup
2. Log in with your Facebook account that has access to the WhatsApp Business App
3. Select your existing WhatsApp Business Account
4. Authorize Zavu to send messages on your behalf

### Step 4: Sync Message History (Optional)

After connecting, you can optionally sync your existing conversation history:

1. On the success screen, click **Sync history**
2. This sends a request to the account owner to approve sharing
3. Once approved, historical messages will be imported to Zavu

<Warning>
  History sync requires approval from the WhatsApp Business App user. They will see a prompt in the app to share their conversation history.
</Warning>

## Connection Options Comparison

When connecting WhatsApp to a sender, you have three options:

<CardGroup cols={3}>
  <Card title="Zavu Phone Number" icon="phone">
    Use a phone number from your Zavu account. Best for dedicated business lines with high volume messaging.
  </Card>

  <Card title="WhatsApp Business App" icon="mobile">
    Connect your existing WhatsApp Business App. Best for keeping personal messaging alongside automation.
  </Card>

  <Card title="Own Phone Number" icon="sim-card">
    Register any phone number you own. Best for using your own carrier number dedicated to Cloud API.
  </Card>
</CardGroup>

## Managing History Sync

After connecting, you can manage synchronization from the sender settings:

### Sync Status

| Status         | Description                    |
| -------------- | ------------------------------ |
| **Not synced** | History sync not requested     |
| **Syncing**    | Sync in progress               |
| **Synced**     | History imported successfully  |
| **Declined**   | User declined to share history |

### Requesting Sync

1. Go to **Senders** → Select your sender
2. Navigate to the **Channels** tab
3. In the WhatsApp Business App Sync section, click **Sync** for:
   * **Message History**: Import existing conversations
   * **Contacts**: Import contact names from the app

## Sync via API

You can also manage history and contacts sync programmatically using the REST API.

### Get Sync Status

Check the current sync status for a sender:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET https://api.zavu.dev/v1/senders/{senderId}/whatsapp-sync \
    -H "Authorization: Bearer $ZAVU_API_KEY"
  ```

  ```typescript TypeScript theme={null}
  const response = await fetch(
    `https://api.zavu.dev/v1/senders/${senderId}/whatsapp-sync`,
    {
      headers: { Authorization: `Bearer ${apiKey}` }
    }
  );
  const { sync } = await response.json();
  console.log(sync.history.status); // "not_requested" | "pending" | "syncing" | "completed" | "rejected"
  console.log(sync.contacts.canSync); // true if sync can be initiated
  ```

  ```ruby Ruby theme={null}
  response = client.senders.get_whatsapp_sync(sender_id)
  puts response.sync.history.status
  puts response.sync.contacts.can_sync
  ```

  ```go Go theme={null}
  response, err := client.Senders.GetWhatsAppSync(context.TODO(), senderID)
  fmt.Println(response.Sync.History.Status)
  fmt.Println(response.Sync.Contacts.CanSync)
  ```

  ```php PHP theme={null}
  $response = $client->senders->getWhatsAppSync($senderId);
  echo $response->sync->history->status . "\n";
  echo $response->sync->contacts->canSync . "\n";
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "sync": {
    "isCoexistence": true,
    "status": "active",
    "history": {
      "status": "completed",
      "canSync": false,
      "requestedAt": "2024-01-15T10:00:00Z",
      "completedAt": "2024-01-15T10:05:00Z"
    },
    "contacts": {
      "status": "not_requested",
      "canSync": true,
      "requestedAt": null
    }
  }
}
```

### Start History Sync

Initiate message history sync from the WhatsApp Business App:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.zavu.dev/v1/senders/{senderId}/whatsapp-sync/history \
    -H "Authorization: Bearer $ZAVU_API_KEY"
  ```

  ```typescript TypeScript theme={null}
  const response = await fetch(
    `https://api.zavu.dev/v1/senders/${senderId}/whatsapp-sync/history`,
    {
      method: 'POST',
      headers: { Authorization: `Bearer ${apiKey}` }
    }
  );
  // Returns 202 Accepted
  ```

  ```ruby Ruby theme={null}
  client.senders.start_whatsapp_history_sync(sender_id)
  ```

  ```go Go theme={null}
  response, err := client.Senders.StartWhatsAppHistorySync(context.TODO(), senderID)
  ```

  ```php PHP theme={null}
  $client->senders->startWhatsAppHistorySync($senderId);
  ```
</CodeGroup>

<Info>
  History sync requires approval from the WhatsApp Business App user. After calling this endpoint, the user will see a prompt in their app to approve sharing their conversation history.
</Info>

### Start Contacts Sync

Import contact names from the WhatsApp Business App:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.zavu.dev/v1/senders/{senderId}/whatsapp-sync/contacts \
    -H "Authorization: Bearer $ZAVU_API_KEY"
  ```

  ```typescript TypeScript theme={null}
  const response = await fetch(
    `https://api.zavu.dev/v1/senders/${senderId}/whatsapp-sync/contacts`,
    {
      method: 'POST',
      headers: { Authorization: `Bearer ${apiKey}` }
    }
  );
  // Returns 202 Accepted
  ```

  ```ruby Ruby theme={null}
  client.senders.start_whatsapp_contacts_sync(sender_id)
  ```

  ```go Go theme={null}
  response, err := client.Senders.StartWhatsAppContactsSync(context.TODO(), senderID)
  ```

  ```php PHP theme={null}
  $client->senders->startWhatsAppContactsSync($senderId);
  ```
</CodeGroup>

### Error Responses

| Error                                                        | Description                                  |
| ------------------------------------------------------------ | -------------------------------------------- |
| `Sender does not have a WhatsApp Business Account connected` | The sender has no WABA configured            |
| `Sync is only available for coexistence accounts`            | The WABA is not in coexistence mode          |
| `WhatsApp account is not active`                             | The WABA status is not active                |
| `History sync is already in progress`                        | A sync request is already pending or running |
| `Sync limit reached. Please wait 24 hours`                   | Meta rate limit exceeded                     |

## Receiving Messages

With coexistence enabled, messages arrive in both places:

1. **WhatsApp Business App**: The user sees and can reply from their phone
2. **Zavu Webhooks**: Your application receives `message.inbound` events

Messages sent from the WhatsApp Business App are also forwarded to your webhooks as `whatsapp.message_echo` events.

## Disconnecting

To disconnect the WhatsApp Business App:

<Warning>
  Disconnection can only be initiated from the WhatsApp Business App, not from Zavu or the API.
</Warning>

1. Open WhatsApp Business App on your phone
2. Go to **Settings** → **Linked Devices**
3. Remove the Zavu connection

When disconnected:

* The sender status changes to `disconnected` in Zavu
* You'll receive a `whatsapp.account_update` webhook event
* The sender can no longer send WhatsApp messages

## Troubleshooting

### Can't see the "Connect WhatsApp Business App" option

Make sure:

* You're using WhatsApp Business App (not regular WhatsApp)
* Your phone number is registered with WhatsApp Business
* You have admin access to the associated Facebook Business account

### History sync stuck in "Syncing"

* The account owner must approve the sync request in the WhatsApp Business App
* Check the app for any pending prompts
* Sync can take several minutes for large histories

### Messages not appearing in Zavu

* Verify the sender status is `active`
* Check webhook configuration is correct
* Ensure the `message.inbound` event is subscribed

## Next Steps

<CardGroup cols={2}>
  <Card title="Send Messages" icon="paper-plane" href="/guides/whatsapp/overview">
    Start sending WhatsApp messages through your connected account
  </Card>

  <Card title="Configure Webhooks" icon="webhook" href="/guides/receiving-messages/webhooks">
    Set up webhooks to receive inbound messages
  </Card>
</CardGroup>