Create an SMS message
/v1/sms/messagesconst msg = await bird.sms.send({
from: "+15557654321",
to: "+14155550100",
text: "Your verification code is 123456.",
category: "authentication",
});
console.log(msg.id, msg.status);msg = client.sms.send(
from_="+15557654321",
to="+15551234567",
text="Your verification code is 123456.",
category="authentication",
)
print(msg.id, msg.status)msg, err := client.Sms.Send(context.Background(), bird.SmsSendParams{
From: "+15557654321",
To: "+15551234567",
Text: "Your verification code is 123456.",
Category: bird.SMSCategoryAuthentication,
})
if err != nil {
log.Fatal(err)
}
fmt.Println(msg.Id, *msg.Status)$message = $bird->sms->send(
from: '+15557654321',
to: '+15551234567',
text: 'Your verification code is 123456.',
category: 'authentication',
);
echo $message->getId(), ' ', $message->getStatus();bird sms send --body-file - <<'JSON'
{
"to": "+14155550100",
"from": "+15557654321",
"text": "Your verification code is 123456.",
"category": "authentication",
"options": {
"smart_encoding": true
},
"tags": [
{
"name": "campaign",
"value": "signup"
}
],
"metadata": {
"user_id": "usr_12345"
}
}
JSONcurl -X POST "https://us1.platform.bird.com/v1/sms/messages" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"to": "+14155550100",
"from": "+15557654321",
"text": "Your verification code is 123456.",
"category": "authentication",
"options": {
"smart_encoding": true
},
"tags": [
{
"name": "campaign",
"value": "signup"
}
],
"metadata": {
"user_id": "usr_12345"
}
}'{
"id": "sms_01krdgeqcxet5s7t44vh8rt9mg",
"direction": "outbound",
"status": "scheduled",
"to": "+15551234567",
"from": "+15557654321",
"text": "Your order has shipped and is on its way.",
"category": "transactional",
"requested_language": "pt-BR",
"resolved_language": "pt-BR",
"template_id": "smt_01krdgeqcxet5s7t44vh8rt9mg",
"template_version_id": "smv_01krdgeqcxet5s7t44vh8rt9mg",
"template_content_hash": "sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
"segments": {
"count": 1,
"encoding": "GSM_7BIT",
"characters": 41
},
"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"
},
"created_at": "2026-05-21T12:00:00Z"
}
Sends one SMS to one recipient with exactly one content form: text, which
requires category and from, or a stored template, which supplies its
category. A workspace template requires from, while a built-in template
selects its sender. To submit up to 100 independent messages in one request, use
Send a batch of SMS messages
instead.
The 202 Accepted response means the API durably accepted the message for
asynchronous delivery. Delivery remains pending; follow it with
Get an SMS message or by subscribing
to sms.* webhook events.
An invalid field, more than 12 segments, a disabled destination country, or
a sender not permitted for the destination returns 422. Insufficient
wallet balance returns 402.
Corps de la requête
toRecipient phone number in E.164 format (for example +14155550100). One recipient per message. The number is stored and returned in canonical E.164; a recipient that cannot be routed returns a 422 SMSInvalidRecipient.
fromSender to send from. It must be a sender the workspace holds: a number it owns in E.164, such as +15557654321, a short code it holds, such as 24680, or an alphanumeric sender ID it has claimed, such as MyBrand. A sender the workspace does not hold returns a 422 SMSSenderNotConfigured, and an alphanumeric sender must also be permitted, and where required registered, for the destination country. Required on a free-text send and when sending a workspace template. Omitting it in either case returns 422. A built-in template selects its sender automatically and rejects from.
textFree-text message body. Required unless template is supplied (the two are mutually exclusive). At least 1 character, up to a 12-segment cap (roughly 1836 GSM-7 or 804 UCS-2 characters). Bird does not truncate; a body exceeding 12 segments is rejected with a 422. The cap applies to segments because GSM-7 and UCS-2 encodings differ in characters per segment.
categoryContent classification: why you are sending. Required on a free-text send; omit it on a template send, where the category is derived from the template. Where the destination country requires the sender to be registered, a category outside what that registration covers returns a 422 SenderCategoryNotPermitted.
validity_periodPreview feature: how long, in seconds (60-172800), the carrier may keep attempting delivery before the message is marked expired. Currently unavailable; supplying this field returns 422 SMSUnsupportedFeature.
tagsStructured {name, value} labels for filtering and analytics. Tags become first-class query dimensions: filter the list endpoint by tag name, slice analytics by tag, and surface in webhook payloads. Maximum 20 tags per send. Use tags for low-cardinality dimensions (category, experiment_variant). For arbitrary structured context you do not need as a filter dimension, use metadata instead.
metadataArbitrary JSON object stored on the message, returned on API reads, and echoed in webhook payloads. Maximum 2 KB serialized. Use metadata for per-send context like internal IDs and foreign keys. For low-cardinality filterable labels, use tags instead.
optionsWhat Bird does to this message on its way out, such as smart_encoding. The message being relayed stays at the top level: its recipient, sender, content, and the delivery instructions the carrier acts on.
media_urlsPreview feature: multimedia (MMS) attachments. Currently unavailable; supplying this field returns 422 SMSUnsupportedFeature.
messaging_profile_idPreview feature: sender selection from a messaging profile pool. Currently unavailable; supplying this field returns 422 SMSUnsupportedFeature.
scheduled_atPreview feature: send-later scheduling. Currently unavailable; supplying this field returns 422 SMSUnsupportedFeature.
broadcast_idPreview feature: broadcast correlation. Currently unavailable; supplying this field returns 422 SMSUnsupportedFeature.
campaign_idPreview feature: campaign correlation for analytics. Currently unavailable; supplying this field returns 422 SMSUnsupportedFeature.
audience_idPreview feature: audience-targeted sends. Currently unavailable; supplying this field returns 422 SMSUnsupportedFeature.
contact_idPreview feature: contact-targeted sends. Currently unavailable; supplying this field returns 422 SMSUnsupportedFeature.
topic_idPreview feature: topic-gated sends. Currently unavailable; supplying this field returns 422 SMSUnsupportedFeature.
personalizationPreview feature: per-recipient substitution for batch sends. Currently unavailable; supplying this field returns 422 SMSUnsupportedFeature.
toRecipient phone number in E.164 format (for example +14155550100). One recipient per message. The number is stored and returned in canonical E.164; a recipient that cannot be routed returns a 422 SMSInvalidRecipient.
fromSender to send from. It must be a sender the workspace holds: a number it owns in E.164, such as +15557654321, a short code it holds, such as 24680, or an alphanumeric sender ID it has claimed, such as MyBrand. A sender the workspace does not hold returns a 422 SMSSenderNotConfigured, and an alphanumeric sender must also be permitted, and where required registered, for the destination country. Required on a free-text send and when sending a workspace template. Omitting it in either case returns 422. A built-in template selects its sender automatically and rejects from.
categoryContent classification: why you are sending. Required on a free-text send; omit it on a template send, where the category is derived from the template. Where the destination country requires the sender to be registered, a category outside what that registration covers returns a 422 SenderCategoryNotPermitted.
validity_periodPreview feature: how long, in seconds (60-172800), the carrier may keep attempting delivery before the message is marked expired. Currently unavailable; supplying this field returns 422 SMSUnsupportedFeature.
tagsStructured {name, value} labels for filtering and analytics. Tags become first-class query dimensions: filter the list endpoint by tag name, slice analytics by tag, and surface in webhook payloads. Maximum 20 tags per send. Use tags for low-cardinality dimensions (category, experiment_variant). For arbitrary structured context you do not need as a filter dimension, use metadata instead.
metadataArbitrary JSON object stored on the message, returned on API reads, and echoed in webhook payloads. Maximum 2 KB serialized. Use metadata for per-send context like internal IDs and foreign keys. For low-cardinality filterable labels, use tags instead.
optionsWhat Bird does to this message on its way out, such as smart_encoding. The message being relayed stays at the top level: its recipient, sender, content, and the delivery instructions the carrier acts on.
media_urlsPreview feature: multimedia (MMS) attachments. Currently unavailable; supplying this field returns 422 SMSUnsupportedFeature.
messaging_profile_idPreview feature: sender selection from a messaging profile pool. Currently unavailable; supplying this field returns 422 SMSUnsupportedFeature.
scheduled_atPreview feature: send-later scheduling. Currently unavailable; supplying this field returns 422 SMSUnsupportedFeature.
templateSend using a stored template instead of free text. The category is derived from the template, so category and media_urls are rejected. A workspace template requires from; a built-in template selects its sender and rejects from.
broadcast_idPreview feature: broadcast correlation. Currently unavailable; supplying this field returns 422 SMSUnsupportedFeature.
campaign_idPreview feature: campaign correlation for analytics. Currently unavailable; supplying this field returns 422 SMSUnsupportedFeature.
audience_idPreview feature: audience-targeted sends. Currently unavailable; supplying this field returns 422 SMSUnsupportedFeature.
contact_idPreview feature: contact-targeted sends. Currently unavailable; supplying this field returns 422 SMSUnsupportedFeature.
topic_idPreview feature: topic-gated sends. Currently unavailable; supplying this field returns 422 SMSUnsupportedFeature.
personalizationPreview feature: per-recipient substitution for batch sends. Currently unavailable; supplying this field returns 422 SMSUnsupportedFeature.
Contenu de la réponse
idID of the message, assigned when the send is accepted. Pass it as message_id to the get-message endpoint.
directionWhether the message was sent from a Bird sender (outbound) or received from a subscriber (inbound).
Possible values: outbound, inbound
statustoWhere 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.
fromWhere 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.
textThe 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.
categoryContent classification supplied for free text or derived from the template. Null for inbound messages.
requested_languageThe template language requested by the send, in canonical form. Null when the send named no language or used no template.
resolved_languageThe template language whose text was rendered, in canonical form. Null when the send used no template. This can differ from requested_language when the template's fallback policy selects another language.
template_idThe template rendered for this message, or null for a free-text message.
template_version_idThe workspace published version or synthetic built-in version rendered at acceptance, or null for a free-text message. For a built-in template, template_content_hash identifies the exact catalogue source.
template_content_hashThe rendered language's source fingerprint, or null for a free-text message.
costWhat the message cost, split into Bird's charge and any third-party fees passed through. Null until the message has been priced.
tagsStructured {name, value} filter labels applied to this message.
metadataArbitrary JSON metadata stored on the message and echoed in webhook payloads.
optionsThe 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.
validity_periodPreview feature: how long, in seconds, the carrier may keep attempting delivery before the message is marked expired. Not returned yet.
carrierCarrier 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_mncMobile country code and mobile network code of the carrier. Absent until the carrier is identified.
last_errorFailure detail on a message that failed, was rejected, was not delivered, or expired. Absent otherwise.
created_atWhen the message was accepted (outbound) or received (inbound).
sent_atWhen the message was handed to the carrier. Null until then.
delivered_atWhen delivery was confirmed. Null until then.
Ressources associées
Poursuivez avec la documentation, les guides et les exemples sur ce sujet.