Skip to Content
Wazend

Ereignisse

Empfange WhatsApp-Ereignisse in Echtzeit mit Webhooks und WebSockets: Payload-Struktur, HMAC, Wiederholungsversuche und vollständige Ereignisliste.

Um deine Anwendung über WhatsApp-Ereignisse zu benachrichtigen, kannst du Webhooks und WebSockets verwenden.

Webhooks

Webhooks ermöglichen zwei Anwendungen, in Echtzeit zu kommunizieren: Wenn ein Ereignis eintritt, sendet Wazend eine HTTP POST-Anfrage an deine URL.

Webhooks pro Sitzung

Konfiguriere die Webhooks pro Sitzung in der Sitzungskonfiguration:

Body
{
  "name": "S0001",
  "config": {
    "webhooks": [
      {
        "url": "https://tu-servidor.com/webhook",
        "events": ["message"],
        "hmac": { "key": "tu-clave-secreta" },
        "retries": {
          "policy": "constant",
          "delaySeconds": 2,
          "attempts": 15
        },
        "customHeaders": [
          { "name": "X-Mi-Header", "value": "Valor" }
        ]
      }
    ]
  }
}

Wiederholungsversuche

Verfügbare Wiederholungsrichtlinien:

  • constant — gleiche Verzögerung zwischen den Versuchen (2, 2, 2).
  • linear — lineares Backoff (2, 4, 6, 8).
  • exponential — exponentielles Backoff mit Jitter.

Headers

Jeder Webhook enthält diese Header:

  • X-Webhook-Request-Id — eindeutige ID der Anfrage.
  • X-Webhook-Timestamp — Unix-Zeitstempel in ms.
  • X-Webhook-Hmac — Authentifizierungscode des Bodys (wenn du HMAC verwendest).
  • X-Webhook-Hmac-Algorithm — verwendeter Algorithmus (sha512).

HMAC-Authentifizierung

Definiere deinen geheimen Schlüssel in config.hmac.key und verifiziere die Signatur im Header X-Webhook-Hmac (Algorithmus sha512) gegen den Body der Anfrage.

Body
{
  "name": "S0001",
  "config": {
    "webhooks": [
      {
        "url": "https://tu-servidor.com/webhook",
        "events": ["message"],
        "hmac": { "key": "tu-clave-secreta" }
      }
    ]
  }
}

Verifiziere immer die Signatur

Validiere die HMAC-Signatur, um deinen Endpunkt vor bösartigen Anfragen zu schützen.

Beispiele

Du kannst Abläufe mit n8n automatisieren.

WebSockets

Verwende WebSockets, um Nachrichten in Echtzeit zu empfangen.

# Alle Sitzungen und Events empfangen
websocat -E wss://latam-1.wazend.net/ws

# Mit API-Key
websocat -E wss://latam-1.wazend.net/ws?x-api-key=123

# Bestimmte Events empfangen
websocat -E "wss://latam-1.wazend.net/ws?session=*&events=session.status&events=message"

# Eine bestimmte Sitzung empfangen
websocat -E "wss://latam-1.wazend.net/ws?session=S0001&events=session.status"

Parameter:

  • session — Name der Sitzung oder * für alle.
  • events — Ereignisliste oder *.
  • x-api-key — dein API key.

Payload-Struktur

Ereignis
{
  "id": "evt_1111111111111111111111111111",
  "timestamp": 1741249702485,
  "event": "message",
  "session": "S0001",
  "metadata": {
    "user.id": "123",
    "user.email": "cliente@ejemplo.com"
  },
  "me": {
    "id": "5215551234567@c.us",
    "pushName": "Mi Nombre"
  },
  "payload": {
    "...": "eventspezifische Daten"
  },
  "environment": {
    "tier": "CORE",
    "version": "2023.10.12"
  },
  "engine": "NOWEB"
}

Metadaten

