> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hypersender.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Queued Request

> 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

<Tip>
  We recommend polling the queued request endpoint every **1-2 seconds** until you receive a response. Most requests complete within a few seconds.
</Tip>

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


## OpenAPI

````yaml v2/api-reference/whatsapp/whatsapp-collection.json GET /{instance}/queued-requests/{queued_request_uuid}
openapi: 3.1.0
info:
  version: v2.0
  title: Hypersender WhatsApp API Docs
  description: >

    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 a request, you'll receive an
    immediate response with a `queued_request_uuid` that you can use to check
    the status of your request.


    **Example Response:**

    ```json

    {
        "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/{queued_request_uuid}"
    }

    ```


    Use the `queued_request_link` or the **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



    <hr />


    **Quick Demo**

      **Learn how to use Hypersender whatsapp API to send a message using Postman:**
      [Demo Link](https://app.hypersender.com/send-whatsapp-message-in-postman) **to easily interact with our API.**

    <hr />


    **postman collection**


    You can download our [Postman
    Collection](https://docs.hypersender.com/whatsapp-postman-collection.json)
    to easily interact with our API.


    ## Servers (Endpoints)


    - Production (activated):
    [https://app.hypersender.com/api/whatsapp/v2](https://app.hypersender.com/api/whatsapp/v2)
servers:
  - url: https://app.hypersender.com/api/whatsapp/v2
    description: Production
security:
  - Authorization: []
paths:
  /{instance}/queued-requests/{queued_request_uuid}:
    get:
      tags:
        - Queued Requests
      parameters:
        - name: Accept
          in: header
          description: application/json
          schema:
            type: string
            example: application/json
        - name: instance
          in: path
          description: Instance UUID copied from hypersender dashboard
          required: true
          schema:
            type: string
            example: '{{ instance_id }}'
        - name: queued_request_uuid
          in: path
          description: The UUID of the queued request returned from any API call
          required: true
          schema:
            type: string
            example: a0816120-7e37-4e8b-8cf3-92deb2cdc133
      responses:
        '200':
          description: Queued request details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueuedRequestResponse'
              examples:
                Successful Message:
                  value:
                    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
                Failed Request:
                  value:
                    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
        '404':
          description: Queued request not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
      security:
        - Authorization: []
components:
  schemas:
    QueuedRequestResponse:
      type: object
      description: Response when checking the status of a queued request
      properties:
        uuid:
          type: string
          description: UUID of the queued request
          example: a0816120-7e37-4e8b-8cf3-92deb2cdc133
        request:
          type: object
          description: The original request details
          properties:
            chatId:
              type: string
              description: The chat ID the message was sent to
              example: 111111111111@c.us
            text:
              type: string
              description: The message text
              example: Hello world!
        response_status:
          type:
            - integer
            - 'null'
          description: >-
            HTTP status code of the processed request. Null while the request is
            still being processed.
          example: 200
        response_body:
          type:
            - object
            - 'null'
          description: >-
            The actual API response body once the request is processed. Contains
            the message details when completed, or error details when failed.
            Null while processing.
          properties:
            message_id:
              type: string
              description: The unique identifier of the sent message
              example: AAAAAA0000BBBBB00CCCCCC
        response_header:
          type:
            - object
            - 'null'
          description: >-
            The response headers from the processed request. Null while
            processing.
      required:
        - uuid
        - request
    NotFoundError:
      type: object
      title: NotFoundError
      example:
        message: Resource not found.
      properties:
        message:
          type: string
      x-examples:
        Example 1:
          message: Resource not found.
      x-stoplight:
        id: ar3vz55asbxme
  securitySchemes:
    Authorization:
      type: http
      scheme: bearer

````