Skip to main content
Connect your Coral assistant to WhatsApp so you can chat with it directly in your WhatsApp conversations.

​
Overview

The WhatsApp integration is sandbox-native — your session credentials are stored securely inside your isolated sandbox environment and never leave it. Unlike Discord and Telegram, WhatsApp uses QR code scanning (via WhatsApp’s Linked Devices feature) instead of a bot token.
Important: The WhatsApp account you scan with becomes the bot. If you only have one phone number, you’ll be messaging yourself to chat with your assistant — this works, but can feel a little awkward. For a more natural experience, consider using a second number for the bot.

​
Prerequisites

  • A Coral account with an active sandbox
  • A phone with WhatsApp installed
  • At least one phone number to allow-list for receiving responses

​
Step 1: Configure Allowed Phone Numbers

For security, your assistant only responds to messages from pre-approved phone numbers.
  1. Open the Coral dashboard and go to the Integrations page.
  2. Click on the WhatsApp card.
  3. Add the phone numbers that should be able to chat with the assistant. Enter each number in international E.164 format (e.g., +15551234567).
You must add at least one phone number before proceeding.

​
Step 2: Scan the QR Code

  1. After entering your phone numbers, click “Generate QR Code”.
  2. Coral will display a QR code on screen.
  3. On your phone, open WhatsApp > Settings > Linked Devices > Link a Device.
  4. Scan the QR code displayed in Coral.
The page will automatically detect when the scan is successful and transition to the connected state.
If the QR code expires before you scan it, click “Refresh QR” to generate a new one.

​
Step 3: Start Chatting

Once connected:
  1. Open WhatsApp on another device or from another number on your allow-list.
  2. Find the linked account in your contacts (or search for the phone number).
  3. Send a message like “Hello!” — your AI assistant will reply right in the chat.

​
Managing Your WhatsApp Integration

Once connected, the WhatsApp card shows your linked phone number and connection status.

​
Edit Allowed Numbers

You can update the list of allowed phone numbers at any time:
  1. Click “Edit allowed numbers” on the connected card.
  2. Add or remove phone numbers.
  3. Click “Save”.

​
Reconnect

If the WhatsApp session becomes disconnected (e.g., you logged out from Linked Devices on your phone), click “Reconnect” to generate a new QR code and re-link.

​
Disconnect

Click “Disconnect” to fully remove the WhatsApp session from your sandbox. You will need to scan a new QR code to reconnect.

​
Troubleshooting

ProblemSolution
QR code expiredClick “Refresh QR” to generate a new one. QR codes are time-limited.
”Configured but not connected”Your linked session may have expired. Click “Reconnect” to scan a new QR code.
Bot doesn’t respond to messagesCheck that the sender’s phone number is on the allowed list. Only allow-listed numbers get responses.
Session disconnects frequentlyThis can happen if you unlink the device from WhatsApp settings on your phone. Keep the linked device active.

​
Security

  • WhatsApp session credentials (Baileys authentication) are stored exclusively inside your sandbox.
  • The session data never passes through Coral’s servers.
  • Phone numbers on the allow-list are stored in your sandbox’s configuration (channels.whatsapp.allowFrom).
  • If you back up and restore your sandbox, the WhatsApp configuration is preserved, but you may need to re-scan the QR code to re-establish the session.