Du kannst benutzerdefinierte metadata beim Erstellen oder Aktualisieren der Sitzung senden; sie wird unverändert im Feld metadata jedes Webhook-Ereignisses enthalten sein. Dadurch kannst du Ereignisse an den richtigen Nutzer weiterleiten, ohne zusätzliche Abfragen an deine Datenbank.

Verfügbare Ereignisse

Zusammenfassung aller verfügbaren Ereignisse. Klicke auf jedes Ereignis, um zu seinen Details zu gelangen:

EreignisWofür es dient
session.statusStatusänderung der Sitzung (STOPPED, STARTING, SCAN_QR_CODE, WORKING, FAILED, PASSKEY).
engine.eventLow-Level-Ereignis der Engine zur Fehlersuche (nicht in events=* enthalten).
messageEingehende Nachricht (Text, Audio, Dateien).
message.anyAlle Nachrichten, einschließlich deiner eigenen.
message.reactionReaktion auf eine Nachricht.
message.ackBestätigung für Zustellung, Lesen oder Wiedergabe der Nachricht.
message.ack.groupBestätigung eines Teilnehmers in einer Gruppe.
message.waitingNachricht in Wartestellung („Warte auf diese Nachricht...“).
message.editedBearbeitete Nachricht.
message.revokedGelöschte (widerrufene) Nachricht.
chat.archiveChat archiviert oder dearchiviert.
group.v2.joinDu trittst einer Gruppe bei oder wirst hinzugefügt.
group.v2.leaveDu verlässt eine Gruppe oder wirst entfernt.
group.v2.participantsJemand tritt ein, verlässt, wird befördert oder herabgestuft.
group.v2.updateDie Gruppeninformationen werden aktualisiert.
presence.updatePräsenzaktualisierung (online, offline, tippend, aufnehmend).
poll.voteNeue Umfragestimmen.
poll.vote.failedNicht entschlüsselbare Umfragestimme.
event.responseAntwort auf eine Ereignisnachricht (GOING, NOT_GOING, MAYBE).
event.response.failedNicht entschlüsselbare Ereignisantwort.
label.upsertEtikett erstellt oder aktualisiert.
label.deletedEtikett gelöscht.
label.chat.addedEtikett zu einem Chat hinzugefügt.
label.chat.deletedEtikett von einem Chat entfernt.
call.receivedEingehender Anruf.
call.acceptedAnruf angenommen (auf einem anderen Gerät).
call.rejectedAnruf abgelehnt oder beendet.

session.status

Wird ausgelöst, wenn sich der Status der Sitzung ändert:

  • STOPPED die Sitzung ist gestoppt.
  • STARTING die Sitzung startet.
  • SCAN_QR_CODE Es ist erforderlich, den QR zu scannen oder sich per Telefon anzumelden. Wird jedes Mal ausgegeben, wenn sich der QR ändert; wenn du ihn empfängst, rufe den aktualisierten QR ab.
  • PASSKEY_REQUIRED WhatsApp verlangt einen Passkey (WebAuthn); data enthält die zu signierende Herausforderung.
  • PASSKEY_CONFIRMATION_REQUIRED der Nutzer muss einen Code verifizieren; data enthält den Code.
  • WORKING die Sitzung funktioniert und ist bereit.
  • FAILED die Sitzung ist fehlgeschlagen; versuche neu zu starten, und wenn nicht, melde dich ab und starte sie erneut.
Ereignis
{
  "event": "session.status",
  "session": "S0001",
  "payload": {
    "status": "WORKING",
    "statuses": [
      { "status": "STOPPED", "timestamp": 1700000001000 },
      { "status": "STARTING", "timestamp": 1700000002000 },
      { "status": "WORKING", "timestamp": 1700000003000 }
    ],
    "data": null
  }
}

status ist der aktuelle Status; statuses die letzten 3 Status; data enthält zusätzliche Statusinfos.

Beispiel mit PASSKEY_REQUIRED:

