WhatsApp OTP API

Overview

People open WhatsApp. Verification codes sent there get seen, and in most markets they cost a fraction of an SMS. This API sends a code through your own verified WhatsApp number, so the message arrives from your business, not from a shared shortcode. Deciding whether to use it rather than wiring it in? The service overview covers pricing, protections and where it fits, in plain language.

Two ways to use it. Pass your own code and Replio just delivers it — nothing about your existing verification logic has to change. Or omit code and Replio generates one, hashes and stores it, and hands you a matching verify endpoint to check what the user typed back — no code to write on your side at all.

Quickstart

Two steps: create a key in the dashboard, then send.

curl -X POST https://replio.live/api/otp/send \
  -H "Authorization: Bearer rpl_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"phone":"447911123456","code":"483920"}'

const res = await fetch("https://replio.live/api/otp/send", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.REPLIO_OTP_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ phone: "447911123456", code: "483920" })
});
const data = await res.json();
// { ok: true, sent_to: "+447911123456", template: "verify_code" }

import os, requests

resp = requests.post(
    "https://replio.live/api/otp/send",
    headers={"Authorization": f"Bearer {os.environ['REPLIO_OTP_KEY']}"},
    json={"phone": "447911123456", "code": "483920"},
    timeout=15,
)
resp.raise_for_status()
# {'ok': True, 'sent_to': '+447911123456', 'template': 'verify_code'}

That example passes its own code, so Replio only delivers it. Drop the code field and Replio will generate one and let you check it with POST /api/otp/verify instead.

Authentication

Every request carries your secret key as a bearer token.

Create the key in Dashboard → Engage → WhatsApp OTP API. Only the account owner can create or rotate it.

Send a code

Body parameters

Response

{
  "ok": true,
  "id": 48213,
  "sent_to": "+447911123456",
  "template": "verify_code",
  "credits_charged": 1,
  "verify_enabled": false
}

id identifies this send for delivery status and webhooks. verify_enabled is true only when you omitted code — that's what tells you whether POST /api/otp/verify has anything to check for this send.

Any non-2xx response carries a stable code you can branch on, plus a human readable message that may be reworded at any time.

{
  "detail": {
    "code": "recipient_rate_limited",
    "message": "That number has already had 5 codes in the last hour."
  }
}

Verify a code

Only checks codes Replio generated — send with code omitted, so verify_enabled came back true. A code you supplied yourself was never stored, so there's nothing here to check it against — keep verifying those on your side.

curl -X POST https://replio.live/api/otp/verify \
  -H "Authorization: Bearer rpl_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"phone":"447911123456","code":"482913"}'

Body parameters

Response

{ "ok": true, "verified": true }

A wrong or expired code is a normal 400, not a 200 with verified: false — same "branch on the error code" contract as send:

{ "detail": { "code": "incorrect_code", "message": "That code is incorrect." } }

Each pending code allows 5 wrong guesses before it's dead (too_many_attempts) and expires after its ttl_seconds (code_expired, 5 minutes by default). Sending a new code to the same number supersedes the old one — only the latest is ever checkable. A correct code is consumed: it cannot be verified a second time.

Email codes and fallback

Not everyone can receive WhatsApp: a landline, a typo, a phone without the app. Two ways to reach them without building a second integration:

Email only. Send with "channel": "email" and the person's email. Verify works exactly the same, by phone.

curl -X POST https://replio.live/api/otp/send \
  -H "Authorization: Bearer rpl_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"phone":"447911123456","channel":"email","email":"ada@example.com"}'

WhatsApp first, email if it doesn't land. Add "fallback": "email". If WhatsApp reports the code failed, Replio emails one straight away. If WhatsApp simply hasn't confirmed delivery within fallback_after_seconds (60 by default), it emails one then. A code that was delivered, or already verified, never falls back.

curl -X POST https://replio.live/api/otp/send \
  -H "Authorization: Bearer rpl_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"phone":"447911123456","email":"ada@example.com","fallback":"email"}'

The email carries its own code. Verify accepts either the WhatsApp code or the emailed one, whichever the person typed, and the first correct one closes both. That is why fallback needs Replio to generate the codes (omit code): we never store a code in readable form, so we can't resend yours.

Delivery status

WhatsApp reports what happened to every message. Ask for one send by the id send returned:

