WhatsApp Inbound OTP integration

Use this guide when you want the user to start verification from WhatsApp instead of receiving a code. Send channel: "whatsapp_inbound" to POST /v3/request. OTP.ID returns a WhatsApp number, an exact message, and a deep link. The user sends that message to OTP.ID, and OTP.ID verifies the transaction automatically. This channel does not use POST /v3/send and does not use POST /v3/verify.

Flow overview

Create an inbound transaction

Call POST /v3/request with channel: "whatsapp_inbound". Include destination only when you want to bind the verification to one sender number.

Show the WhatsApp action

Render verification.wa_link as the primary action. You can also show verification.wa_number and verification.message for manual copy.

User sends the exact message

The user opens WhatsApp and sends the pre-filled message to the OTP.ID WhatsApp number.

OTP.ID verifies automatically

OTP.ID matches the inbound message to the transaction and marks it verified.

Update your UI

Use the otp.verified webhook for server-side automation, or poll GET /v3/otp/{otp_id} while the UI is waiting.

Create the inbound transaction

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",
    "destination": "6281234567890"
  }'

Success response

{
  "success": true,
  "data": {
    "otp_id": "OTP20260811INBD000001",
    "status": "pending",
    "channel": "whatsapp_inbound",
    "number": "6281234567890",
    "price": 350,
    "last_balance": 99650,
    "expires_at": "2026-08-11 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-11 10:05:00"
    }
  },
  "error": null
}

If OTP.ID’s central WhatsApp number is temporarily not configured, this request fails with 503 CHANNEL_UNAVAILABLE instead of creating a transaction — you will never receive a broken wa_link. Treat it like any other channel outage: retry later or offer another channel. See the Error Codes reference.

Show the WhatsApp action

Use verification.wa_link as your primary button.

Verify with WhatsApp

Tap the button below to open WhatsApp.
Send the pre-filled message without editing it.

[ Open WhatsApp ]

Manual option:
Send this message to 6285212345678:
"OTPID V-8FK2QN9P — verifikasi TokoKita. Kirim pesan ini tanpa mengubah isinya."

The user must send the exact message. If they change the text, OTP.ID cannot match it to the transaction.

Detect verification

WhatsApp Inbound is verified automatically. Do not ask the user for a code and do not call POST /v3/verify.

Option A: Listen for the webhook

OTP.ID sends the otp.verified webhook after the inbound message is matched.

{
  "event": "otp.verified",
  "otp_id": "OTP20260811INBD000001",
  "channel": "whatsapp_inbound",
  "number": "6281234567890",
  "verified_at": "2026-08-11 10:01:38"
}

Option B: Poll the status endpoint

If your UI is waiting in real time, poll GET /v3/otp/{otp_id} until the transaction becomes verified or expires.

curl -X GET https://api.otp.id/v3/otp/OTP20260811INBD000001 \
  -H "Authorization: Bearer <api_key>"

While the transaction is still pending and has not expired, the response also includes the same verification block (wa_number, message, wa_link, expires_at) that POST /v3/request returned. Use it to re-render the WhatsApp button after a page reload instead of persisting the link yourself:

{
  "success": true,
  "data": {
    "otp_id": "OTP20260811INBD000001",
    "status": "pending",
    "channel": "whatsapp_inbound",
    "number": "6281234567890",
    "attempts": 0,
    "expires_at": "2026-08-11 10:05:00",
    "verified_at": "",
    "price": 350,
    "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-11 10:05:00"
    }
  },
  "error": null
}

Once the user’s message is matched, the verification block disappears and status becomes verified:

{
  "success": true,
  "data": {
    "otp_id": "OTP20260811INBD000001",
    "status": "verified",
    "channel": "whatsapp_inbound",
    "number": "6281234567890",
    "attempts": 0,
    "expires_at": "2026-08-11 10:05:00",
    "verified_at": "2026-08-11 10:01:38",
    "price": 350
  },
  "error": null
}

UI states to handle

State	What you should show
Pending	Show the WhatsApp button, destination WhatsApp number, exact message, and expiry countdown.
Waiting after tap	Keep the user on the screen and say “Waiting for your WhatsApp message.”
Invalid message	Tell the user to resend the exact message from the screen.
Expired	Disable the WhatsApp action and create a new request.
Success	Confirm verification and continue the flow.

Get Started

Core Concepts

Channel Guides

Guides

Reference

WhatsApp Inbound OTP integration

Flow overview

Create the inbound transaction

Request

Success response

Show the WhatsApp action

Detect verification

Option A: Listen for the webhook

Option B: Poll the status endpoint

UI states to handle

​Flow overview

​Create the inbound transaction

​Request

​Success response

​Show the WhatsApp action

​Detect verification

​Option A: Listen for the webhook

​Option B: Poll the status endpoint

​UI states to handle

​Related pages

Flow overview

Create the inbound transaction

Request

Success response

Show the WhatsApp action

Detect verification

Option A: Listen for the webhook

Option B: Poll the status endpoint

UI states to handle

Related pages