Ereignis
{
  "event": "session.status",
  "session": "S0001",
  "payload": {
    "status": "PASSKEY_REQUIRED",
    "statuses": [],
    "data": {
      "challenge": "9WVUYm9AsQ...",
      "timeout": 60000,
      "rpId": "web.whatsapp.com",
      "allowCredentials": [
        { "id": "AX8bTgH2...", "type": "public-key", "transports": ["internal", "hybrid"] }
      ],
      "userVerification": "required"
    }
  }
}

Beispiel mit PASSKEY_CONFIRMATION_REQUIRED:

Ereignis
{
  "event": "session.status",
  "session": "S0001",
  "payload": {
    "status": "PASSKEY_CONFIRMATION_REQUIRED",
    "statuses": [],
    "data": { "code": "1234" }
  }
}

Beispiel mit Kontaktsperre (Einschränkung des Sendens an neue Kontakte, Ursache des Fehlers 463):

Ereignis
{
  "event": "session.status",
  "session": "S0001",
  "payload": {
    "status": "WORKING",
    "statuses": [],
    "data": {
      "reachoutTimelock": {
        "enforcementType": "RESTRICT_ALL_COMPANIONS",
        "isActive": true,
        "timeEnforcementEnds": 1784477333
      }
    }
  }
}

Kontaktsperre

Starte NICHT neu, melde dich nicht ab und kopple nicht erneut: Die Einschränkung wird automatisch aufgehoben. Pausiere das Senden an neue Kontakte bis timeEnforcementEnds. Lies mehr unter So vermeidest du Sperren.

Beispiel mit Nachrichtenlimit (Kontingent pro Zyklus neuer Kontakte, Ursache des Fehlers 475):

Ereignis
{
  "event": "session.status",
  "session": "S0001",
  "payload": {
    "status": "WORKING",
    "statuses": [],
    "data": {
      "messageCapping": {
        "cappingStatus": "FIRST_WARNING",
        "totalQuota": 1000,
        "usedQuota": 640,
        "cycleStart": 1782874800,
        "cycleEnd": 1785553199,
        "mvStatus": "NOT_ELIGIBLE",
        "oteStatus": "NOT_ELIGIBLE"
      }
    }
  }
}

Nachrichtenlimit

Starte NICHT neu, melde dich nicht ab und kopple nicht erneut: Das Kontingent wird nicht zurückgesetzt. Bei cappingStatus CAPPED pausiere das Senden an neue Kontakte bis cycleEnd. Lies mehr unter So vermeidest du Sperren.

message

Eingehende Nachricht (Text/Audio/Dateien).

Ereignis
{
  "event": "message",
  "session": "S0001",
  "payload": {
    "id": "true_5215551234567@c.us_AAAAAAAAAAAAAAAA",
    "timestamp": 1667561485,
    "from": "5215551234567@c.us",
    "fromMe": true,
    "source": "app",
    "to": "5215551234567@c.us",
    "body": "Hallo!",
    "hasMedia": false,
    "ack": 1
  }
}
  • hasMedia — gibt an, ob die Nachricht Medien enthält.
  • media.url — URL zum Herunterladen der Medien.
  • source — app oder api (wenn du über die API sendest).
  • _data — interne Daten der Engine.

message.any

Wird bei allen Nachrichten ausgelöst, einschließlich deiner eigenen. Gleiche Payload wie message.

Ereignis
{
  "event": "message.any",
  "session": "S0001",
  "payload": {
    "id": "true_5215551234567@c.us_AAAAAAAAAAAAAAAA",
    "timestamp": 1667561485,
    "from": "5215551234567@c.us",
    "fromMe": true,
    "source": "api",
    "to": "5215551234567@c.us",
    "body": "Hallo!",
    "hasMedia": false,
    "ack": 1
  }
}

message.reaction

Reaktion auf eine Nachricht. reaction.text ist das Emoji (leer, wenn entfernt) und reaction.messageId die ID der reagierten Nachricht.

Ereignis
{
  "event": "message.reaction",
  "session": "S0001",
  "payload": {
    "id": "false_5215551234567@c.us_11111111111111111111111111111111",
    "from": "5215551234567@c.us",
    "fromMe": false,
    "reaction": {
      "text": "🙏",
      "messageId": "true_5215551234567@c.us_11111111111111111111111111111111"
    }
  }
}

