Guide d'installation et documentation

Installation

Vous avez besoin d'une machine Linux et du fichier waxion-api qui vous a été remis. Rien d'autre n'est à installer : ni Go, ni base de données, ni serveur web.

1. 1

   Placer le fichier dans un dossier dédié

   Ce dossier accueillera aussi la session WhatsApp et, si vous en créez un, le fichier de configuration.

   mkdir -p /opt/waxion-api
   cd /opt/waxion-api
   # copiez ensuite le fichier waxion-api dans ce dossier

2. 2

   Autoriser son exécution

   Un fichier fraîchement copié n'est pas exécutable par défaut sous Linux.

   chmod +x waxion-api

3. 3

   Lancer l'application

   ./waxion-api

   L'interface est alors disponible sur http://localhost:3063 (port par défaut). Rendez-vous ensuite à la section Premiers pas.

Configuration

L'application démarre sans aucune configuration. Pour changer le port ou déclarer votre nom de domaine, créez un fichier nommé .env à côté de l'exécutable :

PORT=3700
PUBLIC_BASE_URL=https://votre-domaine.com
TRUSTED_ORIGIN=https://votre-domaine.com

Garder l'application lancée en continu

Lancée simplement avec ./waxion-api, l'application s'arrête dès que vous fermez le terminal. Deux solutions selon vos besoins.

nohup ./waxion-api > waxion-api.log 2>&1 &

pkill waxion-api

[Unit]
Description=Waxion API
After=network.target

[Service]
Type=simple
WorkingDirectory=/opt/waxion-api
EnvironmentFile=/opt/waxion-api/.env
ExecStart=/opt/waxion-api/waxion-api
Restart=on-failure
User=waxion

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now waxion-api
sudo systemctl status waxion-api

Option : lancer avec Docker

Docker n'est pas nécessaire — l'exécutable fonctionne seul. Cette option intéresse ceux dont l'infrastructure est déjà conteneurisée. Le principe reste le même : on se contente d'emballer l'exécutable que vous avez reçu.

FROM alpine:3.20

# Certificats requis pour les appels sécurisés sortants
RUN apk add --no-cache ca-certificates tzdata

WORKDIR /app
COPY waxion-api .
RUN chmod +x waxion-api

VOLUME ["/app/data"]
ENTRYPOINT ["./waxion-api"]

docker build -t waxion-api:latest .

docker run -d \
  --name waxion-api \
  --restart unless-stopped \
  --env-file .env \
  -p 3700:3700 \
  -v "$(pwd)/data:/app/data" \
  waxion-api:latest

services:
  waxion-api:
    build: .
    image: waxion-api:latest
    restart: unless-stopped
    env_file:
      - .env
    ports:
      - "3700:3700"
    volumes:
      - ./data:/app/data

Exposer l'application en HTTPS avec Nginx

Cette étape ne concerne que les installations accessibles depuis Internet. Nginx place votre application derrière un nom de domaine et un certificat TLS.

server {
  server_name votre-domaine.com;

  client_max_body_size 140m;

  location / {
    proxy_pass http://127.0.0.1:3700;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_buffering off;
    proxy_read_timeout 3600s;
  }

  listen 443 ssl;
  ssl_certificate     /etc/letsencrypt/live/votre-domaine.com/fullchain.pem;
  ssl_certificate_key /etc/letsencrypt/live/votre-domaine.com/privkey.pem;
}

Vérifiez la syntaxe puis rechargez Nginx :

sudo nginx -t && sudo systemctl reload nginx

Pensez enfin à renseigner PUBLIC_BASE_URL et TRUSTED_ORIGIN avec votre adresse HTTPS dans le fichier .env, puis à redémarrer l'application.

Premiers pas dans l'application

Principes généraux

{
  "success": true,
  "message": "Message envoyé",
  "data": { },
  "error": ""
}

Deux modes d'authentification

X-API-Key: votre_cle_api

Envoi de messages

Ce sont les deux routes que vous utiliserez le plus. Elles acceptent la clé API et consomment votre essai gratuit ou votre abonnement.

{
  "phone": "24177000000",
  "message": "Bonjour, votre réservation est confirmée."
}

curl -X POST https://votre-domaine.com/api/messages/send-text \
  -H "Content-Type: application/json" \
  -H "X-API-Key: votre_cle_api" \
  -d '{"phone":"24177000000","message":"Bonjour !"}'

{
  "success": true,
  "message": "Message envoyé",
  "data": { "message_id": "3EB0...", "phone": "24177000000" }
}

{
  "phone": "24177000000",
  "caption": "Voici votre billet",
  "filename": "billet.pdf",
  "mimetype": "application/pdf",
  "file_base64": "data:application/pdf;base64,JVBERi0x..."
}

Campagnes en masse

Une campagne envoie un message personnalisé à une liste de destinataires, en espaçant automatiquement chaque envoi pour préserver votre compte WhatsApp.

{
  "contacts": [
    { "phone": "24177000001", "message": "Bonjour Jean" },
    {
      "phone": "24177000002",
      "message": "Bonjour Awa",
      "file_base64": "data:application/pdf;base64,...",
      "file_name": "billet.pdf",
      "mimetype": "application/pdf"
    }
  ],
  "delay_min_seconds": 8,
  "delay_max_seconds": 20
}

Le suivi des campagnes est conservé en mémoire : il est remis à zéro au redémarrage de l'application. Si vous devez archiver les résultats, récupérez-les depuis votre propre système.

Recevoir les messages entrants

Waxion API ne conserve jamais le contenu des messages reçus. Pour les exploiter, déclarez une adresse de webhook : chaque message entrant y sera transmis en temps réel, à charge pour votre système de le traiter et de le conserver.

{ "webhook_url": "https://votre-systeme.com/webhook/whatsapp" }

Ce que votre serveur recevra

Pour chaque message reçu, Waxion API envoie une requête POST à votre adresse, avec ce contenu :

{
  "from": "24177000000",
  "push_name": "Jean D.",
  "text": "Bonjour",
  "message_id": "3EB0...",
  "timestamp": "2026-07-02T10:00:00Z"
}

• L'envoi est abandonné au bout de 8 secondes sans réponse de votre part.
• Un webhook lent ou indisponible ne perturbe jamais la réception WhatsApp. En contrepartie, il n'y a ni file d'attente ni nouvelle tentative : un message non reçu par votre serveur est définitivement perdu.
• Seuls les messages textuels sont relayés à ce jour.

Compte, abonnement et connexion WhatsApp

Ces routes sont réservées à l'interface web : elles exigent une session, et n'acceptent pas la clé API. Elles sont documentées ici à titre de référence.

Compte

Abonnement

L'abonnement mensuel coûte 15 000 FCFA. Il est activé pour un mois dès le paiement confirmé, et prolongé si un abonnement était déjà en cours. Il expire automatiquement à échéance : aucun prélèvement récurrent n'est effectué.

Connexion WhatsApp

Les entrées marquées FLUX sont des flux Server-Sent Events : la connexion reste ouverte et le serveur pousse les nouveautés au fil de l'eau. Aucune de ces routes ne consomme votre essai gratuit.

Codes d'erreur

Préserver votre compte WhatsApp

WhatsApp surveille les comportements d'envoi automatisés. Ces précautions réduisent nettement le risque de suspension de votre numéro.

Dépannage