API guides

Chat operations

Exact methods, permissions, request bodies and query fields for chat operations.

Read as Markdown OpenAPI specification

Get active chats for a session#

GET /api/v1/channels/{channel_id}/chats

Token scope: read. Paid access and a ready, customer-owned session are required. List responses are bounded; use documented pagination parameters.

Upstream permissions and engine support apply. Unsupported operations may return 501; WhatsApp can refuse actions even when a session is connected.

Query parameter	Required	Schema
limit	No	{"type":"integer","minimum":1,"maximum":100}
offset	No	{"type":"integer","minimum":0,"maximum":10000}

{
  "type": "object",
  "properties": {},
  "additionalProperties": false,
  "required": []
}

Mark a chat as read/seen#

POST /api/v1/channels/{channel_id}/chats/read

Token scope: manage. Paid access and a ready, customer-owned session are required. Supply an Idempotency-Key. Returns an operation ID; inspect /api/v1/operations/{id}. A completed result is recorded; an unconfirmed result is uncertain and never automatically retried.

Upstream permissions and engine support apply. Unsupported operations may return 501; WhatsApp can refuse actions even when a session is connected.

chatIdRequired: string
Maximum 255 characters. Individual, group or newsletter WhatsApp ID.
messageIdsOptional: array
Maximum 100 items. See JSON schema for all validation constraints.

{
  "type": "object",
  "properties": {
    "chatId": {
      "type": "string",
      "maxLength": 255
    },
    "messageIds": {
      "maxItems": 100,
      "minItems": 1,
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 4096
      }
    }
  },
  "required": [
    "chatId"
  ],
  "additionalProperties": false
}

Mark a chat as unread#

POST /api/v1/channels/{channel_id}/chats/unread

Token scope: manage. Paid access and a ready, customer-owned session are required. Supply an Idempotency-Key. Returns an operation ID; inspect /api/v1/operations/{id}. A completed result is recorded; an unconfirmed result is uncertain and never automatically retried.

Upstream permissions and engine support apply. Unsupported operations may return 501; WhatsApp can refuse actions even when a session is connected.

chatIdRequired: string
Maximum 255 characters. Individual, group or newsletter WhatsApp ID.

{
  "type": "object",
  "properties": {
    "chatId": {
      "type": "string",
      "maxLength": 255
    }
  },
  "required": [
    "chatId"
  ],
  "additionalProperties": false
}

Delete every message in a chat, keeping the chat itself#

DELETE /api/v1/channels/{channel_id}/chats/{chatId}/messages

Token scope: manage. Paid access and a ready, customer-owned session are required. Supply an Idempotency-Key. Returns an operation ID; inspect /api/v1/operations/{id}. A completed result is recorded; an unconfirmed result is uncertain and never automatically retried.

Upstream permissions and engine support apply. Unsupported operations may return 501; WhatsApp can refuse actions even when a session is connected.

{
  "type": "object",
  "properties": {},
  "additionalProperties": false,
  "required": []
}

Archive or unarchive a chat#

POST /api/v1/channels/{channel_id}/chats/archive

Token scope: manage. Paid access and a ready, customer-owned session are required. Supply an Idempotency-Key. Returns an operation ID; inspect /api/v1/operations/{id}. A completed result is recorded; an unconfirmed result is uncertain and never automatically retried.

Upstream permissions and engine support apply. Unsupported operations may return 501; WhatsApp can refuse actions even when a session is connected.

chatIdRequired: string
Maximum 255 characters. Individual, group or newsletter WhatsApp ID.
archiveRequired: boolean
See JSON schema for all validation constraints.

{
  "type": "object",
  "properties": {
    "chatId": {
      "type": "string",
      "maxLength": 255
    },
    "archive": {
      "type": "boolean"
    }
  },
  "required": [
    "chatId",
    "archive"
  ],
  "additionalProperties": false
}

Mute or unmute a chat#

POST /api/v1/channels/{channel_id}/chats/mute

