Pular para o conteúdo principal
GET
/
api
/
chat
/
contacts
/
:instance
Listar contatos
curl --request GET \
  --url https://api.example.com/api/chat/contacts/:instance
Auth: TokenAccount ou TokenInstance • Rate-limit: Global (100/min) • Idempotente: sim

​
Descrição

Retorna a lista de contatos sincronizados no ContactStore do WhatsMeow, são os contatos vindos da agenda do telefone principal: nome, push name, business name e telefone redacted. Se ?number= for fornecido, devolve um único contato. Caso o número não esteja na agenda, ainda assim a resposta é 200 OK com contact.found = false.
Operação de leitura pura sobre o store local, não gera tráfego no WhatsApp.

​
Exemplos

​
Listar todos

Sem query params, retorna todos os contatos sincronizados no ContactStore local da instância, com total indicando o tamanho da lista. 
curl -X GET "https://ryzeapi.cloud/api/chat/contacts/$Instance_Name" \
  -H "token: $Token_Instance"

​
Número específico

Filtra por ?number=5511999999999 (telefone internacional). Retorna o objeto contact único, com found=false quando o número não está na agenda sincronizada. 
curl -X GET "https://ryzeapi.cloud/api/chat/contacts/$Instance_Name?number=5511999999999" \
  -H "token: $Token_Instance"

​
JID completo

Aceita o JID inteiro em ?number=5511999999999@s.whatsapp.net quando você já possui o identificador completo (vindo de webhook ou outra resposta da API), evitando montar manualmente o sufixo. 
curl -X GET "https://ryzeapi.cloud/api/chat/contacts/$Instance_Name?number=5511999999999@s.whatsapp.net" \
  -H "token: $Token_Instance"

​
Resposta de sucesso

Sem ?number, retorna contacts (array) com todos os contatos sincronizados pela agenda + total. Com ?number=..., retorna apenas contact (objeto único). Cada item traz jid, lid (quando aplicável), os nomes disponíveis (first_name, full_name, push_name, business_name) e redacted_phone para casos em que só conhecemos o LID. O campo found indica se a entrada veio do store.
200 OK
{
  "success": true,
  "message": "Contacts retrieved successfully",
  "contacts": [
    {
      "jid": "5511999999999@s.whatsapp.net",
      "lid": "",
      "first_name": "João",
      "full_name": "João Silva",
      "push_name": "João",
      "business_name": "",
      "redacted_phone": "+55 11 ..... 9999",
      "found": true
    },
    {
      "jid": "5511888888888@s.whatsapp.net",
      "full_name": "Maria",
      "push_name": "Maria S.",
      "found": true
    }
  ],
  "total": 42
}

​
Parâmetros de rota

​
instance
string
obrigatório
Nome da instância (ex.: $Instance_Name).

​
Headers

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

​
Query params

​
number
string
Telefone internacional (5511999999999) ou JID (5511999999999@s.whatsapp.net, ...@lid). Se fornecido, retorna apenas este contato.

​
Notas e gotchas

  • found=false com push_name vazio e redacted_phone vazio normalmente significa que o número não tem WhatsApp ou nunca trocou mensagens com você.
  • business_name só é preenchido para contas WhatsApp Business verificadas.
  • Operações com mais de mil contatos podem demorar alguns segundos por causa do context.WithTimeout(30s) aplicado ao GetAllContacts.

​
Respostas de erro

HTTPerror.messageQuando ocorre
400Instance name is required:instance vazio.
401Invalid tokenVer Autenticação.
404Instance not foundInstância não existe na conta.
500WhatsApp client not found for instanceCliente desalocado.
500WhatsApp client is not connectedInstância desconectada.
500contact store not available (use a store that implements ContactStore, e.g. sqlstore)Store sem suporte.
500invalid number: <...>?number= malformado.
500failed to get contacts: <...> / failed to get contact: <...>Erro interno do WhatsMeow.
Erro 400
{
  "success": false,
  "error": { "message": "Instance name is required" }
}