Request API Credentials

API Reference

Welcome to the HavAi Meta Solutions WhatsApp OTP service API documentation. Our service provides programmatically controlled, instantly delivered One-Time Passwords directly to users over WhatsApp.

Base URL

https://wa.api.havai.tech

Authentication

Authenticate your requests by including your secret token in the custom header parameter:

x-api-key: YOUR_API_KEY

Endpoints

Send WhatsApp OTP

Generate and send a 6-digit OTP code to the recipient's WhatsApp. If an OTP is successfully generated, it will trigger a WhatsApp message templated with the active client design.

POST/api/otp/send

Headers

Content-Type: application/json

x-api-key: <YOUR_API_KEY>

Body Parameters

phonerequired

Recipient phone number containing country code. Format: 36203799936. No leading + or 00.

string

Response Example

{
  "success": true,
  "message": "OTP sent via WhatsApp"
}

Code Examples

curl -X POST https://wa.api.havai.tech/api/otp/send \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"phone": "36203799936"}'

Endpoints

Verify Recipient OTP

Confirm whether a recipient has submitted the correct, active OTP code associated with their phone number. Valid OTP inputs automatically mark the log record as verified.

POST/api/otp/verify

Headers

Content-Type: application/json

x-api-key: <YOUR_API_KEY>

Body Parameters

phonestring

required

Target phone number matching the sent OTP logs.

codestring

required

The 6-digit verification code received by the user.

Response Examples

Success Response (200):

{
  "verified": true
}

Failure/Expired/Invalid Response (400):

{
  "verified": false,
  "reason": "expired" // or "invalid"
}

Code Examples

curl -X POST https://wa.api.havai.tech/api/otp/verify \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"phone": "36203799936", "code": "123456"}'

Error Handling

API Error Codes

Standard error responses returned by the HavAi OTP gateway. All errors conform to proper HTTP status specifications and include descriptive JSON payload messages.

Status Code	Error Payload	Trigger Condition
401	`{ "error": "Missing API key" }` or `{ "error": "Invalid API key" }`	The `x-api-key` header was missing or invalid, or the client account has been suspended.
400	`{ "error": "phone is required" }`	The requested payload is missing the required `phone` key during send operations.
400	`{ "error": "phone and code are required" }`	The payload is missing either `phone` or `code` parameters during a verify operation.
400	`{ "verified": false, "reason": "expired" }`	The OTP exists but was generated over 5 minutes ago and has expired.
400	`{ "verified": false, "reason": "invalid" }`	The submitted OTP code does not match the active pending code for the phone.
429	`{ "error": "Too many OTP requests, please wait before trying again" }`	Rate limit exceeded. Standard limit is 5 OTP send requests per IP per minute.
500	`{ "error": "Failed to send OTP" }`	Internal server error or fail-safe event. Usually occurs if the Meta WhatsApp API service is degraded or offline.

Integration Rules

Best Practices

Follow these recommendations to guarantee reliable OTP delivery, prevent request flood blocks, and ensure secure authentication.

Always Format Country Codes

Provide numbers strictly with country codes and no spaces, plus symbols, or double zeros (e.g. use 36203799936 instead of +36-20...).

OTP Validity Duration

All OTP codes are generated with a strict time-to-live of 5 minutes. Implement validation forms prompt to warn clients of expiring codes.

One OTP Per Number At Once

Only one active code can exist for a phone number at a time. Sending a new OTP replaces any previous pending code.

Handle 429 Status Graces

Implement exponential retry delays and restrict button triggers on client UI to block users from hitting rate limiters.