message.ack

Bestätigung für Zustellung/Lesen der Nachricht:

  • ERROR, ack: -1 — ein Fehler ist aufgetreten.
  • PENDING, ack: 0 — ausstehende Nachricht.
  • SERVER, ack: 1 — an den Server gesendet.
  • DEVICE, ack: 2 — an das Gerät gesendet.
  • READ, ack: 3 — gelesen.
  • PLAYED, ack: 4 — abgespielt.
Ereignis
{
  "event": "message.ack",
  "session": "S0001",
  "payload": {
    "id": "true_5215551234567@c.us_4CC5EDD64BC22EBA6D639F2AF571346C",
    "from": "5215551234567@c.us",
    "fromMe": true,
    "ack": 3,
    "ackName": "READ"
  }
}

message.ack.group

Bestätigung eines Teilnehmers in einer Gruppe (enthält das Feld participant).

Ereignis
{
  "event": "message.ack",
  "session": "S0001",
  "payload": {
    "id": "true_5215551234567@g.us_4CC5EDD64BC22EBA6D639F2AF571346C_9999@lid",
    "from": "5215551234567@g.us",
    "participant": "9999@lid",
    "fromMe": true,
    "ack": 3,
    "ackName": "READ"
  }
}

message.waiting

Tritt auf, wenn auf dem Telefon „Warte auf diese Nachricht. Es kann ein wenig dauern“ erscheint.

Ereignis
{
  "event": "message.waiting",
  "session": "S0001",
  "payload": {
    "id": "true_5215551234567@c.us_AAAAAAAAAAAAAAAA",
    "timestamp": 1667561485,
    "from": "5215551234567@c.us",
    "fromMe": true,
    "to": "5215551234567@c.us",
    "_data": {}
  }
}

message.edited

Bearbeitete Nachricht. editedMessageId ist die ID der bearbeiteten Nachricht und body der neue Text. Die id des Ereignisses hat das Format false_chatId_messageId[_participant].

Ereignis
{
  "event": "message.edited",
  "session": "S0001",
  "payload": {
    "id": "false_5215551234567@c.us_AAAAAAAAAAAAAAAA[_5215551234567@c.us]",
    "editedMessageId": "AAAAAAAAAAAAAAAA",
    "body": "Nuevo texto",
    "_data": {}
  }
}

message.revoked

Gelöschte (widerrufene) Nachricht. revokedMessageId ist die ID der gelöschten Nachricht und after.id die des Widerrufsereignisses (Format false_chatId_messageId[_participant]).

Ereignis
{
  "event": "message.revoked",
  "session": "S0001",
  "payload": {
    "after": {
      "id": "false_5215551234567@c.us_AAAAAAAAAAAAAAAA",
      "_data": {}
    },
    "revokedMessageId": "AAAAAAAAAAAAAAAA",
    "before": null
  }
}

chat.archive

Chat archiviert oder dearchiviert.

Ereignis
{
  "event": "chat.archive",
  "session": "S0001",
  "payload": {
    "id": "5215551234567@c.us",
    "timestamp": 1667561485,
    "archived": true
  }
}

group.v2.join

Du trittst einer Gruppe bei oder wirst hinzugefügt.

Ereignis
{
  "event": "group.v2.join",
  "session": "S0001",
  "payload": {
    "group": {
      "id": "5215551234567@g.us",
      "subject": "Grupo de trabajo",
      "description": "Gruppenbeschreibung",
      "invite": "https://chat.whatsapp.com/invitecode",
      "membersCanAddNewMember": true,
      "membersCanSendMessages": true,
      "newMembersApprovalRequired": true,
      "participants": [
        { "id": "5219999999999@c.us", "role": "participant" }
      ]
    },
    "timestamp": 789456123
  }
}

group.v2.leave

Du verlässt eine Gruppe oder wirst entfernt.

Ereignis
{
  "event": "group.v2.leave",
  "session": "S0001",
  "payload": {
    "group": { "id": "5215551234567@g.us" },
    "timestamp": 789456123
  }
}

