Se connecterCommencer l’essai gratuit
easyCoexistence API officielles

Savoir quand la connexion WhatsApp ou celle d'un compte social se coupe

easyCoexistence envoie à votre plateforme des événements de statut signés lorsqu'une connexion client se connecte, se coupe, est supprimée ou suspendue. Un numéro WhatsApp envoie connection.connected, connection.disconnected avec la raison donnée par Meta, connection.removed, connection.suspended ou connection.token_missing ; un compte social envoie les équivalents channel.*, sans token_missing. Chacun est un POST JSON signé avec X-EC-Signature et relancé avec un intervalle croissant pendant environ 33 heures, jusqu'à ce que votre endpoint réponde 2xx.

~14 days

PRIMARY_INACTIVITY : raison donnée par Meta lorsque l'appareil principal est resté inactif pendant environ 14 jours, déconnectant un numéro Coexistence.

~30 days

COMPANION_INACTIVITY : raison donnée par Meta lorsqu'un appareil associé est resté inactif pendant environ 30 jours.

account_update

Le webhook qui signale une déconnexion. Meta l'envoie toujours à l'URL de rappel par défaut de l'application, jamais à une adresse de remplacement.

7 attempts

Nouvelles tentatives d'un événement de statut après toute réponse hors 2xx, à intervalles de 1 minute à 24 heures, sur environ 33 heures.

5 minutes

Plus ancien horodatage signé t qu'un endpoint doit accepter pour un événement de statut, en comparant le HMAC en temps constant.

Quels sont les événements de statut ?

Neuf, en deux familles qui partagent un même endpoint et un même secret de signature. Les numéros utilisent connection.* et les comptes sociaux channel.*, donc un récepteur écrit pour les numéros peut ignorer les événements channel par leur nom. Définissez l'endpoint dans le dashboard, sous Profil puis Développeurs, ou avec l'outil MCP set_partner_events_url ; le secret de signature n'est affiché qu'une fois, au moment où l'URL est enregistrée.

connection.connectedA number connected, came back after a drop, or got its customer token on a second run.
connection.disconnectedMeta dropped the link; reason carries Meta's code when known.
connection.removedRemoved with DELETE /connections/{id} or from the dashboard.
connection.suspendedYour subscription lapsed; reason names its state.
connection.token_missingConnected without a customer token: it receives, but cannot send yet.
channel.connectedA social account connected, one event per Page when a sign-in brings several.
channel.disconnectedThe network refused the token, or the owner withdrew access.
channel.removedRemoved with DELETE /channels/{id} or from the dashboard, or the owner removed the app on Meta.
channel.suspendedYour subscription lapsed.

Qu'est-ce qu'un événement de connexion contient ?

L'id de la livraison, un UUID ; le nom de l'événement ; occurred_at au format ISO 8601 ; et un objet connection avec id, external_ref, connect_session_id, phone, name, waba_id, phone_number_id, status et token_ready. Certains événements ajoutent un champ de premier niveau : reason sur connection.disconnected et connection.suspended, detected_by valant health_check lorsque la vérification périodique d'easyCoexistence a détecté la coupure plutôt que le webhook de Meta, et connect_session_id lorsqu'une session de connexion a produit l'événement.

connection.disconnected
{
  "id": "5c2a9e70-…",
  "event": "connection.disconnected",
  "occurred_at": "2026-10-31T10:15:02.114Z",
  "connection": {
    "id": "<CONNECTION_ID>",
    "external_ref": "customer_4821",
    "connect_session_id": "cs_…",
    "phone": "+55 11 9…",
    "name": "Clínica Sorriso",
    "waba_id": "<WABA_ID>",
    "phone_number_id": "<PHONE_NUMBER_ID>",
    "status": "disconnected",
    "token_ready": true
  },
  "reason": "PRIMARY_INACTIVITY"
}

Qu'est-ce qu'un événement channel contient ?

La même enveloppe, avec un objet channel à la place de connection. C'est la vue de GET /channels/{id} : id, channel pour le réseau, external_ref, connect_session_id, name, username, external_id, status, token_ready, webhook_url, disconnected_reason, last_checked_at et created_at. Il n'existe pas de token_missing pour les channels, car une connexion sociale fournit toujours le token propre au client, et un channel.connected issu d'une session de connexion porte aussi connect_session_id au premier niveau.

