Contacts by label

GET

api

chat

contactsByLabel

:instance

Contacts by label

curl --request GET \
  --url https://api.example.com/api/chat/contactsByLabel/:instance

const options = {method: 'GET'};

fetch('https://api.example.com/api/chat/contactsByLabel/:instance', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

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"

await fetch(`https://ryzeapi.cloud/api/chat/contactsByLabel/${process.env.Instance_Name}?labelIds=1,2`, {
  method: "GET",
  headers: {
    "token": process.env.Token_Instance
  }
});

import os, requests

requests.get(
    f"https://ryzeapi.cloud/api/chat/contactsByLabel/{os.environ['Instance_Name']}?labelIds=1,2",
    headers={"token": os.environ["Token_Instance"]}
)

package main

import (
    "net/http"
    "os"
)

func main() {
    req, _ := http.NewRequest("GET", "https://ryzeapi.cloud/api/chat/contactsByLabel/"+os.Getenv("Instance_Name")+"?labelIds=1,2", nil)
    req.Header.Set("token", os.Getenv("Token_Instance"))
    http.DefaultClient.Do(req)
}

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"

await fetch(`https://ryzeapi.cloud/api/chat/contactsByLabel/${process.env.Instance_Name}?labelNames=VIP,Support&refresh=true`, {
  method: "GET",
  headers: {
    "token": process.env.Token_Instance
  }
});

import os, requests

requests.get(
    f"https://ryzeapi.cloud/api/chat/contactsByLabel/{os.environ['Instance_Name']}?labelNames=VIP,Support&refresh=true",
    headers={"token": os.environ["Token_Instance"]}
)

package main

import (
    "net/http"
    "os"
)

func main() {
    req, _ := http.NewRequest("GET", "https://ryzeapi.cloud/api/chat/contactsByLabel/"+os.Getenv("Instance_Name")+"?labelNames=VIP,Support&refresh=true", nil)
    req.Header.Set("token", os.Getenv("Token_Instance"))
    http.DefaultClient.Do(req)
}

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"

await fetch(`https://ryzeapi.cloud/api/chat/contactsByLabel/${process.env.Instance_Name}`, {
  method: "GET",
  headers: {
    "token": process.env.Token_Instance
  }
});

import os, requests

requests.get(
    f"https://ryzeapi.cloud/api/chat/contactsByLabel/{os.environ['Instance_Name']}",
    headers={"token": os.environ["Token_Instance"]}
)

package main

import (
    "net/http"
    "os"
)

func main() {
    req, _ := http.NewRequest("GET", "https://ryzeapi.cloud/api/chat/contactsByLabel/"+os.Getenv("Instance_Name"), nil)
    req.Header.Set("token", os.Getenv("Token_Instance"))
    http.DefaultClient.Do(req)
}

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

string

required

Instance name.

Headers

Name	Required	Example	Description
`token`	yes (or `Authorization`)	`a1b2c3d4-...`	TokenAccount or TokenInstance.

Query params

string

Label IDs separated by comma. Example: "1,2,3".

string

Label names separated by comma (case-insensitive). Example: "VIP,Support".

boolean

default:"false"

If true, syncs labels with WhatsApp before returning.

Without labelIds or labelNames, returns every chat that has any label.

Error responses

HTTP	`error.message`	When it happens
400	`Instance name is required`	Empty `:instance`.
401	`Invalid token`	,
404	`Instance not found`	,
503	`Instance is not connected to WhatsApp`	Required 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.

Introduction

Instance

Events

Messages

Calls

Groups

Communities

Newsletter

Profile

Chat

Chatwoot

Typebot

Observability

Contacts by label

Description

Examples

By IDs

By names (with refresh)

All with labels

Success response

Path parameters

Headers

Query params

Error responses

List labels

Assign label

​Description

​Examples

​By IDs

​By names (with refresh)

​All with labels

​Success response

​Path parameters

​Headers

​Query params

​Error responses

​Related

List labels

Assign label

Description

Examples

By IDs

By names (with refresh)

All with labels

Success response

Path parameters

Headers

Query params

Error responses

Related