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

# Connect a Voiceflow agent to WhatsApp

> Connect WhatsApp to a Voiceflow text agent. Configure the platform, host the relay, test replies and prepare release.

## Overview

Answer customer-initiated WhatsApp messages with a Voiceflow agent through Meta’s Cloud API. You host the relay; Meta delivers incoming events and sends its text replies from your business number.

<a id="before-you-begin"></a>

## Before you begin

Collect the agent, account and host access.

| Requirement | Obtain before installation |
| --- | --- |
| Voiceflow owner | An existing agent with a known support answer, a private project API key, project ID and reviewed Environment alias. [Build the agent](/docs/documentation/build/overview) first, then [publish the intended release](/docs/documentation/deploy/environments/publishing). |
| Meta business assets | A business portfolio, WhatsApp Business Account and business phone number ID. Use Meta’s test sender and registered test recipient first. |
| Permissions | A system user token assigned to the business assets with `whatsapp_business_messaging`; account administration also needs `whatsapp_business_management`. |
| Relay operator | A Node.js host, public HTTPS hostname, private secrets and persistent disk; an operator who can investigate paused conversations. |

The example provides public-policy text support. Keep private Voiceflow and platform credentials on the host; a customer’s messaging identity does not authorize access to orders or account records. Have the agent return text only and provide a support route in its instructions. Buttons, audio and Handoff traces need additional adapters; see [Adapt agent replies](/docs/guides/channels/messaging/adapt-agent-replies).

<a id="create-platform-app"></a>

## Prepare the platform account

Create the exact app or account this relay will use.

### 1. Create the WhatsApp app

