# 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.

## 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)

```bash
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) :

```json
{
  "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.