Set OTPMOCK_URL=https://api.otpmock.com in your test environment, point the Bird (MessageBird) client at it, and use your otpmock API key as the Bird (MessageBird) credential. Your application code doesn't change, and production keeps sending real SMS through Bird (MessageBird).
Setup
The official SDK has a baseUrl option that overrides the region host derived from the key.
import { BirdClient } from "@messagebird/sdk";
export const bird = new BirdClient({
apiKey: process.env.BIRD_API_KEY, // otpmock API key in tests
...(process.env.OTPMOCK_URL && { baseUrl: process.env.OTPMOCK_URL }),
});Credentials. In the test environment, set your Bird API key variable to your otpmock API key. With baseUrl set, the SDK no longer needs the bk_{region}_ key prefix.
What otpmock emulates
| Endpoint | What it does |
|---|---|
POST /v1/sms/messages | Send one SMS (to, from, text, category), 202 with status: "accepted" |
Responses and errors follow Bird (MessageBird)'s own format, so the SDK parses them as usual. Authentication failures and an exhausted monthly allowance also come back in Bird (MessageBird)'s error shape.
Phone numbers
Send in E.164 (+15550142), as Bird expects.
Read the code in your tests
const phone = otp.randomPhone();
const since = Date.now() - 5_000;
await page.getByRole("button", { name: "Send code" }).click(); // your app calls Bird (MessageBird)
const { code } = await otp.waitForCode(phone, { since });The otp helper is a single file: get it from the docs. Full walkthroughs: Playwright, Cypress.
Good to know
- This is Bird's current SMS API. The legacy MessageBird API (
rest.messagebird.com/messages) and its oldmessagebirdnpm package aren't emulated: that SDK can't be pointed at another host. - When the monthly allowance is used up, otpmock returns Bird's
billing_error(402) rather than a rate-limit error, so the SDK doesn't retry in a loop.
FAQ
Does otpmock send real SMS through Bird (MessageBird)?
No. In the test environment your app's Bird (MessageBird) requests go to otpmock, which stores the message for 10 minutes and never contacts Bird (MessageBird) or any carrier. Production keeps using Bird (MessageBird) because otpmock is only enabled when OTPMOCK_URL is set.
Is the official @messagebird/sdk SDK supported?
Yes. otpmock's Bird (MessageBird) endpoints are tested end to end with the official @messagebird/sdk package for Node.js. Other languages work too if their Bird (MessageBird) client lets you change the API host.
Which Bird (MessageBird) APIs does otpmock support?
POST /v1/sms/messages (Send one SMS (to, from, text, category), 202 with status: "accepted").
The free plan includes 100 messages a month. Using an AI coding assistant? Point it at otpmock.com/llms-full.txt.
Get a free API key