WaAPI

https://waapi.readme.io/reference
Admin
WaAPI is an API gateway for sending messages via WhatsApp with support for instances, contacts,...
Tokens:115,431
Snippets:257
Trust Score:9.9
Update:11 months ago
Show doc for...
Tokens:
Raw
### Install Express framework using npm (Shell)

Source: https://waapi.readme.io/reference/webhooks

Installs the Express library, which is required to run the Node.js webhook server. Execute the command in your project directory before starting the server.

```Shell
npm install express --save
```

--------------------------------

### Example response for get contacts

Source: https://waapi.readme.io/reference/contact

Sample JSON response from the get contacts endpoint. Includes status, instance ID, and an array of contact objects with detailed information such as name, type, and contact status.

```JSON
{
  "status": "success",
  "instanceId": "1",
  "data": [
    {
      "id": {
        "server": "c.us",
        "user": "123456789012",
        "_serialized": "123456789012@c.us"
      },
      "number": "123456789012",
      "isBusiness": false,
      "isEnterprise": false,
      "name": "John Doe",
      "pushname": "John",
      "shortName": "John",
      "type": "in",
      "isMe": false,
      "isUser": true,
      "isGroup": false,
      "isWAContact": true,
      "isMyContact": true,
      "isBlocked": false
    }
  ]
}
```

--------------------------------

### JSON Response Example for Get Stories

Source: https://waapi.readme.io/reference/story

Example of a successful 200 response body containing status, instance ID, and stories array with details like timestamps, counts, and message objects including media keys and types. Stories include images, videos, or text from contacts.

```json
{
  "status": "success",
  "instanceId": "1",
  "data": {
    "stories": [
      {
        "id": {
          "server": "c.us",
          "user": "1234567890",
          "_serialized": "1234567890@c.us"
        },
        "timestamp": 1732860512,
        "totalCount": 1,
        "unreadCount": 1,
        "msgs": [
          {
            "mediaKey": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX=",
            "id": {
              "fromMe": false,
              "remote": {
                "server": "broadcast",
                "user": "status",
                "_serialized": "status@broadcast"
              },
              "participant": {
                "server": "c.us",
                "user": "1234567890",
                "_serialized": "1234567890@c.us"
              }
            },
            "type": "video",
            "timestamp": 1732860512,
            "from": "status@broadcast",
            "to": "1234567890@c.us",
            "author": "1234567890@c.us"
          }
        ]
      }
    ]
  }
}
```

--------------------------------

### Create Group Response Example

Source: https://waapi.readme.io/reference/group

Example successful response from the Create Group API. Contains group ID details and list of participants that couldn't be added.

```json
{
  "status": "success",
  "data": {
    "gid": {
      "server": "g.us",
      "user": "123456789123456789",
      "_serialized": "123456789123456789@g.us"
    },
    "missingParticipants": [
      "123456789@c.us"
    ]
  },
  "links": {
    "self": "https://waapi.app/api/v1/instances/1/client/action/create-group"
  }
}
```

--------------------------------

### GET Client Status with Shell

Source: https://waapi.readme.io/reference/client

This cURL command sends a GET request to retrieve the client status for a specific instance ID. It includes headers for accepting JSON responses and uses placeholder values. Authentication via Bearer token is implied but not detailed in the example. Outputs include client status details in JSON format.

```shell
curl --request GET \
     --url https://waapi.app/api/v1/instances/id/client/status \
     --header 'accept: application/json'
```

--------------------------------

### Get All Labels - JSON Response

Source: https://waapi.readme.io/reference/label

This snippet provides an example response body from the `/get-labels` endpoint. Upon successful execution, the API returns a JSON object containing the status, instance ID, and an array of labels. It includes self and status links for further interaction.

```JSON
{
  "data": {
    "status": "success",
    "instanceId": 0,
    "data": {
      "data": []
    }
  },
  "links": {
    "self": "https://waapi.app/api/v1/instances/1/client/action/get-labels"
  },
  "status": "success"
}
```

--------------------------------

### Message Object Properties

Source: https://waapi.readme.io/reference/send-vcard

Detailed documentation of all properties available in WhatsApp message objects with their data types and example values

