From request
to verified.

Choose who generates and verifies the OTP

WhatsOS-generated OTP: use the verification flow below. Send your own OTP: your software generates and verifies the code; WhatsOS delivers it using your existing API key and template.

Read the supplied-code delivery API guide

Open your OTP workspace and select a test project. Create a scoped API key and store the secret on your backend. Test and live projects use separate credentials.

Keep API keys out of browser JavaScript, public repositories and mobile binaries. Your application calls your backend; your backend calls WhatsOS.

Request a code for the user's phone number. Use an opaque reference to associate the request with the action in your application.

curl -X POST 'https://whatsos.com/api/v1/otp/verifications' \
  -H 'Authorization: Bearer YOUR_SERVER_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: login-send-001' \
  -d '{
    "to": "+12025550123",
    "purpose": "login",
    "reference": "opaque-action-session",
    "locale": "en_US"
  }'

Save the returned verification_id against your server-side action session. A 202 response means the request is queued; it does not mean the message was delivered.

Use a unique idempotency key for each operation. If the request times out, retry with the same key and body. Examples use placeholder credentials and a fictional phone number.

Pass the code entered by the user and the verification_id you saved. Use a new idempotency key for this check operation.

curl -X POST 'https://whatsos.com/api/v1/otp/verifications/VERIFICATION_ID/check' \
  -H 'Authorization: Bearer YOUR_SERVER_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: login-check-001' \
  -d '{"code":"123456"}'

A fresh check after consumption returns 409. Retrying the original successful operation returns its recorded result. Your backend must also deduplicate its own login or business action.

Delivery and verification are separate events. Read both statuses to understand the result of an OTP request.

curl 'https://whatsos.com/api/v1/otp/verifications/VERIFICATION_ID' \
  -H 'Authorization: Bearer YOUR_SERVER_API_KEY'

Save the new verification_id returned by resend, replacing the previous ID in your server-side action session. Resend and cancel use an empty JSON object and a fresh idempotency key. Codes expire five minutes after creation. Five wrong checks lock a challenge; shared request limits survive resends.

Add an HTTPS destination under Webhooks in the OTP dashboard. Events report verification success, expiry or lock, and message delivery or failure.

1. Read X-WhatsOS-Timestamp and reject timestamps outside a five-minute tolerance.
2. Compute HMAC-SHA256 over timestamp + '.' + rawBody using your webhook secret.
3. Prefix the hex digest with sha256= and compare it with X-WhatsOS-Signature using a constant-time comparison.
4. Deduplicate X-WhatsOS-Event-Id. Return a 2xx response after durable processing.

Use the original raw request body for signature verification. Callbacks may arrive more than once, retry for up to 24 hours and be replayed after failure. A delivered message is never proof of a verified recipient.

Complete your sender setup before switching your integration to live credentials.

• Connect your production WhatsApp business number.
• Select an approved authentication template with a Copy code button and five-minute expiry text.
• Complete sender and template readiness checks.
• Activate your subscription and enable the live project when service activation is available.
• Use live API keys and run a controlled test for a recipient who requested the code.

REFERENCE

Errors & retries

Inspect the response error code and message. Preserve your operation key when retrying the same request.

YOUR SERVICE

No transaction charges from WhatsOS.

Your annual licence includes OTP API access, with no additional WhatsOS fee for each OTP transaction. New live requests require a current subscription.

Renewal is manual, with no automatic debit. Existing projects retain their agreed billing terms; your workspace shows the applicable price. See the pricing page for the current package, GST and renewal total.