Documentation
Sign inGet started
Mulai sekarang
Panduan
Referensi API
SDK
CLI
Basis Pengetahuan
Changelog

List SMS messages

GET
/v1/sms/messages
for await (const msg of bird.sms.list({ direction: "outbound" })) {
  console.log(msg.id, msg.status);
}
Returns the workspace's SMS messages as a cursor-paginated list, newest first. Filter by direction, status, category, recipient, sender, failure reason, tag, or creation time; pass the response's next_cursor back as starting_after to fetch the next page. To follow a single message's delivery, use Get an SMS message instead.
Messages are retained for 30 days. A created_after earlier than that is accepted and raised to the retention bound rather than rejected, so a wider window returns what is still retained instead of failing. There is no way to read messages older than the window.
Parameter Kueri
limit
integer
Maximum number of items to return per page.
starting_after
string
Cursor from the next_cursor field of a previous list response. Returns items immediately after the cursor position in the current sort order.
ending_before
string
Cursor from the prev_cursor field of a previous list response. Returns items immediately before the cursor position in the current sort order.
created_after
string
Return only resources created at or after this timestamp (inclusive lower bound). Combine with created_before to filter to a time window. RFC 3339 / ISO 8601 with timezone.
created_before
string
Return only resources created strictly before this timestamp (exclusive upper bound). Combine with created_after to filter to a time window. RFC 3339 / ISO 8601 with timezone.
direction
string
Filter by direction. Omit for both.
Possible values: outbound, inbound
status
array
Keep only messages whose current status matches; repeat the parameter to match any of several. One of scheduled, accepted, sent, delivered, undelivered, failed, rejected, canceled, expired, or received.
error_code
array
Keep only messages whose failure reason (last_error.code) matches; repeat the parameter to match any of several. One of invalid_destination, unreachable, blocked_by_carrier, blocked_by_recipient, landline_unreachable, content_rejected, sender_unregistered, recipient_opted_out, provider_unavailable, insufficient_balance, or unknown.
category
string
Filter by category.
Possible values: transactional, marketing, authentication, service
to
string
Filter by recipient phone number (E.164 exact match).
from
string
Filter by sender (E.164, alphanumeric, or short code; exact match).
tag
array
Filter by tag. Accepts name to match any message carrying that tag name, or name:value to match a specific tag pair (for example category:welcome). Repeat the parameter to add more tags. A message must match every tag listed to be returned.
Payload Respons
data
array of object
wajib
Page of SMS messages, newest first.
Tampilkan atribut turunan
data.id
string
wajib
ID of the message (sms_-prefixed), assigned when the send is accepted. Pass it as message_id to the get-message endpoint.
data.direction
string
wajib
Whether the message was sent from a Bird sender (outbound) or received from a subscriber (inbound).
Possible values: outbound, inbound
data.status
string
wajib
data.to
string
wajib
Where the message went. On an outbound message this is the recipient's phone number in E.164 format; on an inbound one it is your own number that received it.
data.from
string
wajib
Where the message came from. On an outbound message this is the sender you sent it from (an E.164 number, an alphanumeric sender ID, or a short code); on an inbound one it is the phone number that sent it to you.
data.text
string
The message body. Every message carries body text, attachments, or both, so this is absent only on a received message that carried attachments and no text. For a template send, this is the rendered text after parameter substitution. When category is authentication (a message carrying a one-time code), this is **REDACTED**: the code still reaches the recipient, Bird just does not persist it for later reads.
data.category
nullable string
Content classification supplied on the send. Null for inbound messages.
data.segments
object
wajib
Segment breakdown for the body.
Tampilkan atribut turunan
data.segments.count
integer
wajib
Number of segments the body is split into. Each segment is a billable unit.
data.segments.encoding
string
wajib
Encoding used for the body. GSM_7BIT fits 160 characters in a single segment (153 per part when multi-segment); UCS2 is used when the body contains any character outside the GSM 03.38 alphabet (emoji, CJK, some accented characters) and fits 70 characters in a single segment (67 per part when multi-segment).
Possible values: GSM_7BIT, UCS2
data.segments.characters
integer
wajib
Character count of the body under the selected encoding.
data.cost
nullable object
What the message cost, split into Bird's charge and any third-party fees passed through. Null until the message has been priced.
Tampilkan atribut turunan
data.cost.amount
string
wajib
Total charged, as a decimal string: the sum of the components below. Net of tax, which applies to your wallet balance rather than to an individual charge.
data.cost.currency_code
string
wajib
ISO 4217 currency code. Every component is denominated in this currency.
data.cost.transaction_amount
nullable string
wajib
What Bird charged to carry the message, as a decimal string. Null when this component was not priced; "0.00000" when it priced at zero.
data.cost.passthrough_amount
nullable string
wajib
Third-party fees Bird passes on, as a decimal string, such as US 10DLC carrier surcharges. Null when this component was not priced; "0.00000" when it priced at zero.
data.tags
array of object
Structured {name, value} filter labels applied to this message.
Tampilkan atribut turunan
data.tags.name
string
wajib
Tag name. ASCII letters, digits, underscore, and hyphen only. Case-sensitive. Maximum 32 characters.
data.tags.value
string
wajib
Tag value. ASCII letters, digits, underscore, and hyphen only. Case-sensitive. Maximum 64 characters.
data.metadata
object
Arbitrary JSON metadata stored on the message and echoed in webhook payloads.
data.options
object
Settings Bird applied to this message, with any option you omitted filled in with the default that was in force when you sent it. Absent on inbound messages, and on outbound messages sent before Bird began recording these settings.
Tampilkan atribut turunan
data.options.smart_encoding
boolean
wajib
Whether Bird replaced characters outside the GSM-7 alphabet in this message's body with their closest equivalent before sending it. When true, text is the body as sent and segments describes that body.
data.validity_period
integer
How long, in seconds, Bird keeps trying to deliver before the message transitions to expired.
data.carrier
string
Carrier that handled the message. Absent until a delivery receipt identifies it, and on a received message the carrier reports it only where a carrier fee applies.
data.mcc_mnc
string
Mobile country code and mobile network code of the carrier. Absent until the carrier is identified.
data.last_error
nullable object
Failure detail on a message that failed, was rejected, was not delivered, or expired. Absent otherwise.
Tampilkan atribut turunan
data.last_error.code
string
wajib
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.last_error.description
string
wajib
Human-readable explanation of the failure.
data.last_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.last_error.occurred_at
string
wajib
When the failure occurred.
data.created_at
string
wajib
When the message was accepted (outbound) or received (inbound).
data.sent_at
nullable string
When the message was handed to the carrier. Null until then.
data.delivered_at
nullable string
When delivery was confirmed. Null until then.
next_cursor
nullable string
wajib
Cursor for the next page. Pass back as starting_after to advance forward. Null when no next page exists.
prev_cursor
nullable string
wajib
Cursor for the previous page. Pass back as ending_before to step backward. Null when no previous page exists.
refresh_cursor
nullable string
wajib
Refresh anchor. Pass back as ending_before later to fetch items that have appeared since this response. Non-null whenever data is non-empty; null only on an empty page. Distinct from prev_cursor.