SMS API FAQ

Install the SDK and send to the sanctioned test recipient +15005550006 in about five minutes. You can ship a CI check before you provision a number.

One send endpoint, two-way inbound, number provisioning (long codes, short codes, toll-free, and alphanumeric sender IDs), A2P 10DLC and opt-out compliance, direct-to-carrier routing, and delivery analytics, all on one API.

Bird reaches 150+ countries over 240 direct-to-carrier connections, with operator-grade route reselection when a carrier path degrades.

To send application-to-person traffic to US numbers, yes. Brand and campaign registration is handled in the dashboard, and status is queryable from the API.

Per message, at a rate that depends on the destination country and the sender type you send from, so a US long code and a UK alphanumeric sender are priced separately. Rates are published per country on the SMS pricing page.

Yes, billing is per segment rather than per message. One segment holds 160 GSM-7 characters, or 70 once a single emoji or non-Latin character forces the whole message to Unicode. Longer text is split and every segment is billed, so a stray character can double a large campaign's cost.

Carrier fees apply per message and vary by destination and carrier. In the US, 10DLC also carries brand and campaign registration fees. Both are listed on the SMS carrier fees page.

The SMS log shows the segment count and cost on each individual message once it's priced; SMS metrics aggregates accepted volume, segments, and spend over time.

A GSM-7 message fits 160 characters per segment; switching to Unicode (UCS-2) for emoji or non-Latin scripts drops that to 70. Longer messages are concatenated across segments, and the SDK reports the count before you send.

Twelve segments, which is roughly 1,836 GSM-7 characters or 804 Unicode ones. Bird never truncates: a body over the cap comes back as a 422 instead. The limit counts segments rather than characters precisely because the two encodings hold different amounts.

Up to 100 in a batch call, each with its own recipient and text. A single message goes to exactly one recipient, so a batch is how you fan out.

A free-tier key gets 10 single sends and 5 batch calls a minute, and paid plans raise both. Every response carries an IETF RateLimit header telling you what's left and when the window resets, so pace against that rather than a hard-coded number.

That's set by the carriers, not by Bird. A registered 10DLC long code gets throughput based on the brand's trust score and campaign type: more than an unregistered number, less than a short code. Short codes get the highest, most predictable rate.

For US application traffic, a 10DLC long code covers most two-way and OTP use cases. High-volume one-to-many programs move to a short code; toll-free is an option for US/Canada without 10DLC.

A long code or toll-free number is available immediately and starts sending once its registration or verification clears. Short codes are carrier-vetted and typically take weeks.

Yes. Long codes, short codes, and toll-free numbers are two-way: point a number's inbound traffic at a webhook and replies arrive as signed events. Alphanumeric sender IDs are one-way only.

It depends on the sender type and country. US application traffic needs A2P 10DLC, toll-free needs verification, and many countries require sender-ID pre-registration, all handled from the dashboard.

It's a short text string, usually your brand name, that shows in the recipient's "from" field instead of a phone number. It's a label on the message, not a number you own.

Keep it short: typically up to 11 characters on GSM networks. The exact constraint depends on the destination country and carrier, and what each one accepts.

A toll-free number is an 8xx number (800, 888, 877, and the rest of the toll-free prefixes) that sends and receives SMS across the US and Canada. It carries application traffic without A2P 10DLC, once it has passed toll-free verification.

No. Toll-free numbers sit outside the A2P 10DLC system. Instead they go through toll-free verification, where the carriers review the use case and message content before the number is allowed to send at full volume.

A 10-digit long code (10DLC) is a standard local phone number sanctioned for application-to-person SMS in the US once its brand and campaign are registered with the carriers.

Registered 10DLC long codes get vetted throughput that depends on the brand's trust score and campaign type: more than an unregistered number, less than a short code.

A short code is a 5–6 digit number that carriers approve for high-volume one-to-many SMS: marketing campaigns, alerts, and high-rate OTP. It's the highest-throughput sender type, and it goes through carrier vetting before it can send.

Plan in weeks, not minutes. Carriers vet every short code program before it goes live, so a short code carries a real lead time, unlike a long code, which you can buy and start sending on as soon as registration clears.

A dedicated short code is yours alone, so its sending reputation is entirely your own. A shared short code splits a number across senders behind keywords: cheaper, faster to start, but you inherit the reputation of everyone else on it.

You do, on a free-text send: pass a number your workspace owns, a short code, or an alphanumeric sender ID where the destination country allows one. Leave it out and the send is rejected rather than guessed at. A template send is the exception, because it selects its own sender.

It tells Bird and the carriers why you're sending, and per-country compliance rules such as opt-out policy and quiet hours key on it. It's required on a free-text send; a template send inherits the template's own classification.

Pass an idempotency key and a retried request returns the original result instead of sending twice. Without one, a retry is treated as a new message.

Every state change fires an HMAC-signed webhook (queued, sent, delivered, or failed), carrying the carrier delivery receipt and the segment count.

Every message sent to your provisioned number arrives as an HMAC-signed sms.received webhook. You verify one signature, read the from, to, and text, and route it into your own logic, the same envelope you already handle for delivery receipts.

Yes. Reply by sending from the same number the message came in on. Set from to your number and to to the original sender, and the thread stays on one number end to end.

