Contactos por etiqueta

GET

api

chat

contactsByLabel

:instance

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

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

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

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"

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

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

string

requerido

Nombre de la instancia.

Cabeceras

Nombre	Requerido	Ejemplo	Descripción
`token`	sí (o `Authorization`)	`a1b2c3d4-...`	TokenAccount o TokenInstance.

Parámetros de consulta

string

IDs de etiquetas separados por coma. Ejemplo: "1,2,3".

string

Nombres de etiquetas separados por coma (sin distinguir mayúsculas/minúsculas). Ejemplo: "VIP,Support".

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

HTTP	`error.message`	Cuándo ocurre
400	`Instance name is required`	`:instance` vacío.
401	`Invalid token`	,
404	`Instance not found`	,
503	`Instance is not connected to WhatsApp`	Requerido cuando `refresh=true`.

Error 400

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

Introducción

Instancia

Eventos

Mensajes

Llamadas

Grupos

Comunidades

Newsletter

Perfil

Chat

Chatwoot

Typebot

Observabilidad

Contactos por etiqueta

Descripción

Ejemplos

Por IDs

Por nombres (con refresh)

Todos los que tienen etiquetas

Respuesta exitosa

Parámetros de ruta

Cabeceras

Parámetros de consulta

Respuestas de error

Relacionados

Listar etiquetas

Asignar etiqueta

​Descripción

​Ejemplos

​Por IDs

​Por nombres (con refresh)

​Todos los que tienen etiquetas

​Respuesta exitosa

​Parámetros de ruta

​Cabeceras

​Parámetros de consulta

​Respuestas de error

​Relacionados

Listar etiquetas

Asignar etiqueta

Descripción

Ejemplos

Por IDs

Por nombres (con refresh)

Todos los que tienen etiquetas

Respuesta exitosa

Parámetros de ruta

Cabeceras

Parámetros de consulta

Respuestas de error

Relacionados