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.

Yes, automatically per recipient. STOP opts a recipient out and adds them to a queryable suppression list, HELP returns an automatic help reply, and START opts them back in.

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.

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.

No. Alphanumeric senders are one-way. There's no number behind them to route a reply to, so recipients can't text back. Use a long code, short code, or toll-free number when you need two-way traffic.

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.

Often, yes. Many countries require an alphanumeric sender ID to be pre-registered before it will deliver, and some block unregistered ones outright. Register the ID per country before you rely on it.

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.

Yes. Toll-free numbers are two-way: route the number's inbound at a webhook and replies arrive as HMAC-signed events, the same as any other Bird SMS number.

Reach for a long code when you want a local area code or your US traffic already runs through A2P 10DLC. A toll-free number wins when you want one 8xx sender that covers both the US and Canada without registering 10DLC campaigns.

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.

Yes. Long codes are two-way: route the number's inbound at a webhook and replies arrive as HMAC-signed events.

When one-to-many volume outgrows what a long code's throughput supports, or when a program needs the higher, more predictable rate a carrier-vetted short code provides.

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.

When traffic is two-way and conversational, or volume doesn't justify the vetting and lead time. A long code is local, two-way by default, and live as soon as its 10DLC campaign clears.

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.

No. STOP, HELP, and START keywords are honored automatically on every send. A STOP suppresses the recipient, HELP triggers a help response, and START resubscribes them. The suppression list is queryable through the API.

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.

No. Bird recognizes STOP on every send, suppresses the recipient, and blocks further messages to that number. You don't write or maintain any keyword logic.

STOP suppresses the recipient and stops messages. HELP returns an automatic help response. START reverses a prior opt-out and resubscribes the recipient. Each is acted on per recipient.

It's a sender shown as a name rather than a phone number: your brand in the from field. It's one-way only, and where the destination country allows it, it makes a message recognizably yours.

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.

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.

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.

Yes. Batch independent messages in a single call, each with its own recipient and text. The batch validates as a unit, and one idempotency key covers the whole request.

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.