Contatos

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_CONNECTED caso contrário). Raramente (~0,3% na medição de staging) um @lid cujo 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:

json
{
  "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
json
{ "first_name": "Ana", "last_name": "Souza" }

Resposta 200:

json
{
  "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).

  • phone pode 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 phone da 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:

json
{
  "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:

json
{
  "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=true e a instância está conectada, o endpoint enriquece a resposta com dados atualizados do WhatsApp (status, nomes, avatar). Quando live=false ou a instância está desconectada, retorna so o que o Catcher persistiu — resposta sempre disponível.

Nota (politica de proxy — lesson #29): picture_url retorna 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:

json
{
  "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 filtros tier, mutual e search sã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_url retornado nos endpoints GET /chats, GET /contacts, ou GET /contacts/{id} como src de tags <img>. Estas URLs nunca expiram (diferente das URLs do CDN do WhatsApp). Se S3_PUBLIC_URL estiver configurado no servidor, a URL e pública e pode ser usada diretamente; caso contrario, a URL aponta para o endpoint proxy /avatar que 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:

json
{
  "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 contactId aceita 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.IsIn flag do whatsmeow (a contraparte do is_in_address_book da 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=3
  • warm (20-39) — max_consecutive=5
  • engaged (40-59) — max_consecutive=7
  • hot (60-79) — max_consecutive=10
  • very_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:

json
{
  "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:

  • phone aceita 5511999999999, +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:

json
{
  "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_score para 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:

json
{
  "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=true indica que a lease de monitoramento ainda está vigente. O último snapshot conhecido fica em cache por até 24h. typing_state expira após 10s sem novos eventos.

Resposta 200:

json
{
  "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:

json
{
  "numbers": ["554137984905", "5541988887777"]
}

Resposta 200:

json
{
  "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: true e jid traz a forma registrada. verified_name vem 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 no PUT (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:

json
{
  "contact_id": "554137984905"
}

Aceita telefone ou JID. Números BR com 9 extra são normalizados automaticamente.

Resposta 200:

json
{
  "instance_id": "84c2e480-...",
  "contact_id": "554137984905",
  "blocked": true
}

POST/v1/instances/{instanceId}/contacts/unblock#

Desbloqueia um contato.

Auth: Todos autenticados

Request:

json
{
  "contact_id": "554137984905"
}

Resposta 200:

json
{
  "instance_id": "84c2e480-...",
  "contact_id": "554137984905",
  "blocked": false
}

contact_id na 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:

json
{
  "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.

json
{ "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.

json
{ "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, Pix2 valem; pix_2, com espaço não). Dois atalhos iguais (ignorando maiúsculas) são recusados com 409 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.

json
{
  "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).

json
{ "shortcut": "horario", "message": "Atendemos de segunda a sexta, das 9h às 18h." }

Resposta 201:

json
{ "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.

json
{ "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)