> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hypersender.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Request OTP Code
> Generate an OTP code and queue the message to the provided chatId for secure authentication.
## Overview
Generate a one-time password (OTP) code and automatically send it to a WhatsApp user. This endpoint is perfect for implementing two-factor authentication, phone verification, or secure login systems.
## How It Works
1. Send a request with the recipient's `chatId` and OTP configuration
2. The system generates a random code based on your specifications
3. The code is stored with an expiration time
4. A message containing the code is queued to be sent to the user
5. You receive the code details to verify later
## Quick Demo
**Learn how to send an OTP code using Postman:** [Demo Link](/v2/api-reference/otp/how-to-use-otp-api-in-postman)
## Parameters
### chatId (required)
The WhatsApp chat ID of the recipient (e.g., `20123456789@c.us`)
### length
The length of the OTP code. Default is `6` characters.
### useLetter
Include letters in the code generation. Default is `false`.
### useNumber
Include numbers in the code generation. Default is `true`.
### allCapital
Make all letters uppercase when `useLetter` is `true`. Default is `false`.
### name
The name to display in the message template (e.g., your app or service name).
### expires
Time-to-live (TTL) in seconds before the code expires. Default is `1800` seconds (30 minutes).
## Showcase Example Message
## Response
The response includes:
* `uuid`: Unique identifier for this OTP request
* `chat_id`: The recipient's chat ID
* `code`: The generated OTP code (store this securely if needed)
* `status`: Current status (`pending`, `sent`, `validated`, or `expired`)
* `otp_type`: Type of OTP (always `code` for this endpoint)
* `expires_at`: ISO 8601 timestamp when the code expires
* `created_at`: ISO 8601 timestamp when the code was created
## View All of your OTP Requests
## Usage Example
```php theme={null}
use Illuminate\Support\Facades\Http;
$response = Http::withToken('YOUR_API_TOKEN')
->post('https://app.hypersender.com/api/otp/v2/{instance}/request-code', [
'chatId' => '20123456789@c.us',
'length' => 6,
'useLetter' => false,
'useNumber' => true,
'name' => 'YourAppName',
'expires' => 1800,
]);
$result = $response->json();
$otpData = $result['data'] ?? null;
// Example: log or store uuid and status
info('OTP uuid: ' . ($otpData['uuid'] ?? ''));
```
## Next Steps
After generating the code:
1. The user will receive the OTP via WhatsApp
2. User enters the code in your application
3. Use the [Validate OTP Code](/v2/api-reference/otp/otp-service/validate-code) endpoint to verify the code
4. Check the `uuid` to track the verification status
Set an appropriate `expires` time based on your security requirements. Shorter expiration times (5-10 minutes) provide better security but may frustrate users if they need more time to complete the verification.
## OpenAPI
````yaml v2/api-reference/otp/otp-collection.json POST /{instance}/request-code
openapi: 3.1.0
info:
version: v2.0
title: Hypersender OTP API Docs
description: ''
servers:
- url: https://app.hypersender.com/api/otp/v2
description: Production
security:
- Authorization: []
paths:
/{instance}/request-code:
post:
summary: Request OTP code
description: Generate an OTP code and queue the message to the provided chatId.
operationId: requestCode
parameters:
- $ref: '#/components/parameters/instance'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/RequestCodeRequest'
examples:
request:
value:
chatId: 20123456789@c.us
length: 6
useLetter: false
useNumber: true
allCapital: false
name: hypersender
expires: 1800
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/RequestCodeResponse'
examples:
response:
value:
success: true
message: OTP code generated and message queued successfully
data:
uuid: a0b5df6a-b491-4190-80a5-38d85a2a4836
chat_id: 20123456789@c.us
code: '439713'
status: pending
otp_type: code
expires_at: '2025-12-29T18:09:38+00:00'
created_at: '2025-12-29T17:39:38+00:00'
components:
parameters:
instance:
name: instance
in: path
description: Hypersender instance UUID
required: true
schema:
type: string
example: '{{ instance_id }}'
schemas:
RequestCodeRequest:
type: object
properties:
chatId:
type: string
description: WhatsApp chat id (e.g. 20123456789@c.us)
length:
type: integer
description: Length of the code
useLetter:
type: boolean
useNumber:
type: boolean
allCapital:
type: boolean
name:
type: string
description: Name to show in messages
expires:
type: integer
description: TTL in seconds
required:
- chatId
RequestCodeResponse:
type: object
properties:
success:
type: boolean
message:
type: string
data:
type: object
properties:
uuid:
type: string
chat_id:
type: string
code:
type: string
status:
type: string
otp_type:
type: string
expires_at:
type: string
format: date-time
created_at:
type: string
format: date-time
securitySchemes:
Authorization:
type: http
scheme: bearer
````