```APIDOC
## Message Object Properties

### Description
Complete reference of all properties available in WhatsApp message objects

### Properties
- **lastPlaybackProgress** (integer) - Example: 0
- **isDynamicReplyButtonsMsg** (boolean) - Example: false
- **isCarouselCard** (boolean) - Example: false
- **parentMsgId** (string|null) - Nullable - Example: null
- **callSilenceReason** (string|null) - Nullable - Example: null
- **isVideoCall** (boolean) - Example: false
- **isMdHistoryMsg** (boolean) - Example: false
- **stickerSentTs** (integer) - Example: 0
- **isAvatar** (boolean) - Example: false
- **lastUpdateFromServerTs** (integer) - Example: 0
- **invokedBotWid** (string|null) - Nullable - Example: null
- **bizBotType** (string|null) - Nullable - Example: null
- **botResponseTargetId** (string|null) - Nullable - Example: null
- **botPluginType** (string|null) - Nullable - Example: null
- **botPluginReferenceIndex** (integer|null) - Nullable - Example: null
- **botPluginSearchProvider** (string|null) - Nullable - Example: null
- **botPluginSearchUrl** (string|null) - Nullable - Example: null
- **botPluginSearchQuery** (string|null) - Nullable - Example: null
```

--------------------------------

### GET /api/v1/instances

Source: https://waapi.readme.io/reference/api-token

Retrieve information about all instances associated with the authenticated user. Returns an array of instance objects with their details.

```APIDOC
## GET /api/v1/instances

### Description
Retrieve information about all instances associated with the authenticated user. Returns an array of instance objects with their details.

### Method
GET

### Endpoint
https://waapi.app/api/v1/instances

### Headers
| Header Name   | Header Value          | Required |
| :------------ | :-------------------- | :------- |
| Authorization | Bearer your-api-token | Required |
| Accept        | application/json      | Required |
| Content-Type  | application/json      | Required |

### Response
#### Success Response (200)
- **instances** (array) - Array of instance objects
  - **id** (string) - Unique identifier of the instance
  - **owner** (string) - Email of the instance owner
  - **webhook_url** (string) - URL that receives subscribed events
  - **webhook_events** (array) - Array of subscribed events

#### Response Example
```json
{
  "instances": [
    {
      "id": "instance-123",
      "owner": "user@example.com",
      "webhook_url": "https://example.com/webhook",
      "webhook_events": ["message", "status"]
    }
  ]
}
```
```

--------------------------------

### POST /instances/{id}/client/action/get-group-info

Source: https://waapi.readme.io/reference/get-group-info

Gets detailed information about a WhatsApp group, including owner, subject, creation time, invite code/link, and participants. Requires a valid instance ID and Bearer token authentication.

```APIDOC
## POST /instances/{id}/client/action/get-group-info

### Description
Get detailed information about a WhatsApp group for a given instance.

### Method
POST

### Endpoint
/instances/{id}/client/action/get-group-info

### Parameters
#### Path Parameters
- **id** (int64) - Required - Instance ID

#### Query Parameters
None

#### Request Body
- **chatId** (string) - Required - Group chat ID (e.g., `<xxxxx>@g.us`)

### Request Example
{
  "chatId": "<xxxxx>@g.us"
}

### Response
#### Success Response (200)
- **data** (object) - Group information object
  - **chatId** (object) - Group chat identifier
    - **server** (string) - Server part (e.g., `@g.us`)
    - **user** (string) - User part (e.g., `<xxxxxxx>`)
    - **_serialized** (string) - Serialized chat ID (e.g., `<xxxxxxx>@g.us`)
  - **owner** (object) - Group owner identifier
    - **server** (string) - Server part (e.g., `@c.us`)
    - **user** (string) - User part (e.g., `<xxxxxxx>`)
    - **_serialized** (string) - Serialized owner ID (e.g., `<xxxxxxx>@c.us`)
  - **subject** (string) - Group name
  - **createdAt** (string) - ISO 8601 timestamp of group creation (e.g., `2023-05-21T16:26:22.000Z`)
  - **createdAtTimestamp** (integer) - Unix timestamp of group creation (e.g., `1684859182`)
  - **inviteCode** (string) - Invite code (e.g., `abcxyzdefgfh`)
  - **inviteCodeLink** (string) - Invite link (e.g., `https://link.com/abcxyzdefgfh`)
  - **participants** (array) - Array of participant objects

#### Response Example
{
  "data": {
    "chatId": {
      "server": "@g.us",
      "user": "<xxxxxxx>",
      "_serialized": "<xxxxxxx>@g.us"
    },
    "owner": {
      "server": "@c.us",
      "user": "<xxxxxxx>",
      "_serialized": "<xxxxxxx>@c.us"
    },
    "subject": "group name",
    "createdAt": "2023-05-21T16:26:22.000Z",
    "createdAtTimestamp": 1684859182,
    "inviteCode": "abcxyzdefgfh",
    "inviteCodeLink": "https://link.com/abcxyzdefgfh",
    "participants": []
  }
}

