WhatsApp Inbound OTP: Tap-to-Verify for Mobile Apps

The whatsapp_inbound channel flips the normal OTP flow: instead of OTP.ID sending a code to the user, the user sends a pre-filled message to OTP.ID. This approach is popular in mobile apps because a single tap on a deep-link opens WhatsApp with the verification message already composed — no typing required. OTP.ID matches the token in the incoming message, marks the transaction as verified, and fires the otp.verified webhook to your server.

How it works

Request a WhatsApp Inbound OTP

Call POST /v3/request with "channel": "whatsapp_inbound". You do not need to supply number (see Binding vs. Unbound below).

Receive the verification block

The API response includes a verification object containing OTP.ID’s central WhatsApp number, the exact message text the user must send, and a deep-link that pre-fills the message in WhatsApp.

Display the deep-link or message to the user

Show a “Verify via WhatsApp” button powered by wa_link, or display the message text so the user can copy and send it manually.

User sends the message

The user taps your button (or manually sends the message) to OTP.ID’s WhatsApp number. The message text must be sent verbatim — any modification breaks the token match.

OTP.ID matches the token and verifies

OTP.ID receives the message, matches the embedded token against the pending transaction, marks it as verified, and fires the otp.verified webhook to your server.

Sending the request

curl -X POST https://api.otp.id/v3/request \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "whatsapp_inbound",
    "brand": "TokoKita",
    "ttl": 300
  }'

Request body:

{
  "channel": "whatsapp_inbound",
  "brand": "TokoKita",
  "ttl": 300
}

Response with the `verification` block

A successful request returns a verification object in addition to the standard transaction fields. The status is "pending" — it transitions to "verified" when the user sends the correct message.

{
  "success": true,
  "data": {
    "otp_id": "OTP20260807ABCD000002",
    "status": "pending",
    "channel": "whatsapp_inbound",
    "number": "",
    "price": 350,
    "last_balance": 99300,
    "expires_at": "2026-08-07 10:05:00",
    "verification": {
      "wa_number": "6285212345678",
      "message": "OTPID V-8FK2QN9P — verifikasi TokoKita. Kirim pesan ini tanpa mengubah isinya.",
      "wa_link": "https://wa.me/6285212345678?text=OTPID%20V-8FK2QN9P%20%E2%80%94%20verifikasi%20TokoKita.%20Kirim%20pesan%20ini%20tanpa%20mengubah%20isinya.",
      "expires_at": "2026-08-07 10:05:00"
    }
  },
  "error": null
}

`verification` field reference

Field	Description
`wa_number`	OTP.ID’s central WhatsApp number the user must send to
`message`	The exact text the user must send, verbatim
`wa_link`	A `wa.me` deep-link that opens WhatsApp with the message pre-filled
`expires_at`	When the token expires (matches the top-level `expires_at`)

In mobile apps, render wa_link as a prominent button — for example, “Verify via WhatsApp”. On Android and iOS, tapping this link opens WhatsApp directly with the correct message pre-filled in the compose field. The user only needs to tap Send. This dramatically improves completion rates compared to asking the user to copy and paste a code.

Binding vs. unbound

You can optionally include a number in your request to restrict verification to a specific phone number.

Mode	Request	Behaviour
Unbound	No `number` field	Any WhatsApp user who sends the correct token is accepted. Useful for anonymous or pre-login flows.
Bound	Include `"number": "628..."`	OTP.ID only accepts the message if it comes from that specific WhatsApp number. Adds an extra layer of assurance.

Bound request example:

{
  "channel": "whatsapp_inbound",
  "number": "6281234567890",
  "brand": "TokoKita",
  "ttl": 300
}

Handling completion

Because the user acts in a separate app, your server learns about verification via the otp.verified webhook rather than a synchronous API response. In your UI, you can:

Poll GET /v3/otp/{otp_id} every few seconds and check status === "verified".
Listen for the webhook (recommended) and push a notification to your frontend via WebSocket or SSE when the event arrives.

See the Webhooks guide for payload details and how to verify the webhook signature.

Limitations

whatsapp_inbound is not supported by POST /v3/send. You must use POST /v3/request for this channel. Additionally, POST /v3/verify is not called by your server for this flow — verification happens automatically when OTP.ID receives the user’s WhatsApp message.

Get Started

Core Concepts

Guides

Reference

WhatsApp Inbound OTP: Tap-to-Verify for Mobile Apps

How it works

Sending the request

Response with the `verification` block

`verification` field reference

Binding vs. unbound

Handling completion

Limitations

​How it works

​Sending the request

​Response with the verification block

​verification field reference

​Binding vs. unbound

​Handling completion

​Limitations

How it works

Sending the request

Response with the `verification` block

`verification` field reference

Binding vs. unbound

Handling completion

Limitations