Send and verify an OTP
Send OTP codes, follow delivery, verify user entries, and handle retries and failures from your backend.
Use this guide after creating a project key. Your backend sends the request, keeps the message identifier, and verifies the code the user enters.
Choose who creates the code
| Mode | Request | Behavior |
|---|---|---|
| Generated | {"to":"+15555550100"} | Wevlix generates a six-digit code. |
| Provided | {"to":"+15555550100","code":"123456"} | Your backend supplies a four- or six-digit code. |
You can explicitly set otpMode to generated or provided. Do not send code with generated mode. Provided mode requires code. Optional locale selects an eligible authentication-template language; countryIso2 is a validation hint, not a way to override the destination's billing country.
Send from your backend
curl --request POST "$WEVLIX_BASE_URL/v1/otp/send" \
--header "X-API-Key: $WEVLIX_API_KEY" \
--header 'Content-Type: application/json' \
--data '{"to":"+15555550100","clientMessageId":"login-attempt-001","locale":"en"}'Use otp:send. Replace the recipient and assign a unique clientMessageId to the logical attempt. Reuse that identifier when retrying an uncertain network result for the same request; do not generate a new send on every timeout. Follow the API's duplicate response and consult logs before retrying.
Live sends need an approved, accessible authentication template for the requested language and a ready WhatsApp connection. The endpoint selects the eligible template; do not hardcode a promised starter-template name. Development-key and sandbox sends simulate delivery without billing.
Track delivery separately from verification
Read GET /v1/otp/status/{messageId} with otp:status. Save delivery state and verification state separately: a message being delivered does not mean the person has verified the code.
Do not treat queued as a failure or automatically resend an old queued request. Inspect recovery details and delivery attempts. A resend should be an explicit application decision with rate limits and a new logical attempt where appropriate.
Verify the user's entry
curl --request POST "$WEVLIX_BASE_URL/v1/otp/verify" \
--header "X-API-Key: $WEVLIX_API_KEY" \
--header 'Content-Type: application/json' \
--data '{"messageId":"<MESSAGE_ID>","code":"<USER_ENTERED_CODE>"}'Use otp:verify, substitute the real UUID and user-entered code, and grant access only after the verification response accepts it. Both generated and provided modes use this endpoint. Do not return generated codes to the browser or log user-entered codes.
Expiry and retry restrictions should be handled using the actual API response and the selected authentication-template settings. Show an expired/invalid result clearly; avoid promising a fixed lifetime across all projects. Apply your own login-attempt and resend controls as well.
Common failures
- Invalid payload: confirm a four- or six-digit supplied send code, the mode/code combination and E.164 recipient.
- Language unavailable: check approved authentication templates and the requested locale.
- Forbidden: check scopes, allowed development recipients, connection readiness and balance.
- Invalid/expired verification: check that the code belongs to the current
messageId; offer a controlled new attempt.
Use webhooks for delivery notifications. See the generated Messaging API reference for current validation errors and response schemas.
Updated about 16 hours ago
