Get an SMS message

GET

/v1/sms/messages/{message_id}

const msg = await bird.sms.get("sms_abc123");
msg.status; // "accepted" | "delivered" | …

message = client.sms.get("sms_abc123")
print(message.id, message.status)

$message = $bird->sms->get('sms_01krdgeqcxet5s7t44vh8rt9mg');
echo $message->getStatus();

bird sms get <message-id>

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

Returns a single SMS message: its current delivery status, segment breakdown, cost, and failure detail when it failed. The status advances asynchronously as delivery progresses, and cost is null until the message has been priced, so poll this endpoint (or subscribe to sms.* webhook events) after a send to confirm delivery. To scan messages in bulk, use List SMS messages instead.

Parameter

message_id

string

ID of the message (sms_-prefixed), as returned in the send response's id field.

Payload Respons

string

wajib

ID of the message (sms_-prefixed), assigned when the send is accepted. Pass it as message_id to the get-message endpoint.

direction

string

wajib

Whether the message was sent from a Bird sender (outbound) or received from a subscriber (inbound).

Possible values: outbound, inbound

status

string

wajib

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.

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.

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.

tags

array of object

Structured {name, value} filter labels applied to this message.

Tampilkan atribut turunan

tags.name

string

wajib

Tag name. ASCII letters, digits, underscore, and hyphen only. Case-sensitive. Maximum 32 characters.

tags.value

string

wajib

Tag value. ASCII letters, digits, underscore, and hyphen only. Case-sensitive. Maximum 64 characters.

metadata

object

Arbitrary JSON metadata stored on the message and echoed in webhook payloads.

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

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.

validity_period

integer

How long, in seconds, Bird keeps trying to deliver before the message transitions to expired.

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.

mcc_mnc

string

Mobile country code and mobile network code of the carrier. Absent until the carrier is identified.

last_error

nullable object

Failure detail on a message that failed, was rejected, was not delivered, or expired. Absent otherwise.

Tampilkan atribut turunan

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

last_error.description

string

wajib

Human-readable explanation of the failure.

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.

last_error.occurred_at

string

wajib

When the failure occurred.

created_at

string

wajib

When the message was accepted (outbound) or received (inbound).

sent_at

nullable string

When the message was handed to the carrier. Null until then.

delivered_at

nullable string

When delivery was confirmed. Null until then.

const msg = await bird.sms.get("sms_abc123");
msg.status; // "accepted" | "delivered" | …

message = client.sms.get("sms_abc123")
print(message.id, message.status)

$message = $bird->sms->get('sms_01krdgeqcxet5s7t44vh8rt9mg');
echo $message->getStatus();

bird sms get <message-id>

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