### Authentication
Bearer token via `Authorization: Bearer <token>` header.
```

--------------------------------

### Mark chat messages as seen - Response example

Source: https://waapi.readme.io/reference/chat

Example response from the API when marking chat messages as seen. Contains data about whether the seen status was successfully sent and link references.

```json
{
  "data": {
    "seenSend": true
  },
  "links": {
    "self": "https://waapi.app/api/v1/instances/1/client/action/send-seen"
  },
  "status": "success"
}
```

--------------------------------

### cURL Request to Get Stories

Source: https://waapi.readme.io/reference/story

Sends a POST request to the /instances/{id}/client/action/get-stories endpoint to fetch stories. Requires instance ID as path parameter and authentication via Bearer token. Accepts application/json and returns story data on success.

```curl
curl --request POST \
     --url https://waapi.app/api/v1/instances/id/client/action/get-stories \
     --header 'accept: application/json'
```

--------------------------------

### GET /instances/{id}/client/me

Source: https://waapi.readme.io/reference/retrieve-basic-client-information

Retrieve general information of the user connected to your instance. This endpoint requires an instance ID as a path parameter.

```APIDOC
## GET /instances/{id}/client/me

### Description
Retrieve general information of the user connected to your instance.

### Method
GET

### Endpoint
/instances/{id}/client/me

### Parameters
#### Path Parameters
- **id** (integer) - Required - Instance ID

### Request Example
```json
{
  "id": 1
}
```

### Response
#### Success Response (200)
- **qrCode** (object) - Contains client information
- **links** (object) - Contains self link
- **status** (string) - Status of the response

#### Response Example
```json
{
  "qrCode": {
    "status": "success",
    "instanceId": "1",
    "data": {
      "displayName": "Username",
      "contactId": "<xxxxx>@c.us",
      "formattedNumber": "+xx xx xxx xx xx",
      "profilePicUrl": "https://pps.link.net/v/<profileImageUrl>"
    }
  },
  "links": {
    "self": "https://waapi.app/api/v1/instances/1/client/me"
  },
  "status": "success"
}
```
```

--------------------------------

### GET /api/v1/instances/{id}/client/qr

Source: https://waapi.readme.io/reference/retrieve-qr-code

Retrieves a base64 encoded QR code image that can be used to authenticate and connect an account to the specified instance. the instance ID as a path parameter.

```APIDOC
## GET /api/v1/instances/{id}/client/qr

### Description
Retrieves a base64 encoded QR code image that can be used to authenticate and connect an account to the specified instance.

### Method
GET

### Endpoint
https://waapi.app/api/v1/instances/{id}/client/qr

### Parameters
#### Path Parameters
- **id** (int64) - Required - Instance ID

#### Query Parameters
*(none)*

#### Request Body
*(none)*

### Request Example
*( request body for GET)*

### Response
#### Success Response (200)
- **qrCode** (object) - Base64 encoded QR code image and associated metadata
  - **status** (string) - Status of the QR code request (`success` or `error`)
  - **instanceId** (string) - ID of the instance
  - **data** (object) - Contains QR code data
    - **qr_code** (string) - Base64 PNG image data URI
- **links** (object)
  - **self** (string) - URL of this QR code endpoint
- **status** (string) - Overall request statussuccess` or `error`)

### Response Example
{
  "qrCode": {
    "status": "success",
    "instanceId": 1,
    "data": {
      "qr_code": "data:image/png;base64,iVBORw0KGgoAA...AAAElFTkSuQmCC"
    }
  },
  "links": {
    "self": "https://waapi.app/api/v1/instances/1/client/qr"
  },
  "status": "success"
}
```

--------------------------------

### Get Chat ID from Phone Number - Response Example

Source: https://waapi.readme.io/reference/number

Provides an example of the JSON response received after successfully retrieving a chat ID. It includes the status, instance ID, and the formatted chat ID object.

```json
{
  "data": {
    "status": "success",
    "instanceId": "1",
    "data": {
      "numberId": {
        "server": "c.us",
        "user": "15553334444",
        "_serialized": "15553334444@c.us"
      }
    }
  },
  "links": {
    "self": "https://waapi.app/api/v1/instances/1/client/action/get-number-id"
  },
  "status": "success"
}
```

