Saltar al contenido principal
GET
/
api
/
chat
/
contacts
/
:instance
Listar contactos
curl --request GET \
  --url https://api.example.com/api/chat/contacts/:instance
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"

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

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

​
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

​
instance
string
requerido
Nombre de la instancia (por ejemplo, $Instance_Name).

​
Cabeceras

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

​
Parámetros de consulta

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

HTTPerror.messageCuándo ocurre
400Instance name is required:instance vacío.
401Invalid tokenVer Autenticación.
404Instance not foundLa instancia no existe en la cuenta.
500WhatsApp client not found for instanceCliente desasignado.
500WhatsApp client is not connectedInstancia desconectada.
500contact store not available (use a store that implements ContactStore, e.g. sqlstore)Store no soportado.
500invalid number: <...>?number= malformado.
500failed to get contacts: <...> / failed to get contact: <...>Error interno de WhatsMeow.
Error 400
{
  "success": false,
  "error": { "message": "Instance name is required" }
}