Saltar al contenido principal
GET
/
api
/
chat
/
contactsByLabel
/
:instance
Contactos por etiqueta
curl --request GET \
  --url https://api.example.com/api/chat/contactsByLabel/:instance
Auth: TokenAccount o TokenInstance • Rate-limit: Global (100/min) • Idempotente: sí

​
Descripción

Devuelve los chats que tienen al menos una de las etiquetas indicadas. Puedes filtrar por IDs, por nombres (no distingue mayúsculas/minúsculas) o devolver todos los chats que tengan alguna etiqueta.
Usa refresh=true para forzar una sincronización con WhatsApp antes de listar, útil cuando una etiqueta fue cambiada en el teléfono y quieres los datos más recientes.

​
Ejemplos

​
Por IDs

Filtra los chats que tienen al menos una de las etiquetas listadas en ?labelIds=1,2. Útil cuando ya conoces los IDs desde /tags-list. 
curl -X GET "https://ryzeapi.cloud/api/chat/contactsByLabel/$Instance_Name?labelIds=1,2" \
  -H "token: $Token_Instance"

​
Por nombres (con refresh)

Filtra por nombre vía ?labelNames=VIP,Support (no distingue mayúsculas/minúsculas) y agrega refresh=true para forzar una sincronización con WhatsApp antes de listar, asegurando que los cambios hechos en el teléfono ya sean visibles. 
curl -X GET "https://ryzeapi.cloud/api/chat/contactsByLabel/$Instance_Name?labelNames=VIP,Support&refresh=true" \
  -H "token: $Token_Instance"

​
Todos los que tienen etiquetas

Sin labelIds ni labelNames, devuelve todos los chats que tienen alguna etiqueta asignada. Útil para auditar el uso general de etiquetas en la cuenta. 
curl -X GET "https://ryzeapi.cloud/api/chat/contactsByLabel/$Instance_Name" \
  -H "token: $Token_Instance"

​
Respuesta exitosa

chats es una lista de objetos ChatWithLabels agrupando todas las etiquetas asociadas a cada chat. Usa total_chats para la cantidad de chats únicos y total_rows para el total de pares chat-etiqueta. refreshed indica si la caché fue reconstruida en esta llamada (refresh=true); filter_label_ids repite los IDs efectivamente 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 ruta

​
instance
string
requerido
Nombre de la instancia.

​
Cabeceras

NombreRequeridoEjemploDescripción
tokensí (o Authorization)a1b2c3d4-...TokenAccount o TokenInstance.

​
Parámetros de consulta

​
labelIds
string
IDs de etiquetas separados por coma. Ejemplo: "1,2,3".
​
labelNames
string
Nombres de etiquetas separados por coma (sin distinguir mayúsculas/minúsculas). Ejemplo: "VIP,Support".
​
refresh
boolean
predeterminado:"false"
Si es true, sincroniza las etiquetas con WhatsApp antes de devolver.
Sin labelIds ni labelNames, devuelve todos los chats que tienen alguna etiqueta.

​
Respuestas de error

HTTPerror.messageCuándo ocurre
400Instance name is required:instance vacío.
401Invalid token,
404Instance not found,
503Instance is not connected to WhatsAppRequerido cuando refresh=true.
Error 400
{
  "success": false,
  "error": { "message": "Instance name is required" }
}

​
Relacionados

Listar etiquetas

Recupera IDs y nombres para usar en el filtro.

Asignar etiqueta

Agrega una etiqueta a un chat.