whatsapp-gateway

Passerelle WhatsApp minimale pour que des agents (Paperclip ou autre) puissent notifier le proprietaire d'une decision importante et recevoir sa reponse, sans passer par l'API Business officielle de Meta (pas de template a faire approuver pour un message proactif).

Principe

• Liaison au compte WhatsApp personnel du proprietaire via un pairing code (comme un appareil lie), aucune API tierce.

• Les notifications sont envoyees dans le fil "Message a moi-meme" du compte lie.

• Les reponses tapees dans ce meme fil sont capturees et exposees via GET /inbox pour qu'un agent puisse les relire.

• Le service n'ecoute que sur 127.0.0.1 : jamais expose directement sur Internet. C'est a l'appelant local (agent Paperclip / script sur le meme serveur) de l'appeler en curl localhost.

Related MCP server: WhatsApp Cloud API MCP Server

API

Toutes les routes (sauf /health) exigent Authorization: Bearer <GATEWAY_TOKEN>.

• GET /health -> {"status":"ok"}

• POST /send body {"message": "texte"} -> envoie le message dans le fil "Message a moi-meme"

• GET /inbox?since=<ISO8601> -> messages recus depuis cette date (tous si omis)

Premier appairage

Deux methodes, au choix (mutuellement exclusives : le pairing code prend le pas sur le QR si WA_PAIRING_PHONE_NUMBER est renseigne) :

• Pairing code : renseigner WA_PAIRING_PHONE_NUMBER dans .env (numero international sans le +, ex. 33612345678), demarrer le service, le code s'affiche dans les logs (journalctl -u whatsapp-gateway -f). Sur le telephone : WhatsApp > Parametres > Appareils lies > Lier un appareil > Lier avec un numero de telephone > saisir le code.

• QR code : renseigner WA_QR_IMAGE_PATH (ex. /opt/whatsapp-gateway/data/qr.png), laisser WA_PAIRING_PHONE_NUMBER vide, demarrer le service, recuperer le PNG genere et le scanner (WhatsApp > Appareils lies > Lier un appareil > scan). Le QR expire en 20-60s et se regenere tout seul tant que le compte n'est pas enregistre.

Une fois data/auth/ peuple, retirer WA_PAIRING_PHONE_NUMBER du .env (plus jamais necessaire, sauf perte de session).

Deploiement

deploy/push.sh transfere le code vers un serveur cible via tar + ssh (utile si le depot est prive et que le serveur n'a pas de deploy key). Variables requises : WHATSAPP_GW_HOST (ex. user@monserveur) et WHATSAPP_GW_SSH_KEY. Le .env et data/ (session WhatsApp + boite de reception) vivent uniquement sur le serveur et ne sont jamais ecrases.

Utilisation directe (curl)

curl -s -X POST http://127.0.0.1:8787/send \
  -H "Authorization: Bearer $GATEWAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message": "Decision a valider : ..."}'

curl -s "http://127.0.0.1:8787/inbox?since=2026-09-16T10:00:00.000Z" \
  -H "Authorization: Bearer $GATEWAY_TOKEN"

Serveur MCP (pour un agent sans acces Bash/curl)

src/mcp-server.ts (compile en dist/mcp-server.js) expose ce gateway comme deux outils MCP, utile pour un agent volontairement restreint (pas d'acces Bash/curl, par exemple un agent en lecture seule) :

• notify_owner({ message })

• read_owner_replies({ since? })

Config MCP type (variables GATEWAY_TOKEN/GATEWAY_URL injectees via env, pas besoin qu'elles soient dans l'environnement de l'appelant) :

{
  "mcpServers": {
    "whatsapp": {
      "command": "node",
      "args": ["/opt/whatsapp-gateway/dist/mcp-server.js"],
      "env": {
        "GATEWAY_TOKEN": "<valeur de GATEWAY_TOKEN du .env du gateway>",
        "GATEWAY_URL": "http://127.0.0.1:8787"
      }
    }
  }
}

Ce fichier de config contient le GATEWAY_TOKEN en clair : le stocker hors du depot, avec des permissions restrictives (chmod 600), a un endroit lisible par le processus qui lance l'agent (ex. /etc/whatsapp-mcp/config.json). Cote CLI de l'agent (Claude Code, Codex, etc.), il faut generalement passer un flag du type --mcp-config <chemin> et autoriser explicitement les outils mcp__whatsapp__notify_owner / mcp__whatsapp__read_owner_replies dans la liste d'outils permise.