--------------------------------

### WAAPI instances response example

Source: https://waapi.readme.io/reference/instances

Sample JSON response from the instances endpoint. Includes array of instance objects with properties like ID, name, webhook URL, and status. Demonstrates successful response structure.

```json
{
  "instances": [
    {
      "id": 1,
      "name": "My first instance",
      "owner": "mail@example.com",
      "webhook_url": "https://my.url.com/webhook/handler",
      "webhook_events": [
        "message",
        "qr"
      ],
      "is_trial": 0
    }
  ],
  "status": "success"
}
```

--------------------------------

### POST /api/v1/instances

Source: https://waapi.readme.io/reference/create-instance

This endpoint allows you to create a new instance. You need to provide a name, webhook URL, and optionally specify events that you want to receive.

```APIDOC
## POST /api/v1/instances

### Description
Create a new instance.

### Method
POST

### Endpoint
/api/v1/instances

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- `name` (string) - Required - The name of the instance.
- `webhook_url` (string) - Required - The URL to which webhook events should be sent.
- `webhook_events` (array of strings) - Optional - A list of events to subscribe to. Valid values are: `message`, `loading_screen`, `qr`, `authenticated`, `auth_failure`, `ready`, `disconnected`, `message_create`, `message_edit`, `message_revoke_everyone`, `message_revoke_me`, `message_ack`, `message_reaction`, `media_uploaded`, `group_join`, `group_leave`, `group_update`, `change_state`, `call`, `vote_update`.
- `is_trial` (boolean) - Optional - If instance is trial.

### Request Example
{
  "name": "My first instance",
  "webhook_url": "https://my.url.com/webhook/handler",
  "webhook_events": ["message", "qr"],
  "is_trial": false
}

### Response
#### Success Response (200)
- `instance` (object) - Details of the created instance.
- `status` (string) - Status of the operation, either `success` or `error`.

#### Response Example
{
  "instance": {
    "id": 1,
    "name": "My first instance",
    "owner": "mail@example.com",
    "webhook_url": "https://my.url.com/webhook/handler",
    "webhook_events": ["message", "qr"],
    "is_trial": false
  },
  "status": "success"
}
```

--------------------------------

### Get Chat ID from Phone Number - cURL

Source: https://waapi.readme.io/reference/number

Demonstrates retrieving a chat ID from a phone number using a cURL request. It includes the necessary headers and URL structure, along with example request and response payloads.

```curl
curl --request POST \n  --url https://waapi.app/api/v1/instances/id/client/action/get-number-id \n  --header 'accept: application/json' \n  --header 'content-type: application/json'
```

--------------------------------

### Readme Configuration Settings

Source: https://waapi.readme.io/reference/update-instance

Configures the Readme IO settings for the WAAPI project, enabling the API explorer and proxy features.

```json
{
  "x-readme": {
    "explorer-enabled": true,
    "proxy-enabled": true
  },
  "_id": "653551ba368ea0004afb5269"
}
```

--------------------------------

### Get All Labels - OpenAPI JSON

Source: https://waapi.readme.io/reference/get-labels

This OpenAPI JSON specification defines the API structure for retrieving all labels associated with a WaAPI instance. It requires a bearer token for authentication and takes an instance ID as a path parameter. The response includes a list of labels or an empty array, with examples provided for success and error statuses.

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "WaAPI API",
    "description": "WaAPI is a simple API gateway for sending  messages.",
    "version": "v1.6.0"
  },
  "servers": [
    {
      "url": "https://waapi.app/api/v1"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "tags": [
    {
      "name": "label",
      "description": "Operations related to Label management."
    }
  ],
  "paths": {
    "/instances/{id}/client/action/get-labels": {
      "post": {
        "tags": [
          "label"
        ],
        "summary": "get all labels",
        "operationId": "get-labels",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "Instance ID",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "return a list labels and their IDs",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "$ref": "#/components/schemas/status"
                        },
                        "instanceId": {
                          "type": "integer",
                          "format": "int64"
                        },
                        "data": {
                          "type": "object",
                          "example": {
                            "data": []
                          },
                          "description": "Label list response"
                        }
                      }
                    },
                    "links": {
                      "type": "object",
                      "properties": {
                        "self": {
                          "type": "string",
                          "example": "https://waapi.app/api/v1/instances/1/client/action/get-labels"
                        }
                      }
                    },
                    "status": {
                      "$ref": "#/components/schemas/status"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      }
    },
    "schemas": {
      "status": {
        "type": "string",
        "items": {
          "type": "string",
          "example": "success"
        },
        "enum": [
          "success",
          "error"
        ]
      }
    }
  },
  "x-readme": {
    "explorer-enabled": true,
    "proxy-enabled": true
  },
  "_id": "653551ba368ea0004afb5269"
}
```

--------------------------------

### List WAAPI instances with cURL

Source: https://waapi.readme.io/reference/instances

Example cURL command to retrieve a list of WAAPI instances. Requires authentication via Bearer token. Returns JSON array of instance objects with details like ID, name, owner, and webhook configuration.

```shell
curl --request GET \
     --url https://waapi.app/api/v1/instances \
     --header 'accept: application/json'