channel.disconnected
{
  "id": "0b7e41d2-…",
  "event": "channel.disconnected",
  "occurred_at": "2026-10-31T10:15:02.114Z",
  "channel": {
    "id": "<CHANNEL_ID>",
    "channel": "tiktok",
    "external_ref": "customer_4821",
    "connect_session_id": "cs_…",
    "name": "Clínica Sorriso",
    "username": "clinicasorriso",
    "external_id": "<TIKTOK_OPEN_ID>",
    "status": "disconnected",
    "token_ready": false,
    "webhook_url": "https://hooks.example.com/social",
    "disconnected_reason": "<THE_NETWORK'S_MESSAGE>",
    "last_checked_at": "2026-10-31T10:15:02.000Z",
    "created_at": "2026-10-28T16:40:09.000Z"
  }
}

Que signifient les raisons de déconnexion ?

reason sur connection.disconnected est le code que Meta a placé dans disconnection_info de son webhook account_update, que Meta inclut pour les numéros de l'application WhatsApp Business comme pour la Cloud API. Il vaut null lorsque Meta n'en a fourni aucun. Les codes dans la référence de Meta :

  • PRIMARY_INACTIVITY : le téléphone qui fait tourner l'application WhatsApp Business est resté inactif pendant environ 14 jours, la règle des 14 jours. Une nouvelle session de connexion reconnecte le numéro.
  • ACCOUNT_DISCONNECTED : le compte a été déconnecté par une mesure d'application de Meta ou par le client, qui a pu retirer l'accès ou supprimer le compte.
  • COMPANION_INACTIVITY : un appareil associé est resté inactif pendant environ 30 jours.
  • BUSINESS_DOWNGRADE : le numéro était enregistré auprès de l'application WhatsApp grand public.
  • CHANGE_NUMBER et USER_RE_REGISTERED : le client a changé de numéro, ou l'a enregistré à nouveau sur un nouvel appareil.

Quels en-têtes accompagnent un événement de statut ?

Cinq, à chaque tentative : Content-Type application/json, User-Agent easyCoexistence-webhooks/1, X-EC-Event avec le nom de l'événement, X-EC-Delivery avec le même id que le corps, et X-EC-Signature. La signature se présente sous la forme t=<unix>,v1=<hex>, où v1 est le HMAC-SHA256 de t, d'un point et du corps brut, avec pour clé le secret de signature de votre compte, qui commence par whsec_. Chaque tentative est signée à nouveau, donc une relance porte un nouveau t sur le même corps.

Python: verify, then handle each id once
import hashlib, hmac, json, os, time

SECRET = os.environ["EC_EVENTS_SECRET"].encode()  # whsec_..., shown once in Profile > Developers

def verify(raw: bytes, header: str) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(",") if "=" in p)
    t, v1 = parts.get("t", ""), parts.get("v1", "")
    if not t.isdigit() or abs(time.time() - int(t)) > 300:
        return False  # missing, or more than 5 minutes off
    mac = hmac.new(SECRET, t.encode() + b"." + raw, hashlib.sha256).hexdigest()
    return hmac.compare_digest(mac, v1)

def handle(raw: bytes, headers) -> int:
    if not verify(raw, headers.get("X-EC-Signature", "")):
        return 401
    event = json.loads(raw)
    if already_processed(event["id"]):  # the X-EC-Delivery id, the same on every retry
        return 200
    enqueue(event)  # act on event["event"]; the latest occurred_at wins
    return 200

Comment les livraisons échouées sont-elles relancées ?

La première tentative part au moment où l'événement se produit. Une réponse hors 2xx, l'absence de réponse sous 10 secondes, une erreur réseau ou une redirection comptent comme un échec : l'événement est retenté à intervalles croissants, de 1 minute à 24 heures, sept tentatives au total sur environ 33 heures, avant d'être abandonné. Les livraisons ne partent que vers une adresse HTTPS dont la résolution donne une IP publique. Un événement survenu alors qu'aucun endpoint n'est défini n'est jamais mis en file d'attente, et supprimer l'endpoint arrête toutes les livraisons en attente.

Pourquoi traiter chaque id une seule fois et vérifier occurred_at ?

