Callback-API

Übersicht

Die Daten zu „Nachrichtenstatus“ und „Nachrichtenantwort“ werden an das Geschäftssystem des Unternehmens zurückgespielt. Diese Informationen können beispielsweise für Statistiken oder zur Beantwortung von Nutzeranfragen verwendet werden.

Callback-Adresse

Unternehmen müssen Callback-Adressen einrichten, um Nachrichtenstatus und Nachrichtenantworten zu empfangen. Weitere Informationen finden Sie unter Callback-Einstellungen.

Callback-Format

Die Anfragemethode ist POST, der Request-Body ist im JSON-Format und der Datentyp ist „Content-Type: application/json“.
Es werden jeweils mehrere Datensätze gleichzeitig zurückgegeben.

Sicherheitsmechanismus

Der Dienst muss online sein. Aktuell enthält der Callback keine Authentifizierungsinformationen. Daher sollte für die API, die den Callback empfängt, keine Berechtigungsprüfung eingerichtet werden.

Antwortmechanismus

Nach Erhalt des EngageLab-Callbacks muss der Entwicklerdienst innerhalb von 3 Sekunden wie folgt antworten:
Erfolgreich empfangen: Der HTTP-Response-Statuscode muss 200 zurückgeben, eine Antwortnachricht ist nicht erforderlich.

Retry-Mechanismus

Der Dienst muss online sein.

Anfrageparameter

EngageLab sendet folgende Anfrageparameter an die Callback-Adresse des Geschäftssystems:

Feld	Typ	Option	Beschreibung
total	int	erforderlich	Anzahl der Callback-Datensätze
rows	JSON Array	erforderlich	Details der Callback-Daten

Die Parameter in rows sind wie folgt:

Feld	Typ	Option	Beschreibung
message_id	string	optional	Status und Antwort der Nachricht.
from	string	optional	Absender, Nachrichtenstatus, wird beim Versand einer Upstream-Nachricht zurückgegeben.
to	string	optional	Empfänger, Nachrichtenstatus und Upstream-Nachricht.
server	string	erforderlich	Produktservice, zu dem die Callback-Information gehört. Fester Wert: whatsapp.
channel	string	optional	Kanal, zu dem Status oder Antwort gehören. Fester Wert: whatsapp.
itime	int	erforderlich	Zeitstempel, der durch die Callback-Daten generiert wurde. Über das Feld message_status können Sie den Anfrage-, Sende-, Zustell- und Lesetimestamp abrufen.
custom_args	JSON Object	optional	Optionale Felder, die beim Senden der Nachricht individuell angepasst wurden. Diese werden beim Nachrichtenstatus-Callback zurückgegeben.
status	JSON Object	optional	Nachrichtenstatus-Feld
response	JSON Object	optional	Nachrichtenantwort-Feld

Nachrichtenstatus – Status

Callback-Parameter

Feld	Typ	Option	Beschreibung
message_status	string	erforderlich	Status der Nachricht.
status_data	JSON Object	optional	Detaillierte Daten zu diesem Status
error_code	int	optional	Fehlercode. Bei Fehlern wird der Fehlercode zurückgegeben.
error_detail	JSON Object	optional	Fehlerdetails. Bei Fehlern wird die Fehlermeldung zurückgegeben.
loss	JSON Object	optional	Verlustphase und -quelle

message_status – Werte und Beschreibung

Wert	Beschreibung	Definition
plan	Geplante Zustellung	Die Nummer ist unter den „Empfängernummern“ und dokumentiert den Status eines geplanten Versandziels.
target_valid	Gültiges Ziel	Gültigkeitsprüfung bestanden 1. Die Nummer wurde von EngageLab als gültig erkannt. 2. Die Nummer wurde vom Meta WhatsApp Service als gültig erkannt.
sent	Erfolgreich gesendet	Fehlermeldung, nachdem EngageLab die Nummer an den Meta WhatsApp Service übergeben hat.
delivered	Erfolgreich zugestellt	Der Meta WhatsApp Service bestätigt, dass die Nachricht beim Nutzer zugestellt wurde.
read	Gelesen	Der Meta WhatsApp Service bestätigt, dass der Nutzer die Nachricht gelesen hat.
target_invalid	Ziel ungültig	1. Die Nummer wurde von EngageLab als ungültig erkannt. 2. Die Nummer wurde vom Meta WhatsApp Service als ungültig erkannt.
sent_failed	Senden fehlgeschlagen	Fehlermeldung nach Übergabe der Nummer an den Meta WhatsApp Service.
delivered_failed	Zustellung fehlgeschlagen	Die Nummer wurde an den Meta WhatsApp Service übergeben, aber der Meta-Callback ist fehlgeschlagen.
delivered_timeout	Nicht zugestellt nach Timeout	Die Nummer wurde erfolgreich an den Meta WhatsApp Service übergeben, aber Meta hat innerhalb von 5 Minuten keine Rückmeldung zum Erfolg/Misserfolg gegeben. Dies wird als Timeout gewertet.

