Contatos por etiqueta

GET

api

chat

contactsByLabel

:instance

Contatos por etiqueta

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 ou TokenInstance • Rate-limit: Global (100/min) • Idempotente: sim

Descrição

Retorna chats que possuem ao menos uma das etiquetas informadas. Você pode filtrar por IDs, nomes (case-insensitive) ou retornar todos os chats que tenham qualquer etiqueta.

Use refresh=true para forçar uma sincronização com o WhatsApp antes de listar, útil quando uma etiqueta foi alterada no celular e você quer o dado mais recente.

Exemplos

Por IDs

Filtra os chats que possuem pelo menos uma das etiquetas listadas em ?labelIds=1,2. Útil quando você já conhece os IDs vindos de /tags-listar.

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)
}

Por nomes (com refresh)

Filtra por nome via ?labelNames=VIP,Suporte (case-insensitive) e adiciona refresh=true para forçar uma sincronização com o WhatsApp antes de listar, garantindo que mudanças feitas no celular já apareçam.

curl -X GET "https://ryzeapi.cloud/api/chat/contactsByLabel/$Instance_Name?labelNames=VIP,Suporte&refresh=true" \
  -H "token: $Token_Instance"

await fetch(`https://ryzeapi.cloud/api/chat/contactsByLabel/${process.env.Instance_Name}?labelNames=VIP,Suporte&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,Suporte&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,Suporte&refresh=true", nil)
    req.Header.Set("token", os.Getenv("Token_Instance"))
    http.DefaultClient.Do(req)
}

Todos com etiquetas

Sem labelIds nem labelNames, retorna todos os chats que tenham qualquer etiqueta atribuída. Útil para auditar o uso geral de labels na conta.

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)
}

Resposta de sucesso

chats é uma lista de objetos ChatWithLabels agrupando todas as etiquetas associadas a cada chat. Use total_chats para o número de chats únicos e total_rows para o total de pares chat-etiqueta. refreshed indica se o cache foi reconstruído nesta chamada (refresh=true); filter_label_ids repete os IDs efetivamente aplicados.

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"]
}

Parâmetros de rota

string

obrigatório

Nome da instância.

Headers

Nome	Obrigatório	Exemplo	Descrição
`token`	sim (ou `Authorization`)	`a1b2c3d4-...`	TokenAccount ou TokenInstance.

Query params

string

IDs de etiquetas separados por vírgula. Exemplo: "1,2,3".

string

Nomes de etiquetas separados por vírgula (case-insensitive). Exemplo: "VIP,Suporte".

boolean

padrão:"false"

Se true, sincroniza etiquetas com o WhatsApp antes de retornar.

Sem labelIds nem labelNames, retorna todos os chats que possuam qualquer etiqueta.

Respostas de erro

HTTP	`error.message`	Quando ocorre
400	`Instance name is required`	`:instance` vazio.
401	`Invalid token`	,
404	`Instance not found`	,
503	`Instance is not connected to WhatsApp`	Necessário para `refresh=true`.

Erro 400

{
  "success": false,
  "error": { "message": "Instance name is required" }
}

Introdução

Instância

Eventos

Mensagens

Chamadas

Grupos

Comunidades

Newsletter

Perfil

Chat

Chatwoot

Typebot

Observabilidade

Contatos por etiqueta

Descrição

Exemplos

Por IDs

Por nomes (com refresh)

Todos com etiquetas

Resposta de sucesso

Parâmetros de rota

Headers

Query params

Respostas de erro

Relacionados

Listar etiquetas

Atribuir etiqueta

​Descrição

​Exemplos

​Por IDs

​Por nomes (com refresh)

​Todos com etiquetas

​Resposta de sucesso

​Parâmetros de rota

​Headers

​Query params

​Respostas de erro

​Relacionados

Listar etiquetas

Atribuir etiqueta

Descrição

Exemplos

Por IDs

Por nomes (com refresh)

Todos com etiquetas

Resposta de sucesso

Parâmetros de rota

Headers

Query params

Respostas de erro

Relacionados