{
  "ok": true,
  "id": 48213,
  "phone": "+447911123456",
  "channel": "whatsapp",
  "status": "sent",
  "delivery_status": "delivered",
  "delivered_at": "2026-10-06T09:14:03+00:00",
  "error": null,
  "verified": true,
  "fallback": null
}

delivery_status moves forward through sent (WhatsApp accepted it), delivered (it reached the phone) and read, or ends at failed with WhatsApp's reason in error (for example 131026: the number can't receive WhatsApp). With a fallback, fallback.status is pending, sent, failed, no_balance or skipped_verified. Rather than polling, use webhooks.

Webhooks

Set a URL in your dashboard (OTP API → Webhook) and Replio posts an event as each send moves along. It must be a public https:// address.

{
  "event": "otp.delivered",
  "data": { "id": 48213, "phone": "+447911123456", "delivery_status": "delivered", …same fields as delivery status },
  "sent_at": "2026-10-06T09:14:03+00:00"
}

Check the signature

Every post carries X-Replio-Timestamp and X-Replio-Signature: v1=<hex>, an HMAC-SHA256 of timestamp + "." + raw body with your webhook secret. Reject anything that doesn't match, or whose timestamp is more than 5 minutes old.

const crypto = require('crypto');
function isFromReplio(rawBody, ts, sigHeader, secret) {
  const want = 'v1=' + crypto.createHmac('sha256', secret).update(ts + '.' + rawBody).digest('hex');
  return Math.abs(Date.now()/1000 - Number(ts)) < 300 &&
         crypto.timingSafeEqual(Buffer.from(want), Buffer.from(sigHeader || ''));
}

Answer with any 2xx within 5 seconds. A failed post is retried once. Events can arrive out of order, so read data.delivery_status rather than assuming the sequence.

Number check

Check a number before you send: whether it's valid, mobile or landline, its country and original carrier, and whether your earlier WhatsApp codes to it were delivered. Free, no credits.

curl -X POST https://replio.live/api/otp/lookup \
  -H "Authorization: Bearer rpl_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"phone":"2348031234567"}'

{
  "ok": true,
  "phone": "+2348031234567",
  "valid": true,
  "country": "NG",
  "country_code": 234,
  "type": "mobile",
  "carrier": "MTN",
  "e164": "+2348031234567",
  "national_format": "0803 123 4567",
  "whatsapp": { "status": "reachable", "last_seen": "2026-10-01T08:02:11+00:00", "source": "your earlier sends" }
}

type is mobile, fixed_line, fixed_line_or_mobile, voip, toll_free and so on, or unknown. carrier is the network the number was first issued on; a number moved to another network still shows its first one. whatsapp.status is reachable, unreachable or unknown, judged only from codes you sent: we never use other businesses' sends.

Verify widget

A ready-made "enter your code" box for your website: phone number, code entry with one-tap autofill, a resend timer and a clear success state. Two lines of HTML, and your API key never touches the browser.

1. On your server: start a session

curl -X POST https://replio.live/api/otp/sessions \
  -H "Authorization: Bearer rpl_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'
# { "ok": true, "id": "vs_9fK…", "client_secret": "vs_9fK…_secret_…", "expires_at": "…" }

All fields are optional: phone locks the widget to one number (the person can't change it), email plus "fallback": "email" turns on the email fallback, and ttl_seconds sets the session's life (60–3600, default 900). A test key makes a test session.

2. On your page: mount the widget

<div id="verify"></div>
<script src="https://replio.live/otp-widget.js"></script>
<script>
  ReplioVerify.mount('#verify', {
    clientSecret: 'vs_9fK…_secret_…',   // from step 1
    onVerified: function (r) {
      // r.sessionId → tell your server, which confirms it in step 3
    }
  });
</script>

3. On your server: confirm the result

{ "ok": true, "id": "vs_9fK…", "verified": true, "phone": "+2348031234567", "verified_at": "…" }

Each session allows 4 codes and 10 guesses for one number. Codes, credits, fallback and webhooks work exactly as for /api/otp/send.

Templates

WhatsApp requires business-initiated messages to use a template Meta has approved. You do not have to write one from scratch: Meta ships a library of ready-made ones.

In WhatsApp Manager → Message templates → Template library, filter to Authentication and pick one. Approval is usually quick because the wording is Meta's own.

Replio picks your template automatically in this order:

Template variables

Templates contain placeholders. The classic Authentication template has exactly one:

{{1}} is your verification code.

Nothing to do here. The code fills it automatically, including the one-tap copy button.

Many templates in Meta's library use named placeholders instead, and carry more than one:

Hi {{name}}, your {{item}} order is pending shipment.
The delivery person may ask for your delivery code {{code}}.

Anything named code, otp, pin or verification_code is filled with your code automatically. Everything else you supply:

{
  "phone": "447911123456",
  "code": "483920",
  "variables": { "name": "Sam", "item": "jacket" }
}

Miss one and the error names exactly which:

{ "code": "missing_variables",
  "message": "Template 'delivery_code_2' also needs: item." }

Up to 12 variables, each 120 characters or fewer.

Idempotency

Networks time out after the send has already happened. Pass an idempotency_key and a retry returns the original result rather than sending a second code and spending a second credit.

curl -X POST https://replio.live/api/otp/send \
  -H "Authorization: Bearer $REPLIO_OTP_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone":"447911123456","code":"483920",
       "idempotency_key":"signup-8f31c2a4"}'

