DocsGuidesHow to connect an AI agent to WhatsApp

How to connect an AI agent to WhatsApp

Name: ConnectOnion
Author: ConnectOnion

co whatsapp links a number as a companion device by QR, writes every message to ~/.co/inbox/whatsapp/, and lets an agent receive, reply and send from the command line.

Install the WhatsApp extra with pip install 'connectonion[whatsapp]', then run co whatsapp listen and scan the QR code from WhatsApp (Settings → Linked devices → Link a device). Every message is written to ~/.co/inbox/whatsapp/. The agent takes the next message with co whatsapp receive and answers with co whatsapp reply. The linked device sees every chat on that number, so use a number meant for the agent.

1. Install the WhatsApp extra

It needs the system library libmagic. If it is missing, the first co whatsapp listen stops and names the command for your platform.

pip install 'connectonion[whatsapp]'

2. Link the number

A QR code appears in the terminal. On the phone: Settings → Linked devices → Link a device. The pairing is stored in ~/.co/inbox/whatsapp/session.db.

co whatsapp listen

3. Check the setup

check names anything missing: the extra, an unlinked device, or the listener.

co whatsapp check

4. Receive and reply

receive prints the next message as one JSON line and takes it off the queue.

co whatsapp receive
co whatsapp reply <message-id> "On it."
co whatsapp send <chat> "Deploy finished."

5. Let an agent answer every message

consume runs a command per message with the message on stdin and replies with its stdout.

co whatsapp consume -- claude -p

FAQ

Does the agent answer in groups?

A group message counts as addressed when it @-mentions the linked number, replies to something it said, or contains its number. Set mention_only on the channel and the agent answers only those; leave it off and it answers everything in the group.

Is this the official WhatsApp Business API?

No. It links a companion device, the same mechanism as WhatsApp Web, so it sees every chat that number is in. Use a number meant for the agent.

Can it edit or delete what it sent?

Yes. co whatsapp edit replaces the text of a message this account sent, co whatsapp delete deletes one for everyone, and co whatsapp react reacts to any message.