```

--------------------------------

### Define Get Contact LID and Phone endpoint in OpenAPI (JSON)

Source: https://waapi.readme.io/reference/get-lid

This JSON snippet defines the OpenAPI specification for the Get Contact LID and Phone operation. It includes the path, request schema for contact IDs, security requirements, and the expected JSON response containing contact LID and phone data.

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "WaAPI API",
    "description": "WaAPI is a simple API gateway for sending  messages.",
    "version": "v1.6.0"
  },
  "servers": [
    {
      "url": "https://waapi.app/api/v1"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "tags": [
    {
      "name": "contact",
      "description": "Operations related to managing contacts."
    }
  ],
  "paths": {
    "/instances/{id}/client/action/get-lid": {
      "post": {
        "tags": [
          "contact"
        ],
        "summary": "Get Contact LID and Phone",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "Instance ID",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          }
        ],
        "description": "Retrieves LinkedIn ID (LID) and phone number for specified contacts. Returns an array of contact objects with their LID and phone number mappings.",
        "operationId": "get-lid",
 "requestBody": {
          "required": truen          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "contactIds"
                ],
                "properties": {
                  "contactIds": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "example": "491729682587@c.us"
                    },
                    "example": [
                      "491729682587@c.us"
                    ],
                    "description": "Array of contact IDs in the format number@c.us"
                  }
                }
              }            }
          }
        },
        "responses": {
          "200": {
            "description": "Contact LID and phone information retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "example": "success"
                    },
                    "instanceId": {
                      "type": "string",
                      "example": "33322"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "contacts": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "lid": {
                                "type": "string",
                                "example": "169724423991411@lid",
                                "description": "LinkedIn ID for the contact"
                              },
                              "pn": {
                                "type": "string",
                                "example": "491729682587@c.us",
                                "description": "Phone number of the contact"
                              }
                            }
                          }
                        },
                        "count": {
                          "type": "integern                          "example": 1,
                          "description": "Number of contacts returned"
                        }
                      }
                    },
                    "links": {
                      "type": "object",
                      "properties": {
                        "self": {
                          "type": "string",
                          "example": "https://waapi.app/api/v1/instances/1/client/action/get-lid"
                        }
                      }
                    }
                  }
                }
              }
            }
          }        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      }
    }
  },
  "x-readme": {
    "explorer-enabled": true,
    "proxy-enabled": true
  },
  "_id": "653551ba368ea0004afb5269n}
```

--------------------------------

### POST /instances/{id}/client/action/get-channels

Source: https://waapi.readme.io/reference/get-channels

Retrieves channels associated with a specific instance. Use this endpoint to get a list of channels for a given instance identifier.

```APIDOC
## POST /instances/{id}/client/action/get-channels

### Description
Retrieves channels associated with a specific instance. Use this endpoint to get a list of channels for a given instance identifier.

### Method
POST

### Endpoint
/instances/{id}/client/action/get-channels

### Parameters
#### Path Parameters
- **id** (integer) - Required - Instance ID

#### Query Parameters
None

#### Request Body
None

### Request Example
{
  "example": "N/A"
}

### Response
#### Success Response (200)
- **status** (string) - Response status (success or error).
- **data** (object) - Channel data.
- **links** (object) - Links related to the request.
  - **self** (string) - URL to the endpoint.

#### Response Example
{
  "status": "success",
  "data": {
    "example": "Channel Data"
  },
  "links": {
    "self": "https://waapi.app/api/v1/instances/1/client/action/get-channels"
  }
}
```

--------------------------------

### POST /api/v1/instances/{id}/client/action/create-group

Source: https://waapi.readme.io/reference/group

Creates a new group with the specified name and participants. Requires instance ID and valid group details.

