O corpo traz o destinatário em to, o type (text, template, image, video, audio, document, interactive ou location) e o conteúdo correspondente. O mesmo endpoint envia pelo WhatsApp e pelo Direct do Instagram (veja Enviar para o Instagram). A conta é derivada da chave de API, então você nunca passa um id de conta. Os exemplos de envio abaixo usam uma chave de sandbox (bz_sandbox_): funcionam sem número real, sem credenciais da Meta e sem consumir quota; troque para uma chave bz_live_ quando for enviar de verdade. Os exemplos de erro mais adiante (número ambíguo, fora da janela, quota, falha da Meta) ilustram cenários de produção que o sandbox determinístico não reproduz.
Um envio aceito responde 201:
HTTP/1.1 201 Created
{
"id": "0f8a4c1e-5b7d-4e2a-9c3f-1a2b3c4d5e6f",
"wamid": "wamid.HBgNNTUzMTk4ODg4Nzc3NxUCABEYEjA...",
"to": "5531988887777",
"sent_to": "5531988887777",
"status": "sent"
}id é o UUID da mensagem na BotoZap e wamid o id dela na Meta; to é o destinatário que você endereçou (telefone só com dígitos) e sent_to é o endereço que foi de fato à Meta (veja Destinatário). status: "sent" quer dizer que a Meta aceitou o envio, não que entregou: a entrega e a leitura chegam depois, como eventos no seu webhook (veja Eventos de webhook). A resposta ainda pode trazer warnings (ex.: consent_unspecified) e, no sandbox, sandbox: true.
Enviar um texto (sandbox)
Para type: "text", mande o corpo em text.body (até 4096 caracteres). Texto livre só é aceito dentro da janela de 24h (o contato precisa ter enviado uma mensagem nas últimas 24 horas); fora dela, use um template. O número mágico +5500000000001 sempre tem a janela aberta.
Enviar uma mensagem de texto (sandbox)
Testa o envio ponta a ponta sem credenciais Meta e sem custo, usando o número mágico de happy path do sandbox.
curl https://botozap.com.br/api/v1/messages \
-X POST \
-H "X-API-Key: $BOTOZAP_KEY" \
-H "Content-Type: application/json" \
-d '{
"to": "+5500000000001",
"type": "text",
"text": {
"body": "Oi! 👋 Tudo bem?"
}
}'Resposta 201
{
"id": "5b0a9d0e-6e1a-4f3b-8c2d-1a9f6e0b7c11",
"wamid": "wamid.HBgNNTU5MTk5OTk5OTk5FQIAERgSM0FCQzFEMkUzRjRBNUI2QzdEAA==",
"to": "5500000000001",
"sent_to": "5500000000001",
"status": "sent",
"sandbox": true
}Chave sandbox (`bz_sandbox_`) nunca chama a Meta e não consome cota. A origem é sempre o número sintético da conta; o destino pode ser qualquer telefone, e a entrega é simulada. Os números mágicos escolhem o cenário.
`to` é o destinatário que você endereçou, só com dígitos; `sent_to` é o endereço usado no envio. No sandbox os dois são iguais.
O número mágico de happy path mantém a janela de 24h sempre aberta. Para outros destinos, texto fora da janela é 422 `outside_window`, como em produção.
Depois do 201, o BotoZap simula o ciclo de vida (delivered → read no happy path) e dispara seu webhook assinado, como em produção.
Enviar um template (sandbox)
Para type: "template", informe o nome do template e o idioma em template.language.code. Templates reengajam contatos fora da janela de 24h. No sandbox qualquer nome é aceito (a Meta não é chamada); em produção, o template precisa existir e estar APPROVED na conta do WhatsApp — veja Templates para criar e acompanhar a aprovação.
Enviar um template (sandbox)
No sandbox, qualquer nome de template é aceito — a Meta não é chamada, então não há catálogo para validar contra.
curl https://botozap.com.br/api/v1/messages \
-X POST \
-H "X-API-Key: $BOTOZAP_KEY" \
-H "Content-Type: application/json" \
-d '{
"to": "+5500000000001",
"type": "template",
"template": {
"name": "boas_vindas",
"language": {
"code": "pt_BR"
}
}
}'Resposta 201
{
"id": "5b0a9d0e-6e1a-4f3b-8c2d-1a9f6e0b7c11",
"wamid": "wamid.HBgNNTU5MTk5OTk5OTk5FQIAERgSM0FCQzFEMkUzRjRBNUI2QzdEAA==",
"to": "5500000000001",
"sent_to": "5500000000001",
"status": "sent",
"warnings": [
{
"code": "consent_unspecified",
"message": "Consentimento de marketing não informado para este contato."
}
],
"sandbox": true
}Como no texto, o destino pode ser qualquer telefone: o sandbox simula a entrega sem chamar a Meta. Template não depende da janela de 24h.
Template fora do catálogo da conta conta como MARKETING para a guarda de consentimento. Sem Consentimento de marketing registrado para o contato, o envio segue e a resposta traz `warnings` com `consent_unspecified`.
Em produção (chave live), o template precisa existir e estar APPROVED na WABA; quem recusa um nome desconhecido é a Meta.
Template com variáveis, mídia e botões
Um template com {{1}}, {{2}}… no corpo, cabeçalho de mídia ou botão dinâmico precisa dos valores em template.components, no formato da Cloud API da Meta: um item por parte do template, com os valores em parameters, na ordem das variáveis.
POST /api/v1/messages
{
"to": "+5531988887777",
"type": "template",
"template": {
"name": "pedido_enviado",
"language": { "code": "pt_BR" },
"components": [
{
"type": "header",
"parameters": [
{ "type": "image", "image": { "link": "https://cdn.exemplo.com/pedido.jpg" } }
]
},
{
"type": "body",
"parameters": [
{ "type": "text", "text": "Maria" },
{ "type": "text", "text": "#4821" }
]
},
{
"type": "button",
"sub_type": "url",
"index": "0",
"parameters": [{ "type": "text", "text": "4821" }]
},
{
"type": "button",
"sub_type": "copy_code",
"index": "1",
"parameters": [{ "type": "coupon_code", "coupon_code": "BOTO10" }]
}
]
}
}- corpo —
{ "type": "body", "parameters": [...] }, um{ "type": "text", "text": "..." }por variável, na ordem{{1}},{{2}}…; - cabeçalho de texto com variável — o mesmo formato, em
"type": "header"(só uma variável); - cabeçalho de mídia (
image,videooudocument) — porlinkhttps público ou porid, omedia_idque POST /api/v1/media devolve. É o único lugar onde ummedia_idvale no envio:
{
"type": "header",
"parameters": [
{
"type": "document",
"document": { "id": "1234567890123456", "filename": "boleto-4821.pdf" }
}
]
}- botão de URL dinâmica —
"sub_type": "url"com o trecho variável da URL; botão de copiar código —"sub_type": "copy_code"comcoupon_code; resposta rápida —"sub_type": "quick_reply", opcionalmente com{ "type": "payload", "payload": "..." }. Oindexé a posição do botão no template, como texto ("0","1"…).
A BotoZap faz só uma checagem estrutural antes da Meta: components precisa ser uma lista de objetos, com no máximo 20 itens e 32 KB serializado — fora disso, 422 invalid_request. O resto (quantidade de parâmetros, tipo do cabeçalho, índice do botão) quem valida é a Meta, contra o template aprovado: um erro ali volta como 422 meta_error, com o código da Meta em error.meta_code (ex.: 132000, número de parâmetros diferente do template). No sandbox a Meta não é chamada, então components inválido para o template passa.
Consentimento no envio de template
Template de categoria MARKETING para um Contato com Consentimento de marketing revoked responde 422 consent_revoked. UTILITY e AUTHENTICATION não são bloqueados por essa revogação. Sem registro o envio segue e a resposta traz aviso consent_unspecified. O dev pode declarar a base legal com consent_basis (texto curto): grava granted com origem api e o envio segue. Para quem ainda não era contato, o aceite é gravado logo depois do envio; se essa gravação falhar, o template já saiu e a resposta 201 traz o aviso consent_basis_unrecorded: grave o consentimento em POST /api/v1/contacts/{id}/consents antes do próximo marketing. consent_basis não desfaz a recusa do contato: com marketing revoked, o envio responde 422 consent_revoked e nada é gravado. Só o próprio contato volta a aceitar (veja Recusa permanente). A recusa vale para todos os números do Cliente: o mesmo vale para um telefone que recusou por outro número do mesmo Cliente, ou que foi excluído depois de recusar, mesmo que ainda não seja contato do número de envio.
Erro: consentimento de marketing recusado
Template MARKETING para um Contato com Consentimento de marketing revoked responde 422 consent_revoked, com ou sem consent_basis: só o próprio contato desfaz a recusa. UTILITY e AUTHENTICATION não são bloqueados. Sem registro o envio segue com aviso; consent_basis grava o aceite (origem api) e o envio segue.
curl https://botozap.com.br/api/v1/messages \
-X POST \
-H "X-API-Key: $BOTOZAP_KEY" \
-H "Content-Type: application/json" \
-d '{
"to": "+5511988887777",
"type": "template",
"template": {
"name": "promo_semana",
"language": {
"code": "pt_BR"
}
}
}'Resposta 422
{
"error": {
"code": "consent_revoked",
"message": "Este contato recusou mensagens de marketing.",
"outcome": "rejected",
"retry": "after_correction",
"next_step": "Não repita o marketing para este contato: só ele desfaz a recusa. Templates UTILITY e AUTHENTICATION seguem liberados."
}
}A categoria vem do catálogo de templates da conta. Template fora do catálogo conta como MARKETING.
`consent_basis` não desfaz a recusa: o aceite não é gravado e a resposta é a mesma 422. Só o próprio contato volta a aceitar: tocando no botão do pedido de consentimento na conversa ou mandando uma Palavra de volta que o Cliente cadastrou.
A recusa vale para todos os números do Cliente: um telefone que recusou por outro número do mesmo Cliente, ou que foi excluído depois de recusar, também responde 422 `consent_revoked`, mesmo sem ser contato do número de envio. A recusa feita a outro Cliente da Conta não bloqueia.
Um template MARKETING para um Contato sem registro de consentimento responde 201 com `warnings` contendo `consent_unspecified`; com `consent_basis`, o aceite é gravado (origem `api`) e o envio segue.
Pedir consentimento na conversa
POST /api/v1/conversations/{id}/consent-request envia ao contato a mesma mensagem do "Pedir consentimento" do composer (botões no WhatsApp, respostas rápidas no Instagram), com o escopo messages:send. id é o UUID da conversa (o id de GET /api/v1/conversations). O corpo é opcional: purposes escolhe os botões (marketing e/ou utility; sem ele, só marketing) e body troca o texto padrão (até 1024 caracteres). O toque do contato num botão grava o aceite daquela Finalidade, com origem conversation_button, nos dois canais. A resposta traz channel; no Instagram, wamid é o mid do direct.
Só vale com a janela de 24h aberta: fora dela a resposta é 422 outside_window no WhatsApp e 422 window_closed no Instagram (a etiqueta de atendente humano não vale para respostas rápidas). O pedido não passa pelo bloqueio de consentimento: ele sai também para um contato com marketing revoked, porque o toque dele é um dos dois caminhos que desfazem a recusa; o outro é a Palavra de volta, que o Cliente cadastra e vale nos dois canais (veja Recusa permanente). Conta como uma resposta 1:1 do plano. Número sem conexão, plano, conta em exclusão e erros da Meta respondem com os mesmos códigos de Erros de envio. Se a Meta aceitar e a gravação falhar, a resposta continua 201, com id: null e o aviso send_unrecorded: não reenvie, o pedido já saiu.
Pedir consentimento na conversa
Envia ao contato a mensagem com botões do pedido de consentimento, a mesma do "Pedir consentimento" do composer. O toque do contato grava o aceite da Finalidade (origem `conversation_button`), inclusive para quem recusou: é o caminho de volta da recusa. Vale no WhatsApp (botões) e no Instagram (respostas rápidas), só com a janela de 24h aberta.
curl https://botozap.com.br/api/v1/conversations/5b0a9d0e-6e1a-4f3b-8c2d-1a9f6e0b7c11/consent-request \
-X POST \
-H "X-API-Key: $BOTOZAP_KEY" \
-H "Content-Type: application/json" \
-d '{
"purposes": [
"marketing",
"utility"
],
"body": "Quer receber nossas ofertas e avisos por aqui? Toque para confirmar."
}'Resposta 201
{
"data": {
"id": "5b0a9d0e-6e1a-4f3b-8c2d-1a9f6e0b7c11",
"wamid": "wamid.HBgNNTU5MTk5OTk5OTk5FQIAERgSM0FCQzFEMkUzRjRBNUI2QzdEAA==",
"conversation_id": "5b0a9d0e-6e1a-4f3b-8c2d-1a9f6e0b7c11",
"contact_id": "5b0a9d0e-6e1a-4f3b-8c2d-1a9f6e0b7c11",
"channel": "whatsapp",
"type": "interactive",
"status": "sent",
"sent_to": "5511999990001",
"purposes": [
"marketing",
"utility"
],
"body": "Quer receber nossas ofertas e avisos por aqui? Toque para confirmar."
}
}Corpo opcional. Sem `purposes`, o pedido é só de marketing (o padrão do composer). Sem `body`, vai o texto padrão do pedido. `body` aceita até 1024 caracteres; `purposes` aceita `marketing` e `utility`, cada um vira um botão.
Não passa pelo bloqueio de consentimento: o pedido sai também para um contato com marketing `revoked`, porque o toque dele no botão é o que desfaz a recusa.
Conta o envio como resposta 1:1 do plano, como uma mensagem de texto na janela. A mensagem fica na conversa como `interactive`, com a chave de API (ou a pessoa, no acesso por OAuth) como autora.
Se a Meta aceitar e a gravação falhar, a resposta continua 201, com `id: null` e um aviso `send_unrecorded` em `warnings`. Não reenvie: o pedido já saiu para o contato.
Conversa de outra Conta ou id que não é UUID: `404 not_found`. Chave sem o escopo `messages:send`: `403 forbidden_scope`.
Erro: pedido de consentimento fora da janela
O pedido com botões é uma mensagem livre: com a janela de 24h fechada, a API recusa antes de chamar a Meta, com o mesmo código de `POST /api/v1/messages`.
curl https://botozap.com.br/api/v1/conversations/5b0a9d0e-6e1a-4f3b-8c2d-1a9f6e0b7c11/consent-request \
-X POST \
-H "X-API-Key: $BOTOZAP_KEY"Resposta 422
{
"error": {
"code": "outside_window",
"message": "Fora da janela de 24h: este contato não enviou mensagem nas últimas 24h. Envie um template (type: 'template') para reengajar.",
"outcome": "rejected",
"retry": "after_correction",
"next_step": "Use um Template aprovado ou aguarde uma nova mensagem do Contato para abrir a janela de 24h."
}
}Pedir consentimento numa conversa do Instagram
No Instagram o pedido sai como texto com respostas rápidas (uma por Finalidade, até 20 caracteres no título), só com a janela de 24h aberta. O toque do contato volta no direct e grava o aceite com a origem `conversation_button`, como no WhatsApp. `wamid` traz o `mid` do direct.
curl https://botozap.com.br/api/v1/conversations/5b0a9d0e-6e1a-4f3b-8c2d-1a9f6e0b7c11/consent-request \
-X POST \
-H "X-API-Key: $BOTOZAP_KEY" \
-H "Content-Type: application/json" \
-d '{
"purposes": [
"marketing"
]
}'Resposta 201
{
"data": {
"id": "5b0a9d0e-6e1a-4f3b-8c2d-1a9f6e0b7c11",
"wamid": "aWdfZAG1pZAAMDeNeDEyMzQ1Njc4OTA",
"conversation_id": "5b0a9d0e-6e1a-4f3b-8c2d-1a9f6e0b7c11",
"contact_id": "5b0a9d0e-6e1a-4f3b-8c2d-1a9f6e0b7c11",
"channel": "instagram",
"type": "interactive",
"status": "sent",
"sent_to": "17841400000004322",
"purposes": [
"marketing"
],
"body": "Quer receber nossas mensagens de marketing? Toque para confirmar."
}
}Mesmo corpo e mesmas Finalidades do WhatsApp. O texto de `body` segue o teto de texto do direct. Com a janela de 24h fechada a resposta é `422 window_closed` no Instagram (`outside_window` no WhatsApp); a etiqueta de atendente humano não vale para respostas rápidas.
Mostrar "digitando…"
POST /api/v1/conversations/{id}/typing mostra "digitando…" ao contato enquanto a sua integração prepara a resposta, com o escopo messages:send e sem corpo. É o mesmo sinal do painel quando o atendente digita e do agente de IA quando vai responder. Ele vai na última mensagem recebida do contato, que fica como lida (tiques azuis no WhatsApp, "visto" no Instagram), e a Meta tira o indicador quando a resposta sai ou depois de cerca de 25 segundos.
É um limite da Meta: o indicador só existe em resposta a uma mensagem do contato, com a janela de 24h aberta. Template e primeira mensagem não têm. Sem mensagem recebida, a resposta é 409 no_inbound_message; fora da janela, 422 outside_window no WhatsApp e 422 window_closed no Instagram. Repetir a chamada em menos de 20 segundos não chama a Meta de novo e responde repeated: true: para uma resposta demorada, chame de novo a cada 20 segundos. Uma recusa da Meta (422 meta_error) não impede o envio da resposta.
Mostrar "digitando…" ao contato
Enquanto a sua integração prepara a resposta, o contato vê "digitando…" na conversa, como quando o atendente digita no painel. O sinal vai na última mensagem recebida do contato, que fica como lida (tiques azuis no WhatsApp, "visto" no Instagram). A Meta tira o indicador quando a resposta sai ou depois de cerca de 25 segundos. Sem corpo.
curl https://botozap.com.br/api/v1/conversations/5b0a9d0e-6e1a-4f3b-8c2d-1a9f6e0b7c11/typing \
-X POST \
-H "X-API-Key: $BOTOZAP_KEY"Resposta 200
{
"data": {
"conversation_id": "5b0a9d0e-6e1a-4f3b-8c2d-1a9f6e0b7c11",
"channel": "whatsapp",
"typing": true,
"repeated": false
}
}Só existe em resposta a uma mensagem do contato, com a janela de 24h aberta: é um limite da Meta. Template e primeira mensagem não têm "digitando…".
Repetir a chamada dentro de 20 segundos não chama a Meta de novo e responde `repeated: true`; para manter o indicador numa resposta demorada, chame de novo a cada 20 segundos.
Janela fechada: `422 outside_window` (WhatsApp) ou `422 window_closed` (Instagram). Sem mensagem recebida: `409 no_inbound_message`. Canal desconectado: `409 not_connected`. Recusa da Meta: `422 meta_error` (ou `502` se a Meta falhar); a resposta em si pode ser enviada normalmente.
Conversa de outra Conta, do sandbox ou id que não é UUID: `404 not_found`. Chave sem o escopo `messages:send`: `403 forbidden_scope`.
Erro: "digitando…" sem mensagem do contato
Numa conversa que a empresa começou (template, transmissão) e o contato ainda não respondeu, não há mensagem para responder, e a Meta não mostra o indicador. A API recusa antes de chamar a Meta.
curl https://botozap.com.br/api/v1/conversations/5b0a9d0e-6e1a-4f3b-8c2d-1a9f6e0b7c11/typing \
-X POST \
-H "X-API-Key: $BOTOZAP_KEY"Resposta 409
{
"error": {
"code": "no_inbound_message",
"message": "A conversa não tem mensagem recebida do contato: o \"digitando…\" só existe em resposta a uma mensagem dele."
}
}Criar um template
Enviar e criar são endpoints diferentes. POST /api/v1/messages usa um nome já aprovado; POST /api/v1/templates submete um template novo à Meta. Informe a conexão com waba_connection_id ou phone_number_id — os dois vêm de GET /api/v1/phone_numbers. Sem um dos dois, a API responde 422 missing_connection antes de olhar o restante do payload. Filtros, ciclo de aprovação e o que só o painel faz estão em Templates.
Criar um template
Submete um template à Meta. Informe a WABA com `waba_connection_id` ou `phone_number_id` — os dois vêm de `GET /api/v1/phone_numbers`.
curl https://botozap.com.br/api/v1/templates \
-X POST \
-H "X-API-Key: $BOTOZAP_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "pedido_confirmado",
"language": "pt_BR",
"category": "UTILITY",
"phone_number_id": "109876543210987",
"components": [
{
"type": "BODY",
"text": "Olá {{1}}, seu pedido foi confirmado.",
"example": {
"body_text": [
[
"Maria"
]
]
}
}
]
}'Resposta 201
{
"data": {
"id": "5b0a9d0e-6e1a-4f3b-8c2d-1a9f6e0b7c11",
"name": "pedido_confirmado",
"language": "pt_BR",
"category": "UTILITY",
"status": "PENDING",
"rejection_reason": null,
"meta_template_id": "123456789012345",
"components": [
{
"type": "BODY",
"text": "Olá {{1}}, seu pedido foi confirmado.",
"example": {
"body_text": [
[
"Maria"
]
]
}
}
],
"waba_connection_id": "5b0a9d0e-6e1a-4f3b-8c2d-1a9f6e0b7c11",
"created_at": "2026-07-14T12:00:00.000Z",
"last_synced_at": "2026-07-14T12:00:00.000Z"
}
}Sem `waba_connection_id` e sem `phone_number_id`: 422 `missing_connection`. Conexão ou número que não é da conta: 404 `not_found`.
`name` só aceita minúsculas, números e underscore (`pedido_confirmado`). `language` no formato `pt_BR`. `category`: `UTILITY`, `MARKETING` ou `AUTHENTICATION`.
O corpo é obrigatório. Variáveis precisam ser sequenciais (`{{1}}`, `{{2}}`) e cada uma leva um valor em `example.body_text`. Payload local inválido é 422 `invalid_template` — a Meta não é chamada.
Em live o 201 volta com `status: PENDING`; só envie o template quando a listagem mostrar `APPROVED`. A Graph recusando o conteúdo é 422 `meta_error`; 5xx da Graph é 502 `meta_error`.
Chave sandbox cria o template já `APPROVED`, sem chamar a Meta. Use a conexão/número sandbox da conta — misturar live e sandbox é 404.
Nome e idioma que já existem no catálogo da conexão: 409 `duplicate`, em live e no sandbox, antes de chamar a Meta. O template existente não é alterado.
Um UUID inventado não cai em missing_connection: conexão ou número que não é da conta é 404 not_found.
Erro: criar template sem conexão
O POST de template não adivinha a WABA. Sem `waba_connection_id` e sem `phone_number_id`, a API recusa antes de validar o restante do payload.
curl https://botozap.com.br/api/v1/templates \
-X POST \
-H "X-API-Key: $BOTOZAP_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "pedido_confirmado",
"language": "pt_BR",
"category": "UTILITY",
"components": [
{
"type": "BODY",
"text": "Olá, seu pedido foi confirmado."
}
]
}'Resposta 422
{
"error": {
"code": "missing_connection",
"message": "Informe 'waba_connection_id' ou 'phone_number_id' para criar o template."
}
}Pegue os dois ids em `GET /api/v1/phone_numbers`: `waba_connection_id` é o UUID da conexão; `phone_number_id` é o id Meta do número. Basta um dos dois.
Enviar mídia por link
Para image, video, audio e document, mande um objeto com o mesmo nome do tipo e um link https público. Quem baixa o arquivo é a Meta, no instante do envio: o link precisa estar acessível nessa hora.
POST /api/v1/messages
{
"to": "+5531988887777",
"type": "document",
"document": {
"link": "https://cdn.exemplo.com/boleto-4821.pdf",
"caption": "Seu boleto do pedido #4821",
"filename": "boleto-4821.pdf"
}
}link— obrigatório,https://, até 2048 caracteres. Sem o objeto do tipo, ou semlink, 422missing_media; link que não é https, 422invalid_request;caption— opcional, até 1024 caracteres, em imagem, vídeo e documento. Áudio não tem legenda:captionnum áudio é 422invalid_request;filename— opcional, só em documento, até 240 caracteres (vazio = a Meta deriva o nome do link); nos outros tipos é ignorado;voice— opcional, só emaudiodo WhatsApp:truemanda como mensagem de voz.
Mensagem de mídia não aceita media_id. Um objeto com id e sem link é recusado antes da Meta. O media_id de POST /api/v1/media serve para o cabeçalho de template (acima):
POST /api/v1/messages
{ "to": "+5531988887777", "type": "image", "image": { "id": "1234567890123456" } }
HTTP/1.1 422 Unprocessable Entity
{
"error": {
"code": "invalid_request",
"message": "Envio de 'image' por media id ainda não é suportado; informe 'image.link' (URL https pública).",
"outcome": "rejected",
"retry": "after_correction",
"next_step": "Corrija o campo indicado na resposta conforme o contrato de POST /api/v1/messages antes de tentar novamente."
}
}No WhatsApp a BotoZap não sonda o link antes de enviar: o tamanho e o formato quem confere é a Meta, e um arquivo recusado volta como 422 meta_error. Os tetos da Cloud API por tipo:
| Tipo | Tamanho máximo | Legenda |
|---|---|---|
image (imagem) | 5 MB | sim, até 1024 caracteres |
video (vídeo) | 16 MB | sim, até 1024 caracteres |
audio (áudio) | 16 MB | não |
document (documento) | 100 MB | sim, até 1024 caracteres |
Mídia é resposta livre: vale a janela de 24h, como no texto. O SDK expõe messages.sendMedia com os mesmos campos; o SDK e o MCP apenas delegam ao endpoint canônico — não baixam o arquivo no processo do agente.
await boto.messages.sendMedia({
to: "+5531988887777",
type: "image",
link: "https://cdn.exemplo.com/pedido.jpg",
caption: "Seu pedido ficou pronto",
});A mídia que o contato manda (e como baixá-la) está em Mídia.
Mensagem de voz
No WhatsApp, audio.voice: true entrega o áudio como mensagem de voz: o contato vê o botão de tocar e o app oferece a transcrição. A Meta exige arquivo .ogg com codec Opus e entrada mono; até 512 KB o app mostra o botão de tocar, acima disso um botão de download. Sem voice, o mesmo áudio sai como arquivo comum.
Enviar mensagem de voz (sandbox)
Áudio com `audio.voice: true` chega ao contato como mensagem de voz do WhatsApp (ícone de play, transcrição no app). O arquivo precisa ser `.ogg` com codec Opus e entrada mono; até 512 KB o app mostra o botão de tocar.
curl https://botozap.com.br/api/v1/messages \
-X POST \
-H "X-API-Key: $BOTOZAP_KEY" \
-H "Content-Type: application/json" \
-d '{
"to": "+5500000000001",
"type": "audio",
"audio": {
"link": "https://cdn.exemplo.com/recado.ogg",
"voice": true
}
}'Resposta 201
{
"id": "5b0a9d0e-6e1a-4f3b-8c2d-1a9f6e0b7c11",
"wamid": "wamid.HBgNNTU5MTk5OTk5OTk5FQIAERgSM0FCQzFEMkUzRjRBNUI2QzdEAA==",
"to": "5500000000001",
"sent_to": "5500000000001",
"status": "sent",
"sandbox": true
}Fora do sandbox, a BotoZap sonda o link: se o servidor responde um tipo que não é `audio/ogg`, 422 `invalid_voice` antes da Meta. Sem `voice` (ou `voice: false`) o áudio sai como arquivo comum, em qualquer formato aceito.
Quando o contato ouve a mensagem de voz pela primeira vez, chega o evento `whatsapp.message.played` e a mensagem ganha `played_at` (o `status` fica `read`).
`voice` só existe no WhatsApp: no Instagram é 422 `unsupported_voice`; em outro tipo que não `audio`, 422 `invalid_request`.
- Fora do sandbox a BotoZap sonda o link: se o servidor responde um tipo diferente de
audio/ogg, 422invalid_voiceantes da Meta. Sem tipo na resposta, quem confere é a Meta. - Quando o contato ouve pela primeira vez, chega o evento
whatsapp.message.playede a mensagem ganhaplayed_at. Ostatusficaread: ouvida implica lida. - No Instagram não existe mensagem de voz pela API:
voice: trueé 422unsupported_voice.
Botões, listas e botão de link
Dentro da janela de 24h, o WhatsApp aceita mensagens interativas livres: é o caminho para um agente de IA oferecer opções sem template. Mande type: "interactive" e o objeto interactive no mesmo formato da Cloud API da Meta. A BotoZap valida a forma e os limites antes de chamar a Meta e envia só os campos do contrato; campo desconhecido é 422 invalid_request com o nome do campo, não campo ignorado.
Botões de resposta (interactive.type: "button"): até 3 botões. O toque do contato chega como mensagem interactive com content.button_reply.id igual ao id do botão.
Enviar botões de resposta (sandbox)
Até 3 botões de resposta dentro da janela de 24h, no mesmo formato da Cloud API. O toque do contato volta como mensagem `interactive` com `content.button_reply.id`.
curl https://botozap.com.br/api/v1/messages \
-X POST \
-H "X-API-Key: $BOTOZAP_KEY" \
-H "Content-Type: application/json" \
-d '{
"to": "+5500000000001",
"type": "interactive",
"interactive": {
"type": "button",
"header": {
"type": "text",
"text": "Pedido #4821"
},
"body": {
"text": "Podemos entregar amanhã entre 9h e 12h?"
},
"footer": {
"text": "Loja Exemplo"
},
"action": {
"buttons": [
{
"type": "reply",
"reply": {
"id": "entrega_confirmar",
"title": "Confirmar"
}
},
{
"type": "reply",
"reply": {
"id": "entrega_remarcar",
"title": "Remarcar"
}
}
]
}
}
}'Resposta 201
{
"id": "5b0a9d0e-6e1a-4f3b-8c2d-1a9f6e0b7c11",
"wamid": "wamid.HBgNNTU5MTk5OTk5OTk5FQIAERgSM0FCQzFEMkUzRjRBNUI2QzdEAA==",
"to": "5500000000001",
"sent_to": "5500000000001",
"status": "sent",
"sandbox": true
}Mensagem livre, como o texto: fora da janela de 24h é 422 `outside_window`, e no Free conta no teto de respostas 1:1.
Header de mídia (`image`, `video`, `document`) só por `link` https. Campo fora do contrato é 422 `invalid_request` com o nome do campo.
Lista (interactive.type: "list"): um botão que abre até 10 opções, em até 10 seções. A escolha chega com content.list_reply.id.
Enviar uma lista de opções (sandbox)
Um botão que abre até 10 opções, em até 10 seções. A escolha volta como mensagem `interactive` com `content.list_reply.id`.
curl https://botozap.com.br/api/v1/messages \
-X POST \
-H "X-API-Key: $BOTOZAP_KEY" \
-H "Content-Type: application/json" \
-d '{
"to": "+5500000000001",
"type": "interactive",
"interactive": {
"type": "list",
"body": {
"text": "Escolha o melhor horário para a visita técnica."
},
"action": {
"button": "Ver horários",
"sections": [
{
"title": "Manhã",
"rows": [
{
"id": "visita_0900",
"title": "09:00",
"description": "Técnica Ana"
},
{
"id": "visita_1100",
"title": "11:00"
}
]
},
{
"title": "Tarde",
"rows": [
{
"id": "visita_1500",
"title": "15:00"
}
]
}
]
}
}
}'Resposta 201
{
"id": "5b0a9d0e-6e1a-4f3b-8c2d-1a9f6e0b7c11",
"wamid": "wamid.HBgNNTU5MTk5OTk5OTk5FQIAERgSM0FCQzFEMkUzRjRBNUI2QzdEAA==",
"to": "5500000000001",
"sent_to": "5500000000001",
"status": "sent",
"sandbox": true
}Com mais de uma seção, cada uma precisa de `title`. Os `id` das opções são únicos na lista inteira.
Botão de link (interactive.type: "cta_url"): um botão que abre uma URL https. O toque não volta como mensagem.
Enviar um botão de link (sandbox)
curl https://botozap.com.br/api/v1/messages \
-X POST \
-H "X-API-Key: $BOTOZAP_KEY" \
-H "Content-Type: application/json" \
-d '{
"to": "+5500000000001",
"type": "interactive",
"interactive": {
"type": "cta_url",
"body": {
"text": "Seu pedido saiu para entrega. Acompanhe pelo link."
},
"action": {
"name": "cta_url",
"parameters": {
"display_text": "Rastrear pedido",
"url": "https://loja.exemplo.com/pedidos/4821"
}
}
}
}'Resposta 201
{
"id": "5b0a9d0e-6e1a-4f3b-8c2d-1a9f6e0b7c11",
"wamid": "wamid.HBgNNTU5MTk5OTk5OTk5FQIAERgSM0FCQzFEMkUzRjRBNUI2QzdEAA==",
"to": "5500000000001",
"sent_to": "5500000000001",
"status": "sent",
"sandbox": true
}| Campo | Limite |
|---|---|
header | Opcional. Em button e cta_url: text (até 60 caracteres), image, video ou document por link https (sem media id). Em list, só text. |
body.text | Obrigatório. Até 1024 caracteres em button e cta_url; 4096 em list. |
footer.text | Opcional, até 60 caracteres. |
action.buttons[].reply | 1 a 3 botões; title até 20 caracteres, id até 256; ids e títulos únicos. |
action.button (lista) | Obrigatório, até 20 caracteres. |
action.sections (lista) | 1 a 10 seções e até 10 opções somando todas; title da seção até 24 caracteres, obrigatório com mais de uma seção. Em cada opção: id até 200 (único na lista), title até 24, description opcional até 72. |
action.parameters (cta_url) | display_text até 20 caracteres; url https. action.name é "cta_url". |
Outros subtipos da Cloud API (flow, product, product_list, location_request_message, carousel...) respondem 422 unsupported_type com o motivo:
Erro: subtipo interativo não suportado
Subtipos da Cloud API que a BotoZap não envia (Flows, produto, catálogo, pedido de localização...) são recusados antes da Meta.
curl https://botozap.com.br/api/v1/messages \
-X POST \
-H "X-API-Key: $BOTOZAP_KEY" \
-H "Content-Type: application/json" \
-d '{
"to": "+5500000000001",
"type": "interactive",
"interactive": {
"type": "flow",
"body": {
"text": "Preencha seu cadastro"
},
"action": {
"name": "flow",
"parameters": {}
}
}
}'Resposta 422
{
"error": {
"code": "unsupported_type",
"message": "'interactive.type' 'flow' não é suportado: WhatsApp Flows não são enviados pela API do BotoZap. Use 'button', 'list' ou 'cta_url'.",
"outcome": "rejected",
"retry": "after_correction",
"next_step": "Corrija o campo indicado na resposta conforme o contrato de POST /api/v1/messages antes de tentar novamente."
}
}É mensagem livre, com as mesmas regras do texto: vale a janela de 24h e, no Free, o teto de respostas 1:1. O SDK e o MCP ainda não têm método dedicado para interactive e location: use a REST.
Localização
type: "location" manda o cartão de localização. latitude (−90 a 90) e longitude (−180 a 180) em graus decimais, como número ou texto; name (até 1000 caracteres) e address (até 1000) são opcionais. Na listagem, o content guarda as coordenadas como número, a mesma forma da localização recebida.
Enviar uma localização (sandbox)
curl https://botozap.com.br/api/v1/messages \
-X POST \
-H "X-API-Key: $BOTOZAP_KEY" \
-H "Content-Type: application/json" \
-d '{
"to": "+5500000000001",
"type": "location",
"location": {
"latitude": -19.9365,
"longitude": -43.9351,
"name": "Loja Savassi",
"address": "Rua Pernambuco, 1000 - Savassi, Belo Horizonte - MG"
}
}'Resposta 201
{
"id": "5b0a9d0e-6e1a-4f3b-8c2d-1a9f6e0b7c11",
"wamid": "wamid.HBgNNTU5MTk5OTk5OTk5FQIAERgSM0FCQzFEMkUzRjRBNUI2QzdEAA==",
"to": "5500000000001",
"sent_to": "5500000000001",
"status": "sent",
"sandbox": true
}Mensagem livre: vale a janela de 24h. `latitude` vai de -90 a 90 e `longitude` de -180 a 180; `name` e `address` são opcionais.
Reagir a uma mensagem
type: "reaction" põe um emoji numa mensagem que o contato enviou. Em reaction.message_id, informe o id (UUID) da mensagem na BotoZap ou o wamid dela; em reaction.emoji, um único emoji. Emoji vazio ("") retira a reação.
Reagir a uma mensagem do contato (WhatsApp)
Reage com um emoji a uma mensagem RECEBIDA deste contato, de até 30 dias. `reaction.message_id` aceita o `id` (UUID) da mensagem na BotoZap ou o `wamid` dela; emoji vazio (`""`) retira a reação.
curl https://botozap.com.br/api/v1/messages \
-X POST \
-H "X-API-Key: $BOTOZAP_KEY" \
-H "Content-Type: application/json" \
-d '{
"to": "+5511988887777",
"type": "reaction",
"reaction": {
"message_id": "wamid.HBgNNTUxMTk4ODg4Nzc3NxUCABIYFjNFQjBDMEU0QTlEOEY3QjZDNUE0AA==",
"emoji": "👍"
}
}'Resposta 201
{
"id": "5b0a9d0e-6e1a-4f3b-8c2d-1a9f6e0b7c11",
"wamid": "wamid.HBgNNTU5MTk5OTk5OTk5FQIAERgSM0FCQzFEMkUzRjRBNUI2QzdEAA==",
"type": "reaction",
"to": "5511988887777",
"sent_to": "5511988887777",
"status": "sent",
"reaction": {
"message_id": "5b0a9d0e-6e1a-4f3b-8c2d-1a9f6e0b7c11",
"wamid": "wamid.HBgNNTUxMTk4ODg4Nzc3NxUCABIYFjNFQjBDMEU0QTlEOEY3QjZDNUE0AA==",
"emoji": "👍",
"action": "react"
}
}A reação é gravada como mensagem `reaction` (o `id` da resposta) e o `reaction.message_id` da resposta é o `id` da mensagem alvo.
Para reação a Meta manda só o status `sent`: não espere `delivered` nem `read`.
Vale a janela de 24h (422 `outside_window`). Mensagem de outra conversa é 422 `reaction_target_not_found`; alvo com mais de 30 dias, 422 `reaction_target_expired`.
No Free, reação não conta no teto de respostas 1:1 e segue saindo quando o teto acaba.
- A mensagem alvo precisa ser da mesma conversa (o contato do
to, pelo mesmo Número) e ter no máximo 30 dias — limite da Meta. Mensagem enviada pela empresa, outra reação ou mensagem apagada pelo contato não recebem reação. A API recusa antes da Meta com 422reaction_target_not_found,reaction_target_invalidoureaction_target_expired. - Vale a janela de 24h. A reação não é cobrada pela Meta e, no Free, não conta no teto de respostas 1:1.
- A resposta é 201 e a reação fica gravada como mensagem
reaction, comcontent.message_idigual aowamiddo alvo (a mesma forma da reação que o contato manda). No painel, ela aparece embaixo da mensagem alvo. - Para reação, a Meta manda só o status
sent: não esperedeliverednemread. Se mesmo assim a Meta não entregar (alvo apagado depois do envio, por exemplo), ela avisa por webhook com o erro131009.
Responder citando uma mensagem
reply_to.message_id faz a resposta sair citando uma mensagem da conversa, como o "Responder" do app: o contato vê a citada acima da resposta. Aceita o id (UUID) da mensagem na BotoZap ou o id do canal (wamid no WhatsApp, mid no Instagram), de uma mensagem do contato ou da empresa. Vale para texto, mídia, interativas, localização e template (no Instagram: texto, mídia e interativas).
Responder citando uma mensagem (WhatsApp)
Responde citando uma mensagem da conversa: o contato vê a citada acima da resposta, como no app. `reply_to.message_id` aceita o `id` (UUID) da mensagem na BotoZap ou o `wamid` dela — recebida do contato ou enviada pela empresa. Vale para texto, mídia, interativas, localização e template; reação não.
curl https://botozap.com.br/api/v1/messages \
-X POST \
-H "X-API-Key: $BOTOZAP_KEY" \
-H "Content-Type: application/json" \
-d '{
"to": "+5511988887777",
"type": "text",
"text": {
"body": "Abrimos sim, das 9h às 13h."
},
"reply_to": {
"message_id": "wamid.HBgNNTUxMTk4ODg4Nzc3NxUCABIYFjNFQjBDMEU0QTlEOEY3QjZDNUE1AA=="
}
}'Resposta 201
{
"id": "5b0a9d0e-6e1a-4f3b-8c2d-1a9f6e0b7c11",
"wamid": "wamid.HBgNNTU5MTk5OTk5OTk5FQIAERgSM0FCQzFEMkUzRjRBNUI2QzdEAA==",
"to": "5511988887777",
"sent_to": "5511988887777",
"status": "sent",
"reply_to": {
"message_id": "5b0a9d0e-6e1a-4f3b-8c2d-1a9f6e0b7c11",
"external_id": "wamid.HBgNNTUxMTk4ODg4Nzc3NxUCABIYFjNFQjBDMEU0QTlEOEY3QjZDNUE1AA=="
}
}Na Cloud API vira `context.message_id` ("Contextual replies"); no Instagram, `reply_to.mid` ("Send a reply"). A mensagem enviada guarda a citação em `content` e, em `GET /api/v1/messages`, traz `reply_to: { message_id, external_id }`.
A citada é procurada na conversa do contato do `to`: de outra conversa é 422 `reply_target_not_found`; reação, mensagem apagada ou envio que não saiu é 422 `reply_target_unavailable`. `reply_to` com `type: "reaction"` é 422 `invalid_request`.
A Meta omite a citação quando a citada foi apagada ou tem mais de ~30 dias, e em template; o envio sai do mesmo jeito.
- A citada é procurada na conversa do contato do
to. De outra conversa (ou de outra conta): 422reply_target_not_found. Reação, mensagem apagada ou envio que não saiu: 422reply_target_unavailable. Reação não pode ser resposta citada:reply_tocomtype: "reaction"é 422invalid_request. - A resposta do envio e a listagem trazem
reply_to: { message_id, external_id }. Na mensagem recebida que cita outra,reply_toaparece do mesmo jeito;message_idénullquando a citada não está no histórico da BotoZap. - A Meta omite a citação quando a citada foi apagada ou ficou antiga (cerca de 30 dias) e em template; o envio sai do mesmo jeito.
O que cada canal envia pela API
A tabela sai da mesma fonte que a API consulta. Um tipo que o canal não envia é recusado antes da Meta: 422 unsupported_type no WhatsApp e channel_not_supported no Instagram. As regras próprias do Instagram estão em Enviar para o Instagram.
type | ||
|---|---|---|
text | envia | envia |
template | envia | não envia — 422 channel_not_supported |
image | envia | envia |
video | envia | envia |
audio | envia | envia |
document | envia | envia |
sticker | não envia — 422 unsupported_type | não envia — 422 channel_not_supported |
interactive | envia | envia |
location | envia | não envia — 422 channel_not_supported |
contacts | não envia — 422 unsupported_type | não envia — 422 channel_not_supported |
reaction | envia | envia |
- Botões, listas e botão de link saem como
interactivedentro da janela (veja acima); fora dela, só pelos botões de um template aprovado. reactionsai como reação a uma mensagem recebida (veja acima).contactsestickernão saem pela API do WhatsApp. Quando o contato os manda, eles chegam normalmente, com essetype.- Não há endpoint para marcar mensagem como lida nem para mostrar "digitando…".
Escolher o número de origem
O campo from aceita o phone_number_id Meta ou o UUID interno do Número. É opcional quando a conta tem um único número conectado; com mais de um número, é obrigatório. Só contam números de conexão ativa e do mesmo ambiente da chave (sandbox ou produção).
Enviar por um número específico (`from`)
Contas com mais de um número conectado precisam informar `from` (o `phone_number_id` Meta ou o UUID interno) para desambiguar por qual número enviar.
curl https://botozap.com.br/api/v1/messages \
-X POST \
-H "X-API-Key: $BOTOZAP_KEY" \
-H "Content-Type: application/json" \
-d '{
"to": "+5511988887777",
"type": "template",
"template": {
"name": "pedido_confirmado",
"language": {
"code": "pt_BR"
}
},
"from": "112233445566778"
}'Resposta 201
{
"id": "5b0a9d0e-6e1a-4f3b-8c2d-1a9f6e0b7c11",
"wamid": "wamid.HBgNNTU5MTk5OTk5OTk5FQIAERgSM0FCQzFEMkUzRjRBNUI2QzdEAA==",
"to": "5511988887777",
"sent_to": "5511988887777",
"status": "sent"
}`from` é obrigatório quando a conta tem mais de um número conectado — sem ele a API responde 422 `ambiguous_phone`.
Use o `phone_number_id` Meta ou o UUID interno retornado por `GET /api/v1/phone_numbers`.
Sem from numa conta com mais de um número, a API recusa:
Erro: número de origem ambíguo
Quando a conta tem mais de um número conectado e `from` não é informado, a API recusa em vez de adivinhar por qual número enviar.
curl https://botozap.com.br/api/v1/messages \
-X POST \
-H "X-API-Key: $BOTOZAP_KEY" \
-H "Content-Type: application/json" \
-d '{
"to": "+5511988887777",
"type": "template",
"template": {
"name": "pedido_confirmado",
"language": {
"code": "pt_BR"
}
}
}'Resposta 422
{
"error": {
"code": "ambiguous_phone",
"message": "Mais de um número conectado; informe 'from' (phone_number_id).",
"outcome": "rejected",
"retry": "after_correction",
"next_step": "Informe em 'from' o Número correto da Conta e do ambiente da chave."
}
}Toda recusa de `POST /api/v1/messages` traz, além de `code` e `message`, `outcome` (`rejected`: a mensagem não saiu; `unknown`: a Meta pode tê-la recebido), `retry` e `next_step`.
Antes de enviar: o número está pronto?
GET /api/v1/phone_numbers/{id} aceita tanto o UUID interno do Número quanto o phone_number_id da Meta, e traz connection_status, token_status e quality_rating. Para uma resposta de "dá para enviar agora?", use GET /api/v1/phone_numbers/{id}/health (escopo numbers:read, chave de produção; também aceita os dois ids). Com a conexão ativa, ela faz uma checagem ao vivo do token na Meta e confere se o BotoZap continua inscrito para receber as mensagens do número; bloqueio ou conexão revogada não viram saudáveis por causa de um token válido.
GET /api/v1/phone_numbers/106540352242922/health
HTTP/1.1 200 OK
{
"data": {
"status": "unhealthy",
"timestamp": "2026-09-25T14:02:11.000Z",
"error": "…motivo… …ação…",
"checks": { "token_validity": "invalid" },
"readiness": {
"state": "reconnect_required",
"reason": "token_invalid",
"next_action": "reconnect",
"observed_at": "2026-09-25T14:02:11.000Z",
"stale": false,
"live_check": "invalid",
"meta_disconnection_reason": null,
"title": "…",
"detail": "…",
"action": "…"
},
"phone_number_id": "106540352242922",
"customer_id": "7c1d…",
"waba_connection_id": "3b9e…"
}
}| Campo | Valores |
|---|---|
status | healthy (pronto, ou sandbox), degraded (sem observação suficiente da Meta ainda), unhealthy (reconectar ou bloqueio da Meta) e error (não deu para ler ou checar agora). Fora de healthy, error resume o motivo e a ação. |
readiness.state | ready, reconnect_required, blocked, unknown, unavailable ou sandbox; o porquê vem em readiness.reason (ex.: token_invalid, connection_revoked, account_restricted, webhooks_lost quando a Meta parou de mandar as mensagens do número para o BotoZap com o token ainda válido, ou meta_payment_method quando a forma de pagamento da conta na Meta está com erro e só as conversas iniciadas pela empresa param). |
readiness.next_action | reconnect, resolve_in_meta, finish_in_app (número em coexistência pausado pela Meta: o dono termina o registro no app WhatsApp Business do celular e o número volta sozinho, motivo coexistence_offboarded), sync, retry_read ou none. |
readiness.live_check | ok (token válido agora), invalid (a Meta recusou o token), missing (sem token guardado), unavailable (a Meta não respondeu; nada foi concluído) ou skipped (sem checagem: sandbox, conexão inativa ou token já recusado). |
readiness.meta_disconnection_reason | Só com reason connection_revoked: o motivo que a Meta informou ao desligar um número em coexistência, por exemplo USER_RE_REGISTERED (o WhatsApp Business foi registrado em outro aparelho). null nos demais casos. O detail já traz o motivo em português. |
readiness.title, detail, action | Textos em português, os mesmos do painel, prontos para mostrar ao seu usuário. detail e action podem ser null. |
readiness.observed_at, stale | Quando o estado foi observado; stale: true quando a observação tem mais de 24h (informativo, não bloqueia). |
checks.token_validity | valid, invalid ou missing; só aparece quando houve checagem ao vivo. |
checks.webhook_subscription | subscribed (a Meta manda as mensagens do número para o BotoZap), missing (parou de mandar: reconecte o número) ou unknown (a Meta não respondeu). Só aparece quando o token foi aceito na checagem ao vivo. |
A janela de atendimento de 24h
Todo envio que não é template — texto, mídia (image, video, audio, document), interactive, location e reaction — só é aceito enquanto a janela de 24h está aberta, contada desde a última mensagem que o contato enviou para você. A API recusa com 422 outside_window antes de chamar a Meta, sem gastar quota:
Erro: fora da janela de 24h
Todo envio que não é template (texto, `image`, `video`, `audio` ou `document`) só é permitido enquanto a janela de atendimento (24h desde a última mensagem do contato) está aberta. Fora dela, a API recusa ANTES de chamar a Meta.
curl https://botozap.com.br/api/v1/messages \
-X POST \
-H "X-API-Key: $BOTOZAP_KEY" \
-H "Content-Type: application/json" \
-d '{
"to": "+5511977776666",
"type": "text",
"text": {
"body": "Oi, tudo bem?"
}
}'Resposta 422
{
"error": {
"code": "outside_window",
"message": "Fora da janela de 24h: este contato não enviou mensagem nas últimas 24h. Envie um template (type: 'template') para reengajar.",
"outcome": "rejected",
"retry": "after_correction",
"next_step": "Use um Template aprovado ou aguarde uma nova mensagem do Contato para abrir a janela de 24h."
}
}Para reengajar um contato fora da janela, envie um template aprovado (`type: "template"`). A recusa não consome cota.
Para reengajar um contato fora da janela, envie um template aprovado. No sandbox, o número +5500000000003 responde automaticamente ao seu envio (abrindo a janela de verdade), para você testar esse fluxo ponta a ponta.
Destinatário: telefone ou BSUID
O campo to aceita um número em formato internacional (E.164, ex.: +5531988887777) ou um BSUID do WhatsApp (ex.: BR.1A2B...). O BSUID é um identificador opaco que a Meta usa quando o contato não expõe o telefone; trate os dois como uma chave e nunca remova caracteres não numéricos, pois isso destrói o BSUID. Veja Conceitos para os detalhes.
Ao enviar, a BotoZap resolve o contato pelas identidades que já conhece (telefone e BSUID da mesma pessoa) e entrega pelo endereço com melhor chance de entrega. Hoje isso significa preferir o telefone: a Meta aceita o envio para BSUID, mas marca a mensagem como failed (erro 131026) quando o destinatário não tem username ativo. Na prática: BSUID de um contato cujo telefone conhecemos sai pelo telefone; contato que só tem BSUID sai pelo BSUID; destinatário que nunca vimos sai exatamente como você mandou. A resposta do envio traz o endereço usado no campo sent_to. Para desligar a normalização num envio específico, passe to_mode: "raw" no corpo.
Uma ressalva importante: templates de autenticação (OTP) exigem número de telefone. Se o destinatário é um BSUID cujo telefone conhecemos, a normalização acima resolve e o envio segue pelo telefone. Sem telefone conhecido, a API bloqueia o envio com o código auth_template_bsuid.
Enviar para o Instagram
O mesmo endpoint atende os dois canais. O campo to aceita o IGSID do contato (o identificador opaco dele na sua conta profissional, de 16 a 32 dígitos; com 7 a 15 dígitos o endereço é lido como telefone do WhatsApp), e o canal do envio sai da forma do endereço — from só é necessário quando a conta tem mais de uma conta do Instagram ativa.
Responder um direct do Instagram
O mesmo endpoint envia pelos dois canais. `to` aceita o IGSID do contato; o canal sai da forma do endereço, e `from` só é necessário quando a conta tem mais de uma Conta de canal do mesmo canal.
curl https://botozap.com.br/api/v1/messages \
-X POST \
-H "X-API-Key: $BOTOZAP_KEY" \
-H "Content-Type: application/json" \
-d '{
"to": "17841400000000123",
"type": "text",
"text": {
"body": "Tem sim! Sábado às 10h está livre 😊"
}
}'Resposta 201
{
"id": "5b0a9d0e-6e1a-4f3b-8c2d-1a9f6e0b7c11",
"wamid": null,
"external_id": "aWdEZ...mlk",
"channel": "instagram",
"type": "text",
"to": "17841400000000123",
"sent_to": "17841400000000123",
"status": "sent"
}Dentro da janela de 24h a resposta é livre. Fora dela a API responde 422 `window_closed` com a data limite: até 7 dias depois da última mensagem do contato ainda dá para responder com `tag: "human_agent"` — etiqueta em liberação: por enquanto, fora das 24h é sempre 422 `window_closed`.
O canal aceita até 1000 BYTES de texto (acento e emoji contam mais de um byte); acima disso a API responde 422 `text_too_long` sem chamar a Meta.
`interactive` envia botões, cards e galeria dentro da janela. `template` continua sendo o modelo aprovado do WhatsApp; `location`, `contacts` e sticker próprio também são 422 `channel_not_supported` no Instagram.
As regras do Instagram são diferentes das do WhatsApp e a API as aplica antes de chamar a Meta:
- texto até 1000 bytes (acento e emoji contam mais de um byte) — acima disso, 422
text_too_long; - a janela de 24h vale aqui também, mas a saída fora dela é outra: não existe template para reengajar, e sim a etiqueta de atendente humano (logo abaixo);
- imagem até 8 MB (JPEG, PNG ou GIF); áudio, vídeo e PDF até 25 MB — veja Arquivos;
interactiveenvia botões, cards e galeria (veja abaixo). Modelos aprovados (template),location,contactse sticker próprio não existem no canal — 422channel_not_supported.- texto, arquivo ou mensagem interativa enviada pela API conta como resposta da equipe, como no WhatsApp: o agente de IA daquela conversa fica pausado até alguém devolver a conversa à IA. Com outro envio em andamento na mesma conversa, a resposta é 409
conversation_dispatch_busy. A reação não pausa nada.
Fora das 24h: atendente humano (em liberação)
Em liberação: a etiqueta depende de uma permissão da Meta que ainda está em análise. Por enquanto, todo envio fora das 24h é 422 window_closed, com ou sem tag: "human_agent" (dentro das 24h a tag é aceita e não muda nada). O que segue descreve o comportamento depois da liberação.
Passadas as 24h desde a última mensagem do contato, o Instagram só aceita a resposta com a etiqueta de atendente humano, e por no máximo 7 dias. A API não aplica a etiqueta sozinha: a Meta restringe o uso a atendimento humano de verdade, então quem declara é você, com tag: "human_agent".
Responder fora das 24h como atendente humano (em liberação)
Em liberação: a etiqueta depende de uma permissão da Meta ainda em análise, e por enquanto este envio é 422 `window_closed`. Depois da liberação: passadas as 24h e antes dos 7 dias, o Instagram só aceita a resposta com a etiqueta de atendente humano. A API nunca a aplica sozinha: a Meta restringe o uso a atendimento humano de verdade, então quem declara é você, com `tag: "human_agent"`.
curl https://botozap.com.br/api/v1/messages \
-X POST \
-H "X-API-Key: $BOTOZAP_KEY" \
-H "Content-Type: application/json" \
-d '{
"to": "17841400000000123",
"type": "text",
"tag": "human_agent",
"text": {
"body": "Oi! Desculpe a demora — consegui o horário que você pediu."
}
}'Resposta 201
{
"id": "5b0a9d0e-6e1a-4f3b-8c2d-1a9f6e0b7c11",
"wamid": null,
"external_id": "aWdEZ...mlk",
"channel": "instagram",
"type": "text",
"to": "17841400000000123",
"sent_to": "17841400000000123",
"status": "sent"
}Sem a etiqueta, o mesmo envio é 422 `window_closed` — e a mensagem do erro traz a data limite.
Depois dos 7 dias a etiqueta não salva mais nada: a resposta é 422 `conversation_closed` e quem reabre a conversa é o contato.
A etiqueta é do Instagram. Num envio pelo WhatsApp, `tag` é recusado com 422 `channel_not_supported`; fora da janela, o WhatsApp reengaja por template.
São três estados, e a régua é sempre a última mensagem do contato:
- dentro das 24h — resposta livre, sem etiqueta nenhuma;
- entre 24h e 7 dias — só com
tag: "human_agent"; sem ela, 422window_closed, e a mensagem do erro traz a data limite; - depois dos 7 dias — 422
conversation_closed: não há saída pelo lado do negócio, quem reabre a conversa é o contato.
A etiqueta é do Instagram. Num envio pelo WhatsApp, tag é recusado com 422 channel_not_supported — lá o caminho fora da janela continua sendo o template aprovado.
Opções de resposta
Uma mensagem do Instagram pode levar até 13 opções de resposta — os chips que o contato responde com um toque. O toque volta como mensagem recebida com o título do chip no corpo, e o payload escolhido chega em context.quick_reply.payload do evento instagram.message.received (o mesmo campo quando o contato toca um botão que a Meta entrega como messaging_postbacks).
Anexar opções de resposta a um direct
Uma mensagem do Instagram pode levar até 13 opções de resposta — os chips que o contato responde com um toque. O toque volta como mensagem recebida com o título do chip, e o `payload` escolhido chega em `context.quick_reply` do evento `instagram.message.received`.
curl https://botozap.com.br/api/v1/messages \
-X POST \
-H "X-API-Key: $BOTOZAP_KEY" \
-H "Content-Type: application/json" \
-d '{
"to": "17841400000000123",
"type": "text",
"text": {
"body": "Tenho estes horários no sábado:"
},
"quick_replies": [
{
"title": "9h",
"payload": "sabado_09"
},
{
"title": "10h30",
"payload": "sabado_1030"
},
{
"title": "Outro horário",
"payload": "sabado_outro"
}
]
}'Resposta 201
{
"id": "5b0a9d0e-6e1a-4f3b-8c2d-1a9f6e0b7c11",
"wamid": null,
"external_id": "aWdEZ...mlk",
"channel": "instagram",
"type": "text",
"to": "17841400000000123",
"sent_to": "17841400000000123",
"status": "sent"
}Até 13 chips por mensagem, com `title` de até 20 caracteres — acima disso, 422 `too_many_quick_replies` ou `quick_reply_title_too_long`, sem chamar a Meta.
`payload` é opcional (até 1000 caracteres): sem ele, o próprio título volta no toque; acima do teto, 422 `quick_reply_payload_too_long`.
`content_type` aceita `text` (o padrão), `user_phone_number` e `user_email`. Nos dois últimos o Instagram preenche o chip com o dado do perfil de quem tocou — não mande `title` nem `payload`.
Erro de forma (lista que não é lista, item sem `title`, `content_type` fora dos três) é 422 `invalid_quick_replies`, com o número do item na mensagem.
Opções de resposta acompanham `type: "text"` e só existem no Instagram: num envio pelo WhatsApp, `quick_replies` é 422 `channel_not_supported` (lá os botões pertencem ao template aprovado).
Só dentro da janela de 24h: fora dela a resposta com `tag: "human_agent"` sai sem chips, e `quick_replies` é 422 `quick_replies_window_closed`.
- até 13 por mensagem — acima disso, 422
too_many_quick_replies; titlede até 20 caracteres — acima disso, 422quick_reply_title_too_long;payloadé opcional (até 1000 caracteres): sem ele, o próprio título volta no toque; acima do teto, 422quick_reply_payload_too_long;content_typeaceitatext(padrão),user_phone_numbereuser_email; nos dois últimos quem preenche o chip é o Instagram, com o dado do perfil de quem tocou.- só dentro da janela de 24h: fora dela a resposta com a etiqueta de atendente humano sai sem chips, e
quick_repliesé 422quick_replies_window_closed.
Qualquer outro problema de forma — a lista não é uma lista, um item sem title, um content_type fora dos três — é 422 invalid_quick_replies, e a mensagem diz qual item da lista recusou.
As opções de resposta acompanham type: "text" (pedi-las em outro tipo também é invalid_quick_replies) e só existem no Instagram: num envio pelo WhatsApp, quick_replies é 422 channel_not_supported — lá os botões pertencem ao template aprovado.
Botões, cards e galeria
Use type: "interactive". No Instagram, o objeto interactive aceita type: "button" ou type: "generic". O canal é resolvido pelo destinatário e pela origem, como nos outros envios; os objetos de lista e botões reply do WhatsApp não são aceitos aqui.
Para botões, informe body.text (até 640 caracteres) e action.buttons com 1 a 3 itens. Cada botão leva title (até 20 caracteres) e type: "web_url" com url, ou type: "postback" com payload obrigatório (até 1000 caracteres).
Enviar botões no Instagram
Texto com até três botões de link ou postback.
curl https://botozap.com.br/api/v1/messages \
-X POST \
-H "X-API-Key: $BOTOZAP_KEY" \
-H "Content-Type: application/json" \
-d '{
"to": "17841400000000123",
"type": "interactive",
"interactive": {
"type": "button",
"body": {
"text": "Como você quer continuar?"
},
"action": {
"buttons": [
{
"type": "web_url",
"title": "Ver catálogo",
"url": "https://loja.exemplo.com/catalogo"
},
{
"type": "postback",
"title": "Falar com a equipe",
"payload": "falar_equipe"
}
]
}
}
}'Resposta 201
{
"id": "5b0a9d0e-6e1a-4f3b-8c2d-1a9f6e0b7c11",
"wamid": null,
"external_id": "aWdEZ...mlk",
"channel": "instagram",
"type": "interactive",
"to": "17841400000000123",
"sent_to": "17841400000000123",
"status": "sent"
}Botões: de 1 a 3, só web_url ou postback; título até 20 caracteres e payload de postback obrigatório, até 1000 caracteres. Links e imagens usam URL https de até 2048 caracteres (política da BotoZap).
Texto do button até 640 caracteres; generic de 1 a 10 cards, título e subtítulo até 80 caracteres, até 3 botões por card. Cada card exige título e ao menos imagem, subtítulo, botões ou default_action (web_url).
O postback chega em instagram.message.received com o título no corpo, context.quick_reply.payload e o postback original em context.postback. Abrir um web_url não gera esse postback.
Não reabre a janela: mesmas regras de 24h e human_agent atrás da flag. Não combine com quick_replies, que acompanha somente type text. O template genérico não está disponível no Instagram para desktop.
Para um card, use type: "generic" com um item em elements. O title é obrigatório (até 80 caracteres); acrescente ao menos um dos campos image_url, subtitle (até 80 caracteres), buttons (1 a 3 botões) ou default_action ({ type: "web_url", url }). O card pode reunir todos esses campos.
Enviar um card no Instagram
Um card reúne título, imagem, subtítulo e botões em uma mensagem.
curl https://botozap.com.br/api/v1/messages \
-X POST \
-H "X-API-Key: $BOTOZAP_KEY" \
-H "Content-Type: application/json" \
-d '{
"to": "17841400000000123",
"type": "interactive",
"interactive": {
"type": "generic",
"elements": [
{
"title": "Passeio pelo Encontro das Águas",
"subtitle": "Saída às 9h, com guia local.",
"image_url": "https://cdn.exemplo.com/passeio.jpg",
"buttons": [
{
"type": "postback",
"title": "Consultar vagas",
"payload": "vagas_passeio"
}
]
}
]
}
}'Resposta 201
{
"id": "5b0a9d0e-6e1a-4f3b-8c2d-1a9f6e0b7c11",
"wamid": null,
"external_id": "aWdEZ...mlk",
"channel": "instagram",
"type": "interactive",
"to": "17841400000000123",
"sent_to": "17841400000000123",
"status": "sent"
}Botões: de 1 a 3, só web_url ou postback; título até 20 caracteres e payload de postback obrigatório, até 1000 caracteres. Links e imagens usam URL https de até 2048 caracteres (política da BotoZap).
Texto do button até 640 caracteres; generic de 1 a 10 cards, título e subtítulo até 80 caracteres, até 3 botões por card. Cada card exige título e ao menos imagem, subtítulo, botões ou default_action (web_url).
O postback chega em instagram.message.received com o título no corpo, context.quick_reply.payload e o postback original em context.postback. Abrir um web_url não gera esse postback.
Não reabre a janela: mesmas regras de 24h e human_agent atrás da flag. Não combine com quick_replies, que acompanha somente type text. O template genérico não está disponível no Instagram para desktop.
De 2 a 10 itens em elements formam uma galeria com rolagem horizontal, enviada em uma única mensagem e com um único external_id. A Meta informa que o template genérico não está disponível no Instagram para desktop.
Enviar uma galeria no Instagram
Dois a dez cards no mesmo envio formam uma galeria com rolagem horizontal.
curl https://botozap.com.br/api/v1/messages \
-X POST \
-H "X-API-Key: $BOTOZAP_KEY" \
-H "Content-Type: application/json" \
-d '{
"to": "17841400000000123",
"type": "interactive",
"interactive": {
"type": "generic",
"elements": [
{
"title": "Passeio pelo Encontro das Águas",
"image_url": "https://cdn.exemplo.com/passeio.jpg",
"subtitle": "Saída às 9h, com guia local.",
"buttons": [
{
"type": "postback",
"title": "Consultar vagas",
"payload": "vagas_passeio"
}
]
},
{
"title": "Visita ao mercado",
"subtitle": "Sabores e artesanato de Manaus.",
"image_url": "https://cdn.exemplo.com/mercado.jpg",
"buttons": [
{
"type": "web_url",
"title": "Ver roteiro",
"url": "https://loja.exemplo.com/mercado"
}
]
}
]
}
}'Resposta 201
{
"id": "5b0a9d0e-6e1a-4f3b-8c2d-1a9f6e0b7c11",
"wamid": null,
"external_id": "aWdEZ...mlk",
"channel": "instagram",
"type": "interactive",
"to": "17841400000000123",
"sent_to": "17841400000000123",
"status": "sent"
}Botões: de 1 a 3, só web_url ou postback; título até 20 caracteres e payload de postback obrigatório, até 1000 caracteres. Links e imagens usam URL https de até 2048 caracteres (política da BotoZap).
Texto do button até 640 caracteres; generic de 1 a 10 cards, título e subtítulo até 80 caracteres, até 3 botões por card. Cada card exige título e ao menos imagem, subtítulo, botões ou default_action (web_url).
O postback chega em instagram.message.received com o título no corpo, context.quick_reply.payload e o postback original em context.postback. Abrir um web_url não gera esse postback.
Não reabre a janela: mesmas regras de 24h e human_agent atrás da flag. Não combine com quick_replies, que acompanha somente type text. O template genérico não está disponível no Instagram para desktop.
Links de botão, imagem e ação do card devem ser URLs https de até 2048 caracteres (política da BotoZap). Campos desconhecidos, limites excedidos e botões sem URL ou payload são 422 invalid_request, com o caminho do campo na mensagem. Subtipo que o Instagram não aceita é 422 unsupported_type. Não combine esses formatos com quick_replies: os chips continuam acompanhando somente type: "text".
Ao tocar em postback, o contato gera instagram.message.received: título no corpo, context.quick_reply.payload com a seleção e context.postback com o postback original. Um botão web_url abre o link e não gera esse postback. O histórico e o Evento de envio trazem type: "interactive" e o objeto validado em content.
Esses formatos seguem as mesmas regras de janela: 24h e, quando liberada, a etiqueta de atendente humano. Eles não reengajam contatos como um modelo aprovado do WhatsApp. O campo type: "template" continua exclusivo do WhatsApp.
Arquivos
image, video, audio e document funcionam como no WhatsApp: você informa um link https público, e quem busca o arquivo é a Meta, no instante do envio. Não existe media_id na plataforma do Instagram — o link precisa estar acessível quando você chama a API.
- imagem até 8 MB, nos formatos JPEG, PNG e GIF;
- áudio e vídeo até 25 MB;
- documento até 25 MB e só em PDF — o Instagram não tem documento genérico como o WhatsApp;
captioné recusado com 422unsupported_caption: uma mensagem do Instagram leva texto ou anexo, nunca os dois. Mande a legenda como uma segunda mensagem.
Antes de chamar a Meta, a API faz um HEAD curto no link (3 s, sem baixar o arquivo) e recusa com 422 o que o canal não aceita: unsupported_media_type quando o content-type não é um formato do tipo pedido, e media_too_large quando o content-length passa do teto. Se o host não responde ao HEAD ou não manda esses cabeçalhos, o envio segue e quem decide é a Meta — um link acima do teto volta então como 422 meta_error, com a mensagem dela. A sonda é só do Instagram: no WhatsApp o link vai direto para a Meta, sem HEAD prévio (veja Enviar mídia por link).
Um arquivo por mensagem. O Instagram aceita até 10 imagens numa conversa, mas o envio leva um anexo por chamada: para mandar várias, faça uma chamada por arquivo. Cada uma vira uma mensagem própria, com o seu external_id. Anexo e texto também não vão juntos — veja unsupported_caption acima.
No caminho contrário, o anexo que o contato manda (imagem, vídeo, áudio, arquivo e o coraçãozinho) chega em instagram.message.received com o type correspondente, e o arquivo é espelhado no nosso armazenamento. Em content.media.id (e em cada item de content.attachments[]) vem o id da mídia, que você passa em GET /v1/media/{id} para obter uma URL de download assinada — como faz com o media_id do WhatsApp. A url ao lado é a da CDN da Meta e expira em horas: use-a só para consumo imediato. Uma publicação ou um reel compartilhado sem texto chega como type: "unknown" com content.type: "share"; com texto, chega como type: "text" e o compartilhamento vem em content.share. A Meta não entrega o arquivo, mas a mensagem existe e abre a janela de 24h.
O Instagram também aceita type: "reaction": reagir a uma mensagem que o contato enviou na conversa, com reaction: { message_id, emoji }, onde message_id é o external_id da mensagem alvo. Emoji vazio retira a reação. A resposta é 200 (não 201: nenhuma mensagem nova é criada) e o id é o da mensagem reagida (null quando ela não está no histórico da BotoZap). Mensagem enviada pela empresa não recebe reação: a API recusa antes da Meta com 422 reaction_target_invalid. Sem reaction.message_id, 422 missing_reaction_target; fora da janela de 24h, a reação é recusada com 422 window_closed (ou conversation_closed depois de 7 dias). No WhatsApp a reação tem outro contrato (201 e mensagem gravada): veja Reagir a uma mensagem.
Misturar os canais entre to e from também é recusado, em vez de virar um erro opaco da Meta:
Erro: destinatário e origem de canais diferentes
O canal do envio sai da origem quando `from` é informado. Endereçar um telefone a partir de uma Conta do Instagram (ou um IGSID a partir de um Número) é recusado antes de chegar à Meta.
curl https://botozap.com.br/api/v1/messages \
-X POST \
-H "X-API-Key: $BOTOZAP_KEY" \
-H "Content-Type: application/json" \
-d '{
"to": "+5511988887777",
"type": "text",
"text": {
"body": "Oi!"
},
"from": "17841400000000999"
}'Resposta 422
{
"error": {
"code": "channel_mismatch",
"message": "A origem informada é uma Conta do Instagram e o destinatário não é um IGSID. Informe um 'to' do mesmo canal do 'from'.",
"outcome": "rejected",
"retry": "after_correction",
"next_step": "Use em 'from' e em 'to' o mesmo canal: Número do WhatsApp com telefone ou BSUID, Conta do Instagram com IGSID. GET /api/v1/channel_accounts lista as origens."
}
}`GET /api/v1/channel_accounts` lista as Contas de canal com `channel`, `display` e o id que serve de `from`.
Com mais de uma conta do Instagram ativa e sem from, a resposta é 422 ambiguous_channel_account (no WhatsApp, o equivalente é ambiguous_phone). Use GET /api/v1/channel_accounts para listar Números e Contas do Instagram com o id que serve de from.
Sandbox do Instagram
Uma chave bz_sandbox_ também envia pelo Instagram, sem conta profissional conectada e sem custo: criar a primeira chave sandbox provisiona uma Conta do Instagram sintética na sua conta (e o envio confere de novo, caso ela falte), e os IGSIDs mágicos abaixo escolhem o cenário. Nada disso chama a Meta — os eventos são injetados no mesmo pipeline que processa os webhooks reais, então o que você testa é o seu handler de verdade, com assinatura HMAC e retry. Detalhe que muda a ordem dos eventos: para a janela de 24h existir, o primeiro envio a um IGSID mágico (ou o primeiro depois que a janela dele vence) injeta antes um direct do contato, então o seu handler recebe um instagram.message.received (com Contato e Conversa) antes do instagram.message.sent desse envio.
| Destinatário (IGSID) | Comportamento |
|---|---|
17000000000000001 | Envio aceito (instagram.message.sent) e confirmação de leitura (instagram.message.read); a janela de 24h fica sempre aberta. |
17000000000000002 | A Meta recusa com o erro 551 (pessoa indisponível): 422 meta_error, mensagem failed na conversa e instagram.message.failed. |
17000000000000003 | Envio aceito e, segundos depois, o contato reage (instagram.message.reaction) e responde (instagram.message.received). Se a mensagem levou opções de resposta, a resposta volta como o toque no primeiro chip de texto, com o payload dele em context.quick_reply.payload (só o content_type: "text" carrega payload — os de perfil quem preenche é o Instagram). |
17000000000000004 | Janela de 24h vencida, dentro dos 7 dias: texto livre é 422 window_closed e o envio só sai com tag: "human_agent" — enquanto a etiqueta estiver em liberação, é 422 window_closed com ou sem ela. |
| qualquer outro IGSID | 422 window_closed — como em produção: no Instagram quem abre a conversa é sempre o contato. |
Envio pelo sandbox não consome a franquia do plano, e a conta sintética é invisível para uma chave bz_live_ (e vice-versa): as leituras de /v1 filtram o ambiente nos dois sentidos, inclusive GET /v1/events.
Evitar envio em dobro: Idempotency-Key
Duas chamadas iguais podem mandar duas mensagens ao contato. Isso acontece quando o seu sistema repete a chamada depois de um timeout ou quando dois processos disparam o mesmo envio. Mande o header Idempotency-Key e só o primeiro pedido com aquela chave envia:
POST /api/v1/messages
Idempotency-Key: entrega-8431-2026-10-20
{
"to": "+5531988887777",
"type": "template",
"template": { "name": "entrega_pronta", "language": { "code": "pt_BR" } }
}
# A mesma chave e o mesmo corpo de novo: nada é enviado
HTTP/1.1 201 Created
Idempotency-Replayed: true
{ "id": "0f8a4c1e-...", "wamid": "wamid.HBgN...", "status": "sent", ... }A chave precisa vir do evento no seu sistema, não de um valor novo a cada chamada. Para um aviso diário, junte o que identifica aquele aviso (ex.: entrega-<id da assinatura>-<data>). Um UUID aleatório por chamada não protege nada: cada processo teria a sua chave, e as duas mensagens sairiam.
- Formato: de 8 a 200 caracteres ASCII, sem espaços. Fora disso, 422
invalid_idempotency_key. - A chave vale por chave de API (ou por autorização OAuth). Dois processos com chaves de API diferentes não se enxergam: use a mesma chave de API onde o mesmo envio pode se repetir.
- Mesma chave e mesmo corpo: a API devolve a resposta original, com o mesmo status e o header
Idempotency-Replayed: true, sem enviar de novo. A ordem dos campos no JSON não importa. A chave vale por 24 horas depois do envio; passado esse prazo, ela envia de novo. - Mesma chave com outro corpo: 409
idempotency_conflict, e nada é enviado. - Primeiro pedido ainda em andamento, ou que falhou no meio sem resultado conhecido: 409
idempotency_pending. A mensagem pode ter saído. Concilie como num envio ambíguo e, se decidir reenviar, use outra chave: essa fica presa nesse estado. - Recusa antes de a Meta aceitar (ex.:
outside_window,quota_exceeded,meta_error422): a chave é liberada. Corrija e repita com a mesma chave.
Mesmo sem a chave, o template não sai em dobro em seguida: o mesmo template, com os mesmos parâmetros e para o mesmo contato, aceito pela Meta há menos de 60 segundos, recebe 409 duplicate_message, e nada é enviado. A message traz o wamid do primeiro. Isso vale também com uma chave nova: para mandar o mesmo template de novo de propósito, espere 60 segundos. Se a Mensagem anterior falhou, a nova tentativa sai. Texto, mídia e mensagem interativa não passam por essa regra, e o sandbox também não: lá a cópia sai.
No SDK, a chave vai no último argumento de qualquer método de envio (send, sendTemplate, sendMedia, sendInteractive, sendLocation, sendReaction):
await boto.messages.sendTemplate(
{ to, template },
{ idempotencyKey: `entrega-${assinaturaId}-${data}` },
);Na CLI, use --idempotency-key em botozap messages send e nos outros comandos de envio. No MCP, prepare_send_intent gera a chave e as ferramentas de envio recebem idempotency_key.
A chave evita o pedido em dobro, mas não decide se vale tentar de novo depois de uma falha de entrega. O evento whatsapp.message.failed, que chega depois pelo webhook, traz o código da Meta em errors. Conta travada (131031), mensagem que não pode ser entregue (131026, como número sem WhatsApp) ou um pedido do contato para parar de receber não se resolvem com outra tentativa imediata (veja Eventos de webhook). Depois de um 131031, o BotoZap recusa os templates da conta por 5 minutos com account_locked, sem chamar a Meta.
Erros de envio
Todo erro de POST /api/v1/messages vem no envelope { "error": { "code", "message" } } com quatro campos extras de diagnóstico, para você decidir se pode repetir sem mandar a mensagem duas vezes:
outcome—rejected(recusado antes de a Meta aceitar; a mensagem não saiu) ouunknown(a chamada à Meta começou e o resultado não é conhecido; ela pode ter saído);retry—after_correction(corrija algo antes: campo, plano, conexão),backoff(falha temporária antes da Meta: repita com espera crescente),reconcile_first(consulte a mensagem e os eventos antes de repetir) ouunknown(causa não comprovada: investigue antes de repetir);next_step— a orientação em português, pronta para log ou para um operador;meta_code— o código numérico da Graph API, só quando a Meta respondeu com erro.
A API não repete nada sozinha. Os códigos abaixo estão na ordem em que são avaliados; os de validação vêm antes de qualquer consulta, e a Meta só é chamada depois de todos passarem. Erros comuns a toda a API (401, 500 etc.) estão em Erros.
| HTTP | code | Quando acontece | O que fazer | outcome / retry |
|---|---|---|---|---|
| 403 | forbidden_scope | A chave não tem o escopo messages:send. | Use uma chave com o escopo ou peça ao dono da Conta para ajustá-lo. | rejected / after_correction |
| 429 | rate_limited | Orçamento de requisições da REST /v1 por Conta esgotado, ou o teto de envios por Conta. | Respeite o cabeçalho Retry-After e repita com backoff. | rejected / backoff |
| 400 | invalid_json | O corpo não é JSON válido. | Corrija o corpo. | rejected / after_correction |
| 422 | invalid_idempotency_key | Idempotency-Key fora do formato: menos de 8 ou mais de 200 caracteres, espaço ou caractere fora do ASCII. | Corrija a chave. Nada foi enviado. | rejected / after_correction |
| 503 | idempotency_unavailable | Não foi possível registrar a Idempotency-Key. A Meta não foi chamada. | Repita com a mesma chave e backoff. | rejected / backoff |
| 409 | idempotency_conflict | A Idempotency-Key já foi usada, nas últimas 24h, com outro corpo. | Nada foi enviado agora. Para um envio diferente, use outra chave. | rejected / after_correction |
| 409 | idempotency_pending | A mesma Idempotency-Key está com um envio em andamento ou de resultado desconhecido. | Não troque a chave para forçar: consulte a conversa e os Eventos antes. Se decidir reenviar, aí sim use outra chave. | unknown / reconcile_first |
| 404 | file_not_found | file_id que não é de um arquivo ativo da biblioteca desta Conta (inexistente, de outra Conta ou arquivado). | Confira o id em GET /v1/ai/files. Nada foi enviado. | rejected / after_correction |
| 422 | file_not_ready | O arquivo da biblioteca ainda está convertendo (processing) ou não foi convertido (failed). | Espere o status ready em GET /v1/ai/files/{id}, ou envie outra versão do arquivo. | rejected / after_correction |
| 422 | file_type_mismatch | O type do envio não é o do arquivo (ex.: type: "image" com um vídeo). | Use o type do media_type do arquivo. | rejected / after_correction |
| 503 | storage_unavailable | O armazenamento dos arquivos não respondeu ao assinar o link do file_id. | Repita em instantes. Nada foi enviado. | rejected / backoff |
| 422 | missing_to | to ausente ou fora de formato: não é telefone E.164 nem BSUID. | Informe o telefone em E.164 ou o BSUID. | rejected / after_correction |
| 422 | invalid_request | Campo com forma inválida: to_mode diferente de raw, texto acima de 4096 caracteres, caption em áudio ou acima de 1024, link que não é https, mídia por id, template.components fora do teto, template.language.code malformado, consent_basis inválido, interactive ou location fora do formato ou dos limites (campo desconhecido incluso). | A message diz qual campo; corrija e envie de novo. | rejected / after_correction |
| 422 | channel_not_supported | Recurso que o WhatsApp não tem: tag (a etiqueta human_agent é do Instagram) ou quick_replies (os botões do WhatsApp saem em interactive ou no Template). | Retire o campo. Para botões, use interactive ou um Template com botões. | rejected / after_correction |
| 422 | channel_mismatch | from é um Número do WhatsApp e to é um IGSID do Instagram. | Use from e to do mesmo canal. GET /v1/channel_accounts lista as origens. | rejected / after_correction |
| 422 | unsupported_type | type que o WhatsApp não envia pela API (veja a tabela de tipos), ou interactive.type fora de button, list e cta_url (ex.: flow, product). | Use text, template, image, video, audio, document, interactive, location ou reaction; em interactive, button, list ou cta_url. | rejected / after_correction |
| 422 | missing_text | type: "text" sem text.body. | Mande o texto em text.body. | rejected / after_correction |
| 422 | missing_template | type: "template" sem template.name. | Informe o nome do template aprovado. | rejected / after_correction |
| 422 | missing_media | Tipo de mídia sem o objeto correspondente ou sem link. | Envie { link: "https://..." } no campo do tipo (image, video...). | rejected / after_correction |
| 422 | invalid_voice | audio.voice: true com um link que responde outro formato que não audio/ogg (Opus). | Envie o arquivo .ogg com Opus mono, ou mande sem voice como áudio comum. | rejected / after_correction |
| 422 | missing_reaction_target | type: "reaction" sem reaction.message_id. | Informe o id (UUID) ou o wamid da mensagem recebida a reagir. | rejected / after_correction |
| 422 | invalid_reaction | reaction.emoji que não é um único emoji (texto, dígito solto, dois emojis) ou que não é texto. | Mande um emoji só, ou "" para retirar a reação. | rejected / after_correction |
| 422 | no_phone | Nenhum Número ativo no ambiente da chave, ou o from não é um Número ativo da Conta. | Confira o Número em GET /v1/phone_numbers e a Conexão dele. | rejected / after_correction |
| 422 | ambiguous_phone | A Conta tem mais de um Número ativo e o envio não trouxe from. | Informe from com o phone_number_id da Meta ou o UUID do Número. | rejected / after_correction |
| 422 | outside_window | Texto, mídia, interactive, location ou reaction com a janela de 24h fechada. | Envie um template aprovado ou espere o contato escrever. | rejected / after_correction |
| 422 | reaction_target_not_found | reaction.message_id não é uma mensagem da conversa com este contato (inclusive mensagem de outra conversa). | Use o id ou o wamid de uma mensagem que este contato enviou, pelo mesmo Número. | rejected / after_correction |
| 422 | reaction_target_invalid | O alvo é uma mensagem enviada pela empresa, outra reação ou uma mensagem que o contato apagou. | Reaja a uma mensagem recebida do contato. | rejected / after_correction |
| 422 | reaction_target_expired | O alvo tem mais de 30 dias (limite da Meta para reação). | Responda com texto; a Meta não aceita reação a mensagens mais antigas. | rejected / after_correction |
| 422 | reply_target_not_found | reply_to.message_id não é uma mensagem da conversa com este contato. | Use o id ou o wamid de uma mensagem desta conversa. | rejected / after_correction |
| 422 | reply_target_unavailable | A mensagem citada é uma reação, foi apagada ou é um envio que não saiu. | Cite outra mensagem da conversa, ou envie sem reply_to. | rejected / after_correction |
| 422 | account_restricted | Template a partir de uma WABA com banimento ou restrição ativa na Meta, ou de um número que a Meta baniu (status do número na Meta: BANNED). Resposta dentro da janela não passa por essa checagem. | O dono resolve a restrição no WhatsApp Manager; respostas na janela continuam saindo. Número banido: o pedido de análise é feito no WhatsApp Manager ou, se o número também é usado no app WhatsApp Business, pelo próprio app; nada sai por ele, nem resposta. Quando a Meta liberar, o BotoZap percebe em cerca de 15 minutos e o template volta a sair. | rejected / after_correction |
| 422 | account_locked | Template de um número cuja conta do WhatsApp Business recebeu da Meta "Business Account locked" (131031) há menos de 5 minutos. O BotoZap recusa sem chamar a Meta, para não insistir enquanto a conta está travada. Resposta dentro da janela não passa por essa checagem. | Tente de novo depois do prazo que a mensagem informa; nada foi enviado. A Meta costuma mostrar o número liberado antes de a conta voltar: se ele também é usado no app WhatsApp Business, a conta só volta depois de o número ser reconectado pelo app. Se a próxima tentativa receber 131031 de novo, a recusa vale por mais 5 minutos. | rejected / backoff |
| 422 | auth_template_bsuid | Template de autenticação para um contato conhecido só por BSUID. | Envie para o telefone do contato. | rejected / after_correction |
| 422 | consent_revoked | Template MARKETING para um Contato com consentimento de marketing revogado (com ou sem consent_basis), ou para um telefone que recusou por qualquer número do mesmo Cliente, mesmo excluído ou ainda sem contato no número de envio. | Não reenvie marketing: só o próprio contato desfaz a recusa. Templates UTILITY e AUTHENTICATION seguem liberados. | rejected / after_correction |
| 409 | not_connected | O Número não tem token de acesso: a conexão ficou incompleta. | Refaça a conexão do Número no painel. | rejected / after_correction |
| 503 | billing_unavailable | A consulta de consumo do mês falhou. No WhatsApp ela vem na mesma leitura do Número e do contato, e a falha dessa leitura é 500 internal_error. A falha na leitura da Conta (o plano) para antes, com 500 internal_error. | Falha temporária antes da Meta. Repita com backoff, sem mexer no plano. | rejected / backoff |
| 429 | free_form_limit_reached | Plano Free: o teto mensal de respostas 1:1 (texto, mídia, interactive ou location na janela) acabou. Painel, API e agentes de IA somam no mesmo teto. Reação não conta nem é barrada pelo teto. | Assine o BotoZap (1:1 ilimitado) ou espere o próximo mês. Templates seguem pela cota de templates. | rejected / after_correction |
| 402 | business_payment_required | O negócio do Número está pausado: a fatura do slot adicional dele venceu há mais de 7 dias. | Pague a fatura do slot em Plano. Pagou, libera na hora. | rejected / after_correction |
| 403 | account_paused_meta | A Meta registrou duas violações de política da Conta em 14 dias, e o BotoZap pausou os envios dela. Ela continua recebendo. | Fale com o suporte do BotoZap para revisar e liberar. Pare de repetir a chamada até lá. | rejected / after_correction |
| 402 | free_cap | Plano Free: o negócio do Número passou do teto de 1 negócio e está suspenso. Ele continua recebendo. | Assine o BotoZap ou apague o outro negócio (ou desconecte os canais dele). | rejected / after_correction |
| 402 | free_number_cap | Plano Free: o Número passou do teto de 1 número e está suspenso. Ele continua recebendo. | Assine o BotoZap ou desconecte o outro número. | rejected / after_correction |
| 402 | quota_exceeded | Template além da cota mensal de templates do plano (todo plano com teto, não só o Free), ou assinatura com pagamento pendente (aí vale para qualquer envio). | No Free, assine o BotoZap. No plano pago, espere o dia 1º ou fale com o suporte; trocar de plano pago não aumenta a cota. Com pagamento pendente, regularize a cobrança. Pare de repetir a chamada até lá. | rejected / after_correction |
| 409 | conversation_dispatch_busy | Há um envio em andamento na mesma conversa, ou um envio sem confirmação da Meta há menos de 5 minutos. | Este envio não saiu. Repita depois de alguns minutos: a conversa volta a aceitar envios em cerca de 5 minutos. Antes, confira se a mensagem anterior chegou, porque o BotoZap nunca a reenvia sozinho. Se ela foi um envio manual do WhatsApp (API ou painel) que a Meta não confirmou nesse prazo, ela aparece em GET /v1/conversations/{id}/pending-sends, e POST /v1/conversations/{id}/pending-sends/{send_id} diz se saiu. | rejected / reconcile_first |
| 409 | duplicate_message | O mesmo template, com os mesmos parâmetros e para o mesmo contato, foi aceito pela Meta há menos de 60 segundos, e a Mensagem dele não falhou. A message traz o wamid da primeira. | Nada foi enviado agora, e o contato já recebeu a primeira. Não repita: confira no seu sistema por que o mesmo envio saiu duas vezes. Para mandar o mesmo template de novo de propósito, espere 60 segundos. | rejected / after_correction |
| 503 | dispatch_unavailable | Não foi possível abrir o registro de envio da conversa, ou a conversa foi apagada durante o pedido. A Meta não foi chamada. | Repita com backoff. | rejected / backoff |
| 409 | whatsapp_disconnected | A Meta recusou o token da WABA (erro 190 da Graph): expirado ou revogado. | Reconecte o Número em Configurações › Canais no painel. | rejected / after_correction |
| 422 | meta_error | A Meta limitou o ritmo de envio: meta_code 130429 (número), 80007 (conta do WhatsApp Business) ou 4 (aplicativo). Nada saiu. | Espere e repita com backoff, reduzindo o ritmo de envio. | rejected / backoff |
| 422 | meta_error | Mensagens demais para o mesmo contato em pouco tempo (meta_code 131056). Nada saiu. | Espere antes de repetir para esse contato; os outros contatos seguem liberados. | rejected / backoff |
| 422 | meta_error | A Meta restringiu o número porque mensagens anteriores foram bloqueadas ou marcadas como spam (meta_code 131048). | O proprietário confere a qualidade do número no WhatsApp Manager antes de repetir. | rejected / after_correction |
| 422 | meta_error | A Meta recusou o envio (resposta 4xx) por outro motivo. O código dela vem em meta_code. | Leia a message e o meta_code; corrija antes de repetir. | rejected / unknown |
| 502 | meta_error | A Meta falhou (5xx) ou não respondeu. A mensagem pode ter saído. | Não reenvie às cegas: consulte a conversa e os eventos antes. | unknown / reconcile_first |
| 502 | send_failed | Falha de rede ou inesperada durante a chamada à Meta. A mensagem pode ter saído. | Mesmo cuidado do meta_error 502: concilie antes de repetir. | unknown / reconcile_first |
| 503 | idempotency_pending | Com Idempotency-Key, o processamento falhou no meio do envio. A mensagem pode ter saído, e a chave fica presa nesse estado. | Concilie antes de repetir. Repetir a mesma chave responde 409 idempotency_pending; se decidir reenviar, use outra chave. | unknown / reconcile_first |
Limites do plano
São duas réguas separadas. Template (mensagem iniciada pelo negócio) consome a cota mensal de templates do plano — de qualquer plano com teto, não só do Free. Esgotada, o envio de template responde 402 quota_exceeded; o mesmo código aparece em qualquer envio quando a assinatura está com pagamento pendente (veja Transmissões e limites):
Erro: cota mensal de templates esgotada
Template (mensagem iniciada pelo negócio) consome a cota mensal de templates do plano, em qualquer plano com teto. Esgotada a cota, novos templates são recusados antes de chamar a Meta até o próximo período ou um upgrade.
curl https://botozap.com.br/api/v1/messages \
-X POST \
-H "X-API-Key: $BOTOZAP_KEY" \
-H "Content-Type: application/json" \
-d '{
"to": "+5511966665555",
"type": "template",
"template": {
"name": "aviso_importante",
"language": {
"code": "pt_BR"
}
}
}'Resposta 402
{
"error": {
"code": "quota_exceeded",
"message": "Limite de 500 templates por mês do plano Free atingido. Assine o BotoZap em /plano para enviar mais.",
"outcome": "rejected",
"retry": "after_correction",
"next_step": "Confira Plano e uso da Conta; regularize a cobrança ou aguarde a renovação do limite indicado antes de tentar novamente."
}
}Resposta 1:1 (texto ou mídia dentro da janela) não consome esta cota. No Free ela tem teto próprio, com 429 `free_form_limit_reached`.
Nos planos pagos o teto é o mesmo em todos (10.000 por mês), então a mensagem não sugere trocar de plano: diz que o envio de templates volta no dia 1º e que, para enviar mais no mês, é só falar com o suporte.
Com a assinatura paga em pagamento pendente, qualquer envio responde 402 `quota_exceeded`, com uma mensagem pedindo a regularização.
Chave sandbox não passa por esta cota.
Resposta 1:1 (texto, mídia, interactive ou location dentro da janela) não consome a cota de templates. No BotoZap ela é ilimitada; no Free, o teto é de 500 respostas 1:1 por mês, somando painel, API e agentes de IA. Passado o teto, a resposta é 429 free_form_limit_reached (a reação não conta e continua saindo) — não confunda com o 429 rate_limited, que é o limite de requisições (120 a cada 10 segundos por Conta, dos quais no máximo 60 envios) e passa sozinho:
Erro: teto de respostas 1:1 do Free
No plano Free, a resposta 1:1 (texto ou mídia dentro da janela de 24h) tem teto de 500 por mês, somando painel, API e agentes de IA. Atingido o teto, a API recusa antes de chamar a Meta. No BotoZap a resposta 1:1 é ilimitada.
curl https://botozap.com.br/api/v1/messages \
-X POST \
-H "X-API-Key: $BOTOZAP_KEY" \
-H "Content-Type: application/json" \
-d '{
"to": "+5511944443333",
"type": "text",
"text": {
"body": "Claro, já verifico para você."
}
}'Resposta 429
{
"error": {
"code": "free_form_limit_reached",
"message": "Limite de 500 respostas 1:1 por mês do plano Free atingido. Assine o BotoZap em /plano para respostas ilimitadas.",
"outcome": "rejected",
"retry": "after_correction",
"next_step": "Confira Plano e uso da Conta; regularize a cobrança ou aguarde a renovação do limite indicado antes de tentar novamente."
}
}Não confunda com o 429 `rate_limited`, que é o limite de requisições e passa sozinho. Este só libera no próximo mês ou com a assinatura do BotoZap.
Template não entra neste teto: ele consome a cota de templates (402 `quota_exceeded`).
Se a consulta de cobrança estiver indisponível (no Instagram, a do consumo do mês; numa reação, a do bloqueio do Cliente ou do número), a API responde 503 billing_unavailable, com outcome: "rejected" e retry: "backoff". A mensagem foi recusada antes do envio à Meta: tente novamente com backoff. Essa falha temporária não exige upgrade nem alteração da assinatura. No WhatsApp, o consumo do mês vem na mesma leitura do Número e do contato, e a falha dessa leitura é 500 internal_error, que também pede backoff. Sandbox não passa por nenhuma das duas réguas.
Quando a Meta responde
Uma recusa da Meta (4xx) vem como 422 meta_error com o código dela em meta_code:
HTTP/1.1 422 Unprocessable Entity
{
"error": {
"code": "meta_error",
"message": "<mensagem da Meta>",
"outcome": "rejected",
"meta_code": 132000,
"retry": "unknown",
"next_step": "Causa ou transitoriedade não comprovada. ..."
}
}O token recusado (Graph 190) é a exceção: vira 409 whatsapp_disconnected, e o caminho é reconectar o Número em Configurações › Canais no painel. E quando a própria Meta falha ao processar o envio (timeout ou 5xx), o resultado é ambíguo. Veja com cuidado antes de reenviar:
Erro: a Meta falhou ao processar o envio
A Graph API respondeu com um erro de servidor (5xx) ao tentar enviar a mensagem.
curl https://botozap.com.br/api/v1/messages \
-X POST \
-H "X-API-Key: $BOTOZAP_KEY" \
-H "Content-Type: application/json" \
-d '{
"to": "+5511955554444",
"type": "template",
"template": {
"name": "status_pedido",
"language": {
"code": "pt_BR"
}
}
}'Resposta 502
{
"error": {
"code": "meta_error",
"message": "Erro interno do Graph.",
"outcome": "unknown",
"retry": "reconcile_first",
"next_step": "Consulte a mensagem e os Eventos da Conta antes de repetir. Aceitação não prova entrega; um resultado desconhecido pode ter sido aceito pela Meta."
}
}`outcome: "unknown"` e `retry: "reconcile_first"`: confira o resultado antes de repetir. Quando a Meta informa um código de erro, ele vem em `meta_code`.
Um 502 (ou timeout) aqui NÃO prova que a mensagem não saiu — a Meta pode tê-la aceitado do lado dela mesmo assim.
Sem identificador confirmado, a mensagem não aparece em `GET /api/v1/messages` e a cota do período não é debitada. Por cerca de 5 minutos, novos envios nessa conversa recebem 409 `conversation_dispatch_busy`; depois ela volta a aceitar envios, e o BotoZap não reenvia a mensagem sozinho. Antes de repetir, confira se ela chegou ao contato.
O contrato completo de confiabilidade e os casos ambíguos de envio estão em Confiabilidade e entrega.
Listar e buscar mensagens
GET /api/v1/messages lista as mensagens da conta, mais recentes primeiro, paginada por cursor (limit de 1 a 100, padrão 20; after/before com os cursores de paging):
Listar mensagens
Lista as mensagens da conta, mais recentes primeiro, paginado por cursor. `sort=created_at` (padrão) ordena pela chegada ao BotoZap; `sort=event_at`, pela data real da mensagem.
curl https://botozap.com.br/api/v1/messages?limit=2 \
-H "X-API-Key: $BOTOZAP_KEY"Resposta 200
{
"data": [],
"paging": {
"cursors": {
"before": "MjAyNi0wNy0xNFQxMjowMDowMC4wMDBa",
"after": "MjAyNi0wNy0xNFQxMjowMDowMC4wMDBa"
},
"next": "MjAyNi0wNy0xNFQxMjowMDowMC4wMDBa",
"previous": "MjAyNi0wNy0xNFQxMjowMDowMC4wMDBa"
}
}`sort=created_at` (padrão) é a ordem de chegada ao BotoZap: use-a para sincronizar com `before`, porque nenhuma mensagem entra atrás de um cursor já lido. Nessa ordem, o histórico importado do app na coexistência (`source: "history"`) aparece como recente, porque chegou agora.
`sort=event_at` ordena pela data real da mensagem (`event_at`) — o jeito de mostrar uma conversa em ordem cronológica com o histórico importado no lugar certo. O cursor carrega o valor da ordem que o gerou (em `event_at`, junto com o `id`, para mensagens do mesmo segundo não se perderem entre páginas): use-o com o mesmo `sort`. Outro valor em `sort` responde 422 `invalid_request`.
| Filtro | Aceita | Valor que não casa |
|---|---|---|
phone_number_id | O phone_number_id da Meta ou o UUID do Número. | Número que não é da conta: página vazia. |
conversation_id | UUID da conversa (o id de GET /api/v1/conversations). | Não-UUID ou de outra conta: página vazia. |
direction | inbound ou outbound. | Ignorado (lista sem o filtro). |
status | queued, sent, delivered, read, failed ou received. | Ignorado. |
message_type | O type da mensagem: text, image, video, audio, document, sticker, location, contacts, interactive, button, reaction, order, template, system ou unknown. | Ignorado. |
has_media | true (imagem, vídeo, áudio, documento ou sticker) ou false. | Ignorado. |
channel | whatsapp ou instagram. | 422 invalid_channel. |
channel_account_id | UUID da Conta de canal. | Não-UUID: 422 invalid_channel_account; de outra conta: página vazia. |
Além das colunas do exemplo, cada mensagem traz:
reply_to— a mensagem citada (responder citando):{ message_id, external_id }ounull;played_at— mensagem de voz enviada: quando o contato ouviu pela primeira vez;nullantes disso e nos outros tipos;transcription— áudio recebido: a transcrição que o agente de IA já fez ao atender;nullquando não houve. Ler a mensagem não gera transcrição.
Repare na diferença: filtro com valor fora da lista é ignorado (você recebe tudo, não nada). Confira a grafia antes de tratar a lista como filtrada. A chave sandbox só vê as mensagens do sandbox, e a de produção só as de produção.
Ordem da listagem: sort
sort=created_at (o padrão) ordena pela chegada ao BotoZap. É a ordem para sincronizar: com before, você pega o que chegou depois do último cursor, e nada entra atrás de um cursor já lido — nem uma mensagem que a Meta reentregou com atraso.
sort=event_at ordena pela data real da mensagem (event_at: o horário da Meta quando existe, senão a chegada). Use para mostrar uma conversa em ordem cronológica. A diferença aparece no histórico importado na coexistência: ele chega agora, mas as mensagens são de até 180 dias atrás. Em created_at elas aparecem como as mais recentes; em event_at, no lugar certo da conversa. O cursor carrega o valor da ordem que o gerou, então use-o com o mesmo sort; em event_at ele também leva o id da mensagem, para que mensagens do mesmo segundo não se percam entre páginas. Outro valor em sort responde 422 invalid_request.
{id} em GET /api/v1/messages/{id} aceita o UUID interno da mensagem ou o wamid da Meta:
Buscar uma mensagem por id
`{id}` aceita o uuid interno da mensagem OU o `wamid` da Meta.
curl https://botozap.com.br/api/v1/messages/5b0a9d0e-6e1a-4f3b-8c2d-1a9f6e0b7c11 \
-H "X-API-Key: $BOTOZAP_KEY"Resposta 200
{
"data": {
"id": "5b0a9d0e-6e1a-4f3b-8c2d-1a9f6e0b7c11",
"wamid": "wamid.HBgNNTU5MTk5OTk5OTk5FQIAERgSM0FCQzFEMkUzRjRBNUI2QzdEAA==",
"external_id": "wamid.HBgNNTU5MTk5OTk5OTk5FQIAERgSM0FCQzFEMkUzRjRBNUI2QzdEAA==",
"channel": "whatsapp",
"channel_account": {
"id": "5b0a9d0e-6e1a-4f3b-8c2d-1a9f6e0b7c11",
"channel": "whatsapp",
"display": "+5511999990000"
},
"conversation_id": "5b0a9d0e-6e1a-4f3b-8c2d-1a9f6e0b7c11",
"phone_number_id": "5b0a9d0e-6e1a-4f3b-8c2d-1a9f6e0b7c11",
"contact_id": "5b0a9d0e-6e1a-4f3b-8c2d-1a9f6e0b7c11",
"direction": "outbound",
"type": "text",
"status": "sent",
"source": "api",
"content": {
"body": "Mensagem de teste"
},
"context": null,
"error": null,
"has_media": false,
"reply_to": null,
"played_at": null,
"transcription": null,
"revoked_at": null,
"event_at": "2026-07-14T12:00:00.000Z",
"wa_timestamp": null,
"created_at": "2026-07-14T12:00:00.000Z"
}
}Mensagens editadas e apagadas no Instagram
Quando o contato edita um direct, a mensagem passa a trazer o texto novo em content (body no texto, caption na mídia) e content.edited com { count, at }: quantas vezes ela foi editada e quando foi a última edição. Quando ele cancela o envio, a mensagem ganha revoked_at com o horário. As duas mudanças também chegam como os Eventos instagram.message.edited e instagram.message.revoked, por GET /api/v1/events e pelo webhook; veja Eventos. O SDK tipa content.edited e revoked_at.
De onde veio a mensagem: source
Cada mensagem traz source, que diz por qual caminho ela entrou na conta. Não há filtro por source: filtre do seu lado.
source | O que é |
|---|---|
api | O padrão: o que passou pela Cloud API através da BotoZap — seus envios por POST /api/v1/messages, tudo o que a equipe envia pela tela de Conversas do painel (texto, templates e mensagens interativas) e as mensagens que o contato mandou. |
app | O eco do que o atendente mandou pelo app WhatsApp Business no celular, num número em coexistência. Não passou pela BotoZap. |
history | Conversas antigas importadas do app quando um número em coexistência é conectado (nenhuma, 30 ou 180 dias, conforme a escolha na conexão). Chegam em lotes, podem levar horas e trazem as duas direções. Veja Coexistência. |
broadcast | Disparo de uma transmissão. |
automation | Enviada pela própria plataforma, sem pessoa nem chamada sua — por exemplo, a confirmação automática de descadastro. |
Numa integração com coexistência (o mesmo número no app e na API), espere mensagens outbound que você não enviou: são as app, digitadas no celular. Cada uma também chega por webhook como whatsapp.message.echo aos Endpoints que assinam a categoria opt-in app_messages. Nem elas nem as history abrem a janela de 24h — só uma mensagem nova do contato abre. As history também não geram whatsapp.message.received (nem no webhook, nem em GET /api/v1/events) e não acionam agentes, follow-ups ou réguas: são importação, não conversa nova. Elas ficam disponíveis em GET /api/v1/messages (use sort=event_at para vê-las na ordem cronológica) e nas conversas de GET /api/v1/conversations, onde o last_message também traz source.
Montar um inbox (conversas)
Um inbox lista conversas, não mensagens. GET /api/v1/conversations devolve as conversas paginadas por cursor, e include=last_message traz junto a última mensagem de cada uma — sem esse parâmetro você faria uma chamada extra por conversa (20 conversas = 21 requisições). Some customer_id= para ver só as conversas dos números de um cliente; um cliente que não seja da sua conta responde 422 invalid_customer.
Listar conversas com a última mensagem
Lista as conversas da conta, mais recentes primeiro, paginado por cursor. `include=last_message` embute a última mensagem de cada conversa (`null` quando a conversa ainda não tem nenhuma) — é o que evita uma chamada extra por conversa ao montar um inbox. Para ver só as conversas de um cliente, some `customer_id=<uuid do cliente>`.
curl https://botozap.com.br/api/v1/conversations?limit=2&include=last_message \
-H "X-API-Key: $BOTOZAP_KEY"Resposta 200
{
"data": [],
"paging": {
"cursors": {
"before": "MjAyNi0wNy0xNFQxMjowMDowMC4wMDBa",
"after": "MjAyNi0wNy0xNFQxMjowMDowMC4wMDBa"
},
"next": "MjAyNi0wNy0xNFQxMjowMDowMC4wMDBa",
"previous": "MjAyNi0wNy0xNFQxMjowMDowMC4wMDBa"
}
}Sem `include`, a resposta não traz o campo `last_message` — o contrato antigo continua idêntico.
`last_message` é um subconjunto do objeto de `GET /api/v1/messages` (mesmos nomes e semântica, incluindo `type` e `source`). `source: "history"` = mensagem importada do app WhatsApp Business na coexistência, não uma mensagem nova; `app` = enviada pela equipe no app. Para o histórico completo da conversa, use `GET /api/v1/messages?conversation_id=&sort=event_at`.
`customer_id` que não seja um cliente da sua conta responde `422 invalid_customer` — nunca uma lista de outro tenant.
`entry_point` é `ctwa` quando algum inbound da conversa veio de anúncio Click-to-WhatsApp (não volta para `organic`), `organic` quando só houve inbound sem anúncio e `null` quando a origem é desconhecida. `referral` traz o último clique em anúncio (`source_id`, `source_url`, `headline`, `ctwa_clid`, `received_at`) ou `null`.
`fep_expires_at` é o fim da janela grátis do Free Entry Point informado pela Meta no status de um envio. `fep_reply_by` é uma ESTIMATIVA (último clique + 24h) do prazo para responder e abrir essa janela; fica `null` quando não há clique ou a janela já abriu. Nenhum dos dois muda a janela de 24h para texto livre.
A lista completa de filtros da rota está na Referência.
Cenários do sandbox
Números mágicos do ambiente sandbox. Cada um simula um ciclo de vida diferente, disparando seu webhook assinado exatamente como em produção:
| Destinatário | Comportamento |
|---|---|
+5500000000001 | sent → delivered → read; janela de 24h sempre aberta (bom para o primeiro texto). |
+5500000000002 | Falha: sent → failed, com erro Meta 131026 (não entregável). |
+5500000000003 | sent → delivered + resposta inbound simulada, que abre a janela real de 24h. |
| qualquer outro número | sent → delivered; janela de 24h se comporta como em produção (fechada até um inbound de verdade). |
Instagram: perguntas e menu
No painel, configure em Canais › conta do Instagram › Direct: perguntas e menu. A tela Direct do Instagram é configuração da conta.
Em Canais › Instagram › Perguntas e menu, configure os ice breakers anteriores à primeira mensagem e os atalhos da conversa. A API oferece as mesmas ações com o UUID da Conta de canal, obtido em GET /v1/channel_accounts.
GET /v1/channel_accounts/:id/messenger-profile lê o estado desejado salvo. PATCH atualiza as seções enviadas: campos ausentes ficam como estão; null ou uma lista vazia remove a seção. DELETE remove ambas. POST /v1/channel_accounts/:id/messenger-profile/sync, sem corpo, verifica a Meta e restaura a configuração salva quando necessário.
São até 4 perguntas de 80 caracteres, até 5 atalhos com títulos de 20 caracteres e payloads de 1.000 caracteres. Links usam HTTP(S), sem credenciais, até 2.000 caracteres. Perguntas de 80 caracteres e links de 2.000 são limites do BotoZap; 5 itens segue a recomendação de experiência da Meta. Os atalhos aceitam postback (título + payload) ou web_url (título + url). O toque em pergunta/ação entra na Conversa com o texto exibido e abre a janela de 24 horas; abrir link não produz uma pergunta.
Salvar perguntas e menu do Instagram
curl https://botozap.com.br/api/v1/channel_accounts/5b0a9d0e-6e1a-4f3b-8c2d-1a9f6e0b7c11/messenger-profile \
-X PATCH \
-H "X-API-Key: $BOTOZAP_KEY" \
-H "Content-Type: application/json" \
-d '{
"ice_breakers": [
{
"question": "Onde fica a loja?",
"payload": "location"
}
],
"persistent_menu": [
{
"type": "postback",
"title": "Horários",
"payload": "hours"
},
{
"type": "web_url",
"title": "Ver produtos",
"url": "https://loja.exemplo.com/produtos"
}
]
}'Resposta 200
{
"data": {
"channel_account_id": "5b0a9d0e-6e1a-4f3b-8c2d-1a9f6e0b7c11",
"config": {
"ice_breakers": [
{
"question": "Onde fica a loja?",
"payload": "location"
}
],
"persistent_menu": [
{
"type": "postback",
"title": "Horários",
"payload": "hours"
},
{
"type": "web_url",
"title": "Ver produtos",
"url": "https://loja.exemplo.com/produtos"
}
]
},
"revision": 1,
"sync_status": "synced",
"synced_at": "2026-07-14T12:00:00.000Z",
"last_error_code": null,
"updated_at": "2026-07-14T12:00:00.000Z"
}
}Campos ausentes preservam a configuração; null ou [] remove a seção. O estado desejado fica guardado mesmo se a Meta falhar.
Os payloads identificam a ação; o texto da pergunta/título vira Mensagem recebida na Conversa.
Gravar perguntas ou menu exige o BotoZap, trial vigente ou Free legado até 31/10/2026; sem isso, 403 plan_restricted. Um PATCH que só remove seções (null ou []) continua liberado.
Ler a configuração salva do Instagram
curl https://botozap.com.br/api/v1/channel_accounts/5b0a9d0e-6e1a-4f3b-8c2d-1a9f6e0b7c11/messenger-profile \
-H "X-API-Key: $BOTOZAP_KEY"Resposta 200
{
"data": {
"channel_account_id": "5b0a9d0e-6e1a-4f3b-8c2d-1a9f6e0b7c11",
"config": {
"ice_breakers": [
{
"question": "Onde fica a loja?",
"payload": "location"
}
],
"persistent_menu": [
{
"type": "postback",
"title": "Horários",
"payload": "hours"
},
{
"type": "web_url",
"title": "Ver produtos",
"url": "https://loja.exemplo.com/produtos"
}
]
},
"revision": 1,
"sync_status": "synced",
"synced_at": "2026-07-14T12:00:00.000Z",
"last_error_code": null,
"updated_at": "2026-07-14T12:00:00.000Z"
}
}GET lê o espelho do banco. sync_status informa a última confirmação; use /sync para verificar a Meta agora.
Aplicar de novo o perfil de mensagens
curl https://botozap.com.br/api/v1/channel_accounts/5b0a9d0e-6e1a-4f3b-8c2d-1a9f6e0b7c11/messenger-profile/sync \
-X POST \
-H "X-API-Key: $BOTOZAP_KEY"Resposta 200
{
"data": {
"channel_account_id": "5b0a9d0e-6e1a-4f3b-8c2d-1a9f6e0b7c11",
"config": {
"ice_breakers": [
{
"question": "Onde fica a loja?",
"payload": "location"
}
],
"persistent_menu": [
{
"type": "postback",
"title": "Horários",
"payload": "hours"
},
{
"type": "web_url",
"title": "Ver produtos",
"url": "https://loja.exemplo.com/produtos"
}
]
},
"revision": 1,
"sync_status": "synced",
"synced_at": "2026-07-14T12:00:00.000Z",
"last_error_code": null,
"updated_at": "2026-07-14T12:00:00.000Z"
}
}Sem corpo. Compara com a Meta e reaplica a última configuração salva se houver divergência. Requer uma configuração previamente salva.
Reaplicar uma configuração com perguntas ou menu numa conta Free retorna 403 plan_restricted; a configuração vazia continua liberada.
Remover perguntas e menu do Instagram
curl https://botozap.com.br/api/v1/channel_accounts/5b0a9d0e-6e1a-4f3b-8c2d-1a9f6e0b7c11/messenger-profile \
-X DELETE \
-H "X-API-Key: $BOTOZAP_KEY"Resposta 200
{
"data": {
"channel_account_id": "5b0a9d0e-6e1a-4f3b-8c2d-1a9f6e0b7c11",
"config": {
"ice_breakers": [],
"persistent_menu": []
},
"revision": 1,
"sync_status": "synced",
"synced_at": "2026-07-14T12:00:00.000Z",
"last_error_code": null,
"updated_at": "2026-07-14T12:00:00.000Z"
}
}A configuração vazia permanece salva para permitir repetir uma remoção pendente sem ressuscitar itens antigos.
Gravar perguntas e menu é do BotoZap, do teste grátis e do Free legado até 31/10/2026. Numa conta Free, PATCH que adiciona itens e POST /sync de uma configuração com itens retornam 403 plan_restricted; GET, DELETE e PATCH que só remove seções (lista vazia ou null) continuam liberados.
Chaves precisam dos escopos messenger-profile:read e/ou messenger-profile:write. Sandbox não acessa este recurso. A resposta contém config, revision, sync_status, synced_at e o código seguro last_error_code. synced confirma a última aplicação; pending/error preservam o desejado para retry; unconfigured significa que ainda não há configuração salva.
Uma falha da Meta retorna o envelope de erro com profile_sync_failed, preservando o desejado. Token inválido retorna instagram_disconnected: reconecte e chame /sync. Operação simultânea retorna profile_busy, e uma confirmação não gravada retorna profile_sync_unconfirmed: repita /sync após um minuto. profile_not_configured pede salvar antes de sincronizar.
Contratos oficiais: Ice Breakers, Persistent Menu e Postback Button. A aplicação usa graph.instagram.com/{version}/me/messenger_profile com token da Conexão e as permissões já pedidas no login do Instagram.
