Short code, long code, toll-free or alphanumeric: which SMS sender type should I use?

A sender that works in one destination can be ineligible in another. Reply support also depends on the individual number and its route.

What are the four sender types?

Bird supports long codes, short codes, toll-free numbers and alphanumeric sender IDs. Their API values are long_code, short_code, toll_free and alphanumeric.

The country policy can allow toll-free numbers while refusing long codes. Registration requirements can also differ:

The toll_free value is distinct from long_code. A country can permit one and refuse the other, and the two usually demand different registration.

• Long code. An ordinary phone number used for messaging. Sending and receiving depend on its SMS capabilities and destination support.
• Toll-free. An SMS-capable number in a supported toll-free range, with its own verification and routing requirements.
• Short code. A short numeric identity used for messaging programs. Length, availability, send rate and registration vary by market.
• Alphanumeric. A name displayed as the sender, with an 11-character limit. A longer brand name needs a shorter sending identity. Recipients cannot address a reply to it.

Which sender types can receive a reply?

Eligible long codes, toll-free numbers and short codes can support replies. Check the number's SMS capabilities and destination route because its shape does not establish reply support.

If your program needs incoming messages, choose a number that supports replies because recipients cannot reply to an alphanumeric name. This requirement also applies when a subscriber must text a stop keyword back to the sender.

Country policy reports reply support as a direction of one_way or two_way for each sender type. With a supported number and route, incoming SMS can reach your application.

How do I choose without knowing every country's rules?

Use the destination's published sender-type policies, then check the requirements of the sender you intend to use. A country publishes policy entries for its reported sender types. An absent type is unsupported there. A listed type still has its own availability status.

Each policy entry reports these fields:

• status, one of available, restricted, coming_soon or unavailable.
• registration_mode, one of none, optional, or required, and the program that runs the registration when one applies.
• sender_id_behavior: preserved keeps the sender ID you submit, overwritten replaces it before delivery, and unknown means the behavior is not confirmed. This is independent of registration mode, so a required registration can still overwrite the sender ID after approval. Optional registration preserves the approved sender ID and overwrites it before approval.
• registration_timeline_min and registration_timeline_max, in business days, where the country publishes an estimate.
• throughput_mps, the published maximum send rate in messages per second for that sender type and destination. For example, a value of 30 describes a ceiling of 30 messages per second. A null value provides no published rate. Confirm the available account, sender and carrier capacity because these can further constrain your actual sending rate.
• direction, one-way or two-way.
• allowed_source_countries, the countries the sender may originate from. An empty list imposes no source-country restriction.

You can compare published country policies in SMS destinations. Read your sender's requirements separately because country policy does not establish that sender's registration status:

bird sms senders requirements <sender-id> --country-code NL

A nonempty allowed_source_countries list limits eligibility to senders from those countries. A sender from another country has no route under that policy. Registration cannot make that origin eligible.

What decides which sender Bird actually uses?

For a free-text API send, supply the eligible sender in from. The API does not choose a sender pool when you omit it. A system-template send selects its sender from the template. The returned from value identifies the sender used for that message.

The country policy's routing priority does not select the sender for a free-text request. Your application supplies it.

Registration and destination access are separate. A registered sender can still be blocked when the workspace has not enabled the destination, with E12020.

What should I actually do?

1. Choose a sender type supported by the destination, including any source-country restrictions.
2. Choose a supported number when replies are required, including incoming stop keywords.
3. Allow for required registration and any optional registration you choose, using the published timeline to plan the release.
4. Compare the published send-rate ceiling with your peak traffic, then confirm the account, sender and carrier capacity.
5. Confirm sender registration and workspace destination access before sending.