Skip to main content
GET
/
{instance}
/
queued-requests
/
{queued_request_uuid}
cURL
curl --request GET \
  --url https://app.hypersender.com/api/whatsapp/v2/{instance}/queued-requests/{queued_request_uuid} \
  --header 'Authorization: Bearer <token>'
{
  "uuid": "a0816120-7e37-4e8b-8cf3-92deb2cdc133",
  "request": {
    "chatId": "[email protected]",
    "text": "Hello world!"
  },
  "response_status": 200,
  "response_body": {
    "message_id": "AAAAAA0000BBBBB00CCCCCC"
  },
  "response_header": {}
}

​
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: 
{
    "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: 
{
    "uuid": "a08358c2-b4d6-4cd6-a882-70e606e4b95f",
    "request": {
        "text": "Check this https://hypersender.com/",
        "chatId": "[email protected]",
        "session": "4-instance-2598",
        "reply_to": null,
        "linkPreview": false,
        "linkPreviewHighQuality": false
    },
    "response_status": 201,
    "response_body": {
        "key": {
            "id": "3EB0155CFDC2464F72FD75",
            "fromMe": true,
            "remoteJid": "[email protected]"
        },
        "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

FieldTypeDescription
uuidstringUnique identifier for the queued request
requestobjectThe original request payload you sent
response_statusintegerHTTP status code of the processed request (e.g., 201 for success)
response_bodyobjectThe actual API response with message details
response_headerobjectResponse headers from the processed request

​
Response Body (Message Details)

The response_body contains the WhatsApp message details:
FieldDescription
key.idUnique WhatsApp message ID
key.fromMeWhether the message was sent by you
key.remoteJidThe recipient’s WhatsApp JID
statusMessage status (e.g., “PENDING”, “SENT”, “DELIVERED”)
messageThe message content
messageTimestampUnix timestamp when the message was sent

​
Response Status Codes

Check the response_status field to determine if the request was successful:
StatusDescription
201Message sent successfully
404Instance not found or recipient not on WhatsApp
422Validation error (invalid chatId, missing fields, etc.)
500Server error

​
Example: Failed Request

If the request failed (e.g., invalid phone number), the response will look like: 
{
    "uuid": "a08358c2-b4d6-4cd6-a882-70e606e4b95f",
    "request": {
        "text": "Hello!",
        "chatId": "[email protected]"
    },
    "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": "[email protected]",
            "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)

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)

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');
}

Authorizations

​
Authorization
string
header
required

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

Headers

​
Accept
string

application/json

Example:

"application/json"

Path Parameters

​
instance
string
required

Instance UUID copied from hypersender dashboard

Example:

"{{ instance_id }}"

​
queued_request_uuid
string
required

The UUID of the queued request returned from any API call

Example:

"a0816120-7e37-4e8b-8cf3-92deb2cdc133"

Response

Queued request details

Response when checking the status of a queued request

​
uuid
string
required

UUID of the queued request

Example:

"a0816120-7e37-4e8b-8cf3-92deb2cdc133"

​
request
object
required

The original request details

​
response_status
integer | null

HTTP status code of the processed request. Null while the request is still being processed.

Example:

200

​
response_body
object

The actual API response body once the request is processed. Contains the message details when completed, or error details when failed. Null while processing.

​
response_header
object

The response headers from the processed request. Null while processing.