11. Contatos#
GET/v1/instances/{instanceId}/contacts#
Lista a agenda de contatos da instância: uma entrada por pessoa, com telefone e nomes.
| Campo | Descrição |
|---|---|
jid |
JID do contato (<número>@s.whatsapp.net; um …@lid quando o WhatsApp não informou o número) |
phone |
Número (só dígitos). Ausente para um @lid cujo número o WhatsApp não informou — limitação do próprio WhatsApp |
lid |
LID do contato (…@lid), quando conhecido (wwebjs) |
full_name / first_name |
Nome salvo na agenda do celular pareado |
push_name |
Nome de perfil que o contato definiu no WhatsApp |
business_name |
Nome verificado, para contas business |
in_address_book |
true quando o número está salvo na agenda do celular (wwebjs). Ausente quando false |
international |
true quando o número não é do Brasil (+55) |
Provider wwebjs (WhatsApp Web): a lista vem da agenda que a própria página do WhatsApp Web já tem em memória — leitura local, sem consulta aos servidores da Meta. O WhatsApp guarda cada pessoa duas vezes (por número e por
@lid); a API devolve uma entrada só. A lista é montada no máximo uma vez por minuto (cache), então contatos novos podem levar até 1 min para aparecer. Exige a instância conectada (409 INSTANCE_NOT_CONNECTEDcaso contrário). Raramente (~0,3% na medição de staging) um@lidcujo número o WhatsApp não informou aparece como entrada separada do mesmo contato. A lista de chats (GET .../chats) não usa esta agenda no wwebjs: continua vindo do histórico de conversas.
Auth: Todos autenticados
Query Parameters:
| Parametro | Tipo | Padrão | Descricao |
|---|---|---|---|
page |
int | 1 | Página |
limit |
int | 20 | Itens por página (max 100) |
Resposta 200:
{
"data": [
{
"jid": "554137984905@s.whatsapp.net",
"phone": "554137984905",
"lid": "123456789012345@lid",
"push_name": "Joao",
"business_name": "",
"full_name": "Joao Silva",
"first_name": "Joao",
"in_address_book": true,
"international": false,
"profile_pic_url": "https://media.catcher.one/.../avatars/554137984905.jpg"
}
],
"total": 15,
"page": 1,
"limit": 20
}
Nota sobre
profile_pic_url: Presente somente quando o avatar do contato já foi cacheado no storage da Catcher. Contatos sem foto ou com foto ainda não cacheada não incluem este campo. O cache e preenchido automaticamente quando o contato muda a foto (events.Picture) ou via lazy load no primeiro acesso ao endpoint/avatar.
PUT/v1/instances/{instanceId}/contacts/{phone}#
Salva um contato na agenda do WhatsApp da instância, ou renomeia um contato que
já está salvo. É o mesmo que abrir "Salvar contato" / "Editar contato" no
WhatsApp Web e confirmar: o nome passa a aparecer na lista de conversas, no
cabeçalho do chat e, com sync_to_phone, na agenda do celular pareado.
Disponível só no provider wwebjs. Os outros respondem 501 CONTACT_SAVE_NOT_SUPPORTED.
Auth: Todos autenticados
{phone} é o número com DDI (10 a 15 dígitos). Aceita separadores (+55 (41) 3798-4905, codificado na URL) ou um JID de telefone (…@s.whatsapp.net). Um @lid ou um grupo é recusado com 400 INVALID_PHONE: a agenda é por número.
Body:
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
first_name |
string | sim | Nome (até 64 caracteres) |
last_name |
string | não | Sobrenome (até 64 caracteres) |
sync_to_phone |
bool | não | Gravar também na agenda do celular pareado. Padrão true, como a caixa marcada do WhatsApp Web |
{ "first_name": "Ana", "last_name": "Souza" }
Resposta 200:
{
"instance_id": "9c8ffc46-91cf-458b-b9cd-4f94eaa9003a",
"phone": "554137984905",
"jid": "554137984905@s.whatsapp.net",
"full_name": "Ana Souza",
"existed": true,
"unchanged": false
}
-
existed: o número já estava salvo (renomeação) ou não (contato novo). -
unchanged: o nome já era esse. A ação de salvar não é chamada e nenhum evento é emitido (a consulta de existência do número acontece mesmo assim). -
phonepode vir diferente do enviado em celulares BR (variante do 9º dígito,55DD9XXXXXXXX↔55DDXXXXXXXX), e é o número que ficou salvo:- se a agenda já tem a pessoa salva na outra forma, essa entrada é renomeada (não se cria um segundo contato);
- se o número exato não tem WhatsApp, o worker tenta a outra forma e salva a que existe.
Guarde o
phoneda resposta no CRM: é a forma que a agenda usa.
Como é feito: como uma pessoa no WhatsApp Web. O worker abre a gaveta
"Editar contato" do jeito que o próprio WhatsApp Web abre (pela lista de conversas
ou pela busca de nova conversa, sem abrir a conversa), digita o nome no ritmo de
quem digita, deixa "Sincronizar contato com celular" como sync_to_phone pede e
clica em Salvar contato. A gaveta faz a própria checagem do número ao abrir e
registra a mesma telemetria de uma edição feita à mão. Se a gaveta não puder ser
usada antes do clique, o worker chama a ação de salvar da página com os mesmos
argumentos da gaveta; depois do clique nunca há segunda tentativa.
A rota é para edição feita por uma pessoa (um
operador mudando o nome no CRM), não para sincronizar uma lista inteira. Por
instância, salvar e apagar contam juntos: 15 s entre alterações da agenda,
até 5 a cada 10 minutos e 30 por hora. Acima
disso a chamada é recusada na hora com 429. Nomes com
caracteres de controle ou de direção de texto são recusados (400). Cada tentativa
fica no log de auditoria (contact.save, com o token que chamou; o nome não é
gravado no log).
Depois do salvamento a instância emite contact.saved_sent, e o próximo GET .../contacts
já mostra o nome novo (o salvamento descarta o cache da agenda).
Erros:
| HTTP | error_code |
Quando |
|---|---|---|
400 |
INVALID_PHONE |
{phone} não é um número de telefone |
400 |
INVALID_JSON / MISSING_FIELD / BAD_REQUEST |
Corpo inválido, first_name ausente, nome longo demais ou com caracteres de controle |
404 |
INSTANCE_NOT_FOUND |
Instância inexistente ou de outra conta |
404 |
CONTACT_NOT_ON_WHATSAPP |
O número (e a variante do 9º dígito) não tem WhatsApp |
409 |
INSTANCE_NOT_CONNECTED |
Instância desconectada |
429 |
RATE_LIMITED |
Menos de 15 s desde a última alteração da agenda (salvar ou apagar), ou mais de 5 em 10 min / 30 em 1 h nesta instância. Retry-After = 15, 600 ou 3600 conforme o limite |
501 |
CONTACT_SAVE_NOT_SUPPORTED |
Provider sem escrita de agenda (não-wwebjs) |
502 |
CONTACT_SAVE_FAILED |
A página do WhatsApp Web não concluiu o salvamento no tempo. O contato pode ter sido salvo mesmo assim (sem contact.saved_sent); repetir a chamada é seguro e responde unchanged: true se já estiver salvo |
DELETE/v1/instances/{instanceId}/contacts/{phone}#
Apaga um contato da agenda do WhatsApp da instância. É o mesmo que abrir "Editar contato" no WhatsApp Web, tocar em Apagar contato e confirmar em Apagar: o contato sai da agenda do WhatsApp e, se estava sincronizado, da agenda do celular pareado. A conversa e as mensagens continuam; só o nome salvo deixa de existir (a lista volta a mostrar o número ou o nome de perfil).
Disponível só no provider wwebjs. Os outros respondem 501 CONTACT_DELETE_NOT_SUPPORTED.
Auth: Todos autenticados
{phone} segue as mesmas regras do PUT (número com DDI ou JID de telefone; @lid e grupos são recusados). Sem corpo.
Só o número exatamente pedido é apagado, e só se estiver salvo. Em celulares
BR, se a agenda tem a pessoa salva só na outra forma do 9º dígito, nada é
apagado: a resposta é 404 CONTACT_NOT_SAVED com saved_as dizendo a forma que
está salva — para apagá-la, chame o DELETE com esse número. Assim repetir a
chamada é sempre seguro (a segunda devolve 404), e um DELETE nunca apaga uma
entrada diferente da pedida.
Resposta 200:
{
"instance_id": "9c8ffc46-91cf-458b-b9cd-4f94eaa9003a",
"phone": "554137984905",
"jid": "554137984905@s.whatsapp.net",
"deleted": true
}
Como é feito: o worker abre a mesma gaveta "Editar contato" (sem abrir a
conversa), clica em Apagar contato, espera a confirmação e clica em
Apagar, como uma pessoa. Se a gaveta não puder ser usada antes do clique, o
worker roda o mesmo apagar da gaveta pela página (a checagem do número e a ação de
apagar); depois do clique nunca há segunda tentativa. Divide a cadência com o
PUT (15 s entre alterações da agenda, 5 a cada 10 minutos, 30 por hora). Cada
tentativa fica no log de auditoria (contact.delete, com o token que chamou).
Depois de apagar a instância emite contact.deleted_sent, e o próximo
GET .../contacts já não traz o contato.
Erros:
| HTTP | error_code |
Quando |
|---|---|---|
400 |
INVALID_PHONE |
{phone} não é um número de telefone |
404 |
INSTANCE_NOT_FOUND |
Instância inexistente ou de outra conta |
404 |
CONTACT_NOT_SAVED |
O número pedido não está salvo na agenda. Nada foi feito. Se a outra forma do 9º dígito está salva, vem em saved_as (ex.: "saved_as": "554196332719") |
404 |
CONTACT_NOT_ON_WHATSAPP |
O número salvo não tem mais WhatsApp; o WhatsApp Web também não apaga nesse caso |
409 |
INSTANCE_NOT_CONNECTED |
Instância desconectada |
429 |
RATE_LIMITED |
Cadência da agenda (salvar e apagar juntos). Retry-After = 15, 600 ou 3600 |
501 |
CONTACT_DELETE_NOT_SUPPORTED |
Provider sem escrita de agenda (não-wwebjs) |
502 |
CONTACT_DELETE_FAILED |
O WhatsApp Web não confirmou que apagou. O contato pode ter sido apagado mesmo assim (sem contact.deleted_sent); repetir é seguro — só o número pedido pode ser apagado, e se ele já saiu a resposta é 404 CONTACT_NOT_SAVED |
GET/v1/instances/{instanceId}/contacts/{contactId}#
Retorna informações de um contato. A resposta vem do banco do Catcher (registro persistente) e opcionalmente e enriquecida com dados ao vivo do WhatsApp (status, avatar atualizado). O endpoint funciona mesmo se a instância estiver desconectada — retorna o último estado conhecido.
Auth: Todos autenticados
Parametros de URL:
| Parametro | Descricao |
|---|---|
instanceId |
ID da instância |
contactId |
Telefone (E.164, com ou sem +), phone JID (554199...@s.whatsapp.net), ou LID (2162...@lid). BR com 9 extra e normalizado automaticamente |
Query params:
| Parametro | Tipo | Padrão | Descricao |
|---|---|---|---|
live |
bool | true |
false desabilita o enrichment com chamada ao WhatsApp (retorna so o estado do banco). Use quando quiser resposta rápida e offline-safe |
Resposta 200:
{
"id": 42,
"jid": "554137984905@s.whatsapp.net",
"phone": "554137984905",
"push_name": "Joao Silva",
"business_name": "",
"full_name": "Joao Silva",
"first_name": "Joao",
"status": "Hey there!",
"about": "Busy",
"picture_id": "122207890",
"picture_url": "https://media.catcher.one/.../avatars/554137984905.jpg",
"international": false,
"first_seen_at": "2026-03-01T12:00:00Z",
"last_seen_at": "2026-04-17T15:30:00Z",
"created_at": "2026-03-01T12:00:00Z",
"updated_at": "2026-04-17T15:30:00Z",
"identities": [
{
"jid": "554137984905@s.whatsapp.net",
"type": "phone",
"first_seen_at": "2026-03-01T12:00:00Z",
"last_seen_at": "2026-04-17T15:30:00Z"
},
{
"jid": "216251804708983@lid",
"type": "lid",
"first_seen_at": "2026-03-15T08:00:00Z",
"last_seen_at": "2026-04-17T15:30:00Z"
}
]
}
Campos da resposta:
| Campo | Tipo | Descricao |
|---|---|---|
id |
int | ID interno do registro (não persistente entre ambientes) |
jid |
string | Phone JID canonico (<phone>@s.whatsapp.net) |
phone |
string | Número sem sufixo (E.164 sem +) |
push_name / business_name / full_name / first_name |
string | Nomes do contato. push_name/business_name/about vem do banco; full_name e first_name são preenchidos apenas com live=true e instância conectada |
status |
string | Status/about ao vivo (apenas com live=true e instância conectada) |
about |
string | About salvo no banco (persistido de eventos UserAbout) |
picture_url |
string | URL do avatar — sempre controlada pela Catcher (S3/R2 público ou endpoint autenticado /avatar). Nunca e URL direta do CDN do WhatsApp |
first_seen_at / last_seen_at |
datetime | Primeira e última interacao conhecida |
identities[] |
array | Todas as variantes conhecidas de JID/LID para este contato. type=phone ou type=lid. Util para consumidores que recebem webhooks com diferentes JIDs e precisam de-duplicar (lesson #5 — WhatsApp não resolve LID→phone ao vivo, so via registry) |
Nota: Quando
live=truee a instância está conectada, o endpoint enriquece a resposta com dados atualizados do WhatsApp (status, nomes, avatar). Quandolive=falseou a instância está desconectada, retorna so o que o Catcher persistiu — resposta sempre disponível.
Nota (politica de proxy — lesson #29):
picture_urlretorna somente URL controlada pela Catcher. Se o avatar ainda não foi cacheado pelo worker (baixado através do proxy ISP da instância e armazenado no S3/R2), o campo não vem na resposta. A API nunca expoe URL temporaria do CDN do WhatsApp pro frontend — fazer isso delegaria o bypass do proxy ao navegador do cliente.
Erros:
| Status | Descricao |
|---|---|
| 200 | Contato encontrado OU identities[] vazio (ainda sem interacao com esse número). Sempre 200 pra permitir o consumidor guardar o JID mesmo antes da primeira mensagem |
GET/v1/instances/{instanceId}/contacts/engagement#
Lista de contatos rica com dados de engajamento — a listagem renderizada na tela /contacts da Console. Combina, numa única query, contacts (nome de exibição + avatar), contact_mutuality_caches (flag mutuo), contact_temperatures (contadores de engajamento) e contagens agregadas de mensagens.
Auth: Todos autenticados
Query Parameters:
| Parametro | Tipo | Padrão | Descricao |
|---|---|---|---|
search |
string | — | Substring (case-insensitive) contra nome OU telefone |
tier |
string | — | Filtra por tier: cold, warm, engaged, hot, very_hot |
mutual |
string | — | yes ou no (omita para ambos) |
page |
int | 1 | Página (1-based) |
limit |
int | 50 | Tamanho da página (max 200) |
Resposta 200:
{
"items": [
{
"phone": "554199999999",
"remote_jid": "554199999999@s.whatsapp.net",
"name": "Joao Silva",
"push_name": "Joao",
"business_name": "",
"is_group": false,
"has_avatar": true,
"profile_pic_url": "https://media.catcher.one/.../avatars/554199999999.jpg",
"is_mutual": true,
"inbound_total": 12,
"outbound_total": 5,
"outbound_consecutive": 1,
"score": 65,
"tier": "hot",
"max_consecutive": 5,
"last_inbound_at": "2026-05-07T13:42:11Z",
"last_outbound_at": "2026-05-07T14:01:00Z"
}
],
"total": 1234,
"page": 1,
"limit": 50
}
| Campo | Tipo | Descricao |
|---|---|---|
phone |
string | Número normalizado (sem sufixo) |
remote_jid |
string | JID da conversa (<phone>@s.whatsapp.net ou <id>@g.us) |
name |
string | Nome de exibição (push_name > business_name > phone) |
push_name / business_name |
string | Nomes do contato |
is_group |
bool | true se o remote_jid e um grupo |
has_avatar |
bool | true se ha avatar cacheado |
profile_pic_url |
string | URL do avatar (controlada pela Catcher) ou vazia |
is_mutual |
bool | null | true/false quando ha cache de mutualidade; null se ainda não verificado |
inbound_total / outbound_total |
int | Total de mensagens recebidas / enviadas |
outbound_consecutive |
int | Outbounds desde o último inbound |
score |
int | Score de temperatura 0-100 |
tier |
string | cold | warm | engaged | hot | very_hot |
max_consecutive |
int | Limite de outbound consecutivo derivado do tier |
last_inbound_at / last_outbound_at |
RFC3339 | null | Timestamps do último inbound/outbound |
Ordenacao primaria:
last_inbound_at DESC. Os filtrostier,mutualesearchsão aplicados pos-computo do score.
GET/v1/instances/{instanceId}/contacts/{contactId}/avatar#
Retorna a imagem de avatar do contato diretamente (proxy via S3/R2). Na primeira requisição para um contato sem cache, busca a foto do WhatsApp, armazena no storage, e retorna a imagem.
Auth: Todos autenticados (JWT ou API Key)
Headers de resposta:
Content-Type: image/jpeg(ou outro tipo conforme a imagem)Cache-Control: public, max-age=86400
Resposta 200: Imagem binaria (JPEG/PNG).
Resposta 404: Contato não encontrado ou sem foto de perfil.
Resposta 503: Storage S3/R2 não configurado.
Comportamento de cache:
- Primeiro acesso: busca a foto do WhatsApp, faz upload no S3/R2, e retorna a imagem (lazy cache).
- Acessos seguintes: serve diretamente do S3/R2 (rápido, sem depender do WhatsApp).
- Mudanca de foto: quando o WhatsApp notifica via
events.Picture, o cache e atualizado automaticamente em background. - Remoção de foto: quando o contato remove a foto, o cache e limpo e o endpoint passa a retornar 404.
Dica para clientes: Use
profile_pic_urlretornado nos endpointsGET /chats,GET /contacts, ouGET /contacts/{id}comosrcde tags<img>. Estas URLs nunca expiram (diferente das URLs do CDN do WhatsApp). SeS3_PUBLIC_URLestiver configurado no servidor, a URL e pública e pode ser usada diretamente; caso contrario, a URL aponta para o endpoint proxy/avatarque requer autenticação.
GET/v1/instances/{instanceId}/contacts/{contactId}/mutuality#
Retorna se phone (URL param contactId) tem essa instância salva na agenda do WhatsApp dele — i.e. são contatos mutuos. Resposta cacheada por 6h via contact_mutuality_cache (tenant). Cache miss dispara um client.IsOnWhatsApp (uSync) através do worker.
Auth: Todos autenticados (JWT ou API Key)
Resposta 200:
{
"is_mutual": true,
"checked_at": "2026-05-06T15:00:00Z",
"phone": "5511999999999"
}
| Campo | Tipo | Descricao |
|---|---|---|
is_mutual |
bool | true quando o servidor da Meta confirma que o número tem essa instância na agenda |
checked_at |
RFC3339 | Quando o resultado foi obtido (cache hit OU uSync). Use para mostrar "verificado ha N min" |
phone |
string | Número normalizado (sem +, sem sufixo @) |
Resposta 503: Instância não conectada ou worker indisponível.
Notas:
- O
contactIdaceita formato puro (5511999999999), com+(+5511999999999), ou JID completo (5511999999999@s.whatsapp.net). Tudo e normalizado para o número limpo. - Cache hit dentro de 6h retorna sem roundtrip.
- Cache stale + uSync com falha retorna o último valor conhecido (graceful fallback).
- Apenas o
info.IsInflag do whatsmeow (a contraparte dois_in_address_bookda Meta).
Temperatura de Contato (Anti-Spam)#
Score de engajamento 0-100 por contato, usado internamente para limitar mensagens outbound consecutivas sem reply inbound (regra de temperatura do anti-spam guard). O score combina um componente lifetime durável (histórico que não decai com o tempo) + recência + penalty por outbound consecutivo + boost de mutualidade:
- Lifetime: +20 se já respondeu alguma vez; +5 por inbound (cap 10 = +50); +10 se inbound ≥ 30 (relação estabelecida); +10 se inbound ≥ 100 (relação forte). Cap lifetime = 90.
- Recência: +30 se último reply < 7d, +15 < 30d, +5 < 90d.
- Penalty (outbound consecutivo sem reply, cap 5): −5 por consecutivo (normal); contato estabelecido (inbound ≥ 30) é penalizado de leve, −2 por consecutivo. Isso evita que 2-3 mensagens sem resposta derrubem um contato com centenas de trocas reais.
- Mutualidade: +15 se o contato te tem salvo.
Por isso uma conta WhatsApp com bom histórico permanece quente mesmo após um período quieto — o lifetime é um piso durável.
Tiers (curva fixa — recalibrada 2026-05-25, ≈ dobrada):
cold(0-19) —max_consecutive=3warm(20-39) —max_consecutive=5engaged(40-59) —max_consecutive=7hot(60-79) —max_consecutive=10very_hot(80-100) —max_consecutive=15
max_consecutive e o limite de envios outbound seguidos sem reply do contato; quando atingido, o próximo envio retorna 409 BLOCKED_TEMPERATURE_LIMIT — só com contact_limit_mode=temperature na instância (opcional, default off); com o modo desligado o score e só informativo. Bypass via header X-Force-Send: true (audit-logged).
GET/v1/instances/{instanceId}/contacts/{phone}/temperature#
Retorna o score de temperatura corrente para um contato. Bootstraps a linha do contact_temperatures a partir do histórico em messages na primeira chamada (lazy).
Auth: Todos autenticados (JWT ou API Key)
Resposta 200:
{
"phone": "554199999999",
"remote_jid": "554199999999@s.whatsapp.net",
"score": 65,
"tier": "hot",
"max_consecutive": 5,
"inbound_count_total": 8,
"outbound_consecutive": 1,
"last_inbound_at": "2026-05-07T13:42:11Z",
"last_outbound_at": "2026-05-07T14:01:00Z",
"bootstrap_source": "history",
"bootstrapped_at": "2026-04-30T08:15:22Z"
}
| Campo | Tipo | Descricao |
|---|---|---|
phone |
string | Número normalizado |
remote_jid |
string | JID canonico <phone>@s.whatsapp.net |
score |
int | 0-100, computado em runtime a partir dos contadores persistidos |
tier |
string | cold | warm | engaged | hot | very_hot |
max_consecutive |
int | Limite de outbound consecutivo derivado do tier |
inbound_count_total |
int | Total de inbounds na vida do contato |
outbound_consecutive |
int | Outbounds desde o último inbound |
last_inbound_at |
RFC3339 | null | Último inbound recebido |
last_outbound_at |
RFC3339 | null | Último outbound enviado |
bootstrap_source |
string | history | mutuality | cold | manual — evidência usada no bootstrap |
bootstrapped_at |
RFC3339 | null | Quando a linha foi seeded |
Notas:
phoneaceita5511999999999,+5511999999999, ou JID completo. Normalizado.- A mutualidade NÃO e consultada nesta leitura (evita RPC). O score-time mutuality boost so atua via send-path Check.
- Bootstrap pode levar centenas de ms na primeira chamada para um contato com histórico denso (4 queries indexadas em
messages); leituras subsequentes são baratas.
GET/v1/instances/{instanceId}/contacts/temperature#
Lista contatos paginada, filtravel por faixa de score.
Auth: Todos autenticados
Query params:
| Param | Default | Descricao |
|---|---|---|
min_score |
0 | Score mínimo (0-100) |
max_score |
100 | Score máximo (0-100) |
page |
1 | Página (1-based) |
limit |
50 | Tamanho da página (max 200) |
Resposta 200:
{
"items": [
{
"phone": "554199999999",
"remote_jid": "554199999999@s.whatsapp.net",
"score": 65,
"tier": "hot",
"max_consecutive": 5,
"inbound_count_total": 8,
"outbound_consecutive": 1,
"last_inbound_at": "2026-05-07T13:42:11Z",
"last_outbound_at": "2026-05-07T14:01:00Z",
"bootstrap_source": "history",
"bootstrapped_at": "2026-04-30T08:15:22Z"
}
],
"total": 1234,
"page": 1,
"limit": 50
}
Notas:
- Score e calculado em-app a partir de cada linha — para tenants com >100k contatos, considere o filtro do
min_score/max_scorepara reduzir o conjunto antes de paginar. - Ordenacao primaria:
last_inbound_at DESC(contatos mais recentes primeiro).
GET/v1/instances/{instanceId}/profile/avatar#
Retorna a foto de perfil da própria instância conectada. O fluxo é identico ao avatar de contato: a Catcher busca a imagem via worker/whatsmeow, armazena no S3/R2 e expõe apenas URL/local proxy controlado pela plataforma.
Auth: Todos autenticados (JWT ou API Key)
Headers de resposta:
Content-Type: image/jpeg(ou outro tipo conforme a imagem)Cache-Control: public, max-age=86400
Resposta 200: Imagem binaria (JPEG/PNG).
Resposta 404: Instância sem foto de perfil.
Resposta 503: Storage S3/R2 não configurado.
POST/v1/instances/{instanceId}/contacts/{contactId}/presence/subscribe#
Inicia ou renova o monitoramento de presença de um contato 1:1.
Auth: Todos autenticados
Aceita telefone ou JID. Números BR com 9 extra são normalizados automaticamente. Não aceita grupos (
@g.us).
Use este endpoint ao abrir a tela do chat. Ele renova uma lease transiente de monitoramento por 300s. Chamadas repetidas durante a lease são idempotentes e apenas renovam o TTL local.
Resposta 200:
{
"instance_id": "84c2e480-...",
"contact_jid": "551199999999@s.whatsapp.net",
"subscribed": true,
"monitoring_ttl_seconds": 300
}
GET/v1/instances/{instanceId}/contacts/{contactId}/presence#
Retorna o snapshot transiente de presença/typing para um contato 1:1.
Auth: Todos autenticados
O snapshot e mantido em Redis, não em MySQL.
monitoring_active=trueindica que a lease de monitoramento ainda está vigente. O último snapshot conhecido fica em cache por até 24h.typing_stateexpira após 10s sem novos eventos.
Resposta 200:
{
"contact_jid": "551199999999@s.whatsapp.net",
"monitoring_active": true,
"online": true,
"last_seen": 1741360000,
"typing_state": "composing",
"typing_chat": "551199999999@s.whatsapp.net",
"is_group": false,
"observed_at": "2026-03-25T15:04:05Z"
}
| Campo | Tipo | Descricao |
|---|---|---|
contact_jid |
string | JID canonico do contato |
monitoring_active |
bool | Lease de monitoramento ainda ativa |
online |
bool | Último status online/offline conhecido |
last_seen |
int64 | Último visto (unix, pode ser 0 se oculto) |
typing_state |
string | composing, paused ou recording enquanto estiver fresco |
typing_chat |
string | Chat onde o typing foi observado |
is_group |
bool | Sempre omitido/falso para snapshot de contato 1:1 |
observed_at |
string(datetime) | Quando o último evento relevante foi observado |
POST/v1/instances/{instanceId}/contacts/check#
Verifica se números de telefone possuem WhatsApp.
Auth: Todos autenticados
Request:
{
"numbers": ["554137984905", "5541988887777"]
}
Resposta 200:
{
"instance_id": "84c2e480-...",
"results": [
{"query": "554137984905", "jid": "554137984905@s.whatsapp.net", "is_in": true, "verified_name": ""},
{"query": "5541988887777", "jid": "", "is_in": false, "verified_name": ""}
]
}
Por provider:
whatsmeow: uma consulta em lote no servidor do WhatsApp, sem teto de quantidade.wwebjs: o worker faz, para cada número, a mesma consulta que o WhatsApp Web faz quando alguém inicia uma conversa por número: um número por vez, com pausa de ~1 s entre eles, no máximo 5 números por chamada (cada número é uma consulta na conta). Celular brasileiro (assinante começando em 6–9) não encontrado é consultado também na outra forma do 9º dígito; se ela existir,is_in: trueejidtraz a forma registrada.verified_namevem vazio. A chamada leva até ~26 s no pior caso.meta_cloud: não suportado (501).
Erros:
| Status | error_code |
Quando |
|---|---|---|
| 400 | BAD_REQUEST |
numbers vazio, ou mais de 5 números numa instância wwebjs (nenhuma consulta é feita) |
| 400 | INVALID_PHONE |
número mal formado |
| 404 | INSTANCE_NOT_FOUND |
instância não pertence à empresa |
| 409 | INSTANCE_NOT_CONNECTED |
instância wwebjs desconectada |
| 502 | CONTACT_CHECK_FAILED |
a consulta ao WhatsApp falhou (wwebjs); nenhuma resposta parcial — tente de novo mais tarde, nunca leia como "não tem WhatsApp" |
Use antes de
PUT .../contacts/{phone}: um número sem WhatsApp recusado noPUT(404 CONTACT_NOT_ON_WHATSAPP) não gasta a cadência de agenda, mas a checagem evita a ida à tela.
POST/v1/instances/{instanceId}/contacts/block#
Bloqueia um contato.
Auth: Todos autenticados
Request:
{
"contact_id": "554137984905"
}
Aceita telefone ou JID. Números BR com 9 extra são normalizados automaticamente.
Resposta 200:
{
"instance_id": "84c2e480-...",
"contact_id": "554137984905",
"blocked": true
}
POST/v1/instances/{instanceId}/contacts/unblock#
Desbloqueia um contato.
Auth: Todos autenticados
Request:
{
"contact_id": "554137984905"
}
Resposta 200:
{
"instance_id": "84c2e480-...",
"contact_id": "554137984905",
"blocked": false
}
contact_idna resposta ecoa exatamente o valor enviado no request.
Figurinhas salvas na conta (wwebjs)#
As figurinhas que a conta já tem — as abas Recentes e Favoritas da gaveta
de figurinhas do WhatsApp — podem ser listadas, mostradas, enviadas sem reenviar o
arquivo e favoritadas. Tudo acontece no WhatsApp Web da própria instância, como uma
pessoa faria. Só wwebjs: os demais providers respondem 501 STICKER_NOT_SUPPORTED.
sticker_id é o hash do arquivo da figurinha em base64 seguro para URL (-, _, sem
=). Ele identifica a figurinha em todas as rotas abaixo e em POST .../messages/sticker.
O caminho do arquivo no servidor da Meta e a chave de decifrar nunca saem da
instância.
GET /v1/instances/{instanceId}/stickers#
Lista as figurinhas da conta. Leitura local da página (a mesma que a gaveta faz):
nada é consultado ao WhatsApp. Vem só o que a gaveta mostra: uma figurinha cujo
arquivo expirou no servidor do WhatsApp some da gaveta (e não daria para enviá-la),
e "favorita" é o que o WhatsApp marca como favorita. Enviar, baixar ou favoritar
uma figurinha fora da lista responde STICKER_NOT_FOUND sem abrir conversa.
Query: source = recent | favorite (opcional; sem ele, as duas).
Resposta 200:
{
"instance_id": "9c8ffc46-91cf-458b-b9cd-4f94eaa9003a",
"count": 1,
"stickers": [
{
"sticker_id": "u54VDNCJI_CFB-v0h6TIIvmiRoeLnlGCT_TPv9IHVSI",
"sources": ["recent", "favorite"],
"mime_type": "image/webp",
"width": 512, "height": 512,
"is_animated": false,
"emojis": ["😀"],
"file_size": 542,
"pack": { "id": "…", "name": "Gatos", "publisher": "…" },
"last_used_at": 1780269410,
"favorited_at": 1780427374
}
]
}
Ordem: as mais usadas primeiro (como a aba Recentes). Campos opcionais ausentes
quando o WhatsApp não informa (pack, emojis, accessibility_label,
is_first_party, is_avatar, is_ai).
GET /v1/instances/{instanceId}/stickers/{stickerId}/media#
A imagem da figurinha como uma mídia da Catcher, para mostrar no CRM. Vem do cache
da página quando a gaveta já a carregou (leitura local, sem tráfego); senão a Catcher
abre a gaveta de figurinhas como uma pessoa, e é a própria gaveta que a carrega. O
download direto pelo WhatsApp Web da instância (pelo proxy dela) fica só como reserva
quando a gaveta não pode ser usada. Fica guardada; chamadas seguintes devolvem o mesmo
media_id.
{ "instance_id": "…", "sticker_id": "…", "media_id": "a1b2…", "mime_type": "image/webp", "file_size": 542,
"download_url": "/v1/instances/…/media/a1b2…" }
PUT / DELETE /v1/instances/{instanceId}/stickers/{stickerId}/favorite#
PUT adiciona às favoritas, DELETE remove. É o menu da figurinha na gaveta
("Adicionar às favoritas" / "Remover dos Favoritos"), sincronizado com o celular.
Já estava nesse estado → unchanged: true, nada é feito e nenhum evento sai.
Emite sticker.favorite_sent.
Figurinha recebida (ou enviada por arquivo): pela mensagem. Recentes guarda só
as figurinhas que a própria linha enviou pela gaveta — uma figurinha recebida não
entra lá (medido no staging em 14/11), então ela não está em GET .../stickers.
Para favoritá-la, envie o corpo {"message_id": "<UUID Catcher ou id do WhatsApp>"}:
a Catcher abre a conversa, passa o mouse na figurinha, abre o menu dela e clica em
Adicionar às favoritas (no DELETE, Remover dos Favoritos), como uma pessoa.
O sticker_id da URL tem de ser o do arquivo da mensagem (SHA-256 do arquivo em
base64 seguro para URL). Depois de favoritada ela aparece em source=favorite e pode
ser enviada por sticker_id. A mensagem precisa estar carregada na conversa (as mais
recentes). Uma conversa com mensagens não lidas é aberta como quem vai responder:
abrir lê a conversa inteira (veja POST .../mark-read) e a conversa é fechada no
fim; quem precisa dela não lida de novo usa POST .../mark-unread. A ação do próprio
menu, sem abrir a conversa, fica só de reserva, antes do clique, quando a tela não pode
ser usada.
{ "message_id": "966c2f1a-85d0-444e-aa3a-14c5d0d31543" }
``` Cadência por instância: 15 s entre alterações, 5 a cada
10 minutos, 30 por hora (`429` com `Retry-After`). Auditado (`sticker.favorite`).
```json
{ "instance_id": "…", "sticker_id": "…", "favorite": true, "unchanged": false }
Erros das rotas de figurinha:
| HTTP | error_code |
Quando |
|---|---|---|
400 |
INVALID_STICKER_ID / BAD_REQUEST |
sticker_id malformado / source inválido |
404 |
INSTANCE_NOT_FOUND |
Instância inexistente ou de outra conta |
404 |
STICKER_NOT_FOUND |
A figurinha não está em Recentes nem em Favoritas; com message_id, a mensagem não é uma figurinha carregada na conversa |
404 |
MESSAGE_NOT_FOUND |
message_id não é uma mensagem desta instância |
400 |
BAD_REQUEST |
message_id não é uma mensagem de figurinha |
400 |
INVALID_STICKER_ID |
Com message_id: o arquivo da mensagem é outra figurinha que não a do sticker_id |
409 |
INSTANCE_NOT_CONNECTED |
Instância desconectada |
429 |
RATE_LIMITED |
Cadência de alterações (favoritar) |
501 |
STICKER_NOT_SUPPORTED |
Provider sem a gaveta (não-wwebjs) |
502 |
STICKER_FAILED |
O WhatsApp Web não concluiu o pedido |
Salvar uma figurinha nova: envie a imagem como figurinha (POST .../messages/sticker
com media_*/file), depois favorite-a pela mensagem enviada (message_id); ou
favorite pela mensagem uma figurinha que chegou numa conversa. A partir daí ela
aparece em GET .../stickers?source=favorite e pode ser reenviada por sticker_id.
Respostas rápidas da conta (WhatsApp Business, wwebjs)#
As respostas rápidas do WhatsApp Business ficam na própria conta e aparecem também
no celular (sincronizadas). A Catcher lista, cria, edita, apaga e envia essas respostas
pelo WhatsApp Web da instância, como uma pessoa faz: Ferramentas → Respostas rápidas
(o + cria; o menu do item tem Editar e Apagar) e, na conversa, / + o atalho
(POST .../messages/quick-reply). Só wwebjs (501 QUICK_REPLIES_NOT_SUPPORTED) e só
conta WhatsApp Business (422 QUICK_REPLIES_NOT_SUPPORTED numa conta pessoal). A
instância expõe a capacidade em capabilities.supports_quick_replies.
Não confundir com os atalhos da Catcher (/v1/shortcuts): esses são textos prontos
da empresa guardados na Catcher, que nunca chegam ao celular.
Regras (as mesmas da tela do WhatsApp Web):
shortcut: 1 a 25 letras de qualquer alfabeto ou números. Sem espaços, pontuação ou emoji (ação,Pix2valem;pix_2,com espaçonão). Dois atalhos iguais (ignorando maiúsculas) são recusados com409 QUICK_REPLY_SHORTCUT_TAKEN, para o/nunca ficar ambíguo.message: obrigatória, com quebras de linha. O WhatsApp Web não limita o tamanho (o formulário só recusa mensagem vazia) e respostas feitas pelo celular passam de 1000 caracteres; a API aceita até 65.536 caracteres, o máximo de uma mensagem de texto do WhatsApp. Texto longo é colado inteiro de uma vez no formulário da gaveta, como uma pessoa faz.- O WhatsApp Web não tem anexo nem palavras-chave nas respostas rápidas (o app do celular tem); a API cobre o que a tela do WhatsApp Web faz.
- As sugestões automáticas que o WhatsApp monta do perfil comercial (
Perfil,Endereço,Horário, Pix) não são respostas da conta e não aparecem na lista, como na gaveta do WhatsApp Web.
GET /v1/instances/{instanceId}/quick-replies#
Lista as respostas rápidas como a gaveta mostra. Leitura local da página: nada é consultado ao WhatsApp.
{
"instance_id": "…",
"count": 1,
"quick_replies": [
{ "quick_reply_id": "1794852243", "shortcut": "horario", "message": "Atendemos de segunda a sexta, das 9h às 18h.", "uses": 3 }
]
}
uses = quantas vezes a resposta foi escolhida (o WhatsApp atualiza depois de sincronizar).
POST /v1/instances/{instanceId}/quick-replies#
Cria pela gaveta: +, atalho e mensagem digitados no ritmo de uma pessoa (uma mensagem
longa é colada, como uma pessoa faria com um texto desse tamanho), Salvar. A tela
recusa um atalho inválido antes de salvar e a Catcher encerra como uma pessoa: nada é
salvo. Emite quick_reply.saved_sent (created: true).
{ "shortcut": "horario", "message": "Atendemos de segunda a sexta, das 9h às 18h." }
Resposta 201:
{ "instance_id": "…", "quick_reply_id": "1794852243", "shortcut": "horario", "message": "Atendemos de segunda a sexta, das 9h às 18h.", "created": true, "unchanged": false }
PATCH /v1/instances/{instanceId}/quick-replies/{quickReplyId}#
Edita pelo menu do item (Editar). Body parcial {shortcut?, message?}: o que não vier
fica como está. Mesmo texto → 200 com unchanged: true, nada é aberto e nenhum evento
sai. Emite quick_reply.saved_sent (created: false).
DELETE /v1/instances/{instanceId}/quick-replies/{quickReplyId}#
Apaga pelo menu do item (Apagar + a confirmação da própria tela). Emite
quick_reply.deleted_sent.
{ "instance_id": "…", "quick_reply_id": "1794852243", "deleted": true }
Tempo e cadência: criar ou editar leva alguns segundos (a tela é usada de verdade) e
cabe nos 30 s de uma requisição. Se não houver tempo de ver o resultado na tela, a
Catcher salva pela ação da própria página antes de qualquer clique, nunca às cegas.
As alterações são espaçadas como a agenda: 15 s entre uma e outra, 5 a cada 10 minutos,
30 por hora (429 RATE_LIMITED, com Retry-After).
Erros das rotas de resposta rápida:
| HTTP | error_code |
Quando |
|---|---|---|
400 |
INVALID_QUICK_REPLY |
Atalho ou mensagem fora das regras, ou id malformado |
400 |
INVALID_JSON |
Corpo inválido |
404 |
INSTANCE_NOT_FOUND |
Instância inexistente ou de outra conta |
404 |
QUICK_REPLY_NOT_FOUND |
Não há resposta com esse id na conta |
409 |
QUICK_REPLY_SHORTCUT_TAKEN |
Outra resposta já usa esse atalho |
409 |
INSTANCE_NOT_CONNECTED |
Instância desconectada |
422 |
QUICK_REPLIES_NOT_SUPPORTED |
A conta não é WhatsApp Business |
429 |
RATE_LIMITED |
Cadência de alterações |
501 |
QUICK_REPLIES_NOT_SUPPORTED |
Provider sem WhatsApp Web (não-wwebjs) |
502 |
QUICK_REPLY_FAILED |
O WhatsApp Web não concluiu o pedido (sem segunda tentativa) |