Token scope: manage. Paid access and a ready, customer-owned session are required. Supply an Idempotency-Key. Returns an operation ID; inspect /api/v1/operations/{id}. A completed result is recorded; an unconfirmed result is uncertain and never automatically retried.

Upstream permissions and engine support apply. Unsupported operations may return 501; WhatsApp can refuse actions even when a session is connected.

chatIdRequired: string
Maximum 255 characters. Individual, group or newsletter WhatsApp ID.
muteUntilRequired: integer
See JSON schema for all validation constraints.

{
  "type": "object",
  "properties": {
    "chatId": {
      "type": "string",
      "maxLength": 255
    },
    "muteUntil": {
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "chatId",
    "muteUntil"
  ],
  "additionalProperties": false
}

Pin or unpin a chat at the top of the chat list#

POST /api/v1/channels/{channel_id}/chats/pin

Token scope: manage. Paid access and a ready, customer-owned session are required. Supply an Idempotency-Key. Returns an operation ID; inspect /api/v1/operations/{id}. A completed result is recorded; an unconfirmed result is uncertain and never automatically retried.

Upstream permissions and engine support apply. Unsupported operations may return 501; WhatsApp can refuse actions even when a session is connected.

chatIdRequired: string
Maximum 255 characters. Individual, group or newsletter WhatsApp ID.
pinRequired: boolean
See JSON schema for all validation constraints.

{
  "type": "object",
  "properties": {
    "chatId": {
      "type": "string",
      "maxLength": 255
    },
    "pin": {
      "type": "boolean"
    }
  },
  "required": [
    "chatId",
    "pin"
  ],
  "additionalProperties": false
}

Delete a chat from the chat list (e.g. a group you have left)#

POST /api/v1/channels/{channel_id}/chats/delete

Token scope: manage. Paid access and a ready, customer-owned session are required. Supply an Idempotency-Key. Returns an operation ID; inspect /api/v1/operations/{id}. A completed result is recorded; an unconfirmed result is uncertain and never automatically retried.

Upstream permissions and engine support apply. Unsupported operations may return 501; WhatsApp can refuse actions even when a session is connected.

chatIdRequired: string
Maximum 255 characters. Individual, group or newsletter WhatsApp ID.

{
  "type": "object",
  "properties": {
    "chatId": {
      "type": "string",
      "maxLength": 255
    }
  },
  "required": [
    "chatId"
  ],
  "additionalProperties": false
}

Send a typing/recording presence indicator to a chat (or clear it with 'paused')#

POST /api/v1/channels/{channel_id}/chats/typing

Token scope: manage. Paid access and a ready, customer-owned session are required. Supply an Idempotency-Key. Returns an operation ID; inspect /api/v1/operations/{id}. A completed result is recorded; an unconfirmed result is uncertain and never automatically retried.

Upstream permissions and engine support apply. Unsupported operations may return 501; WhatsApp can refuse actions even when a session is connected.

chatIdRequired: string
Maximum 255 characters. Individual, group or newsletter WhatsApp ID.
stateRequired: string
Allowed: ["typing","recording","paused"]. Maximum 4096 characters. See JSON schema for all validation constraints.

{
  "type": "object",
  "properties": {
    "chatId": {
      "type": "string",
      "maxLength": 255
    },
    "state": {
      "type": "string",
      "enum": [
        "typing",
        "recording",
        "paused"
      ],
      "maxLength": 4096
    }
  },
  "required": [
    "chatId",
    "state"
  ],
  "additionalProperties": false
}

Message operations

Previous Page

Contact operations

Next Page

On this page

Get active chats for a session Mark a chat as read/seen Mark a chat as unread Delete every message in a chat, keeping the chat itself Archive or unarchive a chat Mute or unmute a chat Pin or unpin a chat at the top of the chat list Delete a chat from the chat list (e.g. a group you have left)Send a typing/recording presence indicator to a chat (or clear it with 'paused')