```APIDOC
## POST /api/v1/instances/{id}/client/action/create-group

### Description
Creates a new group with specified name and participants.

### Method
POST

### Endpoint
https://waapi.app/api/v1/instances/{id}/client/action/create-group

### Parameters
#### Path Parameters
- **id** (int64) - Required - Instance ID of the client

#### Request Body
- **groupName** (string) - Required - Name of the group to be created (length ≥ 1)
- **groupParticipants** (array of strings) - Required - Array of contact IDs to add to the group (length ≥ 1)

### Request Example
{
  "groupName": "My New Group",
  "groupParticipants": ["123456789@c.us", "987654321@c.us"]
}

### Response
#### Success Response (200)
- **status** (string) - Enum: `success` or `error`
- **data** (object) - Contains group details
  - **gid** (object) - Group ID details
    - **server** (string)
    - **user** (string)
    - **_serialized** (string)
  - **missingParticipants** (array of strings) - List of participants that could not be added
  - **links** (object) - Contains API endpoint URL
    - **self** (string)

#### Response Example
{
  "status": "success",
  "data": {
    "gid": {
      "server": "g.us",
      "user": "123456789123456789",
      "_serialized": "123456789123456789@g.us"
    },
    "missingParticipants": [
      "123456789@c.us"
    ]
  },
  "links": {
    "self": "https://waapi.app/api/v1/instances/1/client/action/create-group"
  }
}
```

--------------------------------

### Create channel via cURL

Source: https://waapi.readme.io/reference/channel

Example cURL command for creating a channel in WAAPI. Requires instance ID and accepts JSON headers. Returns success/error status with resource links.

```shell
curl --request POST \
     --url https://waapi.app/api/v1/instances/id/client/action/create-channel \
     --header 'accept: application/json' \
     --header 'content-type: application/json'
```

--------------------------------

### Get Formatted Number API Endpoint - OpenAPI

Source: https://waapi.readme.io/reference/get-formatted-number

