Send a batch of SMS messages
POST
/v1/sms/batches
const result = await bird.sms.sendBatch([
{ to: "+15551111111", text: "Hi Alice!", category: "marketing" },
{ to: "+15552222222", text: "Hi Bob!", category: "marketing" },
]);batch = client.sms.send_batch(
messages=[
{"to": "+15551111111", "text": "Hi Alice!", "category": "marketing"},
{"to": "+15552222222", "text": "Hi Bob!", "category": "marketing"},
]
)
for msg in batch.data:
print(msg.id, msg.status)batch, err := client.Sms.SendBatch(context.Background(), bird.SmsSendBatchParams{
Messages: []bird.SmsSendParams{
{To: "+15551111111", Text: "Hi Alice!", Category: bird.SMSCategoryMarketing},
{To: "+15552222222", Text: "Hi Bob!", Category: bird.SMSCategoryMarketing},
},
})
if err != nil {
log.Fatal(err)
}
for _, msg := range batch.Data {
fmt.Println(msg.Id, *msg.Status)
}$batch = $bird->sms->sendBatch([
(new SMSMessageSendRequest())->setTo('+15551111111')->setText('Hi Alice!')->setCategory('marketing'),
(new SMSMessageSendRequest())->setTo('+15552222222')->setText('Hi Bob!')->setCategory('marketing'),
]);
foreach ($batch->getData() ?? [] as $item) {
echo $item->getId(), ' ', $item->getStatus(), "\n";
}curl -X POST "https://us1.platform.bird.com/v1/sms/batches" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '[
{
"to": "+15551111111",
"from": "+15557654321",
"text": "Hi Alice!",
"category": "marketing"
},
{
"to": "+15552222222",
"from": "+15557654321",
"text": "Hi Bob!",
"category": "marketing"
}
]'Sends up to 100 independent SMS messages in one request. Each item is a
complete send request with its own recipient, content, id, status, and
cost. For a single message, use
Send an SMS message instead.
Acceptance is all-or-nothing: every item is validated before any is queued,
and one invalid item rejects the whole batch with a 422 (nothing is
sent). A batch from a workspace with no wallet balance fails with a 402.
The 202 response lists the accepted messages in submission order; each
delivers asynchronously and is tracked individually, like a single send.
请求载荷
对象数组,每个对象包含:
to
string
Recipient 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.
from
string
Sender to send from: an E.164 number (+15557654321), an alphanumeric sender ID (1-11 letters, digits, spaces, dashes, or underscores, at least one of them a letter, for example MyBrand), or a short code (5-6 digits). A numeric sender must be a number your workspace owns; an alphanumeric sender is accepted where the destination country permits one. Required on a free-text send: omitting it returns a 422 SMSNoEligibleSender. Not accepted alongside template, which selects its sender automatically.
text
string
必填
Free-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 limit is on segment count, not characters, because GSM-7 and UCS-2 encodings differ in characters per segment.
category
string
Content classification. Tells Bird and carriers why you're sending; per-country compliance rules (opt-out policy, quiet hours) key on it as they roll out. Required on a free-text send; omit it on a template send, where the category is derived from the template.
validity_period
integer
Preview feature: how long, in seconds (60-172800), Bird keeps trying to deliver before the message transitions to expired. Currently unavailable; supplying this field returns 422 SMSUnsupportedFeature.
tags
array of object
Structured {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.
显示子参数
tags.name
string
必填
Tag name. ASCII letters, digits, underscore, and hyphen only. Case-sensitive. Maximum 32 characters.
tags.value
string
必填
Tag value. ASCII letters, digits, underscore, and hyphen only. Case-sensitive. Maximum 64 characters.
metadata
object
Arbitrary 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.
options
object
What 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.
显示子参数
options.smart_encoding
boolean
Replace characters outside the GSM-7 alphabet with their closest GSM-7 equivalent before sending: typically curly quotes, dashes, ellipses, fullwidth forms, and non-breaking spaces.
One such character forces the whole body into UCS2, which more than halves the characters that fit in a segment, so replacing them often lowers the segment count and the cost.
Disabled by default, because it alters the body you composed. The replacement is all-or-nothing: a body that still holds a character outside the alphabet afterwards, such as an emoji or a non-Latin script, is sent exactly as you supplied it. Read the message back to see what was applied: text is the body as sent.
options.track_clicks
boolean
Preview feature: link click tracking. Defaults to false. Currently unavailable; setting this to true returns 422 SMSUnsupportedFeature.
options.max_price_per_segment
number
Preview feature: per-segment price ceiling. Currently unavailable; supplying this field returns 422 SMSUnsupportedFeature.
media_urls
array of string
Preview feature: multimedia (MMS) attachments. Currently unavailable; supplying this field returns 422 SMSUnsupportedFeature.
messaging_profile_id
string
Preview feature: sender selection from a messaging profile pool. Currently unavailable; supplying this field returns 422 SMSUnsupportedFeature.
scheduled_at
string
Preview feature: send-later scheduling. Currently unavailable; supplying this field returns 422 SMSUnsupportedFeature.
template
object
必填
Send using a stored template instead of free text. Mutually exclusive with text; the message category is derived from the template, so from, category, and media_urls are not accepted alongside it.
显示子参数
template.id
string
必填
The template to send, by its id.
template.slug
string
必填
The template to send, by its slug handle (for example bird_otp_verification). Browse the available templates and their variables with the templates endpoint.
template.name
string
必填
Deprecated: use slug instead. Resolved as a slug first, and only if that finds nothing, matched against the template's display name.
template.language
string
Which of the template's languages to send. Omit it to send the template's default language, unless the template sets language_source_required, in which case a send naming no language is rejected. When the template does not carry the language you ask for, its own on_missing_language setting decides whether the closest available language is sent instead or the send is rejected.
template.parameters
object
Values for the template's variables, keyed by variable name. The accepted keys and their formats are fixed per template (the template's variables on the templates endpoint). A missing required variable, an undeclared key, a value that does not match its variable's format, or a serialized payload over 16 KB each return a 422.
broadcast_id
string
Preview feature: broadcast correlation. Currently unavailable; supplying this field returns 422 SMSUnsupportedFeature.
campaign_id
string
Preview feature: campaign correlation for analytics. Currently unavailable; supplying this field returns 422 SMSUnsupportedFeature.
audience_id
string
Preview feature: audience-targeted sends. Currently unavailable; supplying this field returns 422 SMSUnsupportedFeature.
contact_id
string
Preview feature: contact-targeted sends. Currently unavailable; supplying this field returns 422 SMSUnsupportedFeature.
topic_id
string
Preview feature: topic-gated sends. Currently unavailable; supplying this field returns 422 SMSUnsupportedFeature.
personalization
object
Preview feature: per-recipient substitution for batch sends. Currently unavailable; supplying this field returns 422 SMSUnsupportedFeature.
响应载荷
data
array of object
必填
One entry per message in the batch, in submission order.
显示子属性
data.id
string
必填
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
必填
Whether the message was sent from a Bird sender (outbound) or received from a subscriber (inbound).
Possible values: outbound, inbound
data.status
string
必填
data.to
string
必填
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
必填
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
必填
Segment breakdown for the body.
显示子属性
data.segments.count
integer
必填
Number of segments the body is split into. Each segment is a billable unit.
data.segments.encoding
string
必填
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
必填
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.
显示子属性
data.cost.amount
string
必填
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
必填
ISO 4217 currency code. Every component is denominated in this currency.
data.cost.transaction_amount
nullable string
必填
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
必填
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.
显示子属性
data.tags.name
string
必填
Tag name. ASCII letters, digits, underscore, and hyphen only. Case-sensitive. Maximum 32 characters.
data.tags.value
string
必填
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.
显示子属性
data.options.smart_encoding
boolean
必填
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.
显示子属性
data.last_error.code
string
必填
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
必填
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
必填
When the failure occurred.
data.created_at
string
必填
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.
summary
object
必填
Aggregate result for the batch.
显示子属性
summary.accepted_count
integer
必填
Number of messages accepted in the batch. Acceptance is all-or-nothing, so this equals the number of messages submitted.