> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vocily.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# WhatsApp integration
> Workspace setup for WhatsApp Business Accounts and numbers.
Vocily is an official Meta Tech Provider. The WhatsApp integration connects your
workspace to Meta's WhatsApp Business Platform using Meta's official setup paths:
Login by Facebook or Manual Provisioning.
You bring your own WhatsApp Business Account and phone numbers. You keep ownership of
the account, numbers, data, and Meta billing relationship; Vocily connects on top so
your workspace can use those Meta assets across agents, inbox workflows, templates,
and campaigns.
Vocily WhatsApp platform fees are separate from Meta's WhatsApp Business Platform
charges. See [WhatsApp pricing and charges](/whatsapp/pricing-charges).
## What the connection enables
After a WhatsApp Business Account is connected, your workspace can:
* Reply to inbound WhatsApp conversations.
* Assign WhatsApp numbers to agents.
* Create and sync WhatsApp message templates.
* Monitor conversations in the inbox.
* Send WhatsApp campaigns from approved templates.
WhatsApp is connected at the workspace level, then configured per agent in
[Deploy WhatsApp on an agent](/whatsapp/deploy-agents).
## Connect WhatsApp
Choose the connection path that matches how your Meta assets are managed:
Recommended for most workspaces. Sign in with Meta, choose the business, WhatsApp
Business Account, and number, and authorize Vocily through Meta's official
onboarding flow. No access token or Meta app setup is needed from your side.
Use this when your team already manages the Meta app and token. Paste the WABA ID,
Phone Number ID, and access token, then add Vocily's webhook details in Meta if you
want inbound replies and AI conversations.
After connection, Vocily shows the connected WhatsApp Business Account and its numbers.
## Login by Facebook
Use **Login by Facebook** when you want Meta to guide the setup in a secure popup.
Before you start, make sure you have:
* [Meta Business](https://business.facebook.com/latest) admin access.
* Access to the WhatsApp Business Account you want to connect, or permission to create
one during Meta's flow.
* A WhatsApp business phone number, or a new number you want to add during Meta's flow.
* A 6-digit two-step verification PIN if Meta asks you to register or re-register the
number.
If you add a new number during Meta's flow, save this PIN somewhere safe. You may
need the same PIN later if the number is registered again or moved between WhatsApp
setups.
Meta Business verification, WhatsApp account eligibility, phone-number registration,
payment methods, and any Meta billing requirements are managed in Meta by your
business. Vocily connects to the Meta assets you authorize, but those Meta-side
requirements remain under your ownership.
In Vocily:
1. Open **Integrations**.
2. Choose **WhatsApp**.
3. Select **Login by Facebook**.
4. Accept the WhatsApp Addendum + DPA shown in Vocily.
5. Enter the 6-digit registration PIN.
6. Continue with Meta and complete the popup. You can choose an existing WhatsApp
business number or add a new number during the Meta setup.
Meta returns the WhatsApp Business Account ID, Phone Number ID, and an exchangeable
token code to Vocily. Vocily exchanges that code server-side, registers the selected
phone number for Cloud API use, subscribes the account to Vocily's WhatsApp webhook,
and imports the selected number into the workspace.
You do not need to create your own Meta app for Login by Facebook. Vocily uses its
official Tech Provider connection and follows Meta's embedded signup flow for the
authorization, phone registration, and webhook subscription steps.
To learn more, see Meta's
[Embedded Signup overview](https://developers.facebook.com/documentation/business-messaging/whatsapp/embedded-signup/overview).
## Manual Provisioning
Use **Manual Provisioning** when your Meta setup needs to stay under your own app.
This path follows Meta's Cloud API setup: you provide the WABA ID, Phone Number ID, and
an access token with WhatsApp permissions.
Before you start, collect:
| Field | Where it comes from |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **WABA ID** | The WhatsApp Business Account ID shown in Meta's WhatsApp API setup or WhatsApp Manager. |
| **Phone Number ID** | The business phone number ID for the number Vocily should connect. Meta shows this in the WhatsApp API setup and phone-number details. |
| **Access Token** | A Meta access token that can read the WABA and send messages for the selected number. For a durable setup, generate a system-user token from Meta Business Settings. |
If you do not already have an access token, create one in Meta:
1. Open the [Meta App Dashboard](https://developers.facebook.com/apps) and create or use
an app with the WhatsApp use case.
2. Make sure the Meta app is published, business verification is complete, WhatsApp
account setup is ready, a payment method is added, and Meta billing requirements
are completed in Meta for your business.
3. In [Meta Business Settings](https://business.facebook.com/latest/settings), create
a **System user**.
4. Assign the app and the WhatsApp Business Account to that system user with the
required access.
5. Generate a token with the permissions Vocily checks for WhatsApp Cloud API access:
`whatsapp_business_management` and `whatsapp_business_messaging`. If Meta shows
`business_management` instead of `whatsapp_business_management`, Vocily accepts it
as the same management permission.
6. Copy the token and keep it secure.
For Manual Provisioning, your Meta app and WhatsApp setup remain customer-managed.
Please complete Meta's business verification, app publishing, payment method, and
billing setup inside Meta before relying on the connection in production. Vocily
helps connect and use the approved assets, but Meta-side approvals and payments are
handled by your business in Meta.
In Vocily:
1. Open **Integrations**.
2. Choose **WhatsApp**.
3. Select **Manual Provisioning**.
4. Accept the WhatsApp Addendum + DPA shown in Vocily.
5. Enter the **WABA ID**, **Phone Number ID**, and **Access Token**. The access token is
the same system-user token you created in Meta above.
6. Select **Connect & get webhook**.
Vocily validates the token, checks that the selected phone number belongs to the WABA,
imports that number, and returns a **Callback URL** and **Verify token** for the
workspace.
## Set up the Meta webhook
Webhook setup is required when you want inbound customer messages, AI replies, team
replies, and delivery statuses to reach Vocily.
Login by Facebook configures this through Vocily's Tech Provider app. Manual
Provisioning requires you to paste the webhook details into your own Meta app.
For Manual Provisioning:
1. Copy the **Callback URL** and **Verify token** shown by Vocily after connection.
2. In the [Meta App Dashboard](https://developers.facebook.com/apps), open your app.
3. Open **Use cases**.
4. Find **Connect with customers through WhatsApp** and select **Customize**.
5. Open **Step 2. Production Setup**.
6. Select **Configure Webhooks**.
7. Paste the callback URL and verify token from Vocily.
8. Select **Save and verify**.
9. After Meta verifies the webhook, subscribe these webhook fields:
| Field | How Vocily uses it |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `messages` | Core field for WhatsApp conversations. Vocily uses it for inbound customer messages, media messages, reactions, and outbound delivery statuses such as sent, delivered, read, failed, or deleted. |
| `account_update` | Account-level status changes for the connected WhatsApp Business Account. Vocily subscribes to this so workspace status can stay aligned with Meta account changes. |
| `phone_number_quality_update` | Phone-number quality and messaging-limit updates. Vocily subscribes to this so number health can stay aligned with Meta. |
| `message_template_status_update` | Template approval, rejection, pause, disable, reinstate, and related template status updates. Vocily applies these updates to the local template list. |
| `message_template_quality_update` | Template quality-score changes. Vocily applies these updates to the local template list. |
| `template_category_update` | Template category changes from Meta. Vocily applies the updated category to the local template list. |
| `message_template_components_update` | Template component changes. Vocily marks the template for re-sync because Meta does not send the full component body in this webhook. |
| `account_alerts` | Account-level alerts for the connected WhatsApp Business Account. Vocily subscribes to this as part of the account-health event set. |
Use the version Meta shows in the field selector, such as `v25.0`.
You can compare these fields with Meta's
[WhatsApp Business Account webhook reference](https://developers.facebook.com/docs/graph-api/webhooks/reference/whatsapp_business_account/).
Vocily uses one stable webhook URL and verify token per workspace for Manual
Provisioning. If you connect more WhatsApp Business Accounts later, reuse the same
workspace webhook details instead of creating a new callback for each number.
If you only plan to send outbound WhatsApp campaigns and do not need inbound replies
or agent conversations, you can connect Manual Provisioning without completing the
webhook step. To receive replies or run WhatsApp agents, complete the webhook setup.
## What's next
* Learn the WhatsApp workspace flow in [WhatsApp overview](/whatsapp/overview).
* Assign an agent from [Deploy WhatsApp on an agent](/whatsapp/deploy-agents).
* Build outbound sends in [WhatsApp Campaigns](/whatsapp/campaigns).
