# Wawp API Reference

Welcome to the Wawp API documentation in Markdown format. This document provides a comprehensive overview of all available endpoints, parameters, and expected responses.

## General

### Get Started
Learn how to use our interactive developer platform to test, integrate, and master Wawp API in minutes.

#### 💡 Tips
- **Global Sandbox**: Fill out your Instance ID and Token once in the Sidebar to use them across all interactive testers.
- **Code Samples**: Our code samples use your real sandbox values, making them perfect for "Copy-Paste" testing in your local environment.

---

## AI & Tools

### AI & MCP Integration
Connect Wawp API Documentation directly to your AI tools like Cursor, Windsurf, or Claude Desktop.

### Export & Downloads
Download Wawp API in your preferred format (OpenAPI, Markdown, HTML).

---

## Session Management

### Session Lifecycle
Documentation on Wawp's Session Lifecycle — how to provision, start, and maintain reliable WhatsApp instances.

#### 💡 Tips
- **Safe Restarts**: If a session is in FAILED state, always try a Restart before a full Logout/Start cycle.
- **QR Freshness**: QR codes in WhatsApp expire quickly. Always fetch the most recent code when the status is SCAN_QR_CODE.
- **Pairing Code UX**: Use Pairing Codes for users who can't easily scan a QR code. It provides a more accessible onboarding flow.

### Create Session
**Endpoint:** `POST /v2/session/create`

Provisions a fresh Wawp instance and returns metadata such as instance_id and session_name.

#### 💡 Tips
- **Metadata Storage**: Always store the 'server_name' alongside the 'instance_id'. It helps our support team resolve issues faster.
- **Quota Limits**: If you receive a 'quota_reached' error, you must either delete an unused instance or upgrade your plan.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| access_token | string | Yes | Your API Access Token |

#### 📦 Responses

<details>
<summary><b>HTTP 201</b>: Success - Session Created</summary>

```json
{
  "instance_id": "3EB0BCB2E3D4",
  "session_name": "wawp-84729105",
  "status": "STARTING",
  "server_name": "wawp-api-prod-50",
  "config": {}
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Missing Token</summary>

```json
{
  "code": "missing_param",
  "message": "Missing required parameter: access_token",
  "details": {
    "missing": [
      "access_token"
    ],
    "recommendation": "Ensure you are sending the 'access_token' in your request."
  }
}
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized - Invalid or Missing Access Token</summary>

```json
{
  "code": "invalid_access_token",
  "message": "Invalid or expired access token. Please check your credentials.",
  "details": {
    "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
  }
}
```

</details>

<details>
<summary><b>HTTP 403</b>: Forbidden - Quota or Limit Reached</summary>

```json
{
  "code": "quota_reached",
  "message": "You have reached your maximum instances limit.",
  "details": {
    "recommendation": "Upgrade your plan or delete unused instances to create new ones."
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error - Unexpected Failure</summary>

```json
{
  "code": "server_error",
  "message": "An internal server error occurred. Please try again later.",
  "details": {
    "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
  }
}
```

</details>

### Start Session
**Endpoint:** `POST, GET /v2/session/start`

Boots up the WhatsApp engine for a specific instance. This is the trigger that transitions a session from 'STOPPED' to 'STARTING'.

#### 💡 Tips
- **Async Operation**: This endpoint returns 'STARTING' immediately. The actual connection happens asynchronously in the background.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| instance_id | string | Yes | The 12-character ID of the instance |
| access_token | string | Yes | Your API Access Token |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Success - Boot Initiated</summary>

```json
{
  "name": "wawp-84729105",
  "status": "STARTING",
  "config": {
    "webhooks": [],
    "proxy": null
  }
}
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (Plain Text)</summary>

