List events for a WhatsApp message

GET

/v1/whatsapp/messages/{message_id}/events

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)

package main

import (
	"context"
	"fmt"
	"log"
	"os"

	bird "github.com/messagebird/bird-sdk-go"
	"github.com/messagebird/bird-sdk-go/option"
)

func main() {
	client, err := bird.NewClient(option.WithAPIKey(os.Getenv("BIRD_API_KEY")))
	if err != nil {
		log.Fatal(err)
	}
	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 -X GET "https://us1.platform.bird.com/v1/whatsapp/messages/{message_id}/events" \
  -H "Authorization: Bearer $TOKEN"

Response200

{
  "data": [
    {
      "id": "ev_01krdgeqcxet5s7t44vh8rt9mg",
      "type": "whatsapp.delivered",
      "error": {
        "code": "insufficient_balance",
        "description": "Message could not be delivered.",
        "meta_error_code": "131026"
      }
    }
  ]
}

Returns a WhatsApp message's lifecycle events in chronological order, one entry per delivery transition (whatsapp.accepted, whatsapp.sent, whatsapp.delivered, whatsapp.read, whatsapp.failed). The timeline is bounded and returned in full, so this list is not paginated; an unknown message ID returns 404. For the message's current state in a single field, use Get a WhatsApp message instead.

Parameters

message_id

string

ID of the message, as returned in the send response's id field.

Query Parameters

type

string

Keep only events of this exact type (for example whatsapp.delivered or whatsapp.failed). Omit for the full timeline.

Possible values (may grow over time): whatsapp.accepted, whatsapp.delivered, whatsapp.failed, whatsapp.read, whatsapp.received, whatsapp.rejected, whatsapp.sent

Response Payload

data

array of object

required

Timeline events for this WhatsApp message, in chronological order. The timeline is bounded and returned in full; this list is not paginated.

Show child attributes

data.id

string

required

ID of the event, unique within the message's timeline.

data.type

string

required

Message timeline event type:

whatsapp.accepted: The API accepted the request.
whatsapp.sent: The message reached the WhatsApp network.
whatsapp.delivered: Delivery to the recipient's device was confirmed.
whatsapp.read: The recipient opened the message.
whatsapp.failed: Delivery failed permanently.
whatsapp.rejected: The message was refused before sending and not charged.
whatsapp.received: An inbound message arrived from the contact.

This is an open enum. Accept unrecognized values.

Possible values (may grow over time): whatsapp.accepted, whatsapp.delivered, whatsapp.failed, whatsapp.read, whatsapp.received, whatsapp.rejected, whatsapp.sent

data.occurred_at

string

required

When this event occurred.

data.error

nullable object

Failure detail. Present only on whatsapp.failed and whatsapp.rejected events.

Show child attributes

data.error.code

string

required

Standardized failure reason:

insufficient_balance: The workspace wallet could not fund the send.
price_not_found: No price was configured for the destination and template.
internal_error: An unexpected service failure occurred.
undeliverable: The recipient could not be reached.
service_window_expired: The 24-hour service window closed; send a template.
rate_limited: The send was throttled.
recipient_suppressed: The recipient is on the workspace suppression list.
media_rejected: WhatsApp could not fetch the media URL, or refused the file it found there; description carries its reason.

This is an open enum. Accept unrecognized values.

Possible values (may grow over time): insufficient_balance, price_not_found, internal_error, undeliverable, service_window_expired, rate_limited, recipient_suppressed, media_rejected

data.error.description

string

required

Human-readable explanation of the failure.

data.error.meta_error_code

nullable string

Raw error code from the WhatsApp Cloud API, when available, for low-level debugging.

data.error.occurred_at

string

required

When the failure occurred.

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)

package main

import (
	"context"
	"fmt"
	"log"
	"os"

	bird "github.com/messagebird/bird-sdk-go"
	"github.com/messagebird/bird-sdk-go/option"
)

func main() {
	client, err := bird.NewClient(option.WithAPIKey(os.Getenv("BIRD_API_KEY")))
	if err != nil {
		log.Fatal(err)
	}
	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 -X GET "https://us1.platform.bird.com/v1/whatsapp/messages/{message_id}/events" \
  -H "Authorization: Bearer $TOKEN"

Response200

{
  "data": [
    {
      "id": "ev_01krdgeqcxet5s7t44vh8rt9mg",
      "type": "whatsapp.delivered",
      "error": {
        "code": "insufficient_balance",
        "description": "Message could not be delivered.",
        "meta_error_code": "131026"
      }
    }
  ]
}