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:
{
"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.
{
"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
{
"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:
| Ereignis | Wofür es dient |
|---|---|
| session.status | Statusänderung der Sitzung (STOPPED, STARTING, SCAN_QR_CODE, WORKING, FAILED, PASSKEY). |
| engine.event | Low-Level-Ereignis der Engine zur Fehlersuche (nicht in events=* enthalten). |
| message | Eingehende Nachricht (Text, Audio, Dateien). |
| message.any | Alle Nachrichten, einschließlich deiner eigenen. |
| message.reaction | Reaktion auf eine Nachricht. |
| message.ack | Bestätigung für Zustellung, Lesen oder Wiedergabe der Nachricht. |
| message.ack.group | Bestätigung eines Teilnehmers in einer Gruppe. |
| message.waiting | Nachricht in Wartestellung („Warte auf diese Nachricht...“). |
| message.edited | Bearbeitete Nachricht. |
| message.revoked | Gelöschte (widerrufene) Nachricht. |
| chat.archive | Chat archiviert oder dearchiviert. |
| group.v2.join | Du trittst einer Gruppe bei oder wirst hinzugefügt. |
| group.v2.leave | Du verlässt eine Gruppe oder wirst entfernt. |
| group.v2.participants | Jemand tritt ein, verlässt, wird befördert oder herabgestuft. |
| group.v2.update | Die Gruppeninformationen werden aktualisiert. |
| presence.update | Präsenzaktualisierung (online, offline, tippend, aufnehmend). |
| poll.vote | Neue Umfragestimmen. |
| poll.vote.failed | Nicht entschlüsselbare Umfragestimme. |
| event.response | Antwort auf eine Ereignisnachricht (GOING, NOT_GOING, MAYBE). |
| event.response.failed | Nicht entschlüsselbare Ereignisantwort. |
| label.upsert | Etikett erstellt oder aktualisiert. |
| label.deleted | Etikett gelöscht. |
| label.chat.added | Etikett zu einem Chat hinzugefügt. |
| label.chat.deleted | Etikett von einem Chat entfernt. |
| call.received | Eingehender Anruf. |
| call.accepted | Anruf angenommen (auf einem anderen Gerät). |
| call.rejected | Anruf abgelehnt oder beendet. |
session.status
Wird ausgelöst, wenn sich der Status der Sitzung ändert:
STOPPEDdie Sitzung ist gestoppt.STARTINGdie Sitzung startet.SCAN_QR_CODEEs 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_REQUIREDWhatsApp verlangt einen Passkey (WebAuthn);dataenthält die zu signierende Herausforderung.PASSKEY_CONFIRMATION_REQUIREDder Nutzer muss einen Code verifizieren;dataenthält den Code.WORKINGdie Sitzung funktioniert und ist bereit.FAILEDdie Sitzung ist fehlgeschlagen; versuche neu zu starten, und wenn nicht, melde dich ab und starte sie erneut.
{
"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:
{
"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:
{
"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):
{
"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):
{
"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).
{
"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—appoderapi(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.
{
"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.
{
"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.
{
"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).
{
"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.
{
"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].
{
"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]).
{
"event": "message.revoked",
"session": "S0001",
"payload": {
"after": {
"id": "false_5215551234567@c.us_AAAAAAAAAAAAAAAA",
"_data": {}
},
"revokedMessageId": "AAAAAAAAAAAAAAAA",
"before": null
}
}chat.archive
Chat archiviert oder dearchiviert.
{
"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.
{
"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.
{
"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.
{
"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.
{
"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).
{
"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.
{
"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).
{
"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.
{
"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_GOINGoderMAYBE.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 (nullwenn 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.
{
"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.
{
"event": "label.upsert",
"session": "S0001",
"payload": {
"id": "10",
"name": "Cliente VIP",
"color": 14,
"colorHex": "#00a0f2"
}
}label.deleted
Etikett gelöscht.
{
"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.
{
"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).
{
"event": "label.chat.deleted",
"session": "S0001",
"payload": {
"labelId": "6",
"chatId": "5215551234567@c.us",
"label": null
}
}call.received
Eingehender Anruf.
{
"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).
{
"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.
{
"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.
{
"event": "engine.event",
"session": "S0001",
"engine": "NOWEB",
"payload": {
"event": "messages.upsert",
"data": {}
}
}