Complete OpenAPI 3.1 specification for the get-formatted-number endpoint. Defines the request/response structure, authentication requirements, and parameter validation for formatting phone numbers.

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "WaAPI API",
    "description": "WaAPI is a simple API gateway for sending  messages.",
    "version": "v1.6.0"
  },
  "servers": [
    {
      "url": "https://waapi.app/api/v1"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "tags": [
    {
      "name": "contact",
      "description": "Operations related to managing contacts."
    }
  ],
  "paths": {
    "/instances/{id}/client/action/get-formatted-number": {
      "post": {
        "tags": [
          "contact"
        ],
        "summary": "get formatted number",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "Instance ID",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          }
        ],
        "description": "Format a phone number into standardized format",
        "operationId": "get-formatted-number",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "number"
                ],
                "properties": {
                  "number": {
                    "type": "string",
                    "description": "Phone number to format",
                    "example": "+1234567890"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Number formatting result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "$ref": "#/components/schemas/status"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "formattedNumber": {
                          "type": "string",
                          "example": "12345678901@c.us"
                        },
                        "number": {
                          "type": "string",
                          "example": "1234567890"
                        }
                      }
                    },
                    "links": {
                      "type": "object",
                      "properties": {
                        "self": {
                          "type": "string",
                          "example": "https://waapi.app/api/v1/instances/1/client/action/get-formatted-number"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      }
    },
    "schemas": {
      "status": {
        "type": "string",
        "items": {
          "type": "string",
          "example": "success"
        },
        "enum": [
          "success",
          "error"
        ]
      }
    }
  },
  "x-readme": {
    "explorer-enabled": true,
    "proxy-enabled": true
  },
  "_id": "653551ba368ea0004afb5269"
}
```

--------------------------------

### POST /instances/{id}/client/action/promote-group-participant

Source: https://waapi.readme.io/reference/promote-group-participant

Promotes a participant to admin in a WhatsApp group. Requires instance ID and participant details.

```APIDOC
## POST /instances/{id}/client/action/promote-group-participant

### Description
Promote a participant to admin in a WhatsApp group.

### Method
POST

### Endpoint
/instances/{id}/client/action/promote-group-participant

### Parameters
#### Path Parameters
- **id** (integer) - Required - Instance ID

#### Request Body
- **chatId** (string) - Required - Group chat ID (e.g., <yyyyyyyyyyyyyyy>@g.us)
- **participant** (string) - Required - Participant ID to promote (e.g., <xxxxxxxxx>@c.us)

### Request Example
{
  "chatId": "<yyyyyyyyyyyyyyy>@g.us",
  "participant": "<xxxxxxxxx>@c.us"
}

### Response
#### Success Response (200)
- **data** (object) - Group information
- **links.self** (string) - API endpoint URL
- **status** (string) - Operation status ('success' or 'error')

#### Response Example
{
  "data": {},
  "links": {
    "self": "https://waapi.app/api/v1/instances/1/client/action/promote-group-participant"
  },
  "status": "success"
}
```

--------------------------------

### POST /api/v1/instances/{id}/client/action/create-channel

Source: https://waapi.readme.io/reference/channel

Creates a new channel for a WhatsApp instance. Supply the instance ID in the path and the channel details in the request body. Authentication is required.

```APIDOC
## POST /api/v1/instances/{id}/client/action/create-channel

### Description
Create a new channel for a specific WhatsApp instance using the authenticated request.

### Method
POST

### Endpoint
/api/v1/instances/{id}/client/action/create-channel

### Parameters
#### Path Parameters
- **id** (int64) - Required - Instance ID

#### Query Parameters
None

#### Request Body
- **name** (string) - Optional - Channel name
- **description** (string) - Optional - Channel description
- **pictureUrl** (string) - Optional - URL to the channel picture

### Request Example
curl --request POST \
     --url https://waapi.app/api/v1/instances/{id}/client/action/create-channel \
     --header 'accept: application/json' \
     --header 'content-type: application/json'

### Response
#### Success Response (200)
- **status** (string) - enum: `success` | `error`
- **data** (object) - Channel data payload
- **links** (object) - Related links
  - **self** (string) - Canonical URL of the resource

#### Response Example
{
  "status": "success",
  "data": {},
  "links": {
    "self": "https://waapi.app/api/v1/instances/1/client/action/create-channel"
  }
}

```

--------------------------------

### OpenAPI Definition for Get Message Info by ID - JSON

Source: https://waapi.readme.io/reference/get-message-info-by-id

Complete OpenAPI 3.1.0 specification defining the endpoint for retrieving message information by ID. Includes request/response schemas, parameters, authentication requirements, and server configuration.

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "WaAPI API",
    "description": "WaAPI is a simple API gateway for sending  messages.",
    "version": "v1.6.0"
  },
  "servers": [
    {
      "url": "https://waapi.app/api/v1"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "tags": [
    {
      "name": "message",
      "description": "Operations related to sending and managing messages."
    }
  ],
  "paths": {
    "/instances/{id}/client/action/get-message-info-by-id": {
      "post": {
        "tags": [
          "message"
        ],
        "summary": "get message info by id",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "Instance ID",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          }
        ],
        "description": "get a message info by id",
        "operationId": "get-message-info-by-id",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "messageId": {
                    "type": "string",
                    "example": "<bool>_<xxxxx>@c.us>_<megssageHash>",
                    "description": "serialized messageId, <fromMe>_<chatId>_<hash>"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "message": {
                          "type": "object",
                          "properties": []
                        },
                        "media": {
                          "type": "object",
                          "properties": []
                        }
                      }
                    },
                    "links": {
                      "type": "object",
                      "properties": {
                        "self": {
                          "type": "string",
                          "example": "https://waapi.app/api/v1/instances/1/client/action/get-message-info-by-id"
                        }
                      }
                    },
                    "status": {
                      "$ref": "#/components/schemas/status"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      }
    },
    "schemas": {
      "status": {
        "type": "string",
        "items": {
          "type": "string",
          "example": "success"
        },
        "enum": [
          "success",
          "error"
        ]
      }
    }
  },
  "x-readme": {
    "explorer-enabled": true,
    "proxy-enabled": true
  },
  "_id": "653551ba368ea0004afb5269"
}
```

--------------------------------

### Get All Labels - cURL

Source: https://waapi.readme.io/reference/label

This snippet demonstrates how to retrieve all labels using a cURL request. It shows the required headers and URL structure, utilizing the instance ID in the path parameters. The API returns a JSON object containing label data and status information.

```cURL
curl --request POST \
     --url https://waapi.app/api/v1/instances/id/client/action/get-labels \
     --header 'accept: application/json'
```

--------------------------------

### POST /instances/{id}/client/action/create-channel

Source: https://waapi.readme.io/reference/create-channel

Creates a new channel within a specific instance. This endpoint allows for defining the channel's name, description, and an optional picture URL.

```APIDOC
## POST /instances/{id}/client/action/create-channel

### Description
Creates a new channel within a specific instance. This endpoint allows for defining the channel's name, description, and an optional picture URL.

### Method
POST

### Endpoint
/instances/{id}/client/action/create-channel

### Parameters
#### Path Parameters
- **id** (integer) - Required - Instance ID

#### Query Parameters
None

#### Request Body
- **name** (string) - Required - The name of the channel.
- **description** (string) - Optional - A description for the channel.
- **pictureUrl** (string) - Optional - A URL for the channel's picture.

### Request Example
```json
{
  "name": "My Channel Name",
  "description": "My Channel description",
  "pictureUrl": "https://tmp.waapi.app/ce81b23e5ac34a428c79705a08ea9f51:waapi/static/logo.png"
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the status of the operation (e.g., 'success' or 'error').
- **data** (object) - An empty object for this response.
- **links** (object) - Contains a link to the self URL of the created channel.
  - **self** (string) - The URL for the created channel.

#### Response Example
```json
{
  "status": "success",
  "data": {},
  "links": {
    "self": "https://waapi.app/api/v1/instances/1/client/action/create-channel"
  }
}
```
```

--------------------------------

### POST /instances/{id}/client/action/get-invite-info

Source: https://waapi.readme.io/reference/get-invite-info

Retrieves detailed information about a group invite code including group ID, invite code, and expiration timestamp. Requires Bearer token authentication and valid instance ID.

```APIDOC
## POST /instances/{id}/client/action/get-invite-info

### Description
Get information about a group invite code using the provided invite code and instance ID.

### Method
POST

### Endpoint
/instances/{id}/client/action/get-invite-info

### Parameters
#### Path Parameters
- **id** (integer) - Required - Instance ID

#### Request Body
- **inviteCode** (string) - Required - The group invite code to get information about

### Request Example
{
  "inviteCode": "abcdefghijk"
}

### Response
#### Success Response (200)
- **data** (object) - Response data containing invite information
  - **inviteInfo** (object) - Detailed invite information
    - **groupId** (string) - The group ID
    - **inviteCode** (string) - The invite code
    - **inviteCodeExpiration** (integer) - Timestamp when the invite code expires
- **links** (object) - API links
  - **self** (string) - Self-reference link
- **status** (string) - Response status

#### Response Example
{
  "data": {
    "inviteInfo": {
      "groupId": "123456789@g.us",
      "inviteCode": "abcdefghijk",
      "inviteCodeExpiration": 1234567890
    }
  },
  "links": {
    "self": "https://waapi.app/api/v1/instances/1/client/action/get-invite-info"
  },
  "status": "success"
}
```

--------------------------------

### GET /chats/{chatId}

Source: https://waapi.readme.io/reference/send-media-message

Retrieve information about a specific chat using its unique chat ID.

```APIDOC
## GET /chats/{chatId}

### Description
Fetches details for a specific chat given its unique identifier.

### Method
GET

### Endpoint
/chats/{chatId}

### Parameters
#### Path Parameters
- **chatId** (string) - Required - Unique ID of the chat. Format: `countrycode_shortusernumber@c.us` or `@g.us` for groups

### Response
#### Success Response (200)
- **chatId** (string) - Unique identifier for the chat
- **participants** (array) - List of chat participants

#### Response Example
{
  "chatId": "50664083362@c.us",
  "participants": [
    "123456789@c.us",
    "987654321@c.us"
  ]
}
```

--------------------------------

### API Token Permissions

Source: https://waapi.readme.io/reference/api-token

Documentation of available API token permissions and their descriptions for fine-grained access control.

```APIDOC
## API Token Permissions

### Description
Available permissions that can be assigned to API tokens for controlling access to different API functionalities.

### Permissions
| Permission | Description                                                                                                                                             |
| :--------- | :------------------------------------------------------------------------------------------------------------------------------------------------------ |
| create     | Create new instances up to your total instance limit.                                                                                                   |
| delete     | Completely delete existing instances. This will decrease your total instance limit.                                                                     |
| read       | Receive information of all or a single of your existing instances (e.g. read the instance id, webhook url, the instance owner or the subscribed events).|
| update     | Update an existing instance (e.g. change the webhook url or edit the subscription to events).                                                           |
```

--------------------------------

### WAAPI States Configuration

Source: https://waapi.readme.io/reference/update-instance

Defines various states for the WAAPI project including loading, authentication, and disconnection states. This is part of the project's configuration.

```json
{
  "loading_screen",
  "qr",
  "authenticated",
  "auth_failure",
  "ready",
  "disconnected"
}
```
Tokens:
Raw