Connect WhatsApp

Buda connects to WhatsApp via QR code pairing using the Baileys library — the same approach used by WhatsApp Web. This means you do not need a Meta Business account, a phone number API, or any paid subscription. Simply scan a QR code with your phone and Buda will maintain the connection in the background.

Two accounts required: You need one WhatsApp account to act as the bot (Account A, linked to Buda) and a separate account to send messages to it (Account B). WhatsApp filters out messages sent from an account to itself.

Step 1: Add the WhatsApp Channel in Buda

1. Open Channels Settings in Buda (Settings → Channels).
2. Click Add Channel and select WhatsApp.
3. Optionally set a Label (e.g., My WhatsApp Bot) and select a Target Agent.
4. Click Connect — a QR code will appear on screen.

Step 2: Scan the QR Code

1. On your phone (Account A), open WhatsApp.
2. Go to Settings → Linked Devices → Link a Device.
3. Point your camera at the QR code displayed in Buda.
4. Once scanned, the status will change to Active and the QR code will disappear.

You will see the following in the server logs:

[whatsapp] Connection open for channel <id>

Step 3: Start Chatting

• Direct message: From Account B, send a message directly to Account A's phone number. Buda will receive it and reply via the configured agent.
• Group chat: Add Account A to a WhatsApp group. Any message sent in the group will be processed by Buda — no @mention is needed.

Notes

• No HTTPS required: QR pairing works entirely in local development without any public URL or webhook setup.
• Two accounts: You must use a different WhatsApp account (Account B) to send messages to the bot account (Account A). Messages sent from Account A to itself are ignored.
• Session persistence: Authentication credentials are stored in .data/whatsapp/<channelId>/ on the server. The session survives restarts — you only need to scan the QR code once.
• Reconnection: If the connection drops, Buda will automatically retry with exponential backoff. If the session expires, a new QR code will be shown in the channel settings.
• Groups: Unlike Telegram, WhatsApp groups do not require an @mention — all messages in the group are forwarded to the agent.
• fromMe filtering: Messages sent by Account A itself (e.g., from another linked device) are automatically ignored to prevent feedback loops.