List events for an SMS message

GET

/v1/sms/messages/{message_id}/events

const events = await bird.sms.listEvents("sms_abc123");
for (const event of events.data ?? []) {
  console.log(event.type, event.occurred_at);
}

events = client.sms.list_events("sms_abc123")
for event in events.data:
    print(event.type, event.occurred_at)

events, err := client.Sms.ListEvents(context.Background(), "sms_01j9x2k3m4n5p6q7r8s9t0v1w2", bird.SmsListEventsParams{})
if err != nil {
	log.Fatal(err)
}
for _, e := range events.Data {
	fmt.Println(*e.Type, *e.OccurredAt)
}

$events = $bird->sms->listEvents('sms_abc123');
foreach ($events->getData() ?? [] as $event) {
    echo $event->getType(), ' ', $event->getOccurredAt()?->format(DATE_ATOM), PHP_EOL;
}

bird sms list-events <message-id>

curl -X GET "https://us1.platform.bird.com/v1/sms/messages/{message_id}/events" \
  -H "Authorization: Bearer $TOKEN"

Returns the lifecycle event timeline for a message, in chronological order.

Parametry

message_id

string

Message ID.

Parametry zapytania

type

string

Filter by event type (e.g. sms.delivered, sms.failed).

Treść odpowiedzi

data

array of object

wymagane

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

Pokaż atrybuty podrzędne

data.id

string

wymagane

Event ID.

data.type

string

wymagane

Lifecycle event type. sms.accepted — Bird accepted the request. sms.sent — handed to the carrier. sms.delivered — delivery confirmed. sms.undelivered — non-permanent non-delivery. sms.failed — terminal permanent failure. sms.rejected — refused before reaching the carrier. sms.expired — the validity period elapsed. Open enum — new event types may be added over time, so treat any unrecognized value as a future event rather than an error.

Possible values (may grow over time): sms.accepted, sms.sent, sms.delivered, sms.undelivered, sms.failed, sms.rejected, sms.expired

data.occurred_at

string

wymagane

When this event occurred.

data.carrier

string

Carrier that handled the message. Present on sms.sent and sms.delivered once identified, absent otherwise.

data.mcc_mnc

string

Mobile country code and mobile network code of the carrier. Present on sms.sent and sms.delivered once identified, absent otherwise.

data.error

nullable object

Failure detail. Present only on sms.failed, sms.undelivered, sms.rejected, and sms.expired events.

Pokaż atrybuty podrzędne

data.error.code

string

wymagane

Bird-stable failure reason. Open enum: Bird adds reasons as the carrier platform's own buckets are covered, so treat an unrecognized value as a future reason rather than an error. invalid_destination: the number is not assigned, ported out, or malformed. unreachable: handset off or out of coverage. blocked_by_carrier: the carrier filtered the message. blocked_by_recipient: the recipient device blocked the sender. landline_unreachable: the destination is a landline that does not accept SMS. content_rejected: the carrier rejected the content. sender_unregistered: the sender is not registered for the destination. recipient_opted_out: the recipient is on a suppression list. provider_unavailable: an upstream failure after retries. insufficient_balance: the workspace wallet had insufficient balance to send the message. unknown: an unmapped failure.

Possible values (may grow over time): invalid_destination, unreachable, blocked_by_carrier, blocked_by_recipient, landline_unreachable, content_rejected, sender_unregistered, recipient_opted_out, provider_unavailable, insufficient_balance, unknown

data.error.description

string

wymagane

Human-readable explanation of the failure.

data.error.carrier_error_code

nullable string

Raw provider-supplied error code, finer-grained than the code that normalizes it. Not a Bird-defined value, so quote it to support when asking why a message failed. Null when the provider sent none, including any failure decided before one was reached.

data.error.occurred_at

string

wymagane

When the failure occurred.

const events = await bird.sms.listEvents("sms_abc123");
for (const event of events.data ?? []) {
  console.log(event.type, event.occurred_at);
}

events = client.sms.list_events("sms_abc123")
for event in events.data:
    print(event.type, event.occurred_at)

events, err := client.Sms.ListEvents(context.Background(), "sms_01j9x2k3m4n5p6q7r8s9t0v1w2", bird.SmsListEventsParams{})
if err != nil {
	log.Fatal(err)
}
for _, e := range events.Data {
	fmt.Println(*e.Type, *e.OccurredAt)
}

$events = $bird->sms->listEvents('sms_abc123');
foreach ($events->getData() ?? [] as $event) {
    echo $event->getType(), ' ', $event->getOccurredAt()?->format(DATE_ATOM), PHP_EOL;
}

bird sms list-events <message-id>

curl -X GET "https://us1.platform.bird.com/v1/sms/messages/{message_id}/events" \
  -H "Authorization: Bearer $TOKEN"