In [Meta for Developers](https://developers.facebook.com/apps), create a business app with the **Connect with customers through WhatsApp** use case. In its WhatsApp setup, select your business portfolio and obtain the test phone number ID, WhatsApp Business Account ID and test access token. Add and verify your own test recipient. A business phone number ID is an API identifier, distinct from the displayed telephone number.

### 2. Prepare production credentials

For production, add your business number, verify ownership, complete its registration and display-name review, and configure billing where required. Assign the WhatsApp assets to a business system user and generate its token with messaging permission. Put this token in `META_ACCESS_TOKEN`; short-lived dashboard tokens are suitable only for the initial test. Record its expiry and rotation owner.

Businesses integrating their own assets and partners onboarding other businesses have different review requirements. Partners need Advanced Access through App Review; follow Meta’s [webhook access requirements](https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/overview), including any business verification requested for your account.

<a id="run-relay"></a>

## Run the relay

Configure and host the supplied executable example.

Use the [configuration file](/docs/examples/messaging/whatsapp.env.example) for this platform. Every name below is read by the supplied artifact; IDs identify the resources prepared above. `VF_ENVIRONMENT` is the Environment alias, not a version label pasted from another project.

```dotenv
VF_API_KEY=YOUR_PRIVATE_VOICEFLOW_PROJECT_KEY
VF_PROJECT_ID=YOUR_VOICEFLOW_PROJECT_ID
VF_ENVIRONMENT=YOUR_ENVIRONMENT_ALIAS
DATA_DIR=/var/lib/voiceflow-messaging
PORT=8080
PLATFORM=whatsapp
META_APP_SECRET=YOUR_META_APP_SECRET
META_VERIFY_TOKEN=YOUR_RANDOM_VERIFY_TOKEN
META_ACCESS_TOKEN=YOUR_SYSTEM_USER_TOKEN
META_ACCOUNT_ID=YOUR_PHONE_NUMBER_ID
META_GRAPH_VERSION=v27.0
```

### 1. Download and configure the relay

On a Linux host you administer, create `/opt/voiceflow-messaging` and extract the [relay archive](/docs/examples/messaging/messaging-relay.zip) there. Use Node.js 22.12 or later. Run `node --test fixtures.test.mjs` first: it generates signed synthetic events and mocks all remote calls, without credentials or live messages. Save the configuration above as `.env`, replacing every `YOUR_` value; restrict it to the service account with `chmod 600 .env`. Set `DATA_DIR` to a private persistent directory that this account can write.

The archive includes `core.mjs`, platform adapters, HTTP/Teams entry points, local fixture tests and a package manifest. Run `node --env-file=.env relay.mjs serve`. The HTTP relay uses only Node built-ins; it does not need `npm install`.

### 2. Expose the HTTPS endpoint

Point your own DNS hostname to the host. Terminate HTTPS with a valid public certificate and proxy to `127.0.0.1:8080`. For example, with [Caddy](https://caddyserver.com/docs/quick-starts/reverse-proxy) installed:

```sh
caddy reverse-proxy --from support.example.com --to 127.0.0.1:8080
```

Replace the example hostname, allow inbound 80/443 for certificate provisioning and keep the relay port private. Use a separate hostname and credentials for testing. Confirm `https://YOUR_HOST/health` returns `ok` before registering `/webhook`.

### 3. Keep one process running

After the foreground check, stop it and create a service using the unit below. Keep one process and one writable data directory per installation. Do not run this file store on ephemeral serverless storage or start multiple replicas.

```ini
# /etc/systemd/system/voiceflow-messaging.service
[Unit]
Description=Voiceflow messaging relay
After=network-online.target

[Service]
User=relay
WorkingDirectory=/opt/voiceflow-messaging
ExecStart=/usr/bin/node --env-file=.env relay.mjs serve
Restart=on-failure
UMask=0077

[Install]
WantedBy=multi-user.target
```

Create the non-login `relay` service user, give it read access to the application and `.env`, and ownership of `/var/lib/voiceflow-messaging`. Confirm `/usr/bin/node --version` is 22.12 or later, or substitute your actual Node path. Then run `sudo systemctl daemon-reload` and `sudo systemctl enable --now voiceflow-messaging`. Expect the service to stay active; keep the HTTPS proxy running through its own service.

The file store is a small single-process starting point. Back it up privately and monitor disk space, queue age and failures. Higher traffic needs a transactional inbox/outbox and per-conversation workers before adding replicas. Session keys and customer text are stored in the data directory; apply your retention and access policy there as well as in Voiceflow.

<a id="register-events"></a>

## Register incoming events

Connect the platform to your hosted endpoint.

In the app’s **WhatsApp → Configuration**, or **Use cases → Customize → Configuration**, enter your relay’s `https://YOUR_HOST/webhook` and the exact `META_VERIFY_TOKEN`. Choose **Verify and save**, then subscribe to the **messages** webhook field. The GET challenge proves endpoint ownership; POST events are separately checked with `X-Hub-Signature-256` and the app secret.

Subscribe the app to your WhatsApp Business Account as well. Save this as `subscribe.mjs` beside the relay and run it with `node --env-file=.env subscribe.mjs`, after setting `WHATSAPP_WABA_ID` in `.env`:

```js
import { request } from './core.mjs';
const e = process.env;
console.log(await request(
  `https://graph.facebook.com/${e.META_GRAPH_VERSION}/${e.WHATSAPP_WABA_ID}/subscribed_apps`,
  { headers: { Authorization: `Bearer ${e.META_ACCESS_TOKEN}` }, body: {} }
));
```

Expect `success: true` and a verified callback. A dashboard sample event alone does not prove that the selected business number is subscribed. See [Meta’s webhook setup](https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/create-webhook-endpoint).

<a id="conversation-routing"></a>

## Route conversations and replies

Keep the customer, agent session and reply destination aligned.

| Stage | Mapping in the example |
| --- | --- |
| Customer identity | `messages[].from_user_id` (BSUID), falling back to `from` only when absent; scope it to the destination phone number ID. |
| Incoming text | `entry[].changes[].value.messages[].text.body` with `type: text`. |
| Visible reply | POST `/{phone-number-id}/messages`; use `recipient` for a BSUID and `to` for a phone number. |
| Duplicate and status | Deduplicate `messages[].id`; store status notifications without calling the agent. |

The relay hashes platform, destination account, customer/thread, project and Environment into a bounded Voiceflow `userID`. It creates a session with the private project key, stores the returned `sessionKey`, launches once, then sends `{ action: { type: "text", payload: text } }` to `/v4/interact`. Text traces become platform replies. Follow-ups reuse the key; starting a session every message would reset the conversation.

Free-form service replies must remain within the [24-hour customer service window](https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/send-messages). The relay computes its deadline from the inbound message timestamp. It does not send approved templates or reopen expired windows.

Meta’s current [BSUID contract](https://developers.facebook.com/documentation/business-messaging/whatsapp/business-scoped-user-ids) allows phone fields to be absent. The example preserves the full BSUID and uses the separate `recipient` field when replying. Changing from a historical phone-based mapping can start fresh memory; reconcile any existing mappings before migration. It does not merge people by display name.

Webhook failures can be retried for up to seven days. A message accepted by the send API can still fail later; inspect `statuses[].status` and error codes in the private receipt log. Text messages support 4096 characters; this relay sends smaller 1000-character chunks.

<a id="test-conversation"></a>

## Test a customer conversation

Verify the reply in the destination you installed.

### 1. Send a real platform message

From the registered test recipient, message the business test number with your prepared support question. Expect an answer from that number in WhatsApp.

### 2. Check continuity and isolation

Ask a related follow-up, then test with a second authorized customer. Confirm the intended Voiceflow project and exchange in [Transcripts](/docs/documentation/measure/transcripts). Run `node --env-file=.env relay.mjs inspect` while the service is stopped to compare event IDs, conversation keys and completion states without printing session tokens.

### 3. Check this platform’s delivery behavior

Test a signed fixture with `from_user_id` and no `from`: it must produce a `recipient` reply. With an authorized username-enabled test customer, repeat that check through Meta before launch.

A saved callback, accepted API request or successful Voiceflow Run does not prove this platform conversation. Keep local signed-fixture tests separate from this authenticated customer test.

<a id="troubleshooting" />

### The callback saves but no reply arrives

Check platform access as well as endpoint connectivity.

Check the number’s registration, the system user’s asset assignment, token expiry, business account subscription and the open service window. Inspect failed status codes after an accepted send.

### A conversation is paused or a reply is duplicated

Reconcile remote effects before resuming the saved job.

Inspect the event’s `phase`, `failedDuring`, saved traces and accepted chunks in the private data file. A runtime timeout can occur after a tool action; a send timeout can occur after the platform accepted the message. The sample pauses that conversation and does not retry either effect automatically. Follow [Recover failed messages](/docs/guides/channels/messaging/recover-failed-messages), then repeat the platform test.

<a id="go-live"></a>

## Release and maintain the connection

Promote the tested route and keep recovery available.

### 1. Approve the production destination

Complete the production number’s registration, account checks and billing. Use the production phone number ID and system token; repeat the customer test with an authorized recipient after any required app review. Publishing a Voiceflow agent does not register a WhatsApp sender.

### 2. Release the reviewed agent

Have the Voiceflow owner publish the tested agent to the intended Environment. Deploy that alias and production credentials to the relay, restart its service and repeat the [customer test](#test-conversation) with a fresh customer/session. Existing session keys are not an automatic migration to a new release. Keep the previous deployment and state backup available for rollback.

### Rotate, update or disconnect

Maintain both the provider registration and the relay state.

Stop the service before changing `.env` or running maintenance commands. Rotate the platform credentials using its administrator controls, update the secret file and restart. If a webhook secret changes, update both sides and check a real event. For a release change, drain or reconcile pending jobs first; do not erase the state file to resolve a delivery problem.

To disconnect, disable/remove this callback or uninstall this app in the provider, stop the relay and revoke its unused credentials. Confirm no new events arrive and retain/delete customer state according to your policy. Keep the registration details needed to reconnect. See [Pause automated replies](/docs/guides/channels/messaging/pause-automated-replies) for a temporary conversation-specific pause.
