Zdarzenia statusu wiadomości WhatsApp
Bird rejestruje zdarzenia dla przychodzących i wychodzących wiadomości WhatsApp. Oś czasu wiadomości wychodzącej pokazuje, co się wydarzyło po tym, jak wysyłka zwróciła 202: przyjęcie, przekazanie do WhatsApp, doręczenie, odczytanie lub niepowodzenie. Oś czasu wiadomości przychodzącej rejestruje moment odebrania wiadomości przez Bird.
Ta strona opisuje odczytywanie tej osi czasu przez API. Aby Bird wysyłał każde zdarzenie do Twojego endpointu w momencie jego wystąpienia, zobacz Webhooki statusu wiadomości. Reakcje mają własną historię, opisaną w Zdarzenia reakcji.
Zdarzenia cyklu życia
Zdarzenia pojawiają się w kolejności chronologicznej. Wiadomość wychodząca może zatrzymać się na whatsapp.failed lub whatsapp.rejected, a jej zdarzenie whatsapp.read pojawi się tylko wtedy, gdy odbiorca otworzy wiadomość. Oś czasu wiadomości przychodzącej zaczyna się od whatsapp.received i może zarejestrować whatsapp.read po tym, jak Twój obszar roboczy oznaczy wiadomość jako przeczytaną.
| Zdarzenie | Znaczenie |
|---|---|
| whatsapp.accepted | Bird przyjął żądanie wysyłki. To jest to, co zgłosił 202. |
| whatsapp.sent | Bird przekazał wiadomość do sieci WhatsApp. |
| whatsapp.delivered | WhatsApp potwierdził doręczenie na urządzenie odbiorcy. |
| whatsapp.read | Odbiorca otworzył wiadomość. |
| whatsapp.failed | Wiadomość nie została doręczona. error.code wskazuje, co ją zatrzymało. |
| whatsapp.rejected | Bird odrzucił wiadomość przed wysłaniem. Nie została naliczona opłata. |
| whatsapp.received | Bird odebrał wiadomość przychodzącą od kontaktu. |
Odpowiednie wywołania zwrotne delivered lub read mogą uruchomić naliczenie opłaty Meta. Dane zdarzeń WhatsApp nie zawierają kosztu. Odczytaj wiadomość za pomocą GET /v1/whatsapp/messages/{message_id}, aby sprawdzić jej koszt. Zobacz Koszty i rozliczenia.
Oznaczenie wiadomości przychodzącej jako przeczytanej rejestruje whatsapp.read na jej osi czasu, ale nie emituje webhooka potwierdzenia odczytu. Wiadomość przychodząca zachowuje status received i rejestruje read_at po tym, jak WhatsApp przyjmie potwierdzenie.
whatsapp.read nie zmienia status wiadomości. Doręczona wiadomość pozostaje w statusie delivered; wiadomość dodatkowo rejestruje odczytanie w read_at.
whatsapp.delivered może zostać całkowicie pominięte. Gdy odbiorca ma już otwarty czat na swoim urządzeniu, Meta zgłasza odczytanie bez uprzedniego zgłoszenia doręczenia, więc oś czasu wygląda tak: whatsapp.accepted → whatsapp.sent → whatsapp.read bez whatsapp.delivered pomiędzy. Traktuj read jako dowód doręczenia: konsument czekający na delivered, zanim uzna wiadomość za dostarczoną, zawiesi się właśnie na odbiorcach, którzy zobaczyli ją najszybciej, a konsument obliczający wskaźnik doręczeń wyłącznie na podstawie delivered zaniży go. status wiadomości w tym przypadku pozostaje sent, ponieważ tylko potwierdzenie doręczenia go aktualizuje.
Wywołanie zwrotne samego odczytu nadal może uruchomić naliczenie odpowiedniej opłaty Meta. Bird używa jednej tożsamości opłaty zarówno dla ścieżki doręczenia, jak i odczytu; brak zdarzenia doręczenia nie oznacza darmowego komponentu Meta. Zobacz Koszty i rozliczenia.
Lista typów zdarzeń jest otwarta: nowe typy mogą być dodawane z czasem, więc traktuj nierozpoznaną wartość jako przyszłe zdarzenie, a nie błąd.
Zdarzenia niepowodzenia
whatsapp.failed i whatsapp.rejected są terminalne. Odrzucenie oznacza, że Bird zatrzymał wiadomość przed wysłaniem jej do WhatsApp, więc nie została naliczona opłata. Przyczyny obejmują wyciszonego lub wypisanego odbiorcę, niewystarczające saldo portfela lub miejsce docelowe bez skonfigurowanej ceny. Niepowodzenie oznacza, że wiadomość nie została doręczona, a error.code wskazuje, kto o tym zdecydował. Większość kodów zawiera werdykt WhatsApp, zmapowany z kodu, który zgłosił. internal_error jest wyjątkiem: rejestruje brak użytecznych danych uwierzytelniających nadawcy lub wyczerpanie ponownych prób przetwarzania. Niepewna próba transportu nie dowodzi, że Meta nigdy nie otrzymała żądania. meta_error_code zawiera kod WhatsApp, gdy jest dostępny, a niepowodzenie internal_error z założenia go nie ma.
Oba zdarzenia zawierają obiekt error ze stabilnym Bird code, czytelnym dla człowieka description, opcjonalnym meta_error_code oraz occurred_at. Obiekt pojawia się w rekordach API i danych webhooków tylko dla tych typów zdarzeń.
Odczytywanie zdarzeń z API
GET /v1/whatsapp/messages/{message_id}/events zwraca oś czasu w kolejności chronologicznej. Lista ograniczona nie jest paginowana. Odczytywanie zdarzeń wymaga klucza API z whatsapp:read:
const { data } = await bird.whatsapp.listEvents("wa_abc123");
for (const event of data) console.log(event.type, event.occurred_at);events = client.whatsapp.list_events("wa_abc123")
for event in events.data:
print(event.type, event.occurred_at)events, err := client.Whatsapp.ListEvents(context.Background(), "wam_01krdgeqcxet5s7t44vh8rt9mg", bird.WhatsappListEventsParams{})
if err != nil {
log.Fatal(err)
}
for _, e := range events.Data {
fmt.Println(e.Id, e.Type)
}$events = $bird->whatsapp->listEvents('wamid_01krdgeqcxet5s7t44vh8rt9mg');
foreach ($events->getData() ?? [] as $event) {
echo $event->getType(), ' ', $event->getId(), "\n";
}bird whatsapp list-events <message-id>curl https://us1.platform.bird.com/v1/whatsapp/messages/wam_.../events \
-H "Authorization: Bearer $BIRD_API_KEY"Wiadomość, która została przyjęta, wysłana, doręczona i odczytana, zwraca cztery zdarzenia:
Przykład kodu
{
"data": [
{
"id": "ev_01ky7q6a1fejfbvs0myn41hj41",
"occurred_at": "2026-07-23T14:48:34.71Z",
"type": "whatsapp.accepted"
},
{
"id": "ev_01ky7q6a2denvtd6jg1vqwmg13",
"occurred_at": "2026-07-23T14:48:35.671Z",
"type": "whatsapp.sent"
},
{
"id": "ev_01ky7q6a2zff9r2qm74mmg1g6z",
"occurred_at": "2026-07-23T14:48:36.642Z",
"type": "whatsapp.delivered"
},
{
"id": "ev_01ky7q6c21frssf0vj8h50qysw",
"occurred_at": "2026-07-23T14:48:38.65Z",
"type": "whatsapp.read"
}
]
}Przekaż type, aby zwrócić dokładnie jeden publiczny typ zdarzenia, np. ?type=whatsapp.failed lub ?type=whatsapp.read. Pomiń go, aby otrzymać pełną oś czasu.
Ta sama oś czasu jest tym, co renderuje strona dziennika WhatsApp, gdy otworzysz wiadomość.
Następne kroki
- Webhooki statusu wiadomości: odbieraj każde zdarzenie w momencie jego wystąpienia
- Zdarzenia reakcji: odczytuj bieżące reakcje i dziennik reakcji
- Oznacz wiadomość jako przeczytaną: potwierdź wiadomość przychodzącą i pokaż pisanie
- Dziennik WhatsApp: widok poszczególnych wiadomości renderujący tę oś czasu
- Wysyłanie wiadomości WhatsApp: miejsce, w którym zaczyna się cykl życia wiadomości
Powiązane zasoby
Kontynuuj z dokumentacją, przewodnikami i przykładami dotyczącymi tego tematu. Zasoby są w języku angielskim.
Obejrzyj przewodnikConnecting WhatsApp to Bird: from buying a number to a live channelZrozum koncepcjęWhat is the 24-hour customer service window on WhatsApp?Użyj narzędziaWhatsApp message builderPoznaj możliwościWhatsApp
Wypróbuj ćwiczenie i uzyskaj brief wdrożeniowy