status_data

Feld	Typ	Option	Beschreibung
msg_time	int	erforderlich	Zeitpunkt, zu dem die Nachricht gesendet wurde.
channel_message_id	String	erforderlich	Die von WhatsApp zurückgegebene Nachrichten-ID.
whatsapp_business_account_id	String	erforderlich	ID des WhatsApp Business Accounts, von dem die Nummer stammt.
timezone	String	erforderlich	Zeitzone der Organisation
plan_user_total	int	optional	Gesamtanzahl der geplanten Ziele. Nur bei message_status = plan vorhanden.
country_code	String	erforderlich	Ländervorwahl der Empfängernummer.
from_phone_id	String	erforderlich	ID der Absendernummer (from)
conversation	JSON Object	optional	Sitzungsinformationen
pricing	JSON Object	optional	Preisinformationen

conversation

Feld	Typ	Option	Beschreibung
id	String	optional	ID der Meta-Konversation, zu der die Nachricht gehört.
origin	JSON Object	optional	Wer die Konversation initiiert hat. Angegeben durch type. Beispiel: "origin":{"type":"business_initiated"}. Gültige Werte: business_initiated: Die Konversation startet, wenn das Unternehmen die erste Nachricht an den Kunden sendet (mehr als 24 Stunden seit der letzten Kundennachricht). customer_initiated: Die Konversation startet, wenn das Unternehmen auf die Nachricht des Kunden antwortet (Antwort innerhalb von 24 Stunden nach letzter Kundennachricht). referral_conversion: Die Konversation stammt von einem kostenlosen Einstiegspunkt. Diese Konversationen werden immer vom Kunden initiiert.

pricing

Feld	Typ	Option	Beschreibung
pricing_model	String	optional	Fester Wert: CBP
category	String	optional	Kategorie der Dialogpreisgestaltung. Gültige Werte: business_initiated: Händler-Konversation. customer_initiated: Nutzer-Konversation. referral_conversion: Konversation über kostenlosen Zugangspunkt.

error_detail

Feld	Typ	Option	Beschreibung
message	String	erforderlich	Ursache

loss

Feld	Typ	Option	Beschreibung
loss_step	int	erforderlich	Verlustphase 1: Von geplantem Ziel zu effektivem Ziel, d. h. ungültiges Ziel 2: Gültiges Ziel bis Senden, d. h. Senden fehlgeschlagen 3: Senden bis Zustellung. Zustellung fehlgeschlagen
loss_source	String	erforderlich	Quelle des Verlusts. Gültige Werte: engagelab: EngageLab WhatsApp-Verlust durch Serviceprüfung meta: Fehler von Meta zurückgegeben.

Callback-Beispiel

{ "total": 1, "rows": [ { "message_id": "1666165485030094861", "from": "", "to": "", "server": "whatsapp", "channel": "whatsapp", "itime": 1640707579, "custom_args": {}, "status": { "message_status": "delivered", "status_data": { "msg_time": 1663432355, "channel_message_id": "wamid.123321abcdefed==", "whatsapp_business_account_id": "", "timezone": "", "plan_user_total": 2007, "country_code": "CN", "from_phone_id": "111111", "conversation": { "id": "ebe2398cdaa37a0899ca5268b987b0c8", "origin": { "type": "business_initiated" } }, "pricing": { "pricing_model": "CBP", "category": "business_initiated" } }, "error_code": 0, "error_detail": { "message": "" }, "loss": { "loss_step": 1, "loss_source": "aa" } } } ] }

              
              {
    "total": 1,
    "rows": [
        {
            "message_id": "1666165485030094861",
            "from": "",
            "to": "",
            "server": "whatsapp",
            "channel": "whatsapp",
            "itime": 1640707579,
            "custom_args": {},
            "status": {
                "message_status": "delivered",
                "status_data": {
                    "msg_time": 1663432355,
                    "channel_message_id": "wamid.123321abcdefed==",
                    "whatsapp_business_account_id": "",
                    "timezone": "",
                    "plan_user_total": 2007,
                    "country_code": "CN",
                    "from_phone_id": "111111",
                    "conversation": {
                        "id": "ebe2398cdaa37a0899ca5268b987b0c8",
                        "origin": {
                            "type": "business_initiated"
                        }
                    },
                    "pricing": {
                        "pricing_model": "CBP",
                        "category": "business_initiated"
                    }
                },
                "error_code": 0,
                "error_detail": {
                    "message": ""
                },
                "loss": {
                    "loss_step": 1,
                    "loss_source": "aa"
                }
            }
        }
    ]
}

