Documentazione
Sign inGet started
Inizia ora
Guide
Riferimento API
SDK
CLI
Knowledge Base
Changelog

Get an SMS message

GET
/v1/sms/messages/{message_id}
const msg = await bird.sms.get("sms_abc123");
msg.status; // "accepted" | "delivered" | …
Risposta200
{
  "id": "sms_01krdgeqcxet5s7t44vh8rt9mg",
  "direction": "outbound",
  "status": "scheduled",
  "to": "+15551234567",
  "from": "+15557654321",
  "text": "Your order has shipped and is on its way.",
  "category": "transactional",
  "segments": {
    "encoding": "GSM_7BIT"
  },
  "cost": {
    "amount": "0.00990",
    "currency_code": "USD",
    "transaction_amount": "0.00790",
    "passthrough_amount": "0.00200"
  },
  "tags": [
    {
      "name": "category",
      "value": "welcome"
    }
  ],
  "options": {
    "smart_encoding": true
  },
  "carrier": "Verizon",
  "mcc_mnc": "311480",
  "last_error": {
    "code": "invalid_destination",
    "description": "Carrier filtered as spam"
  }
}
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 operation (or subscribe to sms.* webhook events) after a send to confirm delivery. To scan messages in bulk, use List SMS messages instead.
Parametri
message_id
string
ID of the message, as returned in the send response's id field.
Payload di risposta
id
string
obbligatorio
ID of the message, assigned when the send is accepted. Pass it as message_id to the get-message endpoint.
direction
string
obbligatorio
Whether the message was sent from a Bird sender (outbound) or received from a subscriber (inbound).
Possible values: outbound, inbound
status
string
obbligatorio
to
string
obbligatorio
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
obbligatorio
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 message, this 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, but the API does not retain it for later reads.
category
nullable string
Content classification supplied on the send. Null for inbound messages.
segments
object
obbligatorio
Segment breakdown for the body.
Mostra attributi secondari
segments.count
integer
obbligatorio
Number of segments the body is split into. Each segment is a billable unit.
segments.encoding
string
obbligatorio
Encoding used for the body. The GSM_7BIT encoding fits 160 septets (seven-bit units) in one segment, or 153 per part in a multi-segment message. The UCS2 encoding applies when the body contains a character outside the GSM 03.38 alphabet, including emoji, CJK, and some accented characters. It fits 70 UTF-16 code units in one segment, or 67 per part.
Neither limit counts characters, and both alphabets have characters that cost two units. Under GSM_7BIT there are ten such entries, and they are the whole set: ^, {, }, \, [, ], ~, |, €, and the form feed control. Eighty of those fill a single segment. Under UCS2 an emoji outside the Basic Multilingual Plane is a surrogate pair costing two code units, so 35 of those fill a single segment.
Possible values: GSM_7BIT, UCS2
segments.characters
integer
obbligatorio
Character count of the body, counted in Unicode code points under either encoding. This is not the segment measure: a GSM_7BIT extended-table character counts once here but costs two septets, and a UCS2 emoji outside the Basic Multilingual Plane counts once here but costs two of the segment's 70 code units.
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.
Mostra attributi secondari
cost.amount
string
obbligatorio
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.
cost.currency_code
string
obbligatorio
ISO 4217 currency code. Every component is denominated in this currency.
cost.transaction_amount
nullable string
obbligatorio
What we charged to carry the message, as a decimal string. null when this component was not priced; "0.00000" when it priced at zero.
cost.passthrough_amount
nullable string
obbligatorio
Third-party fees we pass 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.
tags
array of object
Structured {name, value} filter labels applied to this message.
Mostra attributi secondari
tags.name
string
obbligatorio
Tag name. ASCII letters, digits, underscore, and hyphen only. Case-sensitive. Maximum 32 characters.
tags.value
string
obbligatorio
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
The settings applied to this message, with any option you omitted filled in with the default in force when you sent it. Absent on inbound messages, and on any outbound message for which no settings were recorded.
Mostra attributi secondari
options.smart_encoding
boolean
obbligatorio
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
Preview feature: how long, in seconds, the carrier may keep attempting delivery before the message is marked expired. Not returned yet.
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.
Mostra attributi secondari
last_error.code
string
obbligatorio
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
last_error.description
string
obbligatorio
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.
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
obbligatorio
When the failure occurred.
created_at
string
obbligatorio
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.