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"

响应200

{
  "data": [
    {
      "id": "evt_01krdgeqcxet5s7t44vh8rt9mg",
      "type": "sms.delivered",
      "carrier": "Verizon",
      "mcc_mnc": "311480",
      "error": {
        "code": "invalid_destination",
        "description": "Carrier filtered as spam"
      }
    }
  ]
}

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

参数

message_id

string

ID of the SMS message (sms_ prefix), as returned when the message was accepted.

查询参数

type

string

Filter by event type, such as sms.delivered or sms.failed.

响应载荷

data

array of object

必填

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

显示子属性

data.id

string

必填

Unique identifier for this event, stable across repeated fetches of the message.

data.type

string

必填

Lifecycle event type. The sms.accepted event means the API accepted the request. The sms.sent event means the message reached the carrier. The sms.delivered event confirms delivery. The sms.undelivered, sms.failed, and sms.expired events describe delivery failures. The sms.rejected event means the message was refused before carrier handoff. This is an open enum. Accept unrecognized values.

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

data.occurred_at

string

必填

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.

显示子属性

data.error.code

string

必填

Standardized failure reason:

invalid_destination: The number is unassigned, ported out, or malformed.
unreachable: The handset is off or outside 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: The provider remained unavailable after retries.
insufficient_balance: The workspace wallet could not fund the send.
unknown: The failure could not be classified.

This is an open enum. Accept unrecognized values.

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

必填

The failure in words, from whatever refused the message: the carrier's own reason text on a delivery receipt, or ours on a message stopped before a carrier saw it. Free-form, so branch on code and show this to a human.

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

必填

When the failure occurred.

Related resources

Continue with the documentation, guides and examples for this topic. Resources are in English.

Watch the guideSending your first SMS Understand the conceptWhat does SMS mean?Explore the capabilitySMS Follow the learning pathBuild your first integration

Try the practice and get an implementation brief

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"

响应200

{
  "data": [
    {
      "id": "evt_01krdgeqcxet5s7t44vh8rt9mg",
      "type": "sms.delivered",
      "carrier": "Verizon",
      "mcc_mnc": "311480",
      "error": {
        "code": "invalid_destination",
        "description": "Carrier filtered as spam"
      }
    }
  ]
}