Numéros de la boîte et webhooks de messages entrants

Sur la page Numéros de la boîte, vous choisissez lesquels de vos numéros WhatsApp se synchronisent dans la boîte de réception Unibox, où votre équipe lit leurs discussions et y répond. Donnez une URL de webhook à un numéro, et WbizTool transmet aussi à votre serveur chaque nouveau message reçu ou envoyé, en JSON signé : enregistrez les conversations dans un CRM, alertez votre équipe ou lancez une réponse automatique.

Vous construisez le récepteur ? Allez à Comment les webhooks sont envoyés, Vérifier la signature et Contenu (payload).

Qui peut le faire : les Propriétaires et les Éditeurs ajoutent des numéros, modifient les webhooks et voient le secret du webhook. Les Analystes ne voient pas Numéros de la boîte dans la barre latérale. Il faut le module Unibox : 20 $ par mois ou 200 $ par an au prix catalogue américain pour chaque numéro de la boîte de réception (votre prix s'affiche dans Facturation et forfaits), ajouté à un forfait payant ou à vie par un Propriétaire dans Facturation et forfaits (voir Modules complémentaires). Sa quantité correspond au nombre de numéros qui peuvent être dans la boîte de réception en même temps.

Ouvrez Numéros de la boîte sous Boîte de réception dans la barre latérale, ou allez sur /unibox/listeners/.

Avant de commencer#

• Le module Unibox avec un numéro de boîte libre : la ligne sous le titre de la page indique par exemple « 2 sur 3 numéros de boîte utilisés (module Unibox) », ou « Pas de module Unibox » (voir Sans le module Unibox).
• Un numéro WhatsApp connecté avec un code QR ou un code de connexion, affiché Connecté dans Numéros WhatsApp. Les numéros connectés via l'extension du navigateur ne peuvent pas être ajoutés. Un compte Telegram connecté peut être ajouté comme un numéro.
• Pour un webhook : une adresse https:// de 500 caractères maximum sur l'Internet public (pas localhost ni un réseau privé) qui accepte les requêtes POST avec un corps JSON et répond 2xx en moins de 8 secondes.

Ajouter un numéro à la boîte de réception#

1. Ouvrir la fenêtre

   Cliquez sur Ajouter un numéro à la boîte en haut à droite de la page.

2. Choisir le numéro

   Choisissez-le sous Numéro WhatsApp. La liste affiche vos numéros connectés qui ne sont pas encore dans la boîte de réception.

3. Ajouter un webhook (facultatif)

   Saisissez votre adresse sous URL du webhook (facultatif). Messages à envoyer apparaît alors : gardez Messages reçus, Messages envoyés ou les deux cochés. Vous pourrez ajouter ou modifier le webhook plus tard.

   

4. L'ajouter

   Cliquez sur Ajouter le numéro. Vous voyez « Numéro ajouté – ses discussions commencent à se synchroniser d’ici quelques minutes. » Si vous avez saisi une URL de webhook, Votre secret de webhook s'ouvre : cliquez sur Copier et conservez le secret là où votre serveur peut le lire. Vous pourrez l'afficher de nouveau plus tard dans les paramètres du webhook.

• Seulement les nouveaux messages. Un numéro se synchronise à partir du moment où vous l'ajoutez : les messages plus anciens ne sont ni importés ni transmis.
• Tous les numéros sont utilisés ? La fenêtre indique « Tous vos numéros de boîte sont utilisés. Arrêtez-en ou supprimez-en un, ou ajoutez-en au module Unibox. » Arrêtez ou supprimez un numéro, ou demandez à un Propriétaire d'augmenter la quantité du module (Voir les modules).
• Rajouter un numéro supprimé rétablit sa boîte de réception (« Numéro rajouté – ses discussions se synchronisent de nouveau à partir de maintenant. ») ; les messages arrivés pendant qu'il était supprimé ne sont pas récupérés. Avec une URL de webhook, il garde son ancien secret s'il en avait un (utilisez Afficher dans Paramètres du webhook) ; sinon, Votre secret de webhook s'ouvre avec un nouveau secret.

Ce qu'affiche la carte d'un numéro#

Chaque carte affiche le numéro, la dernière fois que WbizTool y a cherché des messages (« Dernière vérification il y a 1 min », ou Jamais vérifié), ses Messages et ses Contacts synchronisés (toutes les discussions synchronisées depuis ce numéro, y compris celles sans message dans la boîte de réception), son Dernier message et son Webhook : l'URL et ce qu'il transmet, par exemple « Envoie chaque message reçu et envoyé · signé avec un secret », ou « Aucun – les messages s’affichent seulement dans la boîte. » Un badge Zapier signifie qu'un Zap reçoit les messages (voir Zapier et numéros de la boîte).

Le badge en haut à droite indique ce que fait le numéro :

Modifier l'URL du webhook ou les messages transmis#

1. Ouvrir les paramètres du webhook

   Cliquez sur Paramètres du webhook sur la carte du numéro.

2. Modifier les paramètres

   Modifiez l'URL du webhook (facultatif) et les cases sous Messages à envoyer. Pour désactiver le webhook, videz l'URL.

3. Enregistrer

   Cliquez sur Enregistrer. Vous voyez « Paramètres du webhook enregistrés. »

   

• Modifier l'URL conserve le secret. Vider l'URL le supprime ; une URL ajoutée plus tard reçoit un nouveau secret, affiché une seule fois dans Votre secret de webhook.
• Si aucune des deux cases n'est cochée, la carte indique « Aucun événement sélectionné – rien n’est envoyé ».

Afficher ou régénérer le secret#

Le secret compte 32 lettres et chiffres. Dans Paramètres du webhook, sous Secret du webhook, Afficher le révèle, avec Copier à côté. Régénérer demande « Générer un nouveau secret ? L’actuel cesse aussitôt de fonctionner – mettez-le à jour partout où vous vérifiez les signatures. » Cliquez sur Générer un nouveau secret : il est enregistré immédiatement (« Nouveau secret généré. »), sans Enregistrer, et toutes les requêtes suivantes sont signées avec lui, y compris les nouvelles tentatives de messages antérieurs.

Arrêter, démarrer ou supprimer un numéro#

Les webhooks en attente d'une nouvelle tentative sont abandonnés quand vous arrêtez ou supprimez le numéro, ou modifiez son URL.

Comment les webhooks sont envoyés#

• Quand : chaque numéro de boîte est vérifié environ une fois par minute tant qu'il est connecté ; les vérifications font une pause pendant qu'il envoie des messages, comme une campagne. Un message est transmis après la vérification qui le trouve, généralement en une ou deux minutes. Il n'y a pas de bouton de test : envoyez un message au numéro depuis un autre téléphone.
• Une requête par message : message_received pour Messages reçus ; message_sent pour Messages envoyés, envoyés depuis le téléphone, WhatsApp Web ou par WbizTool (campagnes, API, rappels). Les réponses envoyées depuis la boîte de réception Unibox ne sont généralement pas transmises : la boîte de réception les a déjà.
• Succès : tout statut 2xx en moins de 8 secondes. Les redirections ne sont pas suivies : un 3xx compte comme un échec.
• Nouvelles tentatives : un délai dépassé, une erreur de connexion, 429 ou un 5xx donne lieu à 3 nouvelles tentatives, après 30 secondes, 1 minute et 2 minutes. Les autres réponses, comme 400 ou 404, et un certificat TLS invalide ne donnent pas lieu à une nouvelle tentative.
• 410 Gone : WbizTool désactive le webhook du numéro (URL et secret supprimés ; pour un hook Zapier, votre propre webhook précédent revient). Le numéro continue de se synchroniser dans la boîte de réception.
• Ordre et doublons : les requêtes peuvent arriver dans le désordre et, rarement, en double. Triez par message.whatsapp_timestamp et ignorez un message.id déjà traité pour le même whatsapp_client_id. Deux de vos numéros dans un même groupe transmettent chacun leur propre copie.
• Messages en retard : un message récupéré en retard, par exemple après la reconnexion du numéro ou une pause des vérifications, est quand même transmis, avec replayed à true s'il a plus de 10 minutes. Les messages arrivés pendant que le numéro était arrêté ne sont pas transmis après Démarrer (voir Arrêter, démarrer ou supprimer un numéro).
• Vérification de l'adresse : l'URL est vérifiée de nouveau avant chaque requête ; un hôte qui pointe désormais vers un réseau privé, ou qui ne se résout pas, ne reçoit rien, et ce message n'est pas renvoyé.

En-têtes#

Vérifier la signature#

Chaque requête est signée avec le secret du webhook du numéro, en HMAC-SHA256 sur le corps brut de la requête, exactement tel que reçu. Le condensé hexadécimal en minuscules est envoyé dans X-Wbiztool-Signature sous la forme sha256=<digest>. Un webhook défini sur la page Numéros de la boîte a toujours un secret : l'en-tête est donc toujours présent.

Calculez la signature à partir des octets bruts avant d'analyser le JSON. Analyser puis réencoder le corps le modifie (espaces, caractères échappés), et la signature ne correspond plus.

// Express: register this route before app.use(express.json()), or the raw body is lost
import crypto from "node:crypto";
import express from "express";

const app = express();
const SECRET = process.env.WBIZTOOL_WEBHOOK_SECRET;

app.post("/wbiztool/webhook", express.raw({ type: "application/json" }), (req, res) => {
  const expected = "sha256=" + crypto.createHmac("sha256", SECRET).update(req.body).digest("hex");
  const received = req.get("X-Wbiztool-Signature") || "";

  const a = Buffer.from(received), b = Buffer.from(expected);
  const valid = a.length === b.length && crypto.timingSafeEqual(a, b);
  if (!valid) return res.status(401).send("Invalid signature");

  const data = JSON.parse(req.body.toString("utf8"));
  if (data.event === "message_received") {
    console.log(`New message from ${data.contact.phone}: ${data.message.content}`);
  }
  res.sendStatus(200); // answer quickly; do slow work in the background
});

app.listen(3000);

# Flask
import hashlib
import hmac
import json
import os

from flask import Flask, abort, request

app = Flask(__name__)
SECRET = os.environ["WBIZTOOL_WEBHOOK_SECRET"].encode()


@app.post("/wbiztool/webhook")
def wbiztool_webhook():
    raw_body = request.get_data()  # raw bytes, before parsing
    expected = "sha256=" + hmac.new(SECRET, raw_body, hashlib.sha256).hexdigest()
    received = request.headers.get("X-Wbiztool-Signature", "")
    if not hmac.compare_digest(expected, received):
        abort(401)

    data = json.loads(raw_body)
    if data["event"] == "message_received":
        print(f"New message from {data['contact']['phone']}: {data['message']['content']}")
    return "", 200

<?php
$secret   = getenv('WBIZTOOL_WEBHOOK_SECRET');
$rawBody  = file_get_contents('php://input');
$expected = 'sha256=' . hash_hmac('sha256', $rawBody, $secret);
$received = $_SERVER['HTTP_X_WBIZTOOL_SIGNATURE'] ?? '';

if (!hash_equals($expected, $received)) {
    http_response_code(401);
    exit('Invalid signature');
}

$data = json_decode($rawBody, true);
if ($data['event'] === 'message_received') {
    error_log('New message from ' . $data['contact']['phone'] . ': ' . $data['message']['content']);
}
http_response_code(200);

Pour tester votre récepteur avant qu'un vrai message arrive, signez vous-même un corps et envoyez-le :

BODY='{"event":"message_received","message":{"content":"Test"},"contact":{"phone":"12125550120"}}'
SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$WBIZTOOL_WEBHOOK_SECRET" | sed 's/^.* //')
curl -X POST https://your-server.example/wbiztool/webhook -H 'Content-Type: application/json' -H "X-Wbiztool-Signature: sha256=$SIG" -d "$BODY"

La signature couvre le corps, y compris son timestamp, qui change à chaque tentative. Pour refuser les requêtes rejouées, rejetez un timestamp vieux de plus de 5 minutes et ignorez un message.id déjà traité.

Contenu (payload)#

{
  "event": "message_received",
  "timestamp": "2026-10-15T10:30:31.482913+00:00",
  "replayed": false,
  "webhook_id": 51,
  "whatsapp_client_id": "101",
  "whatsapp_phone": "12125550101",
  "platform": "whatsapp",
  "message": {
    "id": "[email protected]_3EB0C1A2B3D4E5F60718",
    "type": "chat",
    "content": "Can I add a gift note to it?",
    "from": "12125550120",
    "from_name": "Emma Thompson",
    "to": "12125550101",
    "timestamp": "2026-10-15T10:30:04+00:00",
    "whatsapp_timestamp": 1792060204,
    "direction": "incoming",
    "status": "pending",
    "is_forwarded": false,
    "forwarding_score": 0
  },
  "contact": {
    "whatsapp_id": "[email protected]",
    "phone": "12125550120",
    "lid": null,
    "phone_hidden": false,
    "name": "Emma Thompson",
    "is_group": false,
    "is_business": false
  },
  "organisation": {
    "id": "10314",
    "name": "Lumen & Wick"
  }
}

{
  "event": "message_sent",
  "timestamp": "2026-10-15T10:34:22.117205+00:00",
  "replayed": false,
  "webhook_id": 51,
  "whatsapp_client_id": "101",
  "whatsapp_phone": "12125550101",
  "platform": "whatsapp",
  "message": {
    "id": "[email protected]_3EB0F9E8D7C6B5A40312",
    "type": "chat",
    "content": "Of course! Send us the text and we'll print it on a card.",
    "from": "12125550120",
    "from_name": "Emma Thompson",
    "to": "12125550101",
    "timestamp": "2026-10-15T10:33:40+00:00",
    "whatsapp_timestamp": 1792060420,
    "direction": "outgoing",
    "status": "pending",
    "is_forwarded": false,
    "forwarding_score": 0
  },
  "contact": {
    "whatsapp_id": "[email protected]",
    "phone": "12125550120",
    "lid": null,
    "phone_hidden": false,
    "name": "Emma Thompson",
    "is_group": false,
    "is_business": false
  },
  "organisation": {
    "id": "10314",
    "name": "Lumen & Wick"
  }
}

{
  "event": "message_received",
  "timestamp": "2026-10-15T10:35:48.904311+00:00",
  "replayed": false,
  "webhook_id": 51,
  "whatsapp_client_id": "101",
  "whatsapp_phone": "12125550101",
  "platform": "whatsapp",
  "message": {
    "id": "[email protected]_3EB0A7B6C5D4E3F20109",
    "type": "image",
    "content": "📸 Image",
    "from": "12125550122",
    "from_name": "Sofia Martinez",
    "to": "12125550101",
    "timestamp": "2026-10-15T10:34:51+00:00",
    "whatsapp_timestamp": 1792060491,
    "direction": "incoming",
    "status": "pending",
    "is_forwarded": false,
    "forwarding_score": 0,
    "media": {
      "filename": "",
      "mimetype": "image/jpeg",
      "size": 245760,
      "url": "https://wbiztool-static.s3.ap-southeast-1.amazonaws.com/unibox/10314/media/false_12125550122%40c.us_3EB0A7B6C5D4E3F20109.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=…&X-Amz-Date=20261015T103548Z&X-Amz-Expires=604800&X-Amz-SignedHeaders=host&X-Amz-Signature=…"
    }
  },
  "contact": {
    "whatsapp_id": "[email protected]",
    "phone": "12125550122",
    "lid": null,
    "phone_hidden": false,
    "name": "Sofia Martinez",
    "is_group": false,
    "is_business": false
  },
  "organisation": {
    "id": "10314",
    "name": "Lumen & Wick"
  }
}

{
  "event": "message_received",
  "timestamp": "2026-10-15T10:39:40.330187+00:00",
  "replayed": false,
  "webhook_id": 51,
  "whatsapp_client_id": "101",
  "whatsapp_phone": "12125550101",
  "platform": "whatsapp",
  "message": {
    "id": "[email protected][email protected]",
    "type": "chat",
    "content": "Will there be a larger size?",
    "from": "120363041234567890",
    "from_name": "Lumen VIP Club",
    "to": "12125550101",
    "timestamp": "2026-10-15T10:39:02+00:00",
    "whatsapp_timestamp": 1792060742,
    "direction": "incoming",
    "status": "pending",
    "is_forwarded": false,
    "forwarding_score": 0,
    "sender": {
      "phone": "12125550126",
      "name": "Olivia Brooks",
      "phone_hidden": false
    }
  },
  "contact": {
    "whatsapp_id": "[email protected]",
    "phone": "120363041234567890",
    "lid": null,
    "phone_hidden": false,
    "name": "Lumen VIP Club",
    "is_group": true,
    "is_business": false
  },
  "organisation": {
    "id": "10314",
    "name": "Lumen & Wick"
  },
  "group": {
    "name": "Lumen VIP Club"
  }
}

Les numéros, identifiants et noms ci-dessus sont des exemples. Le vrai corps tient sur une ligne de JSON compact, et chaque caractère non ASCII (lettres accentuées, autres écritures, emoji) arrive sous forme d'échappement \uXXXX, comme \ud83d\udcf8 pour 📸. D'autres champs peuvent s'ajouter ; ignorez ceux que vous n'utilisez pas.

Champs de premier niveau#

Champs de message#

Champs de contact#

Zapier et numéros de la boîte#

Le déclencheur WbizTool Incoming WhatsApp Message de Zapier utilise ces webhooks. Activer un Zap ajoute le numéro à la boîte de réception si nécessaire (en utilisant l'un de vos numéros de boîte) et dirige son webhook vers Zapier, pour les messages reçus uniquement, avec son propre secret ; la carte affiche un badge Zapier. Votre propre URL de webhook, votre secret et vos cases cochées reviennent quand le Zap est désactivé.

Paramètres du webhook avertit alors : « Ce webhook appartient à un Zap Zapier. Modifier ou supprimer l’URL empêche le Zap de recevoir les messages. » Arrêter et Supprimer avertissent aussi : le Zap reste activé dans Zapier mais ne reçoit rien, désactivez-le donc plutôt dans Zapier. Voir Fonctionnement du déclencheur avec vos numéros de boîte de réception.

Sans le module Unibox#

La page indique « Pas de module Unibox » et « Le module Unibox n’est pas actif sur cet espace de travail. », et Ajouter un numéro à la boîte ouvre Module Unibox requis : « Pour ajouter des numéros WhatsApp à la boîte de réception partagée et recevoir leurs messages par webhook, abonnez-vous au module Unibox. » Un Propriétaire clique sur Voir les modules et ajoute le module Numéro Unibox dans Facturation et forfaits, sur un forfait payant ou à vie (pas pendant l'essai gratuit).

Quand le module prend fin ou qu'un numéro se déconnecte#

• Le module prend fin : chaque numéro de boîte est arrêté, aussitôt ou dans l'heure environ. Les cartes affichent Arrêté avec « Arrêté car le module Unibox n’est pas actif sur cet espace de travail. » Les Propriétaires et les Éditeurs apprennent quelles boîtes ont été arrêtées, dans l'e-mail de facturation ou dans l'alerte « Des numéros ou fonctions de … se sont arrêtés » (Problèmes de numéro et d’envoi dans Notifications). Les conversations, URL de webhook et secrets sont conservés : une fois le module rétabli, cliquez sur Démarrer pour chaque numéro. Les messages arrivés pendant l'arrêt sont alors ajoutés à la boîte, jusqu'à 30 jours en arrière, mais pas transmis à votre webhook.
• Le module couvre moins de numéros que ceux qui sont activés : « Plus de numéros sont activés que votre module ne le permet. Les numéros en trop les plus récents sont arrêtés automatiquement dans l’heure environ. »
• Le numéro se déconnecte : la carte affiche Numéro déconnecté et rien n'est synchronisé ni transmis. Après la reconnexion, les messages arrivés entre-temps sont aussi récupérés et transmis ; ceux de plus de 10 minutes ont replayed à true.
• Il est reconnecté avec un autre téléphone : le numéro de boîte et son webhook continuent pour le nouveau numéro (même whatsapp_client_id, nouveau whatsapp_phone) à partir de ce moment ; les anciennes discussions restent dans la boîte de réception comme historique.

Dépannage#

Voir aussi#

• Boîte de réception Unibox : lire les discussions de vos numéros de boîte et y répondre
• Intégration Zapier
• Connecter votre numéro WhatsApp
• Forfaits et facturation
• Envoyer un message (API) : son champ webhook indique si un message que vous envoyez est parti (un autre webhook)