A replayed request answers with "idempotent_replay": true. Use something tied to the attempt, such as your own session or signup id.

Test mode

Build the integration without spending credits or messaging real people. A test key validates the entire request, applies every rule, and stops short of sending or checking anything real.

A test key is a separate credential from your live one — create it in Dashboard → Engage → WhatsApp OTP API ("Create test key"), or via the API:

curl -X POST https://replio.live/api/otp/rotate \
  -H "Authorization: Bearer $REPLIO_LIVE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"test":true}'

That request is authenticated with your existing live key (only the account owner can mint either kind) and returns a new key starting rpl_sk_test_. Rotating it never touches your live key, and vice versa — they're independent credentials that can both be live at once.

{ "ok": true, "sent_to": "+447911123456", "test_mode": true }

Test sends appear in your logs marked as tests, and never bill. Verify works the same way in test mode — any phone and code you send it comes back verified: true, no real code needed.

Rate limits

The per-recipient limit is the important one. It stops a single number being pumped with codes, which costs you money and gets numbers reported. Need higher limits for a launch? Ask us.

Error codes

Retry upstream_error and rate_limited with backoff. Every 429 carries a Retry-After header (seconds) — honour it. Everything in the 400 range needs a change to the request. Always retry with the same idempotency_key.

Credits and pricing

OTP sends draw on their own prepaid balance, separate from your Replio message allowance. That is deliberate: your users' sign-ins should never fail because your support inbox had a busy month.

Credits never expire. Only a delivered send costs credits: rejected requests, rate limits, failed sends and test-mode calls are all free.

Premium destinations

One credit sends to almost everywhere. Three destinations cost two credits, because WhatsApp itself charges several times more to deliver there:

Every response tells you exactly what it cost, so you never have to infer it:

{ "ok": true, "sent_to": "+6281234567890",
  "template": "verify_code", "credits_charged": 2 }

Your live balance, usage and the current pack prices are on the dashboard and at GET /api/otp/config.

How this compares

Comparing providers? See Replio as a Twilio Verify alternative or a Dexatel alternative for WhatsApp OTP.

Twilio Verify charges $0.05 per verification plus the channel fee, about $0.053 for a WhatsApp code, at every volume. There is no separate monthly platform fee here: OTP credits are an add-on to the Replio account you already have.

Security

• Keys are stored as a hash. Nobody, including us, can read your key back to you.
• Only the account owner can create or rotate keys.
• Rotating takes effect immediately, so a leaked key can be killed in one click.
• Never put the key in front-end code. It sends from your verified business number.
• Generate codes with a cryptographically secure random source, and expire them quickly. (Let Replio generate the code and this is already handled for you.)
• Codes Replio generates are stored as a sha256 hash, never in plain text.

FAQ

Do you generate and verify the code for me?

Yes, if you want that. Omit code on send and Replio generates it, stores only its hash, and you check what the user typed with POST /api/otp/verify. Prefer to keep owning verification yourself? Pass your own code and nothing changes — Replio just delivers it, same as before this existed.

Can I use my own WhatsApp number?

Yes, and you should. Codes arrive from your verified business number.

What if the user has no WhatsApp?

Add "fallback": "email" and their email address, and Replio emails a code when WhatsApp can't deliver. See Email codes & fallback. You can also check the number first.

Which countries?

Anywhere WhatsApp operates. Per-message pricing is set by Meta and varies by country.

Is there an SDK?

Not needed. It is one JSON POST, shown above in three languages. Delivery results come to you by webhook, and the verify widget gives you the code-entry screen without building one.