Parce qu'une relance répète la livraison à l'identique, avec le même id dans le corps et dans X-EC-Delivery, et parce qu'un événement relancé peut arriver après un plus récent. Conservez les id déjà traités et ignorez les répétitions. Comparez ensuite occurred_at avec le dernier état enregistré pour cette connexion, ou lisez GET /connections/{id} ou GET /channels/{id} avant d'agir sur un événement qui pourrait être périmé.

Que doit faire une plateforme quand un numéro se coupe ?

Agir selon la raison. Après PRIMARY_INACTIVITY, demandez au client d'ouvrir l'application WhatsApp Business et envoyez-lui une nouvelle session de connexion pour le même numéro. La reconnexion sur le même compte WhatsApp Business conserve son identifiant de connexion, rétablit votre destination de webhook et envoie connection.connected ; relisez alors ses identifiants. connection.token_missing signifie au contraire que Meta n'a délivré aucun token lors de cette opération. Meta n'envoie le webhook account_update à l'origine d'une coupure qu'au rappel propre à l'application, jamais à votre URL : cet événement est donc le seul moyen pour votre plateforme d'en être informée.

Que doit faire une plateforme quand un compte social se coupe ?

Sur channel.disconnected, une nouvelle session de connexion avec le même channel reconnecte le compte sous le même identifiant de channel. channel.removed signifie que l'accès est perdu : le token est oublié et la destination du webhook effacée, donc redéfinissez-la si le client se reconnecte. Un numéro ou un channel suspendu revient une fois que votre abonnement est de nouveau actif, en le reconnectant.

Erreurs courantes

  • Traiter une relance comme un nouvel événement. Elle porte le même id dans le corps et dans X-EC-Delivery : enregistrez donc les id traités, sinon une seule coupure peut alerter un client deux fois.
  • Appliquer les événements dans l'ordre d'arrivée. Un événement relancé peut arriver après un plus récent : comparez occurred_at, ou relisez la connexion avant d'agir.
  • Réenregistrer l'URL des événements pour corriger une faute de frappe sans mettre à jour le backend. L'enregistrement émet un nouveau secret de signature, et chaque livraison échoue à la vérification tant que votre endpoint ne l'utilise pas.
  • Faire le travail avant de répondre. Un traitement de plus de 10 secondes compte comme un échec et l'événement revient : répondez donc 2xx d'abord, puis traitez.
Faire cela avec EasyCoexistence

easyCoexistence surveille en permanence le numéro WhatsApp et les comptes sociaux de chaque client, et envoie à votre plateforme un événement signé lorsqu'un compte se connecte, se coupe, est supprimé ou suspendu, avec la raison donnée par Meta pour un numéro qui se coupe. De US$ 9 à US$ 0,75 par connexion et par mois, dégressif à mesure que vous ajoutez des connexions, avec les 3 premiers jours gratuits.

Questions fréquemment posées

Que signifie PRIMARY_INACTIVITY ?

C'est la raison donnée par Meta pour déconnecter un numéro Coexistence dont l'application WhatsApp Business est restée inactive sur son appareil principal pendant environ 14 jours. Une nouvelle session de connexion pour ce client reconnecte le numéro.

Les événements de statut incluent-ils les messages ?

Non. Ils concernent l'état d'une connexion. Les messages d'un numéro partent de Meta vers sa propre destination de webhook, et les commentaires et messages privés sociaux vers la destination de chaque channel.

Où définir l'URL des événements ?

Dans le dashboard, sous Profil puis Développeurs, ou avec l'outil MCP set_partner_events_url. Le secret de signature n'est affiché qu'une fois, et réenregistrer l'URL en émet un nouveau.

Puis-je ignorer les événements channel si je ne gère que les numéros ?

Oui. Les événements channel.* ont leurs propres noms et portent un objet channel au lieu de connection, donc un récepteur peut ignorer tout événement dont le nom ne commence pas par connection.

Poursuivre la lecture

Connectez votre premier canal en deux minutes.

Aucune validation de plateforme à attendre. Connectez WhatsApp, Instagram, TikTok ou un autre canal, puis demandez à votre IA de publier, de répondre ou de faire un rapport, et regardez-la travailler.

  • 3 jours gratuits
  • Résiliable à tout moment
  • API officielles uniquement
  • Supervisé 24/7

Vérifié le