HTTPS API v2 / WhatsApp Webhook

Webhook URL przypisany do agenta WhatsApp służy do przekazywania zdarzeń generowanych podczas konwersacji z użytkownikiem. Mechanizm ten umożliwia integrację systemu z zewnętrznymi usługami poprzez wysyłanie żądań HTTP POST zawierających dane zdarzenia w formacie JSON. Powiadomienia mogą obejmować m.in. informacje o wygenerowanych raportach, interakcjach użytkownika (np. wybór sugerowanej odpowiedzi) oraz wiadomościach wysyłanych przez użytkownika. Każde zdarzenie jest klasyfikowane na podstawie pola 'type', które określa jego typ i strukturę danych: 

- report – wygenerowany raport wiadomości,
- reply – odpowiedź użytkownika wybrana z sugerowanych opcji,
- message – wiadomość tekstowa wysłana przez użytkownika,
- template – zdarzenia związane ze zmianą stanu szablonów,
- template_quality – aktualizacja jakości szablonów,
- template_category – zmiana kategorii szablonów.

Request HTTP

Komunikacja odbywa się poprzez HTTP POST z payloadem w formacie JSON (Content-Type: application/json). Ruch wychodzący dla mechanizmu powiadomień realizowany jest z adresów IP 94.152.153.158 / 94.152.131.145. Przesyłany payload może zawierać tablicę obiektów, przy czym maksymalna liczba elementów w pojedynczym żądaniu wynosi 30.

Struktury JSON

1. Typ 'report':

[{
     "type": "report",
     "phone": "48100100100",
     "status": "displayed",
     "date": "2022-05-04 16:55:45",
     "msgid": "wamid.HBgLNDg3OTE3NjEwNTcVAgARGBJGOTcyNUExMjkxMDRCMzM1RDcA",
     "smsid": "d4505eaeb9",
     "mcc": "260",
     "pricing": {
         "billable": false,
         "pricing_model": "PMP",
         "category": "service",
         "type": "free_customer_service"
     },
     "whatsapp_id":"12341314-1230-12ae-1234-123458a0c6ea"
}]

Oznaczenia pól:

Dostępne wartości parametru 'status':

Dostępne wartości parametru 'pricing ':

 

2. Typ 'reply':

[{
     "type": "reply",
     "phone": "48100100100",
     "text": "Tak, zgadzam się!",
     "date": "2022-05-04 16:55:45",
     "msgid": "wamid.HBgLNDg3OTE3NjEwNTcVAgARGBJGOTcyNUExMjkxMDRCMzM1RDcA",
     "data": "21",
     "profile": {
         "profile": {
             "name": "Jan Kowalski"
         },
         "wa_id": "48100100100",
         "user_id": "PL.2000000000000000"
     },
     "whatsapp_id":"12341314-1230-12ae-1234-123458a0c6ea"
}]

Oznaczenia pól:

 

3. Typ 'message':

[{
     "type": "message",
     "phone": "48100100100",
     "text": "Stop",
     "date": "2022-05-04 16:55:45",
     "msgid": "wamid.HBgLNDg3OTE3NjEwNTcVAgARGBJGOTcyNUExMjkxMDRCMzM1RDcA",
     "profile": {
         "profile": {
             "name": "Jan Kowalski"
         },
         "wa_id": "48100100100",
         "user_id": "PL.2000000000000000"
     },
     "whatsapp_id": "12341314-1230-12ae-1234-123458a0c6ea"
}]

Oznaczenia pól:

 

4. Typ 'template':

[{
     "type": "template",
     "template_id": "1228394058379665",
     "template_name": "serwersms_indywidualny_marketing_test",
     "language": "pl",
     "category": "MARKETING",
     "status": "APPROVED",
     "reason": "NONE",
     "whatsapp_id": "12341314-1230-12ae-1234-123458a0c6ea"
}]

Oznaczenia pól:

 

5. Typ 'template_quality':

[{
     "type": "template_quality",
     "template_id": "1228394058379665",
     "template_name": "serwersms_indywidualny_marketing_test",
     "language": "pl",
     "previous_quality_score": "UNKNOWN",
     "new_quality_score": "GREEN",
     "whatsapp_id": "12341314-1230-12ae-1234-123458a0c6ea"
}]

Oznaczenia pól:

 

6. Typ 'template_category':

[{
     "type": "template_category",
     "template_id": "1228394058379665",
     "template_name": "serwersms_indywidualny_marketing_test",
     "language": "pl",
     "previous_category": "UTILITY",
     "new_category": "MARKETING",
     "correct_category": "MARKETING",
     "category_appeal_status": "APPROVED",
     "whatsapp_id": "12341314-1230-12ae-1234-123458a0c6ea"
}]

Oznaczenia pól:

Weryfikacja odpowiedzi

W panelu klienta, dla wybranego agenta WhatsApp, istnieje możliwość konfiguracji response tag (tagu oczekiwanej odpowiedzi). Jeżeli tag zostanie zdefiniowany jako niepusty ciąg znaków, system przechodzi w tryb oczekiwania na zgodną odpowiedź. W takim przypadku poprawna odpowiedź musi zawierać lub być równa zdefiniowanemu tagowi, aby zostać uznana za prawidłową. W przypadku braku zgodnej odpowiedzi system uruchamia mechanizm retry (ponowień zapytania), zgodnie z następującymi interwałami, dla raportów doręczeń (DLR) ponowienia wykonywane są co 30 minut, natomiast dla odpowiedzi użytkowników co 5 minut. Mechanizm działa do momentu osiągnięcia maksymalnie 5 prób, po czym proces zostaje zakończony jako nieudany.