Listar contactos

GET

api

chat

contacts

:instance

Listar contactos

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

const options = {method: 'GET'};

fetch('https://api.example.com/api/chat/contacts/: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 la lista de contactos sincronizados en el ContactStore de WhatsMeow, son los contactos provenientes de la agenda del teléfono principal: nombre, push name, nombre comercial y número telefónico parcialmente oculto. Si se proporciona ?number=, devuelve un solo contacto. Si el número no está en la agenda, la respuesta sigue siendo 200 OK con contact.found = false.

Operación de solo lectura contra el store local, no genera tráfico de WhatsApp.

Ejemplos

Listar todos

Sin parámetros de query, devuelve todos los contactos sincronizados en el ContactStore local de la instancia, con total indicando el tamaño de la lista.

curl -X GET "https://ryzeapi.cloud/api/chat/contacts/$Instance_Name" \
  -H "token: $Token_Instance"

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

import os, requests

requests.get(
    f"https://ryzeapi.cloud/api/chat/contacts/{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/contacts/"+os.Getenv("Instance_Name"), nil)
    req.Header.Set("token", os.Getenv("Token_Instance"))
    http.DefaultClient.Do(req)
}

Número específico

Filtra por ?number=5511999999999 (teléfono internacional). Devuelve el objeto contact único, con found=false cuando el número no está en la agenda sincronizada.

curl -X GET "https://ryzeapi.cloud/api/chat/contacts/$Instance_Name?number=5511999999999" \
  -H "token: $Token_Instance"

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

import os, requests

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

package main

import (
    "net/http"
    "os"
)

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

JID completo

Acepta el JID completo en ?number=5511999999999@s.whatsapp.net cuando ya tienes el identificador completo (de un webhook u otra respuesta de la API), evitando construir manualmente el sufijo.

curl -X GET "https://ryzeapi.cloud/api/chat/contacts/$Instance_Name?number=5511999999999@s.whatsapp.net" \
  -H "token: $Token_Instance"

await fetch(`https://ryzeapi.cloud/api/chat/contacts/${process.env.Instance_Name}?number=5511999999999@s.whatsapp.net`, {
  method: "GET",
  headers: {
    "token": process.env.Token_Instance
  }
});

import os, requests

requests.get(
    f"https://ryzeapi.cloud/api/chat/contacts/{os.environ['Instance_Name']}?number=5511999999999@s.whatsapp.net",
    headers={"token": os.environ["Token_Instance"]}
)

package main

import (
    "net/http"
    "os"
)

func main() {
    req, _ := http.NewRequest("GET", "https://ryzeapi.cloud/api/chat/contacts/"+os.Getenv("Instance_Name")+"?number=5511999999999@s.whatsapp.net", nil)
    req.Header.Set("token", os.Getenv("Token_Instance"))
    http.DefaultClient.Do(req)
}

Respuesta exitosa

Sin ?number, devuelve contacts (array) con todos los contactos sincronizados de la agenda + total. Con ?number=..., devuelve solo contact (un único objeto). Cada item lleva jid, lid (cuando aplica), los nombres disponibles (first_name, full_name, push_name, business_name) y redacted_phone para casos donde solo conocemos el LID. El campo found indica si la entrada provino del store.

200 OK

{
  "success": true,
  "message": "Contacts retrieved successfully",
  "contacts": [
    {
      "jid": "5511999999999@s.whatsapp.net",
      "lid": "",
      "first_name": "John",
      "full_name": "John Smith",
      "push_name": "John",
      "business_name": "",
      "redacted_phone": "+55 11 ..... 9999",
      "found": true
    },
    {
      "jid": "5511888888888@s.whatsapp.net",
      "full_name": "Mary",
      "push_name": "Mary S.",
      "found": true
    }
  ],
  "total": 42
}

Parámetros de ruta

string

requerido

Nombre de la instancia (por ejemplo, $Instance_Name).

Cabeceras

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

Parámetros de consulta

string

Teléfono internacional (5511999999999) o JID (5511999999999@s.whatsapp.net, ...@lid). Si se proporciona, devuelve solo este contacto.

Notas y precauciones

found=false con push_name vacío y redacted_phone vacío usualmente significa que el número no tiene WhatsApp o nunca intercambió mensajes contigo.
business_name solo se llena para cuentas verificadas de WhatsApp Business.
Las operaciones que involucran más de mil contactos pueden tardar algunos segundos por el context.WithTimeout(30s) aplicado a GetAllContacts.

Respuestas de error

HTTP	`error.message`	Cuándo ocurre
400	`Instance name is required`	`:instance` vacío.
401	`Invalid token`	Ver Autenticación.
404	`Instance not found`	La instancia no existe en la cuenta.
500	`WhatsApp client not found for instance`	Cliente desasignado.
500	`WhatsApp client is not connected`	Instancia desconectada.
500	`contact store not available (use a store that implements ContactStore, e.g. sqlstore)`	Store no soportado.
500	`invalid number: <...>`	`?number=` malformado.
500	`failed to get contacts: <...>` / `failed to get contact: <...>`	Error interno de WhatsMeow.

Error 400

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

Introducción

Instancia

Eventos

Mensajes

Llamadas

Grupos

Comunidades

Newsletter

Perfil

Chat

Chatwoot

Typebot

Observabilidad

Listar contactos

Descripción

Ejemplos

Listar todos

Número específico

JID completo

Respuesta exitosa

Parámetros de ruta

Cabeceras

Parámetros de consulta

Notas y precauciones

Respuestas de error

​Descripción

​Ejemplos

​Listar todos

​Número específico

​JID completo

​Respuesta exitosa

​Parámetros de ruta

​Cabeceras

​Parámetros de consulta

​Notas y precauciones

​Respuestas de error

Descripción

Ejemplos

Listar todos

Número específico

JID completo

Respuesta exitosa

Parámetros de ruta

Cabeceras

Parámetros de consulta

Notas y precauciones

Respuestas de error