Nachrichten-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.

Callbacks zum Nachrichtenstatus und zu eingehenden Nutzernachrichten können eine Business-Scoped User ID (BSUID) enthalten, um den jeweiligen WhatsApp-Nutzer zu identifizieren. Die BSUID wird über neue optionale Felder zurückgegeben und hat keine Auswirkungen auf vorhandene Felder oder Callback-Ereignisse.

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:

Die Parameter in rows sind wie folgt:

BSUID-Felder

Die BSUID wird im vorhandenen Callback-Payload über die folgenden optionalen Felder zurückgegeben:

• Wenn keine BSUID verfügbar ist, wird das entsprechende Feld weggelassen. Clientseitige Parser müssen das Fehlen des Feldes zulassen.
• Um Nummer und BSUID gemeinsam anzuzeigen, verwenden Sie bei Nachrichtenstatus-Callbacks to zusammen mit status_data.recipient_user_id und bei eingehenden Nutzernachrichten contact.wa_id zusammen mit contact.user_id.
• Die BSUID-Felder dienen ausschließlich zur Nutzeridentifizierung in Callbacks. Die Sende-API unterstützt derzeit keine BSUID als Empfänger.

Nachrichtenstatus – Status

Callback-Parameter

message_status – Werte und Beschreibung

status_data

recipient_user_id wird häufig bei sent-, delivered- und read-Callbacks zurückgegeben, sobald die BSUID des Empfängers verfügbar ist. Bei Vorverarbeitungs- oder Fehlerstatus, historischen Nachrichten oder Daten aus älteren Verarbeitungswegen kann das Feld fehlen.

conversation

pricing

error_detail

loss

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",
                    "recipient_user_id": "ID.1234567890123456",
                    "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"
                }
            }
        }
    ]
}

            

Nachrichtenantwort

Callback-Parameter

event

response_data

contact

contact.wa_id behält seine bisherige Bedeutung als Nummernfeld bei, während contact.user_id die BSUID enthält. Lesen Sie zur Identifizierung eines Nutzers per BSUID contact.user_id; behandeln Sie from, to oder contact.wa_id nicht als BSUID.

message

message_context

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",
                        "user_id": "ID.1234567890123456"
                    },
                    "message": {
                        "type": "text",
                        "text": {
                            "body": "Hier steht der Textinhalt der Nachricht"
                        }
                    }
                }
            }
        }
    ]
}

            

Nachrichtenbenachrichtigung – Notification

Callback-Parameter

event

notification_data

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