group.v2.participants

Jemand tritt ein, verlässt, wird befördert oder herabgestuft. type kann join, leave, promote oder demote sein.

Ereignis
{
  "event": "group.v2.participants",
  "session": "S0001",
  "payload": {
    "type": "join",
    "timestamp": 1666943582,
    "group": { "id": "5215551234567@g.us" },
    "participants": [
      { "id": "5219999999999@c.us", "role": "participant" }
    ],
    "_data": {}
  }
}

Mögliche Rollen: left, participant, admin und superadmin.

group.v2.update

Die Gruppeninformationen werden aktualisiert.

Ereignis
{
  "event": "group.v2.update",
  "session": "S0001",
  "payload": {
    "group": { "id": "5215551234567@g.us", "subject": "Neuer Gruppenname" },
    "timestamp": 789456123,
    "_data": {}
  }
}

presence.update

Präsenzaktualisierung. lastKnownPresence kann online, offline, typing, recording oder paused sein. Das Feld payload.id gibt den Chat an (direkt oder Gruppe) und participant den konkreten Teilnehmer (in direkten Chats gibt es nur einen).

Ereignis
{
  "event": "presence.update",
  "session": "S0001",
  "payload": {
    "id": "5215551234567@c.us",
    "presences": [
      {
        "participant": "5215551234567@c.us",
        "lastKnownPresence": "typing",
        "lastSeen": null
      }
    ]
  }
}

poll.vote

Du erhältst neue Umfragestimmen. Identifiziere deine mit poll.fromMe.

Ereignis
{
  "event": "poll.vote",
  "session": "S0001",
  "payload": {
    "vote": {
      "id": "false_5215551234567@c.us_83ACBE602A05C79B234B54415E95EE8A",
      "to": "me",
      "from": "5215551234567@c.us",
      "fromMe": false,
      "selectedOptions": ["Super!"],
      "timestamp": 1692861427
    },
    "poll": {
      "id": "true_5215551234567@c.us_BAE5F2EF5C69001E",
      "to": "5215551234567@c.us",
      "from": "me",
      "fromMe": true
    }
  }
}

poll.vote.failed

Wie poll.vote, aber mit leerem selectedOptions (die Stimme konnte nicht entschlüsselt werden).

Ereignis
{
  "event": "poll.vote.failed",
  "session": "S0001",
  "payload": {
    "vote": {
      "id": "false_5215551234567@c.us_2E8C4CDA89EDE3BC0BC7F605364B8451",
      "to": "me",
      "from": "5215551234567@c.us",
      "fromMe": false,
      "selectedOptions": [],
      "timestamp": 1692956972
    },
    "poll": {
      "id": "true_5215551234567@c.us_BAE595F4E0A2042C",
      "to": "5215551234567@c.us",
      "from": "me",
      "fromMe": true
    }
  }
}

event.response

Antwort auf eine Ereignisnachricht. eventResponse.response kann GOING, NOT_GOING oder MAYBE sein. Lies mehr unter Ereignisnachrichten.

Ereignis
{
  "id": "evt_00000000000000000000001",
  "session": "S0001",
  "event": "event.response",
  "payload": {
    "id": "false_5215551234567@c.us_58BBBBBBBBBBBBBBBBBBBBBBBB",
    "timestamp": 1747707858,
    "from": "5215551234567@c.us",
    "participant": null,
    "fromMe": false,
    "eventCreationKey": {
      "id": "false_5215551234567@c.us_3EBAAAAAAAAAAAAAAAAAAAAAAAAAA",
      "to": "me",
      "from": "5215551234567@c.us",
      "fromMe": false
    },
    "eventResponse": {
      "response": "GOING",
      "timestampMs": 1747707858429,
      "extraGuestCount": 0
    },
    "source": "app",
    "ack": null,
    "ackName": "UNKNOWN",
    "replyTo": null,
    "_data": {}
  }
}
  • eventCreationKey — Informationen zur ursprünglichen Ereignisnachricht (id, to, from, fromMe).
  • eventResponse.response — GOING, NOT_GOING oder MAYBE.
  • eventResponse.timestampMs — Unix-Zeitstempel in ms der Antwort.
  • eventResponse.extraGuestCount — zusätzliche Gäste (0 oder 1).
  • replyTo — Info zur Nachricht, auf die geantwortet wird (null wenn es keine Antwort ist).

