Overview - RyzeAPI

The Chat module groups everything that happens after a message comes in or goes out: contact management, organization with labels, chat state control (archive, pin, mute, block), and actions on individual messages (edit, delete, forward, favorite). It is the broadest module in the API: from a simple call like “list contacts” to complete flows like “create a label, assign it to several chats, then list everything that has that label”.

Every route accepts TokenAccount or TokenInstance and validates instance ownership before operating.

Endpoints

Method	Path	Function
GET	`/api/chat/contacts/:instance`	List/search contacts
GET	`/api/chat/contactsByLabel/:instance`	Chats filtered by label
GET	`/api/chat/getMessage/:instance`	Find message by ID
GET	`/api/chat/tag/:instance`	List labels
POST	`/api/chat/tag/:instance`	Create label
DELETE	`/api/chat/tag/:instance`	Delete label
POST	`/api/chat/assignTag/:instance`	Apply label to chat
DELETE	`/api/chat/assignTag/:instance`	Remove label from chat
POST	`/api/chat/archive/:instance`	Archive/unarchive
POST	`/api/chat/markRead/:instance`	Mark message as read
POST	`/api/chat/markChatRead/:instance`	Mark entire chat as read
POST	`/api/chat/pinChat/:instance`	Pin/unpin chat
POST	`/api/chat/pinMessage/:instance`	Pin/unpin message
POST	`/api/chat/favorite/:instance`	Favorite chat or message
POST	`/api/chat/mute/:instance`	Mute
POST	`/api/chat/block/:instance`	Block/unblock contact
POST	`/api/chat/presence/:instance`	Send presence (typing/recording)
POST	`/api/chat/history/:instance`	Chat history
GET	`/api/chat/base64/:instance`	Media as base64
GET	`/api/chat/status/:instance`	Message delivery status
GET	`/api/chat/poll/:instance`	Poll votes
POST	`/api/chat/forward/:instance`	Forward message
POST	`/api/chat/edit/:instance`	Edit message
DELETE	`/api/chat/delete/:instance`	Delete message
DELETE	`/api/chat/deleteChat/:instance`	Delete entire chat

Contacts

Query synced contacts and filter by labels.

List contacts

GET /api/chat/contacts/:instance

Contacts by label

GET /api/chat/contactsByLabel/:instance

Labels (tags / labels)

Create labels, apply them to chats, and use them as filters, exactly what WhatsApp Business allows, but via API.

List labels

GET /api/chat/tag/:instance

Create label

POST /api/chat/tag/:instance

Delete label

DELETE /api/chat/tag/:instance

Assign label

POST /api/chat/assignTag/:instance

Unassign label

DELETE /api/chat/assignTag/:instance

Chat state

Control how each conversation appears to the WhatsApp user, archive, pin, mute, favorite, block.

Archive chat

POST /api/chat/archive/:instance

Pin chat

POST /api/chat/pinChat/:instance

Pin message

POST /api/chat/pinMessage/:instance

Mute chat

POST /api/chat/mute/:instance

Favorite chat or message

POST /api/chat/favorite/:instance

Block / unblock

POST /api/chat/block/:instance

Read

Mark message as read

POST /api/chat/markRead/:instance

Mark chat as read

POST /api/chat/markChatRead/:instance

Presence

Send presence (typing/recording)

POST /api/chat/presence/:instance, shows typing or recording to the contact.

History

Request history

POST /api/chat/history/:instance, stored messages with optional date filters.

Messages

Actions on specific messages, plus utilities to download media, read polls, and check delivery status.

Find message by ID

GET /api/chat/getMessage/:instance

Forward message

POST /api/chat/forward/:instance

Edit message

POST /api/chat/edit/:instance

Delete message

DELETE /api/chat/delete/:instance

Delete entire chat

DELETE /api/chat/deleteChat/:instance

Media as base64

GET /api/chat/base64/:instance

Delivery status

GET /api/chat/status/:instance

Poll votes

GET /api/chat/poll/:instance

Accepted identifiers

Most endpoints accept the same formats to identify a chat or destination. The table below summarizes them:

Endpoint	Accepts
Most (`number`)	Number (`5511...`), private JID (`...@s.whatsapp.net` or `...@lid`), group JID (`...@g.us`), newsletter JID
`markRead` in groups	Requires `sender` (JID of the message author, `...@s.whatsapp.net` or `...@lid`)
`forward` (`to`)	Same set as `number`

About @lid (LinkedID): an alternative identifier WhatsApp uses for individual users when the phone number is not exposed (privacy in communities, large groups, etc.). It is equivalent to ...@s.whatsapp.net for routing purposes, any endpoint that accepts a private JID also accepts @lid. Use the exact JID coming from a webhook or previous API responses; do not try to convert @lid into a number.

WhatsApp windows

Action	Limit
Edit message	~15 minutes after sending
Delete for everyone (`deleteForEveryone: true`)	~2 days and 12 h after sending
After the window	Local deletion only (`delete_for_me`)

Usage patterns

Label workflow

# 1. Create label
curl -X POST "https://ryzeapi.cloud/api/chat/tag/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{"name":"VIP","color":3}'

# 2. Apply to a chat
curl -X POST "https://ryzeapi.cloud/api/chat/assignTag/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{"number":"5511999999999","tagId":"1"}'

# 3. List chats with the label
curl "https://ryzeapi.cloud/api/chat/contactsByLabel/$Instance_Name?labelIds=1" \
  -H "token: $Token_Instance"

# 4. Remove the label from the chat
curl -X DELETE "https://ryzeapi.cloud/api/chat/assignTag/$Instance_Name?number=5511999999999&tagId=1" \
  -H "token: $Token_Instance"

Moderation workflow

# 1. Mark as read
curl -X POST "https://ryzeapi.cloud/api/chat/markChatRead/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{"number":"5511999999999","read":true}'

# 2. Mute for 8h
curl -X POST "https://ryzeapi.cloud/api/chat/mute/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{"number":"5511999999999","mute":true,"duration":"8h"}'

# 3. Archive
curl -X POST "https://ryzeapi.cloud/api/chat/archive/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{"number":"5511999999999","archive":true}'

# 4. Block (last resort)
curl -X POST "https://ryzeapi.cloud/api/chat/block/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{"number":"5511999999999","block":true}'

Send messages

Send content before managing it.

Real-time events

Webhooks message.exchange, message.status, and label.update.

​Endpoints

​Contacts

List contacts

Contacts by label

​Labels (tags / labels)

List labels

Create label

Delete label

Assign label

Unassign label

​Chat state

Archive chat

Pin chat

Pin message

Mute chat

Favorite chat or message

Block / unblock

​Read

Mark message as read

Mark chat as read

​Presence

Send presence (typing/recording)

​History

Request history

​Messages

Find message by ID

Forward message

Edit message

Delete message

Delete entire chat

Media as base64

Delivery status

Poll votes

​Accepted identifiers

​WhatsApp windows

​Usage patterns

​Label workflow

​Moderation workflow

​Related

Send messages

Real-time events

Endpoints

Contacts

Labels (tags / labels)

Chat state

Read

Presence

History

Messages

Accepted identifiers

WhatsApp windows

Usage patterns

Label workflow

Moderation workflow

Related