# Check Instance Health
Source: https://docs.hypersender.com/v2/api-reference/enterprise/instance-management/check-health
v2/api-reference/enterprise/enterprise-collection.json GET /{instance}/health
Check the current health status of a WhatsApp instance by its UUID to monitor connectivity and readiness.
Check the current health status and connection state of your WhatsApp instance using its UUID.
## Rate Limit
This endpoint is limited to **10 requests per minute** to prevent abuse and ensure system stability.
## Response Fields
* `instance_id` - The UUID of your WhatsApp instance
* `connected_at` - Timestamp when the instance was connected
* `status` - Current status of the instance
## Instance Status Values
* `STOPPED`: Instance is stopped
* `STARTING`: Instance is starting up
* `WORKING`: Instance is running and ready to use
* `SCAN_QR_CODE`: Waiting for QR code to be scanned
* `FAILED`: Instance failed to start
* `PENDING`: Awaiting server assignment
## Use Cases
* Monitor instance health in your dashboard
* Verify instance is ready before sending messages
* Troubleshoot connection issues
* Automated health checks in monitoring systems
Check the instance health before attempting to send messages to ensure the instance is in `WORKING` status.
# Create Instance
Source: https://docs.hypersender.com/v2/api-reference/enterprise/instance-management/create-instance
v2/api-reference/enterprise/enterprise-collection.json POST /create-instance
Create a new WhatsApp instance with a phone number, name, and optional webhook URL for receiving events.
Create a new WhatsApp instance associated with a phone number and a user-defined name. Upon creation, you'll receive a QR code to scan with your WhatsApp mobile app.
## Rate Limit
This endpoint is limited to **5 requests per minute** to prevent abuse.
## Request Body
* `phone` (required) - Phone number in E.164 format (e.g., +201234567890)
* `name` (required) - Instance name (max 50 characters, must be unique per user per service)
* `webhook_url` (optional) - HTTPS webhook URL to receive WhatsApp events
## Response
Upon successful creation, you'll receive:
* Instance details (id, name, phone, service\_type, status)
* `qr_code` - Base64-encoded PNG QR code for WhatsApp authentication
* `access_token` - Bearer token for authenticating API requests
* `created_at` - Creation timestamp
## QR Code Display
The QR code is returned as a base64-encoded PNG **without** the data URI prefix. To display it in HTML:
```html theme={null}
```
## Next Steps
After creating the instance:
1. Display the QR code to the user
2. Open WhatsApp on the mobile device
3. Go to Settings > Linked Devices
4. Scan the QR code
5. Wait for the instance status to change to `WORKING`
The QR code expires after a certain time. If it expires, use the [Request New QR Code](/api-reference/enterprise/instance-management/request-new-qr-code) endpoint to generate a fresh one.
Set up a webhook URL to receive real-time events from your WhatsApp instance, including incoming messages and connection status updates.
## Validation Errors
Common validation errors (422 status):
* Missing `phone` or `name` field
* Invalid phone number format
* Instance name already exists
* Invalid webhook URL (must be HTTPS)
* Name exceeds 50 characters
# List Instances
Source: https://docs.hypersender.com/v2/api-reference/enterprise/instance-management/list-instances
v2/api-reference/enterprise/enterprise-collection.json GET /instances
Retrieve all WhatsApp instances associated with your account with powerful filtering options.
List all WhatsApp instances associated with your authenticated account. Use filters to narrow down results by UUID, name, phone number, or status.
## Filtering Options
You can filter the list of instances using the following query parameters:
* `filter[uuid]` - Filter by instance UUID (exact match)
* `filter[name]` - Filter by instance name (partial match)
* `filter[phone]` - Filter by phone number (exact match)
* `filter[status]` - Filter by instance status
## Response Fields
Each instance in the response includes:
* `id` - Instance UUID
* `name` - Instance name
* `phone` - Phone number in E.164 format
* `service_type` - Service type (whatsapp)
* `status` - Current instance status
* `access_token` - Access token for the instance (null if not yet connected)
* `created_at` - Creation timestamp
## Example Use Cases
* Display all instances in your application dashboard
* Filter instances by status to show only active ones
* Search for a specific instance by name or phone number
* Monitor all instances created at a specific time
Use the `filter[status]` parameter with value `WORKING` to get only active and ready instances.
## Instance Status Values
* `STOPPED`: Instance is stopped
* `STARTING`: Instance is starting up
* `WORKING`: Instance is running and ready
* `SCAN_QR_CODE`: Waiting for QR code scan
* `FAILED`: Instance failed to start
* `PENDING`: Awaiting server assignment
# Request New QR Code
Source: https://docs.hypersender.com/v2/api-reference/enterprise/instance-management/request-new-qr-code
v2/api-reference/enterprise/enterprise-collection.json POST /{instance}/request-new-qr-code
Generate a new QR code for instance authentication after an expired or failed scan.
Force the instance to generate a new QR code when the previous one has expired or the scan failed. This is useful when users take too long to scan the QR code or encounter connection issues.
## Rate Limit
This endpoint is limited to **1 request per minute** to prevent abuse and protect against rapid QR code generation attempts.
## When to Use
Use this endpoint when:
* The QR code has expired (typically after 60 seconds)
* The initial QR code scan failed
* The user closed the scanning interface without completing authentication
* You need to refresh the authentication flow
## Response
The response includes:
* Updated instance details
* `qr_code` - New base64-encoded PNG QR code
* Current instance status (should be `SCAN_QR_CODE`)
* `access_token` - Your instance access token
## QR Code Display
The QR code is returned as a base64-encoded PNG **without** the data URI prefix. To display it in HTML:
```html theme={null}
```
## Authentication Flow
1. Request a new QR code
2. Display it to the user
3. User scans with WhatsApp mobile app (Settings > Linked Devices)
4. Monitor instance status until it changes to `WORKING`
Due to the rate limit of 1 request per minute, avoid calling this endpoint repeatedly. Implement proper error handling and inform users about the cooldown period.
Consider implementing a timer in your UI to show when users can request a new QR code after hitting the rate limit.
## Error Responses
* **404**: Instance not found - Check if the instance UUID is correct
* **429**: Rate limit exceeded - Wait at least 60 seconds before requesting again
# Restart Instance
Source: https://docs.hypersender.com/v2/api-reference/enterprise/instance-management/restart-instance
v2/api-reference/enterprise/enterprise-collection.json POST /{instance}/restart
Restart a WhatsApp instance to resolve connection issues or refresh its state.
Restart a WhatsApp instance when it's stuck, not responding properly, or experiencing connection issues. This endpoint performs a clean restart of the instance.
## Rate Limit
This endpoint is limited to **5 requests per minute** to prevent abuse and ensure system stability.
## When to Use
Restart your instance when:
* The instance is stuck in a `STARTING` or `PENDING` state
* Messages are not being sent or received
* The instance is not responding to health checks
* After extended periods of inactivity
* When experiencing unexplained connection issues
## Response
Upon successful restart:
* **200 OK**: Instance restarted successfully
* The instance will go through the startup sequence
* Status will transition: `STOPPED` → `STARTING` → `WORKING`
## Important Notes
Restarting an instance will temporarily interrupt message sending and receiving. Plan restarts during low-activity periods if possible.
## Restart Process
1. Send restart request
2. Instance stops current operations
3. Instance begins startup sequence
4. Connection is re-established
5. Instance returns to `WORKING` status
## Monitoring After Restart
After restarting an instance, monitor its status:
```
1. Call restart endpoint
2. Wait 5-10 seconds
3. Use Check Instance Health endpoint
4. Verify status is WORKING
```
If the restart fails with a 500 error, try restarting the instance manually from the Hypersender dashboard or contact support if the issue persists.
## Error Responses
* **404**: Instance not found - Verify the instance UUID is correct
* **429**: Rate limit exceeded - Wait before attempting another restart
* **500**: Failed to restart instance - Try manual restart from dashboard or contact support
## Alternative
**If the API restart fails, you can always restart the instance manually from the Hypersender dashboard as a fallback option.**
# Introduction
Source: https://docs.hypersender.com/v2/api-reference/enterprise/introduction
Hypersender Enterprise WhatsApp API Documentation - Premium Access & Advanced Features
Welcome to the **Hypersender Enterprise WhatsApp API** documentation! We're delighted to have you as one of our valued enterprise partners. This documentation is designed specifically for organizations like yours that demand powerful, scalable WhatsApp messaging solutions with advanced capabilities.
## What Makes Enterprise Special
As an enterprise client, you're at the heart of what we do. We've built Hypersender to scale with your business needs, and your enterprise subscription unlocks a premium experience:
Access to all standard API endpoints for WhatsApp messaging
Exclusive access to enterprise-grade features and advanced endpoints
Dedicated support team to ensure your success
Higher rate limits and throughput for mission-critical operations
Easily generate, revoke, and manage API tokens for your applications
## Your Complete API Toolkit
As an enterprise customer, you have access to:
1. **All Standard WhatsApp Endpoints** - Every feature available in our standard WhatsApp API, including sending and receiving messages, managing chats, handling media, and monitoring message status
2. **Enterprise-Exclusive Endpoints** - Advanced features designed for complex business workflows and large-scale WhatsApp operations
3. **Enhanced Performance** - Optimized infrastructure to handle your high-volume WhatsApp messaging needs
4. **Easily Manage API Tokens** - Generate, Revoke, and manage API tokens directly from the dashboard for secure access to your applications
This documentation focuses on the enterprise-specific features. You can also refer to our [standard WhatsApp API documentation](/v1/api-reference/whatsapp/introduction) for core functionality that's available across all plans.
## How it works
Hypersender provides a powerful API that enables you to send and receive WhatsApp messages using your Android devices. The system works seamlessly: your API requests are processed through our infrastructure and delivered to your connected devices, which then send messages to recipients through WhatsApp. The API provides comprehensive message receiving capabilities, media handling, and real-time message status monitoring.
## Enterprise-Specific Features
Your enterprise subscription includes access to advanced capabilities that streamline complex operations:
### Multi-Device Management
Efficiently manage multiple Android devices across your organization with centralized control and monitoring.
### Advanced Analytics
Gain deeper insights into your messaging operations with comprehensive analytics and reporting tools.
### Custom Webhooks
Configure sophisticated webhook routing and event handling for seamless integration with your systems.
### Instance Management API
Programmatically manage your WhatsApp instances with our powerful Instance Management API:
* **Check Instance Health** - Monitor connection status and readiness (10 req/min)
* **List Instances** - Retrieve and filter all your instances
* **Create Instance** - Provision new WhatsApp instances automatically (5 req/min)
* **Request New QR Code** - Generate fresh QR codes for authentication (1 req/min)
* **Restart Instance** - Resolve connection issues programmatically (5 req/min)
### Generate and Revoke API Tokens
Easily generate and revoke API tokens for secure access to your applications:
* **Generate Token** - Create new API tokens with customizable permissions (5 req/min)
![Generate Token]()
* **Revoke Token** - Invalidate existing tokens to maintain security (5 req/min)
![Revoke Token]()
**Getting Started:** If you're new to Hypersender, we recommend starting with our [standard WhatsApp API documentation](/v1/api-reference/enterprise/introduction.mdx) to understand the core concepts, then explore the enterprise-specific features documented here.
## Getting Started
To help you get up and running quickly, here are some key resources and links:
Explore all standard WhatsApp API endpoints
Manage WhatsApp instances programmatically
Try sending your first WhatsApp message with Postman
Set up WhatsApp webhook integrations
Learn how to avoid getting blocked on WhatsApp
## Postman Collection
We've prepared a comprehensive Postman Collection to help you quickly explore and test our API endpoints.
Download the complete Enterprise API Postman Collection with all endpoints.
## Authentication
All API endpoints use secure Bearer token authentication. Your enterprise API keys provide access to both standard and enterprise-exclusive endpoints.
```json theme={null}
"security": [
{
"bearerAuth": []
}
]
```
**Security Best Practice:** Treat your API keys like passwords. Never expose them in client-side code or public repositories. Use environment variables and secure key management systems for production deployments.
## Support & Resources
As an enterprise customer, you have access to priority support:
* **Dedicated Account Manager:** Your primary point of contact for strategic discussions
* **Technical Support:** Priority access to our engineering team for technical issues
* **Documentation:** This comprehensive documentation, regularly updated with new features
**Need Help?** Your account manager is here to ensure your success. Don't hesitate to reach out with questions, feature requests, or integration challenges. We're invested in your success!
***
Thank you for choosing Hypersender Enterprise. We're excited to be part of your messaging infrastructure and look forward to supporting your growth. Let's build something amazing together! 🚀
# How to generate OTP link in Postman
Source: https://docs.hypersender.com/v2/api-reference/otp/generate-whatsapp-otp-link-with-hypersender-api
Generate a WhatsApp OTP magic link for passwordless authentication. In this guide, we will show you how to create an OTP link using Postman.
# How to send OTP in Postman
Source: https://docs.hypersender.com/v2/api-reference/otp/how-to-use-otp-api-in-postman
The Hypersender OTP API is a powerful API to send verification codes via WhatsApp and SMS. In this guide, we will show you how to send an OTP using Postman.
# Introduction
Source: https://docs.hypersender.com/v2/api-reference/otp/introduction
Hypersender OTP API - Send verification codes via WhatsApp & SMS
Send one-time passwords (OTPs) and magic links to your users via WhatsApp or SMS. Simple as that.
## Quick Demo
**Learn how to use Hypersender OTP API with Postman:** [Send OTP Guide](/v2/api-reference/otp/how-to-use-otp-api-in-postman) | [Generate OTP Link Guide](/v2/api-reference/otp/generate-whatsapp-otp-link-with-hypersender-api)
## How It Works
Generate a verification code and send it to your user via **WhatsApp or SMS**.
You can customize the code length, character type (numbers, letters, or both), and expiration time. Works with WhatsApp chat IDs and phone numbers for SMS.
When your user enters the code, hit this endpoint to check if it's correct.
Works for both **WhatsApp and SMS**. We handle expiration checks and make sure each code only works once.
Create a magic link for passwordless auth. User taps the link, you get a callback — no code entry needed.
This endpoint is **WhatsApp only** since it sends an interactive button message.
## Quick Setup
**Base URL:**
```
https://app.hypersender.com/api/otp/v2
```
**Auth:** Bearer token in the header
```bash theme={null}
Authorization: Bearer YOUR_API_TOKEN
```
**Endpoints:**
```
/{instance}/request-code
/{instance}/validate-code
/{instance}/generate-link
```
## Endpoints
Send a verification code
Verify user's code
Send a magic link
## Good to Know
* Codes expire automatically (you set the TTL)
* Each code works only once
* Rate limiting is built-in
* Works with both WhatsApp chat IDs and phone numbers for SMS
Keep your API keys secret. Don't put them in client-side code.
## Postman Collection
Get the Postman collection to test the endpoints.
## Next Steps
1. Grab your API token and instance UUID from the dashboard
2. Try sending a code with [Request Code](/v2/api-reference/otp/request-code)
3. Validate it with [Validate Code](/v2/api-reference/otp/validate-code)
That's it. You're ready to go.
# Generate OTP Link
Source: https://docs.hypersender.com/v2/api-reference/otp/otp-service/generate-link
v2/api-reference/otp/otp-collection.json POST /{instance}/generate-link
Generate an OTP link for passwordless authentication where users click a WhatsApp link to verify their identity.
## Overview
Generate a magic link for passwordless authentication via WhatsApp. Instead of typing a code, users simply click a pre-formatted WhatsApp link that automatically sends a verification message back to your system. This provides a seamless, user-friendly authentication experience.
## Quick Demo
**Learn how to generate a WhatsApp OTP link using Postman:** [Demo Link](/v2/api-reference/otp/generate-whatsapp-otp-link-with-hypersender-api)
## How It Works
1. Generate an OTP link request with custom messages
2. Receive a unique `code` and `whatsapp_link`
3. Send the WhatsApp link to your user (via email, SMS, or your app)
4. User clicks the link, which opens WhatsApp with a pre-filled message
5. User sends the message (containing the unique code)
![Send OTP Link Code]()
6. Your system receives the message via webhooks
![Receive OTP Link]()
7. User clicks the link and verifies the action
![Receive OTP Link]()
8. After verification, the user is redirected to your application with access granted
![Receive OTP Link]()
8. Use callbacks to handle success/failure events
## Parameters
### expires
Time-to-live (TTL) in seconds before the link expires. Default is `1800` seconds (30 minutes).
### name
Your application or service name to display in messages.
### message (object)
Custom messages for different stages of the verification flow:
* **prompt**: The message users see in the WhatsApp link (e.g., "Give me link to login at MyApp")
* **success**: Message sent when verification succeeds. Use `{link}` placeholder for the actual login/verification URL
* **failed**: Message sent when verification fails
* **expired**: Message sent when the link has expired
### callback (object)
Webhook URLs to receive verification events:
* **success**: URL called when user successfully verifies
* **failed**: URL called when verification fails
## Response
The response includes:
* `uuid`: Unique identifier for this OTP link request
* `code`: Short verification code (e.g., "RDYFQUBX")
* `chat_id`: The recipient's chat ID
* `status`: Current status (`pending`, `verified`, `failed`, or `expired`)
* `otp_type`: Type of OTP (always `link` for this endpoint)
* `expires_at`: ISO 8601 timestamp when the link expires
* `created_at`: ISO 8601 timestamp when the link was created
* `whatsapp_link`: The complete WhatsApp link to send to the user
## The WhatsApp Link
The generated `whatsapp_link` follows this format:
```
https://wa.me/20123456789?text=Give+me+link+to+login+at+Hypersender+%5BNFBNWZSF%5D+-+DO+NOT+CHANGE+THIS+MESSAGE
```
Key components:
* Pre-fills WhatsApp with the prompt message
* Includes the unique verification code in brackets
* Warns users not to modify the message
## 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}/generate-link', [
'expires' => 1800,
'name' => 'YourAppName',
'message' => [
'prompt' => 'Give me link to login at YourApp',
'success' => 'Welcome! Here is your login link: {link}',
'failed' => 'Login failed. Please try again.',
'expired' => 'This link has expired. Please request a new one.'
],
'callback' => [
'success' => 'https://yourdomain.com/api/otp/success',
'failed' => 'https://yourdomain.com/api/otp/failed'
]
]);
$result = $response->json();
$magicLink = $result['data']['whatsapp_link'] ?? null;
// Send this link to the user via your preferred channel
info('Send this link to user: ' . $magicLink);
```
## Implementation Flow
### 1. Generate the Link
Call this endpoint to create a verification link for your user.
### 2. Deliver the Link
Send the `whatsapp_link` to your user through:
* Email
* SMS
* In-app notification
* Web page display
### 3. User Clicks Link
When clicked, the link:
* Opens WhatsApp (mobile) or WhatsApp Web
* Pre-fills a message with the verification code
* User just needs to tap "Send"
### 4. Handle Callbacks
Your callback URLs will receive POST requests with the verification result:
```json theme={null}
{
"uuid": "a0b5e14e-95da-4bd4-9e2a-071661244bef",
"code": "RDYFQUBX",
"chat_id": "20123456789@c.us",
"status": "verified",
"verified_at": "2025-12-29T17:50:00+00:00"
}
```
### 5. Respond to User
Based on the callback, send the appropriate message:
* **Success**: Send the login link or access token
* **Failed**: Notify user of the error
* **Expired**: Prompt user to request a new link
## Message Placeholders
Use these placeholders in your message templates:
* `{link}`: Replaced with the actual authentication/login URL
* `{name}`: Your application name
* `{code}`: The verification code
## Use Cases
1. **Passwordless Login**: Let users log in without typing passwords
2. **Two-Factor Authentication**: Add an extra security layer
3. **Phone Verification**: Verify phone numbers during signup
4. **Account Recovery**: Secure account recovery flow
5. **Secure Actions**: Verify sensitive operations (payments, settings changes)
The link-based OTP provides better UX than code-based OTP because users don't need to switch between apps to copy/paste codes. It's especially effective on mobile devices where WhatsApp is already installed.
Ensure your webhook endpoints (callback URLs) are secure and can handle incoming POST requests. Always validate the request signature or use API keys to verify requests are coming from Hypersender.
## Security Considerations
1. **HTTPS Only**: Always use HTTPS for callback URLs
2. **Verify Callbacks**: Validate incoming webhook requests
3. **Short Expiration**: Use shorter TTL for sensitive operations
4. **Rate Limiting**: Implement limits on link generation per user
5. **One-Time Use**: Links should be invalidated after use
6. **Monitor Failed Attempts**: Track and alert on suspicious patterns
## Monitoring
Track these metrics for security and UX optimization:
* Link generation rate
* Click-through rate (users who click the link)
* Verification success rate
* Expiration rate (links that expire unused)
* Failed verification attempts
* Average time to verification
# Request OTP Code
Source: https://docs.hypersender.com/v2/api-reference/otp/otp-service/request-code
v2/api-reference/otp/otp-collection.json POST /{instance}/request-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
![Request OTP Code]()
## 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
![Request OTP Code]()
## 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.
# Validate OTP Code
Source: https://docs.hypersender.com/v2/api-reference/otp/otp-service/validate-code
v2/api-reference/otp/otp-collection.json POST /{instance}/validate-code
Validate an OTP code previously generated for a chat to confirm user authentication.
## Overview
Verify an OTP code that was previously sent to a user via the [Request OTP Code](/v2/api-reference/otp/otp-service/request-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](/v2/api-reference/otp/how-to-use-otp-api-in-postman)
## Parameters
### chatId (required)
The WhatsApp chat ID that received the OTP code (e.g., `20123456789@c.us`)
### 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
```php theme={null}
use Illuminate\Support\Facades\Http;
$response = Http::withToken('YOUR_API_TOKEN')
->post('https://app.hypersender.com/api/otp/v2/{instance}/validate-code', [
'chatId' => '20123456789@c.us',
'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.
# Heartbeat Disabled
Source: https://docs.hypersender.com/v2/api-reference/sms-webhooks/heartbeats/heartbeat-disabled
v2/api-reference/sms-webhooks/sms-webhooks.json webhook heartbeat-disabled
Notification when a webhook heartbeat is disabled.
This webhook is triggered when the phone heartbeat is disabled.
# Heartbeat Missed
Source: https://docs.hypersender.com/v2/api-reference/sms-webhooks/heartbeats/heartbeat-missed
v2/api-reference/sms-webhooks/sms-webhooks.json webhook heartbeat-missed
Notification when a webhook heartbeat is missed.
This webhook is triggered when the phone misses a heartbeat.
# Heartbeat Offline
Source: https://docs.hypersender.com/v2/api-reference/sms-webhooks/heartbeats/heartbeat-offline
v2/api-reference/sms-webhooks/sms-webhooks.json webhook heartbeat-offline
Notification when a webhook heartbeat is offline.
This webhook is triggered when the phone goes offline after being online.
# Heartbeat Online
Source: https://docs.hypersender.com/v2/api-reference/sms-webhooks/heartbeats/heartbeat-online
v2/api-reference/sms-webhooks/sms-webhooks.json webhook heartbeat-online
Notification when a webhook heartbeat is online.
This webhook is triggered when the phone comes online after being offline.
# Heartbeat Received
Source: https://docs.hypersender.com/v2/api-reference/sms-webhooks/heartbeats/heartbeat-received
v2/api-reference/sms-webhooks/sms-webhooks.json webhook heartbeat-received
Notification when a webhook heartbeat is received.
This webhook is triggered when the heartbeat is received either by manually clicking the send heartbeats button on the android app or automatically every 15 minutes.
# Introduction
Source: https://docs.hypersender.com/v2/api-reference/sms-webhooks/introduction
What is SMS Webhooks
# Hypersender SMS Webhooks
The Hypersender SMS API offers a webhook-based integration that delivers real-time, event-driven notifications. This allows developers to monitor their connected phones (sms app) or respond to specific events.
* **Monitor Message Status**: Provides real-time updates on the status of sent messages, such as when the message is queued to be sent or has been successfully delivered.
* **Receive Incoming Messages**: Get notified when a new message is received on the connected phone.
* **Monitor Connected Phone**: Receive periodic heartbeats from your connected phone to ensure the connection is active and act when the phone is offline.
# Message Call Missed
Source: https://docs.hypersender.com/v2/api-reference/sms-webhooks/messages-events/message-call-missed
v2/api-reference/sms-webhooks/sms-webhooks.json webhook message-call-missed
Notification when a message call is missed.
This webhook is triggered when the phone missed a call.
# Message Delivered
Source: https://docs.hypersender.com/v2/api-reference/sms-webhooks/messages-events/message-delivered
v2/api-reference/sms-webhooks/sms-webhooks.json webhook message-delivered
Notification when a message is delivered.
This webhook is triggered when the phone has successfully delivered the message to the recipient.
# Message Expired
Source: https://docs.hypersender.com/v2/api-reference/sms-webhooks/messages-events/message-expired
v2/api-reference/sms-webhooks/sms-webhooks.json webhook message-expired
Notification when a message is expired.
This webhook is triggered when the message expired
# Message Failed
Source: https://docs.hypersender.com/v2/api-reference/sms-webhooks/messages-events/message-failed
v2/api-reference/sms-webhooks/sms-webhooks.json webhook message-failed
Notification when a message has failed.
This webhook is triggered when the phone failed to deliver the message to the recipient. Or something happend during sending the request to the phone.
# Message Received
Source: https://docs.hypersender.com/v2/api-reference/sms-webhooks/messages-events/message-received
v2/api-reference/sms-webhooks/sms-webhooks.json webhook message-received
Notification when a message is received.
This webhook is triggered when a new sms message is received on the connected phone.
# Message Scheduled
Source: https://docs.hypersender.com/v2/api-reference/sms-webhooks/messages-events/message-scheduled
v2/api-reference/sms-webhooks/sms-webhooks.json webhook message-scheduled
Notification when a message is scheduled.
This webhook is triggered when the message is scheduled to be sent at a later time.
# Message Sent
Source: https://docs.hypersender.com/v2/api-reference/sms-webhooks/messages-events/message-sent
v2/api-reference/sms-webhooks/sms-webhooks.json webhook message-sent
Notification when a message is sent.
This webhook is triggered when hypersender sent the request to the phone to send the message.
# Heartbeats
Source: https://docs.hypersender.com/v2/api-reference/sms/heartbeats/heartbeats
v2/api-reference/sms/sms-collection.json GET /{instance}/heartbeats
Index heartbeats of the phone sorted by last heartbeat.
Index heartbeats of the phone sorted by last heartbeat.
You can filter by various attributes, and this endpoint is paginated.
# How to send SMS message in Postman
Source: https://docs.hypersender.com/v2/api-reference/sms/how-to-send-sms-message-in-postman
The Hypersender SMS API is a powerful api to send and receive messages using your own SIM card number. In this guide, we will show you how to send a SMS message using Postman.
# Introduction
Source: https://docs.hypersender.com/v2/api-reference/sms/introduction
Hypersender SMS API Docs
Send and receive sms messages, with Hypersender SMS API. This Documentation provides a comprehensive guide to the API, including detailed information on how to send and receive sms messages, controll message threads, and monitor phone heartbeats.
## How it works
Hypersender SMS is just an API that allows you to send SMS messages using your android phone's SIM card. The API works by sending a message to your phone, and then your phone sends the message to the recipient. The API also allows you to receive messages, and monitor your phone's heartbeats.
**Sender Name Limitation:**
When sending SMS messages through the Hypersender API, the recipient will see the message as coming from your phone number rather than a custom sender name or business name. Custom sender names require extensive business verification processes and regulatory compliance that can take weeks or months to complete. Our API is designed to provide immediate SMS functionality using your existing phone number, offering a streamlined solution for your messaging needs. Please ensure your recipients are aware of this when setting up your messaging workflows.
## Receive Messages
To receive messages, you need to have the Hypersender app installed on your android phone. The app will receive the messages, and then send them to the specified webhook.
## Heartbeats
Heartbeats are like signles that used to monitor the status of your phone. your phone will send a heartbeat to the API every 15 minutes, to let the API know that it's still online.
If your phone doesn't send a heartbeat for more than 2 hours, the API will consider your phone as offline.
## Working with android app
To use the API, you need to have the Hypersender app installed on your android phone. The app will receive the messages and send them to the recipient.
### Download the app
You can download it from the release page on [github](https://github.com/hypersender/sms-app-releases/releases).
Currently, the app is only available for android. You can't use the app on iOS.
### How to use the app
Download the app from the release page.
Install the app on your android phone.
Grant the app the necessary permissions, see the [permissions](https://docs.hypersender.com/docs/hypersender/overview/sms-quick-start#step-4-download-the-hypersender-sms-app) section for more information.
Open the app, and scan the QR code to link the app with the API.
![Scan QR code]()
The app will start receiving messages, and then send them to the recipient.
### Why the app is not on the play store
Currently, the app is only available for android. Google Play Store currently doesn't allow SMS apps, so you can't download the app from the store.
We recommend using a secondary phone number, because the app will send and receive messages using your phone's SIM card.
### Why android only
The app is only available for android because of the restrictions on iOS. Apple doesn't allow apps to send SMS messages, so we can't make an app for iOS.
## cost of sending messages
We don't charge you for sending messages, but for using the API. Please check the pricing page for more information.
Sending costs is different from one country to another, and directly depends on the carrier's pricing and offers.
## Quick Demo
**Learn how to use Hypersender SMS API to send a message using Postman:** [Demo Link](/docs/sms/how-to-send-sms-message-in-postman)
## bulk sending
Currently, the API doesn't support bulk sending, but you can send multiple messages by sending multiple requests.
## international messaging
As long as you have an android phone and SIM card you can send messages from anywhere in the world but take into consideration that the carrier may charge you significantly more for international messaging.
## postman collection
You can download SMS API Postman Collection to easily interact with our API.
Download SMS API Postman Collection.
## Authentication
All API endpoints are authenticated using Bearer tokens and picked up from the specification file.
```json theme={null}
"security": [
{
"bearerAuth": []
}
]
```
# Delete Message threads
Source: https://docs.hypersender.com/v2/api-reference/sms/message-threads/delete-message-thread
v2/api-reference/sms/sms-collection.json DELETE /{instance}/delete-message-thread
Delete a message thread and all associated messages.
Delete a message thread from the database and also deletes all the messages in the thread.
Deleting a thread will delete all of the messages related to the thread.
# Edit Message Thread
Source: https://docs.hypersender.com/v2/api-reference/sms/message-threads/edit-message-thread
v2/api-reference/sms/sms-collection.json PUT /{instance}/edit-message-thread
Edit the archived status of a message thread.
Edit message thread archived status
# Message threads
Source: https://docs.hypersender.com/v2/api-reference/sms/message-threads/message-threads
v2/api-reference/sms/sms-collection.json GET /{instance}/message-threads
Index all contacts a phone number has communicated with.
This endpoint will index all of the contacts which a phone number has communicated with (threads).
with paging limited to `50 messages` per response.
It will be sorted by `updated_at` in descending order.
# Delete Message
Source: https://docs.hypersender.com/v2/api-reference/sms/messages/delete-message
v2/api-reference/sms/sms-collection.json DELETE /{instance}/delete-message
Delete a message from the chat.
Delete a message from the database and removes the message content from the list of threads.
# Index Messages
Source: https://docs.hypersender.com/v2/api-reference/sms/messages/index-messages
v2/api-reference/sms/sms-collection.json GET /{instance}/messages
Retrieve a list of messages with filtering and pagination options.
This endpoint will index all of the messages sent and received based on various criteria, including searching with request id and messages attributes, with paging limited to 50 messages per response. Default sort is by `last_updated_at`.
# Send Message
Source: https://docs.hypersender.com/v2/api-reference/sms/messages/send-message
v2/api-reference/sms/sms-collection.json POST /{instance}/send-message
Send a new SMS message to be sent by your android phone.
Send a new SMS message to be sent by your android phone, you can schedule it up to 3 days in the future relative to your defined phone timezone.
you can also specify an unique request id that you can use later to search for this message.
## Quick Demo
**Learn how to use Hypersender SMS API to send a message using Postman:** [Demo Link](api-reference/sms/how-to-send-sms-message-in-postman.mdx)
# Introduction
Source: https://docs.hypersender.com/v2/api-reference/whatsapp-webhooks/introduction
What is WhatsApp Webhooks
# Hypersender WhatsApp Webhooks
The Hypersender WhatsApp API offers a webhook-based integration that delivers real-time, event-driven notifications. This allows developers to monitor their connected WhatsApp instances or respond to specific events, ranging from message interactions to contact and media management.
* **Status Updates**: Provides updates on the connection status of the connected WhatsApp instance, indicating whether the connection is open, closed, or in the process of connecting. It also updates the presence of chats in real-time, offering information on activities such as typing or recording a voice message.
* **Chats**: Tracks interactions and status changes for chats. This includes the creation of new chats, updates to existing ones, and various chat-specific actions like archiving.
* **Contacts**: Observes changes to the contacts associated with the connected WhatsApp instance. Any addition, removal, or update to a contact triggers a notification through the designated route.
* **Messages**: Central to WhatsApp's core functionality, our API extensively supports message monitoring. This includes notifications for incoming messages, updates to message status, and messages sent through the API.
# Messages Ack
Source: https://docs.hypersender.com/v2/api-reference/whatsapp-webhooks/messages-ack
v2/api-reference/whatsapp-webhooks/whatsapp-webhooks.json webhook messages-ack
For message delivery & read receipts.
## message.ack
Receive events when server or recipient gets the message, read or played it.
AckName field contains message status (ack has the same meaning, but show the value in int, but we keep it for backward compatability, they much to each other)
Possible message ack statuses:
* ackName: ERROR, ack: -1
* ackName: PENDING, ack: 0
* ackName: SERVER, ack: 1
* ackName: DEVICE, ack: 2
* ackName: READ, ack: 3
* ackName: PLAYED, ack: 4
The payload may have more fields, it depends on the engine you use, but here’s a minimum amount that all engines send:
# Messages Any
Source: https://docs.hypersender.com/v2/api-reference/whatsapp-webhooks/messages-any
v2/api-reference/whatsapp-webhooks/whatsapp-webhooks.json webhook messages-any
For all message creations including your own.
## message.any
Incoming messages (text/audio/media) for user or group chats. Fired for all message creations including your own.
Fields:
* `hasMedia`: boolean
* `_data`: engine-specific internal data
# Message Reaction
Source: https://docs.hypersender.com/v2/api-reference/whatsapp-webhooks/messages-reaction
v2/api-reference/whatsapp-webhooks/whatsapp-webhooks.json webhook messages-reaction
Receive events when a message is reacted to or a reaction is removed.
## message.reaction
Receive events when a message is reacted to by a user (or yourself reacting to a message).
* `payload.reaction.text` - emoji that was used to react to the message. It’ll be an empty string if the reaction was removed.
* `payload.reaction.messageId` - id of the message that was reacted to.
# Messages Revoked
Source: https://docs.hypersender.com/v2/api-reference/whatsapp-webhooks/messages-revoked
v2/api-reference/whatsapp-webhooks/whatsapp-webhooks.json webhook messages-revoked
Triggered when a previously sent message is deleted (revoked) by any participant.
## message.revoked
Emitted when a previously sent message is deleted (revoked) by any participant.
# Messages Waiting
Source: https://docs.hypersender.com/v2/api-reference/whatsapp-webhooks/messages-waiting
v2/api-reference/whatsapp-webhooks/whatsapp-webhooks.json webhook messages-waiting
Triggered when WhatsApp shows 'Waiting for this message. This may take a while.'.
## message.waiting
Triggered when WhatsApp shows "Waiting for this message. This may take a while.".
![Message Waiting Screenshot]()
# Poll Vote
Source: https://docs.hypersender.com/v2/api-reference/whatsapp-webhooks/poll-vote
v2/api-reference/whatsapp-webhooks/whatsapp-webhooks.json webhook poll-vote
Triggered when new votes are received for a poll.
## poll.vote
New votes received for a poll.
# Poll Vote Failed
Source: https://docs.hypersender.com/v2/api-reference/whatsapp-webhooks/poll-vote-failed
v2/api-reference/whatsapp-webhooks/whatsapp-webhooks.json webhook poll-vote-failed
Decryption failed for a user poll vote.
## poll.vote.failed
Decryption failed for a user poll vote. Same payload shape as poll.vote but `selectedOptions` is empty.
# Update User Chat Behavior
Source: https://docs.hypersender.com/v2/api-reference/whatsapp-webhooks/presence-update
v2/api-reference/whatsapp-webhooks/whatsapp-webhooks.json webhook presence-update
Real-time updates on user chat activities like typing or recording voice messages.
## presence.update
Provides real-time updates regarding the status of the whatsapp chats. Information like typing, recording a voice message, or other relevant activities, It's like seeing the chat got updated in real whatsapp app.
`payload.id` indicates the chat - either direct chat with a contact or a group chat.
`payload.id.[].participant` - certain participant presence status. For a direct chat there’s only one participant.
# Check Contact Exists
Source: https://docs.hypersender.com/v2/api-reference/whatsapp/contacts/check-exists
v2/api-reference/whatsapp/whatsapp-collection.json POST /{instance}/contacts/check-exists
Verify if a phone number is registered on WhatsApp and retrieve its chatId for messaging purposes.
Check if a phone number is registered on WhatsApp before attempting to send messages.
This endpoint allows you to:
* Verify if a phone number exists on WhatsApp
* Get the correct chatId format for messaging
* Prevent errors when sending messages to non-existent numbers
This is useful for validating contacts before sending messaging operations or when integrating with external systems.
## Use Cases
### Contact Validation
Before sending messages to a list of contacts, verify which numbers are actually registered on WhatsApp.
### CRM Integration
When syncing contacts from your CRM, check their WhatsApp availability to enable messaging features.
### User Onboarding
Verify if a user's phone number is on WhatsApp during registration or account setup.
This endpoint is very useful to avoid getting blocked by WhatsApp, As it prevent you from sending messages to non-existing numbers.
## Response Examples
### Existing Contact
When the phone number is registered on WhatsApp:
```json theme={null}
{
"numberExists": true,
"chatId": "201553730661@c.us"
}
```
### Non-existing Contact
When the phone number is not registered on WhatsApp:
```json theme={null}
{
"numberExists": false,
"chatId": null
}
```
The `chatId` can be in any format `+20123456789`, `20123456789`, `0123456789`, or `123456789`
# Get All Contacts
Source: https://docs.hypersender.com/v2/api-reference/whatsapp/contacts/get-all-contacts
v2/api-reference/whatsapp/whatsapp-collection.json GET /{instance}/contacts/get-all
Retrieve a list of all contacts in the WhatsApp instance with pagination and sorting options.
Retrieve a paginated list of all contacts in your WhatsApp instance.
This endpoint allows you to:
* Fetch all contacts from your WhatsApp instance
* Paginate through large contact lists
* Sort contacts by name or ID
* Control the number of contacts returned
This is useful for syncing contacts with your CRM, building contact lists, or displaying contacts in your application.
## Use Cases
### Contact Synchronization
Sync all your WhatsApp contacts with your CRM or external database.
### Contact Management
Build a contact management interface with pagination and sorting capabilities.
### Bulk Operations
Retrieve contact lists for bulk messaging or data analysis operations.
### Export Contacts
Export your WhatsApp contacts for backup or migration purposes.
## Query Parameters
### limit
* **Type**: Integer
* **Range**: 1-1000
* **Default**: 100
* **Description**: Number of contacts to return per request
### offset
* **Type**: Integer
* **Minimum**: 0
* **Default**: 0
* **Description**: Number of contacts to skip (for pagination)
### sort\_by
* **Type**: String
* **Options**: `id`, `name`
* **Default**: `name`
* **Description**: Field to sort contacts by
### sort\_order
* **Type**: String
* **Options**: `asc`, `desc`
* **Default**: `asc`
* **Description**: Sort order (ascending or descending)
## Response Examples
### Successful Response
When contacts are retrieved successfully:
```json theme={null}
{
"message": "Contacts retrieved successfully.",
"data": [
{
"id": "100875997589545@lid",
"name": "Maria",
"pushname": "Maria Doe"
},
{
"id": "10226367471836@lid",
"name": "John",
"pushname": "John Doe"
}
]
}
```
## Pagination Example
To paginate through contacts, use the `limit` and `offset` parameters:
```bash theme={null}
# First page (contacts 1-100)
GET /{instance}/contacts/get-all?limit=100&offset=0
# Second page (contacts 101-200)
GET /{instance}/contacts/get-all?limit=100&offset=100
# Third page (contacts 201-300)
GET /{instance}/contacts/get-all?limit=100&offset=200
```
## Best Practices
Use pagination with reasonable limits (e.g., 100-200) to avoid timeouts and improve performance.
The `pushname` is the name the user has set in their WhatsApp profile, while `name` is the name saved in your phone's contacts.
Large contact lists may take time to retrieve. Consider implementing progressive loading in your UI.
## Integration Example
### Fetching All Contacts with Pagination
```javascript theme={null}
async function getAllContacts(instance, apiKey) {
let allContacts = [];
let offset = 0;
const limit = 100;
let hasMore = true;
while (hasMore) {
const response = await fetch(
`https://app.hypersender.com/api/whatsapp/v2/${instance}/contacts/get-all?limit=${limit}&offset=${offset}`,
{
headers: {
'Authorization': `Bearer ${apiKey}`,
'Content-Type': 'application/json'
}
}
);
const data = await response.json();
allContacts = allContacts.concat(data.data);
// Check if there are more contacts
hasMore = data.data.length === limit;
offset += limit;
}
return allContacts;
}
```
The `chatId` can be in any format `+20123456789`, `20123456789`, `0123456789`, or `123456789`
# Get All Known LIDs
Source: https://docs.hypersender.com/v2/api-reference/whatsapp/contacts/get-all-known-lids
v2/api-reference/whatsapp/whatsapp-collection.json GET /{instance}/contacts/get-all-known-lids
List the @lid to @c.us mappings already known by a Hypersender WhatsApp instance.
Returns the linked-identifier mappings already known by this instance.
Use this endpoint when you need to:
* Build a local cache of known `@lid` and `@c.us` pairs.
* Page through large mapping sets with `limit` and `offset`.
* Check which conversions are already available before resolving individual identifiers.
A mapping appears here only after the instance has already learned it from contact or conversation data.
## Response Example
```json theme={null}
[
{
"lid": "1111111@lid",
"pn": "3333333@c.us"
},
{
"lid": "2222222@lid",
"pn": "4444444@c.us"
}
]
```
# Get Contact
Source: https://docs.hypersender.com/v2/api-reference/whatsapp/contacts/get-contact
v2/api-reference/whatsapp/whatsapp-collection.json GET /{instance}/contacts/get
Retrieve a specific contact by phone number or chat ID.
Retrieve detailed information about a specific contact in your WhatsApp instance.
This endpoint allows you to:
* Get contact details by phone number or chat ID
* Retrieve the contact's name and pushname
* Verify contact information before sending messages
This is useful when you need to fetch information about a specific contact before interacting with them.
## Use Cases
### Contact Lookup
Quickly look up contact details using their phone number or chat ID.
### Contact Verification
Verify that you have the correct contact information before sending important messages.
### CRM Integration
Sync contact details from WhatsApp to your CRM system.
## Request Parameters
### chat\_id
The contact identifier can be in one of these formats:
* **Phone number**: `123123123`
* **Chat ID (regular)**: `123123@c.us`
* **Chat ID (lid)**: `123123@lid`
## Response Examples
### Successful Response
When the contact is found:
```json theme={null}
{
"message": "Contact retrieved successfully.",
"data": {
"id": "100875997589545@lid",
"name": "Maria",
"pushname": "Maria Doe"
}
}
```
### Contact Not Found
When the contact doesn't exist:
```json theme={null}
{
"message": "Contact not found."
}
```
## Best Practices
Store the contact ID (`id` field) for future API calls instead of repeatedly looking up the same contact.
The `pushname` is the name the user has set in their WhatsApp profile, while `name` is the name saved in your phone's contacts.
# Get LID by Phone Number
Source: https://docs.hypersender.com/v2/api-reference/whatsapp/contacts/get-lid-by-phone-number
v2/api-reference/whatsapp/whatsapp-collection.json GET /{instance}/contacts/get-lid-by-phone-number
Resolve an @c.us chat ID to its @lid value when the mapping is already known by your Hypersender instance.
Resolves a phone-number-based chat ID to its linked identifier.
Pass the `@c.us` value as a query parameter named `phoneNumber`.
You can send either the full identifier, such as `3333333@c.us`, or only the numeric part when that fits your integration.
If the mapping is missing, your instance does not currently know how to convert that `@c.us` value.
## Response Example
```json theme={null}
{
"lid": "1111111@lid",
"pn": "3333333@c.us"
}
```
# Get Count of LIDs
Source: https://docs.hypersender.com/v2/api-reference/whatsapp/contacts/get-lids-count
v2/api-reference/whatsapp/whatsapp-collection.json GET /{instance}/contacts/get-lids-count
Return the number of @lid to @c.us mappings already known by a Hypersender WhatsApp instance.
Returns the total number of linked-identifier mappings currently known by this instance.
This is useful when you want to:
* Measure how many conversions are already available.
* Estimate pagination before listing all mappings.
* Monitor whether your instance is learning new contact mappings over time.
## Response Example
```json theme={null}
{
"count": 123
}
```
# Get Phone Number by LID
Source: https://docs.hypersender.com/v2/api-reference/whatsapp/contacts/get-phone-number-by-lid
v2/api-reference/whatsapp/whatsapp-collection.json GET /{instance}/contacts/get-phone-number-by-lid
Resolve an @lid value to its @c.us chat ID when the mapping is already known by your Hypersender instance.
Resolves a linked identifier to its phone-number-based chat ID.
Pass the `@lid` value as a query parameter named `lid`.
You can send either the full identifier, such as `1111111@lid`, or only the numeric part when that fits your integration.
If the mapping is missing, your instance does not currently know how to convert that `@lid` value.
## Response Example
```json theme={null}
{
"lid": "1111111@lid",
"pn": "3333333@c.us"
}
```
# Get Profile Picture
Source: https://docs.hypersender.com/v2/api-reference/whatsapp/contacts/get-profile-picture
v2/api-reference/whatsapp/whatsapp-collection.json GET /{instance}/contacts/profile-picture
Retrieve the profile picture URL for a specific contact.
Get the profile picture URL for any contact in your WhatsApp instance.
This endpoint allows you to:
* Retrieve profile picture URLs for contacts
* Display contact avatars in your application
* Verify contact identity visually
The returned URL is a direct link to the WhatsApp CDN where the profile picture is hosted.
## Use Cases
### Display Contact Avatars
Show contact profile pictures in your application's UI for better user experience.
### Contact Identity Verification
Visually verify contact identity before sending sensitive information.
### CRM Integration
Sync contact profile pictures to your CRM system for better contact management.
### Chat Interface
Build a chat interface that displays profile pictures alongside messages.
## Request Parameters
### chat\_id
The contact identifier can be in one of these formats:
* **Phone number**: `123123123`
* **Chat ID (regular)**: `123123@c.us`
* **Chat ID (lid)**: `123123@lid`
## Response Examples
### Successful Response
When the profile picture is found:
```json theme={null}
{
"message": "Profile picture retrieved successfully.",
"data": {
"profilePictureURL": "https://pps.whatsapp.net/v/t61.24694-24/374498176_337577482181161_7091117586184162691_n.jpg?ccb=11-4&oh=01_Q5Aa3gEERUGD4fegyplSv2MnHmt_UIA9JnpjREhSJMNVWZC-RA&oe=6970FAAA&_nc_sid=5e03e0&_nc_cat=104"
}
}
```
### No Profile Picture
When the contact has no profile picture:
```json theme={null}
{
"message": "Profile picture not available.",
"data": {
"profilePictureURL": null
}
}
```
## Best Practices
Cache the profile picture URLs to reduce API calls. Profile pictures don't change frequently.
The profile picture URLs are temporary and may expire. Always fetch a fresh URL if you encounter a broken image.
Some users may have privacy settings that prevent you from viewing their profile picture. In such cases, the URL will be null or point to a default image.
## Integration Example
### Displaying Profile Pictures in Your App
```javascript theme={null}
// Fetch profile picture
const response = await fetch(
`https://app.hypersender.com/api/whatsapp/v2/${instance}/contacts/profile-picture?chat_id=${chatId}`,
{
headers: {
'Authorization': `Bearer ${apiKey}`,
'Content-Type': 'application/json'
}
}
);
const data = await response.json();
// Use the URL in your UI
if (data.data.profilePictureURL) {
document.getElementById('avatar').src = data.data.profilePictureURL;
} else {
// Use a default avatar
document.getElementById('avatar').src = '/default-avatar.png';
}
```
# Upsert Contact
Source: https://docs.hypersender.com/v2/api-reference/whatsapp/contacts/upsert-contact
v2/api-reference/whatsapp/whatsapp-collection.json POST /{instance}/contacts/upsert
Update or create a contact in your phone address book and WhatsApp.
Update a contact in your phone address book using a phone number.
This endpoint allows you to:
* Create a new contact in your phone's address book
* Update an existing contact's information
* Sync contact details to WhatsApp using the contact's phone number
This endpoint is intended for phone-number-based contact management and address book synchronization.
## Use Cases
### Contact Management
Automatically create or update contacts when new users register in your system.
### CRM Synchronization
Keep your WhatsApp contacts in sync with your CRM database.
### Bulk Contact Import
Import and update multiple contacts from external sources.
## Request Parameters
### chat\_id
Use the contact's phone number only.
* **Phone number**: `12132132130`
Send the number with country code and without spaces or the `+` sign. Example: `12132132130`
Do not use an `@lid` identifier with this endpoint.
If the same person is handled once by phone number and again by LID, WhatsApp may treat them as two separate contacts. For upsert operations, always use the phone number only.
### first\_name
The contact's first name (required).
### last\_name
The contact's last name (optional).
## Response Examples
### Successful Response
When the contact is upserted successfully:
```json theme={null}
{
"message": "Contact upserted successfully.",
"data": {
"success": true
}
}
```
**Phone Address Book Update Note**
If you have multiple WhatsApp apps installed on your phone, the API might only work with one account.
You may need to make a few API requests with the same parameters and wait a few seconds between requests to update your phone address book.
## Best Practices
### Multiple Requests
If the contact doesn't appear in your address book immediately, try making 2-3 requests with a few seconds delay between them.
### Verification
After upserting a contact, you can use the **Get Contact** endpoint to verify the update was successful.
### Error Handling
Always implement proper error handling to catch validation errors or API failures.
# How to send WhatsApp message in Postman
Source: https://docs.hypersender.com/v2/api-reference/whatsapp/how-to-send-whatsapp-message-in-postman
The Hypersender WhatsApp API is a powerful api to send and receive messages using your own whatsapp number. In this guide, we will show you how to send a WhatsApp message using Postman.
# Introduction
Source: https://docs.hypersender.com/v2/api-reference/whatsapp/introduction
Hypersender WhatsApp API Docs - V2
The Hypersender WhatsApp API is a powerful api to send and recieve messages using your own whatsapp number. Without the high costs of Meta's Whatsapp business API.
In this Docs you'll learn how to use and integrate Hypersnder Whatsapp API into your existing system/service or application using simple API endpoints.
## What's New in V2?
**Queued Responses:** All requests in V2 are now queued for improved reliability and performance.
When you make any API request, you'll receive an immediate response with a `queued_request_uuid`:
```json theme={null}
{
"queued": true,
"message": "Processing your request...",
"queued_request_uuid": "a0816120-7e37-4e8b-8cf3-92deb2cdc133",
"queued_request_link": "https://app.hypersender.com/api/whatsapp/v2/{instance}/queued-requests/a0816120-7e37-4e8b-8cf3-92deb2cdc133"
}
```
Use the `queued_request_link` or the [Get Queued Request](/v2/api-reference/whatsapp/queued-requests/get-queued-request) endpoint to check the actual message response once it's processed.
***
## What you can do?
* Send Text and basic Url messages.
* Send Media through Link or uploaded file.
* Send Audio through Link or uploaded file.
* Send Contact Card
* Send Location
* Send Poll votes
## You can also
* React to a message
* Forward messages to other chats
* Acknowledge messages (mark as read)
* Star and unstar messages
## Quick Demo
Learn how to use Hypersender whatsapp API to send a message using Postman: [Demo Link](https://docs.hypersender.com/docs/hypersender/overview/how-to-send-whatsapp-message-in-postman).
## postman collection
You can download whatsapp API Postman Collection to easily interact with our API.
Download whatsapp API Postman Collection.
## Servers (Endpoints)
* Production (activated): [https://app.hypersender.com/api/whatsapp/v2](https://app.hypersender.com/api/whatsapp/v2)
## Authentication
All API endpoints are authenticated using Bearer tokens and picked up from the specification file.
```json theme={null}
"security": [
{
"bearerAuth": []
}
]
```
# Queued Requests
Source: https://docs.hypersender.com/v2/api-reference/whatsapp/queued-requests
Understanding the V2 queued request system and how it improves reliability and performance
## What are Queued Requests?
In V2 of the Hypersender API, all requests are processed through a **queued system**. Instead of waiting for your message to be sent in real-time, the API immediately accepts your request, queues it for processing, and returns a unique identifier (UUID) that you can use to track the status of your request.
## Why We Migrated to Queued Requests
### The Problem with V1
In V1, when you sent a message, the API would:
1. Receive your request
2. Process it immediately
3. Wait for WhatsApp to confirm the message was sent
4. Return the response to you
This synchronous approach had several limitations:
* **Timeouts**: If WhatsApp was slow to respond, your request could time out
* **Rate limiting issues**: Bursts of messages could overwhelm the system
* **Unreliable delivery confirmation**: Network issues could cause you to miss successful delivery confirmations
* **Poor scalability**: Each request held a connection open until completion
### The V2 Solution
The queued system solves these problems by:
* **Immediate acceptance**: Your request is validated and accepted within milliseconds
* **Reliable processing**: Messages are processed in order with automatic retries
* **Better rate limiting**: Requests are smoothly distributed to avoid WhatsApp blocks
* **Guaranteed delivery tracking**: You can always check the status of any request
* **Improved scalability**: The system can handle many more concurrent requests
## How It Works
### Step 1: Send Your Request
When you make any API request (e.g., send a message), you'll receive an immediate response with a `queued_request_uuid`:
```json theme={null}
{
"queued_request_uuid": "a0816120-7e37-4e8b-8cf3-92deb2cdc133"
}
```
This means your request has been accepted and is queued for processing.
### Step 2: Check the Status (Optional)
You can check the status of your request at any time using the UUID:
```bash theme={null}
GET /api/whatsapp/v2/{instance}/queued-requests/a0816120-7e37-4e8b-8cf3-92deb2cdc133
```
### Step 3: Get the Result
The response will show you the current status of your request:
**While Processing:**
```json theme={null}
{
"uuid": "a0816120-7e37-4e8b-8cf3-92deb2cdc133",
"request": {
"chatId": "111111111111@c.us",
"text": "Hello world!"
},
"response_status": null,
"response_body": null,
"response_header": null
}
```
**When Completed:**
```json theme={null}
{
"uuid": "a0816120-7e37-4e8b-8cf3-92deb2cdc133",
"request": {
"chatId": "111111111111@c.us",
"text": "Hello world!"
},
"response_status": 200,
"response_body": {
"message_id": "AAAAAA0000BBBBB00CCCCCC"
},
"response_header": {}
}
```
## Response Fields Explained
| Field | Type | Description |
| ----------------- | --------------- | --------------------------------------------------------------------------------------------------------------- |
| `uuid` | string | The unique identifier for this queued request |
| `request` | object | The original request payload you submitted |
| `response_status` | integer \| null | HTTP status code of the processed request. `null` while still processing |
| `response_body` | object \| null | The actual API response. Contains message details on success, error details on failure. `null` while processing |
| `response_header` | object \| null | Response headers from the processed request. `null` while processing |
## Determining Request Status
You can determine the status of a request by checking the `response_status` field:
| `response_status` | Meaning |
| ----------------- | ---------------------------------------- |
| `null` | Request is still being processed |
| `200` | Request completed successfully |
| `4xx` | Client error (e.g., invalid parameters) |
| `5xx` | Server error (will typically be retried) |
## Best Practices
### 1. Use Webhooks for Real-Time Updates
Instead of polling the queued request endpoint, configure webhooks to receive real-time notifications when messages are sent, delivered, or fail.
### 2. Store the UUID
Always store the `queued_request_uuid` returned from your requests. This allows you to:
* Track the status of any message
* Debug issues by looking up specific requests
* Build reliable retry logic
## Migration from V1
If you're migrating from V1, here's what changes:
| V1 Behavior | V2 Behavior |
| ----------------------------------------- | --------------------------------------------- |
| Synchronous response with message details | Immediate response with `queued_request_uuid` |
| Timeouts possible on slow requests | Always fast response |
| Direct error responses | Check status via UUID for errors |
## FAQ
Most requests are processed within 1-5 seconds. However, during high load or if WhatsApp is slow, it may take longer. The queued system ensures your request will be processed reliably.
If a request fails due to a temporary error (e.g., network issue), the system will automatically retry. If it fails due to a permanent error (e.g., invalid phone number), the `response_body` will contain the error details.
Queued request data is stored for 30 days. After that, you won't be able to look up the status by UUID.
Currently, queued requests cannot be cancelled once submitted. However, most requests are processed within seconds.
Yes! Webhooks work exactly the same way. You'll still receive webhook notifications for message events (sent, delivered, read, etc.) regardless of the queued system.
# Get Queued Request
Source: https://docs.hypersender.com/v2/api-reference/whatsapp/queued-requests/get-queued-request
v2/api-reference/whatsapp/whatsapp-collection.json GET /{instance}/queued-requests/{queued_request_uuid}
Check the status and response of a queued API request
## Understanding Queued Requests
In V2 of the Hypersender WhatsApp API, all requests are processed asynchronously through a queue system. This provides improved reliability and performance.
When you make any API request (send message, send image, etc.), you'll receive an immediate response like this:
```json theme={null}
{
"queued": true,
"message": "Processing your request...",
"queued_request_uuid": "a0816120-7e37-4e8b-8cf3-92deb2cdc133",
"queued_request_link": "https://app.hypersender.com/api/whatsapp/v2/{instance}/queued-requests/a0816120-7e37-4e8b-8cf3-92deb2cdc133"
}
```
Use this endpoint to check the actual result of your request.
***
## Response Format
When you query a queued request, you'll receive the full details including the original request and the response:
```json theme={null}
{
"uuid": "a08358c2-b4d6-4cd6-a882-70e606e4b95f",
"request": {
"text": "Check this https://hypersender.com/",
"chatId": "2015537361@c.us",
"session": "4-instance-2598",
"reply_to": null,
"linkPreview": false,
"linkPreviewHighQuality": false
},
"response_status": 201,
"response_body": {
"key": {
"id": "3EB0155CFDC2464F72FD75",
"fromMe": true,
"remoteJid": "2015537361@s.whatsapp.net"
},
"status": "PENDING",
"message": {
"extendedTextMessage": {
"text": "Check this https://hypersender.com/"
}
},
"messageTimestamp": "1764859906"
},
"response_header": {
"date": ["Thu, 04 Dec 2025 14:51:46 GMT"],
"content-type": ["application/json"],
"cache-control": ["no-cache, private"]
}
}
```
### Response Fields
| Field | Type | Description |
| ----------------- | ------- | ----------------------------------------------------------------- |
| `uuid` | string | Unique identifier for the queued request |
| `request` | object | The original request payload you sent |
| `response_status` | integer | HTTP status code of the processed request (e.g., 201 for success) |
| `response_body` | object | The actual API response with message details |
| `response_header` | object | Response headers from the processed request |
### Response Body (Message Details)
The `response_body` contains the WhatsApp message details:
| Field | Description |
| ------------------ | ----------------------------------------------------- |
| `key.id` | Unique WhatsApp message ID |
| `key.fromMe` | Whether the message was sent by you |
| `key.remoteJid` | The recipient's WhatsApp JID |
| `status` | Message status (e.g., "PENDING", "SENT", "DELIVERED") |
| `message` | The message content |
| `messageTimestamp` | Unix timestamp when the message was sent |
***
## Response Status Codes
Check the `response_status` field to determine if the request was successful:
| Status | Description |
| ------ | ------------------------------------------------------- |
| `201` | Message sent successfully |
| `404` | Instance not found or recipient not on WhatsApp |
| `422` | Validation error (invalid chatId, missing fields, etc.) |
| `500` | Server error |
***
## Example: Failed Request
If the request failed (e.g., invalid phone number), the response will look like:
```json theme={null}
{
"uuid": "a08358c2-b4d6-4cd6-a882-70e606e4b95f",
"request": {
"text": "Hello!",
"chatId": "invalid@c.us"
},
"response_status": 422,
"response_body": {
"message": "The given data was invalid.",
"errors": {
"messages": ["The number you want to send the message to is not on whatsapp."],
"jid": "invalid@s.whatsapp.net",
"exists": false
},
"statusCode": 422
},
"response_header": {
"content-type": ["application/json"]
}
}
```
***
## Polling Strategy
We recommend polling the queued request endpoint every **1-2 seconds** until you receive a response. Most requests complete within a few seconds.
### Example Polling Code (JavaScript)
```javascript theme={null}
async function waitForResult(queuedRequestLink, maxAttempts = 30) {
for (let i = 0; i < maxAttempts; i++) {
const response = await fetch(queuedRequestLink, {
headers: {
'Authorization': 'Bearer YOUR_API_TOKEN'
}
});
const data = await response.json();
// Check if we have a response_status (request completed)
if (data.response_status) {
if (data.response_status === 201) {
return data.response_body; // Success
} else {
throw new Error(data.response_body?.message || 'Request failed');
}
}
// Wait 1 second before next attempt
await new Promise(resolve => setTimeout(resolve, 1000));
}
throw new Error('Request timed out');
}
```
### Example Polling Code (PHP)
```php theme={null}
function waitForResult($queuedRequestLink, $maxAttempts = 30) {
for ($i = 0; $i < $maxAttempts; $i++) {
$response = Http::withToken('YOUR_API_TOKEN')
->get($queuedRequestLink);
$data = $response->json();
// Check if we have a response_status (request completed)
if (isset($data['response_status'])) {
if ($data['response_status'] === 201) {
return $data['response_body']; // Success
} else {
throw new Exception($data['response_body']['message'] ?? 'Request failed');
}
}
// Wait 1 second before next attempt
sleep(1);
}
throw new Exception('Request timed out');
}
```
# Delete Message
Source: https://docs.hypersender.com/v2/api-reference/whatsapp/send-messages/delete-message
v2/api-reference/whatsapp/whatsapp-collection.json DELETE /{instance}/delete-message
Delete a message from the chat.
**V2 Queued Response:** All API requests in V2 are queued for improved reliability. You'll receive an immediate response with a `queued_request_uuid` that you can use to check the actual message status.
## Response Format
All requests return a queued response:
```json theme={null}
{
"queued": true,
"message": "Processing your request...",
"queued_request_uuid": "a0816120-7e37-4e8b-8cf3-92deb2cdc133",
"queued_request_link": "https://app.hypersender.com/api/whatsapp/v2/{instance}/queued-requests/a0816120-7e37-4e8b-8cf3-92deb2cdc133"
}
```
Use the `queued_request_link` or the [Get Queued Request](/v2/api-reference/whatsapp/queued-requests/get-queued-request) endpoint to check the actual message response once it's processed.
More details on queued requests can be found in the [Queued Requests Documentation](/v2/api-reference/whatsapp/queued-requests).
***
You can delete messages from the chat.
so if you want to delete a message from a specific chat pass the `chatId` and `messageId` in the query parameters.
`chatId` - The unique identifier for the chat (e.g., `111111111111@c.us`)
`messageId` - The unique identifier for the message (e.g., `true_111111111111@c.us_3EB081B845A6A6E3991180`)
![Delete Message]()
# Forward Message
Source: https://docs.hypersender.com/v2/api-reference/whatsapp/send-messages/forward-message
v2/api-reference/whatsapp/whatsapp-collection.json POST /{instance}/forward-message
Forward a message to another chat (that you chatted before, otherwise it may fail) using Hypersender WhatsApp API.
**V2 Queued Response:** All API requests in V2 are queued for improved reliability. You'll receive an immediate response with a `queued_request_uuid` that you can use to check the actual message status.
## Response Format
All requests return a queued response:
```json theme={null}
{
"queued": true,
"message": "Processing your request...",
"queued_request_uuid": "a0816120-7e37-4e8b-8cf3-92deb2cdc133",
"queued_request_link": "https://app.hypersender.com/api/whatsapp/v2/{instance}/queued-requests/a0816120-7e37-4e8b-8cf3-92deb2cdc133"
}
```
Use the `queued_request_link` or the [Get Queued Request](/v2/api-reference/whatsapp/queued-requests/get-queued-request) endpoint to check the actual message response once it's processed.
More details on queued requests can be found in the [Queued Requests Documentation](/v2/api-reference/whatsapp/queued-requests).
***
You can forward a message to another chat (that you chatted before, otherwise it may fail):
* Chat
* Group
* Recipient
![forward message]()
# React to Message
Source: https://docs.hypersender.com/v2/api-reference/whatsapp/send-messages/react-to-message
v2/api-reference/whatsapp/whatsapp-collection.json PUT /{instance}/react-to-message
Add a reaction to a message.
**V2 Queued Response:** All API requests in V2 are queued for improved reliability. You'll receive an immediate response with a `queued_request_uuid` that you can use to check the actual message status.
## Response Format
All requests return a queued response:
```json theme={null}
{
"queued": true,
"message": "Processing your request...",
"queued_request_uuid": "a0816120-7e37-4e8b-8cf3-92deb2cdc133",
"queued_request_link": "https://app.hypersender.com/api/whatsapp/v2/{instance}/queued-requests/a0816120-7e37-4e8b-8cf3-92deb2cdc133"
}
```
Use the `queued_request_link` or the [Get Queued Request](/v2/api-reference/whatsapp/queued-requests/get-queued-request) endpoint to check the actual message response once it's processed.
More details on queued requests can be found in the [Queued Requests Documentation](/v2/api-reference/whatsapp/queued-requests).
***
Add a reaction to a message.
![React to Message]()
# Read Chat
Source: https://docs.hypersender.com/v2/api-reference/whatsapp/send-messages/read-chat
v2/api-reference/whatsapp/whatsapp-collection.json POST /{instance}/read-chat
Mark all unread messages in a chat as read (double blue checkmark) using Hypersender WhatsApp API.
**V2 Queued Response:** All API requests in V2 are queued for improved reliability. You'll receive an immediate response with a `queued_request_uuid` that you can use to check the actual message status.
## Response Format
All requests return a queued response:
```json theme={null}
{
"queued": true,
"message": "Processing your request...",
"queued_request_uuid": "a0816120-7e37-4e8b-8cf3-92deb2cdc133",
"queued_request_link": "https://app.hypersender.com/api/whatsapp/v2/{instance}/queued-requests/a0816120-7e37-4e8b-8cf3-92deb2cdc133"
}
```
Use the `queued_request_link` or the [Get Queued Request](/v2/api-reference/whatsapp/queued-requests/get-queued-request) endpoint to check the actual message response once it's processed.
More details on queued requests can be found in the [Queued Requests Documentation](/v2/api-reference/whatsapp/queued-requests).
***
You can mark all unread messages in the chat as read (double blue checkmark) using one query:
It’ll find all unread messages in the chat and mark them as read.
![Read Chat]()
# Send Contact Card
Source: https://docs.hypersender.com/v2/api-reference/whatsapp/send-messages/send-contact-card
v2/api-reference/whatsapp/whatsapp-collection.json POST /{instance}/send-contact-card
Send a contact card in the chat
**V2 Queued Response:** All API requests in V2 are queued for improved reliability. You'll receive an immediate response with a `queued_request_uuid` that you can use to check the actual message status.
## Response Format
All requests return a queued response:
```json theme={null}
{
"queued": true,
"message": "Processing your request...",
"queued_request_uuid": "a0816120-7e37-4e8b-8cf3-92deb2cdc133",
"queued_request_link": "https://app.hypersender.com/api/whatsapp/v2/{instance}/queued-requests/a0816120-7e37-4e8b-8cf3-92deb2cdc133"
}
```
Use the `queued_request_link` or the [Get Queued Request](/v2/api-reference/whatsapp/queued-requests/get-queued-request) endpoint to check the actual message response once it's processed.
More details on queued requests can be found in the [Queued Requests Documentation](/v2/api-reference/whatsapp/queued-requests).
***
You can send a contact card in a chat in two ways:
### By providing the vcard:
```json theme={null}
{
"vcard": "BEGIN:VCARD\\nVERSION:3.0\\nFN:Jane Doe\\nORG:Company Name;\\nTEL;type=CELL;type=VOICE;waid=911111111111:+11111111111111\\nEND:VCARD",
"organization": "Hypersender",
"whatsappId": 911111111111
}
```
### By providing the contact info:
```json theme={null}
{
"vcard": null,
"fullName": "john doe",
"organization": "hypersender",
"phoneNumber": "+1111111111111",
"whatsappId": "911111111111"
}
```
![Send Contact Card]()
# Send File
Source: https://docs.hypersender.com/v2/api-reference/whatsapp/send-messages/send-file
v2/api-reference/whatsapp/whatsapp-collection.json POST /{instance}/send-file
Send files (documents/attachments) to WhatsApp users via URL or file upload.
**V2 Queued Response:** All API requests in V2 are queued for improved reliability. You'll receive an immediate response with a `queued_request_uuid` that you can use to check the actual message status.
## Response Format
All requests return a queued response:
```json theme={null}
{
"queued": true,
"message": "Processing your request...",
"queued_request_uuid": "a0816120-7e37-4e8b-8cf3-92deb2cdc133",
"queued_request_link": "https://app.hypersender.com/api/whatsapp/v2/{instance}/queued-requests/a0816120-7e37-4e8b-8cf3-92deb2cdc133"
}
```
Use the `queued_request_link` or the [Get Queued Request](/v2/api-reference/whatsapp/queued-requests/get-queued-request) endpoint to check the actual message response once it's processed.
More details on queued requests can be found in the [Queued Requests Documentation](/v2/api-reference/whatsapp/queued-requests).
***
# Send a file (as a document/attachment) to a chat.
## You can send files in two ways:
### Provide a URL for the file.
![send-file url]()
Please note that the URL must be publicly accessible and not require any authentication or special headers to access the file.
***
### Send the file it self as a file upload.
![send-file file]()
Possible file types are: `[png, jpg, jpeg, gif, mp3, mp4, avi, mkv, mov, flv, wav, ogg, webm, 3gp, flac, aac, wma, m4a, opus, pdf, doc, docx, xls, xlsx, ppt, pptx, txt, zip]`
![send-file preview]()
# Send Image
Source: https://docs.hypersender.com/v2/api-reference/whatsapp/send-messages/send-image
v2/api-reference/whatsapp/whatsapp-collection.json POST /{instance}/send-image
Send images to WhatsApp users via URL or file upload.
**V2 Queued Response:** All API requests in V2 are queued for improved reliability. You'll receive an immediate response with a `queued_request_uuid` that you can use to check the actual message status.
## Response Format
All requests return a queued response:
```json theme={null}
{
"queued": true,
"message": "Processing your request...",
"queued_request_uuid": "a0816120-7e37-4e8b-8cf3-92deb2cdc133",
"queued_request_link": "https://app.hypersender.com/api/whatsapp/v2/{instance}/queued-requests/a0816120-7e37-4e8b-8cf3-92deb2cdc133"
}
```
Use the `queued_request_link` or the [Get Queued Request](/v2/api-reference/whatsapp/queued-requests/get-queued-request) endpoint to check the actual message response once it's processed.
More details on queued requests can be found in the [Queued Requests Documentation](/v2/api-reference/whatsapp/queued-requests).
***
Send images to the chat.
## You can send files in two ways:
### Provide a URL for the image.
![send-image url]()
Please note that the URL must be publicly accessible and not require any authentication or special headers to access the file.
Specify the `mimetype` of the image in the URL. Example: `image/png`
***
### Send the image it self as a file upload.
![send-image file]()
***
![send-image]()
# Send Voice
Source: https://docs.hypersender.com/v2/api-reference/whatsapp/send-messages/send-link-audio
v2/api-reference/whatsapp/whatsapp-collection.json POST /{instance}/send-voice
Send voice messages to WhatsApp users for more engaging and personal communication.
**V2 Queued Response:** All API requests in V2 are queued for improved reliability. You'll receive an immediate response with a `queued_request_uuid` that you can use to check the actual message status.
## Response Format
All requests return a queued response:
```json theme={null}
{
"queued": true,
"message": "Processing your request...",
"queued_request_uuid": "a0816120-7e37-4e8b-8cf3-92deb2cdc133",
"queued_request_link": "https://app.hypersender.com/api/whatsapp/v2/{instance}/queued-requests/a0816120-7e37-4e8b-8cf3-92deb2cdc133"
}
```
Use the `queued_request_link` or the [Get Queued Request](/v2/api-reference/whatsapp/queued-requests/get-queued-request) endpoint to check the actual message response once it's processed.
More details on queued requests can be found in the [Queued Requests Documentation](/v2/api-reference/whatsapp/queued-requests).
***
This specialized endpoint will allow you to send voice as if you were recording directly in the WhatsApp application.
## You can send voice messages in two ways:
## Provide a URL for the voice audio.
![send-voice-url]()
Please note that the URL must be publicly accessible and not require any authentication or special headers to access the file.
***
## Send the voice audio it self as a file upload.
![send-voice-file]()
***
![send-voice-preview]()
# Send Link Custom Preview
Source: https://docs.hypersender.com/v2/api-reference/whatsapp/send-messages/send-link-custom-preview
v2/api-reference/whatsapp/whatsapp-collection.json POST /{instance}/send-link-custom-preview
Send a WhatsApp message with a link preview to enhance engagement and provide context to your recipients.
**V2 Queued Response:** All API requests in V2 are queued for improved reliability. You'll receive an immediate response with a `queued_request_uuid` that you can use to check the actual message status.
## Response Format
All requests return a queued response:
```json theme={null}
{
"queued": true,
"message": "Processing your request...",
"queued_request_uuid": "a0816120-7e37-4e8b-8cf3-92deb2cdc133",
"queued_request_link": "https://app.hypersender.com/api/whatsapp/v2/{instance}/queued-requests/a0816120-7e37-4e8b-8cf3-92deb2cdc133"
}
```
Use the `queued_request_link` or the [Get Queued Request](/v2/api-reference/whatsapp/queued-requests/get-queued-request) endpoint to check the actual message response once it's processed.
More details on queued requests can be found in the [Queued Requests Documentation](/v2/api-reference/whatsapp/queued-requests).
***
This feature is only available for subscribed accounts.
Using **`send-text`** or **`send-text-safe`** you can send auto-generated link previews.
## You can send custom link preview in two ways:
### Provide a URL for the image.
![send link custom preview url preview]()
WhatsApp requires the text to contain the **preview URL** anywhere in the text.
Example: `"text": "Check this out! https://hypersender.com/"`
Please note that the URL must be publicly accessible and not require any authentication or special headers to access the file.
***
### Send the image it self as a file upload.
![send link custom preview file]()
By specifying the `high_quality` parameter as `true`, you can get a higher quality image.
![send link custom preview preview]()
# Send Location
Source: https://docs.hypersender.com/v2/api-reference/whatsapp/send-messages/send-location
v2/api-reference/whatsapp/whatsapp-collection.json POST /{instance}/send-location
You can send a location to a chat by providing latitude and longitude coordinates.
**V2 Queued Response:** All API requests in V2 are queued for improved reliability. You'll receive an immediate response with a `queued_request_uuid` that you can use to check the actual message status.
## Response Format
All requests return a queued response:
```json theme={null}
{
"queued": true,
"message": "Processing your request...",
"queued_request_uuid": "a0816120-7e37-4e8b-8cf3-92deb2cdc133",
"queued_request_link": "https://app.hypersender.com/api/whatsapp/v2/{instance}/queued-requests/a0816120-7e37-4e8b-8cf3-92deb2cdc133"
}
```
Use the `queued_request_link` or the [Get Queued Request](/v2/api-reference/whatsapp/queued-requests/get-queued-request) endpoint to check the actual message response once it's processed.
More details on queued requests can be found in the [Queued Requests Documentation](/v2/api-reference/whatsapp/queued-requests).
***
Send location to a chat
![Send Location]()
# Send Poll
Source: https://docs.hypersender.com/v2/api-reference/whatsapp/send-messages/send-poll
v2/api-reference/whatsapp/whatsapp-collection.json POST /{instance}/send-poll
You can ask a question and provide a few options for the user to choose from. The user can select only one option or multiple options, depending on the poll configuration.
**V2 Queued Response:** All API requests in V2 are queued for improved reliability. You'll receive an immediate response with a `queued_request_uuid` that you can use to check the actual message status.
## Response Format
All requests return a queued response:
```json theme={null}
{
"queued": true,
"message": "Processing your request...",
"queued_request_uuid": "a0816120-7e37-4e8b-8cf3-92deb2cdc133",
"queued_request_link": "https://app.hypersender.com/api/whatsapp/v2/{instance}/queued-requests/a0816120-7e37-4e8b-8cf3-92deb2cdc133"
}
```
Use the `queued_request_link` or the [Get Queued Request](/v2/api-reference/whatsapp/queued-requests/get-queued-request) endpoint to check the actual message response once it's processed.
More details on queued requests can be found in the [Queued Requests Documentation](/v2/api-reference/whatsapp/queued-requests).
***
You can create a poll in a chat.
![Send Poll Example]()
# Send Seen
Source: https://docs.hypersender.com/v2/api-reference/whatsapp/send-messages/send-seen
v2/api-reference/whatsapp/whatsapp-collection.json POST /{instance}/send-seen
Indicate to the recipient that you have seen their message in the chat
**V2 Queued Response:** All API requests in V2 are queued for improved reliability. You'll receive an immediate response with a `queued_request_uuid` that you can use to check the actual message status.
## Response Format
All requests return a queued response:
```json theme={null}
{
"queued": true,
"message": "Processing your request...",
"queued_request_uuid": "a0816120-7e37-4e8b-8cf3-92deb2cdc133",
"queued_request_link": "https://app.hypersender.com/api/whatsapp/v2/{instance}/queued-requests/a0816120-7e37-4e8b-8cf3-92deb2cdc133"
}
```
Use the `queued_request_link` or the [Get Queued Request](/v2/api-reference/whatsapp/queued-requests/get-queued-request) endpoint to check the actual message response once it's processed.
More details on queued requests can be found in the [Queued Requests Documentation](/v2/api-reference/whatsapp/queued-requests).
***
If you get a new message via 🔄 Webhooks and want to reply to that message, you need to first send that you've seen the message (double green tick).
# Send Text
Source: https://docs.hypersender.com/v2/api-reference/whatsapp/send-messages/send-text
v2/api-reference/whatsapp/whatsapp-collection.json POST /{instance}/send-text
Send plain text messages with link preview (optional) to WhatsApp users for basic communication, notifications, and automated messaging.
**V2 Queued Response:** All API requests in V2 are queued for improved reliability. You'll receive an immediate response with a `queued_request_uuid` that you can use to check the actual message status.
## Response Format
All requests return a queued response:
```json theme={null}
{
"queued": true,
"message": "Processing your request...",
"queued_request_uuid": "a0816120-7e37-4e8b-8cf3-92deb2cdc133",
"queued_request_link": "https://app.hypersender.com/api/whatsapp/v2/{instance}/queued-requests/a0816120-7e37-4e8b-8cf3-92deb2cdc133"
}
```
Use the `queued_request_link` or the [Get Queued Request](/v2/api-reference/whatsapp/queued-requests/get-queued-request) endpoint to check the actual message response once it's processed.
More details on queued requests can be found in the [Queued Requests Documentation](/v2/api-reference/whatsapp/queued-requests).
***
Send links and simple texts to a WhatsApp
* Chat
* Group
* Recipient
We highly recommend using the [`send-text-safe`](/api-reference/whatsapp/send-messages/send-text-safe) endpoint for regular messaging operations to maintain a more natural communication pattern, and keep your whatsapp number safe from being blocked.
## Sending link preview
If the text has a link - it generates a preview for that link. You can adjust the behaviour by setting
* `link_preview: true` - to enable link preview
* `link_preview_high_quality: true` - to enable high-quality link preview
![send-text send link preview]()
***
## Quick Demo
**Learn how to use Hypersender whatsapp API to send a message using Postman:** [Demo Link](/api-reference/whatsapp/how-to-send-whatsapp-message-in-postman)
# Send Text Safe
Source: https://docs.hypersender.com/v2/api-reference/whatsapp/send-messages/send-text-safe
v2/api-reference/whatsapp/whatsapp-collection.json POST /{instance}/send-text-safe
Safely send a WhatsApp text message with human-like pacing, typing simulation, and optional rich link previews to reduce block risk.
**V2 Queued Response:** All API requests in V2 are queued for improved reliability. You'll receive an immediate response with a `queued_request_uuid` that you can use to check the actual message status.
## Response Format
All requests return a queued response:
```json theme={null}
{
"queued": true,
"message": "Processing your request...",
"queued_request_uuid": "a0816120-7e37-4e8b-8cf3-92deb2cdc133",
"queued_request_link": "https://app.hypersender.com/api/whatsapp/v2/{instance}/queued-requests/a0816120-7e37-4e8b-8cf3-92deb2cdc133"
}
```
Use the `queued_request_link` or the [Get Queued Request](/v2/api-reference/whatsapp/queued-requests/get-queued-request) endpoint to check the actual message response once it's processed.
More details on queued requests can be found in the [Queued Requests Documentation](/v2/api-reference/whatsapp/queued-requests).
***
## Send Text Message Safe
The Send Text Safe endpoint functions similarly to the standard send-text endpoint but with enhanced safety features designed specifically to protect your WhatsApp number from being blocked or flagged for suspicious activity.
* WhatsApp has strict policies against automated messaging, and using the standard send-text endpoint too frequently can lead to your number being flagged or blocked.
* This endpoint is designed to mimic human behavior more closely, making it less likely for WhatsApp to detect automated activity.
### **It:**
* Automatically calculates the appropriate delay between messages based on text length, by adding a few seconds for thinking/reviewing before sending
* Simulates typing behavior in WhatsApp before sending the message
* Significantly reduces the risk of your WhatsApp number being blocked due to automated messaging patterns
* Reduces the risk of being flagged for automated behavior
***
## Sending link preview
If the text has a link - it generates a preview for that link. You can adjust the behaviour by setting
* `link_preview: true` - to enable link preview
* `link_preview_high_quality: true` - to enable high-quality link preview
![send-text send link preview]()
You can still send messages directly with `send-text` endpoint, but we highly recommend using this endpoint for regular messaging operations to maintain a more natural communication pattern, and keep your whatsapp number safe from being blocked.
***
## Quick Demo
**Learn how to use Hypersender whatsapp API to send a message using Postman:** [Demo Link](/api-reference/whatsapp/how-to-send-whatsapp-message-in-postman)
# Send Video
Source: https://docs.hypersender.com/v2/api-reference/whatsapp/send-messages/send-video
v2/api-reference/whatsapp/whatsapp-collection.json POST /{instance}/send-video
Send videos to WhatsApp users via URL or file upload.
**V2 Queued Response:** All API requests in V2 are queued for improved reliability. You'll receive an immediate response with a `queued_request_uuid` that you can use to check the actual message status.
## Response Format
All requests return a queued response:
```json theme={null}
{
"queued": true,
"message": "Processing your request...",
"queued_request_uuid": "a0816120-7e37-4e8b-8cf3-92deb2cdc133",
"queued_request_link": "https://app.hypersender.com/api/whatsapp/v2/{instance}/queued-requests/a0816120-7e37-4e8b-8cf3-92deb2cdc133"
}
```
Use the `queued_request_link` or the [Get Queued Request](/v2/api-reference/whatsapp/queued-requests/get-queued-request) endpoint to check the actual message response once it's processed.
More details on queued requests can be found in the [Queued Requests Documentation](/v2/api-reference/whatsapp/queued-requests).
***
Send videos to the chat.
This feature is only available for subscribed accounts.
## You can send videos in two ways:
### Provide a URL for the video.
![send-video url]()
Please note that the URL must be publicly accessible and not require any authentication or special headers to access the file.
You can send videos only in `mp4` formats - so make sure the url contains the correct extension - what WhatsApp accepts.
**Max allowed file size is `20MB`.**
***
### Send the video it self as a file upload.
![send-video file]()
***
![send-video]()
***
By specifying the `asNote` property to `true`, the video will be sent as a whatsapp note video.
![send-video note]()
# Star Message
Source: https://docs.hypersender.com/v2/api-reference/whatsapp/send-messages/star-message
v2/api-reference/whatsapp/whatsapp-collection.json PUT /{instance}/star-message
You can star or unstar a message using this endpoint.
**V2 Queued Response:** All API requests in V2 are queued for improved reliability. You'll receive an immediate response with a `queued_request_uuid` that you can use to check the actual message status.
## Response Format
All requests return a queued response:
```json theme={null}
{
"queued": true,
"message": "Processing your request...",
"queued_request_uuid": "a0816120-7e37-4e8b-8cf3-92deb2cdc133",
"queued_request_link": "https://app.hypersender.com/api/whatsapp/v2/{instance}/queued-requests/a0816120-7e37-4e8b-8cf3-92deb2cdc133"
}
```
Use the `queued_request_link` or the [Get Queued Request](/v2/api-reference/whatsapp/queued-requests/get-queued-request) endpoint to check the actual message response once it's processed.
More details on queued requests can be found in the [Queued Requests Documentation](/v2/api-reference/whatsapp/queued-requests).
***
Star or unstar a message.
![Star Message]()
# Start Typing
Source: https://docs.hypersender.com/v2/api-reference/whatsapp/send-messages/start-typing
v2/api-reference/whatsapp/whatsapp-collection.json POST /{instance}/start-typing
Indicate to the recipient that you are typing a message in the chat using Hypersender WhatsApp API.
**V2 Queued Response:** All API requests in V2 are queued for improved reliability. You'll receive an immediate response with a `queued_request_uuid` that you can use to check the actual message status.
## Response Format
All requests return a queued response:
```json theme={null}
{
"queued": true,
"message": "Processing your request...",
"queued_request_uuid": "a0816120-7e37-4e8b-8cf3-92deb2cdc133",
"queued_request_link": "https://app.hypersender.com/api/whatsapp/v2/{instance}/queued-requests/a0816120-7e37-4e8b-8cf3-92deb2cdc133"
}
```
Use the `queued_request_link` or the [Get Queued Request](/v2/api-reference/whatsapp/queued-requests/get-queued-request) endpoint to check the actual message response once it's processed.
More details on queued requests can be found in the [Queued Requests Documentation](/v2/api-reference/whatsapp/queued-requests).
***
Start typing in the chat.
![Start Typing]()
# Stop Typing
Source: https://docs.hypersender.com/v2/api-reference/whatsapp/send-messages/stop-typing
v2/api-reference/whatsapp/whatsapp-collection.json POST /{instance}/stop-typing
Indicate to the recipient that you have stopped typing a message in the chat using Hypersender WhatsApp API.
**V2 Queued Response:** All API requests in V2 are queued for improved reliability. You'll receive an immediate response with a `queued_request_uuid` that you can use to check the actual message status.
## Response Format
All requests return a queued response:
```json theme={null}
{
"queued": true,
"message": "Processing your request...",
"queued_request_uuid": "a0816120-7e37-4e8b-8cf3-92deb2cdc133",
"queued_request_link": "https://app.hypersender.com/api/whatsapp/v2/{instance}/queued-requests/a0816120-7e37-4e8b-8cf3-92deb2cdc133"
}
```
Use the `queued_request_link` or the [Get Queued Request](/v2/api-reference/whatsapp/queued-requests/get-queued-request) endpoint to check the actual message response once it's processed.
More details on queued requests can be found in the [Queued Requests Documentation](/v2/api-reference/whatsapp/queued-requests).
***
stop typing in the chat.
# What is chatId?
Source: https://docs.hypersender.com/v2/api-reference/whatsapp/what-is-chatid
Understand the identifier formats used by Hypersender WhatsApp endpoints, including @c.us and @lid.
`chatId` is the destination identifier used by Hypersender WhatsApp endpoints. The two formats you will work with most often are `@c.us` and `@lid`.
## `@c.us`
* Format: `[phoneNumber]@c.us`
* Use this when you know the contact's phone number.
* This is the standard phone-number-based identifier for direct messaging.
* Do not include `+`, spaces, or punctuation in the numeric part.
* Example: `12132132131@c.us`
## `@lid`
* Format: `[numericIdentifier]@lid`
* Use this when the contact is represented by a linked identifier instead of a visible phone number.
* This is a privacy-preserving identifier. The same person can have both an `@lid` value and an `@c.us` value.
* Example: `1111111@lid`
## Difference Between `@c.us` And `@lid`
* `@c.us` is based on the phone number.
* `@lid` is based on a linked identifier.
* Both can refer to the same contact.
* The contact conversion endpoints let you map one format to the other when the mapping is already known by your instance.
## Formatting Rules
* Keep the numeric part clean. Do not send `+`, spaces, or punctuation in phone-number-based values.
* When an endpoint accepts the identifier inside the URL path, encode `@` as `%40`.
* For example, use `1111111%40lid` or `201553730661%40c.us` in path-based endpoints.
* Some conversion endpoints also accept only the numeric part, such as `1111111` or `201553730661`.
## When To Convert
Use the contact conversion endpoints when you need to:
* Resolve a linked identifier to a phone-number chat ID.
* Resolve a phone-number chat ID to a linked identifier.
* List or count the mappings your instance already knows.
# Introduction
Source: https://docs.hypersender.com/v2/hypersender/index
Explore the Hypersender API documentation to learn how to send messages to your customers via WhatsApp and SMS.
## Before you start
This docs is divided into 3 main sections:
This section will introduce you to Hypersender, its features, how to setup an account, and how to use the platform in general.
This section will cover Whatsapp API reference and webhook events.
This section will also cover SMS API reference and webhook events.
This section will cover related packages and SDKs for different programming languages. **(Coming soon)**
## What you'll need
* [An account on Hypersender](https://app.hypersender.com/register).
* **For WhatsApp API, you'll need a working WhatsApp Account preferably 3 months old.**
* **For SMS API, you'll need a working phone number and an android phone.**
## Getting started
Whatsapp and SMS API are two different APIs that requires different setup, you can jump to whichever API you want to start with.
Full guide to start sending messages with Hypersender WhatsApp API.
Full guide to start sending messages with Hypersender SMS API.
## Disclaimer
This project is not affiliated, associated, authorized, endorsed by, or in any way officially connected with WhatsApp or any of its subsidiaries or its affiliates. The official WhatsApp website can be found at [https://whatsapp.com](https://whatsapp.com).
“WhatsApp” as well as related names, marks, emblems and images are registered trademarks of their respective owners. Also it is not guaranteed you will not be blocked by using this method. WhatsApp does not allow bots or unofficial clients on their platform, so this shouldn’t be considered totally safe.
This API is for small to medium businesses who want to send transactional messages such as OTPs, order confirmations, etc. It is not recommended for sending promotional messages. IT WILL GET YOU BANNED.
# Heartbeats
Source: https://docs.hypersender.com/v2/hypersender/overview/sms/heartbeats
Heartbeat are basically a signal that your Android phone sends to Hypersender to let it know that it's still alive and connected to the internet. This is important because Hypersender needs to know if your phone is still connected to the internet to send and receive SMS messages.
## Automatic Heartbeats
Hypersender Android app sends a heartbeat signal to Hypersender every 15 minutes. This is done automatically in the background and you don't have to do anything.
Hypersender will consider your phone offline if it doesn't receive a heartbeat signal from your phone for more than 2 hours. In this case, Hypersender will stop sending SMS messages to your phone until it receives a heartbeat signal from your phone.
## Manual Heartbeats
If you want to manually send a heartbeat signal to Hypersender, you can click on "Send Heartbeat" button in the Hypersender Android app. This is useful if you want to make sure that your phone is connected to the internet and Hypersender is able to send and receive webhooks from your phone.
![Send Heartbeat]()
# How It Works
Source: https://docs.hypersender.com/v2/hypersender/overview/sms/how-it-works
If you are curious about how Hypersender SMS works, you are in the right place. This section will give you a brief overview of sending an API request triggers your phone to send an SMS message.
## Picese of the puzzle
* Hypersender
* Your Android Phone
* Carrier Network
* Recipient's Phone
* Your API (Postman, cURL, etc)
## How Hypersender SMS Works
![How it works]()
1. You send an API request to Hypersender.
2. Hypersender sends the request to your Android phone.
3. Your Android phone sends the request to the carrier network.
4. The carrier network sends the request to the recipient's phone.
Your Android phone must be connected to the internet for this to work.
## What is the Benefits?
* You can can send as many SMS as your SIM credit allows.
* Cost of sending SMS from your phone is significantly lower than using a third-party service.
## What is the Limitations?
* Your carrier network may charge you extra fees for international SMS.
* It's your responsibility to make sure that you keep your SIM card active.
* It's your responsibility to make sure that your phone is connected to the internet and has enough battery.
# Receiving SMS Messages
Source: https://docs.hypersender.com/v2/hypersender/overview/sms/receiving-messages
When someone sends an SMS message to your phone number that is connected to Hypersender, Hypersender will forward the message to your specified webhook URL. This allows you to receive SMS messages from your customers and respond to them programmatically.
# SMS OTP Guide
Source: https://docs.hypersender.com/v2/hypersender/overview/sms/sms-otp-guide
How to send OTP codes over SMS with a lower risk of carrier filtering or dropped messages.
Some carriers may drop OTP SMS messages, especially when the message is too clear, too repetitive, or looks like a standard verification template.
We tested this with Egyptian carriers and verified that this can happen. The same issue may also appear with other carriers.
Delivery is never guaranteed. Even if a message format works on one carrier, the user still needs to test and verify it with their own destination numbers and regions.
## Keep the OTP message short
For OTP SMS, shorter and less explicit wording may work better than a clear verification sentence.
For example, this message may be dropped by some carriers:
```text theme={null}
Your verification code is: 12736. This code will expire in 5 minutes.
```
Instead, try a shorter format like:
```text theme={null}
login {app_name} 12345
```
This style may work better because it is shorter and less obviously formatted as a verification template.
## Recommendations
* Keep the message very short.
* Avoid long explanatory OTP sentences when possible.
* Avoid adding unnecessary punctuation or repeated template wording.
* Test the exact content with the carriers your users actually use.
* Verify delivery across different countries and operators before relying on one format.
## Important note
The format `login {app_name} 12345` is not a guarantee. It is only a practical pattern that may perform better in some cases, so every user should test and verify it in their own environment.
# Quick Start (SMS API)
Source: https://docs.hypersender.com/v2/hypersender/overview/sms/sms-quick-start
This guide will help you get started with Hypersender SMS API and send your first message.
## How To Starts
To get started, you need to create an account on Hypersender. Visit [Hypersender](https://app.hypersender.com/login) and click on the Sign Up button.
After you have successfully created an account, you need to create an instance. An instance represents a one phone number and the app on your android phone. You can create multiple instances for different phone numbers.
1. Click on the **Create Instance** button.
2. Select Service Type: **WhatsApp**
3. Enter a name for your instance.
4. Enter your phone number. i.e. `+2011313311331`, make sure it's a working number and you have access to it.
5. Enter a description for your instance **(Optional)**.
After you have created an instance successfully, you will be redirected to the instance listing page. You'll immediately see a notification to copy your API key. Click on the **Copy** button to copy the API key to your clipboard.
Copy `instanceId` and `apiKey`, you will need them to authenticate your requests.
Currently, Google Play Store does not allow SMS apps to be published. So you need to download the app from the Hypersender website.
1. Visit the Github release page: [Hypersender SMS App](https://github.com/hypersender/sms-app-releases/releases).
2. Click on the Download App button.
3. Scan the QR code using your phone to download the app.
### Required App Permissions
In order for Hypersender to work properly, you need to grant the following permissions to the app:
This permission is required for Hypersender to send notifications to your phone.
![Allow Hypersender SmS to send you notifications]()
This permission is required for Hypersender to send and view messages on your phone.
![Allow Hypersender SmS to send and view messages]()
This permission is required for Hypersender to make and manage phone calls on your phone.
![Allow Hypersender SmS to make and manage phone calls]()
This permission is required for Hypersender to access and view your phone logs.
![Allow Hypersender SmS to access phone logs]()
### Battery Optimization
Hypersender needs to work continuously in the background to send, receive, view, and manage messages, so it's important to disable battery optimization for the app.
Hypersender will asks you to disable battery optimization when you first open it. Click on the **Ignore Battery Optimization** button to disable battery optimization for the app.
![Disable battery optimization for Hypersender SmS]()
If for some reason you missed the battery optimization prompt, you can disable battery optimization manually by following these steps:
1. Open **Settings** on your phone.
2. Search for **Battery Optimization**.
3. Search for **Hypersender SMS** and disable battery optimization for the app.
You'll notice that connection status is **Disconnected**. To connect your SMS app, you need to enter the API key you copied earlier in the app.
After you have successfully connected your SMS app, you should see the connection status as **Connected**. Now you can send your first message.
## Quick Demo
Learn how to use Hypersender SMS API to send a message using Postman: [Demo Link](https://docs.hypersender.com/api-reference/sms/how-to-send-sms-message-in-postman).
## postman collection
You can download SMS API Postman Collection to easily interact with our API.
Download SMS API Postman Collection.
# How to Avoid Getting Blocked (WhatsApp)
Source: https://docs.hypersender.com/v2/hypersender/overview/whatsapp/avoid-getting-blocked
Practical steps to reduce reports, build healthy conversations, and protect your WhatsApp number.
WhatsApp actively limits spam and unwanted messaging. No tactic can guarantee that a number will not be blocked, but consent, useful messages, real conversations, and gradual sending greatly reduce the risk.
Do not use this guide to send unsolicited bulk messages. If recipients do not expect your message, technical adjustments will not protect the number from reports.
## Essentials
### 1. The age of the number
**A number with an established history of normal WhatsApp use is generally safer than a newly registered number.**
Spammers often create new numbers and immediately send high volumes, so new accounts receive more scrutiny.
* **Warm up the number**: Send and receive a small number of genuine messages, calls, images, and files with real contacts before connecting it to the API. Follow the [number warm-up guide](/v2/hypersender/overview/whatsapp/warm-up-your-whatsapp-number).
* **Increase activity gradually**: Do not move from almost no activity to hundreds of outbound messages in one day.
Do not scan the QR code and start automated sending immediately after registering a new number. Use the account normally for a few days first.
### 2. Consent and spam compliance
Most blocks begin with recipients reporting messages they did not request or recognize.
* **Let recipients message you first**: Add a WhatsApp button to your website, checkout, support page, or app.
* **State the purpose immediately**: Mention your business name, why you are contacting them, and what action is expected.
* **Provide an opt-out**: Include wording such as "Reply STOP to unsubscribe" and process it immediately.
* **Personalize honestly**: Use the recipient's name and relevant context, such as an order, booking, support request, or account action.
* **Keep the opening short**: Send one clear message instead of several messages before the recipient responds.
WhatsApp may show prominent **Block** and **Report** actions for unknown senders. A vague or unexpected opening message makes those actions more likely.
### 3. Let the user start the conversation
A customer-initiated conversation is much safer than an unexpected outbound message. When the user messages you first and you reply, the conversation already has clear context and intent.
```mermaid actions={false} theme={null}
flowchart LR
A[User requests an action] --> B[User opens WhatsApp]
B --> C[User sends the first message]
C --> D[Webhook receives it]
D --> E[Your API replies]
```
Use a button or link for login, OTP, support, order updates, booking confirmation, or requesting a quote.
The customer sends the first message from their own WhatsApp account.
Receive the incoming message through [WhatsApp webhooks](/v2/api-reference/whatsapp-webhooks/introduction), then reply using the messaging API.
For OTP or passwordless login, generate a link that opens WhatsApp with a prepared message. The user sends it first, then your system replies.
If you prefer to build the flow yourself, receive the user's first message through webhooks, identify the request, and reply using the API.
### 4. Contacts, `@c.us`, and `@lid`
WhatsApp identifies individual chats using a `chatId`.
| Format | Meaning | Usage |
| --------------------- | --------------------- | --------------------------------------------------------------------------------------------------------------- |
| `201234567890@c.us` | Phone-number-based ID | Use the full international number without `+`, spaces, or hyphens. |
| `123456789012345@lid` | WhatsApp Linked ID | Use the exact ID returned by WhatsApp, a webhook, or the contacts API. Do not construct or convert it manually. |
Read [What is chatId?](/v2/api-reference/whatsapp/what-is-chatid) before storing or sending to these identifiers.
For a new recipient, save the number as a contact before the first outbound message when practical. Use the [Upsert Contact endpoint](/v2/api-reference/whatsapp/contacts/upsert-contact) or add it through the connected phone's address book. Ask customers to save your business number as well.
Saving contacts can improve recognition and trust, but it does not replace consent. An unwanted message can still be reported.
### 5. Response rate
A long sequence of outbound messages with few replies is a strong sign that recipients are not interested. Respond to incoming messages promptly and keep conversations two-sided.
* Ask a clear question or include a useful call to action.
* Reply within 24 hours when possible.
* Stop follow-ups when a recipient does not engage.
* Track sent messages, replies, opt-outs, blocks, and delivery failures.
A practical internal target is at least 30 replies per 100 initial messages. This is not an official WhatsApp threshold, but a low reply rate should trigger a review of your audience and message.
### 6. Mass messaging
There is no universal daily volume that is safe for every number. Risk depends on account history, sending speed, recipient consent, reply rate, and reports.
* Increase volume gradually.
* Send only to recipients who expect the message.
* Segment campaigns by purpose, region, language, and customer relationship.
* Pause campaigns when replies fall or opt-outs and reports rise.
* Never send the same promotion repeatedly to people who did not respond.
Sending many messages to strangers can lead to temporary restrictions or a permanent block, especially when recipients report the number.
### 7. Other considerations
Use a complete business profile with a recognizable name, photo, and status. Avoid misleading claims, scam-like wording, prohibited goods, illegal content, and requests for unnecessary sensitive information. Review WhatsApp's current policies before launching a bot or campaign.
## How to Avoid Getting Banned
WhatsApp does not expect a normal account to suddenly send large volumes to people it has never contacted. Before sending, follow these guidelines.
### Guidelines
**Do not send messages that recipients may reasonably consider spam.** Reports are the clearest signal that your targeting or content is wrong.
* **Provide real value**: Send content tied to an action the recipient requested, such as a survey they joined, an order update, an OTP, or a support reply.
* **Vary messages naturally**: Personalize the name, context, language, and requested action. Do not send identical copy to every recipient or insert random characters only to disguise automation.
* **Avoid fixed bursts**: Spread messages over time. For multi-part messages, wait 30 to 60 seconds when appropriate, or use the [Send Text Safe endpoint](/v2/api-reference/whatsapp/send-messages/send-text-safe).
* **Group contacts by region**: Segment by area code or country when it reflects your real customer base and operating markets.
* **Complete the profile**: Add a profile picture, business name, and status before sending messages.
* **Use a strong opening**: Start with one short message that identifies your business and the reason for contact.
* **Encourage real conversation**: Ask for a reply only when it is useful. Do not manufacture engagement or pressure people to respond.
* **Respect silence and opt-outs**: Stop messaging recipients who do not engage, unsubscribe, or ask not to be contacted.
If the content is spam, switching between direct messages, groups, and broadcast lists will not make it safe.
As an API provider, we recommend following WhatsApp's policies, contacting only opted-in recipients, saving new contacts before outbound messaging, and letting the customer start the conversation whenever possible.
## Timelock, Message Capping, and LID Errors
WhatsApp can limit how many new contacts you message. Two restrictions can block messages to new contacts: a timelock and message capping. Hypersender detects both and shows them in your dashboard.
* [WhatsApp Message Capping: What It Is and How to Handle It](/v2/hypersender/overview/whatsapp/whatsapp-message-capping) covers what message capping is and what to do when you hit the cap.
* [Understanding WhatsApp Timelock Restrictions](/v2/hypersender/overview/whatsapp/whatsapp-timelock-restrictions) explains what timelocks are and how they affect your messaging.
* [Resolving Unknown Contacts (LID Issue)](/v2/hypersender/overview/whatsapp/whatsapp-lid-issue) explains why WhatsApp may fail to resolve a recipient.
You can also read how Hypersender handles these restrictions on our blog: [WhatsApp message capping](https://hypersender.com/en/blog/how-we-handle-whatsapp-message-capping) and [WhatsApp timelock](https://hypersender.com/en/blog/how-we-handle-whatsapp-timelock-restrictions).
Sign in to the [Hypersender dashboard](https://app.hypersender.com) to see the current status of your instances.
# Warming Up New Phone Numbers for WhatsApp API
Source: https://docs.hypersender.com/v2/hypersender/overview/whatsapp/warm-up-your-whatsapp-number
Recent changes in WhatsApp's security protocols have led to stricter monitoring of new numbers, frequently resulting in blocks. This presents a challenge for businesses integrating the WhatsApp API, particularly those using new eSIM numbers. To avoid these blocks, it's crucial to 'warm up' new numbers, mimicking human behavior to establish legitimacy.
The longer a number has been registered with WhatsApp, the more resistant it is to blocking.
Newly registered numbers are immediately flagged as "suspicious". Therefore:
**Important**: Do not scan the QR code immediately after registering a new number on WhatsApp. Wait a few hours or more!
## The Concept of **'Number Warming'**
'Number warming' in the WhatsApp context means gradually increasing a new number's activity. This process is vital to avoid triggering WhatsApp's anti-spam algorithms, which are quick to block numbers showing sudden, high-volume activity.
Warming involves typical user behaviors: messaging, calling, status updates, and group participation. It's a strategy to show the number is used naturally, not for spam or automation. Proper warming builds a usage history, reducing the risk of blocks when starting API integration.
## Strategies for Warming Up New Numbers
Successfully "warming up" a new number on WhatsApp involves a step-by-step approach over a period of about 3-10 days. Here's a step-by-step guide:
**Important**: After connecting a new number, do not rush to immediately send messages through the API!
The following are "perfectly calibrated" tips for a new number just purchased. We realize that you don't always have time to do this. Therefore, we encourage you to use these tips as a basic framework, adjusting the rules to suit your situation.
* Do not connect your newly registered WhatsApp number to our service immediately. Wait a few hours.
* Complete setting up your profile on your phone (set details, profile picture).
* Ensure you have at least 20-50 contacts in your address book. If not, add some contacts (an empty address book is a risk factor!).
* Manually message 1-2 contacts you know from your phonebook and ensure you get a response.
* Start a few private chats (3-6 conversations) with your existing contacts through your phone.
* Write a few varied messages via API and ensure you get responses. Send and receive a few images or videos/stickers to mimic typical user behavior.
* Increase the number of conversations to 10-15 chats.
* Continue to write varied messages and media messages (about 1 message per minute). Ensure you get responses to your messages.
* Begin to initiate more conversations, gradually increasing the number each day.
* Start participating in group conversations, if possible.
* Send a wider variety of messages, including links and longer texts.
* Strive to keep the number of sent messages equal to the number of incoming messages.
* Create or join more groups and actively participate in them.
* Start using WhatsApp status updates, use channels, and create a community.
* Continue to increase the volume of messages and diversify the types of messages sent.
* Initially, don't send more than 2 messages per minute, more than 6 hours a day, or more than 3 days in a row.
## General Tips:
* Ensure that the activities mimic real human behavior – random rather than systematic.
* Add the number to your contacts before you text them.
* Avoid sending too many messages in a short time or engaging in one-way communication.
* Spread interactions throughout the day, not clustered at specific times.
* Gradually build up the number of messages and types of interactions.
# WhatsApp LID Issue — Resolving Unknown Contacts
Source: https://docs.hypersender.com/v2/hypersender/overview/whatsapp/whatsapp-lid-issue
Understand what WhatsApp LIDs are, why you may encounter 'could not resolve recipient' errors, and how to handle them when sending messages.
When sending messages through the WhatsApp API, you may occasionally encounter an error indicating that WhatsApp **could not resolve a recipient**. This is often related to WhatsApp's internal contact resolution system, which uses **LIDs (Linked IDs)** to identify contacts.
## What is a LID?
WhatsApp identifies contacts internally using a unique identifier called a **Linked ID (LID)**. This is separate from the phone-number-based ID (`@c.us` format) that you normally use to send messages.
| Format | Meaning | Usage |
| --------------------- | --------------------- | ------------------------------------------------------------------------- |
| `201234567890@c.us` | Phone-number-based ID | Use the full international number without `+`, spaces, or hyphens. |
| `123456789012345@lid` | WhatsApp Linked ID | An internal identifier managed by WhatsApp. Do not construct it manually. |
When you send a message to a phone number, WhatsApp's servers must first resolve that phone number to its internal LID. If this resolution fails, the message cannot be delivered.
## Why Does the "Could Not Resolve Recipient" Error Happen?
There are several reasons why WhatsApp may fail to resolve a recipient:
### 1. The Number Does Not Exist on WhatsApp
The most common cause. The phone number you are trying to message is not registered with WhatsApp, or the account has been deleted.
### 2. The Number is Temporarily Unreachable
A valid WhatsApp number may be temporarily unreachable due to network issues, the user changing devices, or the account being in a restricted state.
### 3. Timelock Restrictions
If your instance is under a Meta timelock restriction, WhatsApp may refuse to resolve new contacts — even if those numbers exist on WhatsApp. This is part of the restriction enforcement.
Read more: [Understanding WhatsApp Timelock Restrictions](/v2/hypersender/overview/whatsapp/whatsapp-timelock-restrictions)
### 4. WhatsApp Service Disruptions
Rarely, WhatsApp's own infrastructure may experience issues that prevent contact resolution for a short period.
## How Hypersender Handles LID Errors
When WhatsApp fails to resolve a recipient, Hypersender returns a clear error to your API request:
* **HTTP 422 status code** with a message explaining that the recipient could not be resolved
* If your instance has an active timelock, the error message includes the **remaining restriction time**
* The error helps your application distinguish between a genuine invalid number and a temporary resolution failure
## What You Can Do About LID Errors
Double-check that the phone number is in the correct international format (e.g., `201234567890` for an Egyptian number) and that the person actually uses WhatsApp.
Look at your instance's status in the Hypersender dashboard. If a timelock warning banner is visible, the restriction is likely the cause. Wait for the restriction to expire or use a different instance.
Use the [Upsert Contact endpoint](/v2/api-reference/whatsapp/contacts/upsert-contact) to save the number as a contact before sending a message. This can improve resolution reliability.
Use the [Get All Contacts endpoint](/v2/api-reference/whatsapp/contacts/get-all-contacts) to see which contacts are already known to your instance and their LID mappings.
If the error is temporary (network issues or WhatsApp service disruption), wait a few minutes and retry. Hypersender's [Queued Requests](/v2/api-reference/whatsapp/queued-requests) feature can help with automatic retries.
## Working with LIDs in Your Integration
Always use the `@c.us` phone-number format when sending messages. Hypersender handles the LID resolution internally. You do not need to work with `@lid` identifiers directly.
If you need to retrieve the LID for a known phone number or find the phone number for a known LID, use these endpoints:
* [Get Phone Number by LID](/v2/api-reference/whatsapp/contacts/get-phone-number-by-lid) — Look up a phone number using a LID
* [Get LID by Phone Number](/v2/api-reference/whatsapp/contacts/get-lid-by-phone-number) — Look up a LID using a phone number
* [Get All Known LIDs](/v2/api-reference/whatsapp/contacts/get-all-known-lids) — List all known LID mappings for your instance
Learn more about WhatsApp chat identifiers, including `@c.us` and `@lid` formats.
# WhatsApp Message Capping: What It Is and How to Handle It
Source: https://docs.hypersender.com/v2/hypersender/overview/whatsapp/whatsapp-message-capping
WhatsApp message capping limits how many new contacts you can message in a cycle. Learn the status levels, what happens when you hit the cap, and how Hypersender keeps you informed.
WhatsApp message capping is a quota that Meta places on how many new contacts a number can message in a cycle. When an account reaches the cap, WhatsApp blocks messages to new contacts until the cycle resets. Messages to existing conversations keep working.
This guide covers what message capping is, how to read the status levels, what happens when you hit the cap, and how Hypersender shows your quota so you can plan around it.
## What is WhatsApp message capping?
Meta limits the number of new contacts an account can message in a cycle. A new contact is a number with no existing chat history. The cycle has a start and an end, and the quota resets on its own when the cycle ends.
Message capping is a volume limit. It is not a block on your account. Your instance stays connected and working while the cap is active.
Hypersender cannot remove or reset a message cap. Only Meta controls when the quota resets. Do not restart or re-pair your instance to try to clear it. The cap clears on its own.
## Status levels
Meta reports the cap as one of four statuses. Each status shows how close you are to the limit.
| Status | Meaning |
| ---------------- | ----------------------------------------------------------------------------------- |
| `NONE` | No cap is active on this account. |
| `FIRST_WARNING` | You are approaching the quota. Slow down outreach to new contacts. |
| `SECOND_WARNING` | You are close to the quota. Slow down before you hit the cap. |
| `CAPPED` | You reached the quota. Messages to new contacts are blocked until the cycle resets. |
The status moves through these levels as you use the quota:
```mermaid actions={false} theme={null}
flowchart LR
A[NONE] --> B[FIRST_WARNING]
B --> C[SECOND_WARNING]
C --> D[CAPPED]
D -->|Cycle resets| A
```
Each status also carries two numbers:
| Field | Meaning |
| ------------ | --------------------------------------------------------------------------------------------- |
| `totalQuota` | New-chat messages allowed in the current cycle. A value of `-1` means the account has no cap. |
| `usedQuota` | New-chat messages already used in the current cycle. |
The cycle start and end are Unix timestamps. The end time is the clock for when the quota resets.
## What happens when you are capped
When the status is `CAPPED`, messages to new contacts fail until the cycle ends.
* Messages to new contacts fail with an error.
* Messages to existing conversations keep working.
* Incoming messages keep working.
* Your instance stays connected. You do not need to scan a QR code.
The quota counts one-to-one messages to contacts without an established chat. It does not count replies to existing conversations.
## How Hypersender shows your quota
Hypersender reads the capping status from your instance and shows it in three places.
### Dashboard progress bar
When a cap is active, your connection page shows a progress bar with the used and total quota.
The bar shows:
* The percentage of the quota you have used.
* The used and total numbers, for example "640 of 1,000 messages".
* The time left until the quota resets.
The bar color changes as you approach the cap:
| Status | Bar color |
| ---------------- | --------- |
| `FIRST_WARNING` | Amber |
| `SECOND_WARNING` | Orange |
| `CAPPED` | Red |
### Email notification
You receive an email when the status changes. The email shows the used and total quota, the percentage, and the reset time. You receive one email per status level per cycle, so we do not spam you.
### API error message
When your app tries to message a new contact while the account is capped, the API returns HTTP 423 with a clear message. The message includes the time left when the quota resets:
```
Meta has capped this instance's new-chat messages for the current cycle. Hypersender cannot override this. The quota resets in 12 days, 4 hours. You can send to numbers with an existing conversation, or use a different instance.
```
## What to do when you hit the cap
1. **Keep messaging existing contacts.** These conversations still work.
2. **Use another number for new contacts.** If you need to reach new contacts now, switch to a different instance.
3. **Let the quota reset.** The cap lifts on its own at the cycle end. Trying to bypass it does not help.
4. **Review your volume.** If you hit the cap often, spread outreach across more numbers.
## Message capping vs timelock
Message capping and a timelock are two different restrictions. Both block messages to new contacts, but they work in different ways.
| | Message capping | Timelock |
| -------------- | -------------------------------- | ------------------------------------- |
| What it limits | Number of new contacts per cycle | New-contact outreach for a set period |
| Trigger | Reaching the new-contact quota | Messaging too many new contacts |
| Send error | `server returned error 475` | `server returned error 463` |
| Resets | At the cycle end | At the restriction end |
| Session | Stays connected | Stays connected |
Read [Understanding WhatsApp Timelock Restrictions](/v2/hypersender/overview/whatsapp/whatsapp-timelock-restrictions) for details on the other restriction.
## Prevent the cap
The cap tracks new-contact messages. The best way to stay under it is to keep outreach within healthy limits.
* Warm up new numbers before sending at scale. See [Warming Up New Phone Numbers for WhatsApp API](/v2/hypersender/overview/whatsapp/warm-up-your-whatsapp-number).
* Let customers message you first when possible.
* Add more numbers and spread outreach across them.
Read the full [guide on avoiding blocks](/v2/hypersender/overview/whatsapp/avoid-getting-blocked) for a complete checklist.
## Related
* [How we handle WhatsApp message capping](https://hypersender.com/en/blog/how-we-handle-whatsapp-message-capping) on the Hypersender blog.
* [Hypersender dashboard](https://app.hypersender.com) to check your instances.
Complete guide on how to avoid getting blocked on WhatsApp.
# WhatsApp OTP Guide
Source: https://docs.hypersender.com/v2/hypersender/overview/whatsapp/whatsapp-otp-guide
How to handle OTP on WhatsApp with lower ban risk by letting the user message first, then replying through webhooks or the OTP API.
Sending OTP codes as an unexpected first WhatsApp message is risky. WhatsApp is likely to ban or restrict accounts that send OTPs to users who did not start the conversation first.
If your flow sends OTP messages directly to new or inactive recipients, your WhatsApp account is much more likely to be reported, blocked, or banned.
## Recommended approach
The safer pattern is to make the user send the first WhatsApp message, then reply with the OTP.
```mermaid actions={false} theme={null}
flowchart LR
A[User clicks Verify with WhatsApp] --> B[WhatsApp opens]
B --> C[User sends the first message]
C --> D[Your webhook receives the message]
D --> E[Your system generates or fetches the OTP]
E --> F[Reply with the OTP on WhatsApp]
```
This creates clear user intent and gives the conversation context before your system sends the OTP.
## Option 1: Build it yourself with webhooks
Use this option if you want full control over the verification flow.
Add a WhatsApp button or link in your app or website so the user starts the chat themselves.
Configure [WhatsApp webhooks](/v2/api-reference/whatsapp-webhooks/introduction) to capture the user's first message.
In your backend, detect the verification request, generate or validate the OTP, and connect it to the correct user session.
Send the OTP back as a reply using the messaging endpoints in the [WhatsApp API](/v2/api-reference/whatsapp/introduction).
Keep the first user message simple, such as "verify", "login", or a short token tied to the current session.
## Option 2: Use our existing OTP API
If you do not want to build the full flow yourself, use the existing OTP API.
Create a WhatsApp OTP link that opens WhatsApp with a prepared message so the user can start the conversation first.
You can also use these endpoints directly:
* [Request OTP code](/v2/api-reference/otp/otp-service/request-code)
* [Validate OTP code](/v2/api-reference/otp/otp-service/validate-code)
This is the recommended path if you want a faster implementation with less custom backend logic.
## Best practice summary
* Do not send OTPs as cold outbound WhatsApp messages.
* Expect higher ban risk if your account starts OTP conversations by itself.
* Prefer a flow where the user sends the first message.
* Use webhooks if you want to build the logic yourself.
* Use the OTP API if you want a ready-made flow.
# Quick Start (WhatsApp API)
Source: https://docs.hypersender.com/v2/hypersender/overview/whatsapp/whatsapp-quick-start
This guide will help you get started with Hypersender WhatsApp API and send your first message.
## How To Starts
To get started, you need to create an account on Hypersender. Visit [Hypersender](https://app.hypersender.com/login) and click on the Sign Up button.
After you have successfully created an account, you need to create an instance. An instance is a unique identifier for your WhatsApp account. You can create multiple instances for different WhatsApp accounts.
1. Click on the **Create Instance** button.
2. Select Service Type: **WhatsApp**
3. Enter a name for your instance.
4. Enter your WhatsApp number. i.e. `+2011313311331`, make sure it's a working number and you have access to it.
5. Enter a description for your instance **(Optional)**.
After you have created an instance successfully, you will be redirected to the instance listing page. You'll immediately see a notification to copy your API key. Click on the **Copy** button to copy the API key to your clipboard.
Copy `instanceId` and `apiKey`, you will need them to authenticate your requests.
You'll notice that connection status is **Disconnected**. To connect your WhatsApp account, you need to scan the QR code using your Whatsapp App on your phone.
1. Navigate to the 3 dots on the instance then click on **Activate**.
2. A QR code will appear, scan it using your WhatsApp App on your phone.
After you have successfully connected your WhatsApp account, you should see the connection status as **Connected**. Now you can send your first message.
## Quick Demo
Learn how to use Hypersender whatsapp API to send a message using Postman: [Demo Link](https://docs.hypersender.com/api-reference/whatsapp/how-to-send-whatsapp-message-in-postman).
## postman collection
You can download whatsapp API Postman Collection to easily interact with our API.
Download whatsapp API Postman Collection.
# Understanding WhatsApp Timelock Restrictions
Source: https://docs.hypersender.com/v2/hypersender/overview/whatsapp/whatsapp-timelock-restrictions
Learn what WhatsApp timelock restrictions are, how they affect your messaging, and what you can do when Meta places a restriction on your number.
WhatsApp actively enforces its policies to prevent spam and unwanted messaging. One of the enforcement mechanisms is a **timelock restriction**. It is a temporary block that Meta places on a WhatsApp number that prevents it from messaging new contacts.
## What is a Timelock Restriction?
A timelock restriction is a temporary enforcement action imposed by Meta (WhatsApp's parent company) when it detects behavior that may violate its usage policies. When a number is under a timelock:
* **Messages to new contacts are blocked**: You cannot initiate conversations with phone numbers you haven't messaged before.
* **Existing conversations continue to work**: Numbers with an existing chat history can still send and receive messages normally.
* **The restriction is temporary**: It lasts for a specific duration (usually a few hours to several days) and is lifted automatically by Meta.
Hypersender **cannot** override or remove a timelock restriction. Only Meta controls when the restriction is lifted or applied.
## Types of Timelock Restrictions
Meta may apply different levels of restrictions depending on the severity of the detected behavior:
### Block New-Contact Outreach Only
The most common type. WhatsApp blocks your number from sending messages to new contacts, but your instance remains connected. You can:
* Continue messaging contacts with an existing chat history
* Receive incoming messages from anyone
* Use the main phone's WhatsApp app normally
### Disconnect and Block New-Contact Outreach
A more severe enforcement. In addition to blocking new-contact messages, Meta **disconnects your session** entirely. When this happens:
* Your instance is logged out and requires a fresh QR code scan to reconnect
* Messages to both new and existing contacts are blocked until you reconnect
* After the restriction period ends, you must scan the QR code again to resume use
## How Hypersender Helps You Manage Timelocks
When Meta places a timelock on your number, Hypersender detects it automatically and takes the following actions:
### Dashboard Warning Banner
A visible warning appears on your instance's connection page in the Hypersender dashboard, showing:
* **The type of restriction** applied
* **Remaining time** until the restriction is lifted (e.g., "2 days, 5 hours remaining")
* **The exact date and time** when the restriction ends
* Whether you'll need to **reconnect by scanning the QR code**
### Email Notification
You will receive an email notification explaining the restriction, what is blocked, and what your options are. You will receive at most one email per day while the restriction is active.
### API Error Guidance
When you attempt to send a message to a new contact while under a timelock, the API returns a clear error message explaining that a temporary restriction is in place and when it ends. Your application can handle it gracefully.
## What You Should Do During a Timelock
Timelocks are Meta's way of enforcing healthy messaging behavior. Use the restriction period to review your sending patterns.
1. **Continue messaging existing contacts**: Conversations with people who have previously messaged you or you have messaged before will still work.
2. **Use a different instance if urgent**: If you need to reach new contacts immediately, consider using another WhatsApp number connected to Hypersender.
3. **Let the restriction expire naturally**: Do not attempt to bypass or work around the restriction. This can lead to more severe enforcement.
4. **Review your sending practices**: Timelocks are often triggered by high-volume outreach to unknown numbers. Review our [guide on avoiding blocks](/v2/hypersender/overview/whatsapp/avoid-getting-blocked) and [number warm-up guide](/v2/hypersender/overview/whatsapp/warm-up-your-whatsapp-number).
## Preventing Future Timelocks
The best way to avoid timelock restrictions is to follow WhatsApp's guidelines for healthy messaging:
* **Warm up new numbers** gradually before sending at scale. See our [number warm-up guide](/v2/hypersender/overview/whatsapp/warm-up-your-whatsapp-number).
* **Let customers message you first** whenever possible. User-initiated conversations are much safer.
* **Maintain a healthy reply rate**: If few recipients respond, Meta may consider your messages unwanted.
* **Avoid sending to large lists of unknown numbers** in a short period.
* **Personalize your messages** and provide clear opt-out instructions.
Complete guide on how to avoid getting blocked on WhatsApp.
## Related
* [WhatsApp Message Capping: What It Is and How to Handle It](/v2/hypersender/overview/whatsapp/whatsapp-message-capping) covers the volume counterpart of a timelock, a per-cycle quota on new contacts.
* [How we handle WhatsApp timelock restrictions](https://hypersender.com/en/blog/how-we-handle-whatsapp-timelock-restrictions) on the Hypersender blog.
* [Hypersender dashboard](https://app.hypersender.com) to check your instances.
# Introduction
Source: https://docs.hypersender.com/v2/packages-and-sdks/index
Introduction to hypersender Packages and SDKs
The Hypersender Packages and SDKs provide a streamlined way to integrate Hypersender's capabilities into your applications. Whether you're looking to send messages, manage contacts, or utilize other features, our packages and SDKs make it easy to get started.
## Available Packages and SDKs
We offer a variety of packages and SDKs to suit different programming languages and platforms. Here are some of the available options:
* **Laravel SDK**: Great for web development and server-side scripting.
* **OTP with Laravel**: Send/validate codes and generate magic links over WhatsApp.
## Coming Soon...
* **JavaScript SDK**: Ideal for web applications and Node.js environments.
* **Python SDK**: Perfect for backend services and data processing tasks.
* **Go SDK**: Designed for high-performance applications and microservices.
# Installation
Source: https://docs.hypersender.com/v2/packages-and-sdks/laravel/installation
Step-by-step guide for installing and configuring the Hypersender PHP SDK in your Laravel application.
# Getting Started with Hypersender SDK
This guide will walk you through the process of installing and configuring the Hypersender PHP SDK for your Laravel application.
## Prerequisites
Before you begin, ensure you have the following:
* **PHP ^8.2 or higher:** The SDK requires PHP version 8.2 or higher to function properly.
* **Composer:** For package management and dependency resolution
* **Hypersender account:** Sign up at [Hypersender](https://app.hypersender.com) to obtain your API key and Instance ID.
You can find your API key and Instance ID in the Hypersender dashboard
![Hypersender Dashboard API Key]()
## Installation
Run the following command in your terminal to install the Hypersender PHP SDK:
```bash theme={null}
composer require hypersender/hypersender-laravel
```
After installation, you can verify the package is listed in your `composer.json` file.
Publish the configuration file using the following Artisan command:
```bash theme={null}
php artisan vendor:publish --tag=hypersender-config
```
This will create a `hypersender-config.php` configuration file in your `config` directory.
Open the `hypersender-config.php` configuration file, you'll find different options to set up the SDK to work with Whatsapp API, SMS API or both.
**`For WhatsApp API, set the following environment variables in your .env file:`**
```bash theme={null}
# API key from Hypersender dashboard
HYPERSENDER_WHATSAPP_API_KEY=
# Instance ID from Hypersender dashboard
HYPERSENDER_WHATSAPP_INSTANCE_ID=
# Webhook header authorization secret
HYPERSENDER_WHATSAPP_WEBHOOK_AUTHORIZATION_SECRET=
# Webhook route to receive incoming messages and status updates
HYPERSENDER_WHATSAPP_WEBHOOK_ROUTE=
# Job class to handle incoming webhook requests
# (use the default or create your own)
HYPERSENDER_WHATSAPP_WEBHOOK_JOB=
# The default queue for processing WhatsApp jobs
HYPERSENDER_WHATSAPP_QUEUE=default
```
Learn how to get the Hypersender whatsapp `API token` and `Instance ID` from Dashboard: [Demo Link](https://docs.hypersender.com/api-reference/whatsapp/how-to-send-whatsapp-message-in-postman).
**`For SMS API, set the following environment variables in your .env file:`**
```bash theme={null}
# API key from Hypersender dashboard
HYPERSENDER_SMS_API_KEY=
# Instance ID from Hypersender dashboard
HYPERSENDER_SMS_INSTANCE_ID=
# Webhook header authorization secret
HYPERSENDER_SMS_WEBHOOK_AUTHORIZATION_SECRET=
# Webhook route to receive incoming messages and status updates
HYPERSENDER_SMS_WEBHOOK_ROUTE=
# Job class to handle incoming webhook requests
# (use the default or create your own)
HYPERSENDER_SMS_WEBHOOK_JOB=
# The default queue for processing SMS jobs
HYPERSENDER_SMS_QUEUE=default
```
Learn how to get the Hypersender sms `API token` and `Instance ID` from Dashboard: [Demo Link](https://docs.hypersender.com/api-reference/sms/how-to-send-sms-message-in-postman).
**`For OTP API, set the following environment variables in your .env file:`**
```bash theme={null}
# Base URL for OTP API (keep default unless directed otherwise)
HYPERSENDER_OTP_BASE_URL=https://app.hypersender.com/api/otp/v2
# API key from Hypersender dashboard
HYPERSENDER_OTP_API_KEY=
# Instance ID from Hypersender dashboard
HYPERSENDER_OTP_INSTANCE_ID=
```
## You're all set!
You have successfully installed and configured the Hypersender PHP SDK in your Laravel application. You can now start using the SDK to send messages and manage your communications, check out the Usage Guide to learn more about how to use the SDK effectively.
* **WhatsApp:** [Usage Guide](/packages-and-sdks/laravel/whatsapp/send-messages)
* **SMS:** [Usage Guide](/packages-and-sdks/laravel/sms/send-messages)
# Heartbeat Management
Source: https://docs.hypersender.com/v2/packages-and-sdks/laravel/sms/heartbeat-management
List SMS phone heartbeats using Hypersender's Laravel Package
## Overview
Monitor and query your phone's heartbeats with Hypersender's Laravel SDK. This page shows how to list heartbeats with pagination, sorting, includes, and filters.
## Methods
### List Heartbeats
Index heartbeats of the phone sorted by last heartbeat. [(learn more)](/api-reference/sms/heartbeats/heartbeats)
```php theme={null}
use Hypersender\Hypersender;
$response = Hypersender::sms()->getHeartbeats();
```
```php theme={null}
use Hypersender\Hypersender;
$request = app(HeartbeatsIndexRequest::class, [
'perPage' => '50',
'page' => '1',
'sort' => '-created_at',
'include' => 'phone',
'filter' => [
'app_version' => '1.2.3',
'battery_level' => 87,
'is_charging' => true,
'local_timestamp' => '2025-01-20 14:30:00',
'created_at' => '2025-01-20 00:00:00..2025-01-21 00:00:00',
// other filters (check Parameters tab)
],
]);
$response = Hypersender::sms()->getHeartbeats($request);
```
| Parameter | Type | Required | Description |
| ------------------------- | ------ | -------- | ---------------------------------------------- |
| per\_page | int | no | Number of items per page (max 50) |
| page | int | no | Page number to retrieve |
| sort | string | no | Sort fields (e.g., `-created_at`) |
| include | string | no | Related resources to include (comma-separated) |
| filter\[app\_version] | string | no | Filter by app version |
| filter\[battery\_level] | int | no | Filter by battery level percentage |
| filter\[is\_charging] | bool | no | Filter by charging status |
| filter\[local\_timestamp] | string | no | Filter by device local timestamp or range |
| filter\[created\_at] | string | no | Filter by created\_at timestamp or range |
# Messages Management
Source: https://docs.hypersender.com/v2/packages-and-sdks/laravel/sms/send-messages
Full Guide to Sending and Managing SMS Messages using Hypersender's Laravel Package through your Android Phone
## Overview
The Send Message Module in Hypersender's Laravel SDK allows you to send and manage SMS messages programmatically. This guide provides a comprehensive overview of the available methods and how to use them effectively in your Laravel applications through your Android Phone.
## Methods
### Send SMS Message
Send a new SMS message to be sent by your android phone. [(learn more)](/api-reference/sms/messages/send-message)
```php theme={null}
use Hypersender\Hypersender;
Hypersender::sms()
->sendMessage(
content: 'Hello, this is a test message!',
requestId: 'e7b8a3c0-2d1a-4f9b-9f6c-1b2c3d4e5f6a',
to: '+1234567890',
// Optional parameters
// scheduleSendAt: '2025-01-01 12:00:00',
// maxSendAttempts: 3,
// messageExpirationSeconds: 120,
);
```
| Parameter | Type | Required | Description |
| ------------------------ | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| content | string | yes | The content of your SMS message |
| requestId | string | yes | A unique identifier you can later use to find this message (preferably a UUID) |
| to | string | yes | The recipient's phone number (e.g. +201234567890) |
| scheduleSendAt | string | no | Optional date-time to schedule sending (e.g. 2025-01-01 12:00:00). You can schedule up to 3 days ahead (relative to your phone timezone). |
| maxSendAttempts | int | no | How many times to retry sending if it fails. Max: 15. |
| messageExpirationSeconds | int | no | Message validity window in seconds (useful for OTPs, e.g. 120 for 2 minutes). |
### List Messages
Retrieve a paginated list of messages with powerful filtering. [(learn more)](/api-reference/sms/messages/index-messages)
```php theme={null}
use Hypersender\Hypersender;
$response = Hypersender::sms()->messages();
```
```php theme={null}
use Hypersender\Hypersender;
$request = app(MessagesIndexRequest::class, [
'perPage' => '50',
'page' => '2',
'sort' => '-updated_at',
'include' => 'thread',
'filter' => [
'request_id' => 'e7b8a3c0-2d1a-4f9b-9f6c-1b2c3d4e5f6a',
'status' => 'delivered',
// other filters (check Parameters tab)
],
]);
$response = Hypersender::sms()->messages($request);
```
| Parameter | Type | Required | Description |
| ---------------------------- | ------ | -------- | --------------------------------------------------------- |
| per\_page | int | no | Number of items per page (max 50) |
| page | int | no | Page number to retrieve |
| sort | string | no | Sort fields (e.g. `updated_at` or `-updated_at` for desc) |
| include | string | no | Related resources to include (comma-separated) |
| filter\[request\_id] | string | no | Filter by your custom request id |
| filter\[message\_thread\_id] | string | no | Filter by message thread id |
| filter\[from\_phone\_number] | string | no | Filter by sender phone number |
| filter\[to\_phone\_number] | string | no | Filter by recipient phone number |
| filter\[content] | string | no | Filter by message content (search) |
| filter\[status] | string | no | Filter by status (e.g. sent, delivered, failed, expired) |
| filter\[type] | string | no | Filter by message type |
| filter\[delivered\_at] | string | no | Filter by delivered\_at timestamp/range |
| filter\[received\_at] | string | no | Filter by received\_at timestamp/range |
| filter\[expired\_at] | string | no | Filter by expired\_at timestamp/range |
| filter\[failed\_at] | string | no | Filter by failed\_at timestamp/range |
| filter\[schedule\_send\_at] | string | no | Filter by scheduled send time |
| filter\[created\_at] | string | no | Filter by created\_at timestamp/range |
| filter\[updated\_at] | string | no | Filter by updated\_at timestamp/range |
### Delete Message
Delete a message by its ID. [(learn more)](/api-reference/sms/messages/delete-message)
```php theme={null}
use Hypersender\Hypersender;
Hypersender::sms()->deleteMessage(
messageId: 'msg_01HXYZABCDEF1234567'
);
```
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ------------------------------- |
| messageId | string | yes | The ID of the message to delete |
# Thread Management
Source: https://docs.hypersender.com/v2/packages-and-sdks/laravel/sms/thread-management
List, edit, and delete SMS message threads using Hypersender's Laravel Package
## Overview
Manage SMS message threads programmatically with Hypersender's Laravel SDK. This page covers listing threads with filters, editing archived status, and deleting threads.
## Methods
### List Message Threads
Index all message threads with pagination and filtering. [(learn more)](/api-reference/sms/message-threads/message-threads)
```php theme={null}
use Hypersender\Hypersender;
$response = Hypersender::sms()->messageThreads();
```
```php theme={null}
use Hypersender\Hypersender;
$request = app(MessageThreadsIndexRequest::class, [
'perPage' => '50',
'page' => '1',
'sort' => '-updated_at',
'include' => 'last_message',
'filter' => [
'last_message_content' => 'otp',
'is_archived' => false,
'last_message_id' => '9e03fc6b-ce90-4399-a472-6b029857e15b',
'from_or_to_number' => '+201234567890',
// other filters (check Parameters tab)
],
]);
$response = Hypersender::sms()->messageThreads($request);
```
| Parameter | Type | Required | Description |
| ------------------------------- | ------ | -------- | ------------------------------------------------------- |
| per\_page | int | no | Number of items per page (max 50) |
| page | int | no | Page number to retrieve |
| sort | string | no | Sort fields (default: `-updated_at`) |
| include | string | no | Related resources to include (comma-separated) |
| filter\[last\_message\_content] | string | no | Filter by the content of the last message in the thread |
| filter\[is\_archived] | bool | no | Filter by archived status |
| filter\[last\_message\_id] | string | no | Filter by the ID of the last message in the thread |
| filter\[from\_or\_to\_number] | string | no | Filter by phone number (either sender or recipient) |
### Edit Message Thread
Edit a message thread's archived status. [(learn more)](/api-reference/sms/message-threads/edit-message-thread)
```php theme={null}
use Hypersender\Hypersender;
Hypersender::sms()->editMessageThread(
isArchived: true,
messageThreadId: 'thread_01HXYZABCDEF1234567'
);
```
| Parameter | Type | Required | Description |
| --------------- | ------ | -------- | ----------------------------------------------- |
| isArchived | bool | yes | Whether the thread should be marked as archived |
| messageThreadId | string | yes | The ID of the message thread to edit |
### Delete Message Thread
Delete a message thread and all associated messages. [(learn more)](/api-reference/sms/message-threads/delete-message-thread)
```php theme={null}
use Hypersender\Hypersender;
Hypersender::sms()->deleteMessageThread(
messageThreadId: 'thread_01HXYZABCDEF1234567'
);
```
| Parameter | Type | Required | Description |
| --------------- | ------ | -------- | -------------------------------------- |
| messageThreadId | string | yes | The ID of the message thread to delete |
# Webhook Handling & Events
Source: https://docs.hypersender.com/v2/packages-and-sdks/laravel/sms/webhook-handling
Handle SMS webhooks and events using the Laravel SDK
## Overview
In this guide, we will cover how to handle incoming SMS webhooks and events using the Hypersender Laravel SDK. Webhooks are a powerful way to receive real-time updates from SMS, allowing your application to respond to messages, status changes, and other events as they happen.
### Setting Up Webhooks
1. The package auto-registers a POST route (default /sms/webhook).
2. Verifies the signature using the secret in config/env.
3. Dispatches a dedicated Laravel event for each webhook event type (e.g., MessagesUpserted, GroupsUpdated, etc.).
4. Listen for events in your app:
```php theme={null}
use Hypersender\Events\Sms\MessagePhoneSent;
Event::listen(MessagePhoneSent::class, function ($event) {
$event->payload
});
```
See the Webhook Usage in it's dedicated section for more details [webhook usage](/api-reference/sms-webhooks/introduction).
### Available Webhook Events
The following events are available for handling sms webhooks:
* `Hypersender\Events\Sms\MessagePhoneSent`
* `Hypersender\Events\Sms\MessageCallMissed`
* `Hypersender\Events\Sms\MessageNotificationScheduled`
* `Hypersender\Events\Sms\MessagePhoneDelivered`
* `Hypersender\Events\Sms\MessagePhoneReceived`
* `Hypersender\Events\Sms\MessageSendExpired`
* `Hypersender\Events\Sms\MessageSendFailed`
* `Hypersender\Events\Sms\PhoneHeartbeatDisabled`
* `Hypersender\Events\Sms\PhoneHeartbeatOnline`
* `Hypersender\Events\Sms\PhoneHeartbeatOffline`
* `Hypersender\Events\Sms\PhoneHeartbeatMissed`
* `Hypersender\Events\Sms\PhoneHeartbeatReceived`
### Customizing the Webhook Route
To customize the webhook route, you can publish the package's configuration file and modify the `webhook_route` setting:
```bash theme={null}
php artisan vendor:publish --tag="hypersender-config"
```
Then, update the `sms_webhook_route` in `config/hypersender-config.php`:
```php theme={null}
'sms_webhook_route' => 'your/custom/route',
```
# Chat Status
Source: https://docs.hypersender.com/v2/packages-and-sdks/laravel/whatsapp/chat-status
Indicate typing status in chats with the Laravel SDK (start typing, stop typing)
## Overview
Use these methods to show or hide typing indicators in a WhatsApp chat.
## How to avoid getting blocked
We highly recommend reading our full guide on [How to Avoid Getting Blocked on WhatsApp](/hypersender/overview/whatsapp/avoid-getting-blocked) to ensure your usage complies with WhatsApp's policies and best practices, and see how to leverage these two methods effectively without risking your number being blocked.
### Start Typing
Indicate that the user is typing in a chat. [(learn more)](/api-reference/whatsapp/send-messages/start-typing)
```php theme={null}
use Hypersender\Hypersender;
Hypersender::whatsapp()
->startTyping(
chatId: '20123456789@c.us',
);
```
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | --------------------------------- |
| chatId | string | yes | The chat ID to indicate typing in |
### Stop Typing
Indicate that the user has stopped typing in a chat. [(learn more)](/api-reference/whatsapp/send-messages/stop-typing)
```php theme={null}
use Hypersender\Hypersender;
Hypersender::whatsapp()
->stopTyping(
chatId: '20123456789@c.us',
);
```
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | --------------------------------- |
| chatId | string | yes | The chat ID to indicate typing in |
# Message Management
Source: https://docs.hypersender.com/v2/packages-and-sdks/laravel/whatsapp/message-management
Control and interact with messages after they've been sent in WhatsApp using the Laravel SDK
## Overview
Manage sent messages programmatically: react, star, delete, forward, mark as seen, and read chat history.
### React to Message
React to a WhatsApp message with an emoji. [(learn more)](/api-reference/whatsapp/send-messages/react-to-message)
```php theme={null}
use Hypersender\Hypersender;
Hypersender::whatsapp()
->reactToMessage(
messageId: 'true_111111111111@c.us_3EB08F6AD2A432386EFA0E',
reaction: '🥵',
);
```
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | -------------------------------------- |
| messageId | string | yes | The ID of the message to react to |
| reaction | string | yes | The emoji or Unicode reaction to apply |
Set `reaction` parameter to an empty string to remove an existing reaction from a message.
### Star Message
Star or unstar a specific message.
```php theme={null}
use Hypersender\Hypersender;
Hypersender::whatsapp()
->star(
chatId: '20123456789@c.us',
messageId: 'true_111111111111@c.us_3EB08F6AD2A432386EFA0E',
star: true,
);
```
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ---------------------------------------------- |
| chatId | string | yes | The WhatsApp chat ID that contains the message |
| messageId | string | yes | The ID of the message to star/unstar |
| star | bool | yes | true to star the message, false to unstar |
By default, messages are unstarred. Set `star` to `true` to star a message.
or set it to `false` to unstar.
### Delete Message
Delete a message from a chat. [(learn more)](/api-reference/whatsapp/send-messages/delete-message)
```php theme={null}
use Hypersender\Hypersender;
Hypersender::whatsapp()
->deleteMessage(
chatId: '20123456789@c.us',
messageId: 'true_111111111111@c.us_3EB08F6AD2A432386EFA0E',
);
```
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ---------------------------------------------- |
| chatId | string | yes | The WhatsApp chat ID that contains the message |
| messageId | string | yes | The ID of the message to delete |
### Forward Message
Forward a message to another chat. [(learn more)](/api-reference/whatsapp/send-messages/forward-message)
```php theme={null}
use Hypersender\Hypersender;
Hypersender::whatsapp()
->forwardMessage(
chatId: '20123456789@c.us',
messageId: 'true_111111111111@c.us_3EB08F6AD2A432386EFA0E',
);
```
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ------------------------------------------------- |
| chatId | string | yes | The destination chat ID to forward the message to |
| messageId | string | yes | The ID of the message to forward |
### Send Seen
Mark a message as seen (read). For group messages, provide the participant JID.
```php theme={null}
use Hypersender\Hypersender;
Hypersender::whatsapp()
->sendSeen(
chatId: '20123456789@c.us',
messageId: 'true_111111111111@c.us_3EB08F6AD2A432386EFA0E',
participant: null, // e.g. '20123456789@c.us' for group messages
);
```
| Parameter | Type | Required | Description |
| ----------- | ------ | -------- | ------------------------------------- |
| chatId | string | yes | The chat ID that contains the message |
| messageId | string | yes | The message ID to mark as seen |
| participant | string | no | Participant JID for group messages |
### Read Chat
Read a chat history window and optionally mark recent messages as read. [(learn more)](/api-reference/whatsapp/send-messages/read-chat)
```php theme={null}
use Hypersender\Hypersender;
Hypersender::whatsapp()
->readChat(
chatId: '20123456789@c.us',
messages: 20,
days: null,
);
```
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ------------------------------------------------ |
| chatId | string | yes | The chat ID to read |
| messages | int | no | Number of latest messages to read (latest first) |
| days | int | no | Number of latest days to read (latest first) |
# WhatsApp Webhook Job
Source: https://docs.hypersender.com/v2/packages-and-sdks/laravel/whatsapp/overriding-webhook-job
How to override the default WhatsApp webhook job in Hypersender Laravel SDK.
# Overview
This page explains how Hypersender handles incoming WhatsApp webhooks, the default job that processes them, and how to register your own job class.
## How it works
The incoming webhook hits your app on the route configured at `hypersender-config.whatsapp_webhook_route` (default: `whatsapp/webhook`).
`Hypersender\Http\Controllers\WhatsappWebhookController` resolves the job class from config and dispatches it:
* Config key: `hypersender-config.whatsapp_webhook_job`
* The controller validates:
* The class exists and is a string
* The class implements `Hypersender\Contracts\WhatsappWebhookJobInterface`
* The controller dispatches the job with two named arguments:
* `payload: $request->payload()`
* `secret: $request->secret()`
Because the controller uses named arguments, your job’s constructor must accept parameters named `payload` and `secret`.
## The default job
Out of the box, the package ships with `Hypersender\Jobs\ProcessWhatsappWebhookJob`, which implements the interface `Hypersender\Contracts\WhatsappWebhookJobInterface`.
### Key details
```php theme={null}
public function __construct(
public array $payload,
public ?string $secret = null
) { }
```
If `hypersender-config.whatsapp_queue` is set, the job is queued there.
Validates the `event` field and dispatches an application event via `WhatsappWebhookEventEnum` mapping.
## Using your own job class
You can replace the default job with your own implementation. Follow these steps:
Your job must implement `Hypersender\Contracts\WhatsappWebhookJobInterface` (a marker interface). This is enforced by the controller.
Your job’s constructor must accept the same named parameters that the controller provides:
```php theme={null}
use Hypersender\Contracts\WhatsappWebhookJobInterface;
use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Bus\Dispatchable;
use Illuminate\Queue\InteractsWithQueue;
use Illuminate\Queue\SerializesModels;
namespace App\Jobs;
class MyWhatsappWebhookJob implements ShouldQueue, WhatsappWebhookJobInterface
{
use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;
public function __construct(public array $payload, public ?string $secret = null)
{
// Optional: route to a specific queue
if ($queue = config('hypersender-config.whatsapp_queue')) {
$this->onQueue($queue);
}
}
public function handle(): void
{
// Your custom processing logic here
// $this->payload contains the webhook body
// $this->secret contains the Authorization secret (if sent)
}
}
```
You can register it either in your config or via environment variable.
* Via `.env`:
```env theme={null}
HYPERSENDER_WHATSAPP_WEBHOOK_JOB=App\Jobs\MyWhatsappWebhookJob
```
* Or by publishing/editing the config `config/hypersender-config.php`:
```php theme={null}
'whatsapp_webhook_job' => env('HYPERSENDER_WHATSAPP_WEBHOOK_JOB', App\Jobs\MyWhatsappWebhookJob::class),
```
Make sure the class is autoloadable and available to your app (e.g., in `app/Jobs`).
## Can I use my own interface?
Yes! your job class can implement any additional interfaces you want for your own architecture. However, the package still requires your job to implement `Hypersender\\Contracts\\WhatsappWebhookJobInterface` because the controller enforces this at runtime. Swapping out that required interface via configuration is not supported. If you need to enforce your own contract, simply implement both interfaces on your job class.
## Related configuration
* API key: `HYPERSENDER_WHATSAPP_API_KEY`
* Instance ID: `HYPERSENDER_WHATSAPP_INSTANCE_ID`
* Webhook Authorization secret: `HYPERSENDER_WHATSAPP_WEBHOOK_AUTHORIZATION_SECRET`
* Webhook route: `HYPERSENDER_WHATSAPP_WEBHOOK_ROUTE` (defaults to `whatsapp/webhook`)
* Webhook job: `HYPERSENDER_WHATSAPP_WEBHOOK_JOB` (defaults to `Hypersender\Jobs\ProcessWhatsappWebhookJob`)
* Queue name: `HYPERSENDER_WHATSAPP_QUEUE` (defaults to `default`)
## Validation rules enforced by the controller
If the configured job class is invalid, the controller aborts the request with HTTP `500`:
* Not a string or class does not exist
* Does not implement `Hypersender\Contracts\WhatsappWebhookJobInterface`
## Payload expectations
The default job expects an `event` string at `payload['event']`. If it is missing or not a string, the default job will report and fail the job. If you write a custom job, you can apply your own validation.
## Quick checklist
* Custom job implements `Hypersender\Contracts\WhatsappWebhookJobInterface`
* Constructor signature matches the named args: `__construct(array $payload, ?string $secret = null)`
* `HYPERSENDER_WHATSAPP_WEBHOOK_JOB` is set (or config updated)
* Optional: set `HYPERSENDER_WHATSAPP_QUEUE` to route jobs to a specific queue
## Troubleshooting
* 500 error on webhook: Ensure the configured job class exists and implements `WhatsappWebhookJobInterface`.
* Constructor argument mismatch: Because dispatch uses named args, your constructor parameter names must be exactly `payload` and `secret`.
* Queue not used: Verify `HYPERSENDER_WHATSAPP_QUEUE` (or config) and that your job calls `$this->onQueue(...)` in the constructor (or elsewhere) if you want to force a specific queue.
## TL;DR
* Default job: `Hypersender\Jobs\ProcessWhatsappWebhookJob` implements `Hypersender\Contracts\WhatsappWebhookJobInterface` and is used by default.
* Bring your own: Create a job that implements the interface, accepts `payload` and `secret` in the constructor, and register it via `HYPERSENDER_WHATSAPP_WEBHOOK_JOB` or in `config/hypersender-config.php`.
# Queued Requests
Source: https://docs.hypersender.com/v2/packages-and-sdks/laravel/whatsapp/queued-requests
Check the status and response of queued API requests in the V2 WhatsApp API
## Overview
In V2, all API requests are processed through a queued system for improved reliability and performance. When you make any API request (send message, react, etc.), you receive an immediate response with a `queued_request_uuid`. Use this method to check the actual response of your queued request.
Learn more about the V2 queued request system in the [Queued Requests Documentation](/v2/api-reference/whatsapp/queued-requests).
## Get Queued Request
Retrieve the status and response of a queued API request using its UUID.
```php theme={null}
use Hypersender\Hypersender;
$response = Hypersender::whatsapp()
->getQueuedRequest(
uuid: 'a0816120-7e37-4e8b-8cf3-92deb2cdc133',
);
// Check if the request is completed
$data = $response->json();
if ($data['response_status'] !== null) {
// Request completed
echo "Status: " . $data['response_status'];
echo "Response: " . json_encode($data['response_body']);
} else {
// Still processing
echo "Request is still being processed...";
}
```
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ------------------------------------------ |
| uuid | string | yes | The UUID of the queued request to retrieve |
```json theme={null}
{
"uuid": "a0816120-7e37-4e8b-8cf3-92deb2cdc133",
"request": {
"chatId": "111111111111@c.us",
"text": "Hello world!"
},
"response_status": 200,
"response_body": {
"message_id": "AAAAAA0000BBBBB00CCCCCC"
},
"response_header": {}
}
```
The `response_status`, `response_body`, and `response_header` will be `null` while the request is still being processed.
## Response Fields
| Field | Type | Description |
| ----------------- | --------------- | --------------------------------------------------------------------------------------------------------------- |
| `uuid` | string | The unique identifier for this queued request |
| `request` | object | The original request payload you submitted |
| `response_status` | integer \| null | HTTP status code of the processed request. `null` while still processing |
| `response_body` | object \| null | The actual API response. Contains message details on success, error details on failure. `null` while processing |
| `response_header` | object \| null | Response headers from the processed request. `null` while processing |
## Polling Example
If you need to wait for a request to complete, you can implement polling with exponential backoff:
```php theme={null}
use Hypersender\Hypersender;
function waitForCompletion(string $uuid, int $maxAttempts = 10): array
{
$attempt = 0;
while ($attempt < $maxAttempts) {
$response = Hypersender::whatsapp()
->getQueuedRequest(uuid: $uuid);
$data = $response->json();
if ($data['response_status'] !== null) {
return $data; // Request completed
}
// Exponential backoff: 100ms, 200ms, 400ms, 800ms...
usleep(100000 * pow(2, $attempt));
$attempt++;
}
throw new \Exception('Request did not complete in time');
}
// Usage
$sendResponse = Hypersender::whatsapp()
->safeSendTextMessage(
chat_id: '20123456789@c.us',
text: 'Hello!',
);
$uuid = $sendResponse->json()['queued_request_uuid'];
$result = waitForCompletion($uuid);
if ($result['response_status'] === 200) {
echo "Message sent! ID: " . $result['response_body']['message_id'];
} else {
echo "Failed with status: " . $result['response_status'];
}
```
For production applications, consider using webhooks instead of polling to receive real-time notifications when messages are sent, delivered, or fail.
# Send Messages
Source: https://docs.hypersender.com/v2/packages-and-sdks/laravel/whatsapp/send-messages
Full methods guide to sending various types of messages and managing message interactions via WhatsApp
## Overview
The Send Message module provides comprehensive methods for sending various message types, managing interactions, and controlling chat on WhatsApp. Build engaging, feature-rich messaging experiences with safe sending options, link previews, and more.
## Text Methods
Send various types of content to engage your audience with multimedia and interactive elements.
### Safe Send Text Message
Safely send a WhatsApp text message with human-like pacing. [(learn more)](/api-reference/whatsapp/send-messages/send-text-safe)
```php theme={null}
use Hypersender\Hypersender;
Hypersender::whatsapp()
->safeSendTextMessage(
chat_id: '20123456789@c.us',
text: 'Hello from Laravel package!',
);
```
| Parameter | Type | Required | Description |
| ---------------------------- | ------ | -------- | ------------------------------------------- |
| chat\_id | string | yes | The WhatsApp number to send the message to |
| text | string | yes | The message content to send |
| reply\_to | bool | no | Whether to reply to the message |
| link\_preview | bool | no | Whether to show a link preview |
| link\_preview\_high\_quality | bool | no | Whether to show a high-quality link preview |
### Send Text Message
Send plain text messages with link preview (optional) [(learn more)](/api-reference/whatsapp/send-messages/send-text)
We highly recommend using the [`send-text-safe`](/api-reference/whatsapp/send-messages/send-text-safe) endpoint for regular messaging operations to maintain a more natural communication pattern, and keep your whatsapp number safe from being blocked.
```php theme={null}
use Hypersender\Hypersender;
Hypersender::whatsapp()
->sendText(
chat_id: '20123456789@c.us',
text: 'Hello from Laravel package!',
);
```
| Parameter | Type | Required | Description |
| ---------------------------- | ------ | -------- | ------------------------------------------- |
| chat\_id | string | yes | The WhatsApp number to send the message to |
| text | string | yes | The message content to send |
| reply\_to | bool | no | Whether to reply to the message |
| link\_preview | bool | no | Whether to show a link preview |
| link\_preview\_high\_quality | bool | no | Whether to show a high-quality link preview |
### Send Image Message
Send images to WhatsApp users via URL or file upload. [(learn more)](/api-reference/whatsapp/send-messages/send-image)
```php theme={null}
use Hypersender\Hypersender;
Hypersender::whatsapp()
->sendImageUrl(
chat_id: '20123456789@c.us',
url: 'https://hypersender.com',
fileName: 'image.jpeg',
mimetype: 'image/jpeg',
caption: 'Check out this image!',
reply_to: 'string',
);
```
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ------------------------------------------ |
| chat\_id | string | yes | The WhatsApp number to send the message to |
| url | string | yes | The URL of the image to send |
| fileName | string | yes | The name of the file to send |
| mimetype | string | yes | The MIME type of the file to send |
| caption | string | no | The caption for the image |
| reply\_to | bool | no | Whether to reply to the message |
```php theme={null}
use Hypersender\Hypersender;
use Illuminate\Http\File;
Hypersender::whatsapp()
->sendImageFile(
chat_id: '20123456789@c.us',
file: new File('/path/to/image.jpeg'),
fileName: 'image.jpeg',
mimetype: 'image/jpeg',
caption: 'Check out this image!',
reply_to: 'string',
);
```
| Parameter | Type | Required | Description |
| --------- | --------------------- | -------- | ------------------------------------------ |
| chat\_id | string | yes | The WhatsApp number to send the message to |
| file | \Illuminate\Http\File | yes | The image file to send |
| fileName | string | yes | The name of the file to send |
| mimetype | string | yes | The MIME type of the file to send |
| caption | string | no | The caption for the image |
| reply\_to | bool | no | Whether to reply to the message |
### Send Video Message
Send videos to WhatsApp users via URL or file upload. [(learn more)](/api-reference/whatsapp/send-messages/send-video)
```php theme={null}
use Hypersender\Hypersender;
Hypersender::whatsapp()
->sendVideoUrl(
chat_id: '20123456789@c.us',
url: 'https://example.com/video.mp4',
asNote: false,
caption: 'Check out this video!',
reply_to: 'string',
);
```
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ------------------------------------------ |
| chat\_id | string | yes | The WhatsApp number to send the message to |
| url | string | yes | The URL of the video to send |
| asNote | bool | yes | Whether to send the video as a note |
| caption | string | no | The caption for the video |
| reply\_to | bool | no | Whether to reply to the message |
```php theme={null}
use Hypersender\Hypersender;
use Illuminate\Http\File;
Hypersender::whatsapp()
->sendVideoFile(
chat_id: '20123456789@c.us',
file: new File('/path/to/video.mp4'),
asNote: false,
caption: 'Check out this video!',
reply_to: 'string',
);
```
| Parameter | Type | Required | Description |
| --------- | --------------------- | -------- | ------------------------------------------ |
| chat\_id | string | yes | The WhatsApp number to send the message to |
| file | \Illuminate\Http\File | yes | The video file to send |
| asNote | bool | yes | Whether to send the video as a note |
| caption | string | no | The caption for the video |
| reply\_to | bool | no | Whether to reply to the message |
You can send videos only in mp4 formats - so make sure the url contains the correct extension
Max allowed file size is `20MB`.
### Send Voice Message
Send voice messages to WhatsApp users via URL or file upload. [(learn more)](/api-reference/whatsapp/send-messages/send-voice)
```php theme={null}
use Hypersender\Hypersender;
Hypersender::whatsapp()
->sendVoiceUrl(
chat_id: '20123456789@c.us',
url: 'https://example.com/audio.opus',
caption: 'Check out this audio!',
reply_to: 'string',
);
```
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ------------------------------------------ |
| chat\_id | string | yes | The WhatsApp number to send the message to |
| url | string | yes | The URL of the audio to send |
| caption | string | no | The caption for the audio |
| reply\_to | bool | no | Whether to reply to the message |
```php theme={null}
use Hypersender\Hypersender;
use Illuminate\Http\File;
Hypersender::whatsapp()
->sendVoiceFile(
chat_id: '20123456789@c.us',
file: new File('/path/to/audio.opus'),
caption: 'Check out this audio!',
reply_to: 'string',
);
```
| Parameter | Type | Required | Description |
| --------- | --------------------- | -------- | ------------------------------------------ |
| chat\_id | string | yes | The WhatsApp number to send the message to |
| file | \Illuminate\Http\File | yes | The audio file to send |
| caption | string | no | The caption for the audio |
| reply\_to | bool | no | Whether to reply to the message |
### Send Location Message
Send location messages to WhatsApp users. [(learn more)](/api-reference/whatsapp/send-messages/send-location)
```php theme={null}
use Hypersender\Hypersender;
Hypersender::whatsapp()
->sendLocation(
chat_id: '20123456789@c.us',
latitude: '37.7749',
longitude: '-122.4194',
title: 'San Francisco',
reply_to: 'string',
);
```
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ------------------------------------------ |
| chat\_id | string | yes | The WhatsApp number to send the message to |
| latitude | string | yes | The latitude of the location to send |
| longitude | string | yes | The longitude of the location to send |
| title | string | no | The title of the location |
| reply\_to | bool | no | Whether to reply to the message |
### Send Poll Message
Send poll messages to WhatsApp users. [(learn more)](/api-reference/whatsapp/send-messages/send-poll)
```php theme={null}
use Hypersender\Hypersender;
Hypersender::whatsapp()
->sendPoll(
chat_id: '20123456789@c.us',
reply_to: 'string',
poll: [
'name' => 'Sample Poll',
'options' => [
'Option 1',
'Option 2',
'Option 3'
],
'multipleAnswers' => true
]
);
```
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ------------------------------------------------------------- |
| chat\_id | string | yes | The WhatsApp number to send the message to |
| reply\_to | bool | no | Whether to reply to the message |
| poll | array | yes | The poll object containing name, options, and multipleAnswers |
### Send Link Custom Preview
Send a text message with a custom link preview. [(learn more)](/api-reference/whatsapp/send-messages/send-link-custom-preview)
```php theme={null}
use Hypersender\Hypersender;
Hypersender::whatsapp()
->sendLinkCustomPreviewUrl(
chatId: '20123456789@c.us',
text: 'Check this out: https://example.com',
replyTo: null,
highQuality: true,
previewTitle: 'Example Title',
previewDescription: 'A short description for the preview card',
previewUrl: 'https://example.com',
previewImageUrl: 'https://example.com/image.jpg',
);
```
| Parameter | Type | Required | Description |
| ------------------ | ------ | -------- | ------------------------------------------- |
| chatId | string | yes | The WhatsApp chat ID to send the message to |
| text | string | yes | The message text (can include a link) |
| replyTo | string | no | Message ID to reply to |
| highQuality | bool | no | Whether to use high-quality preview images |
| previewTitle | string | yes | Title to display in the link preview |
| previewDescription | string | yes | Description to display in the link preview |
| previewUrl | string | yes | Link URL for the preview card |
| previewImageUrl | string | yes | Direct URL to the preview image |
```php theme={null}
use Hypersender\Hypersender;
use Illuminate\Http\UploadedFile;
Hypersender::whatsapp()
->sendLinkCustomPreviewFile(
chatId: '20123456789@c.us',
text: 'Check this out: https://example.com',
replyTo: null,
highQuality: true,
previewTitle: 'Example Title',
previewDescription: 'A short description for the preview card',
previewUrl: 'https://example.com',
previewImageFile: new UploadedFile('/path/to/image.jpg', 'image.jpg', 'image/jpeg'),
);
```
| Parameter | Type | Required | Description |
| ------------------ | ----------------------------- | -------- | ------------------------------------------- |
| chatId | string | yes | The WhatsApp chat ID to send the message to |
| text | string | yes | The message text (can include a link) |
| replyTo | string | no | Message ID to reply to |
| highQuality | bool | no | Whether to use high-quality preview images |
| previewTitle | string | yes | Title to display in the link preview |
| previewDescription | string | yes | Description to display in the link preview |
| previewUrl | string | yes | Link URL for the preview card |
| previewImageFile | \Illuminate\Http\UploadedFile | yes | The preview image file to upload |
### Send File Message
Send any file type via URL or file upload. [(learn more)](/api-reference/whatsapp/send-messages/send-file)
```php theme={null}
use Hypersender\Hypersender;
Hypersender::whatsapp()
->sendFileUrl(
chatId: '20123456789@c.us',
url: 'https://example.com/files/report.pdf',
fileName: 'report.pdf',
mimeType: 'application/pdf',
caption: 'Monthly report',
replyTo: null,
);
```
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ---------------------------------------- |
| chatId | string | yes | The WhatsApp chat ID to send the file to |
| url | string | yes | Direct URL of the file to send |
| fileName | string | no | File name to display to the recipient |
| mimeType | string | no | MIME type of the file |
| caption | string | no | Optional caption for the file |
| replyTo | string | no | Message ID to reply to |
```php theme={null}
use Hypersender\Hypersender;
use Illuminate\Http\UploadedFile;
Hypersender::whatsapp()
->sendFile(
chatId: '20123456789@c.us',
file: new UploadedFile('/path/to/file.pdf', 'file.pdf', 'application/pdf'),
fileName: 'file.pdf',
mimeType: 'application/pdf',
caption: 'See attached file',
replyTo: null,
);
```
| Parameter | Type | Required | Description |
| --------- | ----------------------------- | -------- | ---------------------------------------- |
| chatId | string | yes | The WhatsApp chat ID to send the file to |
| file | \Illuminate\Http\UploadedFile | yes | The file to upload and send |
| fileName | string | no | File name to display to the recipient |
| mimeType | string | no | MIME type of the file |
| caption | string | no | Optional caption for the file |
| replyTo | string | no | Message ID to reply to |
### Send Contact Card
Send contact cards (vCard) to WhatsApp users. [(learn more)](/api-reference/whatsapp/send-messages/send-contact-card)
```php theme={null}
use Hypersender\Hypersender;
Hypersender::whatsapp()
->sendContactCard(
chatId: '20123456789@c.us',
contacts: [
[
'vcard' => "BEGIN:VCARD\nVERSION:3.0\nFN:John Doe\nORG:Acme Inc\nTEL;type=CELL:+12025550123\nEND:VCARD",
'fullName' => 'John Doe',
'organization' => 'Acme Inc',
'phoneNumber' => '12025550123',
'whatsappId' => '12025550123@c.us',
],
],
);
```
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ------------------------------------------------ |
| chatId | string | yes | The WhatsApp chat ID to send the contact card to |
| contacts | array | yes | Array of contact objects (see note below) |
Each contact supports: `vcard`, `fullName`, `organization`, `phoneNumber`, `whatsappId`.
You can send one or multiple contacts in a single message by including multiple items in the `contacts` array.
# Webhook Handling & Events
Source: https://docs.hypersender.com/v2/packages-and-sdks/laravel/whatsapp/webhook-handling
Handle WhatsApp webhooks and events using the Laravel SDK
## Overview
In this guide, we will cover how to handle incoming WhatsApp webhooks and events using the Hypersender Laravel SDK. Webhooks are a powerful way to receive real-time updates from WhatsApp, allowing your application to respond to messages, status changes, and other events as they happen.
### Setting Up Webhooks
1. The package auto-registers a POST route (default /whatsapp/webhook).
2. Verifies the signature using the secret in config/env.
3. Dispatches a dedicated Laravel event for each webhook event type (e.g., MessagesUpserted, GroupsUpdated, etc.).
4. Listen for events in your app:
```php theme={null}
use Hypersender\Events\Whatsapp\PresenceUpdate;
Event::listen(PresenceUpdate::class, function ($event) {
$event->payload
});
```
See the Webhook Usage in it's dedicated section for more details [webhook usage](/api-reference/whatsapp-webhooks/introduction).
### Available Webhook Events
The following events are available for handling WhatsApp webhooks:
* `Hypersender\Events\Whatsapp\PresenceUpdate`
* `Hypersender\Events\Whatsapp\MessagesAny`
* `Hypersender\Events\Whatsapp\MessageReaction`
* `Hypersender\Events\Whatsapp\MessagesAck`
* `Hypersender\Events\Whatsapp\MessagesWaiting`
* `Hypersender\Events\Whatsapp\MessagesRevoked`
* `Hypersender\Events\Whatsapp\PollVote`
* `Hypersender\Events\Whatsapp\PollVoteFailed`
### Customizing the Webhook Route
To customize the webhook route, you can publish the package's configuration file and modify the `webhook_route` setting:
```bash theme={null}
php artisan vendor:publish --tag="hypersender-config"
```
Then, update the `whatsapp_webhook_route` in `config/hypersender-config.php`:
```php theme={null}
'whatsapp_webhook_route' => 'your/custom/route',
```
# Generate OTP Link
Source: https://docs.hypersender.com/v2/packages-and-sdks/laravel/otp/generate-link
Create WhatsApp magic links for passwordless authentication in Laravel.
Create a passwordless flow: generate a WhatsApp link that pre-fills a message with a unique code. When the user taps **Send** in WhatsApp, you get the verification event via callbacks. Use the Laravel SDK method to keep things concise.
## Parameters
| Field | Type | Required | Description |
| ---------------- | ------ | -------- | ----------------------------------------------------------- |
| expires | int | no | TTL in seconds (default `1800`). |
| name | string | no | Your app name displayed in messages. |
| message.prompt | string | yes | Text pre-filled in the WhatsApp link. |
| message.success | string | yes | Reply when verification succeeds. Use `{link}` placeholder. |
| message.failed | string | yes | Reply when verification fails. |
| message.expired | string | yes | Reply when the link expired. |
| callback.success | string | no | Webhook URL for successful verification. |
| callback.failed | string | no | Webhook URL for failed verification. |
## Generate the link
```php theme={null}
use Hypersender\Hypersender;
$response = Hypersender::otp()->generateLink([
'expires' => 900,
'name' => 'YourApp',
'message' => [
'prompt' => 'Give me link to login at YourApp',
'success' => 'Welcome! Here is your login link: {link}',
'failed' => 'Login failed. Please try again.',
'expired' => 'This link expired. Request a new one.',
],
'callback' => [
'success' => 'https://yourdomain.com/api/otp/success',
'failed' => 'https://yourdomain.com/api/otp/failed',
],
]);
$whatsappLink = $response['whatsapp_link'] ?? null;
```
Send `whatsappLink` via email, SMS, or in-app notification. When the user clicks it, WhatsApp opens with the prompt + code. Handle callbacks to finalize the login.
Secure your callback endpoints (HTTPS + auth) and invalidate links after use.
![Send OTP Link Code]()
# OTP with Laravel
Source: https://docs.hypersender.com/v2/packages-and-sdks/laravel/otp/overview
Send OTP codes and magic links via Hypersender using Laravel.
Use the Hypersender OTP service from Laravel to send verification codes or passwordless links over WhatsApp (and SMS for codes), then validate user submissions securely using the packaged SDK methods.
## What you can do
* **Request OTP codes**: Generate a one-time code and deliver it over WhatsApp.
* **Validate codes**: Check user-entered codes against the active OTP.
* **Generate magic links**: Create WhatsApp links that complete verification without typing.
## Prerequisites
* Laravel app with the Hypersender Laravel package installed ([Installation](/v2/packages-and-sdks/laravel/installation)).
* Hypersender **API token** and **Instance UUID** from the dashboard.
* Laravel HTTP client available (`Illuminate\\Support\\Facades\\Http`).
## Base URL and auth
```bash theme={null}
Base URL: https://app.hypersender.com/api/otp/v2
Auth: Authorization: Bearer YOUR_API_TOKEN
Instance: X-Instance-UUID: YOUR_INSTANCE_UUID
```
## Quick start (request and validate)
```php theme={null}
use Hypersender\Hypersender;
// 1) Send a code
$request = Hypersender::otp()->requestCode([
'chatId' => '20123456789@c.us', // WhatsApp chat ID
'length' => 6,
'useLetter' => false,
'useNumber' => true,
'name' => 'YourApp',
'expires' => 300,
]);
// 2) Validate it later
$validation = Hypersender::otp()->validateCode([
'chatId' => $request['chat_id'] ?? '20123456789@c.us',
'code' => $request['code'] ?? '123456',
]);
```
Keep tokens and OTP codes out of logs. Use HTTPS for all calls.
## Next steps
* [Request OTP Code](/v2/packages-and-sdks/laravel/otp/request-code)
* [Validate OTP Code](/v2/packages-and-sdks/laravel/otp/validate-code)
* [Generate OTP Link](/v2/packages-and-sdks/laravel/otp/generate-link)
# Request OTP Code
Source: https://docs.hypersender.com/v2/packages-and-sdks/laravel/otp/request-code
Generate and send an OTP code from Laravel using Hypersender.
Generate a one-time password and deliver it to a WhatsApp user using the Laravel SDK. The response includes the OTP `uuid`, generated `code`, status, and expiry time so you can track validation.
## Parameters
| Field | Type | Required | Description |
| ---------- | ------ | -------- | ------------------------------------------------------------- |
| chatId | string | yes | WhatsApp chat ID of the recipient (e.g., `20123456789@c.us`). |
| length | int | no | Code length (default `6`). |
| useLetter | bool | no | Include letters (default `false`). |
| useNumber | bool | no | Include numbers (default `true`). |
| allCapital | bool | no | Uppercase letters when `useLetter` is true (default `false`). |
| name | string | no | Display name inside the message (e.g., your app name). |
| expires | int | no | TTL in seconds (default `1800`). |
## Send the request
```php theme={null}
use Hypersender\Hypersender;
$otp = Hypersender::otp()->requestCode([
'chatId' => '20123456789@c.us',
'length' => 6,
'useLetter' => false,
'useNumber' => true,
'allCapital' => false,
'name' => 'YourApp',
'expires' => 900,
]);
```
* Store `uuid` if you plan to track or audit the request.
* Use `status` to monitor the send/validation lifecycle (`pending`, `sent`, `validated`, `expired`).
![Request OTP Code]()
## Next
Validate the code the user enters with [Validate OTP Code](/v2/packages-and-sdks/laravel/otp/validate-code).
OTP codes are short-lived and single-use. Prompt users to request a new code after expiry or repeated failures.
# Validate OTP Code
Source: https://docs.hypersender.com/v2/packages-and-sdks/laravel/otp/validate-code
Confirm a user's OTP submission from Laravel.
Check whether an OTP code is correct, unexpired, and unused using the Laravel SDK. Use this after the user submits the code they received via WhatsApp.
## Parameters
| Field | Type | Required | Description |
| ------ | ------ | -------- | --------------------------------------- |
| chatId | string | yes | WhatsApp chat ID that received the OTP. |
| code | string | yes | The OTP code entered by the user. |
## Validate the code
```php theme={null}
use Hypersender\Hypersender;
$response = Hypersender::otp()->validateCode([
'chatId' => '20123456789@c.us',
'code' => '439713',
]);
if (($response['success'] ?? false) && (($response['data']['status'] ?? '') === 'validated')) {
// proceed with login or protected action
}
```
### Common failure reasons
* Code does not match the active OTP
* Code expired based on `expires` value
* Code already used (single-use)
* No active OTP found for the `chatId`
Implement rate limits on validation attempts (e.g., max 3-5 tries) to block brute-force guessing.
## Next
For passwordless login flows, try [Generate OTP Link](/v2/packages-and-sdks/laravel/otp/generate-link) to avoid manual code entry.
# SMS Webhook Job
Source: https://docs.hypersender.com/v2/packages-and-sdks/laravel/sms/overriding-webhook-job
How to override the default SMS webhook job in Hypersender Laravel SDK.
# Overview
This page explains how Hypersender handles incoming SMS webhooks, the default job that processes them, and how to register your own job class.
## How it works
The incoming webhook hits your app on the route configured at `hypersender-config.sms_webhook_route` (default: `sms/webhook`).
`Hypersender\Http\Controllers\SmsWebhookController` resolves the job class from config and dispatches it:
* Config key: `hypersender-config.sms_webhook_job`
* The controller validates:
* The class exists and is a string
* The class implements `Hypersender\Contracts\SmsWebhookJobInterface`
* The controller dispatches the job with two named arguments:
* `payload: $request->payload()`
* `secret: $request->secret()`
Because the controller uses named arguments, your job’s constructor must accept parameters named `payload` and `secret`.
## The default job
Out of the box, the package ships with `Hypersender\Jobs\ProcessSmsWebhookJob`, which implements the interface `Hypersender\Contracts\SmsWebhookJobInterface`.
### Key details
```php theme={null}
public function __construct(
public array $payload,
public ?string $secret = null
) { }
```
If `hypersender-config.sms_queue` is set, the job is queued there.
Validates the `event` field and dispatches an application event via `SmsWebhookEventEnum` mapping.
## Using your own job class
You can replace the default job with your own implementation. Follow these steps:
Your job must implement `Hypersender\Contracts\SmsWebhookJobInterface` (a marker interface). This is enforced by the controller.
Your job’s constructor must accept the same named parameters that the controller provides:
```php theme={null}
use Hypersender\Contracts\SmsWebhookJobInterface;
use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Bus\Dispatchable;
use Illuminate\Queue\InteractsWithQueue;
use Illuminate\Queue\SerializesModels;
namespace App\Jobs;
class MySmsWebhookJob implements ShouldQueue, SmsWebhookJobInterface
{
use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;
public function __construct(public array $payload, public ?string $secret = null)
{
// Optional: route to a specific queue
if ($queue = config('hypersender-config.sms_queue')) {
$this->onQueue($queue);
}
}
public function handle(): void
{
// Your custom processing logic here
// $this->payload contains the webhook body
// $this->secret contains the Authorization secret (if sent)
}
}
```
You can register it either in your config or via environment variable.
* Via `.env`:
```env theme={null}
HYPERSENDER_SMS_WEBHOOK_JOB=App\Jobs\MySmsWebhookJob
```
* Or by publishing/editing the config `config/hypersender-config.php`:
```php theme={null}
'sms_webhook_job' => env('HYPERSENDER_SMS_WEBHOOK_JOB', App\Jobs\MySmsWebhookJob::class),
```
Make sure the class is autoloadable and available to your app (e.g., in `app/Jobs`).
## Can I use my own interface?
Yes! your job class can implement any additional interfaces you want for your own architecture. However, the package still requires your job to implement `Hypersender\\Contracts\\SmsWebhookJobInterface` because the controller enforces this at runtime. Swapping out that required interface via configuration is not supported. If you need to enforce your own contract, simply implement both interfaces on your job class.
## Related configuration
* API key: `HYPERSENDER_SMS_API_KEY`
* Instance ID: `HYPERSENDER_SMS_INSTANCE_ID`
* Webhook Authorization secret: `HYPERSENDER_SMS_WEBHOOK_AUTHORIZATION_SECRET` (defaults to `x-sms-webhook`)
* Webhook route: `HYPERSENDER_SMS_WEBHOOK_ROUTE` (defaults to `sms/webhook`)
* Webhook job: `HYPERSENDER_SMS_WEBHOOK_JOB` (defaults to `Hypersender\Jobs\ProcessSmsWebhookJob`)
* Queue name: `HYPERSENDER_SMS_QUEUE` (defaults to `default`)
## Validation rules enforced by the controller
If the configured job class is invalid, the controller aborts the request with HTTP `500`:
* Not a string or class does not exist
* Does not implement `Hypersender\Contracts\SmsWebhookJobInterface`
## Payload expectations
The default job expects an `event` string at `payload['event']`. If it is missing or not a string, the default job will report and fail the job. If you write a custom job, you can apply your own validation.
## Quick checklist
* Custom job implements `Hypersender\Contracts\SmsWebhookJobInterface`
* Constructor signature matches the named args: `__construct(array $payload, ?string $secret = null)`
* `HYPERSENDER_SMS_WEBHOOK_JOB` is set (or config updated)
* Optional: set `HYPERSENDER_SMS_QUEUE` to route jobs to a specific queue
## Troubleshooting
* 500 error on webhook: Ensure the configured job class exists and implements `SmsWebhookJobInterface`.
* Constructor argument mismatch: Because dispatch uses named args, your constructor parameter names must be exactly `payload` and `secret`.
* Queue not used: Verify `HYPERSENDER_SMS_QUEUE` (or config) and that your job calls `$this->onQueue(...)` in the constructor (or elsewhere) if you want to force a specific queue.
## TL;DR
* Default job: `Hypersender\Jobs\ProcessSmsWebhookJob` implements `Hypersender\Contracts\SmsWebhookJobInterface` and is used by default.
* Bring your own: Create a job that implements the interface, accepts `payload` and `secret` in the constructor, and register it via `HYPERSENDER_SMS_WEBHOOK_JOB` or in `config/hypersender-config.php`.