Bird adds the sender to your suppression list and fires sms.opted_out, and blocks later sends to that number automatically. HELP returns a help reply and START opts them back in, all handled before they reach your code, so you stay compliant without writing the keyword logic yourself.

You need a two-way-capable number. Long codes, short codes, and toll-free numbers support inbound; alphanumeric sender IDs are send-only and can't receive replies.

Your message hands off straight to the mobile operator over one of our 240 direct connections, not through a chain of resellers. Fewer hops means fewer places for a message to stall or a delivery receipt to go missing.

Bird reselects the route in real time. If a path starts dropping receipts or slowing down, the next message takes a healthier connection to the same operator, and the send you wrote never changes.

Every message returns a carrier delivery receipt as an sms.delivered or sms.failed webhook, carrying the mcc_mnc, country, and latency_ms. That is the operator's own confirmation, not an inference from our side.

Yes. We run an MNP lookup on every send to resolve the recipient's current operator, so a ported number routes to the carrier that actually holds it. For standalone number intelligence, see Lookup.

Routing balances cost and delivery quality per destination. Transactional traffic like one-time passcodes favors the highest-quality path; bulk traffic can lean toward least cost. The selection happens per message, behind the same API call.

From the carrier delivery receipt (DLR) for each send. Bird records the receipt against the message, then rolls those receipts up into delivery, failure, and latency figures. A delivered count is the carrier confirming receipt, not Bird guessing.

Yes. The stats API takes a groupBy of country, carrier (by MCC/MNC), sender, and time bucket, in any combination. A failure rate that looks fine nationally often turns out to be one carrier rejecting one sender ID.

Either. Every delivery state already arrives as a webhook, so you can build your own store from the event stream. The stats API is there when you want Bird to do the aggregation instead of keeping a counter yourself.

Pass the message ID to the events endpoint and you get its full timeline: queued, sent, delivered or failed, each with a timestamp and, on failure, the carrier reason code. That is the report you actually need when a customer says a text never arrived.

Yes. Opt-out is reversible. A recipient who texts START is removed from the suppression list and can receive messages again. The choice stays with the recipient.

The suppression list is a queryable API resource. Look up a number before you build an audience so an opted-out recipient never re-enters a send.

It depends on where you send and what you send. US application traffic needs A2P 10DLC brand and campaign registration. Many countries require sender-ID pre-registration for alphanumeric senders. Opt-out handling applies everywhere and needs no setup.

Bird files each registration with the carriers or registries and reports its status through the API. Your code can poll the registration's state and wait for approval rather than send into a campaign that isn't live yet.

No. It uses the same client and keys as sending, numbers, and two-way. Registration status and the suppression list are API resources alongside the send call, so one integration covers both sending and the rules around it.

To curb spoofing, many countries only deliver alphanumeric sender IDs that have been pre-registered with the local carriers or regulator. Where that rule applies, an unregistered branded sender is rejected or rewritten.

Bird does. You submit the sender ID and destination from the dashboard, Bird carries it to the local registry, and the API reports its status so you know when the sender is live.

Approval runs through external carriers and registries and varies by country, typically days to weeks. Poll the registration's status through the API and wait for it before sending from that sender ID.

A2P 10DLC is the US carrier framework for application-to-person SMS sent over standard 10-digit long codes. A business registers the brand behind its traffic and a campaign describing the messages, and the carriers vet both before granting throughput.

The brand is the legal entity sending the traffic. A campaign describes a specific messaging use case under that brand. One brand can have several campaigns, and you associate numbers with a campaign rather than the brand.

Brand and campaign vetting runs through the carriers and registry and typically takes days to weeks. Query the campaign's status through the API so your code waits for approval before it sends.

No. 10DLC is a US framework. Other countries have their own rules, many requiring sender-ID pre-registration instead, and opt-out keyword handling applies wherever you send.

Your call to Bird is, over HTTPS, and so is the inbound webhook we send you. The last hop isn't ours to encrypt: SMS is a carrier protocol with no end-to-end encryption, and the message is readable on the handset and to the carrier. That's the reason to keep secrets out of the body and to prefer WhatsApp or email for anything sensitive.

Every event is HMAC-signed. Verify the signature with your endpoint's secret before you act on the payload, and rotate that secret from the dashboard whenever you need to.

In the region your organization is hosted in, either us1 or eu1. Your API key carries it in its prefix (bk_us1_…, bk_eu1_…), which is how the SDKs and the CLI pick the right endpoint without you configuring one.

Only what you scope it to. A key carries a list of scopes, each at read or write, so a key that sends SMS cannot manage your numbers or read another channel. Control-plane actions like managing members and issuing keys are dashboard-only and no key can reach them.

Both. A key takes an allowlist of CIDR ranges and rejects requests from anywhere else, and rotating one leaves the old key working for a grace period (24 hours by default, or zero to cut it off immediately) so a roll needs no downtime.

Yes. The audit log is a read-only, organization-wide record of every management action, with the actor, the workspace, the time and the outcome, and it exports to OCSF for your own SIEM.

Certifications and security documentation live in the Trust Center at trust.bird.com. The data processing agreement, privacy statement and acceptable use policy are published at bird.com/legal. For a vendor questionnaire, your Bird account team handles it.