Connect a WhatsApp Client
Create a client, scan the WhatsApp QR code, and verify worker health
A client represents one connected WhatsApp account. WP Engine starts a dedicated worker for each client, stores auth state in Redis, and uses the worker to send and receive messages.
Before you start
Confirm these services are reachable from the server app:
| Service | Used for |
|---|---|
| PostgreSQL | Client ownership, flows, auth, run history |
| MongoDB | WhatsApp chats, contacts, and messages |
| Redis | WhatsApp auth state, QR polling, worker cache |
| Event Redis | Raw WhatsApp event queue for flow execution |
Create the client
- Open
/clientsin the dashboard. - Click the create action.
- Enter a name that identifies the number or team, such as
Sales Inbox. - Continue to start the worker.
The dashboard asks the server to create the client and start the matching worker. Worker desired state is stored with the client, so container boot can reconcile workers that should be running.
Scan the QR code
When the QR dialog opens:
- Open WhatsApp on your phone.
- Go to Linked devices.
- Scan the QR code shown in the dashboard.
- Keep the dialog open until the dashboard reports the connection.
QR values are short-lived. If the QR expires, close the dialog and restart the worker from the row action menu.
Understand statuses
| Status | Meaning | Next action |
|---|---|---|
| Awaiting QR | Worker is waiting for WhatsApp pairing | Scan the QR code |
| Connected | Worker is authenticated and ready | Publish flows or send messages |
| Stopped | Worker is not running | Start or restart from the dashboard |
| Error | Worker failed or disconnected unexpectedly | Check server logs, then restart |
Verify the connection
After the client is connected:
- Open
/contacts/[clientId]from the Clients row menu. - Fetch or inspect contacts if available.
- Send a test WhatsApp message to the connected number from another account.
- Check the flow runs page after publishing a matching flow.
Incoming group, broadcast, and newsletter messages are ignored by the event ingestion layer. Test with a direct one-to-one chat.
Safe operations
| Action | Use when |
|---|---|
| Restart | The worker is stuck, QR expired, or connection state looks stale |
| Stop | You want to pause automation without deleting the client |
| Rename | The dashboard label is unclear |
| Delete | The client should be removed from the dashboard |
Deleting a client is destructive for dashboard ownership and related records. Stop the worker first if you need a clean shutdown window.
Troubleshooting
QR code stays on loading
Check WP_ENGINE_API_URL, WP_ENGINE_API_KEY, REDIS_URL, and server logs. The web app must be able to call the server, and the server must be able to store QR state in Redis.
WhatsApp says the QR is invalid
Restart the worker and scan the newest QR. Do not reuse screenshots of old QR codes.
Client disconnects after a deploy
Check whether the worker process restarted and whether Redis auth state is persistent. If auth state was lost, reconnect by scanning a new QR code.