Pular para o conteúdo principal
GET
/
api
/
chat
/
contactsByLabel
/
:instance
Contatos por etiqueta
curl --request GET \
  --url https://api.example.com/api/chat/contactsByLabel/:instance
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"

​
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"

​
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"

​
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

​
instance
string
obrigatório
Nome da instância.

​
Headers

NomeObrigatórioExemploDescrição
tokensim (ou Authorization)a1b2c3d4-...TokenAccount ou TokenInstance.

​
Query params

​
labelIds
string
IDs de etiquetas separados por vírgula. Exemplo: "1,2,3".
​
labelNames
string
Nomes de etiquetas separados por vírgula (case-insensitive). Exemplo: "VIP,Suporte".
​
refresh
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

HTTPerror.messageQuando ocorre
400Instance name is required:instance vazio.
401Invalid token,
404Instance not found,
503Instance is not connected to WhatsAppNecessário para refresh=true.
Erro 400
{
  "success": false,
  "error": { "message": "Instance name is required" }
}

​
Relacionados

Listar etiquetas

Recuperar IDs e nomes para usar no filtro.

Atribuir etiqueta

Adicionar uma etiqueta a um chat.