Skip to main content
Enable your agent to receive and respond to messages on WhatsApp. Users message your agent’s dedicated WhatsApp number, and replies are powered by your agent’s knowledge base, prompt, and AI model.

​
What You Need

  • A WAHA Plus account (self-hosted server set up by your organization)
  • An active agent (draft or published)
  • A WhatsApp Business Account (optional, for best practices, but not required for web protocol operation)

​
Connecting Your Agent to WhatsApp

​
Step 1: Navigate to Channels

  1. Open your agent’s dashboard.
  2. Click the Channels tab.
  3. Locate the WhatsApp card.

​
Step 2: Pair Your WhatsApp Number

  1. Click Connect.
  2. A QR code appears on your screen.
  3. Open WhatsApp on your phone.
  4. Go to Settings → Linked Devices (or WhatsApp Web).
  5. Tap the + icon to scan a QR code.
  6. Point your phone’s camera at the QR code on your screen.
  7. Authorize the pairing when prompted.
The status will change to Connected once your number is linked. Your phone will remain connected to receive messages.
The QR code refreshes every ~20 seconds if you’re still in the connection flow. If your phone loses internet, WhatsApp Web will disconnect; reconnect by rescanning.

​
Step 3: Verify It’s Working

Send a message to your WhatsApp number from any contact. Your agent should reply within a few seconds.

​
Status States

​
Behavior Settings

​
Citation Style

Choose how your agent references sources from your knowledge base:
  • Footer (default) — Citations appear as numbered markers [1], [2] in the text, with a “Sources:” section listing each document at the end of the message.
  • Strip — Citation markers are removed; sources are not shown.
This setting applies only to WhatsApp. Web channel citations are unaffected.

​
Linked Tools

The WhatsApp channel respects your agent’s tool configuration. If you’ve enabled these tools, WhatsApp users will be able to:
  • File Uploads — Upload images and documents in the chat. Disable this if you don’t want to process attachments.
  • Voice Input — Send voice messages (voice notes). Your agent will transcribe them using the configured transcription model. Disable if voice is not needed.
To enable or change these tools, visit your agent’s Tools tab and toggle the respective tools on or off. WhatsApp users will see a helpful decline message if they try to use a disabled tool.

​
How It Works

​
Inbound Messages

When someone messages your WhatsApp number:
  1. The message is received by the WAHA server.
  2. Your agent processes the message using its knowledge base, prompt, and AI model (same as web chat).
  3. Citations, product cards, and formatting are adapted for WhatsApp.
  4. The reply is sent back within seconds.

​
Support for Media

  • Images & Documents — If file uploads are enabled, attachments are downloaded and processed. Otherwise, a polite decline is sent, but any text caption is still processed.
  • Voice Notes — If voice input is enabled, audio is transcribed and processed as text. Otherwise, a decline message is sent.
  • Reactions & Edits — Not supported; these are silently ignored.

​
Group Chats

WhatsApp group chats are not supported. Only 1:1 messages to your agent’s number are processed. When your agent replies using knowledge-base sources, citations appear as:
Only documents with public URLs show the link. If citation style is set to Strip, no footer appears.

​
Product Cards

If your agent recommends products, images and details are formatted as WhatsApp-compatible cards, with up to 3 cards per reply.

​
Per-Message Fees

Your plan or organization may have per-message fees configured for WhatsApp. These fees are applied:
  • Incoming message fee — Charged when a user sends you a message (after processing begins, not if credits run out).
  • Reply fee — Charged when your agent sends a response.
Fees appear in your credit ledger as “WhatsApp message in” and “WhatsApp reply out.” See your billing dashboard for details.
If your organization runs out of credits, incoming messages will receive a brief unavailable message, and no fees are charged.

​
Disconnecting

To disconnect your WhatsApp number:
  1. Open the Channels tab.
  2. Click Disconnect.
  3. Confirm the action.
Your agent will no longer receive WhatsApp messages. The connection history is retained for reference.

​
Limitations

  • Inbound-first — Your agent cannot initiate conversations; users must message you first.
  • 1:1 only — Group chats, broadcasts, and channel messages are not supported.
  • No proactive messaging — You cannot schedule or send unsolicited messages to users.
  • No message templates — Promotional templates or auto-responses must come from your agent’s reply logic.

​
Troubleshooting

​
”QR Code Invalid” or “Scan Failed”

  • Make sure the QR code is fully visible and well-lit.
  • Refresh the page if the error persists; the QR code will regenerate.
  • Ensure your phone has a stable internet connection before scanning.

​
No Response to Messages

  • Verify the agent is published or in draft mode (either allows chat).
  • Check the agent’s knowledge base is indexed and linked.
  • Ensure your organization has available credits.
  • Confirm WhatsApp Web is still connected on your phone (check Settings → Linked Devices).

​
Slow Replies

  • Large knowledge bases or complex prompts may take a few seconds to generate a response.
  • Voice transcription adds 1-2 seconds per audio message.
  • Check your organization’s credit balance; low credits may trigger rate limiting.

​
Agent Offline or Disconnected

  • WhatsApp Web requires your phone to remain connected to the internet. If your phone goes offline, reconnect it by opening WhatsApp and going to Settings → Linked Devices.
  • If you logged out of WhatsApp, you’ll need to re-pair by scanning the QR code again.

​
Conversation History

All WhatsApp conversations appear in your agent’s Conversations view with a WhatsApp badge. You can:
  • Review chat history
  • See which messages were sources (citations)
  • Escalate to a human operator via the HITL system
  • Export or archive conversations (future feature)

​
Next Steps

  • Review your agent’s Tools to enable or disable file uploads and voice input.
  • Configure the Citation Style (footer or strip) to match your preferences.
  • Test with a real WhatsApp message to verify the connection works.
  • Set up Human-in-the-Loop if you want operators to take over conversations when needed.