Listar contatos

GET

api

chat

contacts

:instance

Listar contatos

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

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

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

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"

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

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

string

obrigatório

Nome da instância (ex.: $Instance_Name).

Headers

Nome	Obrigatório	Exemplo	Descrição
`token`	sim (ou `Authorization`)	`a1b2c3d4-...`	TokenAccount ou TokenInstance.

Query params

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

HTTP	`error.message`	Quando ocorre
400	`Instance name is required`	`:instance` vazio.
401	`Invalid token`	Ver Autenticação.
404	`Instance not found`	Instância não existe na conta.
500	`WhatsApp client not found for instance`	Cliente desalocado.
500	`WhatsApp client is not connected`	Instância desconectada.
500	`contact store not available (use a store that implements ContactStore, e.g. sqlstore)`	Store sem suporte.
500	`invalid number: <...>`	`?number=` malformado.
500	`failed to get contacts: <...>` / `failed to get contact: <...>`	Erro interno do WhatsMeow.

Erro 400

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

Introdução

Instância

Eventos

Mensagens

Chamadas

Grupos

Comunidades

Newsletter

Perfil

Chat

Chatwoot

Typebot

Observabilidade

Listar contatos

Descrição

Exemplos

Listar todos

Número específico

JID completo

Resposta de sucesso

Parâmetros de rota

Headers

Query params

Notas e gotchas

Respostas de erro

​Descrição

​Exemplos

​Listar todos

​Número específico

​JID completo

​Resposta de sucesso

​Parâmetros de rota

​Headers

​Query params

​Notas e gotchas

​Respostas de erro

Descrição

Exemplos

Listar todos

Número específico

JID completo

Resposta de sucesso

Parâmetros de rota

Headers

Query params

Notas e gotchas

Respostas de erro