Chats

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:

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

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

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

json
{
  "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_id e sempre o UUID Catcher — o mesmo que aparece em message_ids nos eventos de webhook — e e o identificador primário desta resposta. O id do protocolo WhatsApp pode ser reciclado após delete 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 como messageId o UUID, o hex (quando único na instância) ou a chave serializada true|false_<chat>_<id>. Use sempre message_id como 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:

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

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

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

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

json
{
  "chat_jid": "554137984905@s.whatsapp.net",
  "message_ids": ["3EB0ABC123", "3EB0DEF456"]
}

Ou para marcar todas:

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

json
{
  "instance_id": "84c2e480-...",
  "marked_read": 2
}

Quando mark_all = true:

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

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

json
{
  "instance_id": "84c2e480-...",
  "chat_jid": "554137984905@s.whatsapp.net",
  "marked_unread": true
}