en
Free Preview

WhatsApp OTP API Integration: PHP, Node.js and Python Examples

By: WapFlow Team · November 16, 2026 · 6 min read
Code editor showing a WhatsApp OTP API call and a verification code message on a phone

Sending a verification code over WhatsApp comes down to two calls with the WapFlow OTP API: one sends the code, the other verifies what the user typed. In this guide we collect how the API works, cURL, PHP, Node.js and Python examples, error handling and the security points to watch. The samples follow the format in the official API documentation, with only small additions for readability. If you are wondering what the product is before you start coding, read What Is WhatsApp OTP first.

The Basics

  • Base URL: https://wapflow.net/api/otp/v1
  • Authentication: an Authorization: Bearer <key> header on every request. Live keys start with wfo_live_, test keys with wfo_test_.
  • Response format: { "success": true, ... } on success, { "success": false, "error": { "code": "...", "message": "..." } } on failure.
  • Phone number: with the country code, for example 905321234567. The API reduces the number to digits (+, spaces and dashes are dropped) and expects 10 to 15 digits. Eleven-digit numbers starting with 0 are treated as Turkish and get 90 added in front.

You create the API key on the WapFlow OTP page of the WapFlow panel. A key is shown only once when it is created; keep it in an environment variable on your server.

Four Endpoints

EndpointPurpose
POST /sendGenerates the code and sends it over WhatsApp. phone is required; optional code_length (4-8), ttl (60-900 s), lang, app_name.
POST /verifyChecks the code the user typed. phone and code are required; if you pass request_id, that request is checked.
GET /status/:request_idReturns the request status: queued, sent, delivered, read, failed, verified, expired.
GET /meShows whether the key is valid, the plan, the number of connected accounts and this month's quota usage.

After 5 wrong attempts a request is locked, and a verified code cannot be used again. If you leave out request_id, the latest unexpired code sent to that number with this key is checked. Because several sessions may exist, we recommend storing the request_id and sending it back when verifying.

A First Try With cURL

# 1) send the code
curl -X POST https://wapflow.net/api/otp/v1/send \
  -H "Authorization: Bearer wfo_live_XXXX" \
  -H "Content-Type: application/json" \
  -d '{"phone":"905321234567","app_name":"Acme"}'

# 2) verify the code
curl -X POST https://wapflow.net/api/otp/v1/verify \
  -H "Authorization: Bearer wfo_live_XXXX" \
  -H "Content-Type: application/json" \
  -d '{"request_id":"req_...","phone":"905321234567","code":"123456"}'

Make the first attempt with a wfo_test_ key: no WhatsApp message is sent, no quota is used, and the code comes back in the test_code field of the response.

PHP Example

<?php
function wapflow_otp(string $path, array $body): array {
    $ch = curl_init('https://wapflow.net/api/otp/v1' . $path);
    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT => 15,
        CURLOPT_HTTPHEADER => [
            'Authorization: Bearer ' . getenv('WAPFLOW_OTP_KEY'),
            'Content-Type: application/json',
        ],
        CURLOPT_POSTFIELDS => json_encode($body),
    ]);
    $res = json_decode(curl_exec($ch), true) ?: [];
    curl_close($ch);
    return $res;
}

$sent = wapflow_otp('/send', ['phone' => '905321234567', 'app_name' => 'Acme']);
// ... when the user submits the code:
$check = wapflow_otp('/verify', ['request_id' => $sent['request_id'], 'phone' => '905321234567', 'code' => $_POST['code']]);
if (!empty($check['valid'])) { /* signed in */ }

Node.js Example

The example uses the built-in fetch (Node.js 18 or later) and must run as an ES module.

const BASE = 'https://wapflow.net/api/otp/v1';
async function otp(path, body) {
  const res = await fetch(BASE + path, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.WAPFLOW_OTP_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(body),
  });
  return res.json();
}
const sent = await otp('/send', { phone: '905321234567', app_name: 'Acme' });
// ... when the user submits the code:
const check = await otp('/verify', { request_id: sent.request_id, phone: '905321234567', code: '123456' });
if (check.valid) { /* signed in */ }

Python Example

import os
import requests

BASE = "https://wapflow.net/api/otp/v1"
HEADERS = {"Authorization": "Bearer " + os.environ["WAPFLOW_OTP_KEY"]}

def otp(path, body):
    return requests.post(BASE + path, json=body, headers=HEADERS, timeout=15).json()

sent = otp("/send", {"phone": "905321234567", "app_name": "Acme"})
# ... when the user submits the code:
check = otp("/verify", {"request_id": sent["request_id"], "phone": "905321234567", "code": "123456"})
if check.get("valid"):
    pass  # signed in

Error Handling

Treat sending and verifying separately. If a send returns success: false, act on the error code:

HTTP / codeWhat to do
401 invalid_keyCheck the key; it may have been revoked or mistyped.
402 no_subscription, subscription_expiredStart or renew the subscription.
422 invalid_phoneAsk the user to enter the number again with the country code.
429 rate_limitedRetry after the retry_after seconds in the response.
429 quota_exceededThe monthly quota is used up; upgrade the plan or wait for the next period.
429 daily_limit_reachedThe connected accounts hit their daily limit; retry after retry_after (the next day at 00:00, Turkey time). No quota is used.
503 no_account_connected, send_failedMake sure a connected, enabled WhatsApp account exists; retry shortly.

On verification, an HTTP 200 can still carry valid false. The reason field tells you why: invalid_code, expired, too_many_attempts, already_verified or not_found. For a wrong code, attempts_left shows how many tries remain; passing that on to the user makes for a better experience.

Rate Limits and User Experience

  • One number can receive 1 code per 60 seconds, 5 per hour and 10 per day. Put a 60-second countdown on your "Resend" button.
  • There are 60 sends per minute per API key, 120 requests per minute per IP address and, for verification, 10 attempts per minute per number.
  • The daily limit and the warm-up of new numbers affect sending; see our post on reducing ban risk for details.

Security Checklist

  • Never use the API key in a browser, a mobile app or any public code; make the calls from your server.
  • Always check the code on the server with /verify; do not trust a "verified" flag coming from the browser.
  • Keep the key in an environment variable and out of your repository.
  • Apply your own rate limit and, if needed, a CAPTCHA before sending a code; abuse can eat your quota.
  • Keep a backup channel (SMS or e-mail) for critical actions. WapFlow OTP is not the official WhatsApp Business API and does not guarantee delivery.

If you use WordPress or WooCommerce, you can skip the coding and use the plugin. See the pricing page for plans and the WapFlow OTP page for the product overview.

Frequently Asked Questions

What changes when I go live?

Only the key. A test key starts with wfo_test_, and its sending and rate rules are the same as a live key; an active subscription is still required.

Do I have to send request_id?

No, but it is recommended. If you leave it out, the latest unexpired code sent to that number is checked.

Can I change the message text?

Yes. In the panel you can set the application name, the message template, code length, validity and language. The template uses the {code}, {app} and {minutes} variables. Per request you can override these with app_name, code_length, ttl and lang.

How do I know the message was delivered?

Query the request with /status/:request_id; you may see sent, delivered and read. Delivery information depends on WhatsApp and is not guaranteed.

Is this API available in the Windows app too?

No. WapFlow OTP is a separate cloud-based service.

Related articles