Skip to main content

​
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: 
{
  "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: 
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: 
{
  "uuid": "a0816120-7e37-4e8b-8cf3-92deb2cdc133",
  "request": {
    "chatId": "[email protected]",
    "text": "Hello world!"
  },
  "response_status": null,
  "response_body": null,
  "response_header": null
}
When Completed: 
{
  "uuid": "a0816120-7e37-4e8b-8cf3-92deb2cdc133",
  "request": {
    "chatId": "[email protected]",
    "text": "Hello world!"
  },
  "response_status": 200,
  "response_body": {
    "message_id": "AAAAAA0000BBBBB00CCCCCC"
  },
  "response_header": {}
}

​
Response Fields Explained

FieldTypeDescription
uuidstringThe unique identifier for this queued request
requestobjectThe original request payload you submitted
response_statusinteger | nullHTTP status code of the processed request. null while still processing
response_bodyobject | nullThe actual API response. Contains message details on success, error details on failure. null while processing
response_headerobject | nullResponse 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_statusMeaning
nullRequest is still being processed
200Request completed successfully
4xxClient error (e.g., invalid parameters)
5xxServer 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 BehaviorV2 Behavior
Synchronous response with message detailsImmediate response with queued_request_uuid
Timeouts possible on slow requestsAlways fast response
Direct error responsesCheck 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.