AnmeldenKostenlose Testphase starten
easyCoexistence Offizielle APIs

Wie Sie erkennen, wann die WhatsApp- oder Social-Media-Verbindung eines Kunden abbricht

easyCoexistence sendet der Plattform signierte Status-Events, wenn eine Kundenverbindung hergestellt, unterbrochen, entfernt oder gesperrt wird. Eine WhatsApp-Nummer sendet connection.connected, connection.disconnected mit dem Grund von Meta, connection.removed, connection.suspended oder connection.token_missing; ein Social-Media-Konto sendet die entsprechenden channel.*-Events, ohne token_missing. Jedes ist ein JSON-POST, mit X-EC-Signature signiert und mit wachsenden Pausen rund 33 Stunden lang wiederholt, bis Ihr Endpoint mit 2xx antwortet.

~14 days

PRIMARY_INACTIVITY: Grund von Meta, wenn das primäre Gerät etwa 14 Tage inaktiv war und dadurch eine Coexistence-Nummer getrennt wird.

~30 days

COMPANION_INACTIVITY: Grund von Meta, wenn ein Companion-Gerät etwa 30 Tage inaktiv war.

account_update

Der Webhook, der eine Trennung meldet. Meta sendet ihn immer an die Standard-Callback-URL der App, nie an eine Überschreibung.

7 attempts

Wie oft ein Status-Event nach jeder Antwort außerhalb von 2xx erneut versucht wird, mit Abständen von 1 Minute bis 24 Stunden, über rund 33 Stunden.

5 minutes

Ältester signierter Zeitstempel t, den ein Endpoint bei einem Status-Event akzeptieren sollte; der HMAC wird in konstanter Zeit verglichen.

Welche Status-Events gibt es?

Neun, in zwei Familien, die einen Endpoint und ein Signing-Secret teilen. Nummern verwenden connection.* und Social-Media-Konten channel.*, sodass ein Empfänger für Nummern channel-Events anhand des Namens überspringen kann. Den Endpoint setzen Sie im Dashboard unter Profil, dann Developers, oder mit dem MCP-Tool set_partner_events_url; das Signing-Secret wird einmal angezeigt, wenn die URL gespeichert wird.

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.

Was enthält ein connection-Ereignis?

Die id der Zustellung, eine UUID; den Ereignisnamen; occurred_at im Format ISO 8601; und ein connection-Objekt mit id, external_ref, connect_session_id, phone, name, waba_id, phone_number_id, status und token_ready. Einige Ereignisse ergänzen ein Feld auf oberster Ebene: reason bei connection.disconnected und connection.suspended, detected_by mit dem Wert health_check, wenn die eigene periodische Prüfung von easyCoexistence die Trennung statt des Webhooks von Meta gefunden hat, und connect_session_id, wenn eine Connect-Session das Ereignis ausgelöst hat.

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"
}

Was enthält ein Channel-Ereignis?

Dieselbe Hülle mit einem channel-Objekt anstelle von connection. Es entspricht der Ansicht GET /channels/{id}: id, channel für das Netzwerk, external_ref, connect_session_id, name, username, external_id, status, token_ready, webhook_url, disconnected_reason, last_checked_at und created_at. Für Channels gibt es kein token_missing, da eine Social-Anmeldung immer das eigene Token des Kunden liefert. Ein channel.connected aus einer Connect-Session trägt connect_session_id ebenfalls auf oberster Ebene.

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"
  }
}

Was bedeuten die Trenngründe?

