Channel orchestration
Bird decides the defaults. You tune a single call.
Channel availability, sender rules, and regulations differ by country, and getting them right is years of work. Bird ships that as a per-country base: which channels land where, which senders are allowed, and sane code defaults, drawn from running email and SMS at scale. A create call already resolves to the right plan for any country, and its options field can reorder or narrow the channels or set the code length for that one verification.
import { BirdClient } from "@messagebird/sdk";
const bird = new BirdClient({
apiKey: process.env.BIRD_API_KEY!,
});
// Send the code, then check it by recipient.
await bird.verify.verifications.create({
to: { phone_number: "+15551234567" },
}).safe();
const { data, error } = await bird.verify.verifications.check({
to: { phone_number: "+15551234567" },
code: userInput,
}).safe();
if (error) throw error;
Bird's defaults travel with every call.
Every verification on the Bird Verify API resolves against a per-country base Bird maintains from years of running email and SMS, so a verification already routes sensibly in every country before you write a line of code. A per-request option can still tune a single call: reorder or narrow the channels, or set the code length. You're never starting from a blank slate.
Two layers decide the plan.
The narrower one wins; whatever a request doesn't set falls through to Bird's per-country base.
- 01
Per-request options.
Pass channels or code_length on the create call to reorder or narrow the channels, or set the code length, for that one verification. Omit either and the country's default applies.
- 02
Bird's per-country base.
Bird's own per-country defaults, drawn from running email and SMS at scale: which channels are available, which senders are allowed, and sane code and TTL defaults. Whatever a request doesn't override resolves from this, so a verification always lands on a sensible plan.
What a verification resolves to.
A Brazilian number resolves against Bird's per-country base for Brazil, narrowed by any per-request options on the call. WhatsApp and SMS are both available there, so the verification reports that ordered plan, with its typed vrf_ id.
const { data, error } = await bird.verify.verifications.create({
to: { phone_number: "+5511998765432" }, // Brazil
}).safe();
if (error) throw error;
// Resolved from the per-country base, capped by availability and the kill-switch:
// {
// id: "vrf_01k2m9q8e7fh3v0b7m4d2a9xzt",
// status: "pending",
// channels: [{ channel: "whatsapp" }, { channel: "sms" }],
// last_channel: "whatsapp"
// }
Two ceilings sit above the defaults.
The two layers above decide defaults. Two gates decide what's allowed on top of that, and each one only narrows the resolved plan:
Per-country availability. A country's resolved plan only ever includes channels Bird actually offers there. A request's options can reorder or narrow that plan; they can't add a channel the country doesn't support, since availability is an intersection.
Global kill-switch. When a provider has an incident, Bird can pull a channel everywhere at once. The resolved plan simply falls back to the next channel, then restores automatically when the switch clears.
The plan is on every response.
Resolved per verification, returned on the response.
- 01
The resolved plan is on the response.
Every verification reports the ordered channels it resolved to, so the resolved plan is never a mystery.
- 02
Automatic failover is rolling out.
Delivery-driven advancement through the plan (trying the next channel when one doesn't land) is rolling out as delivery status lands. The plan is already resolved and returned today.
The rest of the Verify platform
One API, one set of keys. Explore the other capabilities.
Per-country defaults you don't have to build yourself.
Per-country defaults are one capability of Bird Verify: the channels, the code, and the limits ship with it, on the same create and check calls.