WhatsApp

Connect Comis to WhatsApp with step-by-step setup

Connect your Comis agent to WhatsApp personal and group chats. WhatsApp supports reactions, buttons, file attachments up to 100 MB, and block-streaming responses. Unlike other adapters, WhatsApp uses phone-based QR pairing instead of API tokens.

You don’t need to understand the technical details to use this feature. The configuration examples below are copy-paste ready.

Prerequisites

• Comis installed and running (Quickstart)

• A phone with WhatsApp installed
• The phone must stay connected to the internet (WhatsApp multi-device requires periodic syncs)

WhatsApp does not use an API key. On first run, you will scan a QR code with your phone to link Comis as a companion device. Keep your phone connected — if it goes offline for extended periods, the link may expire and you will need to pair again.

Setup

1. Configure Comis

   Unlike other adapters, WhatsApp does not need a token upfront. Add the WhatsApp channel to your Comis configuration file (~/.comis/config.yaml):

   channels:
     whatsapp:
       enabled: true
       authDir: "~/.comis/whatsapp-auth"
       printQR: true
   

   The authDir directory stores session files that keep you connected across restarts. Make sure it points to a persistent location (not /tmp/).

   Never store API keys, tokens, or passwords directly in config.yaml. Use the .env file or Secret Manager for credential management.

2. Start Comis and scan the QR code

   Start (or restart) the Comis daemon:

   comis daemon stop && comis daemon start
   

   Watch the terminal output or logs. A QR code will appear (when printQR: true).

   On your phone:

   1. Open WhatsApp
   2. Go to Settings then Linked Devices
   3. Tap Link a Device
   4. Scan the QR code displayed in the terminal

   Wait for the logs to show “WhatsApp adapter connected”. This confirms the pairing was successful.

3. Send a test message

   From another phone or contact, send a message to the linked WhatsApp number. Verify the agent responds.

   In group chats, the agent must be a participant in the group — you cannot send messages to groups the linked number has not joined.

4. Verify session persistence

   Stop and restart Comis:

   comis daemon stop && comis daemon start
   

   It should reconnect automatically without a new QR scan. If it asks for a QR code again, check that authDir points to a persistent directory and that the session files were not deleted.

Configuration

These options go under channels.whatsapp in your config.yaml:

Option	Type	Default	What it does
enabled	boolean	false	Turns on the WhatsApp adapter
authDir	string	~/.comis/whatsapp-auth	Directory for multi-device session files. Must be persistent.
printQR	boolean	true	Print QR code to the terminal on first pairing
allowFrom	string[]	[] (all)	Restrict to specific WhatsApp phone numbers. Empty means all contacts can talk to the bot.
mediaProcessing.transcribeAudio	boolean	true	Transcribe voice messages to text before passing to the agent
mediaProcessing.analyzeImages	boolean	true	Describe images sent to the bot using AI vision
mediaProcessing.describeVideos	boolean	true	Extract descriptions from video content
mediaProcessing.extractDocuments	boolean	true	Extract text from PDFs, DOCX, and other documents
mediaProcessing.understandLinks	boolean	true	Fetch and summarize URLs included in messages

What your agent can do

Once connected to WhatsApp, your agent can:

• Send and edit messages; delete its own messages (Baileys cannot delete other users’ messages)
• React to messages with Unicode emoji
• Send interactive buttons for user choices (text or image-anchored)
• Send file attachments up to 100 MB
• Send native voice messages (audio attachments uploaded as WhatsApp voice notes via the Baileys client)
• Send native polls (single or multi-select), normalized via Comis’s poll pipeline so vote results flow back through the agent
• Send and receive location messages and contact (vCard) cards
• Read receipts (the Baileys multi-device protocol exposes them natively, so the agent sees when its messages are read)
• Stream responses as separate message blocks (updates every 600 ms)
• Manage groups (info, subject, description, participants, promote/demote, invite codes, settings, leave) and update profile status via platform actions

WhatsApp does not support threads (only quoted-reply chains), fetching message history, rich text formatting (plain text only), @mentions of individual users, or cards/embeds.

Platform limits

Limit	Value	What Comis does about it
Message length	65,536 characters	Rarely hit; automatically splits if exceeded
Attachment size	100 MB	Files over 100 MB are rejected with a user-friendly error message

Troubleshooting

QR code not appearing

What happened: The QR code is not being printed to the terminal.

How to fix it: Check that printQR: true is set in your config. Also ensure your terminal supports QR rendering (most modern terminals do). If running via pm2 or systemd, check the logs instead of the terminal — the QR code is logged there.

Session expired, asking for QR again

What happened: The session files in authDir were deleted, or authDir points to a temporary directory.

How to fix it: Set authDir to a persistent path like ~/.comis/whatsapp-auth. If the files were intentionally deleted, scan the QR code again to re-pair.

WhatsApp adapter starts but nothing happens

What happened: You likely missed the QR pairing step on first run. The adapter is waiting for you to scan the QR code.

How to fix it: Watch the terminal output or logs on first start for the QR code. Open WhatsApp on your phone, go to Settings then Linked Devices then Link a Device, and scan the QR code.

Messages not delivered to groups

What happened: The agent can only participate in groups that the linked WhatsApp number has already joined.

How to fix it: Add the linked phone number to the group in WhatsApp first, then the agent will be able to receive and send messages there.

Delivery Infrastructure

How streaming, typing indicators, and retry logic work under the hood.

Multiple users & teams

Run one install for a whole team - private per person, isolated per agent.

All Channels

Compare all 9 supported platforms side by side.

Agent Configuration

Set up your agent’s personality, tools, and behavior.

Secret Management

Learn how to manage API keys and tokens securely.