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
}

GET/v1/instances/{instanceId}/message/{messageId}#

Busca uma mensagem especifica pelo UUID do Catcher (elemento de message_ids nos eventos) ou pelo whatsapp_id (ID do WhatsApp, ex: 3EB0ABC123). A API tenta os dois campos automaticamente.

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). Usar este endpoint e o caminho canonico para um consumidor reconstruir o estado atual de uma mensagem sem precisar agregar todos os eventos de webhook.

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 e ÚNICO exposto — 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. O hex bruto do WhatsApp NÃO e mais retornado (contrato UUID-only, lições #22/#30) — fica salvo internamente, nunca no fio.
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, 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
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
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 ÚNICO identificador retornado nesta resposta. O hex do protocolo WhatsApp pode ser reciclado após delete for everyone (lições #22/#30) e por isso nunca e exposto na API (contrato UUID-only); fica salvo internamente apenas para correlação. O endpoint AINDA ACEITA um hex como messageId de entrada (resolve UUID OU hex automaticamente), mas a resposta e a correlação sempre usam o UUID Catcher. 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}).

POST/v1/instances/{instanceId}/mark-read#

Marca mensagens como lidas.

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
}