Skip to main content
GET
/
api
/
chat
/
contactsByLabel
/
:instance
Contacts by label
curl --request GET \
  --url https://api.example.com/api/chat/contactsByLabel/:instance
Auth: TokenAccount or TokenInstance • Rate-limit: Global (100/min) • Idempotent: yes

​
Description

Returns chats that have at least one of the given labels. You can filter by IDs, by names (case-insensitive), or return every chat that has any label at all.
Use refresh=true to force a sync with WhatsApp before listing, useful when a label was changed on the phone and you want the latest data.

​
Examples

​
By IDs

Filters chats that have at least one of the labels listed in ?labelIds=1,2. Useful when you already know the IDs from /tags-list. 
curl -X GET "https://ryzeapi.cloud/api/chat/contactsByLabel/$Instance_Name?labelIds=1,2" \
  -H "token: $Token_Instance"

​
By names (with refresh)

Filters by name via ?labelNames=VIP,Support (case-insensitive) and adds refresh=true to force a sync with WhatsApp before listing, ensuring changes made on the phone are already visible. 
curl -X GET "https://ryzeapi.cloud/api/chat/contactsByLabel/$Instance_Name?labelNames=VIP,Support&refresh=true" \
  -H "token: $Token_Instance"

​
All with labels

Without labelIds or labelNames, returns every chat that has any label assigned. Useful to audit the overall use of labels on the account. 
curl -X GET "https://ryzeapi.cloud/api/chat/contactsByLabel/$Instance_Name" \
  -H "token: $Token_Instance"

​
Success response

chats is a list of ChatWithLabels objects grouping every label associated with each chat. Use total_chats for the number of unique chats and total_rows for the total number of chat-label pairs. refreshed indicates whether the cache was rebuilt in this call (refresh=true); filter_label_ids repeats the IDs effectively applied.
200 OK
{
  "success": true,
  "message": "Chats by label retrieved successfully",
  "chats": [
    {
      "chat_jid": "5511999999999@s.whatsapp.net",
      "labels": [
        { "id": "1", "name": "Important" }
      ]
    },
    {
      "chat_jid": "5511988887777@s.whatsapp.net",
      "labels": [
        { "id": "1", "name": "Important" },
        { "id": "2", "name": "VIP" }
      ]
    }
  ],
  "total_chats": 2,
  "total_rows": 3,
  "refreshed": false,
  "filter_label_ids": ["1"]
}

​
Path parameters

​
instance
string
required
Instance name.

​
Headers

NameRequiredExampleDescription
tokenyes (or Authorization)a1b2c3d4-...TokenAccount or TokenInstance.

​
Query params

​
labelIds
string
Label IDs separated by comma. Example: "1,2,3".
​
labelNames
string
Label names separated by comma (case-insensitive). Example: "VIP,Support".
​
refresh
boolean
default:"false"
If true, syncs labels with WhatsApp before returning.
Without labelIds or labelNames, returns every chat that has any label.

​
Error responses

HTTPerror.messageWhen it happens
400Instance name is requiredEmpty :instance.
401Invalid token,
404Instance not found,
503Instance is not connected to WhatsAppRequired when refresh=true.
Error 400
{
  "success": false,
  "error": { "message": "Instance name is required" }
}

List labels

Retrieve IDs and names to use in the filter.

Assign label

Add a label to a chat.