Diesen Codeblock im schwebenden Fenster anzeigen

Nachrichtenantwort

Callback-Parameter

Feld	Typ	Option	Beschreibung
event	string	optional	Antwortereignis
response_data	JSON Object	optional	Inhalt der Upstream-Antwort/Interaktion

event

Wert	Beschreibung	Details
received	Empfangene Nutzernachricht	Der Nutzer hat eine Nachricht direkt gesendet.
reply	Nutzer hat auf Ihre Nachricht geantwortet.	Das Unternehmen sendet zuerst eine Nachricht, der Nutzer antwortet darauf.
order	Nutzerbestellung	-
deleted	Nutzer hat seine Nachricht gelöscht.	Der Nutzer hat die von ihm gesendete Nachricht gelöscht (in Vorbereitung).

response_data

Feld	Typ	Option	Beschreibung
channel_message_id	String	erforderlich	Die von WhatsApp zurückgegebene Nachrichten-ID.
whatsapp_business_account_id	String	erforderlich	ID des WhatsApp Business Accounts, von dem die Nummer stammt.
contact	JSON Object	optional	Absenderinformationen
message	JSON Object	erforderlich	Nachrichteninhalt
message_context	JSON Object	Optional	Nachrichtenkontext, erscheint beim reply-Event und gibt an, auf welche Nachricht der Nutzer geantwortet hat

contact

Feld	Typ	Option	Beschreibung
profile	JSON Object	optional	Informationen des Absenders (Kunde). Aktuell gibt nur das Feld name den Kundennamen an. Beispiel: "profile": {"name": "bob"}
wa_id	String	optional	Nummer des Absenders.

message

Feld	Typ	Option	Beschreibung
type	String	erforderlich	Gültige Werte: text, image, audio, video, document, sticker, button, interactive, unknown, order.
text	JSON Object	optional	Weitere Informationen siehe Textobjekt-Beschreibung
image	JSON Object	optional	Weitere Informationen siehe Bildobjekt-Beschreibung
audio	JSON Object	optional	Weitere Informationen siehe Audioobjekt-Beschreibung
video	JSON Object	optional	Weitere Informationen siehe Videoobjekt-Beschreibung
document	JSON Object	optional	Weitere Informationen siehe Dokumentobjekt-Beschreibung
sticker	JSON Object	optional	Weitere Informationen siehe Stickerobjekt-Beschreibung

message_context

Feld	Typ	Option	Beschreibung
origin_from_phone	String	erforderlich	Absendernummer der referenzierten Nachricht, ohne Leerzeichen oder +
origin_channel_message_id	String	erforderlich	Eindeutige ID der referenzierten Nachricht
origin_from_phone_id	String	optional	Absendernummer-ID der referenzierten Nachricht, normalerweise vorhanden
origin_message_id	String	optional	Nachrichten-ID der referenzierten Nachricht, normalerweise vorhanden

Callback-Beispiel

{ "total": 1, "rows": [ { "message_id": "1666165485030094861", "from": "", "to": "", "server": "whatsapp", "channel": "whatsapp", "itime": 1640707579, "response": { "event": "", "response_data": { "channel_message_id": "wamid.123321abcdefed==", "whatsapp_business_account_id": "123321", "contact": { "profile": { "name": "bob" }, "wa_id": "8613800138000" }, "message": { "type": "text", "text": { "body": "Hier steht der Textinhalt der Nachricht" } } } } } ] }

              
              {
    "total": 1,
    "rows": [
        {
            "message_id": "1666165485030094861",
            "from": "",
            "to": "",
            "server": "whatsapp",
            "channel": "whatsapp",
            "itime": 1640707579,
            "response": {
                "event": "",
                "response_data": {
                    "channel_message_id": "wamid.123321abcdefed==",
                    "whatsapp_business_account_id": "123321",
                    "contact": {
                        "profile": {
                            "name": "bob"
                        },
                        "wa_id": "8613800138000"
                    },
                    "message": {
                        "type": "text",
                        "text": {
                            "body": "Hier steht der Textinhalt der Nachricht"
                        }
                    }
                }
            }
        }
    ]
}

