Skip to main content

Build a WhatsApp AI Agent with nanoinfra

This guide connects nanoinfra to WhatsApp through the whatsapp channel. The channel links as a WhatsApp device and uses the same nanoinfra agent runtime, tools, memory, and workspace as the CLI and WebUI.

What this guide builds​

  • WhatsApp optional dependencies installed
  • a linked WhatsApp device session
  • the whatsapp channel enabled in config.json
  • one pairing-approved WhatsApp sender

Prerequisites​

  • A working local nanoinfra reply:
nanoinfra agent -m "Hello!"
  • A WhatsApp account that can link a new device.
  • A machine that can keep nanoinfra gateway running.

Install nanoinfra​

Quick Start ranks four install methods easiest first. This is the first of them. Use pip, Docker or a source checkout instead if you prefer, and come back here.

uv tool install nanoinfra
nanoinfra onboard --wizard

Enable the WhatsApp channel​

Install the optional channel dependency:

nanoinfra plugins enable whatsapp

Link WhatsApp as a device:

nanoinfra channels login whatsapp

Scan the QR code from WhatsApp -> Settings -> Linked Devices.

Merge this snippet into ~/.nanoinfra/config.json:

{
  "channels": {
    "whatsapp": {
      "enabled": true,
      "groupPolicy": "mention"
    }
  }
}

Omitting allowFrom enables pairing-only mode for private chats. groupPolicy defaults to "open" in the channel, but "mention" is safer for a first deployment.

Run nanoinfra gateway​

nanoinfra channels status
nanoinfra gateway

Test a message​

Message the bot from a different WhatsApp account. The account you linked is the bot. The channel drops every message that account sends, so you cannot be both sides of the conversation. Messaging your own number looks like a broken bot and is the guard working: without it the agent would answer itself forever.

A second phone works, so does WhatsApp Business with another number on the same phone, and so does a group that another account writes in. If you want to talk to the bot from your own phone, give the bot a number of its own.

Send it a private message from that other account. It should answer with a pairing code such as 7K2M-QX9P. Approve that code from a trusted local surface, and not the example below:

nanoinfra agent -m "/pairing approve <the code the bot sent you>"

To see the codes that are waiting, ask for the list:

nanoinfra agent -m "/pairing"

Send the message again after approval. The reply should use the same model and workspace as your local CLI check.

Security notes​

  • Treat the WhatsApp session database as account access.
  • Prefer pairing-only mode for first setup. Add allowFrom only when you want a static allowlist.
  • Keep groupPolicy as "mention" before adding the bot to groups.
  • Avoid allowFrom: ["*"] unless the bot is intentionally public or isolated.

Troubleshooting​

  • If QR linking fails, rerun nanoinfra channels login whatsapp.
  • If you are migrating from the old bridge, remove bridgeUrl and bridgeToken, then re-login.
  • If a sender appears as a LID instead of a phone number, let nanoinfra learn the mapping at runtime or use lidMappings in the full reference.
  • If a first private message returns a pairing code, approve it before testing normal replies.

Next: memory, automations, MCP tools​