Test mode and magic numbers

Keys prefixed blu_test_ are sandbox keys. Sends made with them never reach WhatsApp or any provider, never bill, and are flagged as test data. The sandbox simulates the full delivery lifecycle so your status handling and webhook code run against realistic events.

The simulated lifecycle

A test send advances one step roughly every five seconds: queued → sent → delivered → read. At each stage your active webhook subscriptions receive the same events live traffic produces — message.sent, message.delivered, message.failed — signed with your endpoint secret and carrying "test": true in the payload.

Magic numbers

Deterministic recipients let you exercise every path your integration must handle:

Number	Behaviour
`+27800000001`	Always delivers (any other number behaves the same way).
`+27800000002`	Always fails at the send step with `recipient_unreachable` and fires `message.failed`.
`+27800000003`	Delivers, then fires a simulated `message.received` reply so you can test inbound handling.

Testing the failure path

failure.ts

await bt.contacts.upsert({ phone: "+27800000002", first_name: "Always Fails" });

const msg = await bt.messages.send({
  channel: "whatsapp",
  to: { phone: "+27800000002" },
  template_id: "<template id>",
});

// ~5 seconds later:
const failed = await bt.messages.get(msg.message_id);
console.log(failed.status); // "failed"
// and your webhook receives message.failed with "test": true

Validate-only requests

Independently of the key type, you can pass test_mode: true in a send body to validate auth, contact lookup, template variables, and opt-outs without creating anything at all — the safest very first call:

validate.ts

const check = await bt.messages.send({
  test_mode: true,
  channel: "whatsapp",
  to: { phone: "+27821234567" },
  template_id: "<template id>",
  template_variables: { "1": "Sam" },
});
console.log(check.status); // "validated"
console.log(check.rendered_body_preview);

Differences from live

No provider calls, no Meta quality/tier effects, no billing.
Timing is fixed (~5s per step); live WhatsApp delivery timing varies.
Test rows are flagged test_mode in your workspace data.