10. Chats#
GET/v1/instances/{instanceId}/chats#
Lista chats da instância.
Auth: Todos autenticados
Superadmins resolvem o tenant pelo instanceId; se a instância não existir
ou estiver removida, a resposta e 404 INSTANCE_NOT_FOUND em vez de erro
interno de tenant.
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",
"name": "Joao",
"profile_pic_url": "https://media.catcher.one/.../avatars/554137984905.jpg",
"last_message": {
"id": "3EB0ABC123",
"content": "Ola!",
"type": "text",
"timestamp": "2026-03-07T12:00:00Z",
"from_me": false
}
}
],
"total": 25,
"page": 1,
"limit": 20
}
GET/v1/instances/{instanceId}/chats/{chatId}#
Retorna detalhes de um chat especifico, incluindo informações do contato.
Auth: Todos autenticados
Resposta 200:
{
"jid": "554137984905@s.whatsapp.net",
"name": "Joao Silva",
"is_group": false,
"pinned": false,
"archived": false,
"unread_count": 0,
"contact_info": {
"jid": "554137984905@s.whatsapp.net",
"push_name": "Joao Silva",
"business_name": "",
"full_name": "Joao Silva",
"first_name": "Joao",
"status": "Hey there!",
"picture_id": "122207890",
"picture_url": "https://media.catcher.one/.../avatars/554137984905.jpg"
}
}
Os campos do nivel raiz vem de ChatInfo; os nomes/avatar/status do contato ficam no objeto aninhado contact_info. description aparece no raiz apenas quando disponível.
GET/v1/instances/{instanceId}/chats/{chatId}/messages#
Lista mensagens de um chat com paginação.
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": [
{
"id": 1,
"instance_id": "84c2e480-...",
"direction": "inbound",
"remote_jid": "554137984905@s.whatsapp.net",
"message_type": "text",
"content": "Ola!",
"status": "delivered",
"created_at": "2026-03-07T12:00:00Z",
"updated_at": "2026-03-07T12:00:00Z",
"media_id": "",
"quoted_msg_id": "",
"queued_at": null,
"sent_at": "2026-03-07T12:00:01Z",
"delivered_at": "2026-03-07T12:00:02Z",
"read_at": null,
"failed_at": null,
"fail_reason": ""
}
],
"total": 50,
"page": 1,
"limit": 20
}
Campos ricos por tipo (enriquecimento read-side, 2026-07-22): para
mensagens não-texto, a resposta adiciona campos estruturados extraídos do
proto persistido da mensagem (ProtoData) — sem mudança de schema. Sem proto,
localização pode usar a convenção "lat,lng" em content; contatos também são
enriquecidos quando content contém vCards completos (como no wwebjs), usando
o parser compartilhado de nome/telefones. Cartões concatenados permanecem
separados. Conteúdo antigo com apenas nomes ou cartão incompleto mantém o
fallback sem contacts; um proto válido tem precedência sobre content.
| Campo | Quando aparece | Shape |
|---|---|---|
location |
message_type = location/live_location |
{ "latitude": -25.4284, "longitude": -49.2733, "name": "Jardim Botânico", "address": "...", "thumbnail_b64": "<jpeg base64 do REMETENTE>" } (name/address/thumbnail opcionais) |
contacts |
message_type = contact |
[{ "display_name": "Maria", "phones": ["5541999998888"] }] — telefones extraídos do vCard (waid= preferido) |
poll |
message_type = poll |
{ "question": "...", "options": ["A","B"], "selectable_count": 1 } |
link_preview |
message_type = text com preview |
{ "url": "https://...", "title": "...", "description": "...", "thumbnail_b64": "..." } |
view_once |
mídia enviada como visualização única | true |
Nenhum desses campos carrega URL de CDN da Meta — o thumbnail é o JPEG que o próprio remetente embutiu na mensagem, servido como base64.
GET/v1/instances/{instanceId}/message/{messageId}#
Busca uma mensagem especifica pelo UUID do Catcher (elemento de message_ids nos eventos), com precedência sobre o ID nativo. O lookup legado por whatsapp_id responde somente quando identifica uma única mensagem na instância; colisão entre chats/direções responde 409 CONFLICT, sem expor candidatos. Use o UUID próprio do destinatário.
Retorna o estado final da mensagem no banco do Catcher — já aplicadas as edicoes (content reflete a última versão), revogacoes (status=deleted, is_deleted=true), e recibos (timestamps de delivered_at / read_at / played_at). Serve para consulta pontual (abrir uma mensagem, conferir um caso de suporte). Não use para acompanhar o status de envio: o status chega pelos eventos do webhook (*.sent, *.delivered, *.read, *.played, *.delivery_failed), e read pode nunca chegar quando o destinatário desliga a confirmação de leitura — reconsultar até "ficar lida" não termina. Para reconciliar muitas mensagens depois de uma queda, leia GET /v1/instances/{instanceId}/events/history por cursor. Veja Boas Práticas de Integração.
Auth: Todos autenticados
Parametros de URL:
| Parametro | Descricao |
|---|---|
instanceId |
ID da instância |
messageId |
UUID do Catcher (elemento de message_ids do evento) ou whatsapp_id (ex: 3EB0ABC123) |
Resposta 200:
{
"id": 42,
"external_id": "550e8400-e29b-41d4-a716-446655440000",
"message_id": "550e8400-e29b-41d4-a716-446655440000",
"instance_id": "84c2e480-...",
"direction": "inbound",
"remote_jid": "120363025555555555@g.us",
"chat": "120363025555555555@g.us",
"phone": "120363025555555555",
"is_group": true,
"is_deleted": false,
"sender_jid": "554137984905@s.whatsapp.net",
"message_type": "audio",
"content": "",
"status": "played",
"source": "phone",
"media_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"media": {
"id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"mime_type": "audio/ogg; codecs=opus",
"file_name": "voice.ogg",
"file_size": 34567,
"download_url": "/v1/instances/84c2e480-.../media/b2c3d4e5-...",
"info_url": "/v1/instances/84c2e480-.../media/b2c3d4e5-.../info",
"created_at": "2026-03-07T12:00:00Z"
},
"quoted_msg_id": "f1a2b3c4-d5e6-7890-abcd-ef1234567890",
"queued_at": null,
"sent_at": null,
"delivered_at": "2026-03-07T12:00:02Z",
"read_at": "2026-03-07T12:00:10Z",
"played_at": "2026-03-07T12:00:15Z",
"deleted_at": null,
"failed_at": null,
"fail_reason": "",
"created_at": "2026-03-07T12:00:00Z",
"updated_at": "2026-03-07T12:00:15Z"
}
Campos da resposta:
| Campo | Tipo | Descricao |
|---|---|---|
external_id / message_id |
string | UUID Catcher (v4). Identificador canonico estável — use este para correlacionar com eventos de webhook (no payload aparece como elemento de message_ids). external_id e o nome histórico; message_id e o alias retornado nesta resposta sincrona. A chave nativa do WhatsApp vem à parte em wa_message_id/wa_from_me/wa_remote_jid/wa_serialized (desde 2026-10-21) — use-a inteira, nunca o id sozinho (lição #22). |
instance_id |
string | Instância origem |
direction |
string | inbound ou outbound |
remote_jid / chat |
string | JID da conversa (DM: <phone>@s.whatsapp.net, grupo: <id>@g.us) |
phone |
string | Telefone extraido do chat (vazio em grupos) |
is_group |
bool | true se a conversa e um grupo |
is_deleted |
bool | true se a mensagem foi revogada (status=deleted) |
sender_jid |
string | JID de quem enviou (em grupos, diferente do chat; em DMs geralmente igual) |
message_type |
string | text, image, video, audio, document, sticker, location, contact, reaction, poll, template, interactive, button_reply, forward, live_location |
content |
string | Conteúdo atual (já reflete edicoes). Para reactions contem o emoji |
status |
string | queued, sent, delivered, read, played, failed, deleted |
source |
string | api (enviado via Catcher), external (enviado por outro aparelho/WhatsApp Web), phone (recebido) |
media_id |
string | UUID da mídia anexa (quando houver) |
media |
object | Objeto inline com metadata completa da mídia (veja abaixo). Presente apenas quando ha mídia. Evita chamada extra |
header |
object | Cabeçalho interativo { "type": "image" } ou { "type": "video" }; bytes em media_id/media, nunca ponteiro da Meta |
buttons |
array | Botões persistidos; em eco interativo, { "type": "quick_reply", "id": "...", "text": "..." } |
broadcast_id |
string | Identificador opaco opcional que agrupa cópias de uma transmissão; não substitui o UUID da mensagem |
quoted_msg_id |
string | UUID Catcher da mensagem sendo respondida. Vazio se a mensagem citada não estiver no banco do Catcher (ex: reply antigo) |
queued_at / sent_at / delivered_at / read_at / played_at / failed_at / deleted_at |
datetime | Timestamps do ciclo de vida. played_at so para view-once/audio PTT |
fail_reason |
string | Mensagem de erro se status=failed (texto cru, para debug) |
error_code |
string | Código estável e tipado do motivo da falha quando status=failed (ex.: RECIPIENT_NOT_ON_WHATSAPP, INSTANCE_NOT_CONNECTED, REACH_OUT_TIMELOCK). Derivado do mesmo classificador do evento message.delivery_failed. Use este para tratamento programático de "por que a mensagem não foi enviada" |
created_at / updated_at |
datetime | Metadata do registro |
Objeto media inline:
| Campo | Tipo | Descricao |
|---|---|---|
id |
string | UUID da mídia |
mime_type |
string | MIME (ex: image/jpeg, audio/ogg; codecs=opus) |
file_name |
string | Nome original (se houver) |
file_size |
int | Tamanho em bytes |
download_url |
string | Path para baixar o binario (GET /v1/instances/{instanceId}/media/{mediaId}) |
info_url |
string | Path para o endpoint de metadata (GET /v1/instances/{instanceId}/media/{mediaId}/info) |
created_at |
datetime | Quando foi armazenada |
expires_at |
datetime | Opcional — TTL da mídia em S3 (null se permanente) |
Dica:
message_ide sempre o UUID Catcher — o mesmo que aparece emmessage_idsnos eventos de webhook — e e o identificador primário desta resposta. O id do protocolo WhatsApp pode ser reciclado apósdelete for everyone(lição #22), por isso ele vem à parte, como chave nativa completa (wa_message_id+wa_from_me+wa_remote_jid, desde 2026-10-21) — útil para deduplicar entre transportes, nunca como chave primária sozinho. O endpoint aceita comomessageIdo UUID, o hex (quando único na instância) ou a chave serializadatrue|false_<chat>_<id>. Use sempremessage_idcomo chave primaria no seu banco.
Erros:
| Status | Descricao |
|---|---|
| 404 | Mensagem não encontrada para está instância |
POST/v1/instances/{instanceId}/chats/{chatId}/action#
Executa uma ação em um chat.
Auth: Todos autenticados
Request:
{
"action": "pin",
"duration": 604800
}
| Campo | Tipo | Obrigatório | Descricao |
|---|---|---|---|
action |
string | sim | Ação: archive, unarchive, pin, unpin, mute, unmute, clear, delete |
duration |
int64 | não | Duração em segundos (para mute) |
archive/unarchive emitem chat.archive_sent ({chat, phone, archived, timestamp}), pin/unpin emitem chat.pin_sent ({chat, phone, pinned, timestamp}) e mute/unmute emitem chat.mute_sent ({chat, phone, muted, mute_end, timestamp}).
clear limpa as mensagens do chat mas mantém o chat na lista; delete
remove o chat inteiro da lista. São operações distintas (até a Wave
Conversas+Stories de 2026-05-25, clear usava o proto errado de delete — o
fork patch #12 BuildClearChat corrigiu). clear emite chat.clear_sent,
delete emite chat.delete_sent (ambos {chat, phone, timestamp}).
Resposta 200:
{
"status": "applied",
"action": "pin",
"chat_id": "554137984905@s.whatsapp.net",
"instance_id": "84c2e480-..."
}
POST/v1/instances/{instanceId}/chats/{chatId}/disappearing#
Define o timer de mensagens temporárias (ephemeral) do chat. Toda mensagem nova nesse chat passa a auto-destruir após a duração escolhida.
Auth: Todos autenticados
Request:
{ "duration": "7d" }
| Campo | Tipo | Obrigatório | Descricao |
|---|---|---|---|
duration |
string | sim | 0 ou off (desliga), 24h, 7d ou 90d |
Valor inválido → 400 com error_code=INVALID_DISAPPEARING_DURATION.
Resposta 200:
{
"status": "applied",
"chat_id": "554137984905@s.whatsapp.net",
"duration_seconds": 604800,
"instance_id": "84c2e480-..."
}
Emite o evento executor chat.disappearing_timer_sent
({chat, phone, duration_seconds, timestamp}).
Proteção da conta contra chamadas repetidas (provider wwebjs, desde 14/11/2026)#
A Catcher guarda as contas do WhatsApp: chamadas repetidas ou em laço de um consumidor
são absorvidas sem erro e sem tocar a conta. A resposta é a de sucesso de sempre;
o worker registra no log o que absorveu (consumer abuse gate: absorbed, com o motivo),
para avisarmos o integrador.
| Ação | Como é absorvida |
|---|---|
mark-read |
Uma leitura por conversa, quaisquer que sejam os message_ids: pedidos paralelos para a mesma conversa viram uma leitura só; conversa sem não lidas não é aberta; num laço (mais de 8 por conversa por minuto), o excesso vira uma leitura adiada (~30 s) — a conversa termina lida |
mark-unread |
Paralelos viram um; mais de 4 por conversa por minuto são ignorados (a conversa já está não lida) |
"digitando"/"gravando" (presence/chat-state) |
O mesmo estado na mesma conversa em menos de 2 s não é reenviado; mais de 30 por minuto são ignorados |
| Editar | O mesmo texto na mesma mensagem em menos de 10 s edita uma vez; um texto diferente sempre edita |
| Apagar | Pedidos repetidos da mesma mensagem em 30 s apagam uma vez |
| Fixar mensagem | O mesmo estado (e duração) em menos de 10 s não é repetido; mais de 4 iguais por minuto são ignorados; fixar/desfixar alternados sempre rodam |
| Etiqueta de conversa | A mesma associação em menos de 10 s não é repetida; mais de 6 iguais por minuto são ignorados |
Miniatura de figurinha (/stickers/{id}/media) |
A gaveta abre no máximo uma vez a cada 10 s para carregar imagens; uma figurinha que a gaveta não conseguiu carregar não a reabre por 10 min (502 nesse intervalo) |
Envio sem Idempotency-Key |
Recusado (400) antes da trava anti-spam: a nova tentativa, já com a chave, não é bloqueada como "conteúdo duplicado" |
Pedidos com valores diferentes (outro texto, outro estado) nunca são descartados: só repetições idênticas são absorvidas. Envios — inclusive reações — continuam protegidos pela chave de idempotência, pela trava anti-spam e pela pressão da conta (seções próprias);
salvar/apagar contato e favoritar figurinha têm cadência própria (429 com Retry-After).
POST/v1/instances/{instanceId}/mark-read#
Marca a conversa como lida — a conversa inteira, como uma pessoa que a abre.
Ler a conversa inteira (provider wwebjs, desde 14/11/2026). O WhatsApp não lê mensagem por mensagem: quem abre uma conversa lê tudo o que estava pendente nela. A Catcher faz exatamente isso: abre a conversa na tela do WhatsApp Web da linha, espera um tempo de leitura (proporcional ao número de não lidas) e fecha. É o próprio WhatsApp Web que marca tudo como lido e manda os recibos (medido na Catcher 3: mesma telemetria de quem abre à mão).
message_idsé aceito por compatibilidade, mas o efeito é sempre a conversa inteira;mark_all: trueé a forma recomendada. Conversa sem não lidas: nada é aberto. A leitura direta da página (sendSeen) fica só como reserva quando a tela não pode ser usada.Envios também leem. Enviar ou favoritar pela tela numa conversa com não lidas abre a conversa como quem vai responder, e isso lê a conversa inteira. Se o seu fluxo precisa dela não lida depois, chame
POST .../mark-unread. Com "confirmações de leitura" desligadas no celular da linha, o WhatsApp não manda o azul em nenhum dos dois sentidos.
Auth: Todos autenticados
Request:
{
"chat_jid": "554137984905@s.whatsapp.net",
"message_ids": ["3EB0ABC123", "3EB0DEF456"]
}
Ou para marcar todas:
{
"chat_jid": "554137984905@s.whatsapp.net",
"mark_all": true
}
| Campo | Tipo | Obrigatório | Descricao |
|---|---|---|---|
chat_jid |
string | sim | JID do chat |
message_ids |
[]string | não | IDs das mensagens a marcar |
mark_all |
bool | não | Marcar todas como lidas |
Resposta 200:
Quando mark_all = false (ou omitido):
{
"instance_id": "84c2e480-...",
"marked_read": 2
}
Quando mark_all = true:
{
"instance_id": "84c2e480-...",
"chat_jid": "554137984905@s.whatsapp.net",
"marked_all": true
}
POST/v1/instances/{instanceId}/mark-unread#
Marca uma conversa como não lida. O efeito e sincronizado com todos os dispositivos WhatsApp conectados (aparece o badge azul de "não lido").
Auth: Todos autenticados
Request:
{
"chat_jid": "554137984905@s.whatsapp.net"
}
| Campo | Tipo | Obrigatório | Descricao |
|---|---|---|---|
chat_jid |
string | sim | JID do chat a marcar como não lido |
Resposta 200:
{
"instance_id": "84c2e480-...",
"chat_jid": "554137984905@s.whatsapp.net",
"marked_unread": true
}