reason bei connection.disconnected ist der Code, den Meta in disconnection_info seines account_update-Webhooks angibt; Meta liefert ihn für Nummern sowohl in der WhatsApp-Business-App als auch in der Cloud API. Er ist null, wenn Meta keinen Grund angibt. Die Codes laut Metas Referenz:

  • PRIMARY_INACTIVITY: Das Telefon mit der WhatsApp-Business-App war etwa 14 Tage inaktiv, die 14-Tage-Regel. Eine neue Connect-Session verbindet die Nummer wieder.
  • ACCOUNT_DISCONNECTED: Das Konto wurde durch Metas Durchsetzung oder durch den Kunden getrennt; der Kunde kann den Zugriff entzogen oder das Konto gelöscht haben.
  • COMPANION_INACTIVITY: Ein Companion-Gerät war etwa 30 Tage inaktiv.
  • BUSINESS_DOWNGRADE: Die Nummer war bei der Verbraucher-App WhatsApp registriert.
  • CHANGE_NUMBER und USER_RE_REGISTERED: Der Kunde hat die Nummer geändert oder auf einem neuen Gerät erneut registriert.

Welche Header kommen mit einem Status-Event?

Fünf, bei jedem Versuch: Content-Type application/json, User-Agent easyCoexistence-webhooks/1, X-EC-Event mit dem Ereignisnamen, X-EC-Delivery mit derselben id wie im Body, und X-EC-Signature. Die Signatur lautet t=<unix>,v1=<hex>; dabei ist v1 der HMAC-SHA256 von t, einem Punkt und dem rohen Body, geschlüsselt mit dem Signing-Secret Ihres Kontos, das mit whsec_ beginnt. Jeder Versuch wird neu signiert, sodass eine Wiederholung ein neues t über denselben Body trägt.

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

Wie werden fehlgeschlagene Zustellungen wiederholt?

Der erste Versuch wird gesendet, sobald das Ereignis eintritt. Eine Antwort außerhalb von 2xx, keine Antwort innerhalb von 10 Sekunden, ein Netzwerkfehler oder eine Weiterleitung gilt als Fehler. Das Ereignis wird dann mit wachsenden Abständen von 1 Minute bis 24 Stunden erneut versucht, insgesamt siebenmal über rund 33 Stunden, bevor es verworfen wird. Zugestellt wird nur an eine HTTPS-Adresse, die auf eine öffentliche IP-Adresse aufgelöst wird. Ein Ereignis, das eintritt, während kein Endpoint gesetzt ist, wird nie in eine Warteschlange gestellt, und das Entfernen des Endpoints stoppt alle ausstehenden Zustellungen.

Warum sollte jede id nur einmal verarbeitet und occurred_at geprüft werden?

Weil eine Wiederholung die Zustellung exakt wiederholt, mit derselben id im Body und in X-EC-Delivery, und weil ein wiederholtes Ereignis nach einem neueren eintreffen kann. Speichern Sie die verarbeiteten ids und überspringen Sie Wiederholungen. Vergleichen Sie danach occurred_at mit dem letzten Zustand, den Sie für diese Verbindung gespeichert haben, oder lesen Sie GET /connections/{id} bzw. GET /channels/{id}, bevor Sie auf ein Ereignis reagieren, das veraltet sein könnte.

Was sollte eine Plattform tun, wenn eine Nummer getrennt wird?

Handeln Sie nach dem Grund. Nach PRIMARY_INACTIVITY bitten Sie den Kunden, die WhatsApp-Business-App zu öffnen, und senden Sie ihm eine neue Connect-Session für dieselbe Nummer. Die erneute Verbindung über dasselbe WhatsApp-Business-Konto behält die Verbindungs-ID, stellt Ihr Webhook-Ziel wieder her und sendet connection.connected; danach lesen Sie die Zugangsdaten erneut. connection.token_missing bedeutet dagegen, dass Meta bei diesem Durchlauf kein Token ausgestellt hat. Meta sendet das account_update, das einer Trennung zugrunde liegt, nur an den eigenen Callback der App, nie an Ihre URL; deshalb erfährt Ihre Plattform nur über dieses Ereignis davon.

Was sollte eine Plattform tun, wenn ein Social-Media-Konto getrennt wird?

Bei channel.disconnected meldet eine neue Connect-Session mit demselben Channel das Konto erneut an, unter derselben Channel-ID. channel.removed bedeutet, dass der Zugriff weg ist: das Token wird vergessen und ein eventuelles Webhook-Ziel gelöscht. Setzen Sie das Ziel daher erneut, wenn der Kunde sich wieder verbindet. Eine gesperrte Nummer oder ein gesperrter Channel kommt zurück, indem Sie ihn erneut verbinden, sobald Ihr Abonnement wieder aktiv ist.

Häufige Fehler

  • Eine Wiederholung als neues Ereignis behandeln. Sie trägt dieselbe id im Body und in X-EC-Delivery; speichern Sie also verarbeitete ids, sonst kann eine einzige Trennung einen Kunden zweimal alarmieren.
  • Ereignisse in Eingangsreihenfolge anwenden. Ein wiederholtes Ereignis kann nach einem neueren landen; vergleichen Sie daher occurred_at oder lesen Sie die Verbindung, bevor Sie handeln.
  • Die Events-URL erneut speichern, um einen Tippfehler zu korrigieren, ohne das Backend anzupassen. Beim Speichern entsteht ein neues Signing-Secret, und jede Zustellung schlägt bei der Prüfung fehl, bis Ihr Endpoint es verwendet.
  • Die Arbeit vor der Antwort erledigen. Ein Handler, der länger als 10 Sekunden braucht, gilt als fehlgeschlagen und das Ereignis kommt zurück; antworten Sie also zuerst mit 2xx und verarbeiten Sie danach.
Mit EasyCoexistence

easyCoexistence überwacht die WhatsApp-Nummer und Social-Media-Konten jedes Kunden rund um die Uhr und sendet Ihrer Plattform ein signiertes Ereignis, wenn eine Verbindung hergestellt, unterbrochen, entfernt oder gesperrt wird, bei einer getrennten Nummer mit dem Grund von Meta. Ab US$ 9 pro Verbindung und Monat, sinkend bis auf US$ 0.75, je mehr Verbindungen Sie hinzufügen; die ersten 3 Tage sind kostenlos.

Häufig gestellte Fragen

Was bedeutet PRIMARY_INACTIVITY?

Das ist der Grund von Meta, eine Coexistence-Nummer zu trennen, deren WhatsApp-Business-App auf dem primären Gerät etwa 14 Tage ungenutzt blieb. Eine neue Connect-Session für diesen Kunden verbindet die Nummer wieder.

Enthalten Status-Events Nachrichten?

Nein. Sie betreffen den Status einer Verbindung. Nachrichten einer Nummer gehen von Meta an deren eigenes Webhook-Ziel, Social-Media-Kommentare und DMs an das Ziel jedes Channels.

Wo setze ich die Events-URL?

Im Dashboard unter Profil, dann Developers, oder mit dem MCP-Tool set_partner_events_url. Das Signing-Secret wird einmal angezeigt, und wenn Sie die URL erneut speichern, wird ein neues ausgestellt.

Kann ich Channel-Ereignisse ignorieren, wenn ich nur Nummern verwalte?

Ja. channel.*-Ereignisse haben eigene Namen und enthalten ein channel-Objekt statt connection, sodass ein Empfänger jedes Ereignis überspringen kann, dessen Name nicht mit connection beginnt.

Weiterlesen

Verbinden Sie Ihren ersten Kanal in zwei Minuten.

Keine Plattform-Prüfungen, auf die Sie warten müssen. Verbinden Sie WhatsApp, Instagram, TikTok oder einen anderen Kanal, bitten Sie dann Ihre KI, zu posten, zu antworten oder Berichte zu erstellen, und sehen Sie ihr bei der Arbeit zu.

  • 3 Tage kostenlos
  • Jederzeit kündbar
  • Nur offizielle APIs
  • Überwacht rund um die Uhr (24/7)

Verifiziert am