Mensagens

7. Mensagens#

Todas as operações assincronas desta seção (send, forward, delete, edit) são processadas em fila. A API retorna 202 Accepted com o message_id do Catcher (UUID pre-gerado na aceitacao da request), idempotency_key e task_id para rastreamento e deduplicacao segura de retries do cliente.

Header obrigatório: Idempotency-Key#

Todos os endpoints assincronos de mensagens exigem o header HTTP Idempotency-Key.

  • Use um valor único por operação lógica.
  • Repetir a mesma combinação instanceId + tipo de operação + Idempotency-Key não cria uma nova task.
  • O retry recebe o estado atual do mesmo request (queued, sent ou failed) com o mesmo message_id e o mesmo task_id.
  • Clientes browser podem enviar esse header diretamente: ele faz parte dos headers permitidos no preflight CORS junto com Authorization, Content-Type, X-API-Key, X-CSRF-Token, X-Force-Send e Last-Event-ID.

Formato de destinatário#

O campo to aceita:

  • Número de telefone em E.164 sem + (com o código do país): 554137984905, 51953249443 — será convertido para JID automaticamente
  • JID individual: 554137984905@s.whatsapp.net (também aceito: 51953249443@s.whatsapp.net)
  • JID de grupo: 120363012345678901@g.us

Não são aceitos (retornam 400 INVALID_RECIPIENT): o prefixo + (+554137984905), @lid, @c.us e qualquer forma não-numérica.

Número brasileiro sem o código do país (reparo automático)#

Como conveniência para integrações que guardam o número no formato local brasileiro, um to sem o 55 que seja um número nacional brasileiro válido (10 dígitos fixo/celular-legado ou 11 dígitos celular moderno) recebe o 55 automaticamente: 41988941212 → 5541988941212. Isso é um reparo de borda, não o contrato: envie sempre o número completo com o código do país.

⚠️ Ambiguidade E.164 estrangeiro × DDD brasileiro. Alguns números estrangeiros são, dígito a dígito, indistinguíveis de um celular brasileiro sem DDI — 51953249443 é ao mesmo tempo +51 953 249 443 (Peru) e DDD 51 (Porto Alegre) + 9 5324-9443. Medido com libphonenumber, 19 dos 67 DDDs brasileiros colidem dessa forma (22, 33, 34, 35, 38, 46, 48, 49, 51, 62, 66, 68, 73, 74, 79, 81, 84, 92, 95 — Peru, França, Espanha, Alemanha, Japão, Vietnã, Tailândia, Rússia…). Nenhuma regra de dígitos resolve isso.

O critério de desempate é a origem, não os dígitos: o número é preservado verbatim quando a instância já conversa com ele exatamente naquela forma (uma conversa estabelecida ou um contato aprendido com aquele telefone). Sem essa evidência, prevalece a leitura brasileira — porque um celular BR sem DDI é a forma esmagadoramente mais comum nesta API, e adivinhar "estrangeiro" quebraria todo envio sem DDI vindo de Porto Alegre, Recife ou Natal.

Para um primeiro contato com um número estrangeiro cujos dígitos colidem com um DDD brasileiro, envie o JID (51953249443@s.whatsapp.net): um to que contém @ nunca é tocado pelo reparo.

Resposta padrão (202)#

Todas as operações que criam uma nova mensagem retornam:

json
{
  "status": "queued",
  "message_id": "550e8400-e29b-41d4-a716-446655440000",
  "task_id": "asynq:task:xxxx-xxxx",
  "idempotency_key": "msg-2026-03-21-0001"
}
  • message_id — UUID do Catcher, pre-gerado no momento da aceitacao. E o mesmo valor que aparece como elemento de message_ids nos webhooks message.sent, message.delivered, message.read, message.played, message.deleted, message.edited. Use este campo para correlacionar a resposta sincrona com os eventos assincronos (no consumer, message_ids[0] = message_id da resposta 202).
  • idempotency_key — eco do header enviado pelo cliente. Também aparece no webhook message.sent (campo idempotency_key) quando a mensagem foi originada via API.
  • task_id — identificador interno do Asynq. Util para debug/NOC; não deve ser usado como chave de correlação primaria (use message_id ou idempotency_key).

Operações que não criam um novo Message (delete, edit) retornam apenas status, task_id e idempotency_key; o cliente já possui o message_id alvo da operação.

Repetir a mesma chave idempotente devolve o mesmo message_id, task_id e o estado atual (queued, sent ou failed) sem enfileirar duplicidade. Este e o caminho oficial para um cliente recuperar o message_id caso tenha perdido a resposta original ou precise verificar o estado antes do primeiro webhook.

Confirmando entrega de verdade (o 202 não é entrega)#

O 202 significa apenas "aceito na fila". NÃO significa que a mensagem saiu, chegou, ou renderizou no destinatário. Para confirmar de verdade, acompanhe a escada de eventos (webhook/SSE/WS) correlacionando por message_id:

Evento Prova NÃO prova
202 queued (resposta HTTP) a task entrou na fila que saiu / chegou
message.sent o worker despachou pro WhatsApp; a Meta aceitou o proto que chegou no aparelho
message.delivered chegou no aparelho do destinatário que renderizou / tocou
message.read o destinatário abriu e o chat renderizou (texto, imagem, documento, sticker, localização, contato, link-preview) —
message.played o destinatário tocou a mídia (áudio/PTT, vídeo, PTV, view-once) —

O salto crítico é delivered → read/played: mídia pode entregar e falhar em renderizar/tocar no cliente (proto incompleto, container errado). Se um envio chega em delivered mas nunca dá read/played, trate como não consumido — não como entregue. Regra prática: "sem read/played, não chegou de verdade."

Pré-condição importante: o read/played só dispara se o destinatário tiver recibos de leitura ligados E efetivamente abrir/tocar a mensagem. Se o destinatário não produz recibo, o piso de verificação é message.delivered (chegou no aparelho) + inspecionar o message.received do lado dele e conferir que o conteúdo bate (==) com o enviado: mesma caption/content, mesmo message_type, media_id presente, phone correto. Isso prova que chegou correto, mesmo sem o sinal de leitura.

Status / Stories têm semântica de recepção diferente: o evento status.viewed (alguém viu MEU status) só vem de contatos no público do status (contatos salvos filtrados pela privacidade de status), não de qualquer número com quem você troca DM. Ver Status / Stories.

Campo quoted_id (reply)#

Todos os endpoints de envio que listam quoted_id aceitam:

  • UUID Catcher (formato xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx): e o mesmo UUID retornado em message_ids nos webhooks (message.received, message.sent, etc). A API resolve internamente para o ID hexadecimal do WhatsApp antes de enfileirar.
  • ID hexadecimal do WhatsApp (ex.: 3EB0ABC123...): passa direto, sem lookup.
  • Chave nativa do WhatsApp (desde 2026-10-21): a forma serializada true|false_<chat>_<id> no próprio quoted_id, ou os campos quoted_wa_message_id + quoted_wa_from_me (+ quoted_wa_remote_jid, quoted_wa_participant). Funciona mesmo para mensagem fora do nosso histórico — ver "Id nativo do WhatsApp (wa_*)".

Se o quoted_id for um UUID realmente ausente no banco tenant, o comportamento padrão (desde 2026-07-06) é lenient: a mensagem é enviada sem o reply e o 202 retorna um campo warnings com ["quoted_id not found — sent without quote"]. "Mesmo chat" inclui as duas formas de um celular brasileiro (com e sem o 9º dígito, ex.: 5521979598856 e 552179598856): são a mesma conta e a mesma conversa (corrigido em 14/11/2026 — até então a resposta citando uma mensagem do próprio cliente podia ser recusada quando o número chegava numa forma e o envio era normalizado para a outra). Um UUID reconhecido no tenant, mas pertencente a outro chat ou instância, responde 404 MESSAGE_NOT_FOUND mesmo em modo lenient; não pode selecionar outra cópia do mesmo ID nativo. Referência ambígua responde 409 CONFLICT, sem enfileirar ou omitir o quote silenciosamente.

Para exigir o reply (comportamento antigo de falha), envie "quoted_strict": true no corpo — aí um quoted_id não resolvível responde 404 Not Found com error_code=MESSAGE_NOT_FOUND e nada é enfileirado.

jsonc
// 202 quando o quoted_id não resolveu (modo lenient, padrão)
{
  "status": "queued",
  "message_id": "…",
  "task_id": "…",
  "idempotency_key": "…",
  "warnings": ["quoted_id not found — sent without quote"]
}

Isto vale para SendText, SendImage, SendVideo, SendAudio, SendDocument, SendSticker, SendLocation, SendContact, os variantes Tier A (link preview) e para os equivalentes de envio agendado via POST /v1/instances/{instanceId}/messages/scheduled. O quoted_strict é aceito nos endpoints JSON; no multipart use o campo de formulário quoted_strict=true.

O reply é montado INTEIRO ou não é montado (canal não-oficial). Uma citação só renderiza no aparelho do destinatário quando o ContextInfo leva os três campos juntos: o id da mensagem citada, o autor dela e o conteúdo citado. Quando o quoted_id resolve mas o conteúdo original não pode ser reconstruído (linha antiga sem proto guardado, tipo irreconstruível), a Catcher envia a mensagem sem citação alguma em vez de mandar uma citação pela metade — uma citação incompleta não aparece para o destinatário e, num número com coexistência, faz a mensagem inteira sumir do lado oficial. O worker registra um WARN (reply quote dropped) quando isso acontece.

O autor da citação é sempre o autor da mensagem citada — você mesmo ao citar a sua própria mensagem, o participante ao citar alguém num grupo — nunca o destinatário da resposta.


Confiabilidade de envio — instância em blip vs. desligada (desde 2026-07-06)#

O envio é assíncrono (202 → fila → worker). Quando a instância quer estar conectada (desired_state=CONNECTED) mas está momentaneamente reconectando (deploy, blip de rede), o comportamento mudou para não perder mensagem:

  • A API aceita o envio (202, entra na fila) mesmo se a instância não está CONNECTED naquele instante — desde que ela esteja pareada e queira estar conectada. A fila segura a mensagem e ela sai quando a sessão volta.
  • O 409 INSTANCE_NOT_CONNECTED só é retornado quando a instância foi desligada de propósito (desired_state=DISCONNECTED), nunca foi pareada, foi deslogada (LOGGED_OUT) ou banida (BANNED).
  • No worker, um erro transitório de conexão (instance not connected) numa instância que quer estar conectada é retentado (backoff do Asynq) em vez de falhar na hora. Enquanto retenta, a mensagem fica com status=queued e o motivo em fail_reason — não aparece como failed. Ela só vira failed (e emite message.delivery_failed) quando as tentativas esgotam ou o erro é genuinamente permanente (número inválido, não-registrado, banido, LOGGED_OUT, time-lock 463).

Ou seja: uma reconexão de segundos não vira mais um card "Não entregue" — a mensagem sai sozinha. O feedback de falha terminal continua chegando pelo evento message.delivery_failed com error_code classificado.

Garantias de entrega (contrato do consumidor)#

Um envio aceito com 202 é durável e obedece estas garantias observáveis — o consumidor pode construir sobre elas:

Garantia O que significa para o integrador
Durabilidade (sem perda) O envio aceito é persistido no banco antes do 202. Uma indisponibilidade de infraestrutura de fila (Redis fora do ar / reinício / flush) não perde o envio — a entrega é re-dirigida a partir do banco. Não existe o buraco silencioso de "202 e nunca chega e nada avisa".
Resultado terminal sempre sinalizado Todo envio termina em sucesso (message.delivered → message.read/message.played) ou em message.delivery_failed com um reason classificado. Nunca fica num limbo sem feedback.
Retry através de blip Uma reconexão momentânea da instância (desired_state=CONNECTED) é retentada automaticamente do lado da sessão, com backoff limitado — a mensagem sai sozinha quando a sessão volta. Esses retries não batem na Meta repetidamente (proteção anti-ban).
Janela de validade Se a instância ficar offline por mais de ~1h, a mensagem expira e dispara message.delivery_failed (uma mensagem de WhatsApp horas atrasada é pior do que não enviada). Não há entrega "fora de hora".
Ordem por instância Na mesma instância, a mensagem 2 nunca é enviada antes da mensagem 1 (ordem estrita de emissão).
Sem duplicata Um reinício do worker no meio de um envio não reenvia — a deduplicação é pelo message_id (o UUID pré-gerado do 202).

Correlação: todos os eventos do ciclo (message.sent/delivered/read/played/delivery_failed) carregam o mesmo message_id (o UUID retornado no 202). Correlacione sempre por ele — nunca pelo ID hexadecimal cru do WhatsApp (ele é reciclado pela Meta e colide entre instâncias/direções). Veja a seção de Webhooks (message.delivery_failed) para o payload de falha e a tabela de reason.

(O motor interno que sustenta essas garantias — fila em banco vs. fila Redis — é detalhe de implementação e pode mudar sem quebrar o contrato acima.)


Modo passivo (409 PASSIVE_MODE_ENABLED)#

Quando a instância está configurada em modo passivo (passive_mode_enabled=true em GET/PATCH /v1/instances/{id}/settings), todos os endpoints de envio (text, image, video, audio, document, sticker, location, contact, reaction, poll, template, forward, delete, edit) são bloqueados antes do enfileiramento:

json
{
  "error_code": "PASSIVE_MODE_ENABLED",
  "message": "instance is in passive mode — set passive_mode_enabled=false in /v1/instances/{id}/settings or pass X-Force-Send: true to override (audit-logged)",
  "trace_id": "..."
}
  • HTTP 409 Conflict.
  • Bypass: header X-Force-Send: true (registra audit log audit_action=passive_mode.force_send).
  • Modo passivo falha fechado: um erro transitorio no banco do tenant retorna 503/500 em vez de liberar o envio (proposito: não vazar outbound de uma instância sob hold legal/monitoramento).

Guard anti-spam (409 BLOCKED_*)#

Endpoints de envio passam por um guard anti-spam antes de enfileirar. Qualquer regra que dispare devolve 409 Conflict:

error_code Regra Campos extras no payload
BLOCKED_DUPLICATE_CONTENT Conteúdo identico já enviado nas últimas 24h remote_jid, content_hash, first_sent_at
BLOCKED_NO_RECIPROCITY Envios consecutivos sem nenhum inbound do contato — limite fixo remote_jid, count, threshold
BLOCKED_TEMPERATURE_LIMIT max_consecutive da curva de temperatura do contato excedido remote_jid, score, tier, max_consecutive, outbound_consecutive
  • A regra de conteúdo duplicado é controlada por anti_spam_guard_enabled (default true).
  • O limite seguido sem resposta é opcional (contact_limit_mode, default off): com temperature só BLOCKED_TEMPERATURE_LIMIT pode disparar, com fixed só BLOCKED_NO_RECIPROCITY, com off nenhum dos dois. Os dois nunca rodam ao mesmo tempo.
  • delete, edit, reaction e forward são isentos da regra de conteúdo duplicado (não ha shape de conteúdo comparavel), mas continuam contando para o limite consecutivo.
  • Bypass: header X-Force-Send: true (registra audit log audit_action=anti_spam.force_send).

POST/v1/instances/{instanceId}/messages/text#

Envia mensagem de texto.

Auth: Todos autenticados

Request:

json
{
  "to": "554137984905",
  "text": "Ola! Como posso ajudar?",
  "quoted_id": "3EB0ABC123...",
  "mentions": ["5541988888888@s.whatsapp.net"]
}
Campo Tipo Obrigatório Descricao
to string sim Destinatário (telefone ou JID)
text string sim Conteúdo da mensagem
quoted_id string não ID da mensagem respondida (UUID Catcher ou hex WhatsApp; ver nota geral de quoted_id acima)
mentions []string não JIDs de usuários mencionados

Regras do humanize:

  • Controlado por instância via GET/PATCH /v1/instances/{instanceId}/settings (humanize_enabled, default true).
  • Quando ativo, o processor envia composing imediatamente antes de SendText e espera numero_de_caracteres(texto) * multiplier segundos, com multiplier aleatorio entre 0.1 e 0.5.
  • A aplicação ocorre apenas em mensagens de texto para chats 1:1; grupos (@g.us) e mensagens de mídia seguem o fluxo legado.
  • Se a leitura da configuração falhar, o envio segue imediatamente para não bloquear a fila.
  • Antes do "digitando…", se a conversa tem mensagens recebidas ainda não lidas, elas são marcadas como lidas (como alguém que abre a conversa para responder).
  • Provider wwebjs (desde 2026-11-02): mostra o "digitando…" e marca como lida só se houver não lidas; não abre a conversa na página (uma conversa aberta pode marcar como lidas, sozinha, mensagens que chegam depois). Antes dessa data o wwebjs só aplicava a pausa. POST .../presence com composing/recording/paused também passa a funcionar no wwebjs.

Envio de mídia: media_url, media_id, media_base64 ou arquivo direto#

Os endpoints POST /v1/instances/{instanceId}/messages/{image|video|audio|document|sticker} (e os de status) aceitam as quatro formas de origem no mesmo endpoint:

  1. application/json com media_url: o servidor baixa a URL sincronamente durante o request (~500ms-2s para arquivos pequenos), aplica validação SSRF/MIME/64 MB, armazena no R2/S3, gera um media_id interno e enfileira o envio usando esse ID.
  2. application/json com media_id: reutiliza uma mídia já armazenada pelo endpoint POST /v1/instances/{instanceId}/media ou por mídia recebida.
  3. application/json com media_base64: o conteúdo binário vai inline no corpo, como data-URI (data:image/png;base64,iVBORw0...) ou base64 puro (sem o prefixo). O servidor decodifica, valida MIME/64 MB, armazena no R2 (source="base64") e enfileira usando o media_id gerado. Não há TTL de reaper (diferente de url-cache).
  4. multipart/form-data com campo file: envia o arquivo binario direto no próprio endpoint; a API armazena em R2, gera um media_id e enfileira o envio usando esse ID.

Em JSON, envie apenas UM de media_url / media_id / media_base64 — passar mais de um retorna 400 com "provide only one of media_url, media_id, media_base64".

Arquitetura de mídia: API resolve, worker só envia#

Independente da forma de origem (URL, media_id existente ou multipart), a API sempre garante que os bytes estejam armazenados no R2 antes de retornar 202. O worker só recebe media_id na fila Asynq — nunca uma URL externa para baixar. Isso elimina classe inteira de falha silenciosa em que a CDN externa bloqueia download depois do 202 e a mensagem nunca chega.

Prático para você (consumidor da API):

  • Falha de download é sincrona: se a URL retorna 4xx, 5xx, timeout, ou MIME bloqueado, você recebe 502 MEDIA_FETCH_FAILED no momento da chamada. NÃO vai pra fila, não tem retry silencioso. Retry o request com URL válida ou faca upload prévio.
  • Custo de latência: requests com media_url agora levam ~500ms-2s a mais que com media_id (tempo do download + upload R2). Para arquivos grandes (>10MB), considere fazer upload prévio via POST /v1/instances/{id}/media e reutilizar o media_id retornado.
  • Cache automático: cada media_url baixado vira uma linha no R2 com source="url-cache" e TTL de 7 dias. Reaproveitamento da mesma URL durante esse período é livre.
  • Disciplina de proxy: o download da URL passa pelo cliente HTTP padrão da API (resolver DNS-over-TLS, validador SSRF). Bright Data residential proxy é reservado APENAS para o upload worker → Meta CDN na hora do envio. Isso é deliberado e estrutural — ver .claude/rules/whatsapp-proxy-discipline.md.

Campos textuais do envio (to, caption, file_name, ptt, quoted_id, mentions) podem ir no multipart como campos de formulario. mentions aceita valores repetidos, CSV ou JSON array.

O header Idempotency-Key e obrigatório em todas as tres formas de envio de mídia (igual aos demais endpoints de mensagem).

Exemplo com arquivo direto:

bash
curl -X POST "https://api.catcher.one/v1/instances/$INSTANCE/messages/image" \
  -H "X-API-Key: $TOKEN" \
  -H "Idempotency-Key: req_01HX9Y..." \
  -F "to=554137984905" \
  -F "caption=Imagem enviada pela API" \
  -F "file=@/caminho/foto.png"

Exemplo com URL externa:

bash
curl -X POST "https://api.catcher.one/v1/instances/$INSTANCE/messages/video" \
  -H "X-API-Key: $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: req_01HX9Y..." \
  -d '{
    "to": "554137984905",
    "media_url": "https://meucdn.com/video.mp4",
    "caption": "Olha esse vídeo"
  }'
# → 202 só sai depois que os bytes estão no R2.
# → 502 MEDIA_FETCH_FAILED se o CDN externo recusar.

Exemplo com upload prévio (recomendado para arquivos grandes ou reutilizados):

bash
# 1. Upload uma vez:
MEDIA_ID=$(curl -sf -X POST "https://api.catcher.one/v1/instances/$INSTANCE/media" \
  -H "X-API-Key: $TOKEN" \
  -H "Idempotency-Key: upload-$(date +%s)" \
  -F "file=@/caminho/video-grande.mp4" | jq -r .media_id)

# 2. Reutilize em N envios sem rebaixar:
for PHONE in 554137984905 554196332719 554163475715; do
  curl -X POST "https://api.catcher.one/v1/instances/$INSTANCE/messages/video" \
    -H "X-API-Key: $TOKEN" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: bulk-$PHONE-$(date +%s)" \
    -d "{\"to\":\"$PHONE\",\"media_id\":\"$MEDIA_ID\",\"caption\":\"Veja como ficou\"}"
done

Exemplo com base64 inline (data-URI):

bash
curl -X POST "https://api.catcher.one/v1/instances/$INSTANCE/messages/image" \
  -H "X-API-Key: $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: req_01HX9Z..." \
  -d '{
    "to": "554137984905",
    "media_base64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==",
    "caption": "Pixel enviado inline"
  }'
# → base64 puro (sem o prefixo "data:...") também é aceito.

Em JSON, envie media_url OU media_id OU media_base64 (exatamente um). Em multipart, envie file. Uma dessas formas e obrigatória.


POST/v1/instances/{instanceId}/messages/image#

Envia imagem.

Auth: Todos autenticados

Request:

json
{
  "to": "554137984905",
  "media_url": "https://exemplo.com/foto.png",
  "caption": "Confira esta imagem!",
  "quoted_id": "",
  "mentions": []
}
Campo Tipo Obrigatório Descricao
to string sim Destinatário
media_url string sim* URL pública da imagem
media_id string sim* ID de média pre-enviado via upload
media_base64 string sim* Conteúdo inline: data-URI (data:<mime>;base64,...) ou base64 puro
file file sim* Arquivo direto via multipart/form-data
caption string não Legenda da imagem
quoted_id string não ID da mensagem respondida (UUID Catcher ou hex WhatsApp; ver nota geral de quoted_id acima)
mentions []string não JIDs mencionados

*Enviar media_url, media_id, media_base64 OU file (exatamente um e obrigatório; >1 em JSON retorna 400).


POST/v1/instances/{instanceId}/messages/video#

Envia video.

Auth: Todos autenticados

Request:

json
{
  "to": "554137984905",
  "media_url": "https://exemplo.com/video.mp4",
  "caption": "Assista ao video"
}
Campo Tipo Obrigatório Descricao
to string sim Destinatário
media_url string sim* URL pública do video
media_id string sim* ID de média pre-enviado
media_base64 string sim* Conteúdo inline: data-URI (data:<mime>;base64,...) ou base64 puro
file file sim* Arquivo direto via multipart/form-data
caption string não Legenda
quoted_id string não ID da mensagem respondida (UUID Catcher ou hex WhatsApp; ver nota geral de quoted_id acima)
mentions []string não JIDs mencionados

*Enviar media_url, media_id, media_base64 OU file (exatamente um e obrigatório; >1 em JSON retorna 400).


Áudio: dois endpoints, dois jeitos#

O envio de áudio tem dois endpoints separados — escolha pelo tipo de mensagem que você quer, sem depender de flags:

Endpoint Renderiza como Waveform Recibo played Use quando
POST .../messages/voice mensagem de voz (PTT) ✅ ondinha ✅ quer o áudio "de voz", tipo gravar segurando o microfone
POST .../messages/audio arquivo de áudio ❌ player comum ❌ quer mandar um arquivo de áudio (música, gravação, anexo)

Ambos aceitam o mesmo corpo (to + media_url ou media_id ou media_base64 ou file).


POST/v1/instances/{instanceId}/messages/voice#

Envia uma mensagem de voz (PTT) — renderizada com waveform (ondinha) + ícone de play, e o toque do destinatário gera o recibo message.played. O áudio é sempre convertido para OGG Opus (mono, 16 kHz, 32 kbps) via ffmpeg — formato exigido pelo WhatsApp para voz; uma waveform de 64 bytes é gerada automaticamente. É o jeito de mandar "um áudio de voz", o mais próximo de gravar segurando o microfone.

Auth: Todos autenticados

Request:

json
{
  "to": "554137984905",
  "media_url": "https://exemplo.com/audio.mp3"
}
Campo Tipo Obrigatório Descricao
to string sim Destinatário
media_url string sim* URL pública do áudio (qualquer formato — convertido para OGG Opus)
media_id string sim* ID de mídia pré-enviado
media_base64 string sim* Conteúdo inline: data-URI (data:<mime>;base64,...) ou base64 puro
file file sim* Arquivo direto via multipart/form-data
quoted_id string não ID da mensagem respondida (UUID Catcher ou hex WhatsApp)
mentions []string não JIDs mencionados

*Enviar exatamente um de media_url, media_id, media_base64 ou file.

Ciclo de vida: sent → delivered → read → played. O played chega quando o destinatário toca o áudio (requer confirmações de leitura habilitadas no aparelho dele).


POST/v1/instances/{instanceId}/messages/audio#

Envia um arquivo de áudio — um player de áudio comum, sem waveform e sem recibo played. Para uma mensagem de voz (ondinha + played), use /messages/voice. Os bytes vão como estão, sem conversão.

Auth: Todos autenticados

Request:

json
{
  "to": "554137984905",
  "media_url": "https://exemplo.com/audio.mp3"
}
Campo Tipo Obrigatório Descricao
to string sim Destinatário
media_url string sim* URL pública do áudio (qualquer formato: MP3, OGG, M4A, WAV, etc)
media_id string sim* ID de mídia pré-enviado
media_base64 string sim* Conteúdo inline: data-URI (data:<mime>;base64,...) ou base64 puro
file file sim* Arquivo direto via multipart/form-data
ptt bool não Compatibilidade retroativa. Padrão false (arquivo de áudio). true força uma mensagem de voz (equivalente a /messages/voice, com conversão para OGG Opus). Prefira o endpoint /messages/voice.
quoted_id string não ID da mensagem respondida (UUID Catcher ou hex WhatsApp; ver nota geral de quoted_id acima)
mentions []string não JIDs mencionados

*Enviar media_url, media_id, media_base64 OU file (exatamente um e obrigatório; >1 em JSON retorna 400).

No envio multipart, o campo ptt deve ser um booleano válido (true/false); valores inválidos retornam 400 BAD_REQUEST.


POST/v1/instances/{instanceId}/messages/document#

Envia documento de qualquer tipo de arquivo (PDF, DOCX, XLSX, CSV, ZIP, TXT, etc). Diferente de image/video/audio, o endpoint document não aplica a allow-list de MIME — o WhatsApp entrega qualquer arquivo como documento. Vale para media_url, media_base64 e multipart/form-data.

Auth: Todos autenticados

Request:

json
{
  "to": "554137984905",
  "media_url": "https://exemplo.com/relatorio.pdf",
  "file_name": "relatorio-marco.pdf",
  "caption": "Segue o relatório de março"
}
Campo Tipo Obrigatório Descricao
to string sim Destinatário
media_url string sim* URL pública do documento
media_id string sim* ID de média pre-enviado
media_base64 string sim* Conteúdo inline: data-URI (data:<mime>;base64,...) ou base64 puro
file file sim* Arquivo direto via multipart/form-data
file_name string não Nome do arquivo exibido no WhatsApp
caption string não Legenda nativa exibida junto ao documento (mesmo comportamento de image/video; suportada nos três providers — whatsmeow, wwebjs e meta_cloud)
quoted_id string não ID da mensagem respondida (UUID Catcher ou hex WhatsApp; ver nota geral de quoted_id acima)
mentions []string não JIDs mencionados

*Enviar media_url, media_id, media_base64 OU file (exatamente um e obrigatório; >1 em JSON retorna 400).


POST/v1/instances/{instanceId}/messages/sticker#

Envia sticker (figurinha). A imagem deve estar no formato WebP.

Auth: Todos autenticados

Request:

json
{
  "to": "554137984905",
  "media_url": "https://exemplo.com/sticker.webp"
}
Campo Tipo Obrigatório Descricao
to string sim Destinatário
media_url string sim* URL pública do sticker (WebP). Um WebP animado (chunk ANIM) é enviado com a flag isAnimated — o destinatário recebe is_animated: true no *.received, como faz o cliente oficial
media_id string sim* ID de média pre-enviado
media_base64 string sim* Conteúdo inline: data-URI (data:<mime>;base64,...) ou base64 puro
file file sim* Arquivo direto via multipart/form-data
quoted_id string não ID da mensagem respondida (UUID Catcher ou hex WhatsApp; ver nota geral de quoted_id acima)
mentions []string não JIDs para mencionar
sticker_id string sim* Figurinha que a conta já tem (Recentes/Favoritas, de GET .../stickers). Enviada sem upload: reaproveita o arquivo que já está no WhatsApp. Só wwebjs (501 STICKER_NOT_SUPPORTED nos demais)

*Enviar media_url, media_id, media_base64, file OU sticker_id (exatamente um e obrigatório; >1 em JSON retorna 400).

Com sticker_id o worker faz como uma pessoa: abre a conversa, abre "Emojis, GIFs, figurinhas" → Figurinhas e toca na figurinha (a gaveta registra a mesma telemetria de quem toca). Uma conversa com mensagens não lidas é aberta como quem vai responder: abrir lê a conversa inteira (veja POST .../mark-read); quem precisa dela não lida de novo usa POST .../mark-unread. Figurinha mais abaixo na gaveta é achada rolando a gaveta. Com quoted_id (responder citando) também vai pela tela: passa o mouse na mensagem, abre o menu dela, clica em Responder e então toca na figurinha; mensagem antiga é achada rolando a conversa para cima. A ação da própria gaveta fica só de reserva, antes do clique, quando a tela não pode ser usada. A Catcher confere que a figurinha saiu citando a mensagem pedida. Figurinha premium é recusada como o WhatsApp Web recusa (só pelo celular). Erros assíncronos (message.delivery_failed, com reason sticker_not_found / sticker_premium / sticker_chat_not_found): STICKER_NOT_FOUND (não está entre as que a gaveta mostra), STICKER_PREMIUM, STICKER_CHAT_NOT_FOUND (ainda não há conversa com esse número: mande uma mensagem antes). Síncronos: 400 INVALID_STICKER_ID; sticker_id junto com qualquer mídia → 400. A cadência de envio é a mesma de qualquer mensagem.

json
{ "to": "554137984905", "sticker_id": "u54VDNCJI_CFB-v0h6TIIvmiRoeLnlGCT_TPv9IHVSI" }

POST/v1/instances/{instanceId}/messages/quick-reply#

Envia uma resposta rápida da conta do WhatsApp Business como uma pessoa faz no WhatsApp Web: abre a conversa, digita / + o atalho, escolhe a resposta na lista (nunca a primeira linha às cegas, porque outro atalho pode começar igual), confere que a caixa ficou com a mensagem salva, faz uma pausa curta de leitura e envia com Enter. No fio é um texto comum (message_type: "text", igual a um texto digitado); o que muda é o caminho na tela, com a telemetria do / que um envio de texto puro não tem. Só wwebjs e conta WhatsApp Business.

Auth: Todos autenticados. Idempotency-Key obrigatório (como todo envio).

Request:

json
{ "to": "554137984905", "shortcut": "horario" }
Campo Tipo Obrigatório Descricao
to string sim Destinatário
quick_reply_id string sim* Id da resposta (GET .../quick-replies)
shortcut string sim* O atalho, sem diferenciar maiúsculas; / no começo é aceito
quoted_id string não Responder citando (UUID Catcher ou hex WhatsApp; vai pela tela como as figurinhas)
quoted_strict bool não Como em messages/text

*Exatamente um de quick_reply_id ou shortcut (400 MISSING_FIELD com nenhum ou os dois).

A Catcher lê a mensagem atual da resposta no momento do pedido: é ela que passa pelo anti-spam, é gravada e sai no message.sent. Se a resposta for editada ou apagada antes de o worker enviar, o envio é recusado (message.delivery_failed com reason quick_reply_changed / quick_reply_not_found / quick_replies_not_supported) e nunca sai com outro texto. Uma conversa com não lidas é aberta como quem vai responder (abrir lê a conversa, como no envio de figurinha). Um rascunho na caixa de mensagem nunca é apagado: com rascunho, ou se a lista do / não aparecer, o mesmo texto sai pela caixa de mensagem (reserva antes do envio). Depois do Enter nunca há segunda tentativa.

Resposta 202: a mesma de messages/text (message_id = UUID Catcher do message.sent).

Erros síncronos: 400 MISSING_FIELD / INVALID_QUICK_REPLY, 404 QUICK_REPLY_NOT_FOUND, 409 INSTANCE_NOT_CONNECTED, 422 QUICK_REPLIES_NOT_SUPPORTED (conta pessoal), 501 QUICK_REPLIES_NOT_SUPPORTED (provider sem WhatsApp Web).


POST/v1/instances/{instanceId}/messages/location#

Envia localização.

Auth: Todos autenticados

Request:

json
{
  "to": "554137984905",
  "latitude": -25.4284,
  "longitude": -49.2733,
  "name": "Praca Tiradentes",
  "address": "Centro, Curitiba - PR"
}
Campo Tipo Obrigatório Descricao
to string sim Destinatário
latitude float sim Latitude
longitude float sim Longitude
name string não Nome do local
address string não Endereço
quoted_id string não ID da mensagem respondida (UUID Catcher ou hex WhatsApp; ver nota geral de quoted_id acima)
mentions []string não JIDs para mencionar

POST/v1/instances/{instanceId}/messages/contact#

Envia um ou mais cartoes de contato (vCard). Com 2+ contatos, o WhatsApp do destinatário recebe um único card agrupado (ContactsArrayMessage).

Auth: Todos autenticados

Request — contato único (nome + telefone):

json
{
  "to": "554137984905",
  "contact_name": "Suporte Catcher",
  "contact_phone": "+5541988887777"
}

Request — varios contatos:

json
{
  "to": "554137984905",
  "contacts": [
    { "contact_name": "Suporte Catcher", "contact_phone": "+5541988887777" },
    { "contact_name": "Comercial", "contact_phone": "+5541977776666" }
  ]
}

Request — vCard cru (fidelidade total: email, empresa, multiplos números):

json
{
  "to": "554137984905",
  "vcard": "BEGIN:VCARD\nVERSION:3.0\nFN:Suporte Catcher\nTEL;type=CELL;waid=5541988887777:+5541988887777\nEMAIL:suporte@catcher.one\nEND:VCARD"
}
Campo Tipo Obrigatório Descricao
to string sim Destinatário
contact_name string condicional Nome do contato. Obrigatório no modo contato-único quando vcard e contacts estão ausentes
contact_phone string condicional Telefone do contato em formato E.164 com + (ex: +5541988887777). Obrigatório junto de contact_name
vcard string não vCard 3.0 cru de um único contato (deve conter BEGIN:VCARD/END:VCARD, max 8 KB). Enviado verbatim — o conteúdo e responsabilidade do chamador. Tem precedencia sobre contact_name/contact_phone
contacts []object não Lista de contatos (max 50). Cada item: contact_name+contact_phone, ou vcard. Tem precedencia sobre os campos de nivel raiz. 2+ itens viram um ContactsArrayMessage
quoted_id string não ID da mensagem respondida (UUID Catcher ou hex WhatsApp; ver nota geral de quoted_id acima)
mentions []string não JIDs para mencionar

Precedencia entre as formas: contacts > vcard > contact_name/contact_phone. O webhook message.sent resultante carrega o array contacts (ver message.sent).

Erros de validação (400):

Mensagem Causa
too many contacts: at most 50 per send contacts[] excedeu o cap de 50 itens
vcard must be a vCard 3.0 string (BEGIN/END:VCARD) under 8 KB vcard no nivel raiz não tem BEGIN:VCARD/END:VCARD ou passou de 8 KB
contacts[N]: vcard must be a vCard 3.0 string (BEGIN/END:VCARD) under 8 KB Item N do array contacts com vcard inválido ou oversized
valid contact_name and contact_phone (or a vcard) are required Modo legacy: faltou contact_name, ou contact_phone não está em E.164 com +
contacts[N]: valid contact_name and contact_phone (or a vcard) are required Item N do array sem contact_name+contact_phone válidos nem vcard

POST/v1/instances/{instanceId}/messages/reaction#

Envia reacao (emoji) a uma mensagem.

Auth: Todos autenticados

Request:

json
{
  "to": "554137984905",
  "message_id": "198d2663-d6a7-4d62-a018-963065c80403",
  "emoji": "👍"
}
Campo Tipo Obrigatório Descricao
to string sim JID do chat onde está a mensagem
message_id string sim UUID Catcher (elemento de message_ids nos webhooks) OU hex WhatsApp da mensagem-alvo. A API resolve internamente; retorna 404 MESSAGE_NOT_FOUND se o UUID não existir nesta instância.
emoji string sim Emoji da reacao (string vazia para remover)

POST/v1/instances/{instanceId}/messages/poll#

Cria uma enquete.

Auth: Todos autenticados

Request:

json
{
  "to": "554137984905",
  "question": "Qual o melhor dia para a reuniao?",
  "options": ["Segunda", "Terca", "Quarta"],
  "max_selections": 1
}
Campo Tipo Obrigatório Descricao
to string sim Destinatário
question string sim Pergunta da enquete
options []string sim Opcoes (mínimo 2)
max_selections int não Máximo de selecoes por pessoa. Padrão: 1

POST/v1/instances/{instanceId}/messages/template#

Envia mensagem com botoes (template). Requer conta WhatsApp Business.

Auth: Todos autenticados

Request:

json
{
  "to": "554137984905",
  "body_text": "Escolha uma opcao abaixo:",
  "footer_text": "Powered by Catcher",
  "buttons": [
    {"text": "Comprar", "id": "btn_buy"},
    {"text": "Cancelar", "id": "btn_cancel"}
  ]
}
Campo Tipo Obrigatório Descricao
to string sim Destinatário
body_text string sim Texto principal
footer_text string não Texto do rodape
buttons []object sim 1 a 3 botoes
buttons[].text string sim Texto exibido no botao
buttons[].id string sim ID do botao (retornado no callback)

Nota: Se a instância não for uma conta Business, a mensagem será rejeitada sem retry.


POST/v1/instances/{instanceId}/messages/link-preview#

Envia uma mensagem de texto com card de preview de link controlado (você define título e descrição). Renderiza no destinatário (tipo nativo ExtendedTextMessage).

Auth: Todos autenticados · Header: Idempotency-Key obrigatório

Preview NÃO é o default. Um link num POST /messages/text comum vai como texto puro — o app do destinatário PODE gerar um preview básico do lado dele (fetch client-side), mas isso não é garantido nem controlado por você. Para um card com título/descrição garantidos, use este endpoint.

Request:

json
{
  "to": "554137984905",
  "text": "Conhece a Catcher? https://catcher.one",
  "url": "https://catcher.one",
  "title": "Catcher",
  "description": "WhatsApp API multi-tenant"
}
Campo Tipo Obrigatório Descrição
to string sim Destinatário
text string sim Corpo da mensagem (deve conter a URL)
url string sim URL do preview
title string não Título do card
description string não Descrição do card
quoted_id string não UUID Catcher OU hex WhatsApp da mensagem citada

Retorna 202 com message_id (UUID Catcher) + task_id + idempotency_key. Emite message.sent (message_type: text).


POST/v1/instances/{instanceId}/messages/event#

Envia uma mensagem de evento (calendário). Tipo nativo EventMessage — renderiza no destinatário.

Auth: Todos autenticados · Header: Idempotency-Key obrigatório

Request:

json
{
  "to": "554137984905",
  "name": "Reunião de planejamento",
  "description": "pauta trimestral",
  "start_at": "2026-05-30T15:00:00Z",
  "end_at": "2026-05-30T16:00:00Z",
  "location": "Online"
}
Campo Tipo Obrigatório Descrição
to string sim Destinatário (1:1 ou grupo @g.us)
name string sim Nome do evento
start_at string sim Início (RFC3339)
description string não Descrição
end_at string não Fim (RFC3339)
location string não Local
link string não Link de chamada/join

Retorna 202. Emite message.sent (message_type: event).


POST/v1/instances/{instanceId}/messages/ptv#

Envia um vídeo redondo (PTV / "video note"). Mesma origem de mídia dos outros sends (media_url / media_id / multipart). Tipo nativo PtvMessage.

POST/v1/instances/{instanceId}/messages/gif#

Envia um vídeo animado marcado como GIF (autoplay/loop no destinatário, gifPlayback=true). Mesma origem de mídia.

Ambos: 202 + Idempotency-Key obrigatório; emitem message.sent (message_type: ptv / gif).


view_once (flag de mídia)#

POST /messages/image, /video e /audio aceitam "view_once": true no corpo — a mídia vira visualização única (viewOnceMessage, auto-destrói após aberta). Default false.

json
{ "to": "554137984905", "media_url": "https://...", "view_once": true }

Status / Stories (§13.3)#

Posta um status (story). Nativo e render-safe: a whatsmeow envia para status@broadcast e resolve a audiência automaticamente das configurações de privacidade de status do número (quem vê), cifrando o fan-out. Sem to — status é um broadcast. Anti-spam guard não se aplica (broadcast, não 1:1); o throttle de pacing continua valendo.

Auth: Todos autenticados · Header: Idempotency-Key obrigatório nos POSTs.

POST /v1/instances/{instanceId}/messages/status/text#

json
{ "text": "Meu status ✨", "background_color": "#1FA75B", "font": 6 }
Campo Tipo Obrigatório Descrição
text string sim Texto do status
background_color string não Cor de fundo #RRGGBB
font int não Fonte (0=sistema, 1=system_text, 2=fb_script, 6=system_bold, 7=morningbreeze, 8=calistoga, 10=courierprime_bold)

POST /v1/instances/{instanceId}/messages/status/image#

POST /v1/instances/{instanceId}/messages/status/video#

json
{ "media_url": "https://...", "caption": "legenda opcional" }

Aceita media_url (resolvido sincronamente pra media_id), media_id (upload prévio em /media) OU media_base64 (data-URI ou base64 puro). Exatamente um.

POST /v1/instances/{instanceId}/messages/status/audio#

Posta um áudio (PTT) como status. Mesmo pipeline do /messages/audio: formatos não-OGG são convertidos para OGG Opus mono 16 kHz; waveform de 64 bytes gerada.

json
{ "media_url": "https://exemplo.com/audio.mp3" }

Aceita media_url, media_id OU media_base64 (exatamente um). Sem to (broadcast).

Todos os POSTs de status retornam 202 com message_id (UUID Catcher); emitem message.sent (message_type: status_text / status_image / status_video / status_audio).

POST /v1/instances/{instanceId}/status/{statusId}/media#

Baixa sob demanda a mídia (foto/vídeo/áudio) de UM status de contato. Por padrão a mídia de status não é baixada automaticamente (status_media_download nas configurações da instância); o worker guarda só a referência, e esta rota busca os bytes pelo proxy da instância, grava no armazenamento da Catcher e devolve o media_id (nunca uma URL da Meta). statusId é o status_message_id do status.received. Baixe enquanto o status existe: a mídia some do WhatsApp em poucos dias. Chamadas repetidas para o mesmo status devolvem o mesmo media_id sem baixar de novo, e cada instância faz no máximo 2 downloads de status ao mesmo tempo. Só provider wwebjs: no whatsmeow o status.received não traz mídia e esta rota responde 404 MEDIA_NOT_REDOWNLOADABLE.

Auth: Owner, Admin · sem body.

Resposta 200:

json
{ "media_id": "b2c3d4e5-...", "status": "downloaded" }

status: "already_present" quando a mídia já tinha sido baixada. Depois, leia com GET /v1/instances/{instanceId}/media/{mediaId}.

Erro Quando
400 BAD_REQUEST statusId inválido
404 INSTANCE_NOT_FOUND instância não existe ou não é sua
404 MEDIA_NOT_REDOWNLOADABLE status sem mídia, sem referência salva ou mídia expirada
502 MEDIA_FETCH_FAILED falha temporária ao baixar (pode tentar de novo)
429 RATE_LIMITED a instância já tem 2 downloads de status em andamento; tente em instantes

POST /v1/instances/{instanceId}/status/{statusId}/reply#

Responde (comenta) o status de um contato. statusId (URL) é o status_message_id recebido no webhook status.received (UUID Catcher ou hex WhatsApp). A resposta chega ao autor como uma DM 1:1 com atribuição de status.

Auth: Todos autenticados · Header: Idempotency-Key obrigatório.

json
{ "poster_phone": "554196332719", "type": "text", "text": "Curti demais esse story!" }
Campo Tipo Obrigatório Descrição
poster_phone string sim Telefone do autor do status (destino da resposta 1:1)
type string não text (default) | image | video | sticker
text string sim p/ text Texto da resposta
media_url / media_id / media_base64 string sim p/ não-text Origem da mídia (exatamente um) — resolvido sync pra media_id
caption string não Legenda (image/video)

Retorna 202 com message_id. Emite o evento executor status.reply_sent ({chat, phone, status_message_id, type, timestamp}) e persiste a resposta em status_feed (direction=outbound). O autor do status vê status.reply.

gif não é um tipo de reply (não há type: gif); use image/video/sticker.

GET /v1/instances/{instanceId}/status#

Auth: Todos autenticados

Lista o feed de status persistido (próprios postados + recebidos de contatos), da tabela tenant status_feed. Paginado.

Query Tipo Default Descrição
direction string (ambos) inbound (recebidos) | outbound (postados por mim)
limit int 50 Máximo de itens (cap 100)
page int 1 Página
json
{
  "data": [
    { "status_message_id": "3EB0...", "direction": "inbound", "phone": "554196332719",
      "type": "image", "content": "bom dia", "media_id": "med_...",
      "posted_at": "2026-05-25T12:01:00Z" },
    { "status_message_id": "c710cea9-...", "direction": "outbound",
      "type": "text", "content": "Meu status ✨", "media_id": "",
      "posted_at": "2026-05-25T11:40:00Z" }
  ],
  "page": 1, "limit": 50, "total": 2
}
Campo do item Descrição
status_message_id hex WhatsApp do status (ou UUID quando conhecido)
direction inbound (recebido) | outbound (postado por mim)
phone telefone do autor (vazio nos outbound)
type text | image | video | audio
content texto / legenda
media_id Catcher media_id (vazio em text); nunca uma URL da Meta CDN
posted_at timestamp do status

Mídia sempre como media_id (cacheada no R2 via proxy da instância). Use GET .../media/{mediaId} para baixar.

GET /v1/instances/{instanceId}/status/{statusId}#

Auth: Todos autenticados

Detalhe de um item do feed (statusId = status_message_id, UUID Catcher ou hex). Mesma forma de um item do array de GET .../status. 404 se não existe no feed.

GET /v1/instances/{instanceId}/status/privacy#

Auth: Owner/Admin

Retorna quem pode ver o status do número.

json
{ "status_privacy": [ { "type": "contacts", "list": [], "is_default": true } ] }

type: contacts | blacklist | whitelist. list: telefones (para black/whitelist).

GET /v1/instances/{instanceId}/status/{statusId}/views#

Auth: Owner/Admin

Contagem de visualizações + lista de quem viu UM status seu. statusId é o message_id retornado ao postar (UUID Catcher) ou o id bruto do WhatsApp. A contagem é de viewers únicos (um por contato, mesmo que reabra o status).

json
{
  "status_message_id": "c710cea9-fcc4-4a7c-9e30-1a19ebc07bfb",
  "count": 2,
  "viewers": [
    { "phone": "554196332719", "jid": "216251804708983@lid", "receipt_type": "read",   "viewed_at": "2026-05-23T18:48:26Z" },
    { "phone": "554163475715", "jid": "...@lid",             "receipt_type": "played", "viewed_at": "2026-05-23T18:49:01Z" }
  ]
}

receipt_type: read (status aberto) | played (vídeo assistido). Sem visualizações ainda → count: 0, viewers: [].

Webhooks de status — recepção (interações com seu status)#

A Catcher emite um evento dedicado para cada interação. Compartilhamento não é observável pelo autor (o WhatsApp não notifica o autor quando alguém compartilha).

Semântica de público (audience) — vale para TODOS os eventos de recepção abaixo. Status são entregues ao público do autor: contatos salvos na agenda do número, filtrados pela privacidade de status ("Meus contatos" / exceções). Você só recebe status.received de um contato cujo status alcança a sua instância, e só recebe status.viewed/status.reaction/status.reply de quem está no SEU público. Trocar DM com um número não o coloca no público de status de nenhum dos lados — é preciso estar salvo na agenda. Em testes entre instâncias de API que não se têm salvas, o POST .../status/* envia com sucesso (você vê message.sent no autor), mas a outra instância não emite status.received — isso é esperado, não é bug. Um aviso Server returned different participant list hash … no log do worker é a computação do público, não uma falha de envio.

status.received — um contato postou um status/story (antes era descartado):

json
{ "phone": "5511999999999", "from": "5511999999999@s.whatsapp.net",
  "status_message_id": "3EB0...", "type": "text|image|video|audio",
  "content": "...", "has_media": true, "mime_type": "image/jpeg",
  "timestamp": 1779543210 }

Mídia de status não é baixada por padrão (provider wwebjs). Uma linha movimentada recebe milhares de status por dia, e baixar todos pelo proxy da instância é tráfego que nenhuma pessoa gera. Com status_media_download=false (o padrão), o evento chega com has_media: true e sem media_id; para baixar a mídia de um status específico, use POST /v1/instances/{instanceId}/status/{statusId}/media. Ligando status_media_download em PATCH .../settings, o evento volta a trazer media_id (a mudança vale em até 1 minuto).

Convenção de campos (igual a todos os eventos): phone = telefone do interagente (resolvido), from = JID dele (pode ser um LID em status@broadcast).

status.viewed — um contato VISUALIZOU um status SEU (recibo read/played):

json
{ "phone": "554196332719", "from": "216251804708983@lid",
  "status_message_id": "c710cea9-...",
  "status_type": "image", "receipt_type": "read", "timestamp": 1779565914 }

status.reaction — um contato REAGIU a um status SEU:

json
{ "phone": "554196332719", "from": "216251804708983@lid", "push_name": "Adriano",
  "status_message_id": "c710cea9-...",
  "status_type": "image", "emoji": "💚", "removed": false, "timestamp": 1779565792 }

removed: true (e emoji: "") quando a reação foi removida.

status.reply — um contato RESPONDEU/comentou um status SEU. A message.received do DM continua disparando normalmente; este evento traz o contexto do status:

json
{ "phone": "554196332719", "from": "216251804708983@lid", "push_name": "Adriano",
  "status_message_id": "c710cea9-...",
  "status_type": "image", "reply_message_id": "0a279...",
  "reply_type": "text", "content": "😍", "timestamp": 1779566005 }

Mensagens interativas (botões / PIX / OTP / carrossel / lista) — DESATIVADAS#

Os endpoints POST /messages/button, /button-pix, /button-otp e /option-list existem no código mas estão desativados e retornam 403 INTERACTIVE_DISABLED.

Por quê: o spike de 2026-05-23 provou que os clientes WhatsApp do destinatário descartam silenciosamente mensagens interativas (InteractiveMessage/ListMessage) enviadas pelo protocolo multi-device não-oficial — não renderizam, nem como texto. O Baileys (referência da indústria) nunca shipou envio de botão pelo mesmo motivo. Enviar tipos não suportados é risco de ban sem ganho. Ficam prontos para reativar se a Meta passar a suportar. Detalhe em docs/COMPARATIVO-ZAPI-BIAZAP.md §15.9.

POST /v1/instances/{instanceId}/messages/button#

Retorna 403 INTERACTIVE_DISABLED enquanto mensagens interativas seguem desativadas.

POST /v1/instances/{instanceId}/messages/button-pix#

Retorna 403 INTERACTIVE_DISABLED enquanto mensagens interativas seguem desativadas.

POST /v1/instances/{instanceId}/messages/button-otp#

Retorna 403 INTERACTIVE_DISABLED enquanto mensagens interativas seguem desativadas.

POST /v1/instances/{instanceId}/messages/option-list#

Retorna 403 INTERACTIVE_DISABLED enquanto mensagens interativas seguem desativadas.


POST/v1/instances/{instanceId}/messages/forward#

Encaminha uma mensagem existente para outro chat.

Auth: Todos autenticados

Request:

json
{
  "to": "5541988888888",
  "forward_chat_id": "554137984905@s.whatsapp.net",
  "message_id": "198d2663-d6a7-4d62-a018-963065c80403"
}
Campo Tipo Obrigatório Descricao
to string sim Destinatário do encaminhamento
forward_chat_id string sim JID do chat onde a mensagem original está
message_id string sim UUID Catcher (elemento de message_ids nos webhooks) OU hex WhatsApp da mensagem a encaminhar. A API resolve internamente; retorna 404 MESSAGE_NOT_FOUND se a mensagem (UUID ou hex) não estiver no histórico desta instância, ou se nunca chegou ao WhatsApp (sem id WhatsApp).

Funciona com todos os tipos: texto, imagem, video, audio, documento.

Quando o encaminhamento é impossível (desde 2026-09-19). Encaminhar exige que a mensagem de origem ainda exista no WhatsApp para este aparelho. O que a API já sabe no momento da request é recusado na porta, sem 202, sem enfileirar nada e sem tocar a Meta:

HTTP error_code Condição
422 FORWARD_SOURCE_DELETED A origem foi apagada para todos (pelo autor, ou pelo DELETE desta API) — ela recebeu um evento *.deleted. Use o código (ou o próprio *.deleted) para esconder "Encaminhar" nessa mensagem.
404 MESSAGE_NOT_FOUND A origem não está no histórico desta instância, ou nunca chegou ao WhatsApp.
json
{ "error_code": "FORWARD_SOURCE_DELETED", "message": "the source message was deleted for everyone and can no longer be forwarded", "trace_id": "…" }

O que só o aparelho descobre chega depois do 202, como <tipo>.delivery_failed com wire_state: "not_sent" (nada saiu) e reason específico — nunca mais retry_exhausted para estes casos:

reason Condição Retentado?
forward_source_not_found A origem não existe no WhatsApp deste aparelho: apagada sem que o evento tenha chegado, reportada como enviada mas que nunca existiu (os envios de mídia do incidente de 2026-09-18), ou fora do histórico que o aparelho vinculado carregou. Não — a origem não volta a existir.
forward_source_deleted A origem foi apagada para todos depois do 202 (o worker recheca antes de despachar — no whatsmeow isso impede reenviar o proto guardado), ou o aparelho a encontrou como "apagada para todos". Não.
forward_source_media_unavailable A mídia da origem saiu do store do WhatsApp Web (evita encaminhar um arquivo vazio). Reenvie a mídia. Não.
forward_unavailable O módulo de encaminhamento do WhatsApp Web não carregou nesta sessão (o caso de 2026-09-16). Sim, até a validade do envio; reason só aparece se esgotar.
instance_not_connected A sessão não estava pronta. Sim, enquanto a instância quer estar conectada.

O evento de falha sai na família do conteúdo de origem, igual ao de sucesso: encaminhar uma imagem que falha emite image.delivery_failed (message_type: "image"). Só quando a origem nem está mais no nosso histórico o tipo não é conhecido e o evento sai como message.delivery_failed com message_type: "forward".

É um forward de verdade, não um reenvio — com a semântica do cliente oficial. O selo "Encaminhada" segue a AUTORIA da origem, igual ao app oficial: encaminhar uma mensagem recebida (ou uma cópia que já era forward) carrega ContextInfo.isForwarded=true + forwardingScore = cadeia da origem +1, e o destinatário vê o selo; encaminhar uma mensagem sua (enviada pela própria instância, nunca encaminhada) sai como cópia limpa, SEM selo — é o que o WhatsApp oficial faz, e o forward() nativo do WhatsApp Web (provider wwebjs) aplica sozinho. No whatsmeow a API estampa o proto com a mesma regra. O evento emitido é o da família do CONTEÚDO de origem, não uma família forward: encaminhar um vídeo emite video.sent com o content da mensagem original e o media_id/mime_type/file_name/file_size da mídia de origem (a MESMA mídia, baixável pelo endpoint de media). is_forwarded/forwarding_score no evento refletem o fio: presentes no forward de conteúdo recebido, ausentes na cópia limpa de mensagem própria — a row persistida (forwarded) idem. Encaminhamentos feitos fora da API (celular/WhatsApp Web) são capturados com a mesma marcação — ver is_forwarded em message.received e message.sent.


DELETE/v1/instances/{instanceId}/messages/{messageId}#

Apaga uma mensagem enviada ("apagar para todos").

Auth: Todos autenticados

Request:

json
{
  "to": "554137984905",
  "message_id": "198d2663-d6a7-4d62-a018-963065c80403"
}
Campo Tipo Obrigatório Descricao
to string sim JID do chat
message_id string sim UUID Catcher (elemento de message_ids nos webhooks) OU hex WhatsApp da mensagem a apagar. A API resolve internamente; retorna 404 MESSAGE_NOT_FOUND se o UUID não existir nesta instância.

Resposta 202:

json
{
  "status": "queued",
  "task_id": "asynq:task:xxxx"
}

PUT/v1/instances/{instanceId}/messages/{messageId}/edit#

Edita o texto de uma mensagem enviada — o corpo de uma mensagem de texto OU a legenda (caption) de uma mensagem de mídia (image, video, document, gif, ptv). A edicao de caption preserva a mídia original intacta (nenhum re-upload; o destinatário vê a mesma mídia com a legenda nova + o selo "editada"). Tipos sem texto editável (audio, sticker, location, contact, reaction, poll, ...) são recusados com EDIT_UNSUPPORTED_TYPE. Mídia view-once não é editável (o próprio WhatsApp não oferece — a mensagem é efêmera); a edicao falha de forma assincrona com erro permanente e message.delivery_failed.

A API impoe sincronamente a janela de edicao do WhatsApp (~15 minutos após o envio): passado esse prazo os clientes destinatários ignoram a edicao, então a request retorna 400 EDIT_WINDOW_EXPIRED em vez de aceitar uma edicao fantasma que nunca renderiza.

Mensagens encaminhadas não são editáveis — o WhatsApp não permite (no app oficial a acao "Editar" nem aparece num forward, e o runtime da WA Web recusa a operacao). A API recusa sincronamente com 400 EDIT_FORWARDED_NOT_ALLOWED, sem enfileirar nada e sem tocar a Meta. Use o codigo pra esconder/desabilitar a acao de editar em mensagens com is_forwarded: true.

Mensagem enviada por OUTRO aparelho não é editável numa instância wwebjs. A WA Web só edita o que ela mesma enviou (a regra dela é msg.local || edição entre aparelhos liberada, e a Meta mantém a edição entre aparelhos desligada). Uma mensagem que saiu do celular, ou da API oficial (Cloud API) num número em coexistência, chega como eco com source: "external" e não pode ser editada por aqui. A API recusa sincronamente com 400 EDIT_OTHER_DEVICE_NOT_ALLOWED, sem enfileirar nada e sem tocar a Meta. Edite pelo mesmo canal que enviou a mensagem, ou esconda a acao de editar quando source for "external". Mensagens enviadas pela própria instância (source: "api") continuam editáveis.

Providers: whatsmeow e wwebjs suportam texto + caption. meta_cloud (canal oficial) não suporta edicao (limitação da Cloud API da Meta) — a operação falha de forma assincrona.

Auth: Todos autenticados

Request:

json
{
  "content": "Susiane, segue orientações do seu pós procedimento 🥰"
}
Campo Tipo Obrigatório Descricao
content string sim Novo texto da mensagem (texto) ou nova legenda (mídia)

Resposta 202:

json
{
  "status": "queued",
  "task_id": "asynq:task:xxxx"
}

Erros:

Código Descricao
400 content is required — conteúdo vazio
400 only outbound messages can be edited — mensagem não foi enviada pela instância
400 EDIT_UNSUPPORTED_TYPE — o tipo da mensagem não tem texto editável (só texto e captions de image/video/document/gif/ptv)
400 EDIT_WINDOW_EXPIRED — a janela de ~15 minutos do WhatsApp expirou; o destinatário ignoraria a edicao
400 EDIT_FORWARDED_NOT_ALLOWED — o alvo é uma mensagem encaminhada; o WhatsApp não permite editar forwards
400 EDIT_OTHER_DEVICE_NOT_ALLOWED — instância wwebjs e o alvo foi enviado por outro aparelho (celular ou API oficial; source: "external"); o WhatsApp só deixa editar quem enviou
400 cannot edit a deleted message — mensagem já foi deletada
404 message not found — messageId não encontrado (UUID inexistente nesta instância OU hex desconhecido)

O messageId na URL aceita o UUID Catcher (elemento de message_ids nos webhooks) OU o hex WhatsApp (whats_app_id) — o MESMO id para texto e mídia. A API resolve internamente; UUID inexistente retorna 404 MESSAGE_NOT_FOUND. Após a edicao, o webhook message.edited e emitido com is_from_me: true, new_content (o texto/caption novo) e message_type (o tipo da mensagem editada — text, image, video, ...). Com EVENT_NAMING=specific o evento sai como <tipo>.edited (image.edited, video.edited, ...); a assinatura genérica message.edited cobre as formas específicas.


POST/v1/instances/{instanceId}/messages/{messageId}/redownload-media#

Re-baixa a mídia de uma mensagem cujo media_id voltou NULL (a mídia não foi capturada no recebimento). Operação manual de recuperação — funciona nos DOIS providers: instâncias wwebjs vão pro worker Node (download in-page; só funciona enquanto a mensagem ainda está no store vivo do WhatsApp Web — depois disso ela é evicted e não há recuperação); instâncias whatsmeow re-baixam a partir do proto armazenado, pelo proxy da instância. Os bytes vão pro R2 e a resposta devolve APENAS o media_id da BiaZap — nunca uma URL de CDN da Meta.

Auth: Todos autenticados

Request: sem corpo. O messageId na URL aceita o UUID Catcher OU o hex WhatsApp.

Resposta 200:

json
{
  "media_id": "a1b2c3d4-...",
  "status": "redownloaded"
}
status Significado
redownloaded A mídia foi re-baixada agora e o media_id foi gravado na mensagem.
already_present A mensagem já tinha media_id — nada a fazer (idempotente).

Erros:

Código error_code Descricao
404 MESSAGE_NOT_FOUND messageId não encontrado nesta instância (UUID inexistente OU hex desconhecido).
404 MEDIA_NOT_REDOWNLOADABLE A mídia não é recuperável: wwebjs já fez eviction da mensagem do store vivo, ou a linha whatsmeow não tem proto armazenado.
502 MEDIA_FETCH_FAILED Falha transitória no download (proxy/CDN/rede/storage) — pode funcionar numa nova tentativa.

A mídia recuperada é exposta SOMENTE como media_id (baixe via GET /v1/instances/{id}/media/{mediaId}). Nenhuma URL da Meta atravessa a resposta.


7.X Ações sobre mensagens (Wave 1 — Z-API parity)#

Três endpoints síncronos que operam sobre uma mensagem existente: fixar (pin), votar em enquete (poll-vote) e favoritar (star). Diferente dos sends de conteúdo, esses endpoints respondem 200 OK (não 202) porque atuam direto via RPC no worker — sem fila Asynq, sem Idempotency-Key obrigatório, sem anti-spam guard pesado.

Os 3 endpoints aceitam o message_id em qualquer formato (UUID Catcher OU hex WhatsApp). A API resolve internamente.


POST /v1/instances/{instanceId}/messages/pin#

Fixa ou desfixa uma mensagem no chat para todos os participantes. Em grupos, requer que a instância seja admin.

Request:

json
{
  "chat_jid": "554163475715@s.whatsapp.net",
  "message_id": "198d2663-d6a7-4d62-a018-963065c80403",
  "target_sender_jid": "",
  "target_from_me": true,
  "pin": true,
  "duration_seconds": 86400
}
Campo Tipo Obrigatório Descrição
chat_jid string sim Chat onde a mensagem está.
message_id string sim UUID Catcher OU hex WhatsApp da mensagem-alvo.
target_sender_jid string não JID de quem enviou a mensagem-alvo. Em DM, default = chat_jid. Obrigatório em grupos.
target_from_me bool não Se a mensagem foi enviada pela instância. Default false.
pin bool sim true = PIN_FOR_ALL, false = UNPIN_FOR_ALL.
duration_seconds int não 86400 (24h) / 604800 (7d) / 2592000 (30d). 0 = WhatsApp default (24h). Ignorado em unpin.

No provider wwebjs, fixar/desfixar vai pelo WhatsApp Web (Message.pin/unpin): envelope_message_id volta vazio (o WhatsApp Web não expõe o id do envelope), uma recusa do WhatsApp (prazo sem opção correspondente, mensagem não fixável) volta como erro com PIN_REFUSED, e uma mensagem que o aparelho não tem volta 404.

Response 200 OK:

json
{
  "instance_id": "48a1322e-f3b1-4a32-ac79-58f67036af79",
  "chat_jid": "554163475715@s.whatsapp.net",
  "target_message_id": "3EB01870039BE5362C6F0A",
  "action": "pinned",
  "envelope_message_id": "3EB0ABC123..."
}

envelope_message_id é o ID do WhatsApp da própria mensagem PIN (não da mensagem fixada).


POST /v1/instances/{instanceId}/messages/poll-vote#

Vota em uma enquete existente. A instância precisa ter recebido a enquete (whatsmeow precisa do segredo da poll pra re-encriptar).

Request:

json
{
  "chat_jid": "554163475715@s.whatsapp.net",
  "poll_message_id": "3EB0CAFEBABE123",
  "poll_sender_jid": "",
  "poll_from_me": false,
  "selected_options": ["sim", "muito legal"]
}
Campo Tipo Obrigatório Descrição
chat_jid string sim Chat onde a poll está.
poll_message_id string sim UUID Catcher OU hex WhatsApp da mensagem de criação da poll.
poll_sender_jid string não Quem criou a poll. Em DM, default = chat_jid.
poll_from_me bool não Se a instância criou a poll. Default false.
selected_options array de strings sim Nomes exatos das opções votadas. [] vazio limpa o voto.

Response 200 OK:

json
{
  "instance_id": "...",
  "chat_jid": "554163475715@s.whatsapp.net",
  "poll_message_id": "3EB0CAFEBABE123",
  "selected_options": ["sim", "muito legal"],
  "envelope_message_id": "3EB0VOTE..."
}

Voto é uma PollUpdateMessage cifrada com o segredo da poll original. Se a instância não tem o segredo (poll foi enviada antes da instância existir, ou após reset de sessão), o envio falha com 404.


POST /v1/instances/{instanceId}/messages/star#

Favorita ou desfavorita uma mensagem. Muda só no AppState da instância — propaga pros outros devices via sync (não é visível pro destinatário).

Request:

json
{
  "chat_jid": "554163475715@s.whatsapp.net",
  "message_id": "198d2663-d6a7-4d62-a018-963065c80403",
  "sender_jid": "",
  "from_me": true,
  "starred": true
}
Campo Tipo Obrigatório Descrição
chat_jid string sim Chat onde a mensagem está.
message_id string sim UUID Catcher OU hex WhatsApp.
sender_jid string não Quem enviou. Em DM, default = chat_jid. Obrigatório em grupos.
from_me bool não Se a instância enviou. Default false.
starred bool sim true = favoritar, false = desfavoritar.

Response 200 OK:

json
{
  "instance_id": "...",
  "chat_jid": "554163475715@s.whatsapp.net",
  "message_id": "3EB01870...0A",
  "action": "starred"
}

Mudança propaga pros outros devices da operadora via appstate sync. Webhook message.starred é emitido quando a propagação retorna pelo whatsmeow.