Diesen Codeblock im schwebenden Fenster anzeigen

Nachrichtenbenachrichtigung – Notification

Callback-Parameter

Feld	Typ	Option	Beschreibung
event	string	optional	Antwortereignis
notification_data	JSON Object	optional	Inhalt der Systembenachrichtigung

event

Wert	Beschreibung	Detaillierte Erklärung
insufficient_balance	Unzureichendes Guthaben	Das Echtzeit-Guthaben liegt unter dem von Ihnen festgelegten Schwellenwert (Standard: $10)
template_update	Template-Status geändert	Änderung des Template-Status und der Template-Qualität
phone_number_update	Status der Absendernummer geändert	Statusänderung der Absendernummer, aktuell werden nur Änderungen am „Nachrichtenversandlimit“ unterstützt. Werte sind: TIER_50: 50 Kund:innen/24 Stunden TIER_250: 250 Kund:innen/24 Stunden TIER_1K: 1.000 Kund:innen/24 Stunden TIER_10K: 10.000 Kund:innen/24 Stunden TIER_100K: 100.000 Kund:innen/24 Stunden TIER_UNLIMITED: Unbegrenzt
whatsapp_business_update	WABA-Account geändert	WABA-Account gesperrt, verwarnt etc.

notification_data

Feld	Typ	Option	Beschreibung
whatsapp_business_account_id	String	erforderlich	WhatsApp Business Account Nummer
remain_balance	int	optional	Bei event = insufficient_balance Aktueller Echtzeit-Guthabenwert (USD)
balance_threshold	int	optional	Bei event = insufficient_balance Der von Ihnen gesetzte Schwellenwert für die Guthabenwarnung (USD)
template_id	String	optional	Bei event = template_update Template-ID
template_name	String	optional	Bei event = template_update Template-Name
template_language	String	optional	Bei event = template_update Templatesprache
template_status	String	optional	Bei event = template_update Template-Status, Werte: APPROVED/REJECTED/PENDING/DISABLED/FLAGGED/REINSTATED
template_status_reason	String	optional	Bei event = template_update Änderungsgrund, meist bei abgelehnter Template-Prüfung, sonst „NONE“ oder nicht vorhanden
phone_number_id	String	optional	Bei event = phone_number_update Absendernummer-ID
display_phone_number	String	optional	Bei event = phone_number_update, Absendernummer, Beispiele: +1 320-302-7083 +86 183 7981 2430
current_limit	String	optional	Bei event = phone_number_update Aktuelles Versandlimit, Werte: TIER_50/TIER_250/TIER_1K/TIER_10K/TIER_100K/TIER_UNLIMITED
waba_event	String	optional	Bei event = whatsapp_business_update, aktuelle Werte: DISABLED_UPDATE Account gesperrt ACCOUNT_VIOLATION Account-Verstoß
ban_state	String	optional	Bei event = whatsapp_business_update und waba_event = DISABLED_UPDATE, aktueller Wert: DISABLE Gesperrt
violation_type	String	optional	Bei event = whatsapp_business_update und waba_event = ACCOUNT_VIOLATION, aktuelle Werte: SPAM Als Spam/Belästigung markiert SCAM Als Betrug markiert

Callback-Beispiel

{ "total": 1, "rows": [ { "server": "whatsapp", "itime": 1640707579, "notification": { "event": "insufficient_balance", "notification_data": { "whatsapp_business_account_id": "", "remain_balance": 5.1234, "balance_threshold": 10 } } } ] }

              
              {
  "total": 1,
  "rows": [
    {
      "server": "whatsapp",
      "itime": 1640707579,
      "notification": {
        "event": "insufficient_balance",
        "notification_data": {
          "whatsapp_business_account_id": "",
          "remain_balance": 5.1234,
          "balance_threshold": 10
        }
      }
    }
  ]
}

Diesen Codeblock im schwebenden Fenster anzeigen