```json
"Success: Operation completed successfully."
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Missing Required Parameter(s)</summary>

```json
{
  "code": "missing_param",
  "message": "Missing required parameter: {parameterName}",
  "details": {
    "missing": [
      "{parameterName}"
    ],
    "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (Plain Text)</summary>

```json
"Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized - Invalid or Missing Access Token</summary>

```json
{
  "code": "invalid_access_token",
  "message": "Invalid or expired access token. Please check your credentials.",
  "details": {
    "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
  }
}
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found - Session Does Not Exist</summary>

```json
{
  "code": "invalid_session",
  "message": "Session not found. Please verify your instance_id or session_name.",
  "details": {
    "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
  }
}
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error - Unexpected Failure</summary>

```json
{
  "code": "server_error",
  "message": "An internal server error occurred. Please try again later.",
  "details": {
    "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error (HTML)</summary>

```json
"<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway - Connection Failed to Upstream</summary>

```json
{
  "code": "proxy_error",
  "message": "Failed to connect to WhatsApp server.",
  "details": {
    "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
  }
}
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
```

</details>

### Stop Session
**Endpoint:** `POST, GET /v2/session/stop`

Gracefully shuts down the WhatsApp engine for an instance without logging it out. Used to save resources or restart a stuck session.

#### 💡 Tips
- **Data Persistence**: Stopping a session DOES NOT delete your authentication data. You can restart it anytime without re-scanning the QR code.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| instance_id | string | Yes | The 12-character ID of the instance |
| access_token | string | Yes | Your API Access Token |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Success - Session Stopped</summary>

```json
{
  "name": "wawp-84729105",
  "status": "STOPPED",
  "config": {
    "webhooks": [],
    "proxy": null
  }
}
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (Plain Text)</summary>

```json
"Success: Operation completed successfully."
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Missing Required Parameter(s)</summary>

```json
{
  "code": "missing_param",
  "message": "Missing required parameter: {parameterName}",
  "details": {
    "missing": [
      "{parameterName}"
    ],
    "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (Plain Text)</summary>

```json
"Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized - Invalid or Missing Access Token</summary>

```json
{
  "code": "invalid_access_token",
  "message": "Invalid or expired access token. Please check your credentials.",
  "details": {
    "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
  }
}
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found - Session Does Not Exist</summary>

```json
{
  "code": "invalid_session",
  "message": "Session not found. Please verify your instance_id or session_name.",
  "details": {
    "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
  }
}
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error - Unexpected Failure</summary>

```json
{
  "code": "server_error",
  "message": "An internal server error occurred. Please try again later.",
  "details": {
    "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error (HTML)</summary>

```json
"<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway - Connection Failed to Upstream</summary>

```json
{
  "code": "proxy_error",
  "message": "Failed to connect to WhatsApp server.",
  "details": {
    "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
  }
}
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
```

</details>

### Restart Session
**Endpoint:** `POST, GET /v2/session/restart`

Reboots the WhatsApp instance. Useful for fixing stuck sessions or applying settings.

#### 💡 Tips
- **Zero Data Loss**: Restarting is safe. It does not delete your session data or log you out.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| instance_id | string | Yes | The 12-character ID of the instance |
| access_token | string | Yes | Your API Access Token |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Success - Reboot Initiated</summary>

```json
{
  "name": "wawp-84729105",
  "status": "STARTING",
  "config": {
    "webhooks": [],
    "proxy": null
  }
}
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (Plain Text)</summary>

```json
"Success: Operation completed successfully."
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Missing Required Parameter(s)</summary>

```json
{
  "code": "missing_param",
  "message": "Missing required parameter: {parameterName}",
  "details": {
    "missing": [
      "{parameterName}"
    ],
    "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (Plain Text)</summary>

```json
"Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized - Invalid or Missing Access Token</summary>

```json
{
  "code": "invalid_access_token",
  "message": "Invalid or expired access token. Please check your credentials.",
  "details": {
    "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
  }
}
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found - Session Does Not Exist</summary>

```json
{
  "code": "invalid_session",
  "message": "Session not found. Please verify your instance_id or session_name.",
  "details": {
    "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
  }
}
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error - Unexpected Failure</summary>

```json
{
  "code": "server_error",
  "message": "An internal server error occurred. Please try again later.",
  "details": {
    "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error (HTML)</summary>

```json
"<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway - Connection Failed to Upstream</summary>

```json
{
  "code": "proxy_error",
  "message": "Failed to connect to WhatsApp server.",
  "details": {
    "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
  }
}
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
```

</details>

### Logout Session
**Endpoint:** `POST, GET /v2/session/logout`

Logs the instance out of WhatsApp. This removes the paired device link but keeps the instance alive in a 'SCAN_QR_CODE' state.

#### 💡 Tips
- **Re-Pairing**: After logout, the instance ID remains valid. You do not need to create a new session.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| instance_id | string | Yes | The ID of the instance to logout |
| access_token | string | Yes | Your API Access Token |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Success - Logged Out</summary>

```json
{
  "name": "wawp-84729105",
  "status": "SCAN_QR_CODE",
  "instance_id": "3EB0BCB2E3D4"
}
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (Plain Text)</summary>

```json
"Success: Operation completed successfully."
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Missing Required Parameter(s)</summary>

```json
{
  "code": "missing_param",
  "message": "Missing required parameter: {parameterName}",
  "details": {
    "missing": [
      "{parameterName}"
    ],
    "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (Plain Text)</summary>

```json
"Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized - Invalid or Missing Access Token</summary>

```json
{
  "code": "invalid_access_token",
  "message": "Invalid or expired access token. Please check your credentials.",
  "details": {
    "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
  }
}
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found - Session Does Not Exist</summary>

```json
{
  "code": "invalid_session",
  "message": "Session not found. Please verify your instance_id or session_name.",
  "details": {
    "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
  }
}
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error - Unexpected Failure</summary>

```json
{
  "code": "server_error",
  "message": "An internal server error occurred. Please try again later.",
  "details": {
    "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error (HTML)</summary>

```json
"<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway - Connection Failed to Upstream</summary>

```json
{
  "code": "proxy_error",
  "message": "Failed to connect to WhatsApp server.",
  "details": {
    "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
  }
}
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
```

</details>

### Delete Session
**Endpoint:** `DELETE /v2/session/delete`

Permanently deletes a WhatsApp session locally and from the server. This action is irreversible.

#### 💡 Tips
- **No Undo**: There is no 'trash bin'. Deleted sessions cannot be recovered.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| instance_id | string | Yes | The 12-character ID of the instance to delete |
| access_token | string | Yes | Your API Access Token |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Success - Session Deleted</summary>

```json
{
  "name": "wawp-84729105",
  "status": "DELETED",
  "instance_id": "3EB0BCB2E3D4"
}
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (Plain Text)</summary>

```json
"Success: Operation completed successfully."
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Missing Required Parameter(s)</summary>

```json
{
  "code": "missing_param",
  "message": "Missing required parameter: {parameterName}",
  "details": {
    "missing": [
      "{parameterName}"
    ],
    "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (Plain Text)</summary>

```json
"Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized - Invalid or Missing Access Token</summary>

```json
{
  "code": "invalid_access_token",
  "message": "Invalid or expired access token. Please check your credentials.",
  "details": {
    "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
  }
}
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found - Session Does Not Exist</summary>

```json
{
  "code": "invalid_session",
  "message": "Session not found. Please verify your instance_id or session_name.",
  "details": {
    "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
  }
}
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error - Unexpected Failure</summary>

```json
{
  "code": "server_error",
  "message": "An internal server error occurred. Please try again later.",
  "details": {
    "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error (HTML)</summary>

```json
"<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway - Connection Failed to Upstream</summary>

```json
{
  "code": "proxy_error",
  "message": "Failed to connect to WhatsApp server.",
  "details": {
    "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
  }
}
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
```

</details>

### Session Info
**Endpoint:** `POST /v2/session/info`

Retrieve complete information about a WhatsApp session, including connection status, authenticated user info, and server details.

#### 💡 Tips
- **Real-time Updates**: This endpoint fetches data directly from the container. It is always the source of truth for connection status.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| instance_id | string | Yes | The 12-character ID of the instance to check |
| access_token | string | Yes | Your API Access Token |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Success - Session Info</summary>

```json
{
  "name": "wawp-84729105",
  "status": "WORKING",
  "config": {
    "webhooks": [],
    "proxy": null
  },
  "me": {
    "id": "201012345678@c.us",
    "pushName": "John Doe"
  }
}
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (Plain Text)</summary>

```json
"Success: Operation completed successfully."
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Missing Required Parameter(s)</summary>

```json
{
  "code": "missing_param",
  "message": "Missing required parameter: {parameterName}",
  "details": {
    "missing": [
      "{parameterName}"
    ],
    "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (Plain Text)</summary>

```json
"Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized - Invalid or Missing Access Token</summary>

```json
{
  "code": "invalid_access_token",
  "message": "Invalid or expired access token. Please check your credentials.",
  "details": {
    "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
  }
}
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found - Session Does Not Exist</summary>

```json
{
  "code": "invalid_session",
  "message": "Session not found. Please verify your instance_id or session_name.",
  "details": {
    "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
  }
}
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error - Unexpected Failure</summary>

```json
{
  "code": "server_error",
  "message": "An internal server error occurred. Please try again later.",
  "details": {
    "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error (HTML)</summary>

```json
"<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway - Connection Failed to Upstream</summary>

```json
{
  "code": "proxy_error",
  "message": "Failed to connect to WhatsApp server.",
  "details": {
    "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
  }
}
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
```

</details>

### About WhatsApp Data
**Endpoint:** `GET /v2/session/me`

Retrieves the profile information of the WhatsApp account connected to this session.

#### 💡 Tips
- **Cached Data**: This information is fetched directly from the WhatsApp engine. If you just changed your profile picture or name, it might take a moment to reflect.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| instance_id | string | Yes | The 12-character ID of the instance |
| access_token | string | Yes | Your API Access Token |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Success - Profile Data</summary>

```json
{
  "id": "201012345678@c.us",
  "pushName": "John Doe",
  "platform": "android",
  "me": {
    "id": "201012345678@c.us",
    "name": "John Doe"
  }
}
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (Plain Text)</summary>

```json
"Success: Operation completed successfully."
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Missing Required Parameter(s)</summary>

```json
{
  "code": "missing_param",
  "message": "Missing required parameter: {parameterName}",
  "details": {
    "missing": [
      "{parameterName}"
    ],
    "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (Plain Text)</summary>

```json
"Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized - Invalid or Missing Access Token</summary>

```json
{
  "code": "invalid_access_token",
  "message": "Invalid or expired access token. Please check your credentials.",
  "details": {
    "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
  }
}
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found - Session Does Not Exist</summary>

```json
{
  "code": "invalid_session",
  "message": "Session not found. Please verify your instance_id or session_name.",
  "details": {
    "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
  }
}
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error - Unexpected Failure</summary>

```json
{
  "code": "server_error",
  "message": "An internal server error occurred. Please try again later.",
  "details": {
    "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error (HTML)</summary>

```json
"<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway - Connection Failed to Upstream</summary>

```json
{
  "code": "proxy_error",
  "message": "Failed to connect to WhatsApp server.",
  "details": {
    "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
  }
}
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
```

</details>

---

## Authentication - Login

### About login authentication
Wawp’s Authentication & Login endpoints are designed to make device onboarding and re-authentication fast, secure, and developer-friendly.

#### 💡 Tips
- **Auto-reconnect**: Wawp automatically attempts to reconnect 'WORKING' sessions if a node restarts or a network glitch occurs.

### GET QR raw
**Endpoint:** `POST, GET /v2/auth/qr`

Retrieves the raw QR payload as binary/base64 plus a mimetype.

#### 💡 Tips
- **Freshness**: This endpoint returns a non-cached response header to ensure you always get the latest QR code.
- **Expiry**: The returned QR string has a short lifespan (20-60s). Use the 'expiry' timestamp to refresh it.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| instance_id | string | Yes | The 12-character ID of the instance |
| access_token | string | Yes | Your API Access Token |
| format | string | No | Output format (default: raw) |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Success - QR Raw Data</summary>

```json
{
  "mimetype": "application/json; charset=utf-8",
  "data": "eyJ2YWx1ZSI6IjJAR0JoWWtpTkV1U0tpeXpIeVVOYy9RQi9lTnhpSkJWSE96bGhOQ1daRERvRUZyOEhDWEhxTENKdEVpZHh6WWoxWkpqRzZ4K2NOaFVlVGlZeUJHWExJQzU1Z2ppKzRHQ2VyakRvPSIsImV4cGlyeSI6MTIzNDU2Nzg5MH0="
}
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (Plain Text)</summary>

```json
"Success: Operation completed successfully."
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Missing Required Parameter(s)</summary>

```json
{
  "code": "missing_param",
  "message": "Missing required parameter: {parameterName}",
  "details": {
    "missing": [
      "{parameterName}"
    ],
    "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (Plain Text)</summary>

```json
"Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized - Invalid or Missing Access Token</summary>

```json
{
  "code": "invalid_access_token",
  "message": "Invalid or expired access token. Please check your credentials.",
  "details": {
    "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
  }
}
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found - Session Does Not Exist</summary>

```json
{
  "code": "invalid_session",
  "message": "Session not found. Please verify your instance_id or session_name.",
  "details": {
    "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
  }
}
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error - Unexpected Failure</summary>

```json
{
  "code": "server_error",
  "message": "An internal server error occurred. Please try again later.",
  "details": {
    "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error (HTML)</summary>

```json
"<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway - Connection Failed to Upstream</summary>

```json
{
  "code": "proxy_error",
  "message": "Failed to connect to WhatsApp server.",
  "details": {
    "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
  }
}
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 422</b>: Unprocessable Entity - Session Status Mismatch</summary>

```json
{
  "code": "session_unexpected_status",
  "message": "Session status is not as expected for this operation. We are attempting to auto-recover.",
  "details": {
    "current_status": "FAILED",
    "expected_status": [
      "SCAN_QR_CODE"
    ],
    "action": "auto_restart_triggered",
    "recommendation": "The instance encountered an error and is being restarted. Please wait a few seconds and try again."
  }
}
```

</details>

### Get QR Image
**Endpoint:** `POST, GET /v2/auth/qr-image`

Returns a base64-encoded PNG image of the WhatsApp QR code for easy rendering in web and mobile applications.

#### 💡 Tips
- **Direct Rendering**: The 'qr' field is a full Data URI. Bind it directly to an <img src='...'> tag.
- **Wait for Engine**: After starting a session, it may take 5-15 seconds for the QR code to be ready.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| instance_id | string | Yes | The 12-character ID of the instance |
| access_token | string | Yes | Your API Access Token |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Success - QR Image URL</summary>

```json
{
  "qr": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgA..."
}
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (Plain Text)</summary>

```json
"Success: Operation completed successfully."
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Missing Required Parameter(s)</summary>

```json
{
  "code": "missing_param",
  "message": "Missing required parameter: {parameterName}",
  "details": {
    "missing": [
      "{parameterName}"
    ],
    "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (Plain Text)</summary>

```json
"Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized - Invalid or Missing Access Token</summary>

```json
{
  "code": "invalid_access_token",
  "message": "Invalid or expired access token. Please check your credentials.",
  "details": {
    "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
  }
}
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found - Session Does Not Exist</summary>

```json
{
  "code": "invalid_session",
  "message": "Session not found. Please verify your instance_id or session_name.",
  "details": {
    "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
  }
}
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error - Unexpected Failure</summary>

```json
{
  "code": "server_error",
  "message": "An internal server error occurred. Please try again later.",
  "details": {
    "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error (HTML)</summary>

```json
"<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway - Connection Failed to Upstream</summary>

```json
{
  "code": "proxy_error",
  "message": "Failed to connect to WhatsApp server.",
  "details": {
    "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
  }
}
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 422</b>: Unprocessable Entity - Session Status Mismatch</summary>

```json
{
  "code": "session_unexpected_status",
  "message": "Session status is not as expected for this operation. We are attempting to auto-recover.",
  "details": {
    "current_status": "FAILED",
    "expected_status": [
      "SCAN_QR_CODE"
    ],
    "action": "auto_restart_triggered",
    "recommendation": "The instance encountered an error and is being restarted. Please wait a few seconds and try again."
  }
}
```

</details>

### Request Code (Phone Login)
**Endpoint:** `POST /v2/auth/request-code`

Requests a linking code for phone-based WhatsApp authentication (OTP style).

#### 💡 Tips
- **Wait Time**: WhatsApp generation takes 2-5 seconds. UI should show a spinner.
- **Rate Limit**: Do not request codes frequently. WhatsApp may temporarily block the number.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| instance_id | string | Yes | The 12-character ID of the instance |
| access_token | string | Yes | Your API Access Token |
| phone_number | string | Yes | The phone number to link (e.g., 201145202826) |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Success - Linking Code Generated</summary>

```json
{
  "code": "ABCD-1234"
}
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (Plain Text)</summary>

```json
"Success: Operation completed successfully."
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Missing Required Parameter(s)</summary>

```json
{
  "code": "missing_param",
  "message": "Missing required parameter: {parameterName}",
  "details": {
    "missing": [
      "{parameterName}"
    ],
    "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (Plain Text)</summary>

```json
"Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized - Invalid or Missing Access Token</summary>

```json
{
  "code": "invalid_access_token",
  "message": "Invalid or expired access token. Please check your credentials.",
  "details": {
    "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
  }
}
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found - Session Does Not Exist</summary>

```json
{
  "code": "invalid_session",
  "message": "Session not found. Please verify your instance_id or session_name.",
  "details": {
    "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
  }
}
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error - Unexpected Failure</summary>

```json
{
  "code": "server_error",
  "message": "An internal server error occurred. Please try again later.",
  "details": {
    "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error (HTML)</summary>

```json
"<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway - Connection Failed to Upstream</summary>

```json
{
  "code": "proxy_error",
  "message": "Failed to connect to WhatsApp server.",
  "details": {
    "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
  }
}
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 422</b>: Unprocessable Entity - Session Status Mismatch</summary>

```json
{
  "code": "session_unexpected_status",
  "message": "Session status is not as expected for this operation. We are attempting to auto-recover.",
  "details": {
    "current_status": "FAILED",
    "expected_status": [
      "SCAN_QR_CODE"
    ],
    "action": "auto_restart_triggered",
    "recommendation": "The instance encountered an error and is being restarted. Please wait a few seconds and try again."
  }
}
```

</details>

---

## Send Messages

### Messaging Guide
Overview of Wawp's Messaging capabilities and best practices.

#### 💡 Tips
- **Bulk Sending**: For large campaigns, we recommend spacing out messages to mimic natural human behavior.

### Send Text Message
**Endpoint:** `POST, GET /v2/send/text`

Use for core text messaging. Required params: instance_id, access_token, chatId, message.

#### 💡 Tips
- **Optimistic UI**: Send instantly with optimistic UI ( [show “typing...”](https://docs.wawp.net/start-typing-19609223e0) then update on response).
- **Character Limits**: WhatsApp supports up to 4096 characters per message. However, for marketing or automated alerts, keep it under 1000 for better readability.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| instance_id | string | Yes | Unique ID of the WhatsApp session |
| access_token | string | Yes | API access token |
| chatId | string | Yes | Recipient's WhatsApp ID (JID). Supports Individuals (@c.us), Groups (@g.us), and Newsletters (@newsletter). |
| message | string | Yes | Message text to be sent |
| reply_to | string | No | The ID of the message you are replying to |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Message Sent Successfully</summary>

```json
{
  "_data": {
    "id": {
      "fromMe": true,
      "remote": "000000000000@c.us",
      "id": "MSG_ID_123456",
      "_serialized": "true_000000000000@c.us_MSG_ID_123456"
    },
    "viewed": false,
    "body": "BASE64_IMAGE_DATA",
    "type": "image",
    "t": 1759108866,
    "from": {
      "server": "c.us",
      "user": "111111111111",
      "_serialized": "111111111111@c.us"
    },
    "to": {
      "server": "c.us",
      "user": "000000000000",
      "_serialized": "000000000000@c.us"
    },
    "ack": 0,
    "isNewMsg": true,
    "star": false,
    "kicNotified": false,
    "caption": "Here's your requested image.",
    "deprecatedMms3Url": "https://example.com/media-url",
    "directPath": "/media/direct/path/example",
    "mimetype": "image/jpeg",
    "filehash": "FILE_HASH_PLACEHOLDER",
    "encFilehash": "ENC_FILE_HASH_PLACEHOLDER",
    "size": 192487,
    "mediaKey": "MEDIA_KEY_PLACEHOLDER",
    "mediaKeyTimestamp": 1759108865,
    "streamable": false,
    "mediaHandle": null,
    "isFromTemplate": false,
    "pollInvalidated": false,
    "isSentCagPollCreation": false,
    "latestEditMsgKey": null,
    "latestEditSenderTimestampMs": null,
    "mentionedJidList": [],
    "groupMentions": [],
    "isEventCanceled": false,
    "eventInvalidated": false,
    "isVcardOverMmsDocument": false,
    "isForwarded": false,
    "isQuestion": false,
    "questionReplyQuotedMessage": null,
    "questionResponsesCount": 0,
    "readQuestionResponsesCount": 0,
    "labels": [],
    "hasReaction": false,
    "disappearingModeInitiator": "chat",
    "disappearingModeTrigger": "chat_settings",
    "productHeaderImageRejected": false,
    "lastPlaybackProgress": 0,
    "isDynamicReplyButtonsMsg": false,
    "isCarouselCard": false,
    "parentMsgId": null,
    "callSilenceReason": null,
    "isVideoCall": false,
    "callDuration": null,
    "callCreator": null,
    "callParticipants": null,
    "isCallLink": null,
    "callLinkToken": null,
    "isMdHistoryMsg": false,
    "stickerSentTs": 0,
    "lastUpdateFromServerTs": 0,
    "invokedBotWid": null,
    "bizBotType": null,
    "botResponseTargetId": null,
    "botPluginType": null,
    "botPluginReferenceIndex": null,
    "botPluginSearchProvider": null,
    "botPluginSearchUrl": null,
    "botPluginSearchQuery": null,
    "botPluginMaybeParent": false,
    "botReelPluginThumbnailCdnUrl": null,
    "botMessageDisclaimerText": null,
    "botMsgBodyType": null,
    "requiresDirectConnection": false,
    "bizContentPlaceholderType": null,
    "hostedBizEncStateMismatch": false,
    "senderOrRecipientAccountTypeHosted": false,
    "placeholderCreatedWhenAccountIsHosted": false,
    "galaxyFlowDisabled": false,
    "links": []
  },
  "mediaKey": "MEDIA_KEY_PLACEHOLDER",
  "id": {
    "fromMe": true,
    "remote": "000000000000@c.us",
    "id": "MSG_ID_123456",
    "_serialized": "true_000000000000@c.us_MSG_ID_123456"
  },
  "ack": 0,
  "hasMedia": true,
  "body": "Here's your requested image.",
  "type": "image",
  "timestamp": 1759108866,
  "from": "111111111111@c.us",
  "to": "000000000000@c.us",
  "deviceType": "android",
  "isForwarded": false,
  "forwardingScore": 0,
  "isStatus": false,
  "isStarred": false,
  "fromMe": true,
  "hasQuotedMsg": false,
  "hasReaction": false,
  "vCards": [],
  "mentionedIds": [],
  "groupMentions": [],
  "isGif": false,
  "links": []
}
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (Plain Text)</summary>

```json
"Success: Operation completed successfully."
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Missing Required Parameter(s)</summary>

```json
{
  "code": "missing_param",
  "message": "Missing required parameter: {parameterName}",
  "details": {
    "missing": [
      "{parameterName}"
    ],
    "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Invalid Number (Egypt)</summary>

```json
{
  "code": "invalid_chat_id",
  "message": "Egypt mobile numbers must be 11 digits (national format).",
  "details": {
    "provided": "20114520282",
    "recommendation": "Example: 201012345678 (12 digits total starting with 20)",
    "info": {
      "country": "EG",
      "type": "MOBILE"
    }
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Invalid Number (Saudi Arabia)</summary>

```json
{
  "code": "invalid_chat_id",
  "message": "Invalid phone number format for SA.",
  "details": {
    "provided": "96655555",
    "recommendation": "Saudi numbers must start with 966 followed by 5 and 8 digits (12 digits total). Example: 966501234567",
    "info": {
      "country": "SA"
    }
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Invalid Number (Unknown)</summary>

```json
{
  "code": "invalid_chat_id",
  "message": "Invalid phone number format for Unknown.",
  "details": {
    "provided": "01145202826",
    "recommendation": "Ensure individual numbers are in international format (starting with country code).",
    "info": {
      "country": "Unknown"
    }
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (Plain Text)</summary>

```json
"Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized - Invalid or Missing Access Token</summary>

```json
{
  "code": "invalid_access_token",
  "message": "Invalid or expired access token. Please check your credentials.",
  "details": {
    "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
  }
}
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found - Session Does Not Exist</summary>

```json
{
  "code": "invalid_session",
  "message": "Session not found. Please verify your instance_id or session_name.",
  "details": {
    "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
  }
}
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 429</b>: Too Many Requests - Rate Limit Exceeded</summary>

```json
{
  "code": "rate_limit_exceeded",
  "message": "Too many requests. Please slow down.",
  "details": {
    "retryAfter": 60,
    "recommendation": "Implement a retry strategy with exponential backoff or reduce the frequency of your requests.",
    "upstream": {
      "error": "Rate limit",
      "statusCode": 429
    }
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error - Unexpected Failure</summary>

```json
{
  "code": "server_error",
  "message": "An internal server error occurred. Please try again later.",
  "details": {
    "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error (HTML)</summary>

```json
"<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway - Connection Failed to Upstream</summary>

```json
{
  "code": "proxy_error",
  "message": "Failed to connect to WhatsApp server.",
  "details": {
    "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
  }
}
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
```

</details>

### Send Image
**Endpoint:** `POST, GET /v2/send/image`

SendImage expects a file object (url, mimetype, filename) and required caption/reply_to.

#### 💡 Tips
- **Direct Rendering**: Display a client-side thumbnail before sending to give users immediate feedback.
- **Supported Formats**: WhatsApp primarily accepts PNG and JPEG. Ensure your URLs point to valid image files.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| instance_id | string | Yes | Unique ID of the WhatsApp session |
| access_token | string | Yes | API access token |
| chatId | string | Yes | Recipient's WhatsApp ID (JID). Supports Individuals (@c.us), Groups (@g.us), and Newsletters (@newsletter). |
| file[url] | string | Yes | Publicly accessible HTTPS URL of the image |
| file[filename] | string | Yes | Filename for the image |
| file[mimetype] | string | Yes | MIME type (image/jpeg or image/png) |
| caption | string | Yes | Caption for the image |
| reply_to | string | No | The ID of the message you are replying to |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Message Sent Successfully</summary>

```json
{
  "_data": {
    "id": {
      "fromMe": true,
      "remote": "000000000000@c.us",
      "id": "MSG_ID_123456",
      "_serialized": "true_000000000000@c.us_MSG_ID_123456"
    },
    "viewed": false,
    "body": "BASE64_IMAGE_DATA",
    "type": "image",
    "t": 1759108866,
    "from": {
      "server": "c.us",
      "user": "111111111111",
      "_serialized": "111111111111@c.us"
    },
    "to": {
      "server": "c.us",
      "user": "000000000000",
      "_serialized": "000000000000@c.us"
    },
    "ack": 0,
    "isNewMsg": true,
    "star": false,
    "kicNotified": false,
    "caption": "Here's your requested image.",
    "deprecatedMms3Url": "https://example.com/media-url",
    "directPath": "/media/direct/path/example",
    "mimetype": "image/jpeg",
    "filehash": "FILE_HASH_PLACEHOLDER",
    "encFilehash": "ENC_FILE_HASH_PLACEHOLDER",
    "size": 192487,
    "mediaKey": "MEDIA_KEY_PLACEHOLDER",
    "mediaKeyTimestamp": 1759108865,
    "streamable": false,
    "mediaHandle": null,
    "isFromTemplate": false,
    "pollInvalidated": false,
    "isSentCagPollCreation": false,
    "latestEditMsgKey": null,
    "latestEditSenderTimestampMs": null,
    "mentionedJidList": [],
    "groupMentions": [],
    "isEventCanceled": false,
    "eventInvalidated": false,
    "isVcardOverMmsDocument": false,
    "isForwarded": false,
    "isQuestion": false,
    "questionReplyQuotedMessage": null,
    "questionResponsesCount": 0,
    "readQuestionResponsesCount": 0,
    "labels": [],
    "hasReaction": false,
    "disappearingModeInitiator": "chat",
    "disappearingModeTrigger": "chat_settings",
    "productHeaderImageRejected": false,
    "lastPlaybackProgress": 0,
    "isDynamicReplyButtonsMsg": false,
    "isCarouselCard": false,
    "parentMsgId": null,
    "callSilenceReason": null,
    "isVideoCall": false,
    "callDuration": null,
    "callCreator": null,
    "callParticipants": null,
    "isCallLink": null,
    "callLinkToken": null,
    "isMdHistoryMsg": false,
    "stickerSentTs": 0,
    "lastUpdateFromServerTs": 0,
    "invokedBotWid": null,
    "bizBotType": null,
    "botResponseTargetId": null,
    "botPluginType": null,
    "botPluginReferenceIndex": null,
    "botPluginSearchProvider": null,
    "botPluginSearchUrl": null,
    "botPluginSearchQuery": null,
    "botPluginMaybeParent": false,
    "botReelPluginThumbnailCdnUrl": null,
    "botMessageDisclaimerText": null,
    "botMsgBodyType": null,
    "requiresDirectConnection": false,
    "bizContentPlaceholderType": null,
    "hostedBizEncStateMismatch": false,
    "senderOrRecipientAccountTypeHosted": false,
    "placeholderCreatedWhenAccountIsHosted": false,
    "galaxyFlowDisabled": false,
    "links": []
  },
  "mediaKey": "MEDIA_KEY_PLACEHOLDER",
  "id": {
    "fromMe": true,
    "remote": "000000000000@c.us",
    "id": "MSG_ID_123456",
    "_serialized": "true_000000000000@c.us_MSG_ID_123456"
  },
  "ack": 0,
  "hasMedia": true,
  "body": "Here's your requested image.",
  "type": "image",
  "timestamp": 1759108866,
  "from": "111111111111@c.us",
  "to": "000000000000@c.us",
  "deviceType": "android",
  "isForwarded": false,
  "forwardingScore": 0,
  "isStatus": false,
  "isStarred": false,
  "fromMe": true,
  "hasQuotedMsg": false,
  "hasReaction": false,
  "vCards": [],
  "mentionedIds": [],
  "groupMentions": [],
  "isGif": false,
  "links": []
}
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (Plain Text)</summary>

```json
"Success: Operation completed successfully."
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Missing Required Parameter(s)</summary>

```json
{
  "code": "missing_param",
  "message": "Missing required parameter: {parameterName}",
  "details": {
    "missing": [
      "{parameterName}"
    ],
    "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Invalid Number (Egypt)</summary>

```json
{
  "code": "invalid_chat_id",
  "message": "Egypt mobile numbers must be 11 digits (national format).",
  "details": {
    "provided": "20114520282",
    "recommendation": "Example: 201012345678 (12 digits total starting with 20)",
    "info": {
      "country": "EG",
      "type": "MOBILE"
    }
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Invalid Number (Saudi Arabia)</summary>

```json
{
  "code": "invalid_chat_id",
  "message": "Invalid phone number format for SA.",
  "details": {
    "provided": "96655555",
    "recommendation": "Saudi numbers must start with 966 followed by 5 and 8 digits (12 digits total). Example: 966501234567",
    "info": {
      "country": "SA"
    }
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Invalid Number (Unknown)</summary>

```json
{
  "code": "invalid_chat_id",
  "message": "Invalid phone number format for Unknown.",
  "details": {
    "provided": "01145202826",
    "recommendation": "Ensure individual numbers are in international format (starting with country code).",
    "info": {
      "country": "Unknown"
    }
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (Plain Text)</summary>

```json
"Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized - Invalid or Missing Access Token</summary>

```json
{
  "code": "invalid_access_token",
  "message": "Invalid or expired access token. Please check your credentials.",
  "details": {
    "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
  }
}
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found - Session Does Not Exist</summary>

```json
{
  "code": "invalid_session",
  "message": "Session not found. Please verify your instance_id or session_name.",
  "details": {
    "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
  }
}
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 429</b>: Too Many Requests - Rate Limit Exceeded</summary>

```json
{
  "code": "rate_limit_exceeded",
  "message": "Too many requests. Please slow down.",
  "details": {
    "retryAfter": 60,
    "recommendation": "Implement a retry strategy with exponential backoff or reduce the frequency of your requests.",
    "upstream": {
      "error": "Rate limit",
      "statusCode": 429
    }
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error - Unexpected Failure</summary>

```json
{
  "code": "server_error",
  "message": "An internal server error occurred. Please try again later.",
  "details": {
    "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error (HTML)</summary>

```json
"<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway - Connection Failed to Upstream</summary>

```json
{
  "code": "proxy_error",
  "message": "Failed to connect to WhatsApp server.",
  "details": {
    "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
  }
}
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
```

</details>

### Send PDF
**Endpoint:** `POST, GET /v2/send/pdf`

Treat PDFs as general file deliveries via the file endpoint. Require file.url and required caption.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| instance_id | string | Yes | Unique ID of the WhatsApp session |
| access_token | string | Yes | API access token |
| chatId | string | Yes | Recipient's WhatsApp ID (JID). Supports Individuals (@c.us), Groups (@g.us), and Newsletters (@newsletter). |
| file[url] | string | Yes | Publicly accessible HTTPS URL of the PDF file |
| file[filename] | string | Yes | Filename for the document |
| file[mimetype] | string | Yes | MIME type (e.g., application/pdf) |
| caption | string | Yes | Caption for the document |
| reply_to | string | No | The ID of the message you are replying to |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Message Sent Successfully</summary>

```json
{
  "_data": {
    "id": {
      "fromMe": true,
      "remote": "000000000000@c.us",
      "id": "MSG_ID_123456",
      "_serialized": "true_000000000000@c.us_MSG_ID_123456"
    },
    "viewed": false,
    "body": "BASE64_IMAGE_DATA",
    "type": "image",
    "t": 1759108866,
    "from": {
      "server": "c.us",
      "user": "111111111111",
      "_serialized": "111111111111@c.us"
    },
    "to": {
      "server": "c.us",
      "user": "000000000000",
      "_serialized": "000000000000@c.us"
    },
    "ack": 0,
    "isNewMsg": true,
    "star": false,
    "kicNotified": false,
    "caption": "Here's your requested image.",
    "deprecatedMms3Url": "https://example.com/media-url",
    "directPath": "/media/direct/path/example",
    "mimetype": "image/jpeg",
    "filehash": "FILE_HASH_PLACEHOLDER",
    "encFilehash": "ENC_FILE_HASH_PLACEHOLDER",
    "size": 192487,
    "mediaKey": "MEDIA_KEY_PLACEHOLDER",
    "mediaKeyTimestamp": 1759108865,
    "streamable": false,
    "mediaHandle": null,
    "isFromTemplate": false,
    "pollInvalidated": false,
    "isSentCagPollCreation": false,
    "latestEditMsgKey": null,
    "latestEditSenderTimestampMs": null,
    "mentionedJidList": [],
    "groupMentions": [],
    "isEventCanceled": false,
    "eventInvalidated": false,
    "isVcardOverMmsDocument": false,
    "isForwarded": false,
    "isQuestion": false,
    "questionReplyQuotedMessage": null,
    "questionResponsesCount": 0,
    "readQuestionResponsesCount": 0,
    "labels": [],
    "hasReaction": false,
    "disappearingModeInitiator": "chat",
    "disappearingModeTrigger": "chat_settings",
    "productHeaderImageRejected": false,
    "lastPlaybackProgress": 0,
    "isDynamicReplyButtonsMsg": false,
    "isCarouselCard": false,
    "parentMsgId": null,
    "callSilenceReason": null,
    "isVideoCall": false,
    "callDuration": null,
    "callCreator": null,
    "callParticipants": null,
    "isCallLink": null,
    "callLinkToken": null,
    "isMdHistoryMsg": false,
    "stickerSentTs": 0,
    "lastUpdateFromServerTs": 0,
    "invokedBotWid": null,
    "bizBotType": null,
    "botResponseTargetId": null,
    "botPluginType": null,
    "botPluginReferenceIndex": null,
    "botPluginSearchProvider": null,
    "botPluginSearchUrl": null,
    "botPluginSearchQuery": null,
    "botPluginMaybeParent": false,
    "botReelPluginThumbnailCdnUrl": null,
    "botMessageDisclaimerText": null,
    "botMsgBodyType": null,
    "requiresDirectConnection": false,
    "bizContentPlaceholderType": null,
    "hostedBizEncStateMismatch": false,
    "senderOrRecipientAccountTypeHosted": false,
    "placeholderCreatedWhenAccountIsHosted": false,
    "galaxyFlowDisabled": false,
    "links": []
  },
  "mediaKey": "MEDIA_KEY_PLACEHOLDER",
  "id": {
    "fromMe": true,
    "remote": "000000000000@c.us",
    "id": "MSG_ID_123456",
    "_serialized": "true_000000000000@c.us_MSG_ID_123456"
  },
  "ack": 0,
  "hasMedia": true,
  "body": "Here's your requested image.",
  "type": "image",
  "timestamp": 1759108866,
  "from": "111111111111@c.us",
  "to": "000000000000@c.us",
  "deviceType": "android",
  "isForwarded": false,
  "forwardingScore": 0,
  "isStatus": false,
  "isStarred": false,
  "fromMe": true,
  "hasQuotedMsg": false,
  "hasReaction": false,
  "vCards": [],
  "mentionedIds": [],
  "groupMentions": [],
  "isGif": false,
  "links": []
}
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (Plain Text)</summary>

```json
"Success: Operation completed successfully."
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Missing Required Parameter(s)</summary>

```json
{
  "code": "missing_param",
  "message": "Missing required parameter: {parameterName}",
  "details": {
    "missing": [
      "{parameterName}"
    ],
    "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Invalid Number (Egypt)</summary>

```json
{
  "code": "invalid_chat_id",
  "message": "Egypt mobile numbers must be 11 digits (national format).",
  "details": {
    "provided": "20114520282",
    "recommendation": "Example: 201012345678 (12 digits total starting with 20)",
    "info": {
      "country": "EG",
      "type": "MOBILE"
    }
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Invalid Number (Saudi Arabia)</summary>

```json
{
  "code": "invalid_chat_id",
  "message": "Invalid phone number format for SA.",
  "details": {
    "provided": "96655555",
    "recommendation": "Saudi numbers must start with 966 followed by 5 and 8 digits (12 digits total). Example: 966501234567",
    "info": {
      "country": "SA"
    }
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Invalid Number (Unknown)</summary>

```json
{
  "code": "invalid_chat_id",
  "message": "Invalid phone number format for Unknown.",
  "details": {
    "provided": "01145202826",
    "recommendation": "Ensure individual numbers are in international format (starting with country code).",
    "info": {
      "country": "Unknown"
    }
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (Plain Text)</summary>

```json
"Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized - Invalid or Missing Access Token</summary>

```json
{
  "code": "invalid_access_token",
  "message": "Invalid or expired access token. Please check your credentials.",
  "details": {
    "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
  }
}
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found - Session Does Not Exist</summary>

```json
{
  "code": "invalid_session",
  "message": "Session not found. Please verify your instance_id or session_name.",
  "details": {
    "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
  }
}
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 429</b>: Too Many Requests - Rate Limit Exceeded</summary>

```json
{
  "code": "rate_limit_exceeded",
  "message": "Too many requests. Please slow down.",
  "details": {
    "retryAfter": 60,
    "recommendation": "Implement a retry strategy with exponential backoff or reduce the frequency of your requests.",
    "upstream": {
      "error": "Rate limit",
      "statusCode": 429
    }
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error - Unexpected Failure</summary>

```json
{
  "code": "server_error",
  "message": "An internal server error occurred. Please try again later.",
  "details": {
    "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error (HTML)</summary>

```json
"<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway - Connection Failed to Upstream</summary>

```json
{
  "code": "proxy_error",
  "message": "Failed to connect to WhatsApp server.",
  "details": {
    "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
  }
}
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
```

</details>

### Send List Message
**Endpoint:** `POST, GET /v2/send/list`

Sends an interactive List Message (menu) to a chat. This message type displays a button that, when tapped, opens a list of options.

#### 💡 Tips
- **Better Conversions**: List messages have a significantly higher engagement rate than plain text menus because they reduce typing effort for the user.
- **Unique rowId**: Always ensure your `rowId` is unique within the list to correctly identify the user's choice in your backend logic.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| instance_id | string | Yes | Unique ID of the WhatsApp session |
| access_token | string | Yes | API access token |
| chatId | string | Yes | Recipient's WhatsApp number |
| message | object | Yes | The interactive list message structure. |
| message.title | string | Yes | Header title of the list message. |
| message.description | string | Yes | Body text of the message. |
| message.footer | string | Yes | Small text at the bottom. |
| message.button | string | Yes | Text on the button that opens the list. |
| message.sections | array | Yes | Array of sections, each containing a title and rows. |
| reply_to | string | No | The ID of the message you are replying to |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Message Sent Successfully</summary>

```json
{
  "_data": {
    "id": {
      "fromMe": true,
      "remote": "000000000000@c.us",
      "id": "MSG_ID_123456",
      "_serialized": "true_000000000000@c.us_MSG_ID_123456"
    },
    "viewed": false,
    "body": "BASE64_IMAGE_DATA",
    "type": "image",
    "t": 1759108866,
    "from": {
      "server": "c.us",
      "user": "111111111111",
      "_serialized": "111111111111@c.us"
    },
    "to": {
      "server": "c.us",
      "user": "000000000000",
      "_serialized": "000000000000@c.us"
    },
    "ack": 0,
    "isNewMsg": true,
    "star": false,
    "kicNotified": false,
    "caption": "Here's your requested image.",
    "deprecatedMms3Url": "https://example.com/media-url",
    "directPath": "/media/direct/path/example",
    "mimetype": "image/jpeg",
    "filehash": "FILE_HASH_PLACEHOLDER",
    "encFilehash": "ENC_FILE_HASH_PLACEHOLDER",
    "size": 192487,
    "mediaKey": "MEDIA_KEY_PLACEHOLDER",
    "mediaKeyTimestamp": 1759108865,
    "streamable": false,
    "mediaHandle": null,
    "isFromTemplate": false,
    "pollInvalidated": false,
    "isSentCagPollCreation": false,
    "latestEditMsgKey": null,
    "latestEditSenderTimestampMs": null,
    "mentionedJidList": [],
    "groupMentions": [],
    "isEventCanceled": false,
    "eventInvalidated": false,
    "isVcardOverMmsDocument": false,
    "isForwarded": false,
    "isQuestion": false,
    "questionReplyQuotedMessage": null,
    "questionResponsesCount": 0,
    "readQuestionResponsesCount": 0,
    "labels": [],
    "hasReaction": false,
    "disappearingModeInitiator": "chat",
    "disappearingModeTrigger": "chat_settings",
    "productHeaderImageRejected": false,
    "lastPlaybackProgress": 0,
    "isDynamicReplyButtonsMsg": false,
    "isCarouselCard": false,
    "parentMsgId": null,
    "callSilenceReason": null,
    "isVideoCall": false,
    "callDuration": null,
    "callCreator": null,
    "callParticipants": null,
    "isCallLink": null,
    "callLinkToken": null,
    "isMdHistoryMsg": false,
    "stickerSentTs": 0,
    "lastUpdateFromServerTs": 0,
    "invokedBotWid": null,
    "bizBotType": null,
    "botResponseTargetId": null,
    "botPluginType": null,
    "botPluginReferenceIndex": null,
    "botPluginSearchProvider": null,
    "botPluginSearchUrl": null,
    "botPluginSearchQuery": null,
    "botPluginMaybeParent": false,
    "botReelPluginThumbnailCdnUrl": null,
    "botMessageDisclaimerText": null,
    "botMsgBodyType": null,
    "requiresDirectConnection": false,
    "bizContentPlaceholderType": null,
    "hostedBizEncStateMismatch": false,
    "senderOrRecipientAccountTypeHosted": false,
    "placeholderCreatedWhenAccountIsHosted": false,
    "galaxyFlowDisabled": false,
    "links": []
  },
  "mediaKey": "MEDIA_KEY_PLACEHOLDER",
  "id": {
    "fromMe": true,
    "remote": "000000000000@c.us",
    "id": "MSG_ID_123456",
    "_serialized": "true_000000000000@c.us_MSG_ID_123456"
  },
  "ack": 0,
  "hasMedia": true,
  "body": "Here's your requested image.",
  "type": "image",
  "timestamp": 1759108866,
  "from": "111111111111@c.us",
  "to": "000000000000@c.us",
  "deviceType": "android",
  "isForwarded": false,
  "forwardingScore": 0,
  "isStatus": false,
  "isStarred": false,
  "fromMe": true,
  "hasQuotedMsg": false,
  "hasReaction": false,
  "vCards": [],
  "mentionedIds": [],
  "groupMentions": [],
  "isGif": false,
  "links": []
}
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (Plain Text)</summary>

```json
"Success: Operation completed successfully."
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Missing Required Parameter(s)</summary>

```json
{
  "code": "missing_param",
  "message": "Missing required parameter: {parameterName}",
  "details": {
    "missing": [
      "{parameterName}"
    ],
    "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Invalid Number (Egypt)</summary>

```json
{
  "code": "invalid_chat_id",
  "message": "Egypt mobile numbers must be 11 digits (national format).",
  "details": {
    "provided": "20114520282",
    "recommendation": "Example: 201012345678 (12 digits total starting with 20)",
    "info": {
      "country": "EG",
      "type": "MOBILE"
    }
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Invalid Number (Saudi Arabia)</summary>

```json
{
  "code": "invalid_chat_id",
  "message": "Invalid phone number format for SA.",
  "details": {
    "provided": "96655555",
    "recommendation": "Saudi numbers must start with 966 followed by 5 and 8 digits (12 digits total). Example: 966501234567",
    "info": {
      "country": "SA"
    }
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Invalid Number (Unknown)</summary>

```json
{
  "code": "invalid_chat_id",
  "message": "Invalid phone number format for Unknown.",
  "details": {
    "provided": "01145202826",
    "recommendation": "Ensure individual numbers are in international format (starting with country code).",
    "info": {
      "country": "Unknown"
    }
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (Plain Text)</summary>

```json
"Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized - Invalid or Missing Access Token</summary>

```json
{
  "code": "invalid_access_token",
  "message": "Invalid or expired access token. Please check your credentials.",
  "details": {
    "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
  }
}
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found - Session Does Not Exist</summary>

```json
{
  "code": "invalid_session",
  "message": "Session not found. Please verify your instance_id or session_name.",
  "details": {
    "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
  }
}
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 429</b>: Too Many Requests - Rate Limit Exceeded</summary>

```json
{
  "code": "rate_limit_exceeded",
  "message": "Too many requests. Please slow down.",
  "details": {
    "retryAfter": 60,
    "recommendation": "Implement a retry strategy with exponential backoff or reduce the frequency of your requests.",
    "upstream": {
      "error": "Rate limit",
      "statusCode": 429
    }
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error - Unexpected Failure</summary>

```json
{
  "code": "server_error",
  "message": "An internal server error occurred. Please try again later.",
  "details": {
    "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error (HTML)</summary>

```json
"<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway - Connection Failed to Upstream</summary>

```json
{
  "code": "proxy_error",
  "message": "Failed to connect to WhatsApp server.",
  "details": {
    "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
  }
}
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
```

</details>

### Send Event
**Endpoint:** `POST /v2/send/event`

Sends a calendar event message to a chat. Users can tap on the event to view details, add it to their calendar, or join a call.

#### 💡 Tips
- **Unix Timestamps**: Double-check your timestamp logic. Ensure you are sending seconds (e.g. 1735920000) not milliseconds.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| instance_id | string | Yes | Unique ID of the WhatsApp session |
| access_token | string | Yes | API access token |
| chatId | string | Yes | Recipient's WhatsApp number |
| event.name | string | Yes | Name of the event (e.g. Team Meeting 📅) |
| event.description | string | Yes | Discussing Q1 Roadmap |
| event.startTime | number | Yes | Start time (Unix timestamp in seconds) |
| event.endTime | number | Yes | End time (Unix timestamp in seconds) |
| event.location.name | string | Yes | Meeting Room A |
| event.extraGuestsAllowed | boolean | Yes | Whether extra guests are allowed |
| reply_to | string | No | The ID of the message you are replying to |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Message Sent Successfully</summary>

```json
{
  "_data": {
    "id": {
      "fromMe": true,
      "remote": "000000000000@c.us",
      "id": "MSG_ID_123456",
      "_serialized": "true_000000000000@c.us_MSG_ID_123456"
    },
    "viewed": false,
    "body": "BASE64_IMAGE_DATA",
    "type": "image",
    "t": 1759108866,
    "from": {
      "server": "c.us",
      "user": "111111111111",
      "_serialized": "111111111111@c.us"
    },
    "to": {
      "server": "c.us",
      "user": "000000000000",
      "_serialized": "000000000000@c.us"
    },
    "ack": 0,
    "isNewMsg": true,
    "star": false,
    "kicNotified": false,
    "caption": "Here's your requested image.",
    "deprecatedMms3Url": "https://example.com/media-url",
    "directPath": "/media/direct/path/example",
    "mimetype": "image/jpeg",
    "filehash": "FILE_HASH_PLACEHOLDER",
    "encFilehash": "ENC_FILE_HASH_PLACEHOLDER",
    "size": 192487,
    "mediaKey": "MEDIA_KEY_PLACEHOLDER",
    "mediaKeyTimestamp": 1759108865,
    "streamable": false,
    "mediaHandle": null,
    "isFromTemplate": false,
    "pollInvalidated": false,
    "isSentCagPollCreation": false,
    "latestEditMsgKey": null,
    "latestEditSenderTimestampMs": null,
    "mentionedJidList": [],
    "groupMentions": [],
    "isEventCanceled": false,
    "eventInvalidated": false,
    "isVcardOverMmsDocument": false,
    "isForwarded": false,
    "isQuestion": false,
    "questionReplyQuotedMessage": null,
    "questionResponsesCount": 0,
    "readQuestionResponsesCount": 0,
    "labels": [],
    "hasReaction": false,
    "disappearingModeInitiator": "chat",
    "disappearingModeTrigger": "chat_settings",
    "productHeaderImageRejected": false,
    "lastPlaybackProgress": 0,
    "isDynamicReplyButtonsMsg": false,
    "isCarouselCard": false,
    "parentMsgId": null,
    "callSilenceReason": null,
    "isVideoCall": false,
    "callDuration": null,
    "callCreator": null,
    "callParticipants": null,
    "isCallLink": null,
    "callLinkToken": null,
    "isMdHistoryMsg": false,
    "stickerSentTs": 0,
    "lastUpdateFromServerTs": 0,
    "invokedBotWid": null,
    "bizBotType": null,
    "botResponseTargetId": null,
    "botPluginType": null,
    "botPluginReferenceIndex": null,
    "botPluginSearchProvider": null,
    "botPluginSearchUrl": null,
    "botPluginSearchQuery": null,
    "botPluginMaybeParent": false,
    "botReelPluginThumbnailCdnUrl": null,
    "botMessageDisclaimerText": null,
    "botMsgBodyType": null,
    "requiresDirectConnection": false,
    "bizContentPlaceholderType": null,
    "hostedBizEncStateMismatch": false,
    "senderOrRecipientAccountTypeHosted": false,
    "placeholderCreatedWhenAccountIsHosted": false,
    "galaxyFlowDisabled": false,
    "links": []
  },
  "mediaKey": "MEDIA_KEY_PLACEHOLDER",
  "id": {
    "fromMe": true,
    "remote": "000000000000@c.us",
    "id": "MSG_ID_123456",
    "_serialized": "true_000000000000@c.us_MSG_ID_123456"
  },
  "ack": 0,
  "hasMedia": true,
  "body": "Here's your requested image.",
  "type": "image",
  "timestamp": 1759108866,
  "from": "111111111111@c.us",
  "to": "000000000000@c.us",
  "deviceType": "android",
  "isForwarded": false,
  "forwardingScore": 0,
  "isStatus": false,
  "isStarred": false,
  "fromMe": true,
  "hasQuotedMsg": false,
  "hasReaction": false,
  "vCards": [],
  "mentionedIds": [],
  "groupMentions": [],
  "isGif": false,
  "links": []
}
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (Plain Text)</summary>

```json
"Success: Operation completed successfully."
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Missing Required Parameter(s)</summary>

```json
{
  "code": "missing_param",
  "message": "Missing required parameter: {parameterName}",
  "details": {
    "missing": [
      "{parameterName}"
    ],
    "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Invalid Number (Egypt)</summary>

```json
{
  "code": "invalid_chat_id",
  "message": "Egypt mobile numbers must be 11 digits (national format).",
  "details": {
    "provided": "20114520282",
    "recommendation": "Example: 201012345678 (12 digits total starting with 20)",
    "info": {
      "country": "EG",
      "type": "MOBILE"
    }
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Invalid Number (Saudi Arabia)</summary>

```json
{
  "code": "invalid_chat_id",
  "message": "Invalid phone number format for SA.",
  "details": {
    "provided": "96655555",
    "recommendation": "Saudi numbers must start with 966 followed by 5 and 8 digits (12 digits total). Example: 966501234567",
    "info": {
      "country": "SA"
    }
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Invalid Number (Unknown)</summary>

```json
{
  "code": "invalid_chat_id",
  "message": "Invalid phone number format for Unknown.",
  "details": {
    "provided": "01145202826",
    "recommendation": "Ensure individual numbers are in international format (starting with country code).",
    "info": {
      "country": "Unknown"
    }
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (Plain Text)</summary>

```json
"Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized - Invalid or Missing Access Token</summary>

```json
{
  "code": "invalid_access_token",
  "message": "Invalid or expired access token. Please check your credentials.",
  "details": {
    "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
  }
}
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found - Session Does Not Exist</summary>

```json
{
  "code": "invalid_session",
  "message": "Session not found. Please verify your instance_id or session_name.",
  "details": {
    "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
  }
}
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 429</b>: Too Many Requests - Rate Limit Exceeded</summary>

```json
{
  "code": "rate_limit_exceeded",
  "message": "Too many requests. Please slow down.",
  "details": {
    "retryAfter": 60,
    "recommendation": "Implement a retry strategy with exponential backoff or reduce the frequency of your requests.",
    "upstream": {
      "error": "Rate limit",
      "statusCode": 429
    }
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error - Unexpected Failure</summary>

```json
{
  "code": "server_error",
  "message": "An internal server error occurred. Please try again later.",
  "details": {
    "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error (HTML)</summary>

```json
"<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway - Connection Failed to Upstream</summary>

```json
{
  "code": "proxy_error",
  "message": "Failed to connect to WhatsApp server.",
  "details": {
    "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
  }
}
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
```

</details>

### Send Voice
**Endpoint:** `POST, GET /v2/send/voice`

Voice messages accept OGG/Opus. Required params: instance_id, access_token, chatId, file[url], file[filename], file[mimetype], convert.

#### 💡 Tips
- **Format**: Requires OGG format with Opus codec for PTT (Push-to-Talk) styling.
- **Experience**: Appears as a playable waveform in the chat.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| instance_id | string | Yes | Unique ID of the WhatsApp session |
| access_token | string | Yes | API access token |
| chatId | string | Yes | Recipient's WhatsApp ID (JID). Supports Individuals (@c.us), Groups (@g.us), and Newsletters (@newsletter). |
| file[url] | string | Yes | Publicly accessible HTTPS URL of the audio file |
| file[filename] | string | Yes | Filename for the audio note |
| file[mimetype] | string | Yes | MIME type (audio/ogg; codecs=opus recommended) |
| convert | boolean | Yes | Automatically transcode to WhatsApp compatible OGG/Opus |
| reply_to | string | No | The ID of the message you are replying to |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Message Sent Successfully</summary>

```json
{
  "_data": {
    "id": {
      "fromMe": true,
      "remote": "000000000000@c.us",
      "id": "MSG_ID_123456",
      "_serialized": "true_000000000000@c.us_MSG_ID_123456"
    },
    "viewed": false,
    "body": "BASE64_IMAGE_DATA",
    "type": "image",
    "t": 1759108866,
    "from": {
      "server": "c.us",
      "user": "111111111111",
      "_serialized": "111111111111@c.us"
    },
    "to": {
      "server": "c.us",
      "user": "000000000000",
      "_serialized": "000000000000@c.us"
    },
    "ack": 0,
    "isNewMsg": true,
    "star": false,
    "kicNotified": false,
    "caption": "Here's your requested image.",
    "deprecatedMms3Url": "https://example.com/media-url",
    "directPath": "/media/direct/path/example",
    "mimetype": "image/jpeg",
    "filehash": "FILE_HASH_PLACEHOLDER",
    "encFilehash": "ENC_FILE_HASH_PLACEHOLDER",
    "size": 192487,
    "mediaKey": "MEDIA_KEY_PLACEHOLDER",
    "mediaKeyTimestamp": 1759108865,
    "streamable": false,
    "mediaHandle": null,
    "isFromTemplate": false,
    "pollInvalidated": false,
    "isSentCagPollCreation": false,
    "latestEditMsgKey": null,
    "latestEditSenderTimestampMs": null,
    "mentionedJidList": [],
    "groupMentions": [],
    "isEventCanceled": false,
    "eventInvalidated": false,
    "isVcardOverMmsDocument": false,
    "isForwarded": false,
    "isQuestion": false,
    "questionReplyQuotedMessage": null,
    "questionResponsesCount": 0,
    "readQuestionResponsesCount": 0,
    "labels": [],
    "hasReaction": false,
    "disappearingModeInitiator": "chat",
    "disappearingModeTrigger": "chat_settings",
    "productHeaderImageRejected": false,
    "lastPlaybackProgress": 0,
    "isDynamicReplyButtonsMsg": false,
    "isCarouselCard": false,
    "parentMsgId": null,
    "callSilenceReason": null,
    "isVideoCall": false,
    "callDuration": null,
    "callCreator": null,
    "callParticipants": null,
    "isCallLink": null,
    "callLinkToken": null,
    "isMdHistoryMsg": false,
    "stickerSentTs": 0,
    "lastUpdateFromServerTs": 0,
    "invokedBotWid": null,
    "bizBotType": null,
    "botResponseTargetId": null,
    "botPluginType": null,
    "botPluginReferenceIndex": null,
    "botPluginSearchProvider": null,
    "botPluginSearchUrl": null,
    "botPluginSearchQuery": null,
    "botPluginMaybeParent": false,
    "botReelPluginThumbnailCdnUrl": null,
    "botMessageDisclaimerText": null,
    "botMsgBodyType": null,
    "requiresDirectConnection": false,
    "bizContentPlaceholderType": null,
    "hostedBizEncStateMismatch": false,
    "senderOrRecipientAccountTypeHosted": false,
    "placeholderCreatedWhenAccountIsHosted": false,
    "galaxyFlowDisabled": false,
    "links": []
  },
  "mediaKey": "MEDIA_KEY_PLACEHOLDER",
  "id": {
    "fromMe": true,
    "remote": "000000000000@c.us",
    "id": "MSG_ID_123456",
    "_serialized": "true_000000000000@c.us_MSG_ID_123456"
  },
  "ack": 0,
  "hasMedia": true,
  "body": "Here's your requested image.",
  "type": "image",
  "timestamp": 1759108866,
  "from": "111111111111@c.us",
  "to": "000000000000@c.us",
  "deviceType": "android",
  "isForwarded": false,
  "forwardingScore": 0,
  "isStatus": false,
  "isStarred": false,
  "fromMe": true,
  "hasQuotedMsg": false,
  "hasReaction": false,
  "vCards": [],
  "mentionedIds": [],
  "groupMentions": [],
  "isGif": false,
  "links": []
}
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (Plain Text)</summary>

```json
"Success: Operation completed successfully."
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Missing Required Parameter(s)</summary>

```json
{
  "code": "missing_param",
  "message": "Missing required parameter: {parameterName}",
  "details": {
    "missing": [
      "{parameterName}"
    ],
    "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Invalid Number (Egypt)</summary>

```json
{
  "code": "invalid_chat_id",
  "message": "Egypt mobile numbers must be 11 digits (national format).",
  "details": {
    "provided": "20114520282",
    "recommendation": "Example: 201012345678 (12 digits total starting with 20)",
    "info": {
      "country": "EG",
      "type": "MOBILE"
    }
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Invalid Number (Saudi Arabia)</summary>

```json
{
  "code": "invalid_chat_id",
  "message": "Invalid phone number format for SA.",
  "details": {
    "provided": "96655555",
    "recommendation": "Saudi numbers must start with 966 followed by 5 and 8 digits (12 digits total). Example: 966501234567",
    "info": {
      "country": "SA"
    }
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Invalid Number (Unknown)</summary>

```json
{
  "code": "invalid_chat_id",
  "message": "Invalid phone number format for Unknown.",
  "details": {
    "provided": "01145202826",
    "recommendation": "Ensure individual numbers are in international format (starting with country code).",
    "info": {
      "country": "Unknown"
    }
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (Plain Text)</summary>

```json
"Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized - Invalid or Missing Access Token</summary>

```json
{
  "code": "invalid_access_token",
  "message": "Invalid or expired access token. Please check your credentials.",
  "details": {
    "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
  }
}
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found - Session Does Not Exist</summary>

```json
{
  "code": "invalid_session",
  "message": "Session not found. Please verify your instance_id or session_name.",
  "details": {
    "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
  }
}
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 429</b>: Too Many Requests - Rate Limit Exceeded</summary>

```json
{
  "code": "rate_limit_exceeded",
  "message": "Too many requests. Please slow down.",
  "details": {
    "retryAfter": 60,
    "recommendation": "Implement a retry strategy with exponential backoff or reduce the frequency of your requests.",
    "upstream": {
      "error": "Rate limit",
      "statusCode": 429
    }
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error - Unexpected Failure</summary>

```json
{
  "code": "server_error",
  "message": "An internal server error occurred. Please try again later.",
  "details": {
    "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error (HTML)</summary>

```json
"<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway - Connection Failed to Upstream</summary>

```json
{
  "code": "proxy_error",
  "message": "Failed to connect to WhatsApp server.",
  "details": {
    "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
  }
}
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
```

</details>

### Send Video
**Endpoint:** `POST, GET /v2/send/video`

Send a video file to a chat.

#### 💡 Tips
- **Auto-Download**: Most users have auto-download enabled for videos on Wi-Fi but disabled on data. Consider this for your marketing hooks.
- **Compression**: Sending raw 4K video is not recommended. Pre-compress your videos to 720p or 480p.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| instance_id | string | Yes | Your unique WhatsApp Instance ID |
| access_token | string | Yes | Your API Access Token |
| chatId | string | Yes | Recipient's WhatsApp ID (JID). Supports Individuals (@c.us), Groups (@g.us), and Newsletters (@newsletter). |
| caption | string | Yes | Video caption |
| convert | boolean | Yes | Attempt to convert video to compatible MP4 if needed |
| asNote | boolean | Yes | Send as a round 'Video Note' (if supported by engine) |
| file[url] | string | Yes | Publicly accessible URL of the video |
| file[filename] | string | Yes | Filename for the video |
| file[mimetype] | string | Yes | MIME type of the video |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Message Sent Successfully</summary>

```json
{
  "_data": {
    "id": {
      "fromMe": true,
      "remote": "000000000000@c.us",
      "id": "MSG_ID_123456",
      "_serialized": "true_000000000000@c.us_MSG_ID_123456"
    },
    "viewed": false,
    "body": "BASE64_IMAGE_DATA",
    "type": "image",
    "t": 1759108866,
    "from": {
      "server": "c.us",
      "user": "111111111111",
      "_serialized": "111111111111@c.us"
    },
    "to": {
      "server": "c.us",
      "user": "000000000000",
      "_serialized": "000000000000@c.us"
    },
    "ack": 0,
    "isNewMsg": true,
    "star": false,
    "kicNotified": false,
    "caption": "Here's your requested image.",
    "deprecatedMms3Url": "https://example.com/media-url",
    "directPath": "/media/direct/path/example",
    "mimetype": "image/jpeg",
    "filehash": "FILE_HASH_PLACEHOLDER",
    "encFilehash": "ENC_FILE_HASH_PLACEHOLDER",
    "size": 192487,
    "mediaKey": "MEDIA_KEY_PLACEHOLDER",
    "mediaKeyTimestamp": 1759108865,
    "streamable": false,
    "mediaHandle": null,
    "isFromTemplate": false,
    "pollInvalidated": false,
    "isSentCagPollCreation": false,
    "latestEditMsgKey": null,
    "latestEditSenderTimestampMs": null,
    "mentionedJidList": [],
    "groupMentions": [],
    "isEventCanceled": false,
    "eventInvalidated": false,
    "isVcardOverMmsDocument": false,
    "isForwarded": false,
    "isQuestion": false,
    "questionReplyQuotedMessage": null,
    "questionResponsesCount": 0,
    "readQuestionResponsesCount": 0,
    "labels": [],
    "hasReaction": false,
    "disappearingModeInitiator": "chat",
    "disappearingModeTrigger": "chat_settings",
    "productHeaderImageRejected": false,
    "lastPlaybackProgress": 0,
    "isDynamicReplyButtonsMsg": false,
    "isCarouselCard": false,
    "parentMsgId": null,
    "callSilenceReason": null,
    "isVideoCall": false,
    "callDuration": null,
    "callCreator": null,
    "callParticipants": null,
    "isCallLink": null,
    "callLinkToken": null,
    "isMdHistoryMsg": false,
    "stickerSentTs": 0,
    "lastUpdateFromServerTs": 0,
    "invokedBotWid": null,
    "bizBotType": null,
    "botResponseTargetId": null,
    "botPluginType": null,
    "botPluginReferenceIndex": null,
    "botPluginSearchProvider": null,
    "botPluginSearchUrl": null,
    "botPluginSearchQuery": null,
    "botPluginMaybeParent": false,
    "botReelPluginThumbnailCdnUrl": null,
    "botMessageDisclaimerText": null,
    "botMsgBodyType": null,
    "requiresDirectConnection": false,
    "bizContentPlaceholderType": null,
    "hostedBizEncStateMismatch": false,
    "senderOrRecipientAccountTypeHosted": false,
    "placeholderCreatedWhenAccountIsHosted": false,
    "galaxyFlowDisabled": false,
    "links": []
  },
  "mediaKey": "MEDIA_KEY_PLACEHOLDER",
  "id": {
    "fromMe": true,
    "remote": "000000000000@c.us",
    "id": "MSG_ID_123456",
    "_serialized": "true_000000000000@c.us_MSG_ID_123456"
  },
  "ack": 0,
  "hasMedia": true,
  "body": "Here's your requested image.",
  "type": "image",
  "timestamp": 1759108866,
  "from": "111111111111@c.us",
  "to": "000000000000@c.us",
  "deviceType": "android",
  "isForwarded": false,
  "forwardingScore": 0,
  "isStatus": false,
  "isStarred": false,
  "fromMe": true,
  "hasQuotedMsg": false,
  "hasReaction": false,
  "vCards": [],
  "mentionedIds": [],
  "groupMentions": [],
  "isGif": false,
  "links": []
}
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (Plain Text)</summary>

```json
"Success: Operation completed successfully."
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Missing Required Parameter(s)</summary>

```json
{
  "code": "missing_param",
  "message": "Missing required parameter: {parameterName}",
  "details": {
    "missing": [
      "{parameterName}"
    ],
    "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Invalid Number (Egypt)</summary>

```json
{
  "code": "invalid_chat_id",
  "message": "Egypt mobile numbers must be 11 digits (national format).",
  "details": {
    "provided": "20114520282",
    "recommendation": "Example: 201012345678 (12 digits total starting with 20)",
    "info": {
      "country": "EG",
      "type": "MOBILE"
    }
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Invalid Number (Saudi Arabia)</summary>

```json
{
  "code": "invalid_chat_id",
  "message": "Invalid phone number format for SA.",
  "details": {
    "provided": "96655555",
    "recommendation": "Saudi numbers must start with 966 followed by 5 and 8 digits (12 digits total). Example: 966501234567",
    "info": {
      "country": "SA"
    }
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Invalid Number (Unknown)</summary>

```json
{
  "code": "invalid_chat_id",
  "message": "Invalid phone number format for Unknown.",
  "details": {
    "provided": "01145202826",
    "recommendation": "Ensure individual numbers are in international format (starting with country code).",
    "info": {
      "country": "Unknown"
    }
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (Plain Text)</summary>

```json
"Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized - Invalid or Missing Access Token</summary>

```json
{
  "code": "invalid_access_token",
  "message": "Invalid or expired access token. Please check your credentials.",
  "details": {
    "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
  }
}
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found - Session Does Not Exist</summary>

```json
{
  "code": "invalid_session",
  "message": "Session not found. Please verify your instance_id or session_name.",
  "details": {
    "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
  }
}
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 429</b>: Too Many Requests - Rate Limit Exceeded</summary>

```json
{
  "code": "rate_limit_exceeded",
  "message": "Too many requests. Please slow down.",
  "details": {
    "retryAfter": 60,
    "recommendation": "Implement a retry strategy with exponential backoff or reduce the frequency of your requests.",
    "upstream": {
      "error": "Rate limit",
      "statusCode": 429
    }
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error - Unexpected Failure</summary>

```json
{
  "code": "server_error",
  "message": "An internal server error occurred. Please try again later.",
  "details": {
    "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error (HTML)</summary>

```json
"<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway - Connection Failed to Upstream</summary>

```json
{
  "code": "proxy_error",
  "message": "Failed to connect to WhatsApp server.",
  "details": {
    "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
  }
}
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
```

</details>

### Send Link Preview
**Endpoint:** `POST, GET /v2/send/link-preview`

Send a message with a custom rich link preview card.

#### 💡 Tips
- **Marketing Power**: Use custom titles and descriptions to create compelling Call-to-Actions (CTAs) that standard links cannot provide.
- **High Quality Flag**: The `linkPreviewHighQuality` flag attempts to render a larger image card, which takes more visual space in the chat.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| instance_id | string | Yes | Your unique WhatsApp Instance ID |
| access_token | string | Yes | Your API Access Token |
| chatId | string | Yes | Target phone number with country code |
| url | string | Yes | The URL to preview |
| text | string | Yes | Optional text message accompanying the link. |
| thumbnail | string | Yes | URL for a custom thumbnail image (JPEG/PNG) |
| title | string | Yes | Custom title for the preview card |
| description | string | Yes | Custom description for the preview card |
| linkPreviewHighQuality | boolean | Yes | Try to generate a larger, high-quality preview |
| reply_to | string | No | The ID of a message to reply to |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Message Sent Successfully</summary>

```json
{
  "_data": {
    "id": {
      "fromMe": true,
      "remote": "000000000000@c.us",
      "id": "MSG_ID_123456",
      "_serialized": "true_000000000000@c.us_MSG_ID_123456"
    },
    "viewed": false,
    "body": "BASE64_IMAGE_DATA",
    "type": "image",
    "t": 1759108866,
    "from": {
      "server": "c.us",
      "user": "111111111111",
      "_serialized": "111111111111@c.us"
    },
    "to": {
      "server": "c.us",
      "user": "000000000000",
      "_serialized": "000000000000@c.us"
    },
    "ack": 0,
    "isNewMsg": true,
    "star": false,
    "kicNotified": false,
    "caption": "Here's your requested image.",
    "deprecatedMms3Url": "https://example.com/media-url",
    "directPath": "/media/direct/path/example",
    "mimetype": "image/jpeg",
    "filehash": "FILE_HASH_PLACEHOLDER",
    "encFilehash": "ENC_FILE_HASH_PLACEHOLDER",
    "size": 192487,
    "mediaKey": "MEDIA_KEY_PLACEHOLDER",
    "mediaKeyTimestamp": 1759108865,
    "streamable": false,
    "mediaHandle": null,
    "isFromTemplate": false,
    "pollInvalidated": false,
    "isSentCagPollCreation": false,
    "latestEditMsgKey": null,
    "latestEditSenderTimestampMs": null,
    "mentionedJidList": [],
    "groupMentions": [],
    "isEventCanceled": false,
    "eventInvalidated": false,
    "isVcardOverMmsDocument": false,
    "isForwarded": false,
    "isQuestion": false,
    "questionReplyQuotedMessage": null,
    "questionResponsesCount": 0,
    "readQuestionResponsesCount": 0,
    "labels": [],
    "hasReaction": false,
    "disappearingModeInitiator": "chat",
    "disappearingModeTrigger": "chat_settings",
    "productHeaderImageRejected": false,
    "lastPlaybackProgress": 0,
    "isDynamicReplyButtonsMsg": false,
    "isCarouselCard": false,
    "parentMsgId": null,
    "callSilenceReason": null,
    "isVideoCall": false,
    "callDuration": null,
    "callCreator": null,
    "callParticipants": null,
    "isCallLink": null,
    "callLinkToken": null,
    "isMdHistoryMsg": false,
    "stickerSentTs": 0,
    "lastUpdateFromServerTs": 0,
    "invokedBotWid": null,
    "bizBotType": null,
    "botResponseTargetId": null,
    "botPluginType": null,
    "botPluginReferenceIndex": null,
    "botPluginSearchProvider": null,
    "botPluginSearchUrl": null,
    "botPluginSearchQuery": null,
    "botPluginMaybeParent": false,
    "botReelPluginThumbnailCdnUrl": null,
    "botMessageDisclaimerText": null,
    "botMsgBodyType": null,
    "requiresDirectConnection": false,
    "bizContentPlaceholderType": null,
    "hostedBizEncStateMismatch": false,
    "senderOrRecipientAccountTypeHosted": false,
    "placeholderCreatedWhenAccountIsHosted": false,
    "galaxyFlowDisabled": false,
    "links": []
  },
  "mediaKey": "MEDIA_KEY_PLACEHOLDER",
  "id": {
    "fromMe": true,
    "remote": "000000000000@c.us",
    "id": "MSG_ID_123456",
    "_serialized": "true_000000000000@c.us_MSG_ID_123456"
  },
  "ack": 0,
  "hasMedia": true,
  "body": "Here's your requested image.",
  "type": "image",
  "timestamp": 1759108866,
  "from": "111111111111@c.us",
  "to": "000000000000@c.us",
  "deviceType": "android",
  "isForwarded": false,
  "forwardingScore": 0,
  "isStatus": false,
  "isStarred": false,
  "fromMe": true,
  "hasQuotedMsg": false,
  "hasReaction": false,
  "vCards": [],
  "mentionedIds": [],
  "groupMentions": [],
  "isGif": false,
  "links": []
}
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (Plain Text)</summary>

```json
"Success: Operation completed successfully."
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Missing Required Parameter(s)</summary>

```json
{
  "code": "missing_param",
  "message": "Missing required parameter: {parameterName}",
  "details": {
    "missing": [
      "{parameterName}"
    ],
    "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Invalid Number (Egypt)</summary>

```json
{
  "code": "invalid_chat_id",
  "message": "Egypt mobile numbers must be 11 digits (national format).",
  "details": {
    "provided": "20114520282",
    "recommendation": "Example: 201012345678 (12 digits total starting with 20)",
    "info": {
      "country": "EG",
      "type": "MOBILE"
    }
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Invalid Number (Saudi Arabia)</summary>

```json
{
  "code": "invalid_chat_id",
  "message": "Invalid phone number format for SA.",
  "details": {
    "provided": "96655555",
    "recommendation": "Saudi numbers must start with 966 followed by 5 and 8 digits (12 digits total). Example: 966501234567",
    "info": {
      "country": "SA"
    }
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Invalid Number (Unknown)</summary>

```json
{
  "code": "invalid_chat_id",
  "message": "Invalid phone number format for Unknown.",
  "details": {
    "provided": "01145202826",
    "recommendation": "Ensure individual numbers are in international format (starting with country code).",
    "info": {
      "country": "Unknown"
    }
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (Plain Text)</summary>

```json
"Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized - Invalid or Missing Access Token</summary>

```json
{
  "code": "invalid_access_token",
  "message": "Invalid or expired access token. Please check your credentials.",
  "details": {
    "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
  }
}
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found - Session Does Not Exist</summary>

```json
{
  "code": "invalid_session",
  "message": "Session not found. Please verify your instance_id or session_name.",
  "details": {
    "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
  }
}
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 429</b>: Too Many Requests - Rate Limit Exceeded</summary>

```json
{
  "code": "rate_limit_exceeded",
  "message": "Too many requests. Please slow down.",
  "details": {
    "retryAfter": 60,
    "recommendation": "Implement a retry strategy with exponential backoff or reduce the frequency of your requests.",
    "upstream": {
      "error": "Rate limit",
      "statusCode": 429
    }
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error - Unexpected Failure</summary>

```json
{
  "code": "server_error",
  "message": "An internal server error occurred. Please try again later.",
  "details": {
    "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error (HTML)</summary>

```json
"<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway - Connection Failed to Upstream</summary>

```json
{
  "code": "proxy_error",
  "message": "Failed to connect to WhatsApp server.",
  "details": {
    "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
  }
}
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
```

</details>

### Send Location
**Endpoint:** `POST, GET /v2/send/location`

Send a static geographic location to a chat.

#### 💡 Tips
- **Exact Coordinates**: Always Use GPS-accurate decimal coordinates. Avoid rounding to ensure the pin lands exactly on the right roof.
- **Apple/Google Maps**: The "title" and "message" fields often appear as the label in the recipient's map app.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| instance_id | string | Yes | Unique ID of the WhatsApp session |
| access_token | string | Yes | API access token |
| chatId | string | Yes | Recipient's WhatsApp number |
| latitude | string | Yes | Geographic latitude (e.g. 38.8937255) |
| longitude | string | Yes | Geographic longitude (e.g. -77.0969763) |
| title | string | Yes | Name of the place (e.g., 'Our Office') |
| message | string | Yes | Address or additional description text |
| reply_to | string | No | Message ID to reply to |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Message Sent Successfully</summary>

```json
{
  "_data": {
    "id": {
      "fromMe": true,
      "remote": "000000000000@c.us",
      "id": "MSG_ID_123456",
      "_serialized": "true_000000000000@c.us_MSG_ID_123456"
    },
    "viewed": false,
    "body": "BASE64_IMAGE_DATA",
    "type": "image",
    "t": 1759108866,
    "from": {
      "server": "c.us",
      "user": "111111111111",
      "_serialized": "111111111111@c.us"
    },
    "to": {
      "server": "c.us",
      "user": "000000000000",
      "_serialized": "000000000000@c.us"
    },
    "ack": 0,
    "isNewMsg": true,
    "star": false,
    "kicNotified": false,
    "caption": "Here's your requested image.",
    "deprecatedMms3Url": "https://example.com/media-url",
    "directPath": "/media/direct/path/example",
    "mimetype": "image/jpeg",
    "filehash": "FILE_HASH_PLACEHOLDER",
    "encFilehash": "ENC_FILE_HASH_PLACEHOLDER",
    "size": 192487,
    "mediaKey": "MEDIA_KEY_PLACEHOLDER",
    "mediaKeyTimestamp": 1759108865,
    "streamable": false,
    "mediaHandle": null,
    "isFromTemplate": false,
    "pollInvalidated": false,
    "isSentCagPollCreation": false,
    "latestEditMsgKey": null,
    "latestEditSenderTimestampMs": null,
    "mentionedJidList": [],
    "groupMentions": [],
    "isEventCanceled": false,
    "eventInvalidated": false,
    "isVcardOverMmsDocument": false,
    "isForwarded": false,
    "isQuestion": false,
    "questionReplyQuotedMessage": null,
    "questionResponsesCount": 0,
    "readQuestionResponsesCount": 0,
    "labels": [],
    "hasReaction": false,
    "disappearingModeInitiator": "chat",
    "disappearingModeTrigger": "chat_settings",
    "productHeaderImageRejected": false,
    "lastPlaybackProgress": 0,
    "isDynamicReplyButtonsMsg": false,
    "isCarouselCard": false,
    "parentMsgId": null,
    "callSilenceReason": null,
    "isVideoCall": false,
    "callDuration": null,
    "callCreator": null,
    "callParticipants": null,
    "isCallLink": null,
    "callLinkToken": null,
    "isMdHistoryMsg": false,
    "stickerSentTs": 0,
    "lastUpdateFromServerTs": 0,
    "invokedBotWid": null,
    "bizBotType": null,
    "botResponseTargetId": null,
    "botPluginType": null,
    "botPluginReferenceIndex": null,
    "botPluginSearchProvider": null,
    "botPluginSearchUrl": null,
    "botPluginSearchQuery": null,
    "botPluginMaybeParent": false,
    "botReelPluginThumbnailCdnUrl": null,
    "botMessageDisclaimerText": null,
    "botMsgBodyType": null,
    "requiresDirectConnection": false,
    "bizContentPlaceholderType": null,
    "hostedBizEncStateMismatch": false,
    "senderOrRecipientAccountTypeHosted": false,
    "placeholderCreatedWhenAccountIsHosted": false,
    "galaxyFlowDisabled": false,
    "links": []
  },
  "mediaKey": "MEDIA_KEY_PLACEHOLDER",
  "id": {
    "fromMe": true,
    "remote": "000000000000@c.us",
    "id": "MSG_ID_123456",
    "_serialized": "true_000000000000@c.us_MSG_ID_123456"
  },
  "ack": 0,
  "hasMedia": true,
  "body": "Here's your requested image.",
  "type": "image",
  "timestamp": 1759108866,
  "from": "111111111111@c.us",
  "to": "000000000000@c.us",
  "deviceType": "android",
  "isForwarded": false,
  "forwardingScore": 0,
  "isStatus": false,
  "isStarred": false,
  "fromMe": true,
  "hasQuotedMsg": false,
  "hasReaction": false,
  "vCards": [],
  "mentionedIds": [],
  "groupMentions": [],
  "isGif": false,
  "links": []
}
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (Plain Text)</summary>

```json
"Success: Operation completed successfully."
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Missing Required Parameter(s)</summary>

```json
{
  "code": "missing_param",
  "message": "Missing required parameter: {parameterName}",
  "details": {
    "missing": [
      "{parameterName}"
    ],
    "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Invalid Number (Egypt)</summary>

```json
{
  "code": "invalid_chat_id",
  "message": "Egypt mobile numbers must be 11 digits (national format).",
  "details": {
    "provided": "20114520282",
    "recommendation": "Example: 201012345678 (12 digits total starting with 20)",
    "info": {
      "country": "EG",
      "type": "MOBILE"
    }
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Invalid Number (Saudi Arabia)</summary>

```json
{
  "code": "invalid_chat_id",
  "message": "Invalid phone number format for SA.",
  "details": {
    "provided": "96655555",
    "recommendation": "Saudi numbers must start with 966 followed by 5 and 8 digits (12 digits total). Example: 966501234567",
    "info": {
      "country": "SA"
    }
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Invalid Number (Unknown)</summary>

```json
{
  "code": "invalid_chat_id",
  "message": "Invalid phone number format for Unknown.",
  "details": {
    "provided": "01145202826",
    "recommendation": "Ensure individual numbers are in international format (starting with country code).",
    "info": {
      "country": "Unknown"
    }
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (Plain Text)</summary>

```json
"Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized - Invalid or Missing Access Token</summary>

```json
{
  "code": "invalid_access_token",
  "message": "Invalid or expired access token. Please check your credentials.",
  "details": {
    "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
  }
}
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found - Session Does Not Exist</summary>

```json
{
  "code": "invalid_session",
  "message": "Session not found. Please verify your instance_id or session_name.",
  "details": {
    "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
  }
}
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 429</b>: Too Many Requests - Rate Limit Exceeded</summary>

```json
{
  "code": "rate_limit_exceeded",
  "message": "Too many requests. Please slow down.",
  "details": {
    "retryAfter": 60,
    "recommendation": "Implement a retry strategy with exponential backoff or reduce the frequency of your requests.",
    "upstream": {
      "error": "Rate limit",
      "statusCode": 429
    }
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error - Unexpected Failure</summary>

```json
{
  "code": "server_error",
  "message": "An internal server error occurred. Please try again later.",
  "details": {
    "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error (HTML)</summary>

```json
"<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway - Connection Failed to Upstream</summary>

```json
{
  "code": "proxy_error",
  "message": "Failed to connect to WhatsApp server.",
  "details": {
    "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
  }
}
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
```

</details>

### Send Poll
**Endpoint:** `POST /v2/send/poll`

Send an interactive poll with multiple options.

#### 💡 Tips
- **Engagement Booster**: Polls have the highest response rate for customer feedback surveys.
- **Option Limit**: Keep options under 5 for the best mobile experience. Too many choices can lead to "decision fatigue".

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| instance_id | string | Yes | Your unique WhatsApp Instance ID |
| access_token | string | Yes | Your API Access Token |
| chatId | string | Yes | Target phone number or group ID |
| poll | object | Yes | The poll structure containing name and options. |
| reply_to | string | No | Message ID to reply to |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Message Sent Successfully</summary>

```json
{
  "_data": {
    "id": {
      "fromMe": true,
      "remote": "000000000000@c.us",
      "id": "MSG_ID_123456",
      "_serialized": "true_000000000000@c.us_MSG_ID_123456"
    },
    "viewed": false,
    "body": "BASE64_IMAGE_DATA",
    "type": "image",
    "t": 1759108866,
    "from": {
      "server": "c.us",
      "user": "111111111111",
      "_serialized": "111111111111@c.us"
    },
    "to": {
      "server": "c.us",
      "user": "000000000000",
      "_serialized": "000000000000@c.us"
    },
    "ack": 0,
    "isNewMsg": true,
    "star": false,
    "kicNotified": false,
    "caption": "Here's your requested image.",
    "deprecatedMms3Url": "https://example.com/media-url",
    "directPath": "/media/direct/path/example",
    "mimetype": "image/jpeg",
    "filehash": "FILE_HASH_PLACEHOLDER",
    "encFilehash": "ENC_FILE_HASH_PLACEHOLDER",
    "size": 192487,
    "mediaKey": "MEDIA_KEY_PLACEHOLDER",
    "mediaKeyTimestamp": 1759108865,
    "streamable": false,
    "mediaHandle": null,
    "isFromTemplate": false,
    "pollInvalidated": false,
    "isSentCagPollCreation": false,
    "latestEditMsgKey": null,
    "latestEditSenderTimestampMs": null,
    "mentionedJidList": [],
    "groupMentions": [],
    "isEventCanceled": false,
    "eventInvalidated": false,
    "isVcardOverMmsDocument": false,
    "isForwarded": false,
    "isQuestion": false,
    "questionReplyQuotedMessage": null,
    "questionResponsesCount": 0,
    "readQuestionResponsesCount": 0,
    "labels": [],
    "hasReaction": false,
    "disappearingModeInitiator": "chat",
    "disappearingModeTrigger": "chat_settings",
    "productHeaderImageRejected": false,
    "lastPlaybackProgress": 0,
    "isDynamicReplyButtonsMsg": false,
    "isCarouselCard": false,
    "parentMsgId": null,
    "callSilenceReason": null,
    "isVideoCall": false,
    "callDuration": null,
    "callCreator": null,
    "callParticipants": null,
    "isCallLink": null,
    "callLinkToken": null,
    "isMdHistoryMsg": false,
    "stickerSentTs": 0,
    "lastUpdateFromServerTs": 0,
    "invokedBotWid": null,
    "bizBotType": null,
    "botResponseTargetId": null,
    "botPluginType": null,
    "botPluginReferenceIndex": null,
    "botPluginSearchProvider": null,
    "botPluginSearchUrl": null,
    "botPluginSearchQuery": null,
    "botPluginMaybeParent": false,
    "botReelPluginThumbnailCdnUrl": null,
    "botMessageDisclaimerText": null,
    "botMsgBodyType": null,
    "requiresDirectConnection": false,
    "bizContentPlaceholderType": null,
    "hostedBizEncStateMismatch": false,
    "senderOrRecipientAccountTypeHosted": false,
    "placeholderCreatedWhenAccountIsHosted": false,
    "galaxyFlowDisabled": false,
    "links": []
  },
  "mediaKey": "MEDIA_KEY_PLACEHOLDER",
  "id": {
    "fromMe": true,
    "remote": "000000000000@c.us",
    "id": "MSG_ID_123456",
    "_serialized": "true_000000000000@c.us_MSG_ID_123456"
  },
  "ack": 0,
  "hasMedia": true,
  "body": "Here's your requested image.",
  "type": "image",
  "timestamp": 1759108866,
  "from": "111111111111@c.us",
  "to": "000000000000@c.us",
  "deviceType": "android",
  "isForwarded": false,
  "forwardingScore": 0,
  "isStatus": false,
  "isStarred": false,
  "fromMe": true,
  "hasQuotedMsg": false,
  "hasReaction": false,
  "vCards": [],
  "mentionedIds": [],
  "groupMentions": [],
  "isGif": false,
  "links": []
}
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (Plain Text)</summary>

```json
"Success: Operation completed successfully."
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Missing Required Parameter(s)</summary>

```json
{
  "code": "missing_param",
  "message": "Missing required parameter: {parameterName}",
  "details": {
    "missing": [
      "{parameterName}"
    ],
    "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Invalid Number (Egypt)</summary>

```json
{
  "code": "invalid_chat_id",
  "message": "Egypt mobile numbers must be 11 digits (national format).",
  "details": {
    "provided": "20114520282",
    "recommendation": "Example: 201012345678 (12 digits total starting with 20)",
    "info": {
      "country": "EG",
      "type": "MOBILE"
    }
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Invalid Number (Saudi Arabia)</summary>

```json
{
  "code": "invalid_chat_id",
  "message": "Invalid phone number format for SA.",
  "details": {
    "provided": "96655555",
    "recommendation": "Saudi numbers must start with 966 followed by 5 and 8 digits (12 digits total). Example: 966501234567",
    "info": {
      "country": "SA"
    }
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Invalid Number (Unknown)</summary>

```json
{
  "code": "invalid_chat_id",
  "message": "Invalid phone number format for Unknown.",
  "details": {
    "provided": "01145202826",
    "recommendation": "Ensure individual numbers are in international format (starting with country code).",
    "info": {
      "country": "Unknown"
    }
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (Plain Text)</summary>

```json
"Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized - Invalid or Missing Access Token</summary>

```json
{
  "code": "invalid_access_token",
  "message": "Invalid or expired access token. Please check your credentials.",
  "details": {
    "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
  }
}
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found - Session Does Not Exist</summary>

```json
{
  "code": "invalid_session",
  "message": "Session not found. Please verify your instance_id or session_name.",
  "details": {
    "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
  }
}
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 429</b>: Too Many Requests - Rate Limit Exceeded</summary>

```json
{
  "code": "rate_limit_exceeded",
  "message": "Too many requests. Please slow down.",
  "details": {
    "retryAfter": 60,
    "recommendation": "Implement a retry strategy with exponential backoff or reduce the frequency of your requests.",
    "upstream": {
      "error": "Rate limit",
      "statusCode": 429
    }
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error - Unexpected Failure</summary>

```json
{
  "code": "server_error",
  "message": "An internal server error occurred. Please try again later.",
  "details": {
    "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error (HTML)</summary>

```json
"<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway - Connection Failed to Upstream</summary>

```json
{
  "code": "proxy_error",
  "message": "Failed to connect to WhatsApp server.",
  "details": {
    "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
  }
}
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
```

</details>

### Send Poll Vote
**Endpoint:** `POST /v2/send/poll/vote`

Programmatically vote on a WhatsApp poll.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| instance_id | string | Yes | Your unique WhatsApp Instance ID |
| access_token | string | Yes | Your API Access Token |
| chatId | string | Yes | Target phone number or group ID |
| messageId | string | Yes | The unique ID of the poll message |
| votes | array | Yes | Array of selected option names or indices |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Message Sent Successfully</summary>

```json
{
  "_data": {
    "id": {
      "fromMe": true,
      "remote": "000000000000@c.us",
      "id": "MSG_ID_123456",
      "_serialized": "true_000000000000@c.us_MSG_ID_123456"
    },
    "viewed": false,
    "body": "BASE64_IMAGE_DATA",
    "type": "image",
    "t": 1759108866,
    "from": {
      "server": "c.us",
      "user": "111111111111",
      "_serialized": "111111111111@c.us"
    },
    "to": {
      "server": "c.us",
      "user": "000000000000",
      "_serialized": "000000000000@c.us"
    },
    "ack": 0,
    "isNewMsg": true,
    "star": false,
    "kicNotified": false,
    "caption": "Here's your requested image.",
    "deprecatedMms3Url": "https://example.com/media-url",
    "directPath": "/media/direct/path/example",
    "mimetype": "image/jpeg",
    "filehash": "FILE_HASH_PLACEHOLDER",
    "encFilehash": "ENC_FILE_HASH_PLACEHOLDER",
    "size": 192487,
    "mediaKey": "MEDIA_KEY_PLACEHOLDER",
    "mediaKeyTimestamp": 1759108865,
    "streamable": false,
    "mediaHandle": null,
    "isFromTemplate": false,
    "pollInvalidated": false,
    "isSentCagPollCreation": false,
    "latestEditMsgKey": null,
    "latestEditSenderTimestampMs": null,
    "mentionedJidList": [],
    "groupMentions": [],
    "isEventCanceled": false,
    "eventInvalidated": false,
    "isVcardOverMmsDocument": false,
    "isForwarded": false,
    "isQuestion": false,
    "questionReplyQuotedMessage": null,
    "questionResponsesCount": 0,
    "readQuestionResponsesCount": 0,
    "labels": [],
    "hasReaction": false,
    "disappearingModeInitiator": "chat",
    "disappearingModeTrigger": "chat_settings",
    "productHeaderImageRejected": false,
    "lastPlaybackProgress": 0,
    "isDynamicReplyButtonsMsg": false,
    "isCarouselCard": false,
    "parentMsgId": null,
    "callSilenceReason": null,
    "isVideoCall": false,
    "callDuration": null,
    "callCreator": null,
    "callParticipants": null,
    "isCallLink": null,
    "callLinkToken": null,
    "isMdHistoryMsg": false,
    "stickerSentTs": 0,
    "lastUpdateFromServerTs": 0,
    "invokedBotWid": null,
    "bizBotType": null,
    "botResponseTargetId": null,
    "botPluginType": null,
    "botPluginReferenceIndex": null,
    "botPluginSearchProvider": null,
    "botPluginSearchUrl": null,
    "botPluginSearchQuery": null,
    "botPluginMaybeParent": false,
    "botReelPluginThumbnailCdnUrl": null,
    "botMessageDisclaimerText": null,
    "botMsgBodyType": null,
    "requiresDirectConnection": false,
    "bizContentPlaceholderType": null,
    "hostedBizEncStateMismatch": false,
    "senderOrRecipientAccountTypeHosted": false,
    "placeholderCreatedWhenAccountIsHosted": false,
    "galaxyFlowDisabled": false,
    "links": []
  },
  "mediaKey": "MEDIA_KEY_PLACEHOLDER",
  "id": {
    "fromMe": true,
    "remote": "000000000000@c.us",
    "id": "MSG_ID_123456",
    "_serialized": "true_000000000000@c.us_MSG_ID_123456"
  },
  "ack": 0,
  "hasMedia": true,
  "body": "Here's your requested image.",
  "type": "image",
  "timestamp": 1759108866,
  "from": "111111111111@c.us",
  "to": "000000000000@c.us",
  "deviceType": "android",
  "isForwarded": false,
  "forwardingScore": 0,
  "isStatus": false,
  "isStarred": false,
  "fromMe": true,
  "hasQuotedMsg": false,
  "hasReaction": false,
  "vCards": [],
  "mentionedIds": [],
  "groupMentions": [],
  "isGif": false,
  "links": []
}
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (Plain Text)</summary>

```json
"Success: Operation completed successfully."
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Missing Required Parameter(s)</summary>

```json
{
  "code": "missing_param",
  "message": "Missing required parameter: {parameterName}",
  "details": {
    "missing": [
      "{parameterName}"
    ],
    "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Invalid Number (Egypt)</summary>

```json
{
  "code": "invalid_chat_id",
  "message": "Egypt mobile numbers must be 11 digits (national format).",
  "details": {
    "provided": "20114520282",
    "recommendation": "Example: 201012345678 (12 digits total starting with 20)",
    "info": {
      "country": "EG",
      "type": "MOBILE"
    }
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Invalid Number (Saudi Arabia)</summary>

```json
{
  "code": "invalid_chat_id",
  "message": "Invalid phone number format for SA.",
  "details": {
    "provided": "96655555",
    "recommendation": "Saudi numbers must start with 966 followed by 5 and 8 digits (12 digits total). Example: 966501234567",
    "info": {
      "country": "SA"
    }
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Invalid Number (Unknown)</summary>

```json
{
  "code": "invalid_chat_id",
  "message": "Invalid phone number format for Unknown.",
  "details": {
    "provided": "01145202826",
    "recommendation": "Ensure individual numbers are in international format (starting with country code).",
    "info": {
      "country": "Unknown"
    }
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (Plain Text)</summary>

```json
"Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized - Invalid or Missing Access Token</summary>

```json
{
  "code": "invalid_access_token",
  "message": "Invalid or expired access token. Please check your credentials.",
  "details": {
    "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
  }
}
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found - Session Does Not Exist</summary>

```json
{
  "code": "invalid_session",
  "message": "Session not found. Please verify your instance_id or session_name.",
  "details": {
    "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
  }
}
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 429</b>: Too Many Requests - Rate Limit Exceeded</summary>

```json
{
  "code": "rate_limit_exceeded",
  "message": "Too many requests. Please slow down.",
  "details": {
    "retryAfter": 60,
    "recommendation": "Implement a retry strategy with exponential backoff or reduce the frequency of your requests.",
    "upstream": {
      "error": "Rate limit",
      "statusCode": 429
    }
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error - Unexpected Failure</summary>

```json
{
  "code": "server_error",
  "message": "An internal server error occurred. Please try again later.",
  "details": {
    "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error (HTML)</summary>

```json
"<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway - Connection Failed to Upstream</summary>

```json
{
  "code": "proxy_error",
  "message": "Failed to connect to WhatsApp server.",
  "details": {
    "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
  }
}
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
```

</details>

### Send Contact Vcard
**Endpoint:** `POST /v2/send/contact`

Send professional contact cards (vCards) to a chat. Supports single or multiple contacts in one bubble.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| instance_id | string | Yes | Unique ID of the WhatsApp session |
| access_token | string | Yes | API access token |
| chatId | string | Yes | Recipient's WhatsApp number |
| contacts | array | Yes | Array of contact objects containing name and phone info. |
| reply_to | string | No | The ID of the message you are replying to |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Message Sent Successfully</summary>

```json
{
  "_data": {
    "id": {
      "fromMe": true,
      "remote": "000000000000@c.us",
      "id": "MSG_ID_123456",
      "_serialized": "true_000000000000@c.us_MSG_ID_123456"
    },
    "viewed": false,
    "body": "BASE64_IMAGE_DATA",
    "type": "image",
    "t": 1759108866,
    "from": {
      "server": "c.us",
      "user": "111111111111",
      "_serialized": "111111111111@c.us"
    },
    "to": {
      "server": "c.us",
      "user": "000000000000",
      "_serialized": "000000000000@c.us"
    },
    "ack": 0,
    "isNewMsg": true,
    "star": false,
    "kicNotified": false,
    "caption": "Here's your requested image.",
    "deprecatedMms3Url": "https://example.com/media-url",
    "directPath": "/media/direct/path/example",
    "mimetype": "image/jpeg",
    "filehash": "FILE_HASH_PLACEHOLDER",
    "encFilehash": "ENC_FILE_HASH_PLACEHOLDER",
    "size": 192487,
    "mediaKey": "MEDIA_KEY_PLACEHOLDER",
    "mediaKeyTimestamp": 1759108865,
    "streamable": false,
    "mediaHandle": null,
    "isFromTemplate": false,
    "pollInvalidated": false,
    "isSentCagPollCreation": false,
    "latestEditMsgKey": null,
    "latestEditSenderTimestampMs": null,
    "mentionedJidList": [],
    "groupMentions": [],
    "isEventCanceled": false,
    "eventInvalidated": false,
    "isVcardOverMmsDocument": false,
    "isForwarded": false,
    "isQuestion": false,
    "questionReplyQuotedMessage": null,
    "questionResponsesCount": 0,
    "readQuestionResponsesCount": 0,
    "labels": [],
    "hasReaction": false,
    "disappearingModeInitiator": "chat",
    "disappearingModeTrigger": "chat_settings",
    "productHeaderImageRejected": false,
    "lastPlaybackProgress": 0,
    "isDynamicReplyButtonsMsg": false,
    "isCarouselCard": false,
    "parentMsgId": null,
    "callSilenceReason": null,
    "isVideoCall": false,
    "callDuration": null,
    "callCreator": null,
    "callParticipants": null,
    "isCallLink": null,
    "callLinkToken": null,
    "isMdHistoryMsg": false,
    "stickerSentTs": 0,
    "lastUpdateFromServerTs": 0,
    "invokedBotWid": null,
    "bizBotType": null,
    "botResponseTargetId": null,
    "botPluginType": null,
    "botPluginReferenceIndex": null,
    "botPluginSearchProvider": null,
    "botPluginSearchUrl": null,
    "botPluginSearchQuery": null,
    "botPluginMaybeParent": false,
    "botReelPluginThumbnailCdnUrl": null,
    "botMessageDisclaimerText": null,
    "botMsgBodyType": null,
    "requiresDirectConnection": false,
    "bizContentPlaceholderType": null,
    "hostedBizEncStateMismatch": false,
    "senderOrRecipientAccountTypeHosted": false,
    "placeholderCreatedWhenAccountIsHosted": false,
    "galaxyFlowDisabled": false,
    "links": []
  },
  "mediaKey": "MEDIA_KEY_PLACEHOLDER",
  "id": {
    "fromMe": true,
    "remote": "000000000000@c.us",
    "id": "MSG_ID_123456",
    "_serialized": "true_000000000000@c.us_MSG_ID_123456"
  },
  "ack": 0,
  "hasMedia": true,
  "body": "Here's your requested image.",
  "type": "image",
  "timestamp": 1759108866,
  "from": "111111111111@c.us",
  "to": "000000000000@c.us",
  "deviceType": "android",
  "isForwarded": false,
  "forwardingScore": 0,
  "isStatus": false,
  "isStarred": false,
  "fromMe": true,
  "hasQuotedMsg": false,
  "hasReaction": false,
  "vCards": [],
  "mentionedIds": [],
  "groupMentions": [],
  "isGif": false,
  "links": []
}
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (Plain Text)</summary>

```json
"Success: Operation completed successfully."
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Missing Required Parameter(s)</summary>

```json
{
  "code": "missing_param",
  "message": "Missing required parameter: {parameterName}",
  "details": {
    "missing": [
      "{parameterName}"
    ],
    "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Invalid Number (Egypt)</summary>

```json
{
  "code": "invalid_chat_id",
  "message": "Egypt mobile numbers must be 11 digits (national format).",
  "details": {
    "provided": "20114520282",
    "recommendation": "Example: 201012345678 (12 digits total starting with 20)",
    "info": {
      "country": "EG",
      "type": "MOBILE"
    }
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Invalid Number (Saudi Arabia)</summary>

```json
{
  "code": "invalid_chat_id",
  "message": "Invalid phone number format for SA.",
  "details": {
    "provided": "96655555",
    "recommendation": "Saudi numbers must start with 966 followed by 5 and 8 digits (12 digits total). Example: 966501234567",
    "info": {
      "country": "SA"
    }
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Invalid Number (Unknown)</summary>

```json
{
  "code": "invalid_chat_id",
  "message": "Invalid phone number format for Unknown.",
  "details": {
    "provided": "01145202826",
    "recommendation": "Ensure individual numbers are in international format (starting with country code).",
    "info": {
      "country": "Unknown"
    }
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (Plain Text)</summary>

```json
"Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized - Invalid or Missing Access Token</summary>

```json
{
  "code": "invalid_access_token",
  "message": "Invalid or expired access token. Please check your credentials.",
  "details": {
    "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
  }
}
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found - Session Does Not Exist</summary>

```json
{
  "code": "invalid_session",
  "message": "Session not found. Please verify your instance_id or session_name.",
  "details": {
    "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
  }
}
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 429</b>: Too Many Requests - Rate Limit Exceeded</summary>

```json
{
  "code": "rate_limit_exceeded",
  "message": "Too many requests. Please slow down.",
  "details": {
    "retryAfter": 60,
    "recommendation": "Implement a retry strategy with exponential backoff or reduce the frequency of your requests.",
    "upstream": {
      "error": "Rate limit",
      "statusCode": 429
    }
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error - Unexpected Failure</summary>

```json
{
  "code": "server_error",
  "message": "An internal server error occurred. Please try again later.",
  "details": {
    "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error (HTML)</summary>

```json
"<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway - Connection Failed to Upstream</summary>

```json
{
  "code": "proxy_error",
  "message": "Failed to connect to WhatsApp server.",
  "details": {
    "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
  }
}
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
```

</details>

### Mark message(s) as seen
**Endpoint:** `POST /v2/send/seen`

Mark specific messages or an entire chat as seen/read (Blue Ticks).

#### 💡 Tips
- **Customer Experience**: Marking messages as seen shows your customers that you are active and attending to their needs.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| instance_id | string | Yes | Your unique WhatsApp Instance ID |
| access_token | string | Yes | Your API Access Token |
| chatId | string | Yes | Target phone number or group ID |
| messageIds | array | Yes | Array of message IDs to mark as seen. |
| participant | string | No | The participant who sent the message (for groups). |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Message Sent Successfully</summary>

```json
{
  "_data": {
    "id": {
      "fromMe": true,
      "remote": "000000000000@c.us",
      "id": "MSG_ID_123456",
      "_serialized": "true_000000000000@c.us_MSG_ID_123456"
    },
    "viewed": false,
    "body": "BASE64_IMAGE_DATA",
    "type": "image",
    "t": 1759108866,
    "from": {
      "server": "c.us",
      "user": "111111111111",
      "_serialized": "111111111111@c.us"
    },
    "to": {
      "server": "c.us",
      "user": "000000000000",
      "_serialized": "000000000000@c.us"
    },
    "ack": 0,
    "isNewMsg": true,
    "star": false,
    "kicNotified": false,
    "caption": "Here's your requested image.",
    "deprecatedMms3Url": "https://example.com/media-url",
    "directPath": "/media/direct/path/example",
    "mimetype": "image/jpeg",
    "filehash": "FILE_HASH_PLACEHOLDER",
    "encFilehash": "ENC_FILE_HASH_PLACEHOLDER",
    "size": 192487,
    "mediaKey": "MEDIA_KEY_PLACEHOLDER",
    "mediaKeyTimestamp": 1759108865,
    "streamable": false,
    "mediaHandle": null,
    "isFromTemplate": false,
    "pollInvalidated": false,
    "isSentCagPollCreation": false,
    "latestEditMsgKey": null,
    "latestEditSenderTimestampMs": null,
    "mentionedJidList": [],
    "groupMentions": [],
    "isEventCanceled": false,
    "eventInvalidated": false,
    "isVcardOverMmsDocument": false,
    "isForwarded": false,
    "isQuestion": false,
    "questionReplyQuotedMessage": null,
    "questionResponsesCount": 0,
    "readQuestionResponsesCount": 0,
    "labels": [],
    "hasReaction": false,
    "disappearingModeInitiator": "chat",
    "disappearingModeTrigger": "chat_settings",
    "productHeaderImageRejected": false,
    "lastPlaybackProgress": 0,
    "isDynamicReplyButtonsMsg": false,
    "isCarouselCard": false,
    "parentMsgId": null,
    "callSilenceReason": null,
    "isVideoCall": false,
    "callDuration": null,
    "callCreator": null,
    "callParticipants": null,
    "isCallLink": null,
    "callLinkToken": null,
    "isMdHistoryMsg": false,
    "stickerSentTs": 0,
    "lastUpdateFromServerTs": 0,
    "invokedBotWid": null,
    "bizBotType": null,
    "botResponseTargetId": null,
    "botPluginType": null,
    "botPluginReferenceIndex": null,
    "botPluginSearchProvider": null,
    "botPluginSearchUrl": null,
    "botPluginSearchQuery": null,
    "botPluginMaybeParent": false,
    "botReelPluginThumbnailCdnUrl": null,
    "botMessageDisclaimerText": null,
    "botMsgBodyType": null,
    "requiresDirectConnection": false,
    "bizContentPlaceholderType": null,
    "hostedBizEncStateMismatch": false,
    "senderOrRecipientAccountTypeHosted": false,
    "placeholderCreatedWhenAccountIsHosted": false,
    "galaxyFlowDisabled": false,
    "links": []
  },
  "mediaKey": "MEDIA_KEY_PLACEHOLDER",
  "id": {
    "fromMe": true,
    "remote": "000000000000@c.us",
    "id": "MSG_ID_123456",
    "_serialized": "true_000000000000@c.us_MSG_ID_123456"
  },
  "ack": 0,
  "hasMedia": true,
  "body": "Here's your requested image.",
  "type": "image",
  "timestamp": 1759108866,
  "from": "111111111111@c.us",
  "to": "000000000000@c.us",
  "deviceType": "android",
  "isForwarded": false,
  "forwardingScore": 0,
  "isStatus": false,
  "isStarred": false,
  "fromMe": true,
  "hasQuotedMsg": false,
  "hasReaction": false,
  "vCards": [],
  "mentionedIds": [],
  "groupMentions": [],
  "isGif": false,
  "links": []
}
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (Plain Text)</summary>

```json
"Success: Operation completed successfully."
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Missing Required Parameter(s)</summary>

```json
{
  "code": "missing_param",
  "message": "Missing required parameter: {parameterName}",
  "details": {
    "missing": [
      "{parameterName}"
    ],
    "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Invalid Number (Egypt)</summary>

```json
{
  "code": "invalid_chat_id",
  "message": "Egypt mobile numbers must be 11 digits (national format).",
  "details": {
    "provided": "20114520282",
    "recommendation": "Example: 201012345678 (12 digits total starting with 20)",
    "info": {
      "country": "EG",
      "type": "MOBILE"
    }
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Invalid Number (Saudi Arabia)</summary>

```json
{
  "code": "invalid_chat_id",
  "message": "Invalid phone number format for SA.",
  "details": {
    "provided": "96655555",
    "recommendation": "Saudi numbers must start with 966 followed by 5 and 8 digits (12 digits total). Example: 966501234567",
    "info": {
      "country": "SA"
    }
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Invalid Number (Unknown)</summary>

```json
{
  "code": "invalid_chat_id",
  "message": "Invalid phone number format for Unknown.",
  "details": {
    "provided": "01145202826",
    "recommendation": "Ensure individual numbers are in international format (starting with country code).",
    "info": {
      "country": "Unknown"
    }
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (Plain Text)</summary>

```json
"Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized - Invalid or Missing Access Token</summary>

```json
{
  "code": "invalid_access_token",
  "message": "Invalid or expired access token. Please check your credentials.",
  "details": {
    "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
  }
}
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found - Session Does Not Exist</summary>

```json
{
  "code": "invalid_session",
  "message": "Session not found. Please verify your instance_id or session_name.",
  "details": {
    "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
  }
}
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 429</b>: Too Many Requests - Rate Limit Exceeded</summary>

```json
{
  "code": "rate_limit_exceeded",
  "message": "Too many requests. Please slow down.",
  "details": {
    "retryAfter": 60,
    "recommendation": "Implement a retry strategy with exponential backoff or reduce the frequency of your requests.",
    "upstream": {
      "error": "Rate limit",
      "statusCode": 429
    }
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error - Unexpected Failure</summary>

```json
{
  "code": "server_error",
  "message": "An internal server error occurred. Please try again later.",
  "details": {
    "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error (HTML)</summary>

```json
"<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway - Connection Failed to Upstream</summary>

```json
{
  "code": "proxy_error",
  "message": "Failed to connect to WhatsApp server.",
  "details": {
    "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
  }
}
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
```

</details>

### Start Typing
**Endpoint:** `POST /v2/send/start-typing`

Show the 'typing...' or 'recording audio...' status in a chat.

#### 💡 Tips
- **Bot Strategy**: Using typing status increases trust as it mimics a human agent preparing a response.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| instance_id | string | Yes | Your unique WhatsApp Instance ID |
| access_token | string | Yes | Your API Access Token |
| chatId | string | Yes | Target phone number or group ID |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Message Sent Successfully</summary>

```json
{
  "_data": {
    "id": {
      "fromMe": true,
      "remote": "000000000000@c.us",
      "id": "MSG_ID_123456",
      "_serialized": "true_000000000000@c.us_MSG_ID_123456"
    },
    "viewed": false,
    "body": "BASE64_IMAGE_DATA",
    "type": "image",
    "t": 1759108866,
    "from": {
      "server": "c.us",
      "user": "111111111111",
      "_serialized": "111111111111@c.us"
    },
    "to": {
      "server": "c.us",
      "user": "000000000000",
      "_serialized": "000000000000@c.us"
    },
    "ack": 0,
    "isNewMsg": true,
    "star": false,
    "kicNotified": false,
    "caption": "Here's your requested image.",
    "deprecatedMms3Url": "https://example.com/media-url",
    "directPath": "/media/direct/path/example",
    "mimetype": "image/jpeg",
    "filehash": "FILE_HASH_PLACEHOLDER",
    "encFilehash": "ENC_FILE_HASH_PLACEHOLDER",
    "size": 192487,
    "mediaKey": "MEDIA_KEY_PLACEHOLDER",
    "mediaKeyTimestamp": 1759108865,
    "streamable": false,
    "mediaHandle": null,
    "isFromTemplate": false,
    "pollInvalidated": false,
    "isSentCagPollCreation": false,
    "latestEditMsgKey": null,
    "latestEditSenderTimestampMs": null,
    "mentionedJidList": [],
    "groupMentions": [],
    "isEventCanceled": false,
    "eventInvalidated": false,
    "isVcardOverMmsDocument": false,
    "isForwarded": false,
    "isQuestion": false,
    "questionReplyQuotedMessage": null,
    "questionResponsesCount": 0,
    "readQuestionResponsesCount": 0,
    "labels": [],
    "hasReaction": false,
    "disappearingModeInitiator": "chat",
    "disappearingModeTrigger": "chat_settings",
    "productHeaderImageRejected": false,
    "lastPlaybackProgress": 0,
    "isDynamicReplyButtonsMsg": false,
    "isCarouselCard": false,
    "parentMsgId": null,
    "callSilenceReason": null,
    "isVideoCall": false,
    "callDuration": null,
    "callCreator": null,
    "callParticipants": null,
    "isCallLink": null,
    "callLinkToken": null,
    "isMdHistoryMsg": false,
    "stickerSentTs": 0,
    "lastUpdateFromServerTs": 0,
    "invokedBotWid": null,
    "bizBotType": null,
    "botResponseTargetId": null,
    "botPluginType": null,
    "botPluginReferenceIndex": null,
    "botPluginSearchProvider": null,
    "botPluginSearchUrl": null,
    "botPluginSearchQuery": null,
    "botPluginMaybeParent": false,
    "botReelPluginThumbnailCdnUrl": null,
    "botMessageDisclaimerText": null,
    "botMsgBodyType": null,
    "requiresDirectConnection": false,
    "bizContentPlaceholderType": null,
    "hostedBizEncStateMismatch": false,
    "senderOrRecipientAccountTypeHosted": false,
    "placeholderCreatedWhenAccountIsHosted": false,
    "galaxyFlowDisabled": false,
    "links": []
  },
  "mediaKey": "MEDIA_KEY_PLACEHOLDER",
  "id": {
    "fromMe": true,
    "remote": "000000000000@c.us",
    "id": "MSG_ID_123456",
    "_serialized": "true_000000000000@c.us_MSG_ID_123456"
  },
  "ack": 0,
  "hasMedia": true,
  "body": "Here's your requested image.",
  "type": "image",
  "timestamp": 1759108866,
  "from": "111111111111@c.us",
  "to": "000000000000@c.us",
  "deviceType": "android",
  "isForwarded": false,
  "forwardingScore": 0,
  "isStatus": false,
  "isStarred": false,
  "fromMe": true,
  "hasQuotedMsg": false,
  "hasReaction": false,
  "vCards": [],
  "mentionedIds": [],
  "groupMentions": [],
  "isGif": false,
  "links": []
}
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (Plain Text)</summary>

```json
"Success: Operation completed successfully."
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Missing Required Parameter(s)</summary>

```json
{
  "code": "missing_param",
  "message": "Missing required parameter: {parameterName}",
  "details": {
    "missing": [
      "{parameterName}"
    ],
    "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Invalid Number (Egypt)</summary>

```json
{
  "code": "invalid_chat_id",
  "message": "Egypt mobile numbers must be 11 digits (national format).",
  "details": {
    "provided": "20114520282",
    "recommendation": "Example: 201012345678 (12 digits total starting with 20)",
    "info": {
      "country": "EG",
      "type": "MOBILE"
    }
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Invalid Number (Saudi Arabia)</summary>

```json
{
  "code": "invalid_chat_id",
  "message": "Invalid phone number format for SA.",
  "details": {
    "provided": "96655555",
    "recommendation": "Saudi numbers must start with 966 followed by 5 and 8 digits (12 digits total). Example: 966501234567",
    "info": {
      "country": "SA"
    }
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Invalid Number (Unknown)</summary>

```json
{
  "code": "invalid_chat_id",
  "message": "Invalid phone number format for Unknown.",
  "details": {
    "provided": "01145202826",
    "recommendation": "Ensure individual numbers are in international format (starting with country code).",
    "info": {
      "country": "Unknown"
    }
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (Plain Text)</summary>

```json
"Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized - Invalid or Missing Access Token</summary>

```json
{
  "code": "invalid_access_token",
  "message": "Invalid or expired access token. Please check your credentials.",
  "details": {
    "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
  }
}
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found - Session Does Not Exist</summary>

```json
{
  "code": "invalid_session",
  "message": "Session not found. Please verify your instance_id or session_name.",
  "details": {
    "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
  }
}
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 429</b>: Too Many Requests - Rate Limit Exceeded</summary>

```json
{
  "code": "rate_limit_exceeded",
  "message": "Too many requests. Please slow down.",
  "details": {
    "retryAfter": 60,
    "recommendation": "Implement a retry strategy with exponential backoff or reduce the frequency of your requests.",
    "upstream": {
      "error": "Rate limit",
      "statusCode": 429
    }
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error - Unexpected Failure</summary>

```json
{
  "code": "server_error",
  "message": "An internal server error occurred. Please try again later.",
  "details": {
    "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error (HTML)</summary>

```json
"<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway - Connection Failed to Upstream</summary>

```json
{
  "code": "proxy_error",
  "message": "Failed to connect to WhatsApp server.",
  "details": {
    "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
  }
}
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
```

</details>

### Stop Typing
**Endpoint:** `POST /v2/send/stop-typing`

Remove the 'typing...' or 'recording audio...' status from a chat.

#### 💡 Tips
- **Auto-Stop**: WhatsApp will naturally stop the typing indicator after ~10 seconds of inactivity even if you do not call this.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| instance_id | string | Yes | Your unique WhatsApp Instance ID |
| access_token | string | Yes | Your API Access Token |
| chatId | string | Yes | Target phone number or group ID |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Message Sent Successfully</summary>

```json
{
  "_data": {
    "id": {
      "fromMe": true,
      "remote": "000000000000@c.us",
      "id": "MSG_ID_123456",
      "_serialized": "true_000000000000@c.us_MSG_ID_123456"
    },
    "viewed": false,
    "body": "BASE64_IMAGE_DATA",
    "type": "image",
    "t": 1759108866,
    "from": {
      "server": "c.us",
      "user": "111111111111",
      "_serialized": "111111111111@c.us"
    },
    "to": {
      "server": "c.us",
      "user": "000000000000",
      "_serialized": "000000000000@c.us"
    },
    "ack": 0,
    "isNewMsg": true,
    "star": false,
    "kicNotified": false,
    "caption": "Here's your requested image.",
    "deprecatedMms3Url": "https://example.com/media-url",
    "directPath": "/media/direct/path/example",
    "mimetype": "image/jpeg",
    "filehash": "FILE_HASH_PLACEHOLDER",
    "encFilehash": "ENC_FILE_HASH_PLACEHOLDER",
    "size": 192487,
    "mediaKey": "MEDIA_KEY_PLACEHOLDER",
    "mediaKeyTimestamp": 1759108865,
    "streamable": false,
    "mediaHandle": null,
    "isFromTemplate": false,
    "pollInvalidated": false,
    "isSentCagPollCreation": false,
    "latestEditMsgKey": null,
    "latestEditSenderTimestampMs": null,
    "mentionedJidList": [],
    "groupMentions": [],
    "isEventCanceled": false,
    "eventInvalidated": false,
    "isVcardOverMmsDocument": false,
    "isForwarded": false,
    "isQuestion": false,
    "questionReplyQuotedMessage": null,
    "questionResponsesCount": 0,
    "readQuestionResponsesCount": 0,
    "labels": [],
    "hasReaction": false,
    "disappearingModeInitiator": "chat",
    "disappearingModeTrigger": "chat_settings",
    "productHeaderImageRejected": false,
    "lastPlaybackProgress": 0,
    "isDynamicReplyButtonsMsg": false,
    "isCarouselCard": false,
    "parentMsgId": null,
    "callSilenceReason": null,
    "isVideoCall": false,
    "callDuration": null,
    "callCreator": null,
    "callParticipants": null,
    "isCallLink": null,
    "callLinkToken": null,
    "isMdHistoryMsg": false,
    "stickerSentTs": 0,
    "lastUpdateFromServerTs": 0,
    "invokedBotWid": null,
    "bizBotType": null,
    "botResponseTargetId": null,
    "botPluginType": null,
    "botPluginReferenceIndex": null,
    "botPluginSearchProvider": null,
    "botPluginSearchUrl": null,
    "botPluginSearchQuery": null,
    "botPluginMaybeParent": false,
    "botReelPluginThumbnailCdnUrl": null,
    "botMessageDisclaimerText": null,
    "botMsgBodyType": null,
    "requiresDirectConnection": false,
    "bizContentPlaceholderType": null,
    "hostedBizEncStateMismatch": false,
    "senderOrRecipientAccountTypeHosted": false,
    "placeholderCreatedWhenAccountIsHosted": false,
    "galaxyFlowDisabled": false,
    "links": []
  },
  "mediaKey": "MEDIA_KEY_PLACEHOLDER",
  "id": {
    "fromMe": true,
    "remote": "000000000000@c.us",
    "id": "MSG_ID_123456",
    "_serialized": "true_000000000000@c.us_MSG_ID_123456"
  },
  "ack": 0,
  "hasMedia": true,
  "body": "Here's your requested image.",
  "type": "image",
  "timestamp": 1759108866,
  "from": "111111111111@c.us",
  "to": "000000000000@c.us",
  "deviceType": "android",
  "isForwarded": false,
  "forwardingScore": 0,
  "isStatus": false,
  "isStarred": false,
  "fromMe": true,
  "hasQuotedMsg": false,
  "hasReaction": false,
  "vCards": [],
  "mentionedIds": [],
  "groupMentions": [],
  "isGif": false,
  "links": []
}
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (Plain Text)</summary>

```json
"Success: Operation completed successfully."
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Missing Required Parameter(s)</summary>

```json
{
  "code": "missing_param",
  "message": "Missing required parameter: {parameterName}",
  "details": {
    "missing": [
      "{parameterName}"
    ],
    "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Invalid Number (Egypt)</summary>

```json
{
  "code": "invalid_chat_id",
  "message": "Egypt mobile numbers must be 11 digits (national format).",
  "details": {
    "provided": "20114520282",
    "recommendation": "Example: 201012345678 (12 digits total starting with 20)",
    "info": {
      "country": "EG",
      "type": "MOBILE"
    }
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Invalid Number (Saudi Arabia)</summary>

```json
{
  "code": "invalid_chat_id",
  "message": "Invalid phone number format for SA.",
  "details": {
    "provided": "96655555",
    "recommendation": "Saudi numbers must start with 966 followed by 5 and 8 digits (12 digits total). Example: 966501234567",
    "info": {
      "country": "SA"
    }
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Invalid Number (Unknown)</summary>

```json
{
  "code": "invalid_chat_id",
  "message": "Invalid phone number format for Unknown.",
  "details": {
    "provided": "01145202826",
    "recommendation": "Ensure individual numbers are in international format (starting with country code).",
    "info": {
      "country": "Unknown"
    }
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (Plain Text)</summary>

```json
"Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized - Invalid or Missing Access Token</summary>

```json
{
  "code": "invalid_access_token",
  "message": "Invalid or expired access token. Please check your credentials.",
  "details": {
    "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
  }
}
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found - Session Does Not Exist</summary>

```json
{
  "code": "invalid_session",
  "message": "Session not found. Please verify your instance_id or session_name.",
  "details": {
    "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
  }
}
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 429</b>: Too Many Requests - Rate Limit Exceeded</summary>

```json
{
  "code": "rate_limit_exceeded",
  "message": "Too many requests. Please slow down.",
  "details": {
    "retryAfter": 60,
    "recommendation": "Implement a retry strategy with exponential backoff or reduce the frequency of your requests.",
    "upstream": {
      "error": "Rate limit",
      "statusCode": 429
    }
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error - Unexpected Failure</summary>

```json
{
  "code": "server_error",
  "message": "An internal server error occurred. Please try again later.",
  "details": {
    "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error (HTML)</summary>

```json
"<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway - Connection Failed to Upstream</summary>

```json
{
  "code": "proxy_error",
  "message": "Failed to connect to WhatsApp server.",
  "details": {
    "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
  }
}
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
```

</details>

### Reaction
**Endpoint:** `PUT /v2/send/reaction`

React to a specific message with an emoji (👍, ❤️, 😂, etc.).

#### 💡 Tips
- **Modern UI**: Reactions keep chat history clean and are significantly faster to process for the user than text replies.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| instance_id | string | Yes | Your unique WhatsApp Instance ID |
| access_token | string | Yes | Your API Access Token |
| chatId | string | Yes | Recipient's WhatsApp ID (JID). Supports Individuals (@c.us), Groups (@g.us), and Newsletters (@newsletter). |
| messageId | string | Yes | The ID of the message you want to react to. |
| reaction | string | Yes | The emoji reaction. Use an empty string to remove. |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Message Sent Successfully</summary>

```json
{
  "_data": {
    "id": {
      "fromMe": true,
      "remote": "000000000000@c.us",
      "id": "MSG_ID_123456",
      "_serialized": "true_000000000000@c.us_MSG_ID_123456"
    },
    "viewed": false,
    "body": "BASE64_IMAGE_DATA",
    "type": "image",
    "t": 1759108866,
    "from": {
      "server": "c.us",
      "user": "111111111111",
      "_serialized": "111111111111@c.us"
    },
    "to": {
      "server": "c.us",
      "user": "000000000000",
      "_serialized": "000000000000@c.us"
    },
    "ack": 0,
    "isNewMsg": true,
    "star": false,
    "kicNotified": false,
    "caption": "Here's your requested image.",
    "deprecatedMms3Url": "https://example.com/media-url",
    "directPath": "/media/direct/path/example",
    "mimetype": "image/jpeg",
    "filehash": "FILE_HASH_PLACEHOLDER",
    "encFilehash": "ENC_FILE_HASH_PLACEHOLDER",
    "size": 192487,
    "mediaKey": "MEDIA_KEY_PLACEHOLDER",
    "mediaKeyTimestamp": 1759108865,
    "streamable": false,
    "mediaHandle": null,
    "isFromTemplate": false,
    "pollInvalidated": false,
    "isSentCagPollCreation": false,
    "latestEditMsgKey": null,
    "latestEditSenderTimestampMs": null,
    "mentionedJidList": [],
    "groupMentions": [],
    "isEventCanceled": false,
    "eventInvalidated": false,
    "isVcardOverMmsDocument": false,
    "isForwarded": false,
    "isQuestion": false,
    "questionReplyQuotedMessage": null,
    "questionResponsesCount": 0,
    "readQuestionResponsesCount": 0,
    "labels": [],
    "hasReaction": false,
    "disappearingModeInitiator": "chat",
    "disappearingModeTrigger": "chat_settings",
    "productHeaderImageRejected": false,
    "lastPlaybackProgress": 0,
    "isDynamicReplyButtonsMsg": false,
    "isCarouselCard": false,
    "parentMsgId": null,
    "callSilenceReason": null,
    "isVideoCall": false,
    "callDuration": null,
    "callCreator": null,
    "callParticipants": null,
    "isCallLink": null,
    "callLinkToken": null,
    "isMdHistoryMsg": false,
    "stickerSentTs": 0,
    "lastUpdateFromServerTs": 0,
    "invokedBotWid": null,
    "bizBotType": null,
    "botResponseTargetId": null,
    "botPluginType": null,
    "botPluginReferenceIndex": null,
    "botPluginSearchProvider": null,
    "botPluginSearchUrl": null,
    "botPluginSearchQuery": null,
    "botPluginMaybeParent": false,
    "botReelPluginThumbnailCdnUrl": null,
    "botMessageDisclaimerText": null,
    "botMsgBodyType": null,
    "requiresDirectConnection": false,
    "bizContentPlaceholderType": null,
    "hostedBizEncStateMismatch": false,
    "senderOrRecipientAccountTypeHosted": false,
    "placeholderCreatedWhenAccountIsHosted": false,
    "galaxyFlowDisabled": false,
    "links": []
  },
  "mediaKey": "MEDIA_KEY_PLACEHOLDER",
  "id": {
    "fromMe": true,
    "remote": "000000000000@c.us",
    "id": "MSG_ID_123456",
    "_serialized": "true_000000000000@c.us_MSG_ID_123456"
  },
  "ack": 0,
  "hasMedia": true,
  "body": "Here's your requested image.",
  "type": "image",
  "timestamp": 1759108866,
  "from": "111111111111@c.us",
  "to": "000000000000@c.us",
  "deviceType": "android",
  "isForwarded": false,
  "forwardingScore": 0,
  "isStatus": false,
  "isStarred": false,
  "fromMe": true,
  "hasQuotedMsg": false,
  "hasReaction": false,
  "vCards": [],
  "mentionedIds": [],
  "groupMentions": [],
  "isGif": false,
  "links": []
}
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (Plain Text)</summary>

```json
"Success: Operation completed successfully."
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Missing Required Parameter(s)</summary>

```json
{
  "code": "missing_param",
  "message": "Missing required parameter: {parameterName}",
  "details": {
    "missing": [
      "{parameterName}"
    ],
    "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Invalid Number (Egypt)</summary>

```json
{
  "code": "invalid_chat_id",
  "message": "Egypt mobile numbers must be 11 digits (national format).",
  "details": {
    "provided": "20114520282",
    "recommendation": "Example: 201012345678 (12 digits total starting with 20)",
    "info": {
      "country": "EG",
      "type": "MOBILE"
    }
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Invalid Number (Saudi Arabia)</summary>

```json
{
  "code": "invalid_chat_id",
  "message": "Invalid phone number format for SA.",
  "details": {
    "provided": "96655555",
    "recommendation": "Saudi numbers must start with 966 followed by 5 and 8 digits (12 digits total). Example: 966501234567",
    "info": {
      "country": "SA"
    }
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Invalid Number (Unknown)</summary>

```json
{
  "code": "invalid_chat_id",
  "message": "Invalid phone number format for Unknown.",
  "details": {
    "provided": "01145202826",
    "recommendation": "Ensure individual numbers are in international format (starting with country code).",
    "info": {
      "country": "Unknown"
    }
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (Plain Text)</summary>

```json
"Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized - Invalid or Missing Access Token</summary>

```json
{
  "code": "invalid_access_token",
  "message": "Invalid or expired access token. Please check your credentials.",
  "details": {
    "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
  }
}
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found - Session Does Not Exist</summary>

```json
{
  "code": "invalid_session",
  "message": "Session not found. Please verify your instance_id or session_name.",
  "details": {
    "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
  }
}
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 429</b>: Too Many Requests - Rate Limit Exceeded</summary>

```json
{
  "code": "rate_limit_exceeded",
  "message": "Too many requests. Please slow down.",
  "details": {
    "retryAfter": 60,
    "recommendation": "Implement a retry strategy with exponential backoff or reduce the frequency of your requests.",
    "upstream": {
      "error": "Rate limit",
      "statusCode": 429
    }
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error - Unexpected Failure</summary>

```json
{
  "code": "server_error",
  "message": "An internal server error occurred. Please try again later.",
  "details": {
    "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error (HTML)</summary>

```json
"<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway - Connection Failed to Upstream</summary>

```json
{
  "code": "proxy_error",
  "message": "Failed to connect to WhatsApp server.",
  "details": {
    "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
  }
}
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
```

</details>

---

## Chat Actions

### Chat Management
Manage chat history, message states, and advanced conversation controls.

#### 💡 Tips
- **Clean Inbox**: Archiving old conversations keeps your instance performing optimally and your agents focused.

### Chats list & overview
**Endpoint:** `GET, POST /v2/chats`

Get a list of all active chats (individuals and groups) with pagination support.

#### 💡 Tips
- **Rate Limits**: Be mindful of API rate limits to act responsibly.
- **Error Handling**: Always handle potential API errors.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| instance_id | string | Yes | Your unique WhatsApp Instance ID |
| access_token | string | Yes | Your API Access Token |
| sortBy | string | No | Field to sort by (e.g., id) |
| sortOrder | string | No | Sort direction (ASC or DESC) |
| limit | number | No | Number of chats to return |
| offset | number | No | Number of chats to skip |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Success - Request completed successfully</summary>

```json
{
  "success": true,
  "message": "Operation completed successfully"
}
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (Plain Text)</summary>

```json
"Success: Operation completed successfully."
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Missing Required Parameter(s)</summary>

```json
{
  "code": "missing_param",
  "message": "Missing required parameter: {parameterName}",
  "details": {
    "missing": [
      "{parameterName}"
    ],
    "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (Plain Text)</summary>

```json
"Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized - Invalid or Missing Access Token</summary>

```json
{
  "code": "invalid_access_token",
  "message": "Invalid or expired access token. Please check your credentials.",
  "details": {
    "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
  }
}
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found - Session Does Not Exist</summary>

```json
{
  "code": "invalid_session",
  "message": "Session not found. Please verify your instance_id or session_name.",
  "details": {
    "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
  }
}
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error - Unexpected Failure</summary>

```json
{
  "code": "server_error",
  "message": "An internal server error occurred. Please try again later.",
  "details": {
    "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error (HTML)</summary>

```json
"<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway - Connection Failed to Upstream</summary>

```json
{
  "code": "proxy_error",
  "message": "Failed to connect to WhatsApp server.",
  "details": {
    "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
  }
}
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
```

</details>

### Get Chats Overview
**Endpoint:** `GET /v2/chats/overview`

Retrieve a summary of all active chats and messages metadata.

#### 💡 Tips
- **Performance Tip**: Use the overview for the initial load, then use Webhooks to patch the UI state. Avoid constant polling for the entire list.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| instance_id | string | Yes | Your unique WhatsApp Instance ID |
| access_token | string | Yes | Your API Access Token |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Overview retrieved successfully.</summary>

```json
[
  {
    "id": "447441429009@c.us",
    "name": "John Doe",
    "unreadCount": 5,
    "lastMessage": {
      "id": "ABC123",
      "body": "Hello!",
      "timestamp": 1722170400
    }
  }
]
```

</details>

<details>
<summary><b>HTTP 200</b>: Success - Request completed successfully</summary>

```json
{
  "success": true,
  "message": "Operation completed successfully"
}
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (Plain Text)</summary>

```json
"Success: Operation completed successfully."
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Missing Required Parameter(s)</summary>

```json
{
  "code": "missing_param",
  "message": "Missing required parameter: {parameterName}",
  "details": {
    "missing": [
      "{parameterName}"
    ],
    "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (Plain Text)</summary>

```json
"Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized - Invalid or Missing Access Token</summary>

```json
{
  "code": "invalid_access_token",
  "message": "Invalid or expired access token. Please check your credentials.",
  "details": {
    "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
  }
}
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found - Session Does Not Exist</summary>

```json
{
  "code": "invalid_session",
  "message": "Session not found. Please verify your instance_id or session_name.",
  "details": {
    "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
  }
}
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error - Unexpected Failure</summary>

```json
{
  "code": "server_error",
  "message": "An internal server error occurred. Please try again later.",
  "details": {
    "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error (HTML)</summary>

```json
"<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway - Connection Failed to Upstream</summary>

```json
{
  "code": "proxy_error",
  "message": "Failed to connect to WhatsApp server.",
  "details": {
    "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
  }
}
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
```

</details>

### Get chat picture
**Endpoint:** `GET /v2/chats/picture`

Retrieve the profile picture URL of a chat (individual or group).

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| instance_id | string | Yes | WhatsApp Instance ID |
| access_token | string | Yes | API Access Token |
| chatId | string | Yes | Target Chat ID (phone@c.us or group@g.us) |
| refresh | boolean | No | Force refresh (bypass 24h cache) |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Success - Request completed successfully</summary>

```json
{
  "success": true,
  "message": "Operation completed successfully"
}
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (Plain Text)</summary>

```json
"Success: Operation completed successfully."
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Missing Required Parameter(s)</summary>

```json
{
  "code": "missing_param",
  "message": "Missing required parameter: {parameterName}",
  "details": {
    "missing": [
      "{parameterName}"
    ],
    "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (Plain Text)</summary>

```json
"Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized - Invalid or Missing Access Token</summary>

```json
{
  "code": "invalid_access_token",
  "message": "Invalid or expired access token. Please check your credentials.",
  "details": {
    "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
  }
}
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found - Session Does Not Exist</summary>

```json
{
  "code": "invalid_session",
  "message": "Session not found. Please verify your instance_id or session_name.",
  "details": {
    "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
  }
}
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error - Unexpected Failure</summary>

```json
{
  "code": "server_error",
  "message": "An internal server error occurred. Please try again later.",
  "details": {
    "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error (HTML)</summary>

```json
"<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway - Connection Failed to Upstream</summary>

```json
{
  "code": "proxy_error",
  "message": "Failed to connect to WhatsApp server.",
  "details": {
    "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
  }
}
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
```

</details>

### Get messages in chat
**Endpoint:** `GET /v2/chats/messages`

Retrieve messages from a specific chat with filtering and pagination.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| instance_id | string | Yes | WhatsApp Instance ID |
| access_token | string | Yes | API Access Token |
| chatId | string | Yes | Target Chat ID (phone@c.us or group@g.us) |
| limit | number | No | Number of messages to retrieve |
| offset | number | No | Number of messages to skip |
| downloadMedia | boolean | No | Whether to download and return media content |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Success - Request completed successfully</summary>

```json
{
  "success": true,
  "message": "Operation completed successfully"
}
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (Plain Text)</summary>

```json
"Success: Operation completed successfully."
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Missing Required Parameter(s)</summary>

```json
{
  "code": "missing_param",
  "message": "Missing required parameter: {parameterName}",
  "details": {
    "missing": [
      "{parameterName}"
    ],
    "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (Plain Text)</summary>

```json
"Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized - Invalid or Missing Access Token</summary>

```json
{
  "code": "invalid_access_token",
  "message": "Invalid or expired access token. Please check your credentials.",
  "details": {
    "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
  }
}
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found - Session Does Not Exist</summary>

```json
{
  "code": "invalid_session",
  "message": "Session not found. Please verify your instance_id or session_name.",
  "details": {
    "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
  }
}
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error - Unexpected Failure</summary>

```json
{
  "code": "server_error",
  "message": "An internal server error occurred. Please try again later.",
  "details": {
    "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error (HTML)</summary>

```json
"<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway - Connection Failed to Upstream</summary>

```json
{
  "code": "proxy_error",
  "message": "Failed to connect to WhatsApp server.",
  "details": {
    "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
  }
}
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
```

</details>

### Mark as read
**Endpoint:** `POST /v2/chats/read`

Mark unread messages as read for a specific chat.

#### 💡 Tips
- **Pro-Tip: Blue Tick Delay**: To make bots feel more human, add a random 1-2 second delay before marking a message as read.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| instance_id | string | Yes | WhatsApp Instance ID |
| access_token | string | Yes | API Access Token |
| chatId | string | Yes | Recipient's WhatsApp ID (JID). Supports Individuals (@c.us), Groups (@g.us), and Newsletters (@newsletter). |
| messages | number | No | How many latest to read |
| days | number | No | How many latest days to read |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Success - Request completed successfully</summary>

```json
{
  "success": true,
  "message": "Operation completed successfully"
}
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (Plain Text)</summary>

```json
"Success: Operation completed successfully."
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Missing Required Parameter(s)</summary>

```json
{
  "code": "missing_param",
  "message": "Missing required parameter: {parameterName}",
  "details": {
    "missing": [
      "{parameterName}"
    ],
    "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (Plain Text)</summary>

```json
"Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized - Invalid or Missing Access Token</summary>

```json
{
  "code": "invalid_access_token",
  "message": "Invalid or expired access token. Please check your credentials.",
  "details": {
    "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
  }
}
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found - Session Does Not Exist</summary>

```json
{
  "code": "invalid_session",
  "message": "Session not found. Please verify your instance_id or session_name.",
  "details": {
    "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
  }
}
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error - Unexpected Failure</summary>

```json
{
  "code": "server_error",
  "message": "An internal server error occurred. Please try again later.",
  "details": {
    "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error (HTML)</summary>

```json
"<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway - Connection Failed to Upstream</summary>

```json
{
  "code": "proxy_error",
  "message": "Failed to connect to WhatsApp server.",
  "details": {
    "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
  }
}
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
```

</details>

### Get message by id
**Endpoint:** `POST /v2/messages/get`

Retrieve a specific message by its ID.

#### 💡 Tips
- **Performance Optimization**: Always use lazy loading for media. Use this endpoint only when the user explicitly needs to view an image or video.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| instance_id | string | Yes | WhatsApp Instance ID |
| access_token | string | Yes | API Access Token |
| chatId | string | Yes | Target Chat ID (phone@c.us or group@g.us) |
| messageId | string | Yes | Unique ID of the message |
| downloadMedia | boolean | No | Whether to download and return media content |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Success - Request completed successfully</summary>

```json
{
  "success": true,
  "message": "Operation completed successfully"
}
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (Plain Text)</summary>

```json
"Success: Operation completed successfully."
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Missing Required Parameter(s)</summary>

```json
{
  "code": "missing_param",
  "message": "Missing required parameter: {parameterName}",
  "details": {
    "missing": [
      "{parameterName}"
    ],
    "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (Plain Text)</summary>

```json
"Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized - Invalid or Missing Access Token</summary>

```json
{
  "code": "invalid_access_token",
  "message": "Invalid or expired access token. Please check your credentials.",
  "details": {
    "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
  }
}
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found - Session Does Not Exist</summary>

```json
{
  "code": "invalid_session",
  "message": "Session not found. Please verify your instance_id or session_name.",
  "details": {
    "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
  }
}
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error - Unexpected Failure</summary>

```json
{
  "code": "server_error",
  "message": "An internal server error occurred. Please try again later.",
  "details": {
    "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error (HTML)</summary>

```json
"<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway - Connection Failed to Upstream</summary>

```json
{
  "code": "proxy_error",
  "message": "Failed to connect to WhatsApp server.",
  "details": {
    "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
  }
}
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
```

</details>

### Delete a message
**Endpoint:** `DELETE /v2/messages/delete`

Delete a specific message by its ID.

#### 💡 Tips
- **Time Limit**: Delete for Everyone is usually only available for about 48 hours after the message was sent.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| instance_id | string | Yes | WhatsApp Instance ID |
| access_token | string | Yes | API Access Token |
| chatId | string | Yes | Target Chat ID (phone@c.us or group@g.us) |
| messageId | string | Yes | Unique ID of the message |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Success - Request completed successfully</summary>

```json
{
  "success": true,
  "message": "Operation completed successfully"
}
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (Plain Text)</summary>

```json
"Success: Operation completed successfully."
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Missing Required Parameter(s)</summary>

```json
{
  "code": "missing_param",
  "message": "Missing required parameter: {parameterName}",
  "details": {
    "missing": [
      "{parameterName}"
    ],
    "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (Plain Text)</summary>

```json
"Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized - Invalid or Missing Access Token</summary>

```json
{
  "code": "invalid_access_token",
  "message": "Invalid or expired access token. Please check your credentials.",
  "details": {
    "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
  }
}
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found - Session Does Not Exist</summary>

```json
{
  "code": "invalid_session",
  "message": "Session not found. Please verify your instance_id or session_name.",
  "details": {
    "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
  }
}
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error - Unexpected Failure</summary>

```json
{
  "code": "server_error",
  "message": "An internal server error occurred. Please try again later.",
  "details": {
    "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error (HTML)</summary>

```json
"<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway - Connection Failed to Upstream</summary>

```json
{
  "code": "proxy_error",
  "message": "Failed to connect to WhatsApp server.",
  "details": {
    "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
  }
}
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
```

</details>

### Edit a text message
**Endpoint:** `PUT /v2/messages/edit`

Edit the content of a previously sent text message.

#### 💡 Tips
- **15-Minute Window**: You can usually only edit messages within 15 minutes of sending. Plan your correction logic accordingly.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| instance_id | string | Yes | WhatsApp Instance ID |
| access_token | string | Yes | API Access Token |
| chatId | string | Yes | Target Chat ID (phone@c.us or group@g.us) |
| messageId | string | Yes | Unique ID of the message |
| text | string | Yes | New text content for the message |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Success - Request completed successfully</summary>

```json
{
  "success": true,
  "message": "Operation completed successfully"
}
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (Plain Text)</summary>

```json
"Success: Operation completed successfully."
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Missing Required Parameter(s)</summary>

```json
{
  "code": "missing_param",
  "message": "Missing required parameter: {parameterName}",
  "details": {
    "missing": [
      "{parameterName}"
    ],
    "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (Plain Text)</summary>

```json
"Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized - Invalid or Missing Access Token</summary>

```json
{
  "code": "invalid_access_token",
  "message": "Invalid or expired access token. Please check your credentials.",
  "details": {
    "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
  }
}
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found - Session Does Not Exist</summary>

```json
{
  "code": "invalid_session",
  "message": "Session not found. Please verify your instance_id or session_name.",
  "details": {
    "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
  }
}
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error - Unexpected Failure</summary>

```json
{
  "code": "server_error",
  "message": "An internal server error occurred. Please try again later.",
  "details": {
    "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error (HTML)</summary>

```json
"<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway - Connection Failed to Upstream</summary>

```json
{
  "code": "proxy_error",
  "message": "Failed to connect to WhatsApp server.",
  "details": {
    "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
  }
}
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
```

</details>

### Mark chat as unread
**Endpoint:** `POST /v2/chats/unread`

Explicitly mark a chat as having unread messages.

#### 💡 Tips
- **Internal Workflow**: Use 'Mark as Unread' as a lightweight ticketing system inside WhatsApp without needing external software.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| instance_id | string | Yes | WhatsApp Instance ID |
| access_token | string | Yes | API Access Token |
| chatId | string | Yes | Recipient's WhatsApp ID (JID). Supports Individuals (@c.us), Groups (@g.us), and Newsletters (@newsletter). |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Success - Request completed successfully</summary>

```json
{
  "success": true,
  "message": "Operation completed successfully"
}
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (Plain Text)</summary>

```json
"Success: Operation completed successfully."
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Missing Required Parameter(s)</summary>

```json
{
  "code": "missing_param",
  "message": "Missing required parameter: {parameterName}",
  "details": {
    "missing": [
      "{parameterName}"
    ],
    "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (Plain Text)</summary>

```json
"Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized - Invalid or Missing Access Token</summary>

```json
{
  "code": "invalid_access_token",
  "message": "Invalid or expired access token. Please check your credentials.",
  "details": {
    "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
  }
}
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found - Session Does Not Exist</summary>

```json
{
  "code": "invalid_session",
  "message": "Session not found. Please verify your instance_id or session_name.",
  "details": {
    "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
  }
}
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error - Unexpected Failure</summary>

```json
{
  "code": "server_error",
  "message": "An internal server error occurred. Please try again later.",
  "details": {
    "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error (HTML)</summary>

```json
"<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway - Connection Failed to Upstream</summary>

```json
{
  "code": "proxy_error",
  "message": "Failed to connect to WhatsApp server.",
  "details": {
    "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
  }
}
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
```

</details>

---

## Whatsapp Profile info

### Profile & Identity
Manage your WhatsApp brand identity, including display name, about status, and profile picture.

#### 💡 Tips
- **Circle Crop**: Remember that WhatsApp crops images into a circle. Keep your logo's critical elements in the center 50% of the canvas.

### Get profile
**Endpoint:** `GET /v2/profile`

Retrieve your own WhatsApp profile information (name, status, etc.).

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| instance_id | string | Yes | WhatsApp Instance ID |
| access_token | string | Yes | API Access Token |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Success - Request completed successfully</summary>

```json
{
  "success": true,
  "message": "Operation completed successfully"
}
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (Plain Text)</summary>

```json
"Success: Operation completed successfully."
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Missing Required Parameter(s)</summary>

```json
{
  "code": "missing_param",
  "message": "Missing required parameter: {parameterName}",
  "details": {
    "missing": [
      "{parameterName}"
    ],
    "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (Plain Text)</summary>

```json
"Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized - Invalid or Missing Access Token</summary>

```json
{
  "code": "invalid_access_token",
  "message": "Invalid or expired access token. Please check your credentials.",
  "details": {
    "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
  }
}
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found - Session Does Not Exist</summary>

```json
{
  "code": "invalid_session",
  "message": "Session not found. Please verify your instance_id or session_name.",
  "details": {
    "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
  }
}
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error - Unexpected Failure</summary>

```json
{
  "code": "server_error",
  "message": "An internal server error occurred. Please try again later.",
  "details": {
    "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error (HTML)</summary>

```json
"<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway - Connection Failed to Upstream</summary>

```json
{
  "code": "proxy_error",
  "message": "Failed to connect to WhatsApp server.",
  "details": {
    "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
  }
}
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
```

</details>

### Set Profile Name
**Endpoint:** `PUT /v2/profile/name`

Update your WhatsApp display name (push name).

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| instance_id | string | Yes | WhatsApp Instance ID |
| access_token | string | Yes | API Access Token |
| name | string | Yes | New display name |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Success - Request completed successfully</summary>

```json
{
  "success": true,
  "message": "Operation completed successfully"
}
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (Plain Text)</summary>

```json
"Success: Operation completed successfully."
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Missing Required Parameter(s)</summary>

```json
{
  "code": "missing_param",
  "message": "Missing required parameter: {parameterName}",
  "details": {
    "missing": [
      "{parameterName}"
    ],
    "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (Plain Text)</summary>

```json
"Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized - Invalid or Missing Access Token</summary>

```json
{
  "code": "invalid_access_token",
  "message": "Invalid or expired access token. Please check your credentials.",
  "details": {
    "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
  }
}
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found - Session Does Not Exist</summary>

```json
{
  "code": "invalid_session",
  "message": "Session not found. Please verify your instance_id or session_name.",
  "details": {
    "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
  }
}
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error - Unexpected Failure</summary>

```json
{
  "code": "server_error",
  "message": "An internal server error occurred. Please try again later.",
  "details": {
    "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error (HTML)</summary>

```json
"<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway - Connection Failed to Upstream</summary>

```json
{
  "code": "proxy_error",
  "message": "Failed to connect to WhatsApp server.",
  "details": {
    "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
  }
}
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
```

</details>

### Set 'About' status
**Endpoint:** `PUT /v2/profile/status`

Update your WhatsApp 'About' (bio) status.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| instance_id | string | Yes | WhatsApp Instance ID |
| access_token | string | Yes | API Access Token |
| status | string | Yes | New status text |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Success - Request completed successfully</summary>

```json
{
  "success": true,
  "message": "Operation completed successfully"
}
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (Plain Text)</summary>

```json
"Success: Operation completed successfully."
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Missing Required Parameter(s)</summary>

```json
{
  "code": "missing_param",
  "message": "Missing required parameter: {parameterName}",
  "details": {
    "missing": [
      "{parameterName}"
    ],
    "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (Plain Text)</summary>

```json
"Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized - Invalid or Missing Access Token</summary>

```json
{
  "code": "invalid_access_token",
  "message": "Invalid or expired access token. Please check your credentials.",
  "details": {
    "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
  }
}
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found - Session Does Not Exist</summary>

```json
{
  "code": "invalid_session",
  "message": "Session not found. Please verify your instance_id or session_name.",
  "details": {
    "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
  }
}
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error - Unexpected Failure</summary>

```json
{
  "code": "server_error",
  "message": "An internal server error occurred. Please try again later.",
  "details": {
    "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error (HTML)</summary>

```json
"<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway - Connection Failed to Upstream</summary>

```json
{
  "code": "proxy_error",
  "message": "Failed to connect to WhatsApp server.",
  "details": {
    "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
  }
}
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
```

</details>

### Upload Whatsapp picture
**Endpoint:** `PUT /v2/profile/picture`

Upload a new profile picture for your WhatsApp account.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| instance_id | string | Yes | WhatsApp Instance ID |
| access_token | string | Yes | API Access Token |
| file[url] | string | Yes | Direct URL to the image |
| file[filename] | string | Yes | Name of the file |
| file[mimetype] | string | Yes | MIME type of the image (image/jpeg recommended) |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Success - Request completed successfully</summary>

```json
{
  "success": true,
  "message": "Operation completed successfully"
}
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (Plain Text)</summary>

```json
"Success: Operation completed successfully."
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Missing Required Parameter(s)</summary>

```json
{
  "code": "missing_param",
  "message": "Missing required parameter: {parameterName}",
  "details": {
    "missing": [
      "{parameterName}"
    ],
    "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (Plain Text)</summary>

```json
"Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized - Invalid or Missing Access Token</summary>

```json
{
  "code": "invalid_access_token",
  "message": "Invalid or expired access token. Please check your credentials.",
  "details": {
    "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
  }
}
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found - Session Does Not Exist</summary>

```json
{
  "code": "invalid_session",
  "message": "Session not found. Please verify your instance_id or session_name.",
  "details": {
    "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
  }
}
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error - Unexpected Failure</summary>

```json
{
  "code": "server_error",
  "message": "An internal server error occurred. Please try again later.",
  "details": {
    "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error (HTML)</summary>

```json
"<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway - Connection Failed to Upstream</summary>

```json
{
  "code": "proxy_error",
  "message": "Failed to connect to WhatsApp server.",
  "details": {
    "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
  }
}
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
```

</details>

### Delete profile picture
**Endpoint:** `DELETE /v2/profile/picture-delete`

Remove your current WhatsApp profile picture.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| instance_id | string | Yes | WhatsApp Instance ID |
| access_token | string | Yes | API Access Token |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Success - Request completed successfully</summary>

```json
{
  "success": true,
  "message": "Operation completed successfully"
}
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (Plain Text)</summary>

```json
"Success: Operation completed successfully."
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Missing Required Parameter(s)</summary>

```json
{
  "code": "missing_param",
  "message": "Missing required parameter: {parameterName}",
  "details": {
    "missing": [
      "{parameterName}"
    ],
    "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (Plain Text)</summary>

```json
"Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized - Invalid or Missing Access Token</summary>

```json
{
  "code": "invalid_access_token",
  "message": "Invalid or expired access token. Please check your credentials.",
  "details": {
    "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
  }
}
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found - Session Does Not Exist</summary>

```json
{
  "code": "invalid_session",
  "message": "Session not found. Please verify your instance_id or session_name.",
  "details": {
    "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
  }
}
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error - Unexpected Failure</summary>

```json
{
  "code": "server_error",
  "message": "An internal server error occurred. Please try again later.",
  "details": {
    "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error (HTML)</summary>

```json
"<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway - Connection Failed to Upstream</summary>

```json
{
  "code": "proxy_error",
  "message": "Failed to connect to WhatsApp server.",
  "details": {
    "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
  }
}
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
```

</details>

---

## Presence information

### Presence & Availability
Manage your online status and check the availability of your contacts.

#### 💡 Tips
- **Polling Risk**: Repeatedly polling other users' presence is the #1 cause of bot account bans. Use it sparingly.

### Set session presence
**Endpoint:** `POST /v2/presence`

Sets the presence for the current session (online/offline).

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| instance_id | string | Yes | WhatsApp Instance ID |
| access_token | string | Yes | API Access Token |
| presence | string | Yes | Presence state: online or offline |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Success - Request completed successfully</summary>

```json
{
  "success": true,
  "message": "Operation completed successfully"
}
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (Plain Text)</summary>

```json
"Success: Operation completed successfully."
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Missing Required Parameter(s)</summary>

```json
{
  "code": "missing_param",
  "message": "Missing required parameter: {parameterName}",
  "details": {
    "missing": [
      "{parameterName}"
    ],
    "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (Plain Text)</summary>

```json
"Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized - Invalid or Missing Access Token</summary>

```json
{
  "code": "invalid_access_token",
  "message": "Invalid or expired access token. Please check your credentials.",
  "details": {
    "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
  }
}
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found - Session Does Not Exist</summary>

```json
{
  "code": "invalid_session",
  "message": "Session not found. Please verify your instance_id or session_name.",
  "details": {
    "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
  }
}
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error - Unexpected Failure</summary>

```json
{
  "code": "server_error",
  "message": "An internal server error occurred. Please try again later.",
  "details": {
    "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error (HTML)</summary>

```json
"<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway - Connection Failed to Upstream</summary>

```json
{
  "code": "proxy_error",
  "message": "Failed to connect to WhatsApp server.",
  "details": {
    "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
  }
}
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
```

</details>

### Get the presence for the chat id
**Endpoint:** `GET /v2/presence/{chatId}`

Retrieves the current presence information for a specific chat ID.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| instance_id | string | Yes | WhatsApp Instance ID |
| access_token | string | Yes | API Access Token |
| chatId | string | Yes | The chatId to check presence for |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Success - Request completed successfully</summary>

```json
{
  "success": true,
  "message": "Operation completed successfully"
}
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (Plain Text)</summary>

```json
"Success: Operation completed successfully."
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Missing Required Parameter(s)</summary>

```json
{
  "code": "missing_param",
  "message": "Missing required parameter: {parameterName}",
  "details": {
    "missing": [
      "{parameterName}"
    ],
    "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (Plain Text)</summary>

```json
"Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized - Invalid or Missing Access Token</summary>

```json
{
  "code": "invalid_access_token",
  "message": "Invalid or expired access token. Please check your credentials.",
  "details": {
    "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
  }
}
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found - Session Does Not Exist</summary>

```json
{
  "code": "invalid_session",
  "message": "Session not found. Please verify your instance_id or session_name.",
  "details": {
    "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
  }
}
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error - Unexpected Failure</summary>

```json
{
  "code": "server_error",
  "message": "An internal server error occurred. Please try again later.",
  "details": {
    "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error (HTML)</summary>

```json
"<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway - Connection Failed to Upstream</summary>

```json
{
  "code": "proxy_error",
  "message": "Failed to connect to WhatsApp server.",
  "details": {
    "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
  }
}
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
```

</details>

---

## Presence

### Get General Presence
**Endpoint:** `GET /v2/presence`

Get the current presence status (online/offline) for the authenticated session.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| instance_id | string | Yes | Your unique WhatsApp Instance ID |
| access_token | string | Yes | Your API Access Token |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Presence status retrieved</summary>

```json
{
  "presence": "online"
}
```

</details>

<details>
<summary><b>HTTP 200</b>: Success - Request completed successfully</summary>

```json
{
  "success": true,
  "message": "Operation completed successfully"
}
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (Plain Text)</summary>

```json
"Success: Operation completed successfully."
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Missing Required Parameter(s)</summary>

```json
{
  "code": "missing_param",
  "message": "Missing required parameter: {parameterName}",
  "details": {
    "missing": [
      "{parameterName}"
    ],
    "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (Plain Text)</summary>

```json
"Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized - Invalid or Missing Access Token</summary>

```json
{
  "code": "invalid_access_token",
  "message": "Invalid or expired access token. Please check your credentials.",
  "details": {
    "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
  }
}
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found - Session Does Not Exist</summary>

```json
{
  "code": "invalid_session",
  "message": "Session not found. Please verify your instance_id or session_name.",
  "details": {
    "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
  }
}
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error - Unexpected Failure</summary>

```json
{
  "code": "server_error",
  "message": "An internal server error occurred. Please try again later.",
  "details": {
    "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error (HTML)</summary>

```json
"<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway - Connection Failed to Upstream</summary>

```json
{
  "code": "proxy_error",
  "message": "Failed to connect to WhatsApp server.",
  "details": {
    "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
  }
}
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
```

</details>

### Subscribe to Presence
**Endpoint:** `POST /v2/presence/{chatId}/subscribe`

Subscribe to real-time presence updates (online/offline) for a specific contact.

#### 💡 Tips
- **Monitoring**: Great for CRM systems that need to know when a customer is active to initiate a chat.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| instance_id | string | Yes | Your unique WhatsApp Instance ID |
| access_token | string | Yes | Your API Access Token |
| chatId | string | Yes | The identifier for the contact (@c.us) |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Success - Request completed successfully</summary>

```json
{
  "success": true,
  "message": "Operation completed successfully"
}
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (Plain Text)</summary>

```json
"Success: Operation completed successfully."
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Missing Required Parameter(s)</summary>

```json
{
  "code": "missing_param",
  "message": "Missing required parameter: {parameterName}",
  "details": {
    "missing": [
      "{parameterName}"
    ],
    "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (Plain Text)</summary>

```json
"Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized - Invalid or Missing Access Token</summary>

```json
{
  "code": "invalid_access_token",
  "message": "Invalid or expired access token. Please check your credentials.",
  "details": {
    "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
  }
}
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found - Session Does Not Exist</summary>

```json
{
  "code": "invalid_session",
  "message": "Session not found. Please verify your instance_id or session_name.",
  "details": {
    "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
  }
}
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error - Unexpected Failure</summary>

```json
{
  "code": "server_error",
  "message": "An internal server error occurred. Please try again later.",
  "details": {
    "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error (HTML)</summary>

```json
"<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway - Connection Failed to Upstream</summary>

```json
{
  "code": "proxy_error",
  "message": "Failed to connect to WhatsApp server.",
  "details": {
    "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
  }
}
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
```

</details>

---

## 24 Hour Status

### WhatsApp Status (Stories)
Learn how to post text, image, and video updates that disappear after 24 hours.

#### 💡 Tips
- **Disappearing Content**: Status updates are the best way to share time-sensitive info without cluttering your chat history.

### Text status
**Endpoint:** `POST /v2/status/text`

Post a text-based status (story) to WhatsApp.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| instance_id | string | Yes | WhatsApp Instance ID |
| access_token | string | Yes | API Access Token |
| text | string | Yes | Text content for the status |
| backgroundColor | string | Yes | Background color in #RRGGBB format |
| font | number | Yes | Font ID (0-5 mostly) |
| linkPreview | boolean | Yes | Enable link preview |
| linkPreviewHighQuality | boolean | Yes | High quality link preview |
| contacts | string | Yes | Optional contacts to mention or target |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Success - Request completed successfully</summary>

```json
{
  "success": true,
  "message": "Operation completed successfully"
}
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (Plain Text)</summary>

```json
"Success: Operation completed successfully."
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Missing Required Parameter(s)</summary>

```json
{
  "code": "missing_param",
  "message": "Missing required parameter: {parameterName}",
  "details": {
    "missing": [
      "{parameterName}"
    ],
    "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (Plain Text)</summary>

```json
"Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized - Invalid or Missing Access Token</summary>

```json
{
  "code": "invalid_access_token",
  "message": "Invalid or expired access token. Please check your credentials.",
  "details": {
    "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
  }
}
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found - Session Does Not Exist</summary>

```json
{
  "code": "invalid_session",
  "message": "Session not found. Please verify your instance_id or session_name.",
  "details": {
    "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
  }
}
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error - Unexpected Failure</summary>

```json
{
  "code": "server_error",
  "message": "An internal server error occurred. Please try again later.",
  "details": {
    "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error (HTML)</summary>

```json
"<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway - Connection Failed to Upstream</summary>

```json
{
  "code": "proxy_error",
  "message": "Failed to connect to WhatsApp server.",
  "details": {
    "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
  }
}
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
```

</details>

### Image status
**Endpoint:** `POST /v2/status/image`

Post an image status (story) to WhatsApp.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| instance_id | string | Yes | WhatsApp Instance ID |
| access_token | string | Yes | API Access Token |
| file[url] | string | Yes | Direct URL to the image |
| file[filename] | string | Yes | Name of the file |
| file[mimetype] | string | Yes | MIME type of the image |
| caption | string | Yes | Caption for the image |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Success - Request completed successfully</summary>

```json
{
  "success": true,
  "message": "Operation completed successfully"
}
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (Plain Text)</summary>

```json
"Success: Operation completed successfully."
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Missing Required Parameter(s)</summary>

```json
{
  "code": "missing_param",
  "message": "Missing required parameter: {parameterName}",
  "details": {
    "missing": [
      "{parameterName}"
    ],
    "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (Plain Text)</summary>

```json
"Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized - Invalid or Missing Access Token</summary>

```json
{
  "code": "invalid_access_token",
  "message": "Invalid or expired access token. Please check your credentials.",
  "details": {
    "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
  }
}
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found - Session Does Not Exist</summary>

```json
{
  "code": "invalid_session",
  "message": "Session not found. Please verify your instance_id or session_name.",
  "details": {
    "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
  }
}
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error - Unexpected Failure</summary>

```json
{
  "code": "server_error",
  "message": "An internal server error occurred. Please try again later.",
  "details": {
    "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error (HTML)</summary>

```json
"<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway - Connection Failed to Upstream</summary>

```json
{
  "code": "proxy_error",
  "message": "Failed to connect to WhatsApp server.",
  "details": {
    "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
  }
}
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
```

</details>

### Voice status
**Endpoint:** `POST /v2/status/voice`

Post a voice status (story) to WhatsApp.

#### 💡 Tips
- **Background**: Voice statuses allow you to share audio updates with contacts.
- **Duration**: Limited to 30 seconds, similar to video status.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| instance_id | string | Yes | WhatsApp Instance ID |
| access_token | string | Yes | API Access Token |
| file[url] | string | Yes | URL to the audio file (ogg/opus recommended) |
| file[filename] | string | Yes | Name of the file |
| file[mimetype] | string | Yes | MIME type |
| convert | boolean | Yes | Enable auto-conversion |
| caption | string | Yes | Caption for the voice status |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Success - Request completed successfully</summary>

```json
{
  "success": true,
  "message": "Operation completed successfully"
}
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (Plain Text)</summary>

```json
"Success: Operation completed successfully."
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Missing Required Parameter(s)</summary>

```json
{
  "code": "missing_param",
  "message": "Missing required parameter: {parameterName}",
  "details": {
    "missing": [
      "{parameterName}"
    ],
    "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (Plain Text)</summary>

```json
"Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized - Invalid or Missing Access Token</summary>

```json
{
  "code": "invalid_access_token",
  "message": "Invalid or expired access token. Please check your credentials.",
  "details": {
    "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
  }
}
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found - Session Does Not Exist</summary>

```json
{
  "code": "invalid_session",
  "message": "Session not found. Please verify your instance_id or session_name.",
  "details": {
    "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
  }
}
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error - Unexpected Failure</summary>

```json
{
  "code": "server_error",
  "message": "An internal server error occurred. Please try again later.",
  "details": {
    "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error (HTML)</summary>

```json
"<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway - Connection Failed to Upstream</summary>

```json
{
  "code": "proxy_error",
  "message": "Failed to connect to WhatsApp server.",
  "details": {
    "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
  }
}
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
```

</details>

### Video status
**Endpoint:** `POST /v2/status/video`

Post a video status (story) to WhatsApp.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| instance_id | string | Yes | WhatsApp Instance ID |
| access_token | string | Yes | API Access Token |
| file[url] | string | Yes | URL to the video file |
| file[filename] | string | Yes | Name of the file |
| file[mimetype] | string | Yes | MIME type |
| convert | boolean | Yes | Enable auto-conversion |
| asNote | boolean | Yes | Send as video note |
| caption | string | Yes | Caption for the video |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Success - Request completed successfully</summary>

```json
{
  "success": true,
  "message": "Operation completed successfully"
}
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (Plain Text)</summary>

```json
"Success: Operation completed successfully."
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Missing Required Parameter(s)</summary>

```json
{
  "code": "missing_param",
  "message": "Missing required parameter: {parameterName}",
  "details": {
    "missing": [
      "{parameterName}"
    ],
    "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (Plain Text)</summary>

```json
"Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized - Invalid or Missing Access Token</summary>

```json
{
  "code": "invalid_access_token",
  "message": "Invalid or expired access token. Please check your credentials.",
  "details": {
    "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
  }
}
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found - Session Does Not Exist</summary>

```json
{
  "code": "invalid_session",
  "message": "Session not found. Please verify your instance_id or session_name.",
  "details": {
    "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
  }
}
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error - Unexpected Failure</summary>

```json
{
  "code": "server_error",
  "message": "An internal server error occurred. Please try again later.",
  "details": {
    "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error (HTML)</summary>

```json
"<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway - Connection Failed to Upstream</summary>

```json
{
  "code": "proxy_error",
  "message": "Failed to connect to WhatsApp server.",
  "details": {
    "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
  }
}
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
```

</details>

### Delete status
**Endpoint:** `POST /v2/status/delete`

Delete a specific status (story) by ID.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| instance_id | string | Yes | WhatsApp Instance ID |
| access_token | string | Yes | API Access Token |
| id | string | Yes | The status message ID to delete |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Success - Request completed successfully</summary>

```json
{
  "success": true,
  "message": "Operation completed successfully"
}
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (Plain Text)</summary>

```json
"Success: Operation completed successfully."
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Missing Required Parameter(s)</summary>

```json
{
  "code": "missing_param",
  "message": "Missing required parameter: {parameterName}",
  "details": {
    "missing": [
      "{parameterName}"
    ],
    "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (Plain Text)</summary>

```json
"Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized - Invalid or Missing Access Token</summary>

```json
{
  "code": "invalid_access_token",
  "message": "Invalid or expired access token. Please check your credentials.",
  "details": {
    "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
  }
}
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found - Session Does Not Exist</summary>

```json
{
  "code": "invalid_session",
  "message": "Session not found. Please verify your instance_id or session_name.",
  "details": {
    "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
  }
}
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error - Unexpected Failure</summary>

```json
{
  "code": "server_error",
  "message": "An internal server error occurred. Please try again later.",
  "details": {
    "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error (HTML)</summary>

```json
"<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway - Connection Failed to Upstream</summary>

```json
{
  "code": "proxy_error",
  "message": "Failed to connect to WhatsApp server.",
  "details": {
    "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
  }
}
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
```

</details>

---

## Status

### Get New Status ID
**Endpoint:** `GET /v2/status/new-message-id`

Generate a new message ID for a status update. Useful for idempotent status updates.

#### 💡 Tips
- **Format**: Generates a hexadecimal ID required for creating new status updates.
- **Uniqueness**: Ensures your status update doesn't collide with others.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| instance_id | string | Yes | Your unique WhatsApp Instance ID |
| access_token | string | Yes | Your API Access Token |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: New ID generated</summary>

```json
{
  "id": "3EB0BCB2E3D4"
}
```

</details>

<details>
<summary><b>HTTP 200</b>: Success - Request completed successfully</summary>

```json
{
  "success": true,
  "message": "Operation completed successfully"
}
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (Plain Text)</summary>

```json
"Success: Operation completed successfully."
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Missing Required Parameter(s)</summary>

```json
{
  "code": "missing_param",
  "message": "Missing required parameter: {parameterName}",
  "details": {
    "missing": [
      "{parameterName}"
    ],
    "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (Plain Text)</summary>

```json
"Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized - Invalid or Missing Access Token</summary>

```json
{
  "code": "invalid_access_token",
  "message": "Invalid or expired access token. Please check your credentials.",
  "details": {
    "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
  }
}
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found - Session Does Not Exist</summary>

```json
{
  "code": "invalid_session",
  "message": "Session not found. Please verify your instance_id or session_name.",
  "details": {
    "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
  }
}
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error - Unexpected Failure</summary>

```json
{
  "code": "server_error",
  "message": "An internal server error occurred. Please try again later.",
  "details": {
    "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error (HTML)</summary>

```json
"<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway - Connection Failed to Upstream</summary>

```json
{
  "code": "proxy_error",
  "message": "Failed to connect to WhatsApp server.",
  "details": {
    "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
  }
}
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
```

</details>

---

## Channels Control

### Channels Management
Learn how to create, manage, and search for WhatsApp Channels using Wawp.

#### 💡 Tips
- **Subscriber Privacy**: Channel owners cannot see the phone numbers of their subscribers, ensuring high-privacy broadcasting.

### Get Channels List
**Endpoint:** `GET /v2/channels`

Retrieve a list of WhatsApp channels known to the instance, filtered by role if specified.

#### 💡 Tips
- **Scope**: Returns channels you follow or own.
- **Pagination**: This list can be long. Use pagination cursors if available.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| instance_id | string | Yes | Your unique WhatsApp Instance ID |
| access_token | string | Yes | Your API Access Token |
| role | string | No | Filter by role. Available values: OWNER, ADMIN, SUBSCRIBER |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: List of channels retrieved successfully</summary>

```json
[
  {
    "id": "1234567890@newsletter",
    "name": "Wawp Updates",
    "role": "OWNER",
    "description": "Official updates from Wawp"
  }
]
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized - Invalid or Missing Access Token</summary>

```json
{
  "code": "invalid_access_token",
  "message": "Invalid or expired access token. Please check your credentials.",
  "details": {
    "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Invalid Parameter Format</summary>

```json
{
  "code": "invalid_param",
  "message": "Invalid format for one or more parameters.",
  "details": {
    "param": "text",
    "value": "too_long",
    "recommendation": "Refer to the documentation for the allowed format and length of this parameter."
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error - Unexpected Failure</summary>

```json
{
  "code": "server_error",
  "message": "An internal server error occurred. Please try again later.",
  "details": {
    "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
  }
}
```

</details>

### Create Channel
**Endpoint:** `POST /v2/channels/create`

Create a new WhatsApp channel with a name, description, and profile picture.

#### 💡 Tips
- **Visibility**: Channels are public by default. Anyone can search and find them.
- **Broadcast**: Channels are one-way broadcast tools; followers cannot reply with text.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| access_token | string | Yes | Your API Access Token |
| instance_id | string | Yes | Your unique WhatsApp Instance ID |
| name | string | Yes | The name of the channel |
| description | string | No | A brief description of the channel |
| picture | object | No | Channel profile picture details |
| type | string | No | Channel type |

#### 📦 Responses

<details>
<summary><b>HTTP 201</b>: Channel created successfully</summary>

```json
{
  "id": "1234567890@newsletter",
  "status": "success",
  "message": "Channel created successfully"
}
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized - Invalid or Missing Access Token</summary>

```json
{
  "code": "invalid_access_token",
  "message": "Invalid or expired access token. Please check your credentials.",
  "details": {
    "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Invalid Parameter Format</summary>

```json
{
  "code": "invalid_param",
  "message": "Invalid format for one or more parameters.",
  "details": {
    "param": "text",
    "value": "too_long",
    "recommendation": "Refer to the documentation for the allowed format and length of this parameter."
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error - Unexpected Failure</summary>

```json
{
  "code": "server_error",
  "message": "An internal server error occurred. Please try again later.",
  "details": {
    "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
  }
}
```

</details>

### Get Channel Info
**Endpoint:** `GET /v2/channels/{id}`

Get detailed information about a specific channel.

#### 💡 Tips
- **Verification**: Returns verification status (Green checkmark).
- **Stats**: Includes subscriber count and channel creation date.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| id | string | Yes | The unique ID of the channel |
| instance_id | string | Yes | Your unique WhatsApp Instance ID |
| access_token | string | Yes | Your API Access Token |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Channel info retrieved successfully</summary>

```json
{
  "id": "1234567890@newsletter",
  "name": "Channel Name",
  "description": "Channel Description",
  "subscribers": 1500
}
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found - Session Does Not Exist</summary>

```json
{
  "code": "invalid_session",
  "message": "Session not found. Please verify your instance_id or session_name.",
  "details": {
    "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
  }
}
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized - Invalid or Missing Access Token</summary>

```json
{
  "code": "invalid_access_token",
  "message": "Invalid or expired access token. Please check your credentials.",
  "details": {
    "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error - Unexpected Failure</summary>

```json
{
  "code": "server_error",
  "message": "An internal server error occurred. Please try again later.",
  "details": {
    "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
  }
}
```

</details>

### Preview Channel Messages
**Endpoint:** `GET /v2/channels/{invite}/messages/preview`

Preview messages from a public channel using an invite code or link. (Wawp PLUS Feature)

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| instance_id | string | Yes | Your unique WhatsApp Instance ID |
| access_token | string | Yes | Your API Access Token |
| invite | string | Yes | Channel invite code or full link |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Messages previewed</summary>

```json
[
  {
    "id": "123",
    "body": "Welcome to our channel!",
    "timestamp": 1722170400
  }
]
```

</details>

<details>
<summary><b>HTTP 200</b>: Success - Request completed successfully</summary>

```json
{
  "success": true,
  "message": "Operation completed successfully"
}
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (Plain Text)</summary>

```json
"Success: Operation completed successfully."
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Missing Required Parameter(s)</summary>

```json
{
  "code": "missing_param",
  "message": "Missing required parameter: {parameterName}",
  "details": {
    "missing": [
      "{parameterName}"
    ],
    "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (Plain Text)</summary>

```json
"Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized - Invalid or Missing Access Token</summary>

```json
{
  "code": "invalid_access_token",
  "message": "Invalid or expired access token. Please check your credentials.",
  "details": {
    "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
  }
}
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found - Session Does Not Exist</summary>

```json
{
  "code": "invalid_session",
  "message": "Session not found. Please verify your instance_id or session_name.",
  "details": {
    "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
  }
}
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error - Unexpected Failure</summary>

```json
{
  "code": "server_error",
  "message": "An internal server error occurred. Please try again later.",
  "details": {
    "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error (HTML)</summary>

```json
"<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway - Connection Failed to Upstream</summary>

```json
{
  "code": "proxy_error",
  "message": "Failed to connect to WhatsApp server.",
  "details": {
    "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
  }
}
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
```

</details>

### Follow Channel
**Endpoint:** `POST /v2/channels/{id}/follow`

Start following a WhatsApp channel to receive its updates.

#### 💡 Tips
- **Privacy**: Channel admins cannot see the phone numbers of followers.
- **Updates**: Following ensures updates appear in the Updates tab.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| id | string | Yes | The unique ID of the channel |
| instance_id | string | Yes | Your unique WhatsApp Instance ID |
| access_token | string | Yes | Your API Access Token |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Followed channel successfully</summary>

```json
{
  "status": "success",
  "message": "Now following the channel"
}
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized - Invalid or Missing Access Token</summary>

```json
{
  "code": "invalid_access_token",
  "message": "Invalid or expired access token. Please check your credentials.",
  "details": {
    "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error - Unexpected Failure</summary>

```json
{
  "code": "server_error",
  "message": "An internal server error occurred. Please try again later.",
  "details": {
    "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
  }
}
```

</details>

### Unfollow Channel
**Endpoint:** `POST /v2/channels/{id}/unfollow`

Stop following a WhatsApp channel.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| id | string | Yes | The unique ID of the channel |
| instance_id | string | Yes | Your unique WhatsApp Instance ID |
| access_token | string | Yes | Your API Access Token |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Unfollowed channel successfully</summary>

```json
{
  "status": "success",
  "message": "No longer following the channel"
}
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized - Invalid or Missing Access Token</summary>

```json
{
  "code": "invalid_access_token",
  "message": "Invalid or expired access token. Please check your credentials.",
  "details": {
    "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error - Unexpected Failure</summary>

```json
{
  "code": "server_error",
  "message": "An internal server error occurred. Please try again later.",
  "details": {
    "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
  }
}
```

</details>

### Mute Channel
**Endpoint:** `POST /v2/channels/{id}/mute`

Mute notifications for a specific channel.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| id | string | Yes | The unique ID of the channel |
| instance_id | string | Yes | Your unique WhatsApp Instance ID |
| access_token | string | Yes | Your API Access Token |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Channel muted successfully</summary>

```json
{
  "status": "success",
  "message": "Channel muted"
}
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized - Invalid or Missing Access Token</summary>

```json
{
  "code": "invalid_access_token",
  "message": "Invalid or expired access token. Please check your credentials.",
  "details": {
    "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error - Unexpected Failure</summary>

```json
{
  "code": "server_error",
  "message": "An internal server error occurred. Please try again later.",
  "details": {
    "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
  }
}
```

</details>

### Unmute Channel
**Endpoint:** `POST /v2/channels/{id}/unmute`

Unmute notifications for a specific channel.

#### 💡 Tips
- **Engagement**: Enables push notifications for new updates.
- **Volume**: Ensure you want notifications for every broadcast.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| id | string | Yes | The unique ID of the channel |
| instance_id | string | Yes | Your unique WhatsApp Instance ID |
| access_token | string | Yes | Your API Access Token |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Channel unmuted successfully</summary>

```json
{
  "status": "success",
  "message": "Channel unmuted"
}
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized - Invalid or Missing Access Token</summary>

```json
{
  "code": "invalid_access_token",
  "message": "Invalid or expired access token. Please check your credentials.",
  "details": {
    "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error - Unexpected Failure</summary>

```json
{
  "code": "server_error",
  "message": "An internal server error occurred. Please try again later.",
  "details": {
    "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
  }
}
```

</details>

### Search Channels by View
**Endpoint:** `GET /v2/channels/search/view`

Search for channels based on views like RECOMMENDED.

#### 💡 Tips
- **Visuals**: Optimized for rendering search result cards.
- **Badges**: Includes verification badge status in the response.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| instance_id | string | Yes | Your unique WhatsApp Instance ID |
| access_token | string | Yes | Your API Access Token |
| view | string | Yes | The view to search by (e.g. RECOMMENDED, POPULAR, NEW) |
| countries | array[string] | Yes | Filter by countries (comma separated). e.g. EG,US,SA |
| categories | array[string] | Yes | Filter by categories. e.g. ENTERTAINMENT,SPORTS |
| limit | number | Yes | Maximum number of results |
| startCursor | string | Yes | Cursor for pagination. Leave as empty string for the first page. |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Channels retrieved successfully</summary>

```json
{
  "channels": [],
  "nextCursor": "cursor_456"
}
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized - Invalid or Missing Access Token</summary>

```json
{
  "code": "invalid_access_token",
  "message": "Invalid or expired access token. Please check your credentials.",
  "details": {
    "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error - Unexpected Failure</summary>

```json
{
  "code": "server_error",
  "message": "An internal server error occurred. Please try again later.",
  "details": {
    "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
  }
}
```

</details>

### Search Channels by Text
**Endpoint:** `GET /v2/channels/search/text`

Search for channels using a text query.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| instance_id | string | Yes | Your unique WhatsApp Instance ID |
| access_token | string | Yes | Your API Access Token |
| text | string | Yes | The search query text |
| categories | array[string] | Yes | Filter by categories. e.g. ENTERTAINMENT,SPORTS |
| limit | number | Yes | Maximum number of results |
| startCursor | string | Yes | Cursor for pagination. Leave as empty string for the first page. |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Channels retrieved successfully</summary>

```json
{
  "channels": [],
  "nextCursor": "cursor_456"
}
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized - Invalid or Missing Access Token</summary>

```json
{
  "code": "invalid_access_token",
  "message": "Invalid or expired access token. Please check your credentials.",
  "details": {
    "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error - Unexpected Failure</summary>

```json
{
  "code": "server_error",
  "message": "An internal server error occurred. Please try again later.",
  "details": {
    "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
  }
}
```

</details>

### Get Channel Views
**Endpoint:** `GET /v2/channels/search/views`

Retrieve available view types for searching channels (e.g. RECOMMENDED, MOST_ACTIVE).

#### 💡 Tips
- **Analytics**: Returns view counts and interaction metrics.
- **Privacy**: Metrics are aggregated and approximate to protect user privacy.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| instance_id | string | Yes | Your unique WhatsApp Instance ID |
| access_token | string | Yes | Your API Access Token |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Views retrieved successfully</summary>

```json
[
  "RECOMMENDED",
  "MOST_ACTIVE",
  "POPULAR"
]
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized - Invalid or Missing Access Token</summary>

```json
{
  "code": "invalid_access_token",
  "message": "Invalid or expired access token. Please check your credentials.",
  "details": {
    "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error - Unexpected Failure</summary>

```json
{
  "code": "server_error",
  "message": "An internal server error occurred. Please try again later.",
  "details": {
    "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
  }
}
```

</details>

### Get Channel Countries
**Endpoint:** `GET /v2/channels/search/countries`

Retrieve available country filters for searching channels.

#### 💡 Tips
- **ISO Codes**: Uses standard ISO 3166-1 alpha-2 country codes.
- **Localization**: Channels are often region-locked or ranked by country.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| instance_id | string | Yes | Your unique WhatsApp Instance ID |
| access_token | string | Yes | Your API Access Token |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Countries retrieved successfully</summary>

```json
[
  "US",
  "EG",
  "SA",
  "AE"
]
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized - Invalid or Missing Access Token</summary>

```json
{
  "code": "invalid_access_token",
  "message": "Invalid or expired access token. Please check your credentials.",
  "details": {
    "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error - Unexpected Failure</summary>

```json
{
  "code": "server_error",
  "message": "An internal server error occurred. Please try again later.",
  "details": {
    "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
  }
}
```

</details>

### Get Channel Categories
**Endpoint:** `GET /v2/channels/search/categories`

Retrieve available channel categories for searching.

#### 💡 Tips
- **Directory**: Lists available categories (e.g., News, Sports, Entertainment).
- **Discovery**: Use correct categories to improve your channel's visibility.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| instance_id | string | Yes | Your unique WhatsApp Instance ID |
| access_token | string | Yes | Your API Access Token |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Categories retrieved successfully</summary>

```json
[
  "Entertainment",
  "News",
  "Technology"
]
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized - Invalid or Missing Access Token</summary>

```json
{
  "code": "invalid_access_token",
  "message": "Invalid or expired access token. Please check your credentials.",
  "details": {
    "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error - Unexpected Failure</summary>

```json
{
  "code": "server_error",
  "message": "An internal server error occurred. Please try again later.",
  "details": {
    "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
  }
}
```

</details>

---

## Contacts

### Contacts Management
Overview of how to manage WhatsApp contacts, check existence, and handle blocks.

#### 💡 Tips
- **WhatsApp Existence**: Always check if a number exists before sending your first message to avoid 'Invalid Recipient' errors.

### Get All Contacts
**Endpoint:** `GET /v2/contacts/all`

Retrieves a list of all known contacts from the connected WhatsApp account's address book and chat history.

#### 💡 Tips
- **Sync**: Returns all contacts sync'd from the phone's address book.
- **Performance**: Can be slow for accounts with thousands of contacts. Use caching.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| instance_id | string | Yes | Your unique WhatsApp Instance ID |
| access_token | string | Yes | Your API Access Token |
| limit | string | No | Maximum number of contacts to return (1-1000) |
| offset | string | No | Number of contacts to skip |
| sortBy | string | No | Field to sort by (e.g., name) |
| sortOrder | string | No | Sort order (ASC or DESC) |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: List of contacts retrieved successfully</summary>

```json
[
  {
    "id": "1234567890@c.us",
    "name": "John Doe",
    "pushname": "John"
  },
  {
    "id": "0987654321@lid",
    "name": "Business Contact",
    "pushname": "Business"
  }
]
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized - Invalid or Missing Access Token</summary>

```json
{
  "code": "invalid_access_token",
  "message": "Invalid or expired access token. Please check your credentials.",
  "details": {
    "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Invalid Parameter Format</summary>

```json
{
  "code": "invalid_param",
  "message": "Invalid format for one or more parameters.",
  "details": {
    "param": "text",
    "value": "too_long",
    "recommendation": "Refer to the documentation for the allowed format and length of this parameter."
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error - Unexpected Failure</summary>

```json
{
  "code": "server_error",
  "message": "An internal server error occurred. Please try again later.",
  "details": {
    "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
  }
}
```

</details>

### Get Contact Info
**Endpoint:** `GET /v2/contacts`

Get basic information about a specific contact.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| instance_id | string | Yes | Your unique WhatsApp Instance ID |
| access_token | string | Yes | Your API Access Token |
| contactId | string | Yes | The unique ID of the contact (e.g., 123456789@c.us) |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Contact info retrieved successfully</summary>

```json
{
  "id": "123456789@c.us",
  "name": "John Doe",
  "pushname": "John",
  "isBusiness": false,
  "isEnterprise": false
}
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized - Invalid or Missing Access Token</summary>

```json
{
  "code": "invalid_access_token",
  "message": "Invalid or expired access token. Please check your credentials.",
  "details": {
    "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Invalid Parameter Format</summary>

```json
{
  "code": "invalid_param",
  "message": "Invalid format for one or more parameters.",
  "details": {
    "param": "text",
    "value": "too_long",
    "recommendation": "Refer to the documentation for the allowed format and length of this parameter."
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error - Unexpected Failure</summary>

```json
{
  "code": "server_error",
  "message": "An internal server error occurred. Please try again later.",
  "details": {
    "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
  }
}
```

</details>

### Check Phone on WhatsApp
**Endpoint:** `GET /v2/contacts/check-exists`

Check if a phone number is registered on WhatsApp.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| instance_id | string | Yes | Your unique WhatsApp Instance ID |
| access_token | string | Yes | Your API Access Token |
| phone | string | Yes | Phone number to check (digits only) |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Check completed</summary>

```json
{
  "exists": true,
  "jid": "1234567890@c.us"
}
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized - Invalid or Missing Access Token</summary>

```json
{
  "code": "invalid_access_token",
  "message": "Invalid or expired access token. Please check your credentials.",
  "details": {
    "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Invalid Parameter Format</summary>

```json
{
  "code": "invalid_param",
  "message": "Invalid format for one or more parameters.",
  "details": {
    "param": "text",
    "value": "too_long",
    "recommendation": "Refer to the documentation for the allowed format and length of this parameter."
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error - Unexpected Failure</summary>

```json
{
  "code": "server_error",
  "message": "An internal server error occurred. Please try again later.",
  "details": {
    "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
  }
}
```

</details>

### Get Contact Profile Picture
**Endpoint:** `GET /v2/contacts/profile-picture`

Get the profile picture URL of a contact.

#### 💡 Tips
- **Privacy**: You will get a 404 or placeholder if the user hides their photo.
- **Caching**: URLs are temporary; download the image immediately.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| instance_id | string | Yes | Your unique WhatsApp Instance ID |
| access_token | string | Yes | Your API Access Token |
| contactId | string | Yes | The unique ID of the contact |
| refresh | boolean | No | Whether to bypass cache and refresh the picture |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Profile picture retrieved</summary>

```json
{
  "id": "123456789@c.us",
  "url": "https://pps.whatsapp.net/v/t61.24694-24/..."
}
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized - Invalid or Missing Access Token</summary>

```json
{
  "code": "invalid_access_token",
  "message": "Invalid or expired access token. Please check your credentials.",
  "details": {
    "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Invalid Parameter Format</summary>

```json
{
  "code": "invalid_param",
  "message": "Invalid format for one or more parameters.",
  "details": {
    "param": "text",
    "value": "too_long",
    "recommendation": "Refer to the documentation for the allowed format and length of this parameter."
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error - Unexpected Failure</summary>

```json
{
  "code": "server_error",
  "message": "An internal server error occurred. Please try again later.",
  "details": {
    "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
  }
}
```

</details>

### Create/Update Contact
**Endpoint:** `PUT /v2/contacts/{chatId}`

Create or update a contact in the phone's address book.

#### 💡 Tips
- **Local Sync**: Updates the contact name in the phone's address book.
- **Permissions**: Requires 'Write Contacts' permission on the host device.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| chatId | string | Yes | The unique ID of the contact |
| instance_id | string | Yes | Your unique WhatsApp Instance ID |
| access_token | string | Yes | Your API Access Token |
| firstName | string | No | First name of the contact |
| lastName | string | No | Last name of the contact |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Contact updated successfully</summary>

```json
{
  "ok": true
}
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized - Invalid or Missing Access Token</summary>

```json
{
  "code": "invalid_access_token",
  "message": "Invalid or expired access token. Please check your credentials.",
  "details": {
    "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Invalid Parameter Format</summary>

```json
{
  "code": "invalid_param",
  "message": "Invalid format for one or more parameters.",
  "details": {
    "param": "text",
    "value": "too_long",
    "recommendation": "Refer to the documentation for the allowed format and length of this parameter."
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error - Unexpected Failure</summary>

```json
{
  "code": "server_error",
  "message": "An internal server error occurred. Please try again later.",
  "details": {
    "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
  }
}
```

</details>

### Get LIDs Mapping
**Endpoint:** `GET /v2/lids`

Retrieves all known LID to phone number mappings.

#### 💡 Tips
- **Dump**: Returns all LID mappings stored on the device.
- **Size**: Payload can be large. Parse efficiently.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| instance_id | string | Yes | Your unique WhatsApp Instance ID |
| access_token | string | Yes | Your API Access Token |
| limit | string | No | Maximum number of mappings to return |
| offset | string | No | Number of mappings to skip |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: LIDs mapped successfully</summary>

```json
[
  {
    "lid": "1234567890@lid",
    "number": "1234567890"
  }
]
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized - Invalid or Missing Access Token</summary>

```json
{
  "code": "invalid_access_token",
  "message": "Invalid or expired access token. Please check your credentials.",
  "details": {
    "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Invalid Parameter Format</summary>

```json
{
  "code": "invalid_param",
  "message": "Invalid format for one or more parameters.",
  "details": {
    "param": "text",
    "value": "too_long",
    "recommendation": "Refer to the documentation for the allowed format and length of this parameter."
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error - Unexpected Failure</summary>

```json
{
  "code": "server_error",
  "message": "An internal server error occurred. Please try again later.",
  "details": {
    "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
  }
}
```

</details>

### Get LID by Phone
**Endpoint:** `GET /v2/lids/pn/{number}`

Convert a phone number to its corresponding WhatsApp LID.

#### 💡 Tips
- **Resolution**: Resolves a Phone Number to its corresponding LID.
- **Availability**: Not all accounts have LIDs yet; depends on rollout phase.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| instance_id | string | Yes | Your unique WhatsApp Instance ID |
| access_token | string | Yes | Your API Access Token |
| number | string | Yes | The phone number without @c.us (e.g. 447441429009) |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: LID found</summary>

```json
{
  "lid": "1234567890@lid",
  "number": "447441429009"
}
```

</details>

<details>
<summary><b>HTTP 200</b>: Success - Request completed successfully</summary>

```json
{
  "success": true,
  "message": "Operation completed successfully"
}
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (Plain Text)</summary>

```json
"Success: Operation completed successfully."
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Missing Required Parameter(s)</summary>

```json
{
  "code": "missing_param",
  "message": "Missing required parameter: {parameterName}",
  "details": {
    "missing": [
      "{parameterName}"
    ],
    "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (Plain Text)</summary>

```json
"Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized - Invalid or Missing Access Token</summary>

```json
{
  "code": "invalid_access_token",
  "message": "Invalid or expired access token. Please check your credentials.",
  "details": {
    "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
  }
}
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found - Session Does Not Exist</summary>

```json
{
  "code": "invalid_session",
  "message": "Session not found. Please verify your instance_id or session_name.",
  "details": {
    "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
  }
}
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error - Unexpected Failure</summary>

```json
{
  "code": "server_error",
  "message": "An internal server error occurred. Please try again later.",
  "details": {
    "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error (HTML)</summary>

```json
"<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway - Connection Failed to Upstream</summary>

```json
{
  "code": "proxy_error",
  "message": "Failed to connect to WhatsApp server.",
  "details": {
    "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
  }
}
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
```

</details>

### Get Phone by LID
**Endpoint:** `GET /v2/lids/{lid}`

Convert a WhatsApp LID to its corresponding phone number.

#### 💡 Tips
- **Architecture**: LID (Ledger ID) is a privacy-preserving identifier.
- **Usage**: Required for some advanced features like username lookup.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| instance_id | string | Yes | Your unique WhatsApp Instance ID |
| access_token | string | Yes | Your API Access Token |
| lid | string | Yes | The unique LID (@lid) |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Phone number found</summary>

```json
{
  "lid": "1234567890@lid",
  "number": "447441429009"
}
```

</details>

<details>
<summary><b>HTTP 200</b>: Success - Request completed successfully</summary>

```json
{
  "success": true,
  "message": "Operation completed successfully"
}
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (Plain Text)</summary>

```json
"Success: Operation completed successfully."
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Missing Required Parameter(s)</summary>

```json
{
  "code": "missing_param",
  "message": "Missing required parameter: {parameterName}",
  "details": {
    "missing": [
      "{parameterName}"
    ],
    "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (Plain Text)</summary>

```json
"Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized - Invalid or Missing Access Token</summary>

```json
{
  "code": "invalid_access_token",
  "message": "Invalid or expired access token. Please check your credentials.",
  "details": {
    "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
  }
}
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found - Session Does Not Exist</summary>

```json
{
  "code": "invalid_session",
  "message": "Session not found. Please verify your instance_id or session_name.",
  "details": {
    "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
  }
}
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error - Unexpected Failure</summary>

```json
{
  "code": "server_error",
  "message": "An internal server error occurred. Please try again later.",
  "details": {
    "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error (HTML)</summary>

```json
"<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway - Connection Failed to Upstream</summary>

```json
{
  "code": "proxy_error",
  "message": "Failed to connect to WhatsApp server.",
  "details": {
    "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
  }
}
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
```

</details>

### Get LIDs Count
**Endpoint:** `GET /v2/lids/count`

Returns the number of known LIDs.

#### 💡 Tips
- **Stats**: Returns the number of LID-based contacts known to the device.
- **Health**: Zero count might indicate LIDs are not enabled for this session.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| instance_id | string | Yes | Your unique WhatsApp Instance ID |
| access_token | string | Yes | Your API Access Token |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Success</summary>

```json
{
  "count": 42
}
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized - Invalid or Missing Access Token</summary>

```json
{
  "code": "invalid_access_token",
  "message": "Invalid or expired access token. Please check your credentials.",
  "details": {
    "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error - Unexpected Failure</summary>

```json
{
  "code": "server_error",
  "message": "An internal server error occurred. Please try again later.",
  "details": {
    "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
  }
}
```

</details>

---

## Labels

### Labels API Guide
Comprehensive guide to mastering WhatsApp Labels for organizational excellence and automation.

#### 💡 Tips
- **Events**: Listen for 'label.create' and 'label.delete' webhooks.
- **Real-time**: Ensures your UI is always in sync with the mobile app.

### Get All Labels
**Endpoint:** `GET /v2/labels`

Retrieve all WhatsApp labels available in your WhatsApp Business account.

#### 💡 Tips
- **Catalog**: Returns a list of all defined labels on the account.
- **Sync**: Use this on startup to build your local label map.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| instance_id | string | Yes | Your unique WhatsApp Instance ID |
| access_token | string | Yes | Your API Access Token |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: List of labels retrieved successfully</summary>

```json
[
  {
    "id": "1",
    "name": "New Customer",
    "color": 0,
    "colorHex": "#ff9485"
  },
  {
    "id": "2",
    "name": "Favorites",
    "color": 1,
    "colorHex": "#64c4ff"
  }
]
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized - Invalid or Missing Access Token</summary>

```json
{
  "code": "invalid_access_token",
  "message": "Invalid or expired access token. Please check your credentials.",
  "details": {
    "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error - Unexpected Failure</summary>

```json
{
  "code": "server_error",
  "message": "An internal server error occurred. Please try again later.",
  "details": {
    "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
  }
}
```

</details>

### Get Label
**Endpoint:** `GET /v2/labels/{id}`

Retrieve details of a specific WhatsApp label.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| instance_id | string | Yes | Your unique WhatsApp Instance ID |
| access_token | string | Yes | Your API Access Token |
| id | string | Yes | The unique ID of the label |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Label info retrieved</summary>

```json
{
  "id": "1",
  "name": "New Customer",
  "color": 0,
  "colorHex": "#ff9485"
}
```

</details>

<details>
<summary><b>HTTP 200</b>: Success - Request completed successfully</summary>

```json
{
  "success": true,
  "message": "Operation completed successfully"
}
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (Plain Text)</summary>

```json
"Success: Operation completed successfully."
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Missing Required Parameter(s)</summary>

```json
{
  "code": "missing_param",
  "message": "Missing required parameter: {parameterName}",
  "details": {
    "missing": [
      "{parameterName}"
    ],
    "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (Plain Text)</summary>

```json
"Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized - Invalid or Missing Access Token</summary>

```json
{
  "code": "invalid_access_token",
  "message": "Invalid or expired access token. Please check your credentials.",
  "details": {
    "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
  }
}
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found - Session Does Not Exist</summary>

```json
{
  "code": "invalid_session",
  "message": "Session not found. Please verify your instance_id or session_name.",
  "details": {
    "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
  }
}
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error - Unexpected Failure</summary>

```json
{
  "code": "server_error",
  "message": "An internal server error occurred. Please try again later.",
  "details": {
    "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error (HTML)</summary>

```json
"<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway - Connection Failed to Upstream</summary>

```json
{
  "code": "proxy_error",
  "message": "Failed to connect to WhatsApp server.",
  "details": {
    "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
  }
}
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
```

</details>

### Create Label
**Endpoint:** `POST /v2/labels/create`

Create a new WhatsApp label with a name and optional color.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| instance_id | string | Yes | Your unique WhatsApp Instance ID |
| access_token | string | Yes | Your API Access Token |
| name | string | Yes | The name of the new label |
| color | number | No | Internal color number (0-19). E.g., 0=#ff9485, 1=#64c4ff, ... 19=#9368cf |

#### 📦 Responses

<details>
<summary><b>HTTP 201</b>: Label created successfully</summary>

```json
{
  "id": "3",
  "name": "Urgent",
  "color": 0,
  "colorHex": "#ff9485"
}
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized - Invalid or Missing Access Token</summary>

```json
{
  "code": "invalid_access_token",
  "message": "Invalid or expired access token. Please check your credentials.",
  "details": {
    "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Invalid Parameter Format</summary>

```json
{
  "code": "invalid_param",
  "message": "Invalid format for one or more parameters.",
  "details": {
    "param": "text",
    "value": "too_long",
    "recommendation": "Refer to the documentation for the allowed format and length of this parameter."
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error - Unexpected Failure</summary>

```json
{
  "code": "server_error",
  "message": "An internal server error occurred. Please try again later.",
  "details": {
    "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
  }
}
```

</details>

### Update Label
**Endpoint:** `PUT /v2/labels/{labelId}/update`

Update an existing WhatsApp label's name or color.

#### 💡 Tips
- **Modification**: Allows renaming or changing the color of an existing label.
- **Consistency**: Updates are pushed to all devices immediately.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| labelId | string | Yes | The unique ID of the label to update |
| instance_id | string | Yes | Your unique WhatsApp Instance ID |
| access_token | string | Yes | Your API Access Token |
| name | string | No | New name for the label |
| color | number | No | New internal color number (0-19). E.g., 0=#ff9485, 1=#64c4ff, ... 19=#9368cf |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Label updated successfully</summary>

```json
{
  "id": "3",
  "name": "Very Urgent",
  "color": 0,
  "colorHex": "#ff0000"
}
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized - Invalid or Missing Access Token</summary>

```json
{
  "code": "invalid_access_token",
  "message": "Invalid or expired access token. Please check your credentials.",
  "details": {
    "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Invalid Parameter Format</summary>

```json
{
  "code": "invalid_param",
  "message": "Invalid format for one or more parameters.",
  "details": {
    "param": "text",
    "value": "too_long",
    "recommendation": "Refer to the documentation for the allowed format and length of this parameter."
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error - Unexpected Failure</summary>

```json
{
  "code": "server_error",
  "message": "An internal server error occurred. Please try again later.",
  "details": {
    "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
  }
}
```

</details>

### Delete Label
**Endpoint:** `DELETE /v2/labels/{labelId}/delete`

Permanently delete a WhatsApp label.

#### 💡 Tips
- **Cascade**: Deleting a label removes it from ALL associated chats.
- **Irreversibility**: This action cannot be undone.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| labelId | string | Yes | The unique ID of the label to delete |
| instance_id | string | Yes | Your unique WhatsApp Instance ID |
| access_token | string | Yes | Your API Access Token |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Label deleted successfully</summary>

```json
{
  "ok": true
}
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized - Invalid or Missing Access Token</summary>

```json
{
  "code": "invalid_access_token",
  "message": "Invalid or expired access token. Please check your credentials.",
  "details": {
    "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error - Unexpected Failure</summary>

```json
{
  "code": "server_error",
  "message": "An internal server error occurred. Please try again later.",
  "details": {
    "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
  }
}
```

</details>

### Get Chats with Label
**Endpoint:** `GET /v2/labels/{labelId}/chats`

Get a list of chats associated with a specific label.

#### 💡 Tips
- **Aggregation**: Often used to get a count of chats per label.
- **Dashboard**: Great for visualizing workload (e.g., 'Pending Support Tickets').

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| labelId | string | Yes | The unique ID of the label |
| instance_id | string | Yes | Your unique WhatsApp Instance ID |
| access_token | string | Yes | Your API Access Token |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: List of chats retrieved successfully</summary>

```json
[
  {
    "id": "123456789@c.us",
    "name": "John Doe"
  }
]
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized - Invalid or Missing Access Token</summary>

```json
{
  "code": "invalid_access_token",
  "message": "Invalid or expired access token. Please check your credentials.",
  "details": {
    "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error - Unexpected Failure</summary>

```json
{
  "code": "server_error",
  "message": "An internal server error occurred. Please try again later.",
  "details": {
    "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
  }
}
```

</details>

### Link Label to Chat
**Endpoint:** `PUT /v2/labels/{id}/chats/{chatId}`

Assign a specific label to a chat or contact.

#### 💡 Tips
- **Capacity**: A chat can have multiple labels (up to 20).
- **Automation**: Labels are excellent triggers for automated workflows.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| instance_id | string | Yes | Your unique WhatsApp Instance ID |
| access_token | string | Yes | Your API Access Token |
| id | string | Yes | The unique ID of the label |
| chatId | string | Yes | Target phone number or group ID (@c.us, @g.us) |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Success - Request completed successfully</summary>

```json
{
  "success": true,
  "message": "Operation completed successfully"
}
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (Plain Text)</summary>

```json
"Success: Operation completed successfully."
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Missing Required Parameter(s)</summary>

```json
{
  "code": "missing_param",
  "message": "Missing required parameter: {parameterName}",
  "details": {
    "missing": [
      "{parameterName}"
    ],
    "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (Plain Text)</summary>

```json
"Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized - Invalid or Missing Access Token</summary>

```json
{
  "code": "invalid_access_token",
  "message": "Invalid or expired access token. Please check your credentials.",
  "details": {
    "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
  }
}
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found - Session Does Not Exist</summary>

```json
{
  "code": "invalid_session",
  "message": "Session not found. Please verify your instance_id or session_name.",
  "details": {
    "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
  }
}
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error - Unexpected Failure</summary>

```json
{
  "code": "server_error",
  "message": "An internal server error occurred. Please try again later.",
  "details": {
    "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error (HTML)</summary>

```json
"<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway - Connection Failed to Upstream</summary>

```json
{
  "code": "proxy_error",
  "message": "Failed to connect to WhatsApp server.",
  "details": {
    "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
  }
}
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
```

</details>

### Unlink Label from Chat
**Endpoint:** `DELETE /v2/labels/{id}/chats/{chatId}`

Remove a specific label from a chat or contact.

#### 💡 Tips
- **Cleanup**: Removes a specific label relationship, not the label itself.
- **Sync**: Changes are reflected instantly across all devices.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| instance_id | string | Yes | Your unique WhatsApp Instance ID |
| access_token | string | Yes | Your API Access Token |
| id | string | Yes | The unique ID of the label |
| chatId | string | Yes | Target phone number or group ID (@c.us, @g.us) |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Success - Request completed successfully</summary>

```json
{
  "success": true,
  "message": "Operation completed successfully"
}
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (Plain Text)</summary>

```json
"Success: Operation completed successfully."
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Missing Required Parameter(s)</summary>

```json
{
  "code": "missing_param",
  "message": "Missing required parameter: {parameterName}",
  "details": {
    "missing": [
      "{parameterName}"
    ],
    "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (Plain Text)</summary>

```json
"Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized - Invalid or Missing Access Token</summary>

```json
{
  "code": "invalid_access_token",
  "message": "Invalid or expired access token. Please check your credentials.",
  "details": {
    "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
  }
}
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found - Session Does Not Exist</summary>

```json
{
  "code": "invalid_session",
  "message": "Session not found. Please verify your instance_id or session_name.",
  "details": {
    "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
  }
}
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error - Unexpected Failure</summary>

```json
{
  "code": "server_error",
  "message": "An internal server error occurred. Please try again later.",
  "details": {
    "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error (HTML)</summary>

```json
"<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway - Connection Failed to Upstream</summary>

```json
{
  "code": "proxy_error",
  "message": "Failed to connect to WhatsApp server.",
  "details": {
    "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
  }
}
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
```

</details>

### Get Chat Labels
**Endpoint:** `GET /v2/labels/chats/{chatId}`

Get all labels assigned to a specific chat.

#### 💡 Tips
- **Association**: Returns all chats associated with a specific label ID.
- **Pagination**: Supports cursor-based pagination for large lists.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| chatId | string | Yes | The unique ID of the chat (e.g., 123456789@c.us) |
| instance_id | string | Yes | Your unique WhatsApp Instance ID |
| access_token | string | Yes | Your API Access Token |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: List of labels for the chat</summary>

```json
[
  {
    "id": "1",
    "name": "New Customer",
    "color": 0,
    "colorHex": "#ff9485"
  }
]
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized - Invalid or Missing Access Token</summary>

```json
{
  "code": "invalid_access_token",
  "message": "Invalid or expired access token. Please check your credentials.",
  "details": {
    "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Invalid Parameter Format</summary>

```json
{
  "code": "invalid_param",
  "message": "Invalid format for one or more parameters.",
  "details": {
    "param": "text",
    "value": "too_long",
    "recommendation": "Refer to the documentation for the allowed format and length of this parameter."
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error - Unexpected Failure</summary>

```json
{
  "code": "server_error",
  "message": "An internal server error occurred. Please try again later.",
  "details": {
    "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
  }
}
```

</details>

### Set Chat Labels
**Endpoint:** `PUT /v2/labels/chats/{chatId}`

Overwrite all labels for a specific chat.

#### 💡 Tips
- **Overwrite**: This REPLACES all existing labels on the chat with the new set.
- **Bulk Action**: Efficient for resetting a chat's categorization state.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| chatId | string | Yes | The unique ID of the chat (e.g., 123456789@c.us) |
| instance_id | string | Yes | Your unique WhatsApp Instance ID |
| access_token | string | Yes | Your API Access Token |
| labels | string[] | Yes | Array of label IDs to assign (overwrites existing ones) |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Labels updated successfully</summary>

```json
{
  "ok": true
}
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized - Invalid or Missing Access Token</summary>

```json
{
  "code": "invalid_access_token",
  "message": "Invalid or expired access token. Please check your credentials.",
  "details": {
    "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Invalid Parameter Format</summary>

```json
{
  "code": "invalid_param",
  "message": "Invalid format for one or more parameters.",
  "details": {
    "param": "text",
    "value": "too_long",
    "recommendation": "Refer to the documentation for the allowed format and length of this parameter."
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error - Unexpected Failure</summary>

```json
{
  "code": "server_error",
  "message": "An internal server error occurred. Please try again later.",
  "details": {
    "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
  }
}
```

</details>

---

## Groups

### Groups Overview
Learn how to manage WhatsApp groups, participants, and settings using Wawp.

#### 💡 Tips
- **Admin Requirement**: Modification actions like 'Add Participant' or 'Set Admin Only' will fail if your instance is not a Group Admin.

### Get All List groups
**Endpoint:** `GET /v2/groups`

Retrieve a list of all groups the instance is a member of.

#### 💡 Tips
- **Performance**: Scanning thousands of groups can be slow. Use filters if available.
- **Sync**: Use this to bootstrap your local database on startup.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| instance_id | string | Yes | Your unique WhatsApp Instance ID |
| access_token | string | Yes | Your API Access Token |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: List of groups retrieved successfully</summary>

```json
[
  {
    "id": "1234567890@g.us",
    "name": "Project Team",
    "participants": []
  }
]
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized - Invalid or Missing Access Token</summary>

```json
{
  "code": "invalid_access_token",
  "message": "Invalid or expired access token. Please check your credentials.",
  "details": {
    "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error - Unexpected Failure</summary>

```json
{
  "code": "server_error",
  "message": "An internal server error occurred. Please try again later.",
  "details": {
    "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
  }
}
```

</details>

### Create group
**Endpoint:** `POST /v2/groups/create`

Create a new WhatsApp group with specified name and participants.

#### 💡 Tips
- **Admin Status**: Your bot automatically becomes a Super Admin of the created group.
- **Privacy Settings**: Users with strict privacy settings may not be added directly; use Invite Links as a fallback.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| instance_id | string | Yes | Your unique WhatsApp Instance ID |
| access_token | string | Yes | Your API Access Token |
| name | string | Yes | Name of the group |
| participants | array | Yes | List of participant JIDs to add to the group |

#### 📦 Responses

<details>
<summary><b>HTTP 201</b>: Group created successfully</summary>

```json
{
  "id": "1234567890@g.us",
  "name": "New Project"
}
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized - Invalid or Missing Access Token</summary>

```json
{
  "code": "invalid_access_token",
  "message": "Invalid or expired access token. Please check your credentials.",
  "details": {
    "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Invalid Parameter Format</summary>

```json
{
  "code": "invalid_param",
  "message": "Invalid format for one or more parameters.",
  "details": {
    "param": "text",
    "value": "too_long",
    "recommendation": "Refer to the documentation for the allowed format and length of this parameter."
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error - Unexpected Failure</summary>

```json
{
  "code": "server_error",
  "message": "An internal server error occurred. Please try again later.",
  "details": {
    "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
  }
}
```

</details>

### Join group / Get join info
**Endpoint:** `GET, POST /v2/groups/join`

Use GET to fetch information about a group before joining, or POST to join it. Accepts both direct invite codes and full WhatsApp group links.

#### 💡 Tips
- **Rate Limits**: Joining too many groups rapidly can flag your account.
- **Approval**: Some groups require admin approval, which this endpoint does not bypass.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| instance_id | string | Yes | Your unique WhatsApp Instance ID |
| access_token | string | Yes | Your API Access Token |
| code | string | Yes | Group invite code or full WhatsApp invite URL |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Successful operation</summary>

```json
{
  "id": "1234567890@g.us",
  "subject": "Community Group",
  "description": "Group for testing"
}
```

</details>

### Get the number of groups
**Endpoint:** `GET /v2/groups/count`

Get the total number of groups the instance is a member of.

#### 💡 Tips
- **Caching**: Cache this count locally to avoid frequent API calls.
- **Monitoring**: Track group count trends to identify suspicious bulk-joining activity.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| instance_id | string | Yes | Your unique WhatsApp Instance ID |
| access_token | string | Yes | Your API Access Token |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Count retrieved</summary>

```json
{
  "count": 15
}
```

</details>

### Get the group
**Endpoint:** `GET /v2/groups/{id}`

Retrieve detailed information about a specific group.

#### 💡 Tips
- **Metadata**: This returns basic info (Subject, Owner, Creation Time).
- **No Participants**: This endpoint does NOT return the full participant list. Use '/groups/{id}/participants' for that.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| id | string | Yes | The unique ID of the group (@g.us) |
| instance_id | string | Yes | Your unique WhatsApp Instance ID |
| access_token | string | Yes | Your API Access Token |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Group info retrieved</summary>

```json
{
  "id": "1234567890@g.us",
  "name": "Project Alpha",
  "description": "Main coordination group"
}
```

</details>

### Leave the group
**Endpoint:** `POST /v2/groups/{id}/leave`

Leave a specific group.

#### 💡 Tips
- **Clean Exit**: You will be removed from the participant list, but the group persists.
- **History**: You lose access to future messages but often keep local history.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| id | string | Yes | The unique ID of the group |
| instance_id | string | Yes | Your unique WhatsApp Instance ID |
| access_token | string | Yes | Your API Access Token |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Left group successfully</summary>

```json
{
  "ok": true
}
```

</details>

### Get group picture
**Endpoint:** `GET /v2/groups/{id}/picture`

Retrieve the current profile picture of the group.

#### 💡 Tips
- **Caching**: Profile pictures are cached aggressively by WhatsApp.
- **URL**: Returns a temporary direct URL to the image file.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| id | string | Yes | The unique ID of the group |
| instance_id | string | Yes | Your unique WhatsApp Instance ID |
| access_token | string | Yes | Your API Access Token |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Picture URL retrieved</summary>

```json
{
  "url": "https://pps.whatsapp.net/..."
}
```

</details>

### Set group picture
**Endpoint:** `PUT /v2/groups/{id}/picture`

Update the group profile picture.

#### 💡 Tips
- **Format**: Use SQUARE JPEG or PNG images for best results.
- **Size**: High-res images may be compressed. Aim for 640x640px.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| id | string | Yes | The unique ID of the group |
| instance_id | string | Yes | Your unique WhatsApp Instance ID |
| access_token | string | Yes | Your API Access Token |
| file | object | Yes | Picture file details (url, mimetype, filename) |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Picture updated successfully</summary>

```json
{
  "ok": true
}
```

</details>

### Delete group picture
**Endpoint:** `DELETE /v2/groups/{id}/picture`

Remove the group profile picture.

#### 💡 Tips
- **Default**: Deleting the picture reverts it to the default WhatsApp placeholder.
- **Visibility**: All participants will see that the group icon was removed.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| id | string | Yes | The unique ID of the group |
| instance_id | string | Yes | Your unique WhatsApp Instance ID |
| access_token | string | Yes | Your API Access Token |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Picture removed successfully</summary>

```json
{
  "ok": true
}
```

</details>

### Updates the group description
**Endpoint:** `PUT /v2/groups/{id}/description`

Update the description text for the group.

#### 💡 Tips
- **Visibility**: The description is visible to all participants at the top of the chat.
- **SEO**: Include keywords and links to your support portal here.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| id | string | Yes | The unique ID of the group |
| instance_id | string | Yes | Your unique WhatsApp Instance ID |
| access_token | string | Yes | Your API Access Token |
| description | string | Yes | New group description |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Description updated</summary>

```json
{
  "ok": true
}
```

</details>

### Updates the group subject
**Endpoint:** `PUT /v2/groups/{id}/subject`

Update the group subject (name).

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| id | string | Yes | The unique ID of the group |
| instance_id | string | Yes | Your unique WhatsApp Instance ID |
| access_token | string | Yes | Your API Access Token |
| subject | string | Yes | New group subject |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Subject updated</summary>

```json
{
  "ok": true
}
```

</details>

### Get "info admin only" settings
**Endpoint:** `GET /v2/groups/{id}/settings/security/info-admin-only`

Check if only admins can update group info.

#### 💡 Tips
- **Permissions**: Checks if 'Edit Group Info' is restricted to admins.
- **Boolean**: Returns true if restricted (Admins Only), false if open (All Users).

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| id | string | Yes | The unique ID of the group |
| instance_id | string | Yes | Your unique WhatsApp Instance ID |
| access_token | string | Yes | Your API Access Token |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Setting retrieved</summary>

```json
{
  "adminOnly": true
}
```

</details>

### Updates "info admin only" settings
**Endpoint:** `PUT /v2/groups/{id}/settings/security/info-admin-only`

Set whether only admins can update group info.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| id | string | Yes | The unique ID of the group |
| instance_id | string | Yes | Your unique WhatsApp Instance ID |
| access_token | string | Yes | Your API Access Token |
| value | boolean | Yes | True to restrict to admins, false to allow all |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Setting updated</summary>

```json
{
  "ok": true
}
```

</details>

### Get settings - who can send messages
**Endpoint:** `GET /v2/groups/{id}/settings/security/messages-admin-only`

Check if only admins can send messages to the group.

#### 💡 Tips
- **Announce Mode**: Checks if 'Send Messages' is restricted to admins.
- **Term**: Often called 'Announcement Group' or 'Broadcast Mode'.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| id | string | Yes | The unique ID of the group |
| instance_id | string | Yes | Your unique WhatsApp Instance ID |
| access_token | string | Yes | Your API Access Token |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Setting retrieved</summary>

```json
{
  "adminOnly": false
}
```

</details>

### Set messages admin only
**Endpoint:** `PUT /v2/groups/{id}/settings/security/messages-admin-only`

Set whether only admins can send messages to the group.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| id | string | Yes | The unique ID of the group |
| instance_id | string | Yes | Your unique WhatsApp Instance ID |
| access_token | string | Yes | Your API Access Token |
| value | boolean | Yes | True to restrict to admins, false to allow all |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Setting updated</summary>

```json
{
  "ok": true
}
```

</details>

### Get the invite code for the group
**Endpoint:** `GET /v2/groups/{id}/invite-code`

Get the current invite code for the group.

#### 💡 Tips
- **Security**: Anyone with this code can join. Treat it like a password.
- **Format**: Returns a full URL (https://chat.whatsapp.com/...) and the raw code.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| id | string | Yes | The unique ID of the group |
| instance_id | string | Yes | Your unique WhatsApp Instance ID |
| access_token | string | Yes | Your API Access Token |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Invite code retrieved</summary>

```json
{
  "code": "ABC123XYZ"
}
```

</details>

### Invalidates the current group invite code and generates a new one
**Endpoint:** `POST /v2/groups/{id}/invite-code/revoke`

Revoke the current invite code and generate a new one.

#### 💡 Tips
- **Instant Effect**: The old invite link will stop working immediately.
- **Auto-Gen**: A new code is automatically generated upon revocation.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| id | string | Yes | The unique ID of the group |
| instance_id | string | Yes | Your unique WhatsApp Instance ID |
| access_token | string | Yes | Your API Access Token |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Invite code revoked and recreated</summary>

```json
{
  "code": "NEW456DEF"
}
```

</details>

### Get participants
**Endpoint:** `GET /v2/groups/{id}/participants`

Retrieve a list of all participants in the group.

#### 💡 Tips
- **Scaling**: Large groups return large arrays. Handle pagination or timeouts.
- **Roles**: The response includes the role (admin, superadmin, participant) of each user.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| id | string | Yes | The unique ID of the group |
| instance_id | string | Yes | Your unique WhatsApp Instance ID |
| access_token | string | Yes | Your API Access Token |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Participants retrieved</summary>

```json
[
  {
    "id": "1234567890@c.us",
    "isAdmin": true,
    "isSuperAdmin": false
  }
]
```

</details>

### Add participants
**Endpoint:** `POST /v2/groups/{id}/participants/add`

Add one or more participants to the group.

#### 💡 Tips
- **Privacy**: Users can block being added to groups by strangers.
- **Failures**: If an add fails, you may need to send an invite link instead.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| id | string | Yes | The unique ID of the group |
| instance_id | string | Yes | Your unique WhatsApp Instance ID |
| access_token | string | Yes | Your API Access Token |
| participants | array | Yes | List of JIDs to add |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Participants added</summary>

```json
{
  "ok": true
}
```

</details>

### Remove participants
**Endpoint:** `POST /v2/groups/{id}/participants/remove`

Remove one or more participants from the group.

#### 💡 Tips
- **Admin Only**: Only group admins can remove participants.
- **Notification**: The removed user will see a system message that you removed them.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| id | string | Yes | The unique ID of the group |
| instance_id | string | Yes | Your unique WhatsApp Instance ID |
| access_token | string | Yes | Your API Access Token |
| participants | array | Yes | List of JIDs to remove |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Participants removed</summary>

```json
{
  "ok": true
}
```

</details>

### Promote participants to admin users
**Endpoint:** `POST /v2/groups/{id}/admin/promote`

Promote one or more participants to group admins.

#### 💡 Tips
- **Admin Powers**: Admins can edit group info, add/remove users, and promote others.
- **Trust**: Only promote trusted bots or humans. They can remove you (unless you are Creator).

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| id | string | Yes | The unique ID of the group |
| instance_id | string | Yes | Your unique WhatsApp Instance ID |
| access_token | string | Yes | Your API Access Token |
| participants | array | Yes | List of JIDs to promote |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Participants promoted</summary>

```json
{
  "ok": true
}
```

</details>

### Demotes participants to regular users
**Endpoint:** `POST /v2/groups/{id}/admin/demote`

Demote one or more admins to regular participants.

#### 💡 Tips
- **Creator Immunity**: You cannot demote the group creator.
- **Effect**: Demoted users become regular participants but remain in the group.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| id | string | Yes | The unique ID of the group |
| instance_id | string | Yes | Your unique WhatsApp Instance ID |
| access_token | string | Yes | Your API Access Token |
| participants | array | Yes | List of JIDs to demote |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Participants demoted</summary>

```json
{
  "ok": true
}
```

</details>

---

## Media

### Media Overview
Learn how to handle media files (images, videos, audio, documents) in WhatsApp.

#### 💡 Tips
- **File Limits**: Check file size limits for different media types before uploading.
- **Mime Types**: Ensure the correct MIME type is specified for the media file.

### Convert Media
**Endpoint:** `POST /v2/media/convert`

Convert media files to WhatsApp-compatible formats (e.g., to OGG/Opus for voice notes).

#### 💡 Tips
- **File Limits**: Check file size limits for different media types before uploading.
- **Mime Types**: Ensure the correct MIME type is specified for the media file.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| instance_id | string | Yes | Your unique WhatsApp Instance ID |
| access_token | string | Yes | Your API Access Token |
| file | object | Yes | File to convert (URL, filename, mimetype) |
| outputFormat | string | Yes | Desired output format (ogg, mp4, etc.) |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Media converted successfully</summary>

```json
{
  "url": "https://wawp.net/media/converted.ogg",
  "filename": "converted.ogg",
  "mimetype": "audio/ogg; codecs=opus"
}
```

</details>

<details>
<summary><b>HTTP 200</b>: Success - Request completed successfully</summary>

```json
{
  "success": true,
  "message": "Operation completed successfully"
}
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (Plain Text)</summary>

```json
"Success: Operation completed successfully."
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Missing Required Parameter(s)</summary>

```json
{
  "code": "missing_param",
  "message": "Missing required parameter: {parameterName}",
  "details": {
    "missing": [
      "{parameterName}"
    ],
    "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (Plain Text)</summary>

```json
"Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized - Invalid or Missing Access Token</summary>

```json
{
  "code": "invalid_access_token",
  "message": "Invalid or expired access token. Please check your credentials.",
  "details": {
    "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
  }
}
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found - Session Does Not Exist</summary>

```json
{
  "code": "invalid_session",
  "message": "Session not found. Please verify your instance_id or session_name.",
  "details": {
    "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
  }
}
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error - Unexpected Failure</summary>

```json
{
  "code": "server_error",
  "message": "An internal server error occurred. Please try again later.",
  "details": {
    "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error (HTML)</summary>

```json
"<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway - Connection Failed to Upstream</summary>

```json
{
  "code": "proxy_error",
  "message": "Failed to connect to WhatsApp server.",
  "details": {
    "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
  }
}
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
```

</details>

---

## Calls

### Calls Overview
Learn how to manage WhatsApp voice and video calls using Wawp.

#### 💡 Tips
- **Webhook Events**: Listen to call.* webhooks to handle incoming calls in real-time.
- **Outbound Calls**: WhatsApp API does not support programmatic outbound calls. Use links instead.

### Reject Call
**Endpoint:** `POST /v2/calls/reject`

Reject an incoming call for a specific session.

#### 💡 Tips
- **Webhook Events**: Listen to call.* webhooks to handle incoming calls in real-time.
- **Outbound Calls**: WhatsApp API does not support programmatic outbound calls. Use links instead.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| instance_id | string | Yes | Your unique WhatsApp Instance ID |
| access_token | string | Yes | Your API Access Token |
| callId | string | Yes | The unique ID of the incoming call (from call.received webhook) |
| from | string | Yes | The WhatsApp ID (JID) of the caller (from call.received webhook) |

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Success - Request completed successfully</summary>

```json
{
  "success": true,
  "message": "Operation completed successfully"
}
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<response>\n    <success>true</success>\n    <message>Operation completed successfully</message>\n</response>"
```

</details>

<details>
<summary><b>HTTP 200</b>: Success (Plain Text)</summary>

```json
"Success: Operation completed successfully."
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request - Missing Required Parameter(s)</summary>

```json
{
  "code": "missing_param",
  "message": "Missing required parameter: {parameterName}",
  "details": {
    "missing": [
      "{parameterName}"
    ],
    "recommendation": "Check if the parameter is spelled correctly and present in the request body/query."
  }
}
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>missing_param</code>\n    <message>Missing required parameter: {parameterName}</message>\n    <details>\n        <missing>{parameterName}</missing>\n        <recommendation>Check if the parameter is spelled correctly and present in the request body/query.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 400</b>: Bad Request (Plain Text)</summary>

```json
"Error: missing_param. Missing required parameter: {parameterName}. Please check your request parameters and try again."
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized - Invalid or Missing Access Token</summary>

```json
{
  "code": "invalid_access_token",
  "message": "Invalid or expired access token. Please check your credentials.",
  "details": {
    "recommendation": "Ensure you are sending a valid 'access_token' in the request. You can find your token in the dashboard."
  }
}
```

</details>

<details>
<summary><b>HTTP 401</b>: Unauthorized (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_access_token</code>\n    <message>Invalid or expired access token.</message>\n    <details>\n        <recommendation>Ensure you are sending a valid 'access_token' in the request.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found - Session Does Not Exist</summary>

```json
{
  "code": "invalid_session",
  "message": "Session not found. Please verify your instance_id or session_name.",
  "details": {
    "recommendation": "Check if the instance exists and is currently active. You might need to start it first."
  }
}
```

</details>

<details>
<summary><b>HTTP 404</b>: Not Found (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>invalid_session</code>\n    <message>Session not found.</message>\n    <details>\n        <recommendation>Check if the instance exists and is active.</recommendation>\n    </details>\n</error>"
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error - Unexpected Failure</summary>

```json
{
  "code": "server_error",
  "message": "An internal server error occurred. Please try again later.",
  "details": {
    "recommendation": "This is likely a temporary issue on our side. Please retry your request in a few seconds or contact support if it persists."
  }
}
```

</details>

<details>
<summary><b>HTTP 500</b>: Internal Server Error (HTML)</summary>

```json
"<!DOCTYPE html>\n<html>\n<head><title>500 Internal Server Error</title></head>\n<body>\n    <h1>Internal Server Error</h1>\n    <p>The server encountered an internal error. Please try again later.</p>\n    <p><em>Recommendation: Check the API dashboard for service status updates.</em></p>\n</body>\n</html>"
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway - Connection Failed to Upstream</summary>

```json
{
  "code": "proxy_error",
  "message": "Failed to connect to WhatsApp server.",
  "details": {
    "recommendation": "Ensure the instance is online and connected to WhatsApp. If the issue persists, the upstream server might be experiencing downtime."
  }
}
```

</details>

<details>
<summary><b>HTTP 502</b>: Bad Gateway (XML Format)</summary>

```json
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n    <code>proxy_error</code>\n    <message>Failed to connect to WhatsApp server.</message>\n    <details>\n        <recommendation>Check if the instance is online and connected.</recommendation>\n    </details>\n</error>"
```

</details>

---

## Webhooks

### Webhooks Overview
Stream WhatsApp events to your server in real-time.

#### 💡 Tips
- **Async Processing**: Always respond with a 200 OK to the webhook as quickly as possible. Process the data after acknowledging receipt.

### Session Status Change
**Endpoint:** `POST /session.status`

This event is triggered when the session status changes (e.g., from WORKING to STOPPED).

#### 💡 Tips
- **Uptime Monitoring**: Use this event to detect if your WhatsApp instance goes offline so you can alert your support team or trigger an automated restart.
- **Status Mapping**: The 'status' field returns values like WORKING, STOPPED, and SCAN_QR_CODE.

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Webhook Payload Example</summary>

```json
{
  "id": "evt_01aaaaaaaaaaaaaaaaaaaaaaaa",
  "timestamp": 1634567890123,
  "session": "default",
  "metadata": {
    "user.id": "123",
    "user.email": "email@example.com"
  },
  "engine": "WEBJS",
  "event": "session.status",
  "payload": {
    "name": "default",
    "status": "STOPPED"
  },
  "me": {
    "id": "11111111111@c.us",
    "lid": "123123@lid",
    "pushName": "Wawp Instance"
  }
}
```

</details>

### Incoming Message
**Endpoint:** `POST /message`

This event is triggered when a new message is received by your WhatsApp instance.

#### 💡 Tips
- **fromMe Field**: The 'fromMe' boolean is crucial. It tells you if the message was sent by YOU (the instance) or by the CONTACT. This prevents infinite bot loops.
- **Real-time CRM**: Use this event to push WhatsApp messages directly into your support dashboard without the user needing to refresh.

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Webhook Payload Example</summary>

```json
{
  "id": "evt_01aaaaaaaaaaaaaaaaaaaaaaaa",
  "timestamp": 1634567890123,
  "session": "default",
  "metadata": {
    "user.id": "123",
    "user.email": "email@example.com"
  },
  "engine": "WEBJS",
  "event": "message",
  "payload": {
    "id": "false_11111111111@c.us_AAAAAAAAAAAAAAAAAAAA",
    "timestamp": 1666943582,
    "from": "11111111111@c.us",
    "fromMe": true,
    "source": "api",
    "to": "11111111111@c.us",
    "participant": null,
    "body": "Hello, world!",
    "hasMedia": true,
    "media": {
      "url": "https://api.wawp.net/api/files/example.oga",
      "mimetype": "audio/ogg",
      "filename": "example.oga",
      "s3": {
        "Bucket": "my-bucket",
        "Key": "default/example.oga"
      },
      "error": null
    },
    "ack": -1,
    "ackName": "PENDING",
    "author": "11111111111@c.us",
    "location": {
      "description": "London, UK",
      "latitude": "51.5074",
      "longitude": "0.1278"
    },
    "vCards": [
      "BEGIN:VCARD..."
    ],
    "_data": {},
    "replyTo": {
      "id": "AAAAAAAAAAAAAAAAAAAA",
      "participant": "11111111111@c.us",
      "body": "Hello!",
      "_data": {}
    }
  },
  "me": {
    "id": "11111111111@c.us",
    "lid": "123123@lid",
    "pushName": "Wawp Instance"
  }
}
```

</details>

### Message Reaction
**Endpoint:** `POST /message.reaction`

Triggered when a user reacts to a message with an emoji.

#### 💡 Tips
- **Emoji Removal**: An empty reaction string often indicates that a user has removed their previous reaction.

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Webhook Payload Example</summary>

```json
{
  "id": "evt_01...",
  "timestamp": 1634567890123,
  "session": "default",
  "metadata": {
    "user.id": "123",
    "user.email": "email@example.com"
  },
  "engine": "WEBJS",
  "event": "message.reaction",
  "payload": {
    "id": "false_11111111111@c.us_...",
    "reaction": "❤️",
    "senderId": "11111111111@c.us",
    "messageId": "false_11111111111@c.us_AAAAA"
  },
  "me": {
    "id": "11111111111@c.us",
    "lid": "123@lid",
    "pushName": "Instance"
  }
}
```

</details>

### Any Message
**Endpoint:** `POST /message.any`

Catch-all event for any message activity in the session.

#### 💡 Tips
- **High Volume**: This event triggers for every single message. Ensure your server can handle the high traffic frequency.

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Webhook Payload Example</summary>

```json
{
  "id": "evt_01...",
  "timestamp": 1634567890123,
  "session": "default",
  "metadata": {
    "user.id": "123",
    "user.email": "email@example.com"
  },
  "engine": "WEBJS",
  "event": "message.any",
  "payload": {
    "id": "true_11111111111@c.us_...",
    "body": "Catching everything!",
    "from": "11111111111@c.us",
    "to": "22222222222@c.us"
  },
  "me": {
    "id": "11111111111@c.us",
    "lid": "123@lid",
    "pushName": "Instance"
  }
}
```

</details>

### Message Acknowledgement
**Endpoint:** `POST /message.ack`

Track message delivery and read status (sent, delivered, read).

#### 💡 Tips
- **ACK Values**: 1 = Sent, 2 = Delivered (Double check), 3 = Read (Blue ticks).

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Webhook Payload Example</summary>

```json
{
  "id": "evt_01...",
  "timestamp": 1634567890123,
  "session": "default",
  "metadata": {
    "user.id": "123",
    "user.email": "email@example.com"
  },
  "engine": "WEBJS",
  "event": "message.ack",
  "payload": {
    "id": "true_11111111111@c.us_...",
    "ack": 3,
    "ackName": "READ",
    "chatId": "11111111111@c.us"
  },
  "me": {
    "id": "11111111111@c.us",
    "lid": "123@lid",
    "pushName": "Instance"
  }
}
```

</details>

### Message Revoked
**Endpoint:** `POST /message.revoked`

Triggered when a user deletes a message for everyone.

#### 💡 Tips
- **Data Erasure**: Respect the user's wish to delete the message by removing it from your own database/UI as well.

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Webhook Payload Example</summary>

```json
{
  "id": "evt_01...",
  "timestamp": 1634567890123,
  "session": "default",
  "metadata": {
    "user.id": "123",
    "user.email": "email@example.com"
  },
  "engine": "WEBJS",
  "event": "message.revoked",
  "payload": {
    "id": "false_11111111111@c.us_...",
    "revokedBy": "11111111111@c.us"
  },
  "me": {
    "id": "11111111111@c.us",
    "lid": "123@lid",
    "pushName": "Instance"
  }
}
```

</details>

### Message Edited
**Endpoint:** `POST /message.edited`

Triggered when a sent message is modified by the user.

#### 💡 Tips
- **Time Window**: Edits can only happen within a short professional window after sending (approx 15 mins).

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Webhook Payload Example</summary>

```json
{
  "id": "evt_01...",
  "timestamp": 1634567890123,
  "session": "default",
  "metadata": {
    "user.id": "123",
    "user.email": "email@example.com"
  },
  "engine": "WEBJS",
  "event": "message.edited",
  "payload": {
    "id": "false_11111111111@c.us_...",
    "newBody": "Updated message text!",
    "prevBody": "Old message text"
  },
  "me": {
    "id": "11111111111@c.us",
    "lid": "123@lid",
    "pushName": "Instance"
  }
}
```

</details>

### Group Join (V2)
**Endpoint:** `POST /group.v2.join`

Triggered when a new member joins or is added to a group.

#### 💡 Tips
- **Auto-Welcome**: Use this to automatically send a welcome message or rule set to new group members.

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Webhook Payload Example</summary>

```json
{
  "id": "evt_01...",
  "timestamp": 1634567890123,
  "session": "default",
  "metadata": {
    "user.id": "123",
    "user.email": "email@example.com"
  },
  "engine": "WEBJS",
  "event": "group.v2.join",
  "payload": {
    "chatId": "1234567890@g.us",
    "participants": [
      "11111111111@c.us"
    ]
  },
  "me": {
    "id": "11111111111@c.us",
    "lid": "123@lid",
    "pushName": "Instance"
  }
}
```

</details>

### Group Leave (V2)
**Endpoint:** `POST /group.v2.leave`

Triggered when a member leaves or is removed from a group.

#### 💡 Tips
- **Retention Logic**: Use this to track churn or automatically follow up with members who leave (if appropriate).

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Webhook Payload Example</summary>

```json
{
  "id": "evt_01...",
  "timestamp": 1634567890123,
  "session": "default",
  "metadata": {
    "user.id": "123",
    "user.email": "email@example.com"
  },
  "engine": "WEBJS",
  "event": "group.v2.leave",
  "payload": {
    "chatId": "1234567890@g.us",
    "participants": [
      "11111111111@c.us"
    ]
  },
  "me": {
    "id": "11111111111@c.us",
    "lid": "123@lid",
    "pushName": "Instance"
  }
}
```

</details>

### Group Updated (V2)
**Endpoint:** `POST /group.v2.update`

Triggered when group settings like title, description, or icon are changed.

#### 💡 Tips
- **Synchronization**: Keep your mirrored group metadata up to date using this event.

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Webhook Payload Example</summary>

```json
{
  "id": "evt_01...",
  "timestamp": 1634567890123,
  "session": "default",
  "metadata": {
    "user.id": "123",
    "user.email": "email@example.com"
  },
  "engine": "WEBJS",
  "event": "group.v2.update",
  "payload": {
    "chatId": "1234567890@g.us",
    "subject": "New Group Name",
    "description": "Updated description text"
  },
  "me": {
    "id": "11111111111@c.us",
    "lid": "123@lid",
    "pushName": "Instance"
  }
}
```

</details>

### Group Participants Change
**Endpoint:** `POST /group.v2.participants`

Triggered when participants are promoted to admin or demoted.

#### 💡 Tips
- **Admin Rights**: Be aware of admin status changes if your bot depends on admin permissions to execute certain commands.

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Webhook Payload Example</summary>

```json
{
  "id": "evt_01...",
  "timestamp": 1634567890123,
  "session": "default",
  "metadata": {
    "user.id": "123",
    "user.email": "email@example.com"
  },
  "engine": "WEBJS",
  "event": "group.v2.participants",
  "payload": {
    "chatId": "1234567890@g.us",
    "action": "promote",
    "participants": [
      "11111111111@c.us"
    ]
  },
  "me": {
    "id": "11111111111@c.us",
    "lid": "123@lid",
    "pushName": "Instance"
  }
}
```

</details>

### Presence Updated
**Endpoint:** `POST /presence.update`

Triggered when a contact starts typing, recording audio, or changes their online status.

#### 💡 Tips
- **Online Privacy**: Note that many users have 'Last Seen' and 'Online' status disabled in their privacy settings.

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Webhook Payload Example</summary>

```json
{
  "id": "evt_01...",
  "timestamp": 1634567890123,
  "session": "default",
  "metadata": {
    "user.id": "123",
    "user.email": "email@example.com"
  },
  "engine": "WEBJS",
  "event": "presence.update",
  "payload": {
    "chatId": "11111111111@c.us",
    "type": "composing",
    "from": "11111111111@c.us"
  },
  "me": {
    "id": "11111111111@c.us",
    "lid": "123@lid",
    "pushName": "Instance"
  }
}
```

</details>

### Poll Vote Failed
**Endpoint:** `POST /poll.vote.failed`

Triggered if a vote on a poll fails to process correctly.

#### 💡 Tips
- **Error Handling**: Use this to notify admins if a voting session is being interrupted by technical errors.

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Webhook Payload Example</summary>

```json
{
  "id": "evt_01...",
  "timestamp": 1634567890123,
  "session": "default",
  "metadata": {
    "user.id": "123",
    "user.email": "email@example.com"
  },
  "engine": "WEBJS",
  "event": "poll.vote.failed",
  "payload": {
    "pollId": "true_11111111111@c.us_...",
    "voter": "11111111111@c.us",
    "reason": "MSG_NOT_FOUND"
  },
  "me": {
    "id": "11111111111@c.us",
    "lid": "123@lid",
    "pushName": "Instance"
  }
}
```

</details>

### Chat Archived/Unarchived
**Endpoint:** `POST /chat.archive`

Triggered when a chat's archive status changes.

#### 💡 Tips
- **Folder Logic**: Use this to organize chats in your custom dashboard similar to the official WhatsApp app.

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Webhook Payload Example</summary>

```json
{
  "id": "evt_01...",
  "timestamp": 1634567890123,
  "session": "default",
  "metadata": {
    "user.id": "123",
    "user.email": "email@example.com"
  },
  "engine": "WEBJS",
  "event": "chat.archive",
  "payload": {
    "chatId": "11111111111@c.us",
    "archived": true
  },
  "me": {
    "id": "11111111111@c.us",
    "lid": "123@lid",
    "pushName": "Instance"
  }
}
```

</details>

### Call Received
**Endpoint:** `POST /call.received`

Triggered when an incoming Voice or Video call is detected.

#### 💡 Tips
- **Calling Limitation**: Wawp currently does not support ANSWERING calls via API. This is for NOTIFICATION purposes only.

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Webhook Payload Example</summary>

```json
{
  "id": "evt_01...",
  "timestamp": 1634567890123,
  "session": "default",
  "metadata": {
    "user.id": "123",
    "user.email": "email@example.com"
  },
  "engine": "WEBJS",
  "event": "call.received",
  "payload": {
    "id": "call_12345",
    "from": "11111111111@c.us",
    "isVideo": false
  },
  "me": {
    "id": "11111111111@c.us",
    "lid": "123@lid",
    "pushName": "Instance"
  }
}
```

</details>

### Call Accepted
**Endpoint:** `POST /call.accepted`

Triggered when a received call is picked up on another device.

#### 💡 Tips
- **Multi-device Sync**: Shows the status shift when you answer the call using your physical phone.

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Webhook Payload Example</summary>

```json
{
  "id": "evt_01...",
  "timestamp": 1634567890123,
  "session": "default",
  "metadata": {
    "user.id": "123",
    "user.email": "email@example.com"
  },
  "engine": "WEBJS",
  "event": "call.accepted",
  "payload": {
    "id": "call_12345"
  },
  "me": {
    "id": "11111111111@c.us",
    "lid": "123@lid",
    "pushName": "Instance"
  }
}
```

</details>

### Call Rejected
**Endpoint:** `POST /call.rejected`

Triggered when an incoming call is declined.

#### 💡 Tips
- **Sync Status**: Useful for accurate logging of missed or ignored calls.

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Webhook Payload Example</summary>

```json
{
  "id": "evt_01...",
  "timestamp": 1634567890123,
  "session": "default",
  "metadata": {
    "user.id": "123",
    "user.email": "email@example.com"
  },
  "engine": "WEBJS",
  "event": "call.rejected",
  "payload": {
    "id": "call_12345"
  },
  "me": {
    "id": "11111111111@c.us",
    "lid": "123@lid",
    "pushName": "Instance"
  }
}
```

</details>

### Label Created/Updated
**Endpoint:** `POST /label.upsert`

Triggered when a WhatsApp Business label is added or modified.

#### 💡 Tips
- **Business Feature**: Labels are exclusive to WhatsApp Business accounts. Personal accounts will not fire this event.

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Webhook Payload Example</summary>

```json
{
  "id": "evt_01...",
  "timestamp": 1634567890123,
  "session": "default",
  "metadata": {
    "user.id": "123",
    "user.email": "email@example.com"
  },
  "engine": "WEBJS",
  "event": "label.upsert",
  "payload": {
    "label": {
      "id": "1",
      "name": "New Customer",
      "color": "#DFE5E7"
    }
  },
  "me": {
    "id": "11111111111@c.us",
    "lid": "123@lid",
    "pushName": "Instance"
  }
}
```

</details>

### Label Deleted
**Endpoint:** `POST /label.deleted`

Triggered when a label is completely removed from the account.

#### 💡 Tips
- **Cascading Deletion**: When a label is deleted, it is automatically removed from all chats. You should cleanup your local associations as well.

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Webhook Payload Example</summary>

```json
{
  "id": "evt_01...",
  "timestamp": 1634567890123,
  "session": "default",
  "metadata": {
    "user.id": "123",
    "user.email": "email@example.com"
  },
  "engine": "WEBJS",
  "event": "label.deleted",
  "payload": {
    "labelId": "1"
  },
  "me": {
    "id": "11111111111@c.us",
    "lid": "123@lid",
    "pushName": "Instance"
  }
}
```

</details>

### Label Added to Chat
**Endpoint:** `POST /label.chat.added`

Triggered when a label is assigned to a specific conversation.

#### 💡 Tips
- **Lead Status**: Perfect for moving leads through your custom kanban or pipeline based on tags applied in WhatsApp.

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Webhook Payload Example</summary>

```json
{
  "id": "evt_01...",
  "timestamp": 1634567890123,
  "session": "default",
  "metadata": {
    "user.id": "123",
    "user.email": "email@example.com"
  },
  "engine": "WEBJS",
  "event": "label.chat.added",
  "payload": {
    "chatId": "11111111111@c.us",
    "labelId": "1"
  },
  "me": {
    "id": "11111111111@c.us",
    "lid": "123@lid",
    "pushName": "Instance"
  }
}
```

</details>

### Label Removed from Chat
**Endpoint:** `POST /label.chat.deleted`

Triggered when a label is unassigned from a conversation.

#### 💡 Tips
- **Pipeline Movement**: Use this to detect when a lead is cleared from a specific stage in your sales funnel.

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Webhook Payload Example</summary>

```json
{
  "id": "evt_01...",
  "timestamp": 1634567890123,
  "session": "default",
  "metadata": {
    "user.id": "123",
    "user.email": "email@example.com"
  },
  "engine": "WEBJS",
  "event": "label.chat.deleted",
  "payload": {
    "chatId": "11111111111@c.us",
    "labelId": "1"
  },
  "me": {
    "id": "11111111111@c.us",
    "lid": "123@lid",
    "pushName": "Instance"
  }
}
```

</details>

### Event Success Response
**Endpoint:** `POST /event.response`

Triggered when an asynchronous event completes successfully.

#### 💡 Tips
- **Async Tracking**: Essential for tracking the completion of bulk tasks or long-running operations.

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Webhook Payload Example</summary>

```json
{
  "id": "evt_01...",
  "timestamp": 1634567890123,
  "session": "default",
  "metadata": {
    "user.id": "123",
    "user.email": "email@example.com"
  },
  "engine": "WEBJS",
  "event": "event.response",
  "payload": {
    "requestId": "req_001",
    "data": {
      "status": "completed"
    }
  },
  "me": {
    "id": "11111111111@c.us",
    "lid": "123@lid",
    "pushName": "Instance"
  }
}
```

</details>

### Event Failure Response
**Endpoint:** `POST /event.response.failed`

Triggered when an asynchronous event fails to complete.

#### 💡 Tips
- **Error Recovery**: Always listen for this event to implement retry logic or alert users of a failed task.

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Webhook Payload Example</summary>

```json
{
  "id": "evt_01...",
  "timestamp": 1634567890123,
  "session": "default",
  "metadata": {
    "user.id": "123",
    "user.email": "email@example.com"
  },
  "engine": "WEBJS",
  "event": "event.response.failed",
  "payload": {
    "requestId": "req_002",
    "error": "TIMEOUT_ERROR"
  },
  "me": {
    "id": "11111111111@c.us",
    "lid": "123@lid",
    "pushName": "Instance"
  }
}
```

</details>

### Raw Engine Event
**Endpoint:** `POST /engine.event`

Catch-all for low-level system events directly from the WhatsApp engine.

#### 💡 Tips
- **Advanced Use**: This is primarily for developers needing raw access to internal engine movements not covered by high-level events.

#### 📦 Responses

<details>
<summary><b>HTTP 200</b>: Webhook Payload Example</summary>

```json
{
  "id": "evt_01...",
  "timestamp": 1634567890123,
  "session": "default",
  "metadata": {
    "user.id": "123",
    "user.email": "email@example.com"
  },
  "engine": "WEBJS",
  "event": "engine.event",
  "payload": {
    "raw": {
      "event": "internal_movement",
      "data": {}
    }
  },
  "me": {
    "id": "11111111111@c.us",
    "lid": "123@lid",
    "pushName": "Instance"
  }
}
```

</details>

---