International WhatsApp OTP

|View as Markdown|Full Docs (.txt)

Every MiniMoth project can send OTPs to US and EU-area phone numbers over WhatsApp, using the exact same POST /v1/otp/send and POST /v1/otp/verify endpoints you already use for Indian (+91) numbers — just pass an international number instead:

const res = await fetch('https://api.minimoth.dev/v1/otp/send', {
  method: 'POST',
  headers: { 'X-Api-Key': 'mm_live_...', 'Content-Type': 'application/json' },
  body: JSON.stringify({ phone: '+1-2025551234' }),
})
const { message, otp_id, expires_at } = await res.json()
// 403 REGION_NOT_ENABLED if this project hasn't turned on the number's region yet
// 422 INVALID_PHONE if the number's country isn't a supported region at all

const res = await fetch('https://api.minimoth.dev/v1/otp/verify', {
  method: 'POST',
  headers: { 'X-Api-Key': 'mm_live_...', 'Content-Type': 'application/json' },
  body: JSON.stringify({ phone: '+1-2025551234', code: '123456' }),
})
const { access_token, refresh_token, expires_at, identity_id } = await res.json()
// Same response shape as a domestic (+91) verify -- nothing about the session,
// identity, or refresh-token lifecycle differs for an international number.

Enable International regions

Enable regions from your project’s International WhatsApp OTP card in the project details page, which shows the current rate for each region before you turn it on.

Supported regions

United States / Canada, United Kingdom, France, Netherlands, Germany, Rest of Western Europe, Spain, Italy, Poland, Hungary, Romania, and Rest of Central & Eastern Europe. Each is billed per OTP sent. If your project has its own connected WhatsApp Business Account instead, every international send is billed at a flat facilitation fee regardless of region — see Branding for connecting your own account.

Current rates for every region are shown in your project’s International WhatsApp OTP card in the dashboard before you enable one.

WhatsApp-only — no SMS fallback

Domestic (+91) sends try WhatsApp first and automatically fall back to SMS if delivery fails. International sends don’t — there’s no SMS route for these numbers at all, so a WhatsApp delivery failure surfaces directly instead of silently retrying over a different channel.

If a WhatsApp delivery fails, you get 502 INTERNATIONAL_WHATSAPP_FAILED and the charge for that attempt is automatically refunded to your wallet — no action needed on your end. See Error Codes for the full list.

Repeated failures block a number temporarily

After enough WhatsApp delivery failures for the same number in a short window, further sends to that number return 502 INTERNATIONAL_WHATSAPP_BLOCKED instead of attempting delivery again — no charge is made for a blocked attempt, since nothing was sent. The block clears on its own after the window passes without a new real failure.

Try the full OTP flow interactively in the sandbox — no SMS sent, no credits consumed. The same Playground also has a live test to send a real OTP to your phone (uses your credits).

Test in Playground →