Skip to main content
POST
/
{instance}
/
validate-code
Validate OTP code
curl --request POST \
  --url https://app.hypersender.com/api/otp/v2/{instance}/validate-code \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "chatId": "[email protected]",
  "code": "439713"
}
'
{
  "success": true,
  "message": "OTP code validated successfully",
  "data": {
    "uuid": "a0b5df6a-b491-4190-80a5-38d85a2a4836",
    "chat_id": "[email protected]",
    "status": "validated",
    "validated_at": "2025-12-29T17:43:36+00:00"
  }
}

​
Overview

Verify an OTP code that was previously sent to a user via the Request OTP Code endpoint. This endpoint checks if the provided code matches the active OTP for the given chat ID.

​
How It Works

  1. User receives OTP code via WhatsApp
  2. User enters the code in your application
  3. Send the chatId and code to this endpoint
  4. The system validates:
    • Code matches the active OTP
    • Code hasn’t expired
    • Code hasn’t been used already
  5. Returns validation result with status update

​
Quick Demo

Learn how to send an OTP code using Postman: Demo Link

​
Parameters

​
chatId (required)

The WhatsApp chat ID that received the OTP code (e.g., [email protected])

​
code (required)

The OTP code provided by the user to validate

​
Showcase Example Message

Request OTP Code

​
Response

The response includes:
  • success: Boolean indicating if validation was successful
  • message: Descriptive message about the validation result
  • data.uuid: The unique identifier of the OTP request
  • data.chat_id: The chat ID associated with this OTP
  • data.status: Updated status (typically validated on success)
  • data.validated_at: ISO 8601 timestamp when the code was validated

​
View All of your OTP Requests

Request OTP Code

​
Validation Rules

The code validation will fail if:
  • The code doesn’t match the active OTP for the chat
  • The code has expired based on the expires parameter
  • The code has already been validated (codes are single-use)
  • No active OTP exists for the provided chatId

​
Usage Example

use Illuminate\Support\Facades\Http;

$response = Http::withToken('YOUR_API_TOKEN')
    ->post('https://app.hypersender.com/api/otp/v2/{instance}/validate-code', [
        'chatId' => '[email protected]',
        'code' => '439713',
    ]);

$result = $response->json();

if (($result['success'] ?? false) && (($result['data']['status'] ?? '') === 'validated')) {
    // Code is valid - proceed with user authentication
    info('User verified successfully!');
} else {
    // Code is invalid or expired
    info('Verification failed: ' . ($result['message'] ?? 'Unknown error'));
}

​
Error Handling

Common validation failures:
  • Invalid Code: The code doesn’t match
  • Expired Code: The TTL period has passed
  • Already Used: The code was previously validated
  • No Active OTP: No pending OTP found for this chat
OTP codes are single-use only. Once validated successfully, the same code cannot be used again. Users will need to request a new code if they need to authenticate again.

​
Security Best Practices

  1. Rate Limiting: Implement rate limiting on validation attempts to prevent brute-force attacks
  2. Maximum Attempts: Consider limiting failed validation attempts (e.g., 3-5 tries) before requiring a new code
  3. Secure Storage: Never log or store OTP codes in plain text
  4. HTTPS Only: Always use HTTPS for API calls containing OTP codes
  5. Short Expiration: Use shorter expiration times (5-10 minutes) for sensitive operations
After successful validation, immediately proceed with your authentication flow. The validated status ensures this specific OTP cannot be reused.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

​
instance
string
required

Hypersender instance UUID

Body

application/json
​
chatId
string
required
​
code
string
required

Response

200 - application/json

Successful validation

​
success
boolean
​
message
string
​
data
object