event.response.failed

Die Antwort konnte nicht entschlüsselt werden (mit eventResponse: null). Sende die Ereignisnachricht erneut, um eine neue Antwort zu erhalten. Lies mehr unter Ereignisnachrichten.

Ereignis
{
  "id": "evt_00000000000000000000001",
  "session": "S0001",
  "event": "event.response.failed",
  "payload": {
    "id": "false_5215551234567@c.us_58BBBBBBBBBBBBBBBBBBBBBBBB",
    "timestamp": 1747707858,
    "from": "5215551234567@c.us",
    "participant": null,
    "fromMe": false,
    "eventCreationKey": {
      "id": "false_5215551234567@c.us_3EBAAAAAAAAAAAAAAAAAAAAAAAAAA",
      "to": "me",
      "from": "5215551234567@c.us",
      "fromMe": false
    },
    "eventResponse": null,
    "source": "app",
    "ack": null,
    "ackName": "UNKNOWN",
    "replyTo": null,
    "_data": {}
  }
}

label.upsert

Etikett erstellt oder aktualisiert.

Ereignis
{
  "event": "label.upsert",
  "session": "S0001",
  "payload": {
    "id": "10",
    "name": "Cliente VIP",
    "color": 14,
    "colorHex": "#00a0f2"
  }
}

label.deleted

Etikett gelöscht.

Ereignis
{
  "event": "label.deleted",
  "session": "S0001",
  "payload": {
    "id": "10",
    "name": "",
    "color": 14,
    "colorHex": "#00a0f2"
  }
}

label.chat.added

Etikett zu einem Chat hinzugefügt (labelId + chatId). Direkt nach dem Scannen des QR kann label null sein.

Ereignis
{
  "event": "label.chat.added",
  "session": "S0001",
  "payload": {
    "labelId": "6",
    "chatId": "5215551234567@c.us",
    "label": null
  }
}

label.chat.deleted

Etikett von einem Chat entfernt (labelId + chatId).

Ereignis
{
  "event": "label.chat.deleted",
  "session": "S0001",
  "payload": {
    "labelId": "6",
    "chatId": "5215551234567@c.us",
    "label": null
  }
}

call.received

Eingehender Anruf.

Ereignis
{
  "event": "call.received",
  "session": "S0001",
  "payload": {
    "id": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
    "from": "5215551234567@c.us",
    "timestamp": 1721374000,
    "isVideo": false,
    "isGroup": false
  }
}

call.accepted

Anruf angenommen (auf einem anderen Gerät).

Ereignis
{
  "event": "call.accepted",
  "session": "S0001",
  "payload": {
    "id": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
    "from": "5215551234567@c.us",
    "timestamp": 1721374000,
    "isVideo": false,
    "isGroup": false,
    "_data": {}
  }
}

call.rejected

Anruf abgelehnt oder beendet.

Ereignis
{
  "event": "call.rejected",
  "session": "S0001",
  "payload": {
    "id": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
    "from": "5215551234567@c.us",
    "timestamp": 1721374000,
    "isVideo": false,
    "isGroup": false,
    "_data": {}
  }
}

In der Engine WEBJS wird call.rejected nur ausgelöst, wenn du den Anruf über die API ablehnst.

engine.event

Low-Level-Ereignis der Engine, für Fehlersuche und Diagnose. Es ist nicht enthalten, wenn du dich mit events=* abonnierst; du musst es explizit angeben.

Ereignis
{
  "event": "engine.event",
  "session": "S0001",
  "engine": "NOWEB",
  "payload": {
    "event": "messages.upsert",
    "data": {}
  }
}