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-Keynão cria uma nova task. - O retry recebe o estado atual do mesmo request (
queued,sentoufailed) com o mesmomessage_ide o mesmotask_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-SendeLast-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:
{
"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 demessage_idsnos webhooksmessage.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_idda resposta 202).idempotency_key— eco do header enviado pelo cliente. Também aparece no webhookmessage.sent(campoidempotency_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 (usemessage_idouidempotency_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_ide o estado atual (queued,sentoufailed) sem enfileirar duplicidade. Este e o caminho oficial para um cliente recuperar omessage_idcaso 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 emmessage_idsnos 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óprioquoted_id, ou os camposquoted_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.
// 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 viaPOST /v1/instances/{instanceId}/messages/scheduled. Oquoted_stricté aceito nos endpoints JSON; no multipart use o campo de formulárioquoted_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áCONNECTEDnaquele 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_CONNECTEDsó é 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 comstatus=queuede o motivo emfail_reason— não aparece comofailed. Ela só virafailed(e emitemessage.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 mesmomessage_id(o UUID retornado no202). 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 dereason.
(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:
{
"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 logaudit_action=passive_mode.force_send). - Modo passivo falha fechado: um erro transitorio no banco do tenant retorna
503/500em 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(defaulttrue). - O limite seguido sem resposta é opcional (
contact_limit_mode, defaultoff): comtemperaturesóBLOCKED_TEMPERATURE_LIMITpode disparar, comfixedsóBLOCKED_NO_RECIPROCITY, comoffnenhum dos dois. Os dois nunca rodam ao mesmo tempo. delete,edit,reactioneforwardsã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 logaudit_action=anti_spam.force_send).
POST/v1/instances/{instanceId}/messages/text#
Envia mensagem de texto.
Auth: Todos autenticados
Request:
{
"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, defaulttrue). - Quando ativo, o processor envia
composingimediatamente antes deSendTexte esperanumero_de_caracteres(texto) * multipliersegundos, commultiplieraleatorio entre0.1e0.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 owwebjssó aplicava a pausa.POST .../presencecomcomposing/recording/pausedtambém passa a funcionar nowwebjs.
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:
application/jsoncommedia_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 ummedia_idinterno e enfileira o envio usando esse ID.application/jsoncommedia_id: reutiliza uma mídia já armazenada pelo endpointPOST /v1/instances/{instanceId}/mediaou por mídia recebida.application/jsoncommedia_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 omedia_idgerado. Não há TTL de reaper (diferente deurl-cache).multipart/form-datacom campofile: envia o arquivo binario direto no próprio endpoint; a API armazena em R2, gera ummedia_ide 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_FAILEDno 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_urlagora levam ~500ms-2s a mais que commedia_id(tempo do download + upload R2). Para arquivos grandes (>10MB), considere fazer upload prévio viaPOST /v1/instances/{id}/mediae reutilizar omedia_idretornado. - Cache automático: cada
media_urlbaixado vira uma linha no R2 comsource="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 CDNna 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-Keye obrigatório em todas as tres formas de envio de mídia (igual aos demais endpoints de mensagem).
Exemplo com arquivo direto:
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:
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):
# 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):
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_urlOUmedia_idOUmedia_base64(exatamente um). Em multipart, enviefile. Uma dessas formas e obrigatória.
POST/v1/instances/{instanceId}/messages/image#
Envia imagem.
Auth: Todos autenticados
Request:
{
"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_base64OUfile(exatamente um e obrigatório; >1 em JSON retorna400).
POST/v1/instances/{instanceId}/messages/video#
Envia video.
Auth: Todos autenticados
Request:
{
"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_base64OUfile(exatamente um e obrigatório; >1 em JSON retorna400).
Á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:
{
"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_base64oufile.
Ciclo de vida:
sent → delivered → read → played. Oplayedchega 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:
{
"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_base64OUfile(exatamente um e obrigatório; >1 em JSON retorna400).
No envio multipart, o campo
pttdeve ser um booleano válido (true/false); valores inválidos retornam400 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:
{
"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_base64OUfile(exatamente um e obrigatório; >1 em JSON retorna400).
POST/v1/instances/{instanceId}/messages/sticker#
Envia sticker (figurinha). A imagem deve estar no formato WebP.
Auth: Todos autenticados
Request:
{
"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,fileOUsticker_id(exatamente um e obrigatório; >1 em JSON retorna400).
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.
{ "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:
{ "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_idoushortcut(400 MISSING_FIELDcom 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:
{
"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):
{
"to": "554137984905",
"contact_name": "Suporte Catcher",
"contact_phone": "+5541988887777"
}
Request — varios contatos:
{
"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):
{
"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 webhookmessage.sentresultante carrega o arraycontacts(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:
{
"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:
{
"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:
{
"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/textcomum 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:
{
"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:
{
"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.
{ "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#
{ "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#
{ "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.
{ "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:
{ "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.
{ "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.
gifnão é um tipo de reply (não hátype: gif); useimage/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 |
{
"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). UseGET .../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.
{ "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).
{
"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.receivedde um contato cujo status alcança a sua instância, e só recebestatus.viewed/status.reaction/status.replyde 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, oPOST .../status/*envia com sucesso (você vêmessage.sentno autor), mas a outra instância não emitestatus.received— isso é esperado, não é bug. Um avisoServer 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):
{ "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 comhas_media: truee semmedia_id; para baixar a mídia de um status específico, usePOST /v1/instances/{instanceId}/status/{statusId}/media. Ligandostatus_media_downloademPATCH .../settings, o evento volta a trazermedia_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):
{ "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:
{ "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:
{ "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:
{
"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. |
{ "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 oforward()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íliaforward: encaminhar um vídeo emitevideo.sentcom ocontentda mensagem original e omedia_id/mime_type/file_name/file_sizeda mídia de origem (a MESMA mídia, baixável pelo endpoint de media).is_forwarded/forwarding_scoreno 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 — veris_forwardedem message.received e message.sent.
DELETE/v1/instances/{instanceId}/messages/{messageId}#
Apaga uma mensagem enviada ("apagar para todos").
Auth: Todos autenticados
Request:
{
"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:
{
"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:
{
"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:
{
"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
messageIdna URL aceita o UUID Catcher (elemento demessage_idsnos webhooks) OU o hex WhatsApp (whats_app_id) — o MESMO id para texto e mídia. A API resolve internamente; UUID inexistente retorna404 MESSAGE_NOT_FOUND. Após a edicao, o webhookmessage.editede emitido comis_from_me: true,new_content(o texto/caption novo) emessage_type(o tipo da mensagem editada —text,image,video, ...). ComEVENT_NAMING=specifico evento sai como<tipo>.edited(image.edited,video.edited, ...); a assinatura genéricamessage.editedcobre 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:
{
"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 viaGET /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:
{
"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:
{
"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:
{
"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:
{
"instance_id": "...",
"chat_jid": "554163475715@s.whatsapp.net",
"poll_message_id": "3EB0CAFEBABE123",
"selected_options": ["sim", "muito legal"],
"envelope_message_id": "3EB0VOTE..."
}
Voto é uma
PollUpdateMessagecifrada 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 com404.
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:
{
"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:
{
"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. Webhookmessage.starredé emitido quando a propagação retorna pelo whatsmeow.