POST

Send WhatsApp OTP Code

Instant VIP

Dispatches an instant, cryptographically secure OTP code to a recipient WhatsApp number. Features Redis in-memory storage (5-minute TTL), 60-second cooldown protection against flooding, automatic 6-digit code generation, and VIP express stream priority.

In-Memory Fast Path & Anti-Bombing Cooldown

OTP verification state is stored purely in Redis with an automated 5-minute TTL, avoiding disk write overhead to MySQL. Protection includes a 60-second resend cooldown and a daily limit of 10 requests per destination number.

HTTP Endpoint

POSThttps://api-wa.hidessh.com/api/v1/otp/send

Authentication

This endpoint requires Bearer authentication via your secret API Key.

Header Key	Value	Required
Authorization	Bearer hide_<your_api_key>	Required
Content-Type	application/json	Required

Request Parameters

The request body must be formatted as JSON with the following parameters:

Parameter	Type	Required	Description
`phone`	string	Required	Target recipient phone number in international E.164 format without spaces, dashes, or leading plus. Example: 628123456789. example: 628123456789
`otp`	string	Optional	Custom OTP code (4-8 digits). If omitted or empty, the engine automatically generates a cryptographically random 6-digit numeric code. default: Auto 6-digitexample: 884920
`template`	string	Optional	Custom message template body. Must include the '{{otp}}' placeholder which will be replaced by the generated OTP code. default: "Your verification code is {{otp}}. Keep this code confidential. Valid for 5 minutes."example: Your login verification code is {{otp}}. Do not share this code with anyone.
`device_id`	string	Optional	Specific WhatsApp Device ID slot to dispatch the OTP from. If omitted or set to 'auto', intelligent round-robin across healthy connected devices is used. default: "auto"example: auto
`expires_in`	integer	Optional	OTP code validity lifetime in seconds. Default is 300 seconds (5 minutes). Maximum allowed is 900 seconds (15 minutes). default: 300example: 300
`priority`	boolean	Optional	When true, routes the dispatch into the VIP Express stream to bypass bulk marketing campaign queues and deliver within sub-seconds. default: trueexample: true

Code Examples

request.sh

curl -X POST "https://api-wa.hidessh.com/api/v1/otp/send" \
  -H "Authorization: Bearer hide_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "628123456789",
    "template": "Your account verification code is *{{otp}}*. Valid for 5 minutes.",
    "device_id": "auto",
    "expires_in": 300,
    "priority": true
  }'

Response Formats

OTP generated, stored in Redis cache, and queued for instant WhatsApp delivery.

application/json • 200 OK

{
  "code": 200,
  "status": "success",
  "message": "OTP sent successfully",
  "data": {
    "phone": "628123456789",
    "expires_in": 300,
    "cooldown": 60
  }
}

Response Attributes Breakdown

Attribute	Type	Description
`data.phone`	string	Target normalized phone number in E.164 format.
`data.expires_in`	integer	Remaining validity period in seconds (default: 300s).
`data.cooldown`	integer	Minimum interval in seconds before the next OTP request is allowed (60s).

Error Codes & Troubleshooting

Status	Error Code	Description	Recommended Action
429	`ERR_OTP_COOLDOWN`	New OTP request submitted before the 60-second cooldown elapsed.	Display a 60-second countdown timer on your application's 'Resend OTP' button.
429	`ERR_OTP_DAILY_LIMIT`	Daily limit quota (10x OTP/day) for this destination phone number has been reached.	Prompt the user to wait for UTC day reset or offer an alternative verification method.
503	`ERR_NO_CONNECTED_DEVICE`	Tenant has no WhatsApp device currently in 'Connected' state.	Connect at least one WhatsApp device via QR code pairing in the Wahide dashboard.
402	`ERR_QUOTA_EXCEEDED`	Tenant subscription quota limit or prepaid credit balance has been exhausted.	Top up your account balance or upgrade your subscription tier.

On this page