This is the abridged developer documentation for Messajo # Messajo > Documentação do Messajo, a camada sobre as APIs oficiais da Meta para WhatsApp, Instagram e Messenger. As APIs oficiais da Meta — WhatsApp, Instagram e Messenger — com uma chave e webhooks. Para começar você precisa de: * uma conta em [app.messajo.com](https://app.messajo.com); * uma chave de API; * um canal conectado: WhatsApp, Instagram ou Messenger. [Começar em 5 minutos](/start/quickstart/)Da chave de API à primeira mensagem. [Enviar mensagens](/send/text/)Uma página para cada tipo de mensagem. [Construir com IA](/start/build-with-ai/)llms.txt, Markdown por página e o OpenAPI. [Conectar canais](/connect/whatsapp/)WhatsApp, Instagram e Messenger. [Webhooks](/webhooks/events/)Eventos assinados no seu endpoint. [Referência da API](/reference)Todos os endpoints, com exemplos. WhatsApp Coexistência, com o app do celular funcionando junto, ou só API, com o número dedicado à integração. Instagram Direct, comentários com resposta privada e publicação, pela conta profissional. Messenger Conversas da sua Página do Facebook no mesmo formato do Instagram. # Construir com IA > Como dar ao Claude Code, ao Cursor ou ao ChatGPT o contexto certo da documentação do Messajo, com llms.txt, Markdown por página e OpenAPI. Um assistente de código acerta mais quando lê a documentação de verdade em vez de adivinhar a API. O Messajo publica a doc em formatos feitos para isso. ## O que você pode entregar ao assistente [Seção intitulada “O que você pode entregar ao assistente”](#o-que-você-pode-entregar-ao-assistente) | O quê | Onde | Para quê | | ------------- | ------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- | | Índice da doc | [`https://docs.messajo.com/llms.txt`](/llms.txt) | Índice curto: descrição da API e links para a doc completa, a resumida e o OpenAPI. Para ler uma página só, use o `.md` dela | | Doc completa | [`https://docs.messajo.com/llms-full.txt`](/llms-full.txt) | Tudo em um arquivo só, para colar em um contexto grande | | Doc resumida | [`https://docs.messajo.com/llms-small.txt`](/llms-small.txt) | Versão abreviada, para contexto pequeno | | Uma página | `.md` | A página em Markdown puro | | OpenAPI | [`/openapi.pt-BR.json`](/openapi.pt-BR.json) | Contrato exato de cada rota, corpo e erro | Os arquivos `llms*.txt` são gerados a partir das páginas em português. ## Cada página em Markdown [Seção intitulada “Cada página em Markdown”](#cada-página-em-markdown) Acrescente `.md` ao fim do endereço de qualquer página: ```text https://docs.messajo.com/start/quickstart.md https://docs.messajo.com/en/start/quickstart.md https://docs.messajo.com/es/start/quickstart.md ``` Ao lado do título de cada página há o controle **Copiar página**. Ele copia o Markdown da página para a área de transferência e, no menu, oferece **Ver como Markdown**, **Abrir no ChatGPT** e **Abrir no Claude**. Os dois últimos abrem o assistente com um pedido para ler aquela página. ## OpenAPI [Seção intitulada “OpenAPI”](#openapi) O contrato da API está em JSON, um arquivo por idioma: * [`/openapi.json`](/openapi.json): em inglês. * [`/openapi.pt-BR.json`](/openapi.pt-BR.json): em português. * [`/openapi.es.json`](/openapi.es.json): em espanhol. A [referência interativa](/reference) é gerada do mesmo arquivo, e os tipos do [SDK TypeScript](/sdk/typescript/) também. Entregue o OpenAPI quando o assistente precisar do formato exato de um corpo de requisição. ## Apontar o assistente para a doc [Seção intitulada “Apontar o assistente para a doc”](#apontar-o-assistente-para-a-doc) O caminho é o mesmo no Claude Code, no Cursor e em outros assistentes de código: 1. **Na conversa.** Cole o endereço do `llms.txt` ou do `.md` da página e peça para ler antes de escrever código. 2. **No arquivo de instruções do projeto.** Escreva o endereço uma vez no arquivo que o seu assistente lê no começo de cada sessão (como o `CLAUDE.md` ou as regras do projeto), e toda sessão começa com a doc à mão. 3. **Para formatos exatos.** Dê o `openapi.json` ou o `.md` da página da rota em questão, em vez de pedir para o assistente lembrar. Exemplo de trecho para o arquivo de instruções: ```text API do Messajo (WhatsApp, Instagram e Messenger oficiais): - Índice da documentação: https://docs.messajo.com/llms.txt - Contrato da API: https://docs.messajo.com/openapi.json - Antes de escrever código que chama a API, leia a página .md da rota. - Use o SDK @messajo/sdk; nunca invente campos fora do OpenAPI. ``` ## O que ajuda o assistente a depurar [Seção intitulada “O que ajuda o assistente a depurar”](#o-que-ajuda-o-assistente-a-depurar) Todo erro da API tem o mesmo corpo, com três campos úteis para quem está depurando (veja [Formato do erro](/errors/)): * `code`: identificador estável, seguro para tratar no código. * `docs_url`: link para o `code` em [Erros](/errors/), com o significado e o que fazer. * `request_id`: o mesmo valor do cabeçalho `X-Request-Id` (veja [X-Request-Id para suporte](/api/authentication/#x-request-id-para-suporte)). Cole o corpo do erro inteiro no assistente: o `docs_url` leva a explicação certa. ## Primeira tarefa [Seção intitulada “Primeira tarefa”](#primeira-tarefa) Um bom primeiro pedido, com o `llms.txt` já na conversa: ```text Leia https://docs.messajo.com/send/text.md e https://docs.messajo.com/webhooks/verify-signature.md. Depois, com o @messajo/sdk: 1. envie um texto para 5511999999999 usando a chave em MESSAJO_API_KEY; 2. crie um endpoint que receba webhooks e verifique a assinatura Messajo-Signature antes de tratar o evento. Se algum campo não estiver na documentação, pergunte em vez de inventar. ``` Páginas de apoio: [Enviar texto](/send/text/) e [Verificar a assinatura](/webhooks/verify-signature/). # Conceitos > As peças do Messajo: organização, conexões, chaves, destinos de eventos e as duas camadas da API. ## Organização, membros e papéis [Seção intitulada “Organização, membros e papéis”](#organização-membros-e-papéis) Tudo pertence a uma organização: conexões, chaves de API, destinos de eventos, templates e logs. Uma pessoa pode ser membro de várias organizações e troca entre elas no painel. Cada membro tem um papel: | Papel | Pode | | ----------- | ------------------------------------------------------------------------------------------------------------------------------ | | **Dono** | Tudo, inclusive cobrança e apagar a organização. Só um dono promove ou rebaixa outro dono, e a organização nunca fica sem dono | | **Admin** | Conexões, membros e convites, chaves de API, destinos de eventos, templates, logs e auditoria | | **Dev** | Chaves de API (sem a permissão `admin`), destinos de eventos, templates e logs. Vê as conexões, mas não cria nem altera | | **Leitura** | Só vê: chaves (sem o segredo), conexões, destinos, templates e logs | Dono e admin precisam ter a verificação em duas etapas (2FA) ligada para usar o painel da organização. O dono pode **redefinir o 2FA** de outro membro em **Membros**: a pessoa é desconectada e configura um novo autenticador no próximo login. Para o dono único que perdeu o autenticador, quem administra a instância faz a redefinição. O convite só vale se quem convidou ainda pode conceder o papel ([`invitation_invalid`](/errors#invitation_invalid)). **Acesso por conexão.** Dev e Leitura podem ter acesso a **todas** as conexões ou só a **algumas** (acesso restrito). O papel continua o mesmo; o acesso só define o que o membro vê. Dono e admin sempre veem tudo. O membro restrito não enxerga as outras conexões, nem os avisos que não são de uma conexão dele (cobrança, situação da organização, membros), e só cria chaves da conexão a que tem acesso. As chaves que ele criou e que ficam fora do novo acesso são revogadas, a menos que quem altera o acesso escolha mantê-las. Veja [Autenticação e chaves de API](/api/authentication/). Quando a organização troca de **slug**, o slug antigo fica reservado por 90 dias: outra organização não consegue usá-lo, e a própria organização pode voltar a ele. ## Painel: organização na URL [Seção intitulada “Painel: organização na URL”](#painel-organização-na-url) O endereço de cada tela da organização começa pelo slug: `//api-keys`, `//members`. Abas abertas em organizações diferentes não se misturam. A conta da pessoa fica em `/account`. * **Trocar o slug** (só o dono, com senha e código 2FA): o endereço antigo continua redirecionando por 90 dias. * **Limite de organizações por usuário:** `ORG_LIMIT_PER_USER` (padrão 5). Acima disso, criar outra organização falha com `org_limit_reached`. * **Fuso da organização:** as datas dos e-mails (convites, avisos) usam o fuso configurado em Organização. * **E-mail dos membros:** só dono e admin veem; os demais papéis veem o nome. ## Conexão e canal [Seção intitulada “Conexão e canal”](#conexão-e-canal) Uma **conexão** é uma conta da Meta ligada à organização. Cada conexão tem um **canal**: | Canal | A conexão é | Como liga | | ----------- | ----------------------------------------------------------------------- | ------------------------------------------- | | `whatsapp` | Um número de WhatsApp Business, em coexistência com o app ou só API | [Conectar o WhatsApp](/connect/whatsapp/) | | `instagram` | Uma conta profissional do Instagram, sem precisar de Página do Facebook | [Conectar o Instagram](/connect/instagram/) | | `messenger` | Uma Página do Facebook | [Conectar o Messenger](/connect/messenger/) | A conexão tem um `id` (`conn_…`) usado nas chamadas de envio e presente em todo evento. Quem não tem conta no Messajo pode ligar a própria conta por um **convite de conexão**; depois disso, quem administra é a organização. ## Chave de API [Seção intitulada “Chave de API”](#chave-de-api) A chave autentica a API `/v1` pelo cabeçalho `Authorization: Bearer`. Ela é da organização, não de quem a criou, e tem: | Permissão | Libera | | ----------- | ----------------------------------- | | `send` | Enviar mensagens | | `read` | Ler conexões, conversas e logs | | `templates` | Criar e editar templates | | `admin` | Tudo, inclusive as permissões acima | Há dois tipos: a **chave de organização** (`mj_`), que vale para qualquer conexão e exige `connection_id` nas rotas de mensagem, e a **chave de conexão** (`mjc_`), criada na aba **Chaves de API** da conexão, que só enxerga a própria conexão e dispensa o `connection_id`. Usar uma conexão fora do alcance devolve [`connection_not_allowed`](/errors#connection_not_allowed). Toda chave tem validade e limite por minuto próprios. Veja [Tipos de chave](/api/authentication/#tipos-de-chave). A hierarquia é **organização → conexão → WABA**. Templates, flows e catálogos pertencem à WABA, que pode ser compartilhada por conexões irmãs: alterá-los por uma conexão afeta as outras da mesma WABA. ## Destinos de eventos [Seção intitulada “Destinos de eventos”](#destinos-de-eventos) Tudo o que acontece nas conexões — mensagem recebida, status de entrega, template aprovado, conexão caiu — vira um **evento** e sai por um destino: * **Webhook** (padrão): `POST` HTTPS assinado com o cabeçalho `Messajo-Signature`. Veja [Eventos](/webhooks/events/) e [Verificar a assinatura](/webhooks/verify-signature/). * **RabbitMQ, SQS, Kafka e WebSocket**: opcionais, com o mesmo envelope e a mesma assinatura. Veja [Tipos de destino](/webhooks/destinations/). Cada destino é **global** (recebe eventos de toda a organização) ou **de uma conexão** (só os dela). Ele filtra por tipo de evento e escolhe o formato: * `normalized`: o mesmo formato do Messajo nos 3 canais, bom para quem atende WhatsApp, Instagram e Messenger com um código só; * `meta`: o conteúdo cru que a Meta mandou, para quem já tem código que entende o formato dela. ## Duas camadas da API [Seção intitulada “Duas camadas da API”](#duas-camadas-da-api) A mesma chave usa as duas camadas, e você escolhe por chamada: | Camada | Exemplo | Para quê | | ------------------------------ | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Espelho da Meta**, por canal | `POST /v1/whatsapp/{phone_number_id}/messages` com o corpo idêntico ao da Meta | Cobre 100% dos recursos da Meta desde o primeiro dia. Quem migra de outro provedor troca só a URL e a chave. A documentação de cada campo é a oficial da Meta | | **Simples**, unificada | `POST /v1/messages` com `connection_id`, `to`, `type`… | O dia a dia (texto, mídia, template, botões), igual nos 3 canais | A [referência da API](/reference) documenta a camada simples e as rotas da plataforma. ## Janelas de conversa [Seção intitulada “Janelas de conversa”](#janelas-de-conversa) A Meta só deixa enviar mensagem livre dentro de uma **janela de atendimento** aberta pelo contato: 24 horas desde a última mensagem que ele mandou. Fora da janela: * no **WhatsApp**, só sai **template** aprovado pela Meta (marketing, utilidade ou autenticação), que reabre a conversa quando o contato responde; * no **Instagram** e no **Messenger**, o envio fora da janela é recusado, salvo as exceções previstas pela Meta. Envio fora da janela devolve o erro da Meta, com o código original em `meta_code`. Veja [Erros](/errors/). ## Idempotência [Seção intitulada “Idempotência”](#idempotência) Rede cai, e repetir um envio às cegas manda a mensagem duas vezes. Para evitar isso, mande o cabeçalho `Idempotency-Key` com um valor único por operação (um UUID, por exemplo): ```http POST /v1/messages Idempotency-Key: 6f1c0f3e-9b1a-4c55-9a3e-2d8c1b7e4a10 ``` A mesma chave repetida em até **24 horas** devolve a resposta original, sem enviar de novo. Gere a chave antes da primeira tentativa e reaproveite a mesma em todas as repetições. ## Quem cobra o quê [Seção intitulada “Quem cobra o quê”](#quem-cobra-o-quê) | Quem | Cobra | De quem | | ----------- | -------------------------------------------------- | ----------------------------------------------------------------- | | **Messajo** | Assinatura mensal por conexão | Da sua organização | | **Meta** | As conversas e mensagens, pela tabela oficial dela | Direto da sua conta na Meta, no método de pagamento cadastrado lá | O Messajo não revende mensagem nem cobra margem sobre o que a Meta cobra. # Começar em 5 minutos > Da conta nova à primeira chamada da API e à primeira mensagem, passo a passo. ## Antes de começar [Seção intitulada “Antes de começar”](#antes-de-começar) Você precisa de uma conta em `app.messajo.com`. Tenha também um terminal com `curl`. Nos exemplos, a API fica em `https://api.messajo.com/v1`. ## 1. Criar a conta e a organização [Seção intitulada “1. Criar a conta e a organização”](#1-criar-a-conta-e-a-organização) 1. Abra o painel e clique em **Criar conta**. Informe nome, e-mail e senha. 2. Confirme o e-mail pelo link que chega na sua caixa de entrada. 3. Dê um nome à sua organização. Você vira o **dono** dela. Tudo no Messajo — conexões, chaves, destinos de eventos — pertence à organização, não à pessoa. Veja [Conceitos](/start/concepts/). ## 2. Ligar o 2FA [Seção intitulada “2. Ligar o 2FA”](#2-ligar-o-2fa) A verificação em duas etapas é obrigatória para dono e admin. Sem ela o painel não libera as áreas da organização, inclusive a criação de chaves. 1. Em **Configurações → Segurança**, ative a **Verificação em duas etapas (2FA)**. 2. Leia o QR code com um app autenticador (Google Authenticator, 1Password, Authy…) e digite o código de 6 dígitos. 3. Guarde os **códigos de backup** num lugar seguro: eles são a saída se você perder o celular. ## 3. Criar uma chave de API [Seção intitulada “3. Criar uma chave de API”](#3-criar-uma-chave-de-api) 1. Abra **Chaves de API** e clique em **Criar chave**. 2. Dê um nome (por exemplo, `teste`) e marque só a permissão **Ler** (`read`), que basta para este guia. 3. Deixe **Todas as conexões**, escolha a validade e confirme. A chave completa, que começa com `mj_`, aparece **uma única vez**. Copie e guarde numa variável de ambiente: ```bash export MESSAJO_API_KEY="mj_..." ``` Detalhes em [Autenticação e chaves de API](/api/authentication/). ## 4. Testar com GET /v1/me [Seção intitulada “4. Testar com GET /v1/me”](#4-testar-com-get-v1me) `GET /v1/me` aceita qualquer chave válida e mostra a organização e a própria chave. É a forma mais rápida de confirmar que a autenticação está certa. * cURL ```bash curl https://api.messajo.com/v1/me \ -H "Authorization: Bearer $MESSAJO_API_KEY" ``` * TypeScript ```ts // npm install @messajo/sdk import { Messajo } from "@messajo/sdk"; const messajo = new Messajo({ apiKey: process.env.MESSAJO_API_KEY! }); const me = await messajo.me.get(); console.log(me.organization.name, me.api_key.permissions); ``` * Python ```python import os import requests response = requests.get( "https://api.messajo.com/v1/me", headers={"Authorization": f"Bearer {os.environ['MESSAJO_API_KEY']}"}, timeout=10, ) response.raise_for_status() me = response.json() print(me["organization"]["name"], me["api_key"]["permissions"]) ``` Resposta `200 OK`: ```json { "organization": { "id": "Kq3vT9xZ2mWb7LpR4nYc8sDf1gHj6aEu", "name": "Acme", "slug": "acme" }, "api_key": { "id": "Zt5rB8wQ1nXc4LmV7pYd2sGf9hJk3aRe", "name": "teste", "start": "mj_A1b2c3d", "permissions": ["read"], "connection_ids": null, "kind": "org", "connection_id": null, "connection": null, "expires_at": "2027-01-01T00:00:00.000Z" }, "request_id": "req_0193a1b2c3d47e8f9a0b1c2d3e4f5a6b" } ``` * `start` é o prefixo visível da chave, o mesmo que o painel mostra. * `kind` é `org` (chave `mj_`) ou `connection` (chave `mjc_`). Em chave de conexão, `connection_id` e `connection { id, channel, label }` identificam a conexão dela; na de organização são `null`. * `connection_ids: null` quer dizer que a chave de organização vale para todas as conexões; numa chave de conexão, traz só o id da conexão dela. * `expires_at` é `null` quando a chave não expira. Recebeu `401`? O corpo traz o `code` do erro, por exemplo [`missing_api_key`](/errors#missing_api_key) (faltou o cabeçalho) ou [`invalid_api_key`](/errors#invalid_api_key) (chave errada ou revogada). ## 5. Conectar um número de WhatsApp [Seção intitulada “5. Conectar um número de WhatsApp”](#5-conectar-um-número-de-whatsapp) 1. No painel, abra **Conexões → Conectar WhatsApp**. 2. Escolha o modo: **Manter meu WhatsApp Business** (coexistência: o número continua no app) ou **Número novo, só pela API**, e clique em **Continuar**. 3. Clique em **Abrir o popup da Meta**, siga o cadastro oficial da Meta na janela que abre e espere o painel mostrar **WhatsApp conectado.** A conexão aparece como **Ativa**, com um `id` no formato `conn_…`, usado nas chamadas de envio (a lista também sai em `GET /v1/connections`). O passo a passo completo está em [Conectar o WhatsApp](/connect/whatsapp/). ## 6. Enviar a primeira mensagem [Seção intitulada “6. Enviar a primeira mensagem”](#6-enviar-a-primeira-mensagem) Crie uma chave com a permissão `send` e chame `POST /v1/messages`. Mensagem livre só sai para um contato que falou com você nas últimas 24 horas; fora dessa janela, use um template aprovado (veja [Conceitos](/start/concepts/)). * cURL ```bash curl https://api.messajo.com/v1/messages \ -H "Authorization: Bearer $MESSAJO_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{ "connection_id": "conn_...", "to": "5511999999999", "type": "text", "text": { "body": "Olá! Mensagem enviada pelo Messajo." } }' ``` * TypeScript ```ts const sent = await messajo.messages.send({ connection_id: "conn_...", to: "5511999999999", type: "text", text: { body: "Olá! Mensagem enviada pelo Messajo." }, }); ``` * n8n **Configurações do nó HTTP Request do n8n** * Método: `POST` * URL: `https://api.messajo.com/v1/messages` * Autenticação: Generic Credential Type, depois Header Auth. Nome: `Authorization`; Valor: `Bearer mj_...` * Cabeçalhos: ative Send Headers e adicione `Idempotency-Key` (um valor único por item) * Corpo: ative Send Body; Body Content Type: JSON; Specify Body: Using JSON ```json { "connection_id": "conn_...", "to": "5511999999999", "type": "text", "text": { "body": "Olá! Mensagem enviada pelo Messajo." } } ``` Substitua mj\_... pela sua chave de API. O SDK gera o `Idempotency-Key` sozinho e repete com segurança quando a rede falha. Veja [SDK TypeScript](/sdk/typescript/). ### Com chave de conexão [Seção intitulada “Com chave de conexão”](#com-chave-de-conexão) Se o código só fala com um número, crie uma **chave de conexão** (`mjc_…`) no painel da própria conexão, em **Chaves de API**. Ela já sabe a qual conexão pertence: o `connection_id` do corpo some, e a chave não alcança as outras conexões. Chave de organização (`mj_`) continua exigindo o `connection_id`. * cURL ```bash curl https://api.messajo.com/v1/messages \ -H "Authorization: Bearer $MESSAJO_CONNECTION_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{ "to": "5511999999999", "type": "text", "text": { "body": "Olá!" } }' ``` * TypeScript ```ts const sent = await messajo.connection().messages.send({ to: "5511999999999", type: "text", text: { body: "Olá!" }, }); ``` Veja [Tipos de chave](/api/authentication/#tipos-de-chave). A resposta é `201`: ```json { "id": "msg_...", "external_id": "wamid.HBgNNTUxMTk5OTk5OTk5ORUCABEYEjQ", "status": "queued", "meta_status": "accepted", "conversation_id": "cnv_...", "contact_id": "ctc_...", "created_at": "2026-11-09T12:00:00.000Z" } ``` `external_id` é o id da Meta (`wamid`). A entrega e a leitura chegam depois, no evento `message.status`. Fora da janela, a resposta é `422` [`outside_service_window`](/errors#outside_service_window). Cada tipo tem a sua página no grupo **Enviar mensagens**, a começar por [Enviar texto](/send/text/); os campos de cada um estão também na [referência da API](/reference). ## 7. Receber o webhook [Seção intitulada “7. Receber o webhook”](#7-receber-o-webhook) 1. Em **Destinos de eventos**, cadastre a URL HTTPS que vai receber os eventos. O painel mostra o segredo (`whsec_…`) uma vez. 2. Responda `2xx` em até 10 segundos. Sem isso, o Messajo tenta de novo com espera crescente por até 24 horas. 3. Mande uma mensagem para o seu número: chega um evento `message.received`. ```json { "id": "evt_...", "type": "message.received", "format": "normalized", "org": "Kq3vT9xZ2mWb7LpR4nYc8sDf1gHj6aEu", "connection": "conn_...", "channel": "whatsapp", "timestamp": "2026-11-09T12:00:00.000Z", "sequence": 1, "data": {} } ``` O conteúdo de `data` depende do tipo do evento e do formato do destino. Antes de confiar no corpo, confira o cabeçalho `Messajo-Signature` com o segredo: veja [Verificar a assinatura](/webhooks/verify-signature/). O catálogo completo está em [Eventos](/webhooks/events/). ## Próximos passos [Seção intitulada “Próximos passos”](#próximos-passos) * [Conceitos](/start/concepts/): organizações, conexões, chaves e as duas camadas da API. * [Autenticação e chaves de API](/api/authentication/): permissões, validade e boas práticas. * [Erros](/errors/) e [Limites](/api/limits/): o que tratar no seu código. * [Verificar a assinatura](/webhooks/verify-signature/): obrigatório antes de ir para produção. * [SDK TypeScript](/sdk/typescript/), [Histórico](/api/history/) e [Campanhas](/guides/campaigns/). * [Enviar texto](/send/text/): a primeira de uma página por tipo de mensagem. * [Construir com IA](/start/build-with-ai/): `llms.txt`, Markdown por página e o OpenAPI. # Autenticação e chaves de API > Como criar, usar e proteger as chaves que autenticam a API /v1. ## Criar a chave no painel [Seção intitulada “Criar a chave no painel”](#criar-a-chave-no-painel) Em **Chaves de API → Criar chave**, preencha: | Campo | O que é | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Nome** | Até 32 caracteres, para reconhecer a chave depois (`produção`, `crm`) | | **Permissões** | `send` (enviar mensagens), `read` (ler conexões, conversas e logs), `templates` (criar e editar templates) e `admin` (tudo). Marque só o que a integração usa | | **Conexões** | **Todas as conexões** ou só as selecionadas. Uma chave presa a conexões não enxerga as outras | | **Validade** | 30, 90, 180 ou 365 dias, ou **Não expira** | | **Limite por minuto** | De 1 a 6.000 requisições por minuto (padrão: 600). Veja [Limites](/api/limits/) | Dono, admin e dev criam chaves. Só dono e admin dão a permissão `admin`. Depois de criada, a chave pode ser editada (nome, permissões, conexões, limite), desativada, reativada ou revogada. ## Tipos de chave [Seção intitulada “Tipos de chave”](#tipos-de-chave) | | Chave de organização (`mj_`) | Chave de conexão (`mjc_`) | | ---------------------------------- | -------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | Onde criar | **Chaves de API**, no nível da organização | Aba **Chaves de API** da conexão | | Alcance | Qualquer conexão da org; `connection_id` obrigatório nas rotas de mensagem | Só a conexão dela; `connection_id` é opcional (se enviado e diferente, 403 [`connection_not_allowed`](/errors#connection_not_allowed)) | | Destinos | Globais e de qualquer conexão | Só os da própria conexão, nunca globais | | Conexões | Listar, alterar e desconectar | Ler e alterar a própria; não desconecta | | Links de conexão | Sim | 403 [`organization_key_required`](/errors#organization_key_required) | | Gerir chaves de conexão pela `/v1` | Sim, com a permissão `admin` | Não | | Eventos, entregas, logs e custos | A org inteira | Só os da conexão (mais eventos da WABA) | | `GET /v1/me` | `api_key.kind = "org"`, `connection_id` e `connection` nulos | `api_key.kind = "connection"`, com `connection_id` e `connection { id, channel, label }` | As permissões (`send`, `read`, `templates`, `commerce`, `admin`) valem para os dois tipos. Use uma chave de conexão por integração: ela só enxerga o número dela e dispensa o `connection_id`. Chaves de organização antigas presas a várias conexões continuam funcionando, mas o painel não oferece mais essa opção. Templates, flows e catálogos pertencem à WABA: a chave de conexão que os altera afeta também as conexões irmãs da mesma WABA. ## A chave aparece uma vez [Seção intitulada “A chave aparece uma vez”](#a-chave-aparece-uma-vez) O valor completo, que começa com `mj_` (organização) ou `mjc_` (conexão), só aparece no diálogo de criação. O Messajo guarda apenas um hash: nem o painel, nem o suporte conseguem mostrá-la de novo. Perdeu? Crie outra e revogue a antiga. Para reconhecer a chave depois, o painel mostra o **prefixo visível**, os 10 primeiros caracteres (por exemplo, `mj_A1b2c3d`). O mesmo prefixo volta no campo `api_key.start` de `GET /v1/me`. ## Authorization: Bearer [Seção intitulada “Authorization: Bearer”](#authorization-bearer) Mande a chave no cabeçalho `Authorization` com o esquema `Bearer`, em toda requisição: ```bash curl https://api.messajo.com/v1/me \ -H "Authorization: Bearer $MESSAJO_API_KEY" ``` Cookie de sessão do painel **nunca** autentica a API `/v1`: uma requisição só com cookie recebe [`missing_api_key`](/errors#missing_api_key). Também não há chave em query string. ## Erros de autenticação [Seção intitulada “Erros de autenticação”](#erros-de-autenticação) Todo erro usa o corpo único da API, com um `code` estável: ```json { "error": { "code": "missing_api_key", "message": "Missing API key: send Authorization: Bearer ", "meta_code": null, "retryable": false, "request_id": "req_0193a1b2c3d47e8f9a0b1c2d3e4f5a6b", "docs_url": "https://docs.messajo.com/errors#missing_api_key" } } ``` | Status | `code` | Quando | | ------ | ---------------------------------------------------------------- | ---------------------------------------------------------- | | 401 | [`missing_api_key`](/errors#missing_api_key) | Faltou o cabeçalho `Authorization: Bearer` | | 401 | [`invalid_api_key`](/errors#invalid_api_key) | A chave não existe ou foi revogada | | 401 | [`api_key_expired`](/errors#api_key_expired) | A validade da chave acabou | | 401 | [`api_key_disabled`](/errors#api_key_disabled) | A chave foi desativada no painel | | 403 | [`insufficient_permissions`](/errors#insufficient_permissions) | A chave não tem a permissão que a rota exige | | 403 | [`connection_not_allowed`](/errors#connection_not_allowed) | A chave está presa a outras conexões | | 403 | [`organization_key_required`](/errors#organization_key_required) | A rota é só de chave de organização e a chave é de conexão | Nenhum desses erros se resolve repetindo a chamada (`retryable: false`): corrija a chave ou as permissões dela. ## Testar no /reference [Seção intitulada “Testar no /reference”](#testar-no-reference) A referência interativa fica em `https://api.messajo.com/reference`. Ali você cola a chave em **Authentication** e usa **Test request** para chamar as rotas de verdade, como `GET /v1/me`. A chamada sai do seu navegador para o próprio servidor, na mesma origem, sem passar por proxy de terceiros. A [referência destas docs](/reference) é só leitura e não envia requisições. ## Girar uma chave [Seção intitulada “Girar uma chave”](#girar-uma-chave) No painel, **Girar** cria uma chave nova com o mesmo nome, tipo, permissões, conexão e limite, e mostra o novo valor uma única vez. A chave antiga continua valendo por uma **carência**: **24 horas** (padrão) ou **agora**, que a encerra na hora. A carência nunca passa da validade original. Chave desativada ou vencida não pode ser girada. Pela `/v1`, uma chave de organização com `admin` cria, gira e revoga só **chaves de conexão** (`grace`: `24h` ou `now`). Chaves de organização são giradas no painel; a `/v1` devolve 404 `not_found` para elas: ```bash # criar chave de uma conexão curl -X POST https://api.messajo.com/v1/connections/$CONNECTION_ID/api-keys \ -H "Authorization: Bearer $MESSAJO_API_KEY" \ -H "Content-Type: application/json" \ -d '{"name": "crm", "permissions": ["send", "read"]}' # girar curl -X POST https://api.messajo.com/v1/api-keys/$KEY_ID/rotate \ -H "Authorization: Bearer $MESSAJO_API_KEY" \ -H "Content-Type: application/json" \ -d '{"grace": "24h"}' # revogar curl -X DELETE https://api.messajo.com/v1/api-keys/$KEY_ID \ -H "Authorization: Bearer $MESSAJO_API_KEY" ``` A resposta da rotação traz o segredo novo e `previous_key_expires_at`, o fim da carência da antiga. Os campos completos estão na [referência](/reference). ## Boas práticas [Seção intitulada “Boas práticas”](#boas-práticas) * **Variável de ambiente ou cofre de segredos**, nunca no código nem no repositório. * **Nunca no navegador nem no app móvel.** Qualquer pessoa extrai a chave de um front-end. Chame o Messajo do seu back-end. * **Uma chave por integração**, com o mínimo de permissões e, se der, presa às conexões que usa. Vazou uma, você revoga só ela. * **Validade definida** para chaves de teste e de terceiros. * **Girar sem parar:** crie a chave nova, troque na integração, confira o **último uso** da antiga no painel e só então revogue. O **último uso** é atualizado no máximo a cada \~5 s por réplica e o contador de requisições não é exato por chamada (a verificação da chave é cacheada por 5 s). * **Vazou?** Revogue na hora. A próxima chamada com ela já recebe [`invalid_api_key`](/errors#invalid_api_key). ## X-Request-Id para suporte [Seção intitulada “X-Request-Id para suporte”](#x-request-id-para-suporte) Toda resposta, de sucesso ou de erro, traz o cabeçalho `X-Request-Id` (`req_…`). O mesmo valor aparece em `request_id` no corpo dos erros e de `GET /v1/me`. Grave esse valor no log da sua integração. Ao pedir ajuda, mande o `X-Request-Id`: com ele o suporte acha a chamada exata, sem que você precise mandar a chave. # Histórico > Conversas, contatos e mensagens gravados pelo Messajo: filtros, paginação por cursor e como a retenção limita o intervalo. O Messajo guarda o que passa pelas conexões e deixa consultar pela API com a permissão `read`. Tudo respeita as conexões da chave: chave presa a algumas conexões só vê o que é delas. ## Rotas [Seção intitulada “Rotas”](#rotas) | Rota | Filtros | Ordem | | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | | `GET /v1/conversations` | `connection_id`, `contact_id`, `window=open\|closed`, `since`, `until` (sobre `last_message_at`) | `last_message_at` mais recente primeiro | | `GET /v1/conversations/{id}/messages` | `direction`, `type`, `since`, `until`, `order=desc\|asc` | `created_at` | | `GET /v1/messages` | `connection_id`, `contact_id`, `conversation_id`, `direction`, `status`, `type`, `source`, `campaign_id`, `since`, `until`, `order` | `created_at` | | `GET /v1/contacts` | `connection_id`, `channel`, `identity`, `q`, `since` | `last_seen_at` mais recente primeiro | Cada uma tem a versão por id (`GET /v1/conversations/{id}`, `GET /v1/messages/{id}`, `GET /v1/contacts/{id}`). Datas em ISO 8601. * `identity` busca exata por telefone (só dígitos), BSUID, @usuário do Instagram, IGSID ou PSID. * `q` busca pelo começo do nome do contato (até 64 caracteres). * `source` diz de onde veio a mensagem: `customer` (o contato), `api`, `campaign`, `business_app` (o app no celular, na coexistência) ou `history` (histórico importado); `campaign_id` traz só as mensagens de uma campanha. * A mídia aparece como parte da mensagem, com `id`. O arquivo sai em `GET /v1/media/{id}/content`. ## Paginação por cursor [Seção intitulada “Paginação por cursor”](#paginação-por-cursor) Toda lista devolve `{ data, next_cursor }`. Passe `limit` (até 100) e, para a próxima página, o `next_cursor` recebido em `cursor`. Acabou quando `next_cursor` vier `null`. ```bash curl "https://api.messajo.com/v1/messages?conversation_id=cnv_...&limit=100" \ -H "Authorization: Bearer $MESSAJO_API_KEY" ``` ```json { "data": [ { "id": "msg_...", "conversation_id": "cnv_...", "contact_id": "ctc_...", "direction": "inbound", "type": "text", "text": { "body": "Oi! Ainda tem o cupom?" }, "source": "customer", "status": "received", "campaign": null, "created_at": "2026-11-10T14:03:11.000Z" } ], "next_cursor": "eyJ2IjoxLCJrIjpbIjIwMjYtMTEtMTBUMTQ6MDM6MTEuMDAwWiIsIm1zZ18uLi4iXX0" } ``` * O cursor é opaco: não monte nem altere. Cursor quebrado → `400` [`invalid_cursor`](/errors#invalid_cursor). * O cursor guarda a posição, não um retrato da lista: o que chegar depois não duplica nem pula itens já lidos. * Use os mesmos filtros em todas as páginas. Com o [SDK](/sdk/typescript/), o `paginate` segue o cursor sozinho: ```ts for await (const message of messajo.paginate(messajo.messages.list, { conversation_id: "cnv_...", })) { console.log(message.id); } ``` ## Intervalo e retenção [Seção intitulada “Intervalo e retenção”](#intervalo-e-retenção) Mensagens são guardadas por mês. Toda consulta de mensagens tem um intervalo `since`/`until`: * sem `since`, vale o início da [retenção](/operate/data-privacy/#reten%C3%A7%C3%A3o) da organização (90 dias por padrão); sem `until`, agora; * um `since` mais antigo que a retenção é cortado no limite, sem erro: o que passou do prazo já foi apagado; * intervalos curtos respondem mais rápido. A retenção conta da **gravação** no Messajo. O histórico de 6 meses importado na coexistência é gravado no dia da importação e sai junto com o resto quando o prazo vence. # Limites > Os limites da API do Messajo, do envio por número, da Meta e da retenção de dados. ## API do Messajo [Seção intitulada “API do Messajo”](#api-do-messajo) Cada chave e cada organização têm um limite de requisições por minuto. Os dois valem ao mesmo tempo: a chamada passa só se couber nos dois. | Escopo | Limite padrão | | ----------------------------------------- | ------------------------------------------------------------------------------ | | Por chave de API | 600 requisições/min (ajustável por chave até 6.000/min) | | Por organização (todas as chaves somadas) | soma da vazão das conexões ativas × 60 × 1,25, no mínimo 1.200 requisições/min | Os dois limites valem para os dois tipos de chave ([organização `mj_` e conexão `mjc_`](/api/authentication/#tipos-de-chave)). O limite por chave é de cada chave: cada chave de conexão tem o seu próprio contador de 600 requisições/min. O limite da organização é um só e soma o tráfego de todas as chaves, inclusive as de conexão, então várias chaves de conexão juntas ainda dividem a mesma vazão da organização. Toda resposta da API `/v1` traz os cabeçalhos da janela atual: | Cabeçalho | O que é | | ----------------------- | -------------------------------------------- | | `X-RateLimit-Limit` | Limite da janela | | `X-RateLimit-Remaining` | Quantas chamadas ainda cabem na janela | | `X-RateLimit-Reset` | Quando a janela reinicia (Unix, em segundos) | Passou do limite, a resposta é `429` com o código [`rate_limited`](/errors#rate_limited), o cabeçalho `Retry-After` (segundos) e o campo `retry_after_ms` no corpo. Espere esse tempo antes de repetir. O limite da organização acompanha as conexões: dois números de 80 e 20 mensagens/s dão 7.500 requisições/min (100 × 60 × 1,25). Instagram e Messenger só entram na soma se tiverem vazão registrada. O valor é recalculado a cada 60 s, então conectar ou remover um número leva até 1 minuto para valer; `X-RateLimit-Limit` mostra o limite em vigor. Os demais valores podem mudar por plano. ## Envio por número [Seção intitulada “Envio por número”](#envio-por-número) Cada número tem uma vazão máxima, que depende do modo da conexão. O Messajo lê a vazão junto com a saúde do número, a cada 15 minutos, e mostra em **Velocidade** na página da conexão: | Modo | Vazão | | ----------------------------------------- | --------------------------------------- | | Coexistência (app do celular + API) | 20 mensagens/s | | Só API | 80 mensagens/s | | Só API, com vazão alta liberada pela Meta | 1.000 mensagens/s (a Meta sobe sozinha) | Cada número tem um balde de fichas com a capacidade da vazão (20, 80 ou 1.000) e que enche nesse ritmo por segundo. Cada chamada que vai para a Meta gasta uma ficha: o envio, pela camada simples ou pelo espelho, e o `typing`. Sem ficha, o Messajo responde `429` com o código [`connection_rate_limited`](/errors#connection_rate_limited), o cabeçalho `Retry-After` e o `retry_after_ms` no corpo, sem chamar a Meta. Nada é enfileirado: espere esse tempo e repita com a mesma `Idempotency-Key`. Se a própria Meta recusar por vazão (`130429`, `80007` ou `4` em `meta_code`), a resposta é `429` [`meta_rate_limited`](/errors#meta_rate_limited). Como a Meta não processou o pedido, o Messajo repete sozinho quando a espera cabe em 2,5 s; acima disso, devolve o erro com o `retry_after_ms` que a Meta informar. ## Limite de mensagens da Meta [Seção intitulada “Limite de mensagens da Meta”](#limite-de-mensagens-da-meta) A Meta limita quantos **usuários únicos** o portfólio (Business Manager) alcança com mensagens iniciadas pela empresa em 24 horas móveis. O limite é **do portfólio** e é compartilhado entre todos os números dele. Os degraus são 250 → 2.000 → 10.000 → 100.000 → ilimitado. Para subir: * verificar a empresa no portfólio, ou * manter boa qualidade e enviar para pelo menos metade do limite atual dentro de 7 dias. A Meta reavalia o portfólio a cada 6 horas e sobe o degrau sozinha quando as condições são cumpridas. O Messajo lê o degrau atual (campo `whatsapp_business_manager_messaging_limit` do número) junto com a saúde e mostra em **Faixa de envio** na página da conexão; quando ele muda, sai `connection.updated` com `reason: "limit_changed"`. Respostas dentro de uma conversa aberta pelo contato não contam neste limite. As [campanhas](/guides/campaigns/#velocidade-e-a-faixa-do-portf%C3%B3lio) param sozinhas em 95 % da faixa e voltam quando ela libera. Detalhes oficiais: [limites de mensagens da Meta](https://developers.facebook.com/docs/whatsapp/messaging-limits). ## Limite por par [Seção intitulada “Limite por par”](#limite-por-par) A Meta também limita quantas mensagens um número manda para **o mesmo contato** em pouco tempo (da ordem de uma mensagem a cada 6 segundos, com pequenas rajadas). Acima disso, a resposta é `429` [`pair_rate_limited`](/errors#pair_rate_limited), com `131056` em `meta_code` e `retry_after_ms` de 6.000: espere e espace os envios para esse contato. O Messajo nunca repete esse erro sozinho. ## Janelas [Seção intitulada “Janelas”](#janelas) | Canal | Regra | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | WhatsApp | Até 24 horas depois da última mensagem do contato, qualquer mensagem. Fora disso, só template aprovado. | | Instagram e Messenger | Até 24 horas depois da última mensagem do contato; 7 dias depois de o contato responder a um anúncio. Com `tag: "human_agent"` (só resposta de pessoa), até 7 dias. Fora disso, `422` antes de chamar a Meta. | No WhatsApp, o Messajo confere a janela antes de chamar a Meta: mensagem que não é template, fora da janela, volta `422` [`outside_service_window`](/errors#outside_service_window), com o fim da janela em `details[0].message`. Só a mensagem do contato abre a janela; o que você manda pelo app do celular na coexistência não abre. ## Instagram e Messenger [Seção intitulada “Instagram e Messenger”](#instagram-e-messenger) Cada conta do Instagram e cada Página do Messenger têm um balde de fichas, como os números do WhatsApp. Sem ficha, a resposta é `429` [`connection_rate_limited`](/errors#connection_rate_limited), sem chamar a Meta. | Canal | Texto, reação, curtida, botões e cards | Mídia (imagem, `images`, áudio, vídeo, PDF) | | --------- | -------------------------------------- | ------------------------------------------------ | | Instagram | 100 mensagens/s | 10 mensagens/s (gasta também uma ficha de texto) | | Messenger | 100 mensagens/s | 100 mensagens/s | | Limite | Instagram | Messenger | | -------------------- | -------------------------------------------------------------------------- | ---------------- | | Texto | 1.000 bytes | 2.000 caracteres | | Imagens por mensagem | até 10 (`images`) | 1 | | Anexo | imagem até 8 MB; áudio, vídeo e PDF até 25 MB | 25 MB | | Publicações | 100 por conta em 24 h ([publicações](/connect/instagram-content/#limites)) | — | Se a própria Meta recusar por vazão (`4`, `17`, `32`, `613` ou `80006`), a resposta é `429` [`meta_rate_limited`](/errors#meta_rate_limited) com o `retry_after_ms` que a Meta informar. Não há envio em massa nem campanhas no Instagram e no Messenger: a Meta não permite. Os números acima vêm da documentação da [Plataforma do Instagram](https://developers.facebook.com/docs/instagram-platform) e da [Plataforma do Messenger](https://developers.facebook.com/docs/messenger-platform) e ainda são conferidos em conta real. ## Ligações, grupos, Flows e pedidos [Seção intitulada “Ligações, grupos, Flows e pedidos”](#ligações-grupos-flows-e-pedidos) | Limite | Valor | | ------------------------------------- | ---------------------------------------------------------------------------------------------------- | | Pedido de permissão de chamada (Meta) | 1 a cada 24 h e 2 a cada 7 dias para o mesmo contato ([Ligações](/guides/calls/)) | | SDP de uma ligação | 64 KiB | | Participantes por grupo | 8 ([Grupos](/guides/groups/)) | | JSON de um Flow | 10 MiB; `PUT /v1/flows/{id}/json` até 30 por minuto por organização | | Trocas no endpoint de um Flow | 1.200 por minuto por Flow; o seu handler tem 7 s e até 256 KiB de resposta ([Flows](/guides/flows/)) | | Itens por pedido | 100 ([Vendas](/guides/commerce/)) | | Upload de mídia (`POST /v1/media`) | 120 por minuto por organização | ## Tamanho do corpo [Seção intitulada “Tamanho do corpo”](#tamanho-do-corpo) | Rota | Máximo | | ------------------------------------ | ------- | | `/v1` (JSON) | 1 MiB | | `POST /v1/media` | 100 MiB | | `POST /v1/campaigns/{id}/recipients` | 20 MiB | | `PUT /v1/flows/{id}/json` | 10 MiB | | Painel (`/rpc`) | 2 MiB | Acima disso, a resposta é `413` [`body_too_large`](/errors#body_too_large), sem processar nada. ## Retenção [Seção intitulada “Retenção”](#retenção) | Dado | Prazo | | --------------------------------------- | --------------------------------------------------------------- | | Evento bruto recebido da Meta | 7 dias | | Eventos e registro das entregas | 30 dias (ou o prazo da organização, se for menor) | | Logs do painel (requisições da API) | 30 dias (ou o prazo da organização, se for menor) | | Mensagens, mídias, conversas e contatos | 90 dias por padrão; o dono escolhe de 7 até o teto da instância | Depois do prazo, o dado é apagado no expurgo diário. Detalhes em [Dados e privacidade](/operate/data-privacy/). ## Idempotency-Key [Seção intitulada “Idempotency-Key”](#idempotency-key) Mande o cabeçalho `Idempotency-Key` (um valor único por operação, por exemplo um UUID) nas chamadas que criam algo, como o envio de mensagem. A chave vale por **24 horas**: repetir a mesma chave nesse prazo devolve a resposta original, sem executar de novo. É assim que se repete um envio com segurança depois de um timeout. # Changelog > As mudanças de cada versão do Messajo: novidades, correções, desempenho e segurança. Novidades, correções, desempenho e segurança de cada versão do Messajo. ## 0.4.22026-11-18 ### Novidades * web: Saúde do WhatsApp lista o que está bloqueado ou limitado ## 0.4.02026-11-18 ### Novidades * web: Progresso por etapas ao concluir a conexão do WhatsApp e linha da conexão clicável * web: Painel por conexão (Fase 1) * Acesso de membro por conexão (Fase 1b) * Destinos por conexão e webhook global da org (Fase 2) * Chaves de API por conexão e /v1 resolvida pela chave (Fase 3) * sdk,docs: Messajo.connection(), gestão de chaves e docs por conexão (Fase 4) * Contração — remove destination.connection_ids (Fase 5) * web: Prévia local de Flows e prévia de template como mensagem do WhatsApp ### Correções * whatsapp: Ligações com NOT_SET, username não elegível e ramo traduzido * web: Sem sublinhado no apelido da linha de conexão * web: Retry do toast refaz todas as queries com erro * web: Balão da prévia do template com cor de texto própria no tema escuro ## 0.3.72026-11-17 ### Correções * whatsapp: Atribuir o usuário de sistema à WABA com o token dele, não o do popup ## 0.3.62026-11-17 ### Correções * whatsapp: Conta nova com can_send_message BLOCKED conecta; só REJECTED é banida ## 0.3.52026-11-17 ### Correções * web: Pegar o FB no fbAsyncInit, não no load do sdk.js ## 0.3.42026-11-16 ### Correções * server: Liberar o SDK da Meta no connect-src do painel ## 0.3.32026-11-16 ### Correções * server: Copiar o native.wasm do @platformatic/wasm-utils para o dist ## 0.3.22026-11-16 ### Novidades * instagram: Login unificado (Login do Facebook para Empresas) no lugar do Login do Instagram * whatsapp: Token permanente do usuário do sistema do Messajo (META_SYSTEM_USER_TOKEN) ## 0.3.02026-11-16 ### Novidades * brand: Capa da página do Facebook * Fase 0A platform foundation * Fase 0B accounts and Fase 0C docs * Fase 1 messaging core and WhatsApp (0.1.0-alpha) * Fase 2 Instagram and Messenger (0.2.0-alpha) * Fase 3 beta * Fase 4 stable 1.0 * P1 entrada (rotas, org na URL, convites, conta, primeiro uso) * P2 notificações + robustez de conexão e entrega * P3 situação da org + painel do admin da instância * P4 custo Meta (estimado + oficial, teto de gasto, câmbio) * Tabela de preços da Meta sincronizada automaticamente * Avisar orgs legadas da WABA de outra org; limpar pendências * Job crypto.reseal re-sela segredos após rotação (1A-14) * billing: Ganchos do open-core para o módulo de cobrança (OC-1..OC-9) * Limite da org pela vazão (4-21), hot rows a cada 30 s (4-30) e datas por idioma (4-31) * destinos: Kafka com @platformatic/kafka no lugar do kafkajs (3-10) ### Correções * P0 bugs graves (cobrança, vazamento entre orgs, segurança) * sdk: Regenerar cliente (usage/costs, delivery held) * env: S3_ENDPOINT público para o varlock * release: Repassar o env atual ao git * core: Teto de 4 MiB na resposta da Graph (4-25) * server: Cross-Origin-Resource-Policy same-origin na /v1 (4-26) * api: Campo desconhecido no envio vira validation_failed (4-23) * whatsapp: Janela deslizante de 1 s no limite por número (4-19) * sdk: Regenerar cliente (lastSuccessAt/lastWebhookAt com atraso de 30 s) * e2e: Esperar o formulário de esqueci a senha montar e o toast sumir ### Desempenho * Dívida 4-16..4-20 (partição diária, bucket, ritmo da campanha, envio e entrada) * campanhas: Pacer na hora do envio (pico 68 → 64/s) e rodada 2 do k6 # Conectar o Instagram > Como ligar uma conta profissional do Instagram para Direct, comentários e menções. ## Requisitos [Seção intitulada “Requisitos”](#requisitos) * Uma conta **profissional** do Instagram (comercial ou de criador). Se nenhuma conta for liberada no login, a conexão é recusada com [`instagram_account_not_professional`](/errors#instagram_account_not_professional). * Não é preciso ter uma Página do Facebook. * Quem faz o login precisa administrar a conta no Instagram. * Na conta, ative **Configurações → Mensagens e respostas a stories → Controles de mensagens → Ferramentas conectadas → Permitir acesso às mensagens**. Sem isso o Direct não funciona (veja [Acesso ao Direct desativado](#acesso-ao-direct-desativado)). ## Permissões [Seção intitulada “Permissões”](#permissões) O Messajo pede só as permissões da [API do Instagram com Login do Facebook para Empresas](https://developers.facebook.com/documentation/instagram-platform/overview): | Permissão | Para quê | Obrigatória | | --------------------------- | ------------------------------------------------------------------------------------------- | ----------- | | `instagram_basic` | Ler o perfil e a mídia da conta | sim | | `instagram_manage_messages` | Receber e enviar mensagens no Direct | sim | | `instagram_manage_comments` | Listar, responder, ocultar e apagar comentários; resposta privada; menções | não | | `instagram_content_publish` | [Publicar](/connect/instagram-content/#publicar) fotos, vídeos, carrosséis, Reels e Stories | não | | `instagram_manage_insights` | Ler os [insights](/connect/instagram-content/#insights) da conta e de cada post | não | Sem uma das duas obrigatórias a conexão não é criada ([`signup_scope_mismatch`](/errors#signup_scope_mismatch)). As outras podem ser desmarcadas na tela do Instagram: a conta conecta, a página da conexão mostra **Permissões que faltam** e o recurso responde `403` [`instagram_scope_missing`](/errors#instagram_scope_missing), com a permissão em `details[0].message`, até você reconectar. ## Passo a passo [Seção intitulada “Passo a passo”](#passo-a-passo) 1. Abra **Conexões → Conectar Instagram**. O painel navega para a página da Meta (Login do Facebook para Empresas), sem popup e funcionando no celular. 2. Entre, escolha a(s) conta(s) do Instagram que o Messajo pode acessar e confirme. 3. A Meta volta para o Messajo, que troca o código por um token de acesso, lê a conta, inscreve o app nos webhooks e lê o perfil de mensagens. 4. Pronto: a conta aparece como **Ativa**, com os campos de webhook inscritos. * Uma conta liberada: conecta direto. * Mais de uma: o Messajo mostra um seletor e conecta **uma por login**. Repita o login para conectar as outras. * Nenhuma: erro [`instagram_account_not_professional`](/errors#instagram_account_not_professional). ![Página de uma conexão do Instagram no painel: conta ativa, permissões que faltam e campos do webhook](/_astro/instagram-connection-pt-BR.XSF15IDx_2JsGz.webp) Se você cancelar na tela da Meta, a tentativa fica no **Histórico** da conexão com o evento `CANCEL`. Se um passo falhar depois de a conexão ser criada, ela fica **Pendente** com o passo que faltou, e **Concluir conexão** refaz só o que falta. Uma organização pode conectar várias contas. Para conectar a conta de um cliente, mande um [convite por link](/connect/whatsapp/#convidar-o-cliente-por-link) com o canal Instagram: a pessoa autoriza pela página pública do convite, sem conta no Messajo. ## Acesso sem validade [Seção intitulada “Acesso sem validade”](#acesso-sem-validade) O acesso não expira, então não há renovação. Se a Meta revogar o acesso (senha trocada, app removido da conta, erro `190`), a conexão vai para `needs_reconnect` com `token_invalid` e o dono recebe o aviso com o link de reconexão. Reconectar mantém a mesma conexão. ### Acesso ao Direct desativado [Seção intitulada “Acesso ao Direct desativado”](#acesso-ao-direct-desativado) Se a configuração **Permitir acesso às mensagens** estiver desligada na conta, a verificação de saúde da conexão registra `reason: "dm_access_disabled"`: sai um evento `connection.updated` e o painel mostra um aviso. A conexão continua ativa e comentários, publicação e insights seguem funcionando; só o Direct não. Para resolver, no Instagram abra **Configurações → Mensagens e respostas a stories → Controles de mensagens → Ferramentas conectadas** e ative **Permitir acesso às mensagens**. O aviso some na próxima verificação. ### Contas conectadas antes desta versão [Seção intitulada “Contas conectadas antes desta versão”](#contas-conectadas-antes-desta-versão) Contas conectadas com o Login do Instagram precisam ser reconectadas uma vez. Os ids de mensagem da Meta são diferentes entre os dois logins. ## Tipos de mensagem [Seção intitulada “Tipos de mensagem”](#tipos-de-mensagem) Instagram e Messenger usam o mesmo motor e o mesmo `POST /v1/messages`. O `to` é o IGSID do contato (ou o `ctc_…` do Messajo). | `type` | WhatsApp | Instagram | Messenger | | ---------------------------------------------------------------- | -------- | --------- | --------- | | `text` (com `quick_replies` no IG/Messenger) | sim | sim | sim | | `image` · `video` · `audio` · `document` | sim | sim | sim | | `images` (2 a 10 imagens numa mensagem) | não | sim | não | | `reaction` | sim | sim | sim | | `like` (curtida) | não | sim | não | | `share` (compartilhar um post da conta) | não | sim | não | | `buttons` · `cards` | não | sim | sim | | `template` · `interactive` · `location` · `contacts` · `sticker` | sim | não | não | Tipo fora da matriz volta `422` [`type_not_supported_by_channel`](/errors#type_not_supported_by_channel). No Instagram o texto tem até 1.000 bytes; imagem até 8 MB (JPEG, PNG ou GIF); áudio, vídeo e PDF até 25 MB. `typing: true` mostra “digitando” antes do envio e `POST /v1/messages/{id}/read` marca a conversa como vista. O contato chega com nome, nome de usuário e foto (lidos na primeira mensagem e a cada 7 dias). ## Janelas e HUMAN_AGENT [Seção intitulada “Janelas e HUMAN_AGENT”](#janelas-e-human_agent) A Meta só deixa responder dentro de uma janela aberta pela última mensagem do contato: | Janela | Quando vale | | -------- | -------------------------------------------------------------------------------------------------- | | 24 horas | Qualquer resposta, contada da última mensagem do contato | | 7 dias | Depois de o contato responder a um anúncio de Direct (o Messajo reconhece o `referral` do anúncio) | | 7 dias | Com `tag: "human_agent"` | `tag: "human_agent"` serve **só para resposta escrita por uma pessoa** (política da Meta): nunca use em automação ou bot. O painel não oferece a tag em automações. Ela exige o recurso **Human Agent** aprovado no App Review; sem ele a Meta recusa e o Messajo devolve `403` [`human_agent_not_approved`](/errors#human_agent_not_approved). Fora da janela, o Messajo recusa antes de chamar a Meta: `422` [`outside_service_window`](/errors#outside_service_window), com o fim da janela em `details[0].message`. Com a tag e mais de 7 dias: `422` [`human_agent_window_closed`](/errors#human_agent_window_closed). Reação, curtida e `share` não abrem nem estendem a janela. ## Comentários, resposta privada e menções [Seção intitulada “Comentários, resposta privada e menções”](#comentários-resposta-privada-e-menções) Com `instagram_manage_comments`, o Messajo inscreve os campos `comments`, `live_comments` e `mentions` e entrega os eventos `comment.*` e `mention.received` ([catálogo](/webhooks/events/#cat%C3%A1logo)). | O quê | Rota `/v1` | Evento | | ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------ | | Comentários de um post (ao vivo na Meta, com o estado do Messajo) | `GET /connections/{id}/posts/{post_id}/comments` | — | | Responder em público | `POST /connections/{id}/comments/{comment_id}/replies` com `{ message }` (até 2.200 caracteres) | `comment.replied` | | Ocultar ou mostrar | `POST /connections/{id}/comments/{comment_id}/hide` com `{ hidden }` | `comment.hidden` · `comment.unhidden` | | Apagar | `DELETE /connections/{id}/comments/{comment_id}` | `comment.deleted` | | Resposta privada | `POST /connections/{id}/comments/{comment_id}/private-reply` | `comment.private_replied` + `message.sent` | | Menções | `GET /connections/{id}/mentions` | `mention.received` | A **resposta privada** manda uma mensagem no Direct para quem comentou, mesmo sem janela de 24 h aberta. Regras da Meta: só `text`, `buttons` ou `cards`; uma por comentário (`409` [`private_reply_already_sent`](/errors#private_reply_already_sent)); até 7 dias depois do comentário, e em comentário de live só durante a live (`422` [`private_reply_window_closed`](/errors#private_reply_window_closed)). A resposta abre a conversa com o contato e as próximas mensagens seguem as janelas normais. Só dá para apagar comentário em mídia da própria conta ([`comment_not_owned`](/errors#comment_not_owned)). A resposta que você mandou volta pela Meta como webhook, mas não gera evento de novo. ## Perfil de mensagens [Seção intitulada “Perfil de mensagens”](#perfil-de-mensagens) Em **Conexões → (conta) → Perfil de mensagens**, ou por `GET`/`PUT /v1/connections/{id}/messaging-profile`: * **Perguntas frequentes** (ice breakers): até 4 por idioma, até 80 caracteres cada, com o `payload` que chega no webhook quando a pessoa toca. * **Menu fixo**: até 20 itens (`postback` ou link). * **Boas-vindas dos anúncios**: no Instagram, as boas-vindas são os fluxos dos anúncios de Direct (`/v1/connections/{id}/welcome-flows`). Fluxo usado num anúncio não muda nem apaga ([`welcome_flow_in_use`](/errors#welcome_flow_in_use)). ![Tela do perfil de mensagens de uma conta do Instagram, com uma pergunta frequente e um fluxo de boas-vindas](/_astro/instagram-profile-pt-BR.Cq-ZYVhN_ZGkJnd.webp) O `PUT` é parcial: campo ausente não muda, `null` apaga. Depois de gravar, o Messajo relê o perfil na Meta. ## Camada espelho [Seção intitulada “Camada espelho”](#camada-espelho) Quem já fala a Graph do Instagram pode usar `/v1/instagram/{ig_user_id}/...` com o corpo e a resposta da Meta intactos: o Messajo põe o token da conta e confere a permissão da chave. Nós avulsos (mídia, comentário, contêiner, mensagem) ficam em `/v1/instagram/{ig_user_id}/nodes/{node_id}`. * `POST …/messages` grava a mensagem nos logs, gasta as fichas de envio e devolve `X-Messajo-Message-Id`. * `subscribed_apps`, `access_token` e `oauth/*` são bloqueados (`403` [`mirror_path_blocked`](/errors#mirror_path_blocked)). * `media_publish` pelo espelho **não** passa pelo agendamento do Messajo: para agendar, use [`/v1/publications`](/connect/instagram-content/#publicar). ## O que a Meta não permite [Seção intitulada “O que a Meta não permite”](#o-que-a-meta-não-permite) * envio em massa (não há campanhas no Instagram); * mensagem fora da janela; * grupos; * contas pessoais: só funciona com conta profissional. # Publicações e insights do Instagram > Publicar e agendar fotos, vídeos, carrosséis, Reels e Stories, e ler os insights da conta e dos posts. Esta página vale para contas do Instagram já [conectadas](/connect/instagram/). Publicar exige a permissão `instagram_content_publish`; insights exigem `instagram_manage_insights`. Sem elas, a rota responde `403` [`instagram_scope_missing`](/errors#instagram_scope_missing) até você reconectar a conta. ## Publicar [Seção intitulada “Publicar”](#publicar) A Meta não agenda publicações: o Messajo guarda o pedido e publica na hora marcada. No painel, use **Publicações → Nova publicação**; pela API, `POST /v1/publications`. ![Tela de nova publicação com conta, tipo, mídia, legenda com contadores e a escolha entre publicar agora e agendar](/_astro/publication-composer-pt-BR.BQbDxC3d_ZKQx5t.webp) ### Tipos [Seção intitulada “Tipos”](#tipos) | `type` | Mídia | Observação | | ---------- | ------------------------------- | -------------------------------------------------------------------------------------- | | `photo` | 1 imagem | Post no feed | | `video` | 1 vídeo | Vira Reels com `share_to_feed` sempre ligado (a Meta descontinuou vídeo comum no feed) | | `reel` | 1 vídeo | Aceita capa (`cover`), `thumb_offset_ms`, `share_to_feed` e `audio_name` | | `carousel` | 2 a 20 itens, imagem e/ou vídeo | Um contêiner por item e um para o carrossel | | `story` | 1 imagem ou vídeo | Sem legenda visível | Cada item vem por `media_id` (arquivo enviado em `POST /v1/media` com `purpose=publication`) ou por `url` pública. Também aceitam `alt_text`, `user_tags`, `collaborators` (até 3) e `location_id`. ### Limites [Seção intitulada “Limites”](#limites) | Regra | Valor | | ------------ | --------------------------------------------------------------------------------------------------- | | Legenda | até 2.200 caracteres, 30 hashtags e 20 menções (`@`) | | Imagem | **JPEG**, até 8 MiB. PNG e WebP enviados por `media_id` são convertidos para JPEG antes de publicar | | Vídeo | MP4 ou MOV, até 300 MiB (Stories até 100 MiB) | | Agendamento | de agora até 75 dias à frente | | Cota da Meta | 100 publicações por conta em 24 h móveis (`GET /v1/connections/{id}/publishing-limit`) | Fora dessas regras, a resposta é `422` [`validation_failed`](/errors#validation_failed) com o campo em `details`. ### URL pública [Seção intitulada “URL pública”](#url-pública) A Meta **baixa** a mídia pela URL: ela precisa ser acessível da internet. O `media_id` vira um link assinado do armazenamento S3 válido por 24 h. URL de rede privada é recusada com `422` [`media_url_not_public`](/errors#media_url_not_public). ### Agendamento e status [Seção intitulada “Agendamento e status”](#agendamento-e-status) `scheduled_at` vazio (ou dentro do próximo minuto) publica agora; no futuro, a publicação fica **Agendada** e uma tarefa roda na hora certa, com uma varredura a cada minuto como rede de segurança. Enquanto está `scheduled` ou `queued`, dá para editar (`PATCH /v1/publications/{id}`) ou cancelar (`POST /v1/publications/{id}/cancel`); depois disso, [`publication_not_editable`](/errors#publication_not_editable). | `status` | O que acontece | | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `scheduled` | Esperando a hora marcada | | `queued` | Na fila para publicar. Com a cota da Meta cheia, tenta de novo a cada hora; passadas 24 h do horário, falha com [`publishing_limit_reached`](/errors#publishing_limit_reached) | | `creating` | Criando os contêineres de mídia na Meta | | `processing` | A Meta está processando a mídia. Mais de 30 min falha com [`container_timeout`](/errors#container_timeout) | | `publishing` | Pedindo a publicação | | `published` | Publicado, com `external_media_id` e `permalink` | | `failed` | Falhou; o motivo vem em `error` (código do Messajo + código e status da Meta) | | `canceled` | Cancelada por você | Saem os eventos `publication.published` e `publication.failed` ([catálogo](/webhooks/events/#cat%C3%A1logo)). ### Nunca repete às cegas [Seção intitulada “Nunca repete às cegas”](#nunca-repete-às-cegas) Se a Meta não responde ao pedido de publicação (timeout, `5xx`), não dá para saber se o post saiu. O Messajo **não** publica de novo: consulta o status do contêiner na Meta. Se já foi publicado, marca `published` e procura o post; se o contêiner está pronto e não publicado, repete uma vez; se ainda processa, espera. Se publicou mas o post não foi encontrado, fica `published` sem `external_media_id`, e essa publicação não aceita `retry`. Uma publicação `failed` comum pode ser repetida com `POST /v1/publications/{id}/retry`, que cria contêineres novos. ## Insights [Seção intitulada “Insights”](#insights) No painel, **Insights** mostra a conta escolhida em 7, 28 ou 90 dias: alcance, visualizações, contas engajadas, interações, seguidores ganhos e perdidos, a série diária e o público do mês. Abaixo, os posts com as métricas de cada um. ![Tela de insights com os cartões de alcance e engajamento, o gráfico diário e a tabela de posts](/_astro/insights-pt-BR.Dbrlvvw-_1cuVoO.webp) | Rota `/v1` | O que devolve | | -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `GET /connections/{id}/insights` | Métricas da conta: `reach`, `views`, `accounts_engaged`, `total_interactions`, `likes`, `comments`, `shares`, `saves`, `replies`, `reposts`, `follows_and_unfollows`, `profile_links_taps` (por dia) e `follower_demographics`, `engaged_audience_demographics` | | `GET /connections/{id}/posts` · `/posts/{post_id}` | Posts da conta, com curtidas e comentários | | `GET /connections/{id}/posts/{post_id}/insights` | Métricas do post, conforme o tipo (feed, Reels ou story) | * **Atraso:** a Meta pode levar até 48 h para atualizar os números. O Messajo guarda cada consulta por 15 min. * `impressions` foi descontinuada pela Meta e é recusada com `validation_failed`. * Item de carrossel não tem insights próprios: `422` [`insights_not_available`](/errors#insights_not_available). Story com audiência abaixo de 5 pessoas também. * **Stories:** a métrica de um story some 24 h depois de ele sair do ar e o webhook de insights de story está a confirmar no login unificado. Por isso o Messajo tira um retrato dos stories ativos de hora em hora; o insight de um story vencido vem desse retrato, com `source: "snapshot"` e o horário em `captured_at` (no painel, “capturado às …”). # Conectar o Messenger > Como ligar uma Página do Facebook para conversar pelo Messenger. ## Requisitos [Seção intitulada “Requisitos”](#requisitos) * Uma **Página do Facebook**. * Ser admin da Página (ou ter controle total dela pelo portfólio de negócios), com uma função que permita mensagens (`MESSAGING` ou `MANAGE`). ## Permissões [Seção intitulada “Permissões”](#permissões) | Permissão | Para quê | | ----------------------- | ------------------------------------------------------------------ | | `pages_show_list` | Listar as Páginas que você administra, para escolher qual conectar | | `pages_manage_metadata` | Inscrever o app nos webhooks da Página | | `pages_messaging` | Receber e enviar mensagens pelo Messenger | | `pages_read_engagement` | Ler dados básicos da Página e das conversas | | `business_management` | Acessar Páginas que pertencem a um portfólio de negócios | Sem `pages_messaging` ou `pages_manage_metadata` a conexão não é criada ([`signup_scope_mismatch`](/errors#signup_scope_mismatch)). ## Passo a passo [Seção intitulada “Passo a passo”](#passo-a-passo) 1. Abra **Conexões → Conectar Messenger**. O painel navega para o [Login do Facebook para Empresas](https://developers.facebook.com/documentation/facebook-login/facebook-login-for-business) (sem popup, funciona no celular). 2. Entre no Facebook, escolha as Páginas que o Messajo pode acessar e aceite as permissões. 3. De volta ao painel, se houver mais de uma Página disponível, marque em **Escolha as Páginas** quais conectar e toque em **Conectar Páginas**. Cada Página escolhida vira uma conexão. Página já conectada em outra organização ou sem função de mensagens aparece desabilitada, com o motivo. 4. Pronto: cada Página aparece como **Ativa**. Sem nenhuma Página que dê para conectar, a tentativa termina com [`messenger_no_pages`](/errors#messenger_no_pages). Uma falha numa Página não desfaz as outras. Para conectar a Página de um cliente, mande um [convite por link](/connect/whatsapp/#convidar-o-cliente-por-link) com o canal Messenger: a pessoa autoriza e escolhe as Páginas pela página pública do convite. ## Token da Página [Seção intitulada “Token da Página”](#token-da-página) O token da Página **não expira**: não há renovação. Ao conectar, o Messajo inscreve o app na Página (`subscribed_apps`) para receber os webhooks; a cada 15 min confere a inscrição e, se o app sumiu da lista, inscreve de novo (`connection.updated` com `reason: "resubscribed"`). Se alguém tirar as permissões, a conexão passa para `needs_reconnect` (`token_invalid`) e o dono recebe o link de reconexão. ## Mensagens [Seção intitulada “Mensagens”](#mensagens) O Messenger usa o mesmo motor e a mesma [matriz de tipos](/connect/instagram/#tipos-de-mensagem) do Instagram, com estas diferenças: * `to` é o PSID do contato (ou o `ctc_…` do Messajo); * texto até 2.000 caracteres; anexos até 25 MB; * uma imagem por mensagem (sem `images`), sem `like` e sem `share`; * o recibo de leitura da Meta (`watermark`) vira `message.status` com `read` para todas as mensagens até aquele momento. ## Janelas [Seção intitulada “Janelas”](#janelas) | Janela | Quando vale | | -------- | -------------------------------------------------------- | | 24 horas | Qualquer resposta, contada da última mensagem do contato | | 7 dias | Depois de o contato responder a um anúncio | | 7 dias | Com `tag: "human_agent"` | `tag: "human_agent"` é só para resposta escrita por uma pessoa, nunca para automação, e exige o recurso **Human Agent** aprovado no App Review (sem ele: `403` [`human_agent_not_approved`](/errors#human_agent_not_approved)). As outras tags do Messenger foram descontinuadas pela Meta e não são aceitas. Fora da janela: `422` [`outside_service_window`](/errors#outside_service_window). Veja a [política do Messenger da Meta](https://developers.facebook.com/documentation/business-messaging/messenger-platform/policy). ## Perfil de mensagens [Seção intitulada “Perfil de mensagens”](#perfil-de-mensagens) Em **Conexões → (Página) → Perfil de mensagens**, ou por `GET`/`PUT /v1/connections/{id}/messaging-profile`: * **Perguntas frequentes** (ice breakers): até 4 por idioma; * **Menu fixo**: até 20 itens, com a opção de desativar a caixa de texto; * **Saudação**: até 160 caracteres, aceita `{{user_first_name}}`; * **Começar**: o botão “Começar” e o `payload` que ele manda. O Messajo grava o “Começar” antes do menu (a Meta exige) e não deixa apagá-lo enquanto houver menu. ![Tela do perfil de mensagens de uma Página, com menu fixo e saudação](/_astro/messenger-profile-pt-BR.CwR5RXrp_Z1acI2E.webp) ## Camada espelho [Seção intitulada “Camada espelho”](#camada-espelho) `/v1/messenger/{page_id}/...` repassa para a Graph com o token da Página, com corpo e resposta da Meta intactos; nós avulsos em `/v1/messenger/{page_id}/nodes/{node_id}`. `POST …/messages` grava a mensagem nos logs; `subscribed_apps` e as rotas de token são bloqueadas (`403` [`mirror_path_blocked`](/errors#mirror_path_blocked)), e `pass_thread_control`/`take_thread_control` exigem chave com permissão `admin`. # Conectar o WhatsApp > Como ligar um número de WhatsApp em coexistência ou só pela API, pelo cadastro oficial da Meta. ## Escolha o modo [Seção intitulada “Escolha o modo”](#escolha-o-modo) O Messajo conecta números pelo cadastro oficial da Meta (Embedded Signup), em dois modos. A escolha é feita na hora de conectar e muda o que o número consegue fazer: | | Coexistência (“Manter meu WhatsApp Business”) | Só API (“Número novo, só pela API”) | | -------------------------------- | -------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | | App WhatsApp Business no celular | Continua funcionando, com as mensagens enviadas pelo celular chegando à API (`message.echo`) | O número fica dedicado à integração | | Velocidade de envio | Fixa em 20 msg/s | 80 msg/s, ou 1.000 msg/s quando a Meta libera vazão alta | | Histórico de 6 meses e contatos | Sincronizados uma vez, dentro de 24 h | Não há | | Perfil, nome exibido e username | Editados no app do celular | Editados pelo painel ou pela API | | Registro do número | O número não é registrado de novo | Registrado com um PIN aleatório de 6 dígitos, guardado cifrado | | Parceiros ao mesmo tempo | Só um | Vários | Use a coexistência quando o atendimento continua no celular. Use o modo só API para volume ou para um número novo. ## Requisitos [Seção intitulada “Requisitos”](#requisitos) * Um portfólio de negócios na Meta e acesso de admin a ele. * Um número de telefone para conectar. * Na coexistência: o número já ativo no app WhatsApp Business **2.24.17 ou mais novo**. * No modo só API: um número que possa receber o código de verificação por SMS ou ligação e que não esteja em uso no app. * No painel, o papel de dono ou admin, com o 2FA ligado. ## Passo a passo no painel [Seção intitulada “Passo a passo no painel”](#passo-a-passo-no-painel) 1. Abra **Conexões** e clique em **Conectar WhatsApp**. 2. Escolha o modo: **Manter meu WhatsApp Business** (coexistência) ou **Número novo, só pela API**. Na coexistência, o painel mostra a lista de [limites](#limites-da-coexist%C3%AAncia) antes de seguir. Clique em **Continuar**. 3. Clique em **Abrir o popup da Meta**. O popup abre em outra janela: não feche a página do painel. Se o navegador bloquear, libere popups do endereço do painel e tente de novo. 4. No popup, faça login no Facebook, escolha (ou crie) o portfólio e a conta de mensagens, e escolha o número. 5. Na coexistência, confirme no app do celular lendo o QR code que a Meta mostra. No modo só API, confirme o número com o código por SMS ou ligação. 6. Ao fechar o popup, o painel mostra **Concluindo a conexão…** e, em seguida, **WhatsApp conectado.** A conexão aparece como **Ativa** e sai o evento `connection.created`. Na conclusão, o servidor troca o código do popup pelo token da conta (guardado cifrado), confere que a conta escolhida é mesmo a que o popup autorizou, inscreve o app nos webhooks da conta, registra o número (só API) e lê a saúde do número. Contas banidas ou sinalizadas pela Meta são recusadas antes de qualquer alteração na Meta, com o erro [`account_flagged`](/errors#account_flagged). ### Quando falta um passo [Seção intitulada “Quando falta um passo”](#quando-falta-um-passo) Se um passo depois da inscrição falhar, a conexão fica **Pendente** e o painel mostra o motivo, por exemplo “O registro do número na Meta falhou.”. Na página da conexão: * **Tentar registrar de novo** refaz só o registro do número (só API). A Meta aceita até 10 registros por número em 72 h. * **Concluir conexão** refaz o que faltou, sem abrir o popup de novo. Cada passo, do popup e do servidor, fica gravado na aba **Histórico** da conexão. Um cancelamento no popup aparece lá com a etapa em que a pessoa parou. ## Convidar o cliente por link [Seção intitulada “Convidar o cliente por link”](#convidar-o-cliente-por-link) Agências podem conectar o número de um cliente sem que ele crie conta no Messajo. Em **Links de conexão**, clique em **Criar link** e configure (o botão **Criar link de conexão**, em **Conexões**, leva para lá): | Campo | O que é | | ------------------------------------- | -------------------------------------------------------------------- | | **Rótulo** | Nome do link, só a sua equipe vê | | **Canal** | WhatsApp. Instagram e Messenger chegam na `0.2.0-alpha` | | **Modo** | Coexistência, só API ou “escolhido por quem abrir” | | **Validade** | 1 hora, 24 horas, 3, 7, 14 ou 30 dias. Padrão: 7 dias | | **Reaproveitável** | Desligado, o link vale para um número só; ligado, para vários | | **Senha (opcional)** | De 8 a 128 caracteres, pedida antes de abrir o cadastro | | **Idioma da página** | Idioma da página e do e-mail: português, inglês ou espanhol | | **Reconectar uma conexão (opcional)** | Faz do link uma reconexão: herda o modo da conexão e vale uma vez só | | **Enviar por e-mail para (opcional)** | Manda o link por e-mail já na criação | A URL do link (`https:///c/`) aparece **uma única vez**, na criação: o Messajo guarda só o hash do token. Copie e envie por onde quiser, ou mande pelo e-mail da plataforma. **Enviar por e-mail** gera um token novo, e a URL anterior deixa de valer. A senha nunca vai no e-mail: combine com o cliente por outro canal. A página do convite não pede login. Ela mostra o nome e o logo da sua organização, deixa trocar o idioma, explica os modos e os limites da coexistência e abre o mesmo popup da Meta. Ao terminar, mostra “Conexão feita. Pode fechar esta página.” A conexão fica com a sua organização: o cliente não ganha acesso a nada. * Cinco senhas erradas seguidas bloqueiam o link por 15 minutos ([`link_locked`](/errors#link_locked)). * Link de uso único já usado responde [`link_used`](/errors#link_used); vencido, [`link_expired`](/errors#link_expired). Para tirar um link do ar antes do prazo, use **Revogar**. * O logo vem de **Configurações → Organização**. Os links também podem ser criados pela API, em `POST /v1/connection-links` (permissão `admin`). Veja a [referência da API](/reference). ## Limites da coexistência [Seção intitulada “Limites da coexistência”](#limites-da-coexistência) A Meta impõe estas regras a todo número em coexistência: * velocidade fixa de 20 msg/s; * grupos não sincronizam; * listas de transmissão ficam só leitura; * mensagens temporárias e de visualização única são desligadas; * o app precisa ser aberto a cada \~14 dias; * exige WhatsApp Business 2.24.17 ou mais novo; * só um parceiro por vez. ## Sincronização da coexistência [Seção intitulada “Sincronização da coexistência”](#sincronização-da-coexistência) Logo depois de conectar em coexistência, o Messajo pede à Meta os contatos do app e, em seguida, até 6 meses de conversas. A aba **Sincronização** da conexão mostra cada um: | Status | O que quer dizer | | ------------------------- | ------------------------------------------------------------------- | | **Na fila** | Ainda não foi pedida, ou vai ser pedida de novo depois de uma falha | | **Pedida à Meta** | A Meta aceitou o pedido e está mandando os dados | | **Concluída** | Tudo chegou. O histórico mostra o progresso em % por fase | | **Recusada** | A pessoa recusou o compartilhamento do histórico no celular | | **Prazo de 24 h vencido** | A Meta só aceita o pedido até 24 h depois da conexão | Cada sincronização acontece uma vez só. Se o pedido falhar, o Messajo tenta de novo em 1 min, 5 min, 15 min, 1 h, 3 h e 6 h, sempre dentro das 24 h. Uma falha aqui nunca derruba a conexão. Os contatos chegam como evento `contacts.sync` e as conversas como `history.batch`, e as mensagens importadas aparecem nos logs com a origem `history`. ## Trocar de parceiro na coexistência [Seção intitulada “Trocar de parceiro na coexistência”](#trocar-de-parceiro-na-coexistência) Na coexistência o número aceita um parceiro por vez. Para trazer um número que já está com outro provedor: 1. Faça backup das conversas no app. 2. No app, vá em **Configurações > Conta > Plataforma Business > Desconectar**. 3. Conecte de novo pelo Messajo, como no passo a passo acima. O parceiro antigo recebe o aviso `PARTNER_REMOVED` da Meta. Se aparecer um erro de linha de crédito do parceiro anterior, siga o [guia da Meta para coexistência](https://developers.facebook.com/documentation/business-messaging/whatsapp/embedded-signup/onboarding-business-app-users). ## Depois de conectar [Seção intitulada “Depois de conectar”](#depois-de-conectar) A aba **Visão geral** da conexão mostra a **Saúde** do número: * **Qualidade**: Alta, Média, Baixa ou Sem nota, como a Meta mede; * **Faixa de envio**: quantos contatos novos por 24 h o portfólio pode alcançar (veja [Limites](/api/limits#limite-de-mensagens-da-meta)); * **Velocidade**: 20, 80 ou 1.000 msg/s, a vazão usada no envio; * **Envio**: Liberado, Limitado ou Bloqueado; * a restrição, quando a Meta restringe a conta, com o prazo. O Messajo lê a saúde a cada 15 minutos. **Atualizar saúde** lê na hora. A aba **Perfil** edita o perfil do negócio, pede a troca do nome exibido e define o username (só no modo só API). Cada mudança de status gera um evento `connection.*` nos seus [destinos de eventos](/webhooks/events/), com o motivo em `reason`, e um e-mail para donos e admins, no idioma de cada um. ## Quando a conexão cai [Seção intitulada “Quando a conexão cai”](#quando-a-conexão-cai) | Status | Quando | O que fazer | | ---------------------- | ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | | **Precisa reconectar** | A Meta invalidou o token (erro `190`), numa leitura de saúde ou num envio | Reconectar | | **Restrita** | A Meta restringiu a conta por um prazo, ou bloqueou o envio por política | Esperar o prazo e corrigir a causa no Gerenciador do WhatsApp. O envio continua liberado onde a Meta deixar | | **Desativada** | Violação de política ou banimento | Recorrer na Meta. Se ela reativar, a conexão volta a **Ativa** sozinha | | **Desconectada** | O app foi removido da conta, a conta ou o número foi apagado, ou alguém desconectou pelo painel | Conectar de novo | No erro `190`, o e-mail para donos e admins traz um **link de reconexão**. Na página da conexão, **Reconectar** abre o popup de novo, e **Gerar link de reconexão** cria um link para mandar a quem administra o número. A reconexão precisa ser do **mesmo número** ([`reconnect_mismatch`](/errors#reconnect_mismatch)) e mantém o `id` da conexão, o histórico e os destinos. Reconectar uma conexão **Desconectada** conta como conexão nova na cobrança; reconectar uma em **Precisa reconectar** não. Uma conta do WhatsApp Business (WABA) pertence a uma organização só: conectá-la em outra devolve [`waba_owned_by_other_org`](/errors#waba_owned_by_other_org). Uma conexão **Desconectada** nunca volta a **Ativa** sozinha: só reconectando pelo painel. **Desconectar** para de receber e enviar pelo número. No modo só API, dá para também cancelar o registro do número na Meta. Na coexistência, o painel mostra como remover o acesso no app do celular. # Erros > O formato único de erro da API e o significado de cada código. ## Formato do erro [Seção intitulada “Formato do erro”](#formato-do-erro) Todo erro da API usa o mesmo corpo JSON, com um `code` estável que você pode tratar no seu código. Este é o corpo real de uma chamada a `GET /v1/me` sem chave: ```http HTTP/1.1 401 Unauthorized Content-Type: application/json X-Request-Id: req_01a1c036cb127000b175ffba86a20018 ``` ```json { "error": { "code": "missing_api_key", "message": "Missing API key: send Authorization: Bearer ", "meta_code": null, "retryable": false, "request_id": "req_01a1c036cb127000b175ffba86a20018", "docs_url": "https://docs.messajo.com/errors#missing_api_key" } } ``` ## Campos [Seção intitulada “Campos”](#campos) | Campo | Tipo | O que é | | ---------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `code` | string | Código estável do Messajo. Trate o erro por ele, nunca pela mensagem. | | `message` | string | Texto curto **em inglês**, bom para log. Pode mudar entre versões. | | `meta_code` | número ou `null` | Código original da Meta quando o erro veio dela; `null` nos demais. | | `retryable` | booleano | `true` quando repetir a mesma chamada pode dar certo. | | `request_id` | string | Id da requisição, igual ao cabeçalho `X-Request-Id`. | | `docs_url` | string | Link para a âncora do código nesta página. | | `retry_after_ms` | número | Só nos erros de limite (`rate_limited`, `connection_rate_limited`, `pair_rate_limited`, `meta_rate_limited`, `link_locked`): quanto esperar, em milissegundos. | | `details` | lista | Itens `{ path, message }`. Em `validation_failed`, um por campo inválido. Num erro da Meta, `details[0].message` traz o detalhe que ela mandou (`error_data.details`). Em `outside_service_window`, o fim da janela (`path: "window_ends_at"`). | ## Quando repetir [Seção intitulada “Quando repetir”](#quando-repetir) * Repita só quando `retryable` for `true`. Os demais pedem uma correção antes. * Se a resposta trouxer `Retry-After` (segundos) ou `retry_after_ms`, espere pelo menos esse tempo. * Sem `Retry-After`, use backoff exponencial com jitter (por exemplo 1 s, 2 s, 4 s…) e um teto de tentativas. * Envio de mensagem **nunca** é repetido às cegas: mande o cabeçalho `Idempotency-Key` e repita com a mesma chave, para não entregar a mensagem duas vezes. Veja [Limites](/api/limits#idempotency-key). ## Códigos do Messajo [Seção intitulada “Códigos do Messajo”](#códigos-do-messajo) Cada código tem uma âncora própria (`/errors#`), a mesma do `docs_url`. ### `validation_failed` * Status HTTP 400 * Pode repetir Não * Mensagem no painel Alguns campos estão inválidos. Revise e tente de novo. * O que significa O corpo, a query ou os parâmetros da requisição não passaram na validação. * O que fazer Leia `details`: cada item traz o `path` do campo e o motivo. Corrija e envie de novo. ### `missing_api_key` * Status HTTP 401 * Pode repetir Não * Mensagem no painel Envie a chave de API no cabeçalho Authorization. * O que significa A requisição chegou sem o cabeçalho `Authorization: Bearer`. * O que fazer Envie a chave no cabeçalho `Authorization: Bearer `. Cookie do painel não autentica a API; veja [Autenticação](/api/authentication/). ### `invalid_api_key` * Status HTTP 401 * Pode repetir Não * Mensagem no painel Chave de API inválida. * O que significa A chave enviada não existe ou foi revogada. * O que fazer Confira se copiou a chave inteira, sem espaços. Se ela foi revogada, crie outra no painel. ### `api_key_expired` * Status HTTP 401 * Pode repetir Não * Mensagem no painel Esta chave de API expirou. * O que significa A chave passou da data de validade definida na criação. * O que fazer Crie uma chave nova no painel e troque na sua integração antes de apagar a antiga. ### `api_key_disabled` * Status HTTP 401 * Pode repetir Não * Mensagem no painel Esta chave de API está desativada. * O que significa A chave existe, mas foi desativada no painel. * O que fazer Peça a um admin da organização para reativar a chave ou use outra ativa. ### `unauthenticated` * Status HTTP 401 * Pode repetir Não * Mensagem no painel Sua sessão expirou. Entre de novo. * O que significa A rota do painel exige uma sessão e ela não existe ou expirou. * O que fazer Entre de novo no painel. Integrações devem usar a API `/v1` com chave. ### `billing_required` * Status HTTP 402 * Pode repetir Não * Mensagem no painel Seu plano não permite esta ação. Revise a cobrança. * O que significa O plano da organização não permite esta ação ou há cobrança pendente. * O que fazer Revise o plano e a cobrança no painel. Repetir a chamada não resolve. ### `org_restricted` * Status HTTP 403 * Pode repetir Não * Mensagem no painel Esta organização está restrita: não dá para criar itens novos até regularizar. * O que significa A organização está restrita: não pode criar itens novos (destinos, campanhas, flows, templates, links de conexão). * O que fazer O que já existe segue funcionando. Regularize a situação da organização no painel; repetir a chamada não resolve. ### `org_suspended` * Status HTTP 402 * Pode repetir Não * Mensagem no painel Esta organização está suspensa. O painel fica só para leitura até regularizar. * O que significa A organização está suspensa: a API só responde a GET /v1/me e os webhooks ficam retidos. * O que fazer Regularize a situação da organização no painel. Ao reativar, os webhooks retidos são entregues em ordem. ### `forbidden` * Status HTTP 403 * Pode repetir Não * Mensagem no painel Você não tem permissão para fazer isso. * O que significa Quem fez a chamada não tem acesso a este recurso. * O que fazer Confira se a chave ou o usuário pertence à organização dona do recurso. ### `insufficient_permissions` * Status HTTP 403 * Pode repetir Não * Mensagem no painel Sua chave ou seu papel não tem esta permissão. * O que significa A chave ou o papel não tem a permissão que a rota exige. * O que fazer Crie uma chave com a permissão necessária ou peça um papel com mais acesso. ### `connection_not_allowed` * Status HTTP 403 * Pode repetir Não * Mensagem no painel Esta chave não tem acesso a esta conexão. * O que significa A chave está restrita a outras conexões. * O que fazer Use uma chave liberada para esta conexão ou inclua a conexão nas permissões da chave. ### `organization_key_required` * Status HTTP 403 * Pode repetir Não * Mensagem no painel Esta operação exige uma chave da organização. * O que significa Esta operação só aceita uma chave da organização (`mj_`), e a chave usada é de conexão (`mjc_`). * O que fazer Use uma chave da organização e repita a chamada. Veja [Autenticação](/api/authentication#tipos-de-chave/). ### `two_factor_required` * Status HTTP 403 * Pode repetir Não * Mensagem no painel Seu papel exige verificação em duas etapas. Ative o 2FA para continuar. * O que significa Seu papel exige verificação em duas etapas e ela está desligada. Só aparece no painel. * O que fazer Ative o 2FA em Perfil → Segurança e repita a ação. ### `two_factor_mandatory` * Status HTTP 403 * Pode repetir Não * Mensagem no painel Donos e admins não podem desativar a verificação em duas etapas. * O que significa Donos e admins não podem desligar a verificação em duas etapas. Só aparece no painel. * O que fazer Mantenha o 2FA ligado ou peça para mudarem seu papel antes de desligar. ### `no_active_organization` * Status HTTP 409 * Pode repetir Não * Mensagem no painel Escolha uma organização para continuar. * O que significa A sessão do painel não tem uma organização escolhida. * O que fazer Escolha ou crie uma organização no painel e repita a ação. ### `last_owner` * Status HTTP 409 * Pode repetir Não * Mensagem no painel A organização precisa de pelo menos um dono. * O que significa A ação deixaria a organização sem nenhum dono. * O que fazer Promova outro membro a dono antes de sair ou de mudar o seu papel. ### `slug_taken` * Status HTTP 409 * Pode repetir Não * Mensagem no painel Este endereço já está em uso. Escolha outro. * O que significa Já existe uma organização com este endereço. * O que fazer Escolha outro endereço (slug) e envie de novo. ### `org_limit_reached` * Status HTTP 409 * Pode repetir Não * Mensagem no painel Você atingiu o limite de organizações por usuário. * O que significa Você atingiu o limite de organizações por usuário. * O que fazer Exclua uma organização que não usa mais ou peça ao admin da instância para subir o limite. ### `reauth_failed` * Status HTTP 403 * Pode repetir Não * Mensagem no painel Senha ou código de verificação incorreto. * O que significa A senha ou o código de verificação da reconfirmação está incorreto. * O que fazer Digite a senha de novo e, se tiver 2FA, o código atual de 6 dígitos. ### `account_delete_blocked` * Status HTTP 409 * Pode repetir Não * Mensagem no painel Você é o único dono de uma organização com outros membros. Transfira a posse ou exclua a organização antes. * O que significa Você é o único dono de uma organização com outros membros. * O que fazer Transfira a posse ou exclua a organização e repita. ### `not_found` * Status HTTP 404 * Pode repetir Não * Mensagem no painel Não encontramos o que você procurou. * O que significa O recurso não existe ou não pertence à organização da chave. * O que fazer Confira o id e a organização. Recurso de outra organização também responde 404. ### `conflict` * Status HTTP 409 * Pode repetir Não * Mensagem no painel Este registro mudou ou já existe. Atualize a página. * O que significa O registro mudou ou já existe com estes dados. * O que fazer Busque o estado atual do recurso e decida se envia de novo. ### `rate_limited` * Status HTTP 429 * Pode repetir Sim * Mensagem no painel Muitas tentativas. Aguarde um pouco e tente de novo. * O que significa Você passou do limite da chave ou da organização. * O que fazer Espere `retry_after_ms` (ou o `Retry-After`) e tente de novo; veja [Limites](/api/limits/). ### `internal_error` * Status HTTP 500 * Pode repetir Sim * Mensagem no painel Algo deu errado do nosso lado. Tente de novo. * O que significa Algo falhou do nosso lado ao processar a requisição. * O que fazer Repita com backoff. Se continuar, fale com o suporte mandando o `request_id`. ### `service_unavailable` * Status HTTP 503 * Pode repetir Sim * Mensagem no painel Serviço temporariamente indisponível. Tente de novo em instantes. * O que significa O serviço ou uma dependência dele está fora do ar por um instante. * O que fazer Repita com backoff exponencial respeitando o `Retry-After`, quando houver. ### `missing_signature` * Status HTTP 401 * Pode repetir Não * Mensagem no painel O webhook chegou sem assinatura. * O que significa O webhook de entrada chegou sem o cabeçalho `X-Hub-Signature-256`. * O que fazer Só a Meta (ou o seu simulador) deve chamar esta URL. Confira se a chamada vem do app certo, assinada com o app secret. ### `invalid_signature` * Status HTTP 401 * Pode repetir Não * Mensagem no painel A assinatura do webhook não confere. * O que significa A assinatura `sha256=` do webhook não confere com o app secret configurado. * O que fazer Confira se `META_APP_SECRET` é o do app que assina o webhook e se o corpo não foi alterado no caminho. ### `invalid_payload` * Status HTTP 400 * Pode repetir Não * Mensagem no painel O conteúdo do webhook é inválido. * O que significa O corpo do webhook não é um JSON no formato que a Meta envia. * O que fazer Envie o corpo exatamente como a Meta o gerou, com `Content-Type: application/json`. ### `payload_too_large` * Status HTTP 413 * Pode repetir Não * Mensagem no painel O conteúdo enviado é grande demais. * O que significa O corpo da requisição passou do tamanho máximo aceito. * O que fazer Reduza o conteúdo enviado. Arquivos grandes vão por mídia, não no corpo. ### `channel_not_configured` * Status HTTP 503 * Pode repetir Sim * Mensagem no painel Este canal ainda não está configurado no servidor. * O que significa O canal não tem app secret configurado neste servidor, então o webhook não pode ser conferido. * O que fazer A Meta reenvia o que recebeu `503`. ### `idempotency_key_reused` * Status HTTP 422 * Pode repetir Não * Mensagem no painel Esta Idempotency-Key já foi usada em outra requisição. * O que significa A `Idempotency-Key` já foi usada nas últimas 24 h com outro método, caminho ou corpo. * O que fazer Gere uma chave nova para cada operação diferente. Repita a mesma chave só para reenviar a mesma requisição. ### `idempotency_in_progress` * Status HTTP 409 * Pode repetir Sim * Mensagem no painel Uma requisição com esta Idempotency-Key ainda está em andamento. * O que significa A primeira requisição com esta `Idempotency-Key` ainda está sendo processada. * O que fazer Espere alguns segundos e repita com a mesma chave: você recebe a resposta guardada. ### `destination_url_not_allowed` * Status HTTP 400 * Pode repetir Não * Mensagem no painel Este endereço de destino não é permitido. * O que significa A URL do destino aponta para um endereço bloqueado (rede privada, `http` sem permissão, host inválido). * O que fazer Leia `details[].message` com o motivo e use uma URL `https` pública. ### `destination_limit_reached` * Status HTTP 409 * Pode repetir Não * Mensagem no painel A organização chegou ao limite de destinos. Remova um para criar outro. * O que significa A organização já tem o número máximo de destinos. * O que fazer Remova um destino que não usa mais antes de criar outro. ### `destination_paused` * Status HTTP 409 * Pode repetir Não * Mensagem no painel Este destino está pausado. Retome-o para continuar. * O que significa O destino está pausado (por você ou pela pausa automática após falhas seguidas). * O que fazer Corrija o endpoint, retome o destino no painel e reenvie as entregas que falharam. ### `outside_service_window` * Status HTTP 422 * Pode repetir Não * Mensagem no painel Fora da janela de 24 h de atendimento. Envie um template. * O que significa O contato não manda mensagem há mais de 24 h (72 h se veio de anúncio), e só template pode abrir a conversa. * O que fazer Envie um template aprovado. Quando o contato responder, a janela abre de novo e mensagens livres voltam a valer. ### `recipient_unavailable` * Status HTTP 422 * Pode repetir Não * Mensagem no painel Não foi possível entregar a este destinatário. * O que significa A Meta não conseguiu entregar: o número não tem WhatsApp, o app dele está desatualizado ou ele não aceitou os termos novos. * O que fazer Confira o número com DDI. Não repita em seguida: o resultado será o mesmo até o destinatário resolver do lado dele. ### `marketing_limit_reached` * Status HTTP 422 * Pode repetir Não * Mensagem no painel A Meta limitou mensagens de marketing para este contato. * O que significa A Meta segurou o template de marketing para manter o engajamento do contato saudável (limite por usuário). * O que fazer Não reenvie em seguida. Espere alguns dias ou mande algo que o contato peça; reenvio imediato não passa. ### `pair_rate_limited` * Status HTTP 429 * Pode repetir Sim * Mensagem no painel Mensagens demais para este contato em pouco tempo. Aguarde alguns segundos. * O que significa O limite por par (este número ↔ este contato) da Meta foi atingido. * O que fazer Espere `retry_after_ms` (6 s) antes de mandar de novo para o mesmo contato. Outros contatos não são afetados. ### `meta_rate_limited` * Status HTTP 429 * Pode repetir Sim * Mensagem no painel A Meta limitou a vazão. Aguarde e tente de novo. * O que significa A Meta recusou por limite de vazão do número, da conta ou do app, sem processar o pedido. * O que fazer Espere `retry_after_ms` (ou o cabeçalho `Retry-After`) e repita. Veja [Limites](/api/limits/). ### `template_error` * Status HTTP 422 * Pode repetir Não * Mensagem no painel A Meta recusou o template. Veja o motivo nos detalhes. * O que significa O template não existe nesse idioma, os parâmetros não batem, o texto passou do limite ou ele está pausado/desativado. * O que fazer Leia `details[].message` e `meta_code`. Confira nome, idioma e parâmetros em Templates; pausado ou desativado precisa ser editado. ### `policy_blocked` * Status HTTP 403 * Pode repetir Não * Mensagem no painel A Meta bloqueou este número por violação de política. * O que significa A Meta restringiu o número ou a conta por violar as políticas do WhatsApp Business. A conexão fica `restricted`. * O que fazer Veja o motivo e o prazo na saúde da conexão e no Gerenciador do WhatsApp; recorra por lá se discordar. ### `connection_needs_reconnect` * Status HTTP 409 * Pode repetir Não * Mensagem no painel O acesso a esta conexão expirou. Reconecte o número. * O que significa O token da Meta foi revogado ou expirou (senha trocada, app removido, permissão retirada). A conexão fica `needs_reconnect`. * O que fazer Reconecte pelo painel ou pelo link do e-mail que enviamos. Nada sai por essa conexão até reconectar. ### `meta_payment_required` * Status HTTP 402 * Pode repetir Não * Mensagem no painel Há um problema de pagamento na conta do WhatsApp Business. * O que significa A conta do WhatsApp Business está sem forma de pagamento válida, ou o pagamento falhou, ou o limite de crédito acabou. * O que fazer Ajuste a forma de pagamento no Gerenciador de Negócios da Meta. A cobrança das mensagens é da Meta, não do Messajo. ### `recipient_not_allowed` * Status HTTP 422 * Pode repetir Não * Mensagem no painel Este número de teste só envia para destinatários cadastrados. * O que significa O número de teste da Meta só manda para até 5 destinatários cadastrados no app. * O que fazer Cadastre o destinatário no painel do app da Meta ou conecte um número de verdade. ### `media_error` * Status HTTP 422 * Pode repetir Não * Mensagem no painel A Meta não conseguiu processar a mídia. * O que significa A Meta não baixou ou não aceitou a mídia: tipo não suportado, arquivo grande demais ou link inacessível. * O que fazer Leia `details[].message`. Confira tipo e tamanho aceitos e, se mandou link, que ele é público e responde rápido. ### `number_not_registered` * Status HTTP 409 * Pode repetir Não * Mensagem no painel Este número ainda não está registrado na API do WhatsApp. * O que significa O registro do número na Cloud API falhou ou foi desfeito, então a Meta não aceita envio por ele. * O que fazer Abra a conexão no painel e tente registrar de novo. Se persistir, reconecte o número. ### `username_not_eligible` * Status HTTP 422 * Pode repetir Não * Mensagem no painel Esta conta ainda não pode ter nome de usuário no WhatsApp. * O que significa A Meta ainda não liberou nome de usuário para esta conta do WhatsApp Business (Meta 147002). Vale para sugestões e para definir o nome. * O que fazer Nada a corrigir no Messajo. Tente de novo mais tarde; a liberação é da Meta e depende da conta. ### `meta_invalid_parameter` * Status HTTP 400 * Pode repetir Não * Mensagem no painel A Meta recusou um parâmetro da requisição. * O que significa Algum campo do corpo enviado à Meta é inválido ou não existe para este tipo de mensagem. * O que fazer Leia `details[].message` e `meta_code`, corrija o campo e envie de novo. ### `meta_unavailable` * Status HTTP 503 * Pode repetir Sim * Mensagem no painel A Meta está temporariamente indisponível. Tente de novo em instantes. * O que significa A Meta respondeu com falha temporária numa leitura ou em outra chamada que pode ser repetida sem efeito duplicado. * O que fazer Repita com backoff. Se durar, veja a página de status da Meta. ### `meta_unknown_outcome` * Status HTTP 502 * Pode repetir Não * Mensagem no painel A Meta não confirmou o envio. A mensagem pode ter saído; confira antes de reenviar. * O que significa Timeout ou falha temporária da Meta num envio: não dá para saber se a mensagem saiu. Ela fica `queued` até o status chegar por webhook. * O que fazer Não reenvie às cegas. Confirme pelo evento `message.status` ou com o contato; repetir com a mesma `Idempotency-Key` devolve o mesmo 502 sem reenviar. Para enviar de novo de propósito, use uma chave nova. ### `meta_error` * Status HTTP 502 * Pode repetir Não * Mensagem no painel A Meta devolveu um erro. * O que significa A Meta devolveu um erro que o Messajo ainda não traduz para um código próprio. * O que fazer Leia `meta_code` e `details[].message` e procure o código na documentação da Meta. Guarde o `request_id` se for abrir chamado. ### `connection_not_active` * Status HTTP 409 * Pode repetir Não * Mensagem no painel Esta conexão não está ativa. * O que significa Obsoleto: substituído por `connection_pending`, `connection_disconnected`, `connection_restricted`, `connection_disabled` e `connection_needs_reconnect`; some na próxima versão maior. Hoje só sai quando a org não tem nenhuma conta ativa para a ação. * O que fazer Veja o status da conexão no painel e resolva o motivo (reconectar, concluir o cadastro ou esperar a restrição acabar). ### `connection_restricted` * Status HTTP 409 * Pode repetir Não * Mensagem no painel A conexão está restrita pela Meta. * O que significa A Meta restringiu a conexão e o envio está bloqueado. * O que fazer Veja o motivo na conexão, no painel, e espere a restrição acabar ou resolva-a na Meta. ### `connection_disabled` * Status HTTP 409 * Pode repetir Não * Mensagem no painel A conexão foi desativada pela Meta. * O que significa A Meta desativou a conexão. * O que fazer Confira o status na conexão, no painel, e abra um recurso na Meta se a desativação for indevida. ### `connection_disconnected` * Status HTTP 409 * Pode repetir Não * Mensagem no painel A conexão está desconectada. Reconecte para usar. * O que significa A conexão está desconectada e não envia. * O que fazer Reconecte a conexão no painel. ### `connection_pending` * Status HTTP 409 * Pode repetir Não * Mensagem no painel A configuração da conexão ainda não terminou. * O que significa A configuração da conexão ainda não terminou. * O que fazer Conclua o cadastro da conexão no painel antes de enviar. ### `pin_invalid` * Status HTTP 422 * Pode repetir Não * Mensagem no painel PIN da verificação em duas etapas incorreto. * O que significa O PIN da verificação em duas etapas está incorreto. * O que fazer Informe o PIN correto do número. Se o esqueceu, redefina-o no app do WhatsApp. ### `pin_attempts_exhausted` * Status HTTP 429 * Pode repetir Sim * Mensagem no painel Tentativas demais para este número. Tente de novo mais tarde. * O que significa O número atingiu o limite de tentativas de registro. * O que fazer Espere o tempo informado em `retry_after_ms` antes de tentar de novo. ### `secret_rotation_pending` * Status HTTP 409 * Pode repetir Não * Mensagem no painel O segredo anterior ainda vale. Espere ele expirar para girar de novo. * O que significa O segredo anterior do destino ainda é válido. * O que fazer Espere o segredo anterior expirar para girar de novo. ### `notification_type_locked` * Status HTTP 409 * Pode repetir Não * Mensagem no painel Este aviso é obrigatório e não pode ser alterado. * O que significa O tipo de aviso é obrigatório e não aceita mudança. * O que fazer Escolha outro tipo de aviso; os de segurança e de conta são sempre enviados. ### `connection_rate_limited` * Status HTTP 429 * Pode repetir Sim * Mensagem no painel Esta conexão atingiu a velocidade máxima de envio. Aguarde um instante. * O que significa O número já está mandando na velocidade máxima que a Meta permite para ele (20/s na coexistência, 80/s ou mais só na API). * O que fazer Espere `retry_after_ms` e repita. Nada fica enfileirado: quem repete é a sua integração. Veja [Limites](/api/limits/). ### `account_flagged` * Status HTTP 403 * Pode repetir Não * Mensagem no painel Esta conta do WhatsApp Business foi banida ou sinalizada pela Meta. * O que significa A Meta baniu ou sinalizou esta conta do WhatsApp Business por violação, e ela não pode ser conectada. * O que fazer Resolva a situação com a Meta no Gerenciador do WhatsApp. Depois de liberada, conecte de novo. ### `signup_code_invalid` * Status HTTP 400 * Pode repetir Não * Mensagem no painel O código do cadastro expirou ou é inválido. Abra a janela da Meta de novo. * O que significa O `code` devolvido pela janela da Meta vale 30 s e só uma vez; ele expirou ou já foi usado. * O que fazer Recomece a conexão e conclua sem pausa depois que a janela da Meta fechar. ### `signup_scope_mismatch` * Status HTTP 403 * Pode repetir Não * Mensagem no painel Faltaram permissões na janela da Meta. Conecte de novo e aceite todas. * O que significa A janela da Meta foi concluída sem as permissões de gerenciar e mandar mensagens pela conta do WhatsApp Business. * O que fazer Conecte de novo e mantenha todas as permissões marcadas na janela da Meta. ### `signup_session_expired` * Status HTTP 410 * Pode repetir Não * Mensagem no painel A sessão de cadastro expirou. Comece de novo. * O que significa A sessão de conexão vale 30 minutos e passou do prazo, ou foi cancelada. * O que fazer Comece a conexão de novo no painel ou pelo link de conexão. ### `signup_incomplete` * Status HTTP 422 * Pode repetir Não * Mensagem no painel O cadastro terminou sem um número de telefone. Conclua escolhendo um número. * O que significa A janela da Meta criou ou escolheu a conta do WhatsApp Business, mas não terminou com exatamente um número. * O que fazer Conecte de novo e escolha (ou cadastre) o número na janela da Meta até o fim. ### `system_user_assignment_failed` * Status HTTP 502 * Pode repetir Não * Mensagem no painel Este servidor não conseguiu acesso à conta do WhatsApp. Peça ao administrador da instância para conferir o usuário do sistema da Meta. * O que significa A Meta recusou atribuir o usuário de sistema da instância (`META_SYSTEM_USER_TOKEN`) à conta do WhatsApp Business, ou o token dele não enxerga a conta. * O que fazer Quem administra a instância confere o token e o id do usuário de sistema (precisa ser admin do portfólio) e a conta conecta de novo. Nada foi gravado. ### `connection_already_exists` * Status HTTP 409 * Pode repetir Não * Mensagem no painel Este número já está conectado. * O que significa O número já tem uma conexão viva, nesta organização ou em outra. * O que fazer Use a conexão existente. Para mudar de organização, desconecte lá primeiro. ### `waba_owned_by_other_org` * Status HTTP 409 * Pode repetir Não * Mensagem no painel Esta conta do WhatsApp Business já está conectada a outra organização. * O que significa A conta do WhatsApp Business (WABA) já está conectada a outra organização. * O que fazer Desconecte a conta na outra organização primeiro, ou use a organização que já a tem. ### `invitation_invalid` * Status HTTP 409 * Pode repetir Não * Mensagem no painel Este convite não vale mais. Peça um novo. * O que significa Quem enviou o convite saiu da organização ou não pode mais conceder esse papel. * O que fazer Peça a um administrador da organização que envie um novo convite. ### `reconnect_mismatch` * Status HTTP 409 * Pode repetir Não * Mensagem no painel A reconexão foi feita com outro número. Escolha o mesmo número da conexão. * O que significa Na reconexão, a janela da Meta voltou com um número ou conta diferente do da conexão original. * O que fazer Reconecte escolhendo o mesmo número. Para um número novo, crie uma conexão nova. ### `coex_not_on_business_app` * Status HTTP 422 * Pode repetir Não * Mensagem no painel O modo coexistência exige um número que já usa o app WhatsApp Business. * O que significa No modo coexistência o número continua no app WhatsApp Business do celular; este número não está nele. * O que fazer Instale e ative o número no app WhatsApp Business, ou conecte no modo só API. ### `link_invalid` * Status HTTP 404 * Pode repetir Não * Mensagem no painel Este link de conexão não existe. * O que significa O endereço do link está incompleto, foi digitado errado ou o link foi revogado. * O que fazer Peça um link novo para quem o enviou. ### `link_expired` * Status HTTP 410 * Pode repetir Não * Mensagem no painel Este link de conexão expirou. * O que significa O link passou da data de validade (no máximo 30 dias). * O que fazer Peça um link novo para quem o enviou. ### `link_used` * Status HTTP 410 * Pode repetir Não * Mensagem no painel Este link de conexão já foi usado. * O que significa O link é de uso único e já conectou um número. * O que fazer Se precisa conectar outro número, peça um link novo. ### `link_locked` * Status HTTP 423 * Pode repetir Sim * Mensagem no painel Muitas tentativas de senha. Este link ficou bloqueado por alguns minutos. * O que significa Senhas erradas demais em seguida bloquearam o link por um tempo. * O que fazer Espere `retry_after_ms` e tente de novo com a senha certa. ### `link_password_required` * Status HTTP 401 * Pode repetir Não * Mensagem no painel Este link pede senha. * O que significa Quem criou o link definiu uma senha para abri-lo. * O que fazer Digite a senha que veio junto com o link. Sem ela, peça para quem enviou. ### `link_password_invalid` * Status HTTP 401 * Pode repetir Não * Mensagem no painel Senha incorreta. * O que significa A senha digitada não confere com a do link. * O que fazer Confira a senha e tente de novo. Várias tentativas erradas bloqueiam o link por alguns minutos. ### `mirror_path_blocked` * Status HTTP 403 * Pode repetir Não * Mensagem no painel Este caminho da API da Meta é bloqueado pelo Messajo. * O que significa A chamada pela camada espelho quebraria a conexão (ex.: desregistrar o número, trocar a inscrição do app) e é bloqueada. * O que fazer Faça essa ação pelo painel ou pela rota própria do Messajo, que mantém a conexão consistente. ### `media_too_large` * Status HTTP 413 * Pode repetir Não * Mensagem no painel O arquivo é grande demais para este tipo de mídia. * O que significa O arquivo passa do limite da Meta para o tipo (ex.: 16 MB para áudio e vídeo, 5 MB para imagem, 100 MB para documento). * O que fazer Comprima o arquivo ou mande como documento, que aceita mais. ### `media_type_not_supported` * Status HTTP 415 * Pode repetir Não * Mensagem no painel Este tipo de arquivo não é aceito. * O que significa O tipo do arquivo (MIME) não está entre os que o WhatsApp aceita para esse tipo de mensagem. * O que fazer Converta para um formato aceito (ex.: JPEG/PNG, MP4, OGG/Opus, PDF) ou mande como documento. ### `voice_conversion_failed` * Status HTTP 422 * Pode repetir Não * Mensagem no painel Não foi possível converter o áudio em mensagem de voz. * O que significa A conversão do áudio para OGG/Opus (mensagem de voz) falhou: arquivo corrompido ou formato que o conversor não lê. * O que fazer Mande o áudio já em OGG/Opus, ou como áudio comum sem `voice`. ### `template_not_found` * Status HTTP 404 * Pode repetir Não * Mensagem no painel Template não encontrado. * O que significa Não há template com esse id, ou com esse nome e idioma, nesta conta do WhatsApp Business. * O que fazer Confira nome e idioma em Templates, ou sincronize a lista com a Meta. ### `coex_not_supported` * Status HTTP 422 * Pode repetir Não * Mensagem no painel Indisponível em número de coexistência: altere no app WhatsApp Business. * O que significa Número em coexistência: a Meta não deixa a API mudar perfil, nome exibido nem username; isso se faz no app WhatsApp Business do celular. * O que fazer Altere pelo app WhatsApp Business no celular conectado, ou use um número só API. ### `instagram_account_not_professional` * Status HTTP 422 * Pode repetir Não * Mensagem no painel Nenhuma conta profissional do Instagram foi liberada no login. Selecione a conta na tela da Meta (ela precisa ser profissional) e tente de novo. * O que significa Nenhuma conta profissional foi liberada no login do Instagram; a Meta só libera mensagens e conteúdo pela API para contas profissionais. * O que fazer Na tela da Meta, selecione a conta e confirme que ela é profissional e gerenciada pela pessoa que fez o login; depois conecte de novo. ### `instagram_scope_missing` * Status HTTP 403 * Pode repetir Não * Mensagem no painel Falta uma permissão do Instagram para este recurso. Reconecte a conta e aceite todas as permissões. * O que significa A conexão foi feita sem o escopo que este recurso exige (comentários, publicação ou insights). `details[0].message` traz o escopo que falta. * O que fazer Reconecte a conta do Instagram e deixe marcadas todas as permissões na janela da Meta. ### `oauth_state_invalid` * Status HTTP 400 * Pode repetir Não * Mensagem no painel A conexão não pôde ser confirmada. Comece de novo pelo botão de conectar. * O que significa O retorno do login da Meta trouxe um `state` que não confere com a sessão de conexão aberta (adulterado, vencido ou de outra aba). * O que fazer Comece a conexão de novo pelo painel ou pelo link de conexão, na mesma aba, sem reaproveitar endereços antigos. ### `messenger_no_pages` * Status HTTP 422 * Pode repetir Não * Mensagem no painel Nenhuma Página do Facebook disponível para conectar. Confira se você é admin da Página e se a escolheu na janela da Meta. * O que significa Nenhuma Página escolhida no Login do Facebook pode ser conectada: faltam as tarefas de mensagens/gerenciar ou ela já está conectada em outra organização. * O que fazer Confira se você tem acesso total à Página (tarefas `MESSAGING` ou `MANAGE`), se marcou a Página na janela da Meta e se ela não está ligada em outra organização. ### `messenger_page_not_granted` * Status HTTP 403 * Pode repetir Não * Mensagem no painel Esta Página não foi liberada no login do Facebook. Conecte de novo e marque a Página. * O que significa A Página escolhida não está entre as que a pessoa liberou na janela do Login do Facebook. * O que fazer Escolha uma Página da lista devolvida ou faça o login de novo marcando a Página que falta. ### `type_not_supported_by_channel` * Status HTTP 422 * Pode repetir Não * Mensagem no painel Este tipo de conteúdo não existe neste canal. * O que significa O `type` (ou o campo de perfil) enviado não existe no canal da conexão, como `template` no Instagram ou `cards` no WhatsApp. * O que fazer Consulte os tipos aceitos por canal na referência da API e escolha um equivalente. ### `tag_not_supported_by_channel` * Status HTTP 422 * Pode repetir Não * Mensagem no painel Este canal não aceita etiqueta de mensagem. * O que significa O envio trouxe `tag` (como `human_agent`) numa conexão cujo canal não tem etiquetas, como o WhatsApp. * O que fazer Tire o `tag`. No WhatsApp, fora da janela de 24 h, envie um template. ### `human_agent_window_closed` * Status HTTP 422 * Pode repetir Não * Mensagem no painel Já passaram 7 dias da última mensagem do contato. Espere ele escrever de novo. * O que significa A etiqueta `human_agent` só vale até 7 dias depois da última mensagem do contato, e esse prazo passou. * O que fazer Não há como enviar até o contato escrever de novo. `details` traz quando a janela fechou. ### `human_agent_not_approved` * Status HTTP 403 * Pode repetir Não * Mensagem no painel O app ainda não tem aprovação da Meta para responder com atendente humano. * O que significa A Meta recusou o envio com `human_agent`: o app não tem o recurso Human Agent aprovado no App Review. * O que fazer Peça o recurso Human Agent no App Review do app da Meta. Até lá, responda dentro da janela de 24 h. ### `meta_permission_denied` * Status HTTP 403 * Pode repetir Não * Mensagem no painel A Meta negou a permissão para esta ação. Reconecte a conta e aceite todas as permissões. * O que significa A Meta recusou a chamada por falta de permissão: escopo retirado, função removida na Página ou recurso ainda não aprovado no app. * O que fazer Veja a saúde da conexão no painel. Reconecte aceitando todas as permissões; se continuar, confira o App Review do app da Meta. ### `private_reply_window_closed` * Status HTTP 422 * Pode repetir Não * Mensagem no painel O prazo para responder este comentário no Direct acabou. * O que significa A resposta privada só pode ser enviada até 7 dias depois do comentário (em comentário de live, só durante a live). * O que fazer Responda em público no comentário ou espere o contato mandar mensagem no Direct. ### `private_reply_already_sent` * Status HTTP 409 * Pode repetir Não * Mensagem no painel Este comentário já recebeu uma resposta no Direct. * O que significa A Meta permite uma única resposta privada por comentário, e ela já foi enviada. * O que fazer Continue a conversa no Direct que a resposta privada abriu. ### `comment_not_found` * Status HTTP 404 * Pode repetir Não * Mensagem no painel Comentário não encontrado. * O que significa Não há comentário com esse id nesta conexão, ou ele foi apagado. * O que fazer Confira o id na lista de comentários do post ou nos eventos `comment.*`. ### `comment_not_owned` * Status HTTP 403 * Pode repetir Não * Mensagem no painel Só dá para apagar comentários nos posts desta conta. * O que significa O comentário está numa mídia de outra conta (por exemplo, uma menção), e a Meta só deixa apagar comentários nos posts da própria conta. * O que fazer Oculte ou responda o comentário, ou peça ao dono do post para apagá-lo. ### `publication_not_editable` * Status HTTP 409 * Pode repetir Não * Mensagem no painel Esta publicação já está em andamento e não pode mais ser alterada. * O que significa Só publicações agendadas (`scheduled`) ou na fila (`queued`) podem ser editadas ou canceladas; esta já está sendo criada, publicada ou terminou. * O que fazer Acompanhe o `status` da publicação. Se falhou, use tentar de novo; se já saiu, edite ou apague o post no Instagram. ### `publication_media_invalid` * Status HTTP 422 * Pode repetir Não * Mensagem no painel A mídia da publicação foi recusada. Confira formato, tamanho e duração. * O que significa A Meta não conseguiu processar a mídia da publicação (contêiner em `ERROR`) ou ela está fora das regras: imagem JPEG até 8 MiB, vídeo MP4/MOV até 300 MiB (story até 100 MiB). * O que fazer Leia `details`, que traz o `status` da Meta, ajuste o arquivo e crie a publicação de novo. ### `media_url_not_public` * Status HTTP 422 * Pode repetir Não * Mensagem no painel A Meta não consegue baixar a mídia: o endereço não é público. * O que significa Para publicar, a Meta baixa a mídia pela URL, e o endereço enviado (ou o do armazenamento) não é acessível pela internet. * O que fazer Use uma URL pública em HTTPS. ### `media_url_expired` * Status HTTP 410 * Pode repetir Não * Mensagem no painel O link desta mídia expirou e não pode mais ser baixado. * O que significa A URL assinada do anexo venceu antes do download, e a Meta não emite outra. * O que fazer Peça ao contato para enviar o arquivo de novo. ### `publishing_limit_reached` * Status HTTP 429 * Pode repetir Sim * Mensagem no painel A conta chegou ao limite de publicações das últimas 24 horas. Tente mais tarde. * O que significa A conta do Instagram atingiu o limite de publicações pela API nas últimas 24 horas (`content_publishing_limit`). * O que fazer Espere o tempo de `retry_after_ms` ou agende para mais tarde. Publicações na fila são adiadas sozinhas por até 24 h. ### `container_timeout` * Status HTTP 504 * Pode repetir Não * Mensagem no painel A Meta demorou demais para processar a mídia. Tente publicar de novo. * O que significa O contêiner da publicação ficou em processamento na Meta por mais de 30 minutos. * O que fazer Tente de novo a publicação. Se repetir, reduza o tamanho ou a duração do vídeo. ### `insights_not_available` * Status HTTP 422 * Pode repetir Não * Mensagem no painel Não há insights disponíveis para este item. * O que significa A Meta não fornece insights para este item: filho de carrossel, story vencido sem snapshot, post antigo ou conta abaixo do mínimo de seguidores. * O que fazer Consulte o post pai do carrossel ou um período mais recente. Os dados da Meta podem atrasar até 48 h. ### `welcome_flow_in_use` * Status HTTP 409 * Pode repetir Não * Mensagem no painel Este fluxo de boas-vindas está em uso num anúncio e não pode ser alterado. * O que significa O fluxo de boas-vindas está ligado a um anúncio ativo, e a Meta não deixa alterar nem apagar. * O que fazer Tire o fluxo do anúncio no Gerenciador de Anúncios ou crie um fluxo novo. ### `signed_request_invalid` * Status HTTP 400 * Pode repetir Não * Mensagem no painel O pedido da Meta chegou com assinatura inválida. * O que significa O callback de desautorização ou de exclusão de dados chegou sem `signed_request`, com assinatura que não confere com o segredo do app ou com algoritmo diferente de `HMAC-SHA256`. * O que fazer Confira se a URL do callback no app da Meta aponta para este servidor e se `META_APP_SECRET` é o do mesmo app. ### `data_deletion_not_found` * Status HTTP 404 * Pode repetir Não * Mensagem no painel Não encontramos um pedido de exclusão com este código. * O que significa Não há pedido de exclusão de dados com esse código de confirmação, ou ele passou de 1 ano e foi apagado. * O que fazer Confira o código que a Meta mostrou ao pedir a exclusão e copie o endereço inteiro. ### `invalid_cursor` * Status HTTP 400 * Pode repetir Não * Mensagem no painel O cursor de paginação é inválido. Recomece da primeira página. * O que significa O `cursor` enviado não foi gerado por esta rota com estes mesmos filtros, ou foi alterado. * O que fazer Envie o `next_cursor` exatamente como veio na resposta anterior, com os mesmos filtros. Para recomeçar, omita o `cursor`. ### `retention_out_of_range` * Status HTTP 422 * Pode repetir Não * Mensagem no painel Escolha uma retenção entre 7 dias e o máximo desta instância. * O que significa O prazo de retenção pedido fica abaixo de 7 dias ou acima do máximo definido pela instância (`RETENTION_MAX_DAYS`). * O que fazer Escolha um valor dentro da faixa mostrada nas configurações de dados da organização. ### `campaign_channel_not_supported` * Status HTTP 422 * Pode repetir Não * Mensagem no painel Campanhas só estão disponíveis em conexões do WhatsApp. * O que significa A conexão escolhida é de um canal sem envio em massa. A Meta só permite campanhas com template no WhatsApp. * O que fazer Escolha uma conexão do WhatsApp em `connection_id`. ### `campaign_template_not_approved` * Status HTTP 422 * Pode repetir Não * Mensagem no painel O template precisa estar aprovado e ser de marketing ou utilidade. * O que significa O template não está `APPROVED` na Meta ou é de uma categoria que não entra em campanha (só `MARKETING` e `UTILITY`). * O que fazer Aguarde a aprovação ou escolha outro template. Sincronize os templates da conexão se o status mudou na Meta há pouco. ### `campaign_template_mapping_invalid` * Status HTTP 422 * Pode repetir Não * Mensagem no painel O mapeamento das variáveis não cobre todos os parâmetros do template. * O que significa Algum parâmetro do template (cabeçalho, corpo ou botão) ficou sem fonte no `variable_mapping`, ou a fonte não serve para aquele parâmetro. * O que fazer Leia `details`: cada item traz o `path` do parâmetro e o motivo. Dê a ele uma coluna, um valor fixo ou o nome do contato. ### `campaign_not_editable` * Status HTTP 409 * Pode repetir Não * Mensagem no painel Esta campanha não pode mais ser editada neste estado. * O que significa Template, mapeamento e destinatários só mudam em `draft`. Nome e velocidade também mudam em `scheduled`, `paused` e `auto_paused`. * O que fazer Desagende a campanha para voltar a `draft`, ou crie uma nova campanha. ### `campaign_invalid_state` * Status HTTP 409 * Pode repetir Não * Mensagem no painel Esta ação não é possível no estado atual da campanha. * O que significa A ação pedida (agendar, iniciar, pausar, retomar, cancelar) não vale a partir do `status` atual da campanha. * O que fazer Consulte a campanha, veja o `status` e escolha uma ação permitida a partir dele. ### `campaign_no_recipients` * Status HTTP 422 * Pode repetir Não * Mensagem no painel A campanha não tem nenhum destinatário válido. * O que significa A campanha não tem nenhum destinatário em `pending`: a lista está vazia ou todas as linhas ficaram `invalid`. * O que fazer Importe destinatários e corrija as linhas inválidas (o relatório da importação mostra linha, coluna e motivo). ### `campaign_too_many_recipients` * Status HTTP 422 * Pode repetir Não * Mensagem no painel A lista passou do limite de destinatários da campanha. * O que significa A importação passaria do máximo de 100 000 destinatários por campanha, ou a chamada inline trouxe mais de 10 000 linhas. * O que fazer Divida a lista em mais de uma campanha, ou envie um arquivo CSV/JSON em vez da lista inline. ### `campaign_import_in_progress` * Status HTTP 409 * Pode repetir Não * Mensagem no painel Ainda há uma importação de destinatários em andamento. * O que significa Um arquivo de destinatários ainda está sendo processado, e a campanha não pode ser agendada, iniciada nem receber outra importação até ele acabar. * O que fazer Acompanhe a importação até `completed` ou `failed` e tente de novo. ### `campaign_schedule_invalid` * Status HTTP 422 * Pode repetir Não * Mensagem no painel Agende entre 1 minuto e 90 dias a partir de agora. * O que significa O `scheduled_at` está no passado, a menos de 1 minuto de agora ou a mais de 90 dias. * O que fazer Envie um horário em ISO 8601 com fuso dentro dessa faixa. Para disparar já, inicie a campanha em vez de agendar. ### `spend_cap_reached` * Status HTTP 409 * Pode repetir Não * Mensagem no painel O teto de gasto do mês foi atingido. As campanhas ficam bloqueadas até o próximo mês ou até você aumentar o teto. * O que significa Atingiu o teto de gasto mensal da organização com "pausar campanhas" ligado, então campanhas não podem ser iniciadas ou retomadas. * O que fazer Aumente o teto em Configurações > Custos, desligue "pausar campanhas" ou espere o próximo mês. ### `meta_spam_rate_limited` * Status HTTP 429 * Pode repetir Não * Mensagem no painel A Meta limitou o número por excesso de denúncias ou bloqueios. * O que significa A Meta recusou o envio (código 131048) porque muitas mensagens deste número foram denunciadas ou bloqueadas. Campanhas pausam sozinhas com este erro. * O que fazer Não reenvie. Revise a lista (só quem pediu para receber), o conteúdo do template e a frequência; espere a qualidade do número voltar antes de retomar. ### `destination_type_disabled` * Status HTTP 422 * Pode repetir Não * Mensagem no painel Este tipo de destino está desligado neste servidor. * O que significa O servidor não liga este tipo de destino (RabbitMQ, SQS, Kafka ou WebSocket). Destinos já criados desse tipo ficam pausados. * O que fazer Use um webhook, ou peça a quem opera a instância para ligar `DESTINATIONS__ENABLED`. ### `no_client_connected` * Status HTTP 503 * Pode repetir Sim * Mensagem no painel Nenhum cliente WebSocket está conectado a este destino. * O que significa A entrega para o destino WebSocket não achou nenhum cliente conectado (ou nenhum confirmou o recebimento). Aparece só no último erro da entrega. * O que fazer Mantenha um cliente conectado em `/v1/ws` com ticket válido; a entrega é tentada de novo e, depois das tentativas, vai para a lista de falhas. ### `ws_ticket_invalid` * Status HTTP 401 * Pode repetir Não * Mensagem no painel O ticket do WebSocket é inválido, venceu ou já foi usado. * O que significa O ticket enviado ao abrir `/v1/ws` não existe, já venceu ou já foi usado: cada ticket vale para uma conexão só. * O que fazer Peça um ticket novo pela API logo antes de conectar e use-o uma única vez. ### `ws_session_limit` * Status HTTP 429 * Pode repetir Não * Mensagem no painel Há sessões WebSocket demais abertas para este destino. * O que significa O destino já tem o máximo de sessões WebSocket simultâneas. * O que fazer Feche as conexões que não usa mais (ou reaproveite uma) antes de abrir outra. ### `data_request_in_progress` * Status HTTP 409 * Pode repetir Não * Mensagem no painel Já existe um pedido deste tipo em andamento. * O que significa A organização já tem um pedido de exportação ou de exclusão deste tipo na fila ou rodando. * O que fazer Acompanhe o pedido nas configurações de dados da organização e espere ele terminar. ### `data_request_limit` * Status HTTP 429 * Pode repetir Sim * Mensagem no painel Limite de exportações das últimas 24 horas atingido. * O que significa A organização já pediu 3 exportações nas últimas 24 horas. * O que fazer Baixe uma das exportações já prontas ou tente de novo depois do tempo indicado em `retry_after_ms`. ### `data_export_expired` * Status HTTP 410 * Pode repetir Não * Mensagem no painel Esta exportação venceu e o arquivo foi apagado. * O que significa O arquivo da exportação fica disponível por 7 dias; depois disso ele é apagado. * O que fazer Peça uma nova exportação nas configurações de dados da organização. ### `calling_not_supported_in_coex` * Status HTTP 422 * Pode repetir Não * Mensagem no painel Ligações não estão disponíveis para números em coexistência com o app WhatsApp Business. * O que significa O número está em coexistência com o app WhatsApp Business, e a Meta não oferece a Calling API nesse modo. * O que fazer Use um número conectado só pela API (sem o app) para receber e fazer ligações. ### `calling_not_enabled` * Status HTTP 409 * Pode repetir Não * Mensagem no painel As ligações não estão ativadas neste número. * O que significa As ligações estão desligadas nas configurações do número. * O que fazer Ative as ligações em `PUT /v1/connections/{id}/calling-settings` (`status: ENABLED`) ou nas configurações de ligação da conexão no painel. ### `call_not_found` * Status HTTP 404 * Pode repetir Não * Mensagem no painel Ligação não encontrada. * O que significa A ligação não existe nesta organização. * O que fazer Confira o `id` (`cal_…`) e se a chave tem acesso à conexão da ligação. ### `call_invalid_state` * Status HTTP 409 * Pode repetir Não * Mensagem no painel Esta ação não é permitida no estado atual da ligação. * O que significa A ação não vale no estado atual da ligação (ex.: aceitar uma ligação já encerrada). * O que fazer Leia o status atual em `details` ou em `GET /v1/calls/{id}` e mande só as ações que esse estado permite. ### `call_sdp_invalid` * Status HTTP 400 * Pode repetir Não * Mensagem no painel SDP inválido. * O que significa O SDP veio vazio, passou de 64 KiB ou não começa com `v=0`. * O que fazer Mande o SDP gerado pela sua pilha WebRTC sem alterações. ### `call_sdp_mismatch` * Status HTTP 409 * Pode repetir Não * Mensagem no painel O SDP precisa ser o mesmo enviado no pre_accept. * O que significa Depois do `pre_accept`, a Meta exige que o `accept` use exatamente o mesmo SDP. * O que fazer Guarde o SDP do `pre_accept` e reenvie o mesmo texto no `accept`. ### `call_permission_required` * Status HTTP 403 * Pode repetir Não * Mensagem no painel O contato ainda não deu permissão para receber ligações. * O que significa O contato não deu permissão para a empresa ligar (Meta 138006). * O que fazer Peça a permissão com uma mensagem `interactive.call_permission_request` (ou template com esse botão) e espere o evento `call.permission_updated`. ### `call_rate_limited` * Status HTTP 429 * Pode repetir Não * Mensagem no painel Limite de ligações da Meta atingido. * O que significa A Meta limitou as ligações deste número ou para este contato. * O que fazer Espere antes de ligar de novo; não repita em laço. ### `call_error` * Status HTTP 422 * Pode repetir Não * Mensagem no painel A Meta recusou o pedido de ligação. * O que significa A Meta recusou o pedido da Calling API com um código da faixa 138xxx. * O que fazer Leia `meta_code` e `details[0].message` para o motivo; corrija o pedido antes de tentar de novo. ### `group_not_supported` * Status HTTP 422 * Pode repetir Não * Mensagem no painel Grupos não estão disponíveis para este número. * O que significa Este número não tem acesso à Groups API (ex.: número em coexistência). * O que fazer Use um número conectado só pela API e elegível a grupos. ### `group_not_found` * Status HTTP 404 * Pode repetir Não * Mensagem no painel Grupo não encontrado. * O que significa O grupo não existe nesta organização. * O que fazer Confira o `id` (`grp_…`) e se a chave tem acesso à conexão do grupo. ### `group_not_active` * Status HTTP 409 * Pode repetir Não * Mensagem no painel O grupo não está ativo. * O que significa O grupo ainda está sendo criado, foi suspenso ou apagado. * O que fazer Espere o evento `group.created` antes de mandar mensagens; grupo suspenso ou apagado não recebe envio. ### `group_participant_limit` * Status HTTP 422 * Pode repetir Não * Mensagem no painel Participantes demais para um grupo. * O que significa O grupo passaria do limite de participantes (8). * O que fazer Remova participantes antes de convidar outros. ### `group_message_type_not_supported` * Status HTTP 422 * Pode repetir Não * Mensagem no painel Este tipo de mensagem não pode ser enviado para um grupo. * O que significa A Meta só aceita texto, mídia e templates de texto ou mídia em grupos. * O que fazer Mande um desses tipos; botões, listas e Flows não vão para grupo. ### `flow_not_found` * Status HTTP 404 * Pode repetir Não * Mensagem no painel Flow não encontrado. * O que significa O Flow não existe nesta organização. * O que fazer Confira o `id` (`flw_…`) ou o id da Meta do Flow. ### `flow_not_editable` * Status HTTP 409 * Pode repetir Não * Mensagem no painel O Flow só pode ser editado enquanto está em rascunho. * O que significa O JSON só muda enquanto o Flow está em `DRAFT`. * O que fazer Clone o Flow publicado (`POST /v1/flows/{id}/clone`) e edite a cópia. ### `flow_invalid_json` * Status HTTP 422 * Pode repetir Não * Mensagem no painel O JSON do Flow é inválido. * O que significa O JSON do Flow não passou na validação (local ou da Meta, código 139001). * O que fazer Cada item de `details` traz `path = flow_json::` e o motivo; corrija e envie de novo. ### `flow_handler_required` * Status HTTP 422 * Pode repetir Não * Mensagem no painel Este Flow precisa de um servidor de troca de dados. * O que significa O Flow usa o endpoint do Messajo, mas falta o servidor do cliente (handler) ou a base pública HTTPS do endpoint. * O que fazer Configure `endpoint.url` (HTTPS público) no Flow; quem opera a instância precisa de `FLOWS_ENDPOINT_BASE_URL` com `https:`. ### `flow_key_not_uploaded` * Status HTTP 409 * Pode repetir Não * Mensagem no painel A chave de criptografia do Flow ainda não foi enviada a um número ativo. * O que significa A chave pública dos Flows ainda não foi enviada a nenhum número ativo da conta; a Meta não consegue chamar o endpoint. * O que fazer Espere a sincronização da chave ou gire a chave em `POST /v1/connections/{id}/flow-key/rotate` e tente publicar de novo. ### `flow_error` * Status HTTP 422 * Pode repetir Não * Mensagem no painel A Meta recusou o pedido do Flow. * O que significa A Meta recusou o pedido de Flows com um código da faixa 139xxx. * O que fazer Leia `meta_code` e `details[0].message` e corrija antes de tentar de novo. ### `catalog_not_found` * Status HTTP 404 * Pode repetir Não * Mensagem no painel Catálogo não encontrado. * O que significa O catálogo não existe nesta organização. * O que fazer Confira o `id` (`cat_…`) e sincronize os catálogos da conta. ### `catalog_not_linked` * Status HTTP 409 * Pode repetir Não * Mensagem no painel O catálogo não está ligado a esta conta do WhatsApp Business. * O que significa O catálogo citado não está ligado à conta do WhatsApp Business da conexão. * O que fazer Ligue o catálogo (`POST /v1/catalogs/{id}/link`) antes de usá-lo em mensagens. ### `product_not_found` * Status HTTP 404 * Pode repetir Não * Mensagem no painel Produto não encontrado. * O que significa O produto não existe neste catálogo. * O que fazer Confira o `id` (`prd_…`) ou o `retailer_id` e sincronize o catálogo. ### `commerce_permission_missing` * Status HTTP 403 * Pode repetir Não * Mensagem no painel Falta a permissão catalog_management para este catálogo. * O que significa O token da conexão não tem a permissão `catalog_management` para este catálogo. * O que fazer Reconecte o número concedendo acesso ao catálogo, ou use um catálogo da mesma empresa. ### `order_not_found` * Status HTTP 404 * Pode repetir Não * Mensagem no painel Pedido não encontrado. * O que significa O pedido não existe nesta organização. * O que fazer Confira o `id` (`ord_…`). ### `order_invalid_transition` * Status HTTP 409 * Pode repetir Não * Mensagem no painel Esta mudança de status não é permitida no estado atual do pedido. * O que significa O novo status não segue a ordem do pedido (ex.: `shipped` antes do pagamento). * O que fazer Leia o status atual do pedido e avance um passo de cada vez. ### `order_reference_taken` * Status HTTP 409 * Pode repetir Não * Mensagem no painel Este reference_id já foi usado nesta conexão. * O que significa Já existe um pedido com este `reference_id` nesta conexão. * O que fazer Use um `reference_id` novo para cada pedido (até 35 caracteres). ### `order_totals_mismatch` * Status HTTP 422 * Pode repetir Não * Mensagem no painel Os totais do pedido não fecham. * O que significa O total não é subtotal + imposto + frete − desconto, ou o subtotal não é a soma dos itens. * O que fazer Recalcule os valores em centavos (inteiros) e envie de novo. ### `payment_not_available` * Status HTTP 422 * Pode repetir Não * Mensagem no painel Forma de pagamento indisponível para este pedido. * O que significa A forma de pagamento não está disponível para este pedido (moeda, país ou configuração da Meta). * O que fazer Use BRL com Pix, link de pagamento ou boleto; veja o guia de comércio. ### `otp_template_invalid` * Status HTTP 422 * Pode repetir Não * Mensagem no painel O template de autenticação não existe ou não está aprovado. * O que significa O template de autenticação citado não existe ou não está `APPROVED`. * O que fazer Crie o template em `POST /v1/templates/authentication` e espere a aprovação antes de mandar códigos. ### `body_too_large` * Status HTTP 413 * Pode repetir Não * Mensagem no painel O corpo da requisição é grande demais para esta rota. * O que significa O corpo da requisição passou do limite desta rota. * O que fazer Envie um corpo menor; mídia grande vai por link ou upload próprio. ## Erros da Meta em meta_code [Seção intitulada “Erros da Meta em meta_code”](#erros-da-meta-em-meta_code) Quando a Meta recusa uma chamada da camada simples, o Messajo devolve o código dele em `code`, o código original da Meta em `meta_code` e o detalhe da Meta em `details[0].message`. Na camada espelho (`/v1/whatsapp/...`) a resposta da Meta volta como veio, sem tradução: o espelho é a própria Meta. | `meta_code` | `code` | HTTP | O que significa | O que fazer | | ------------------------------ | -------------------------------------------------------------------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | 131047 | [`outside_service_window`](/errors#outside_service_window) | 422 | Passaram mais de 24 horas desde a última mensagem do contato. O Messajo confere antes de chamar a Meta e responde o mesmo código. | Mande um template aprovado para reabrir a conversa. | | 131026 | [`recipient_unavailable`](/errors#recipient_unavailable) | 422 | A mensagem não pôde ser entregue (número sem WhatsApp, versão antiga, termos não aceitos). | Não repita; confirme o número com o contato por outro canal. | | 131049 | [`marketing_limit_reached`](/errors#marketing_limit_reached) | 422 | A Meta segurou o template de marketing para preservar a experiência do usuário. | Não repita logo em seguida; tente outro dia ou outro conteúdo. Numa [campanha](/guides/campaigns/#131049-e-as-24-horas), pausa sozinha a partir de 10 %. | | 131048 | [`meta_spam_rate_limited`](/errors#meta_spam_rate_limited) | 429 | A Meta limitou o número por suspeita de spam (muitas denúncias ou bloqueios). | Não repita; espere algumas horas e reduza o volume. Uma campanha pausa sozinha. | | 131056 | [`pair_rate_limited`](/errors#pair_rate_limited) | 429 | Muitas mensagens do mesmo número para o mesmo contato em pouco tempo. | Espere o `retry_after_ms` (6 s) e espace os envios; veja [Limite por par](/api/limits#limite-por-par). | | 130429 · 80007 · 4 | [`meta_rate_limited`](/errors#meta_rate_limited) | 429 | O número ou o app passou da vazão da Meta. | Repita depois do `Retry-After`; veja [Envio por número](/api/limits#envio-por-n%C3%BAmero). | | 132000 | [`template_error`](/errors#template_error) | 422 | O número de variáveis enviado não bate com o template. | Envie exatamente os parâmetros que o template define. | | 132001 | [`template_error`](/errors#template_error) | 422 | O template não existe no idioma pedido ou ainda não foi aprovado. | Confira nome, idioma e status do template. | | 132005 | [`template_error`](/errors#template_error) | 422 | O texto do template com as variáveis passou do tamanho máximo. | Encurte os valores das variáveis. | | 132007 | [`template_error`](/errors#template_error) | 422 | O conteúdo das variáveis viola a política da Meta. | Revise o texto enviado nas variáveis. | | 132012 | [`template_error`](/errors#template_error) | 422 | O formato de um parâmetro não bate com o template (ex.: imagem no lugar de texto). | Envie cada parâmetro no tipo que o template define. | | 132015 | [`template_error`](/errors#template_error) | 422 | O template foi pausado por baixa qualidade. O Messajo marca o template como `PAUSED`. | Edite o template ou use outro até a qualidade voltar. | | 132016 | [`template_error`](/errors#template_error) | 422 | O template foi desativado por baixa qualidade repetida. O Messajo marca o template como `DISABLED`. | Crie um template novo. | | 132068 · 132069 | [`template_error`](/errors#template_error) | 422 | O Flow do template está bloqueado ou com limite atingido. | Corrija o Flow no Gerenciador do WhatsApp. | | 368 · 131031 | [`policy_blocked`](/errors#policy_blocked) | 403 | A conta foi bloqueada por violar a política da Meta. A conexão passa para **Restrita**. | Veja o motivo no Gerenciador do WhatsApp e corrija antes de enviar de novo. | | 190 · 102 | [`connection_needs_reconnect`](/errors#connection_needs_reconnect) | 409 | O token de acesso da conexão é inválido ou expirou. | A conexão passa para `needs_reconnect` e donos e admins recebem um e-mail com link de reconexão. Reconecte. | | 131042 | [`meta_payment_required`](/errors#meta_payment_required) | 402 | Problema na forma de pagamento da conta na Meta. | Corrija o pagamento no Gerenciador de Negócios. | | 131030 | [`recipient_not_allowed`](/errors#recipient_not_allowed) | 422 | Número de teste: o destinatário não está na lista de permitidos. | Adicione o destinatário no painel do app da Meta. | | 131051 · 131052 · 131053 | [`media_error`](/errors#media_error) | 422 | Tipo de mensagem não suportado, ou a Meta não conseguiu baixar ou subir a mídia. | Confira o formato e o tamanho; use `media_id` em vez de `link`. | | 138006 | [`call_permission_required`](/errors#call_permission_required) | 403 | O contato não deu permissão para a empresa ligar. | Peça a permissão (veja [Ligações](/guides/calls/)) e espere `call.permission_updated`. | | 138xxx (limites de ligação) | [`call_rate_limited`](/errors#call_rate_limited) | 429 | Passou do limite de ligações ou de pedidos de permissão da Meta. | Espere; não repita em seguida. | | 138xxx (outros) | [`call_error`](/errors#call_error) | 422 | A Meta recusou a ação da ligação. | Veja `details[0].message`. | | 139001 | [`flow_invalid_json`](/errors#flow_invalid_json) | 422 | A Meta recusou o JSON do Flow. | Corrija o ponto citado em `details` (`flow_json::`). | | 139xxx (outros) | [`flow_error`](/errors#flow_error) | 422 | A Meta recusou a operação no Flow. | Veja `details[0].message`. | | 200 · 10 em catálogo | [`commerce_permission_missing`](/errors#commerce_permission_missing) | 403 | Falta a permissão `catalog_management` ao app. | Reconecte aceitando a permissão de catálogo. | | 133005 | [`pin_invalid`](/errors#pin_invalid) | 422 | O número já tem PIN de verificação em duas etapas e o PIN informado não confere. A conexão fica `pending` com motivo `pin_required`. | Informe o PIN de 6 dígitos na página da conexão (ou no link de conexão). Se não lembra, redefina o PIN no Gerenciador do WhatsApp. | | 133016 · 133008 · 133009 | [`pin_attempts_exhausted`](/errors#pin_attempts_exhausted) | 429 | Limite de 10 registros por número em 72 h, ou a Meta pediu espera. O Messajo conta as chamadas e não envia a 11ª. | Espere o `retry_after_ms` da resposta. | | 133010 | [`number_not_registered`](/errors#number_not_registered) | 409 | O número não está registrado na Cloud API. | Na página da conexão, use **Tentar registrar de novo**. | | 147002 | [`username_not_eligible`](/errors#username_not_eligible) | 422 | O número ainda não pode ter nome de usuário na Meta. | Tente de novo mais tarde; a liberação é da Meta. | | 100 | [`meta_invalid_parameter`](/errors#meta_invalid_parameter) | 400 | Parâmetro inválido na chamada. | Corrija o campo citado em `details[0].message`. | | 131000 · 131016 · 133004 · 5xx | [`meta_unavailable`](/errors#meta_unavailable) | 503 | A Meta está fora do ar ou sobrecarregada, numa leitura. | Repita com backoff. | | 131000 · 131016 · 133004 · 5xx | [`meta_unknown_outcome`](/errors#meta_unknown_outcome) | 502 | Mesma falha, mas num envio: a mensagem pode ter saído. | **Não** reenvie às cegas; veja abaixo. | | outro | [`meta_error`](/errors#meta_error) | 502 | Código da Meta sem tradução no Messajo. | Veja `meta_code` e `details[0].message`. | ### Instagram e Messenger [Seção intitulada “Instagram e Messenger”](#instagram-e-messenger) Instagram e Messenger usam a mesma tabela, com o código e o subcódigo da Meta (`meta_code` / subcódigo). O espelho (`/v1/instagram/...`, `/v1/messenger/...`) devolve a resposta da Meta sem tradução. | `meta_code` | `code` | HTTP | O que significa | O que fazer | | ------------------------------------------ | ------------------------------------------------------------------ | ---- | ------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | | 10 / 2018278 · 10 / 2534022 | [`outside_service_window`](/errors#outside_service_window) | 422 | Fora da janela de 24 h (ou de 7 dias com a tag). | Espere o contato escrever; resposta de pessoa pode usar `tag: "human_agent"`. | | 551 · 100 / 2018001 · 100 / 2534014 | [`recipient_unavailable`](/errors#recipient_unavailable) | 422 | O contato não está disponível (bloqueou a conta, apagou o perfil ou nunca conversou). | Não repita. | | 10 / 2018065 · 200 com `tag: human_agent` | [`human_agent_not_approved`](/errors#human_agent_not_approved) | 403 | A tag `HUMAN_AGENT` foi usada sem o recurso Human Agent aprovado. | Peça o recurso no App Review ou responda dentro de 24 h. | | 10 / 2534023 | [`private_reply_already_sent`](/errors#private_reply_already_sent) | 409 | O comentário já recebeu uma resposta privada. | Continue a conversa pelo Direct. | | 4 · 17 · 32 · 613 · 80006 | [`meta_rate_limited`](/errors#meta_rate_limited) | 429 | A conta ou o app passou da vazão da Meta. | Repita depois do `Retry-After`. | | 190 · 102 | [`connection_needs_reconnect`](/errors#connection_needs_reconnect) | 409 | O token da conta ou da Página é inválido. | A conexão passa para `needs_reconnect`; reconecte. | | 10 · 200 sem subcódigo mapeado (Messenger) | [`connection_needs_reconnect`](/errors#connection_needs_reconnect) | 409 | A pessoa que conectou perdeu o papel na Página. A conexão passa para `needs_reconnect` com motivo `page_role_lost`. | Reconecte com alguém que administre a Página. | | 200 / 2018028 · 10 · 3 | [`meta_permission_denied`](/errors#meta_permission_denied) | 403 | Falta uma permissão para essa ação. | Reconecte aceitando todas as permissões. | | 100 / 2018047 | [`media_error`](/errors#media_error) | 422 | Anexo recusado (tipo, tamanho ou URL). | Confira o formato e o tamanho; use `media_id`. | | 368 · 10 / 2018320 | [`policy_blocked`](/errors#policy_blocked) | 403 | A Meta bloqueou por política. A conexão passa para **Restrita**. | Veja o motivo na Meta antes de enviar de novo. | | 9 / 2207042 | [`publishing_limit_reached`](/errors#publishing_limit_reached) | 429 | Cota de 100 publicações em 24 h cheia. | O Messajo tenta de novo a cada hora por até 24 h. | | 2207xxx | [`publication_media_invalid`](/errors#publication_media_invalid) | 422 | A Meta não aceitou ou não conseguiu baixar a mídia da publicação. | Confira formato, tamanho e se a URL é pública. | | 1 · 2 · 5xx | [`meta_unavailable`](/errors#meta_unavailable) | 503 | A Meta está fora do ar, numa leitura. | Repita com backoff. | | 1 · 2 · 5xx | [`meta_unknown_outcome`](/errors#meta_unknown_outcome) | 502 | Mesma falha, num envio: a mensagem pode ter saído. | **Não** reenvie às cegas; veja abaixo. | | outro | [`meta_error`](/errors#meta_error) | 502 | Código da Meta sem tradução no Messajo. | Veja `meta_code` e `details[0].message`. | ### Envio sem resposta certa [Seção intitulada “Envio sem resposta certa”](#envio-sem-resposta-certa) Quando a Meta falha no meio de um envio (timeout, `5xx`), não dá para saber se a mensagem saiu. O Messajo **não** tenta de novo: grava a mensagem com o erro `meta_unknown_outcome` e responde `502` com `retryable: false`. Confira com o contato ou no celular antes de mandar de novo. Repetir com a mesma `Idempotency-Key` devolve a mesma resposta, sem reenviar; para mandar de novo de propósito, use uma chave nova. ## Falar com o suporte [Seção intitulada “Falar com o suporte”](#falar-com-o-suporte) Mande o `request_id` do erro (ou o cabeçalho `X-Request-Id`), a hora aproximada e o `code`. Com o `request_id` o suporte encontra a requisição exata nos logs. # Templates de autenticação > Códigos de verificação (OTP) pelo WhatsApp: os 3 tipos de botão, o handshake no app Android e o envio com type otp, sem o código ficar gravado. Um template de autenticação leva um **código de uso único** (login, confirmação de cadastro, troca de senha). A Meta fixa o texto; você escolhe o botão, a validade e o idioma. O código é **seu**: o Messajo não gera nem confere códigos, só entrega, e não grava o código em lugar nenhum. ## Os 3 tipos de botão [Seção intitulada “Os 3 tipos de botão”](#os-3-tipos-de-botão) | `otp_type` | O que o contato vê | Requisito | | ----------- | ---------------------------------------------- | ----------------------------------------------------------------------------------------------- | | `COPY_CODE` | botão **Copiar código** | nenhum | | `ONE_TAP` | botão que preenche o código no seu app Android | handshake no app; `supported_apps` | | `ZERO_TAP` | o código entra no app sozinho, sem toque | handshake no app; `supported_apps`; aceitar os termos da Meta (`zero_tap_terms_accepted: true`) | Quando o app não fez o handshake (ou o contato está no iPhone), `ONE_TAP` e `ZERO_TAP` viram **Copiar código**. ## Criar [Seção intitulada “Criar”](#criar) ```bash curl https://api.messajo.com/v1/templates/authentication \ -H "Authorization: Bearer $MESSAJO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "connection_id": "conn_...", "name": "codigo_login", "languages": ["pt_BR", "en_US", "es"], "add_security_recommendation": true, "code_expiration_minutes": 10, "message_send_ttl_seconds": 300, "button": { "otp_type": "ONE_TAP", "text": "Copiar código", "autofill_text": "Preencher", "supported_apps": [{ "package_name": "com.suaempresa.app", "signature_hash": "K8a/AINcGX7" }] } }' ``` * Volta um template por idioma (até 20), em revisão na Meta, como os outros [templates](/start/concepts/). * `add_security_recommendation` acrescenta “Para sua segurança, não compartilhe este código”. * `code_expiration_minutes` (1 a 90) acrescenta o rodapé com a validade. * `message_send_ttl_seconds` (30 a 900): depois desse tempo sem entregar, a Meta desiste (o código já teria vencido). * `supported_apps`: de 1 a 5 apps, cada um com o `package_name` e o `signature_hash` de 11 caracteres. `POST /v1/templates/authentication/preview` com os mesmos campos mostra o texto que a Meta vai gerar, sem criar nada. No painel, **Templates → Novo template → Autenticação**. ## Handshake no app Android [Seção intitulada “Handshake no app Android”](#handshake-no-app-android) `ONE_TAP` e `ZERO_TAP` só funcionam se o seu app avisar o WhatsApp **antes** de você mandar o código: 1. Gere o `signature_hash` do certificado que assina o app (o mesmo hash de 11 caracteres da SMS Retriever API do Google). 2. No app, logo antes de pedir o código ao seu backend, mande o intent de handshake para o WhatsApp (`com.whatsapp` e `com.whatsapp.w4b`) com um `PendingIntent` do seu app. 3. Para `ONE_TAP`, receba o código na Activity que trata `com.whatsapp.otp.OTP_RETRIEVED`; para `ZERO_TAP`, num `BroadcastReceiver` com o mesmo action. O passo a passo com código Kotlin está na [documentação da Meta](https://developers.facebook.com/docs/whatsapp/business-management-api/authentication-templates). Sem handshake válido, o botão cai para **Copiar código**. ## Mandar o código [Seção intitulada “Mandar o código”](#mandar-o-código) ```bash curl https://api.messajo.com/v1/messages \ -H "Authorization: Bearer $MESSAJO_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: 7b0c…" \ -d '{ "connection_id": "conn_...", "to": "5511999990001", "type": "otp", "otp": { "template": { "name": "codigo_login", "language": "pt_BR" }, "code": "482913" } }' ``` * Use `template_id` (`tpl_…`) **ou** `template` (nome e idioma), um dos dois. * `code`: de 4 a 15 letras ou números. * O template precisa ser `AUTHENTICATION` e estar aprovado; senão `422` [`otp_template_invalid`](/errors#otp_template_invalid). * Não há janela de 24 h: template sai a qualquer hora. ## O código não fica gravado [Seção intitulada “O código não fica gravado”](#o-código-não-fica-gravado) O código só existe na chamada à Meta. A mensagem guardada, os eventos (`message.sent`, `message.status`), os logs e a resposta guardada para a `Idempotency-Key` levam `code: "••••"` e `otp: true`. Você confere o código digitado contra o que o **seu** sistema gerou, nunca contra o Messajo. Boas práticas: código curto e com validade curta, limite de tentativas no seu backend e um código novo a cada pedido. # Ligações no WhatsApp > Receber e fazer ligações de voz pela Calling API: o Messajo cuida da sinalização, o áudio vai direto entre o seu cliente WebRTC e a Meta. O Messajo trata **só a sinalização** das ligações da [Calling API](https://developers.facebook.com/docs/whatsapp/cloud-api/calling): a oferta SDP chega por webhook, você responde pela API e o áudio (WebRTC ou SIP) passa direto entre o seu sistema e a Meta. O Messajo nunca carrega mídia. ## Antes de começar [Seção intitulada “Antes de começar”](#antes-de-começar) * Uma conexão de WhatsApp em modo **só API**. A coexistência não tem ligações: qualquer chamada de ligação nesse modo volta `422` [`calling_not_supported_in_coex`](/errors#calling_not_supported_in_coex). * Ligações ligadas nas configurações do número (abaixo). Desligadas → `409` [`calling_not_enabled`](/errors#calling_not_enabled). * O campo `calls` assinado no webhook do app da Meta. * Uma chave com `send` (atender, recusar, encerrar, ligar), `read` (log e permissões) e `admin` (configurações). ## Estados de uma ligação [Seção intitulada “Estados de uma ligação”](#estados-de-uma-ligação) | Direção | Caminho | | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------- | | Recebida (`user_initiated`) | `offered` → `pre_accepted` (opcional) → `accepted` → `terminating` → `ended`; ou `offered`/`pre_accepted` → `rejected` | | Feita (`business_initiated`) | `dialing` → `ringing` → `accepted` → `terminating` → `ended`; ou `dialing`/`ringing` → `rejected` | `end_reason` diz como terminou: `completed`, `missed` (nunca atendida), `failed`, `rejected`, `canceled` ou `unknown` (sem notícia da Meta por mais de 10 minutos). Ação que não vale no estado atual devolve `409` [`call_invalid_state`](/errors#call_invalid_state), com o estado atual em `details`. ## Receber uma ligação, de ponta a ponta [Seção intitulada “Receber uma ligação, de ponta a ponta”](#receber-uma-ligação-de-ponta-a-ponta) 1. O contato liga. Chega o evento `call.incoming` com `data.call.id` (`cal_…`), `sdp_type: "offer"` e o `sdp` da oferta. 2. Seu cliente WebRTC cria a resposta SDP a partir da oferta. 3. Opcional: `POST /v1/calls/{id}/pre-accept` com o `sdp` para a Meta já montar a mídia enquanto a tela de atender aparece. 4. `POST /v1/calls/{id}/accept` com o **mesmo** `sdp`. Depois de um `pre-accept`, um SDP diferente volta `409` [`call_sdp_mismatch`](/errors#call_sdp_mismatch) sem chamar a Meta. 5. Para desligar: `POST /v1/calls/{id}/terminate`. Quando a Meta confirma, chega `call.ended` com `duration_s`. Um cliente mínimo em JavaScript (navegador), que recebe o `call.incoming` do seu backend (por exemplo pelo [WebSocket](/webhooks/destinations/)) e atende: atender.js ```js const API = "https://api.messajo.com/v1"; // Chame do seu backend: a chave de API nunca vai para o navegador. async function callApi(path, body) { const res = await fetch(`/meu-backend/messajo${path}`, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(body), }); if (!res.ok) throw new Error(`Messajo ${res.status}`); return res.json(); } export async function onIncomingCall(event) { const { id, sdp } = event.data.call; // call.incoming const pc = new RTCPeerConnection(); const mic = await navigator.mediaDevices.getUserMedia({ audio: true }); for (const track of mic.getTracks()) pc.addTrack(track, mic); pc.ontrack = ({ streams }) => { const audio = new Audio(); audio.srcObject = streams[0]; audio.play(); }; await pc.setRemoteDescription({ type: "offer", sdp }); await pc.setLocalDescription(await pc.createAnswer()); // espera os candidatos ICE entrarem no SDP local await new Promise((resolve) => { if (pc.iceGatheringState === "complete") return resolve(); pc.onicegatheringstatechange = () => pc.iceGatheringState === "complete" && resolve(); }); const answer = pc.localDescription.sdp; await callApi(`/calls/${id}/pre-accept`, { sdp: answer }); await callApi(`/calls/${id}/accept`, { sdp: answer }); return { pc, hangUp: () => callApi(`/calls/${id}/terminate`, {}) }; } ``` O backend só repassa o corpo para `${API}/calls/{id}/…` com `Authorization: Bearer $MESSAJO_API_KEY`. O SDP é texto até 64 KiB, começa com `v=0` e pode vir com quebras LF ou CRLF; fora disso, `400` [`call_sdp_invalid`](/errors#call_sdp_invalid). ## Ligar para o contato [Seção intitulada “Ligar para o contato”](#ligar-para-o-contato) A Meta só deixa a empresa ligar para quem deu **permissão de chamada**. Confira antes: ```bash curl "https://api.messajo.com/v1/connections/conn_.../call-permissions?to=5511999990001" \ -H "Authorization: Bearer $MESSAJO_API_KEY" ``` A resposta traz `status` (`no_permission`, `temporary`, `permanent` ou `rejected`), `expires_at` e as `actions` que a Meta permite agora, com os limites. Sem permissão, peça com uma mensagem `interactive` do tipo `call_permission_request` (só `body.text`, dentro da janela de 24 h) ou com um template que tenha o componente de pedido de permissão. A resposta do contato chega como `call.permission_updated`. A Meta limita os pedidos a 1 por 24 h e 2 por 7 dias para o mesmo contato. Com permissão, ligue com a oferta SDP do seu cliente WebRTC: ```bash curl https://api.messajo.com/v1/calls \ -H "Authorization: Bearer $MESSAJO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "connection_id": "conn_...", "to": "5511999990001", "sdp": "v=0\r\n..." }' ``` Volta `201` com a ligação em `dialing`. A resposta SDP do contato chega em `call.sdp_answer`; os passos seguintes, em `call.status`. Sem permissão → `403` [`call_permission_required`](/errors#call_permission_required). ## Eventos [Seção intitulada “Eventos”](#eventos) | Tipo | Quando | | ------------------------- | -------------------------------------------------------------------------------- | | `call.incoming` | o contato ligou (com `sdp` da oferta) | | `call.sdp_answer` | o contato atendeu uma ligação sua (com `sdp` da resposta) | | `call.status` | `RINGING`, `ACCEPTED`, `REJECTED` | | `call.ended` | fim, com `end_reason`, `start_time`, `end_time` e `duration_s` | | `call.permission_updated` | a permissão de chamada do contato mudou (`status`, `is_permanent`, `expires_at`) | O SDP tem endereços IP do contato. Ele vai nos eventos, mas a leitura pela API (`GET /v1/calls`, `GET /v1/calls/{id}`) mostra só `has_sdp`, e o Messajo apaga o SDP 1 hora depois do fim da ligação. O painel mostra o log em **Ligações**. ## Configurações do número [Seção intitulada “Configurações do número”](#configurações-do-número) `GET /v1/connections/{id}/calling-settings` lê e `PUT` (chave `admin`) altera, em partes: ligar ou desligar (`status`), mostrar o ícone de ligar (`call_icon_visibility`), oferecer retorno de ligação (`callback_permission_status`), o horário de atendimento (`call_hours`, com fuso, dias da semana e feriados) e o SIP. No painel: conexão → **Ligações**. ## SIP [Seção intitulada “SIP”](#sip) Para levar o áudio a um PBX em vez de um cliente WebRTC, configure `sip.servers` (hostname público e porta). O Messajo só grava a configuração e a repassa à Meta. A senha SIP que a Meta gera vem **uma vez**, só num `GET …/calling-settings?include_sip_credentials=true` feito por chave `admin`: o Messajo não grava nem registra em log. ## Limites e erros [Seção intitulada “Limites e erros”](#limites-e-erros) | Código | Quando | | -------------------------------------------------------------- | ------------------------------------------------------------------ | | [`call_permission_required`](/errors#call_permission_required) | Meta `138006`: o contato não deu permissão | | [`call_rate_limited`](/errors#call_rate_limited) | limite de ligações ou de pedidos de permissão da Meta | | [`call_error`](/errors#call_error) | outro erro `138xxx` da Meta, com o detalhe em `details[0].message` | | [`meta_unknown_outcome`](/errors#meta_unknown_outcome) | a Meta falhou no meio da ação; o webhook acerta o estado depois | # Campanhas no WhatsApp > Template aprovado + lista CSV/JSON + variáveis + agendamento: como montar, enviar, acompanhar e retomar uma campanha. Uma campanha manda **um template aprovado** para uma lista de contatos, no ritmo do número e dentro da faixa de 24 horas do portfólio. Ela existe só no WhatsApp: Instagram e Messenger não permitem envio em massa. ## Antes de começar [Seção intitulada “Antes de começar”](#antes-de-começar) * Uma conexão de WhatsApp **Ativa** ou **Restrita** (veja [Conectar o WhatsApp](/connect/whatsapp/)). * Um template **Aprovado** da categoria **Marketing** ou **Utilidade** nessa conexão. * Uma chave com a permissão `send` (para criar e disparar) ou um membro com papel dono, admin ou dev no painel. O papel viewer só lê. ## O ciclo de vida [Seção intitulada “O ciclo de vida”](#o-ciclo-de-vida) | Status | O que quer dizer | | --------------- | ---------------------------------------------------------------------------------- | | `draft` | Rascunho. Só aqui dá para trocar template, variáveis e destinatários | | `scheduled` | Agendada para `scheduled_at` | | `running` | Enviando | | `waiting_limit` | A faixa de 24 h do portfólio acabou; volta sozinha em `limit_wait_until` | | `paused` | Pausada por alguém | | `auto_paused` | Pausada pelo Messajo para proteger o número (veja [Pausas](#pausas-e-o-que-fazer)) | | `completed` | Não sobrou destinatário na fila | | `canceled` | Cancelada; os destinatários na fila viram `skipped` | Nome e velocidade (`rate_limit_mps`) também mudam em `scheduled`, `paused` e `auto_paused`. Editar outra coisa fora do rascunho devolve `409` [`campaign_not_editable`](/errors#campaign_not_editable); uma ação que não vale no status atual devolve `409` [`campaign_invalid_state`](/errors#campaign_invalid_state). ## 1. Criar o rascunho [Seção intitulada “1. Criar o rascunho”](#1-criar-o-rascunho) No painel: **Campanhas → Nova campanha**, escolha a conexão e o template. Pela API: ```bash curl https://api.messajo.com/v1/campaigns \ -H "Authorization: Bearer $MESSAJO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Black Friday", "connection_id": "conn_...", "template": { "name": "promo_bf", "language": "pt_BR" }, "variables": { "body": [ { "contact": "display_name", "default": "cliente" }, { "column": "cupom" } ] } }' ``` A resposta é a campanha em `draft`. Template que não está aprovado ou não é de marketing/utilidade → `422` [`campaign_template_not_approved`](/errors#campaign_template_not_approved). ## 2. Mapear as variáveis [Seção intitulada “2. Mapear as variáveis”](#2-mapear-as-variáveis) Cada parâmetro do template precisa de uma origem. Faltou algum → `422` [`campaign_template_mapping_invalid`](/errors#campaign_template_mapping_invalid), com o parâmetro em `details`. | Origem | Exemplo | De onde vem o valor | | ------- | ----------------------------------------------------- | --------------------------------------------- | | Coluna | `{ "column": "cupom", "default": "BF10" }` | coluna do CSV ou chave de `variables` no JSON | | Fixo | `{ "value": "até domingo" }` | o mesmo texto para todos | | Contato | `{ "contact": "display_name", "default": "cliente" }` | nome do contato, quando o Messajo conhece | * `body`: lista na ordem de `{{1}}`, `{{2}}`… (formato posicional) ou objeto por nome (formato `NAMED`). * `header`: `{ "params": [...] }` para texto, `{ "media_id": "med_..." }` para imagem, vídeo ou documento, ou `{ "location": {...} }`. * `buttons`: `[{ "index": 0, "param": {...} }]` para URL dinâmica, código de cupom e payload. Use `default` quando a coluna pode vir vazia. Sem `default`, a linha vira `invalid` com o motivo `missing_variable:`. Valor com mais de 1024 caracteres vira `invalid` (`variable_too_long`). ## 3. Enviar a lista [Seção intitulada “3. Enviar a lista”](#3-enviar-a-lista) Baixe o [CSV de exemplo](/examples/campanha-exemplo.csv) para começar: ```csv to,nome,cupom 5511999990001,Ana,BF10 +55 (21) 99999-0002,Bruno, ctc_0193a1b2c3d47e8f9a0b1c2d3e4f5a6b,,BF20 ``` * Cabeçalho obrigatório. A coluna do destino é `to` (ou outra, com `to_column`); as outras viram variáveis. * Separador `,`, `;` ou tab. BOM do Excel é aceito. * O destino pode ser telefone (o Messajo tira `+ ( ) - .` e espaços; de 8 a 15 dígitos), BSUID ou o `ctc_…` de um contato da organização. * Repetidos são ignorados e contados em `rows_duplicate`. Até 10 000 destinatários por chamada vão no corpo, em JSON, e a importação volta pronta: ```bash curl https://api.messajo.com/v1/campaigns/cmp_.../recipients \ -H "Authorization: Bearer $MESSAJO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "recipients": [ { "to": "5511999990001", "variables": { "cupom": "BF10" } } ] }' ``` Arquivo (CSV, JSON ou NDJSON, até 20 MiB) vai por `multipart` e volta `202` com a importação em fila. Acompanhe em `GET /v1/campaigns/{id}/imports/{import_id}`: os 100 primeiros erros saem em `errors` com linha, coluna e código. ```bash curl https://api.messajo.com/v1/campaigns/cmp_.../recipients \ -H "Authorization: Bearer $MESSAJO_API_KEY" \ -F "file=@campanha-exemplo.csv" -F "to_column=to" ``` O teto é 100 000 destinatários por campanha (`422` [`campaign_too_many_recipients`](/errors#campaign_too_many_recipients)). ## 4. Conferir a prévia [Seção intitulada “4. Conferir a prévia”](#4-conferir-a-prévia) `POST /v1/campaigns/{id}/preview` (ou o passo **Prévia** no painel) mostra as primeiras mensagens já montadas, com o corpo e os parâmetros trocados. Confira antes de agendar: mensagem errada não volta. ## 5. Agendar ou começar agora [Seção intitulada “5. Agendar ou começar agora”](#5-agendar-ou-começar-agora) ```bash curl -X POST https://api.messajo.com/v1/campaigns/cmp_.../schedule \ -H "Authorization: Bearer $MESSAJO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "scheduled_at": "2026-11-27T12:00:00Z" }' ``` * `scheduled_at` entre 1 minuto e 90 dias à frente (`422` [`campaign_schedule_invalid`](/errors#campaign_schedule_invalid)). * Precisa de pelo menos um destinatário válido ([`campaign_no_recipients`](/errors#campaign_no_recipients)) e de nenhuma importação em andamento ([`campaign_import_in_progress`](/errors#campaign_import_in_progress)). * `POST /start` dispara agora; `POST /unschedule` volta para rascunho. ## Velocidade e a faixa do portfólio [Seção intitulada “Velocidade e a faixa do portfólio”](#velocidade-e-a-faixa-do-portfólio) * **Velocidade:** por padrão, 80 % da vazão do número (`send_rate_mps`); os 20 % restantes ficam para os envios da API. Ajuste com `rate_limit_mps`, de 1 até a vazão do número. * **Faixa de 24 h:** a Meta limita quantos contatos **únicos** recebem template por dia (250, 2 000, 10 000, 100 000 ou ilimitado). O limite é do **portfólio**: todos os números do mesmo Business dividem a faixa. O Messajo para em 95 % da faixa e a campanha vai para `waiting_limit`; quando os envios mais antigos saem da janela de 24 h, ela volta sozinha. * Contato com a janela de atendimento aberta não gasta faixa. * O contador só enxerga o que sai pelo Messajo. Se você também envia por outra ferramenta no mesmo portfólio, deixe folga. `GET /v1/campaigns/{id}` traz `estimate`: destinatários válidos, velocidade efetiva, duração estimada e quanto resta da faixa. ## Pausas e o que fazer [Seção intitulada “Pausas e o que fazer”](#pausas-e-o-que-fazer) O Messajo pausa sozinho (`auto_paused`), avisa por e-mail donos, admins e quem criou a campanha, e emite `campaign.paused` com `auto: true`. Para continuar, `POST /resume` (ou **Retomar** no painel): retomar aceita a qualidade atual como nova referência. | `pause_reason` | Por quê | O que fazer | | ----------------------- | ------------------------------------------------------ | --------------------------------------------------------------------- | | `quality_low` | A qualidade do número caiu (ou o envio ficou limitado) | Revise conteúdo e lista; insistir derruba a qualidade e a faixa | | `template_paused` | O template saiu de **Aprovado** | Espere voltar a Aprovado em **Templates** | | `template_quality_low` | A qualidade do template caiu | Ajuste o template ou a lista: muita gente bloqueando ou denunciando | | `error_rate` | 20 % ou mais de falhas nos últimos 100 envios | Baixe o relatório e veja os códigos | | `marketing_limit` | 10 % ou mais de `131049` | Veja abaixo | | `spam_limit` | A Meta respondeu `131048` (suspeita de spam) | Espere algumas horas e reduza a velocidade | | `policy` | Bloqueio por política ou token caído | Resolva na conexão; pode precisar reconectar | | `connection_not_active` | A conexão não está ativa | Reconecte e retome | | `spend_cap` | O teto de gasto do mês foi atingido | Suba o teto em Configurações → Custos ou espere virar o mês, e retome | | `manual` | Alguém pausou | Retome quando quiser | ### 131049 e as 24 horas [Seção intitulada “131049 e as 24 horas”](#131049-e-as-24-horas) [`marketing_limit_reached`](/errors#marketing_limit_reached) (`131049`) é a Meta segurando marketing para quem já recebeu demais. Não é falha do número e não adianta repetir logo: o contato só volta a receber depois de um tempo que a Meta não informa (na prática, um dia ou mais). Termine a campanha, espere pelo menos 24 horas e use **Duplicar** com `recipients: "failed"` para mandar só para quem falhou. ## Acompanhar e o relatório [Seção intitulada “Acompanhar e o relatório”](#acompanhar-e-o-relatório) * `GET /v1/campaigns/{id}/recipients?status=failed` lista os destinatários por status: `pending`, `invalid`, `sending`, `sent`, `delivered`, `read`, `failed`, `unknown`, `skipped`. * `unknown` é envio que pode ter saído (queda da Meta ou do processo no meio). O Messajo **nunca** reenvia às cegas; se a Meta mandar o status depois, o destinatário é atualizado. * `GET /v1/campaigns/{id}/report` devolve um CSV com `to`, `contact_id`, `status`, `message_id`, `external_id`, `error_code`, `meta_code`, as datas e as colunas de variáveis. * Os status de entrega continuam chegando até 72 horas depois de `completed`. * Eventos: `campaign.scheduled`, `campaign.started`, `campaign.paused`, `campaign.resumed`, `campaign.progress` (no máximo 1 por minuto), `campaign.completed` e `campaign.canceled`. As mensagens saem com `campaign: { id, recipient_id }` em `message.sent` e `message.status`. Veja [Eventos](/webhooks/events/). # Vendas no WhatsApp > Catálogo, produtos, carrinho e cobrança com Pix, link de pagamento ou boleto: como montar, mandar e conciliar um pedido. O WhatsApp vende em três passos: o contato vê o **catálogo**, monta um **carrinho** e você manda a **cobrança** (`order_details`) com Pix, link de pagamento ou boleto. O Messajo guarda cada pedido, calcula os totais e avisa por evento. ## Antes de começar [Seção intitulada “Antes de começar”](#antes-de-começar) * Uma conexão de WhatsApp ativa e a permissão `catalog_management` concedida ao app da Meta (sem ela, `403` [`commerce_permission_missing`](/errors#commerce_permission_missing)). * Chave com `commerce` para catálogos, produtos, configurações e pagamento manual, `send` para as mensagens e `read` para ler. No painel, **Vendas**. * Valores sempre em **centavos** (`amount_minor`, inteiro). `R$ 12,90` = `1290`. ## Catálogo e produtos [Seção intitulada “Catálogo e produtos”](#catálogo-e-produtos) | Chamada | O que faz | | ---------------------------------------------------------- | ------------------------------------------------------------------------------------- | | `POST /v1/catalogs` | cria um catálogo no portfólio e liga à conta de mensagens (`{ connection_id, name }`) | | `POST /v1/catalogs/link` · `POST /v1/catalogs/{id}/unlink` | liga um catálogo que já existe (`catalog_external_id`) ou desliga | | `POST /v1/catalogs/{id}/sync` | relê os produtos da Meta (também roda todo dia) | | `GET` · `PUT /v1/connections/{id}/commerce-settings` | `is_cart_enabled` (carrinho) e `is_catalog_visible` (ícone da loja) | | `GET` · `POST /v1/catalogs/{id}/products` | lista e cria produtos | | `GET` · `PATCH` · `DELETE /v1/products/{id}` | lê, altera e apaga | ```json { "retailer_id": "bolo-cenoura", "name": "Bolo de cenoura", "amount_minor": 4500, "sale_amount_minor": 3900, "currency": "BRL", "availability": "in stock", "image_url": "https://loja.suaempresa.com/img/bolo.jpg" } ``` O `retailer_id` é o seu código do produto: é ele que vai nas mensagens e volta no carrinho. ## Mostrar produtos [Seção intitulada “Mostrar produtos”](#mostrar-produtos) Pelo `POST /v1/messages`, com `type: "interactive"`: | `interactive.type` | O que mostra | | ------------------ | ---------------------------------------------------------------------------- | | `product` | um produto (`action.catalog_id` + `product_retailer_id`) | | `product_list` | até 30 produtos em até 10 seções, com header de texto | | `catalog_message` | o catálogo inteiro, com um produto de capa (`thumbnail_product_retailer_id`) | Um catálogo que não está ligado à conta → `409` [`catalog_not_linked`](/errors#catalog_not_linked). Templates com catálogo ou vários produtos usam o formato da Meta, como qualquer [template](/start/concepts/). ## Receber o carrinho [Seção intitulada “Receber o carrinho”](#receber-o-carrinho) O contato manda o carrinho e chegam `message.received` (conteúdo `order`) e `order.received`, com o pedido em `cart_received`, os itens e os totais calculados pelos preços do carrinho. Leia depois com `GET /v1/orders` ou `GET /v1/orders/{id}`. ## Cobrar com Pix [Seção intitulada “Cobrar com Pix”](#cobrar-com-pix) Mande um `order_details` com `payment_type: "br"`: ```json { "connection_id": "conn_...", "to": "5511999990001", "type": "interactive", "interactive": { "type": "order_details", "body": { "text": "Seu pedido" }, "action": { "name": "review_and_pay", "parameters": { "reference_id": "pedido-1042", "type": "digital-goods", "payment_type": "br", "currency": "BRL", "total_amount": { "value": 3900, "offset": 100 }, "payment_settings": [ { "type": "pix_dynamic_code", "pix_dynamic_code": { "code": "00020101021226…6304ABCD", "merchant_name": "Doceria Exemplo", "key": "39580525000189", "key_type": "CNPJ" } } ], "order": { "status": "pending", "items": [{ "retailer_id": "bolo-cenoura", "name": "Bolo de cenoura", "amount": { "value": 3900, "offset": 100 }, "quantity": 1 }], "subtotal": { "value": 3900, "offset": 100 } } } } } } ``` O Messajo confere antes de chamar a Meta: * `currency: "BRL"`, `offset: 100` em todos os valores e `action.name: "review_and_pay"`; * `subtotal` = soma de `quantidade × (sale_amount ?? amount)` e `total` = `subtotal + tax + shipping − discount`; não bate → `422` [`order_totals_mismatch`](/errors#order_totals_mismatch); * `reference_id` único na conexão, de 1 a 35 caracteres (letras, números, `_`, `.`, `-`); repetido → `409` [`order_reference_taken`](/errors#order_reference_taken); * de 1 a 3 formas de pagamento, sem repetir tipo: `pix_dynamic_code` (o código copia-e-cola do seu PSP, nome, chave e tipo da chave), `payment_link` (`uri` https) e `boleto` (`digitable_line`); * até 100 itens. Requisitos do Pix: o código dinâmico vem do **seu** PSP (banco ou gateway), com o valor do pedido; a chave tem que ser da mesma conta. A Meta só mostra o código ao contato. Depois do envio, o pedido fica `pending` com `payment_status: pending` e sai `order.updated`. Com o parâmetro `expiration` da Meta, o pedido vencido vira `payment_status: expired`. ## Conciliar o pagamento [Seção intitulada “Conciliar o pagamento”](#conciliar-o-pagamento) O Pix fora da plataforma **não** tem webhook de pagamento: a Meta não sabe se o contato pagou. Concilie no seu PSP pelo `reference_id` (use o mesmo id na cobrança do PSP) e avise o Messajo: ```bash curl https://api.messajo.com/v1/orders/ord_.../payment \ -H "Authorization: Bearer $MESSAJO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "status": "captured", "notify": true }' ``` `notify: true` manda ao contato um `order_status` `processing` (com `message` opcional) e a resposta traz `notification_message_id`. No painel, o pedido tem **Marcar como pago**. Link de pagamento e cartão com webhook da Meta atualizam sozinhos e geram `payment.updated`. ## Andamento do pedido [Seção intitulada “Andamento do pedido”](#andamento-do-pedido) Mande `order_status` (`action.name: "review_order"`) para avisar o contato: `processing`, `partially_shipped`, `shipped`, `completed` ou `canceled`. ```text cart_received → pending → processing → partially_shipped → shipped → completed cart_received | pending | processing → canceled ``` Transição fora desse caminho → `409` [`order_invalid_transition`](/errors#order_invalid_transition). ## Eventos [Seção intitulada “Eventos”](#eventos) | Tipo | Quando | | ----------------- | ------------------------------------------------------------------------------------------------------- | | `order.received` | chegou um carrinho | | `order.updated` | cobrança enviada, status mudou, pagamento marcado ou vencido | | `payment.updated` | a Meta avisou o pagamento (`{ order: { id, reference_id }, payment: { status, method, transaction } }`) | # Custos da Meta > Quanto o WhatsApp custa: estimado × oficial, tela de Custos, conversão de moeda, teto de gasto e GET /v1/usage/costs. O Messajo mostra quanto a Meta cobra pelas suas mensagens e pode pausar campanhas quando o gasto do mês chega ao teto que você definir. Os valores dos exemplos desta página são ilustrativos. ## O que a Meta cobra [Seção intitulada “O que a Meta cobra”](#o-que-a-meta-cobra) * Só o WhatsApp tem cobrança. Instagram e Messenger não entram. * A cobrança é por mensagem **entregue**, por categoria (marketing, utilidade, autenticação, serviço) e país do destinatário. `sent` não cobra. * Mensagens `free_*` e `paid_exempt` não entram na conta. * A fatura sai na moeda da conta do WhatsApp. ## Estimado × oficial [Seção intitulada “Estimado × oficial”](#estimado--oficial) * **Estimado**: gravado na entrega. O preço sai, nesta ordem, do custo real da sua conta no mesmo mercado e categoria nos últimos 30 dias (já com desconto por volume), da tabela de preços baixada da Meta ou da tabela que vem no repositório. A origem fica gravada em cada mensagem (`calibrated`, `rate_card` ou `seed`). * **Oficial**: valor **aproximado** que a Meta informa por dia. O Messajo busca todo dia às 06:00 UTC, dos últimos 3 dias. Os dias são em UTC. * A diferença vem de desconto por volume e de arredondamento. O painel avisa quando ela passa de 10% num dia. ## Tela de Custos [Seção intitulada “Tela de Custos”](#tela-de-custos) Em **Custos** você escolhe o período e a conexão e vê os cartões, o gráfico diário e as abas de recorte. Campanha e template são sempre **estimados**. Aparece “sem estimativa” quando o destinatário não tem telefone, a moeda não tem tabela ou a categoria está fora da tabela. ## Conversão de moeda [Seção intitulada “Conversão de moeda”](#conversão-de-moeda) A conversão usa a cotação do BCE do dia de cada gasto. `FX_PROVIDER=none` desliga a conversão. Moeda que o BCE não cota não converte. ## Teto de gasto [Seção intitulada “Teto de gasto”](#teto-de-gasto) * Em **Configurações → Custos** o dono ou admin define um valor mensal por moeda, os percentuais de aviso e se as campanhas pausam em 100%. * O mês segue o fuso da organização. * Com a pausa ligada, campanhas rodando pausam com motivo `spend_cap`. Envios avulsos e de serviço seguem. * Iniciar ou retomar devolve `409` [`spend_cap_reached`](/errors#spend_cap_reached) até virar o mês ou subir o teto. A retomada é manual. ## Pela API [Seção intitulada “Pela API”](#pela-api) `GET /v1/usage/costs` exige a permissão `read`. Parâmetros: `from`, `to`, `connection_id`, `currency` e `group_by`. ```bash curl -H "Authorization: Bearer $MESSAJO_API_KEY" \ "https://api.messajo.com/v1/usage/costs?from=2026-11-10&to=2026-11-11¤cy=BRL&group_by=day" ``` ```json { "currency": "BRL", "items": [ { "key": "2026-11-10", "estimate": "37.5", "official": "36.92" }, { "key": "2026-11-11", "estimate": "12.25", "official": null } ] } ``` O `message.status` traz o campo `cost`: ```json { "type": "message.status", "data": { "status": "delivered", "pricing": { "billable": true, "pricing_model": "PMP", "category": "marketing", "type": "regular" }, "cost": { "estimate": "0.35", "currency": "BRL", "rate_card_version": "2026-10" } } } ``` `cost` vem só no status que gerou a cobrança (`delivered`, ou `read` se o `delivered` não chegou) e é `null` nos demais. `estimate: null` quer dizer cobrada, sem estimativa. # WhatsApp Flows > Criar, publicar e mandar Flows, receber as respostas e usar o endpoint de data exchange do Messajo, que cuida da criptografia da Meta. Um [WhatsApp Flow](https://developers.facebook.com/docs/whatsapp/flows) é um formulário de várias telas que abre dentro do WhatsApp. O Messajo cria e publica o Flow na sua conta de mensagens, manda o Flow numa mensagem, entrega a resposta como evento e, se o Flow busca dados no seu sistema, **hospeda o endpoint** que a Meta chama: a criptografia RSA/AES fica com o Messajo e o seu servidor recebe JSON em texto claro, assinado. ## Antes de começar [Seção intitulada “Antes de começar”](#antes-de-começar) * Uma conexão de WhatsApp ativa. O Flow pertence à conta de mensagens (WABA) dela. * Chave com a permissão `templates` (criar, editar, publicar) e `read` (ler e ver as trocas). * No webhook do app da Meta, o campo `flows` assinado. ## Criar e editar o JSON [Seção intitulada “Criar e editar o JSON”](#criar-e-editar-o-json) ```bash curl https://api.messajo.com/v1/flows \ -H "Authorization: Bearer $MESSAJO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "connection_id": "conn_...", "name": "agendamento", "categories": ["APPOINTMENT_BOOKING"], "flow_json": { "version": "7.0", "screens": [ ... ] } }' ``` O Flow nasce `DRAFT` (`flw_…`). Categorias: `SIGN_UP`, `SIGN_IN`, `APPOINTMENT_BOOKING`, `LEAD_GENERATION`, `CONTACT_US`, `CUSTOMER_SUPPORT`, `SURVEY` e `OTHER`. * `PUT /v1/flows/{id}/json` troca o JSON (corpo cru, até 10 MiB). O Messajo confere o básico (JSON válido, `version` e `screens`) e a Meta valida o resto: os erros dela voltam em `422` [`flow_invalid_json`](/errors#flow_invalid_json), com `details[].path` no formato `flow_json::`. * Só um `DRAFT` muda. Publicado → `409` [`flow_not_editable`](/errors#flow_not_editable); faça `POST /v1/flows/{id}/clone` e edite a cópia. * `POST /v1/flows/{id}/preview` devolve `preview_url` e `expires_at` para abrir o Flow no navegador. * `POST /v1/flows/{id}/publish` publica; `…/deprecate` aposenta; `DELETE` apaga (só `DRAFT`); `…/sync` relê o status da Meta. No painel, **Flows** tem a lista, o editor de JSON com prévia e o link para o construtor visual da Meta. ## Mandar o Flow [Seção intitulada “Mandar o Flow”](#mandar-o-flow) ```json { "connection_id": "conn_...", "to": "5511999990001", "type": "interactive", "interactive": { "type": "flow", "body": { "text": "Escolha o melhor horário" }, "action": { "name": "flow", "parameters": { "flow_message_version": "3", "flow_id": "flw_...", "flow_cta": "Agendar", "flow_action": "navigate", "flow_action_payload": { "screen": "INICIO" } } } } } ``` `flow_id` aceita o `flw_…` do Messajo ou o id da Meta. `flow_cta` vai até 20 caracteres. Sem `flow_token`, o Messajo gera um (`mjft_…`) e guarda com o contato, a conversa e a mensagem, para o endpoint saber de quem é a troca. Um Flow num template (botão **FLOW**) funciona igual. ## Receber as respostas [Seção intitulada “Receber as respostas”](#receber-as-respostas) Quando o contato termina o Flow, chegam `message.received` (conteúdo `reply` com `kind: "flow"`) e `flow.response`: ```json { "type": "flow.response", "data": { "flow": { "id": "flw_...", "external_id": "1234567890", "name": "agendamento" }, "flow_token": "mjft_...", "response": { "data": "2026-11-20", "horario": "09:00" }, "message": { "id": "msg_..." }, "contact": { "id": "ctc_..." }, "conversation": { "id": "cnv_..." } } } ``` Outros eventos: `flow.status_changed` (a Meta publicou, bloqueou ou limitou o Flow), `flow.endpoint_alert` (alerta de saúde do endpoint: taxa de erro, latência, disponibilidade) e `flow.endpoint_error` (o app do contato avisou um erro no endpoint). ## O endpoint de data exchange do Messajo [Seção intitulada “O endpoint de data exchange do Messajo”](#o-endpoint-de-data-exchange-do-messajo) Flow que busca dados (tela dinâmica, validação, agendamento) precisa de um endpoint. Dê ao Flow um `endpoint` com a URL do **seu** handler: ```json { "endpoint": { "url": "https://app.suaempresa.com/flows/agendamento", "headers": [{ "name": "X-Tenant", "value": "loja-1" }] } } ``` O Messajo cadastra na Meta o endereço `https://api.messajo.com/meta/flows/` e devolve o `handler_secret` **uma vez** (gire com `POST /v1/flows/{id}/rotate-handler-secret`). Sem handler, um Flow com endpoint volta `422` [`flow_handler_required`](/errors#flow_handler_required). A URL do handler segue as regras dos [destinos](/webhooks/destinations/): `https` e endereço público. A cada troca, a Meta chama o Messajo; o Messajo confere a assinatura da Meta, decifra, responde sozinho o `ping` e as notificações de erro, e repassa `INIT`, `BACK` e `data_exchange` para o seu handler: ```http POST https://app.suaempresa.com/flows/agendamento Content-Type: application/json Messajo-Signature: t=1763000000,v1=5257a869… Messajo-Flow-Id: flw_... Messajo-Request-Id: req_... User-Agent: Messajo-Flows/1 { "type": "flow.data_exchange", "flow": { "id": "flw_...", "external_id": "1234567890", "name": "agendamento" }, "action": "data_exchange", "screen": "INICIO", "data": { "data": "2026-11-20" }, "flow_token": "mjft_...", "context": { "connection_id": "conn_...", "contact_id": "ctc_...", "message_id": "msg_..." }, "version": "3.0" } ``` Responda `200` com a próxima tela, no formato da Meta: ```json { "screen": "HORARIOS", "data": { "horarios": [{ "id": "09", "title": "09:00" }] } } ``` * `context` vem `null` quando o Flow não saiu pelo Messajo (sem `flow_token` conhecido). * `flow_token` que você não reconhece → responda `{ "error": "flow_token_invalid" }`: o Messajo devolve `427` à Meta e o app mostra que o Flow expirou. * Tempo máximo do handler: **7 s**; resposta até 256 KiB. Erro, demora ou resposta sem `screen` → a Meta recebe `500` e o contato vê um erro genérico. Cada troca fica em `GET /v1/flows/{id}/exchanges` por 7 dias (sem os dados), com o resultado e o tempo. ### Verificar a assinatura do handler [Seção intitulada “Verificar a assinatura do handler”](#verificar-a-assinatura-do-handler) O `Messajo-Signature` é igual ao dos webhooks, com o `handler_secret` como chave: HMAC-SHA256 de `${t}.${corpo cru}`, comparação em tempo constante e tolerância de 5 minutos. Detalhes em [Verificar a assinatura](/webhooks/verify-signature/). verify.ts ```ts import { createHmac, timingSafeEqual } from "node:crypto"; const TOLERANCE_SECONDS = 300; const DIGITS = /^\d+$/; /** * Checks the Messajo-Signature header ("t=,v1=[,v1=…]"). * `rawBody` must be the exact body received, before any JSON parsing. */ export function verify( header: string, rawBody: string, secret: string, nowSeconds: number = Math.floor(Date.now() / 1000) ): boolean { const timestamps: string[] = []; const signatures: string[] = []; for (const part of header.split(",")) { const [key, value = ""] = part.trim().split("=", 2); if (key === "t") { timestamps.push(value); } else if (key === "v1") { signatures.push(value); } } const [rawTimestamp = ""] = timestamps; if (timestamps.length !== 1 || !DIGITS.test(rawTimestamp)) { return false; } const timestamp = Number(rawTimestamp); if (Math.abs(nowSeconds - timestamp) > TOLERANCE_SECONDS) { return false; } const expected = Buffer.from( createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest("hex") ); return signatures.some((signature) => { const received = Buffer.from(signature); return ( received.length === expected.length && timingSafeEqual(received, expected) ); }); } ``` verify.py ```python """Verify a Messajo webhook signature. Usage: python3 verify.py < raw_body Exit code 0 = valid signature, 1 = invalid. """ import hashlib import hmac import sys import time TOLERANCE_SECONDS = 300 def verify(header: str, raw_body: bytes, secret: str, now: int | None = None) -> bool: """`raw_body` must be the exact bytes received, before any JSON parsing.""" timestamps, signatures = [], [] for part in header.split(","): key, _, value = part.strip().partition("=") if key == "t": timestamps.append(value) elif key == "v1": signatures.append(value) if len(timestamps) != 1 or not (timestamps[0].isascii() and timestamps[0].isdigit()): return False timestamp = int(timestamps[0]) now = int(time.time()) if now is None else now if abs(now - timestamp) > TOLERANCE_SECONDS: return False signed = f"{timestamp}.".encode() + raw_body expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest() return any(hmac.compare_digest(expected, signature) for signature in signatures) if __name__ == "__main__": secret, header = sys.argv[1], sys.argv[2] sys.exit(0 if verify(header, sys.stdin.buffer.read(), secret) else 1) ``` ### Códigos que a Meta recebe [Seção intitulada “Códigos que a Meta recebe”](#códigos-que-a-meta-recebe) | HTTP | Quando | O que o app do contato faz | | ----- | ----------------------------------------------------------- | -------------------------------------- | | `200` | resposta cifrada | segue o Flow | | `421` | o Messajo não decifrou com a chave atual nem com a anterior | baixa a chave pública de novo e repete | | `427` | o handler respondeu `flow_token_invalid` | mostra que o Flow não vale mais | | `432` | a assinatura da Meta (`X-Hub-Signature-256`) não confere | erro | | `429` | mais de 1.200 trocas por minuto no Flow | erro | | `500` | o handler falhou | erro genérico | ### Chave e rotação [Seção intitulada “Chave e rotação”](#chave-e-rotação) A Meta cifra cada troca com a **chave pública da conta de mensagens**. O Messajo gera um par RSA 2048 na primeira vez que um Flow da conta usa o endpoint, envia a chave a todos os números ativos e confere todo dia se a Meta ainda tem a chave certa (reenvia sozinho se faltar). Para trocar: `POST /v1/connections/{id}/flow-key/rotate` (chave `admin`); a chave anterior continua decifrando por **24 horas**. Publicar sem a chave enviada a pelo menos um número → `409` [`flow_key_not_uploaded`](/errors#flow_key_not_uploaded). Pelo [espelho](/operate/migrate/), `whatsapp_business_encryption` fica bloqueado (`403 mirror_path_blocked`) quando a chave é do Messajo, para ninguém trocar a chave por fora. ## Erros [Seção intitulada “Erros”](#erros) | Código | Quando | | ------------------------------------------------ | ------------------------------------------- | | [`flow_not_found`](/errors#flow_not_found) | o Flow não existe ou é de outra organização | | [`flow_invalid_json`](/errors#flow_invalid_json) | JSON recusado (Meta `139001`) | | [`flow_error`](/errors#flow_error) | outro erro `139xxx` da Meta | # Grupos no WhatsApp > Criar e administrar grupos pela Groups API, mandar e receber mensagens de grupo e os eventos group.*. A [Groups API](https://developers.facebook.com/docs/whatsapp/cloud-api/groups) da Meta deixa um número em modo **só API** criar e administrar grupos pequenos. No Messajo ela existe **só pela API**: o painel não tem tela de grupos. ## Antes de começar [Seção intitulada “Antes de começar”](#antes-de-começar) * Conexão de WhatsApp **só API**. Na coexistência, `422` [`group_not_supported`](/errors#group_not_supported). * No webhook do app da Meta, os campos `group_lifecycle_update`, `group_participants_update`, `group_settings_update` e `group_status_update` assinados. * Chave com `send` para criar, editar e moderar, `read` para ler e `admin` para apagar. ## Criar [Seção intitulada “Criar”](#criar) ```bash curl https://api.messajo.com/v1/groups \ -H "Authorization: Bearer $MESSAJO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "connection_id": "conn_...", "subject": "Turma de sábado", "description": "Avisos da turma", "join_approval_mode": "approval_required" }' ``` O grupo nasce `creating` (`grp_…`). A Meta cria em segundo plano e avisa por webhook: deu certo → `active` com o `invite_link` e o evento `group.created`; falhou → `failed` e `group.create_failed` com o motivo. `subject` vai até 128 caracteres e `description` até 2048. | Status | O que quer dizer | | ---------------------- | --------------------- | | `creating` | esperando a Meta | | `active` | pronto para mensagens | | `suspended` | suspenso pela Meta | | `deleting` · `deleted` | apagado | | `failed` | a Meta não criou | ## Administrar [Seção intitulada “Administrar”](#administrar) | Chamada | O que faz | | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ | | `GET /v1/groups` · `GET /v1/groups/{id}` | lista e lê (assunto, descrição, participantes, status) | | `PATCH /v1/groups/{id}` | troca assunto e descrição; em `multipart/form-data`, o campo `picture` troca a foto (JPEG quadrado, ≥ 192 px, até 5 MiB) | | `GET /v1/groups/{id}/invite-link` · `POST …/invite-link/reset` | lê ou gera um link de convite novo (o antigo deixa de valer) | | `POST /v1/groups/{id}/participants/remove` | `{ "participants": [{ "wa_id": "5511…" }] }` ou `{ "user_id": "…" }` | | `GET /v1/groups/{id}/join-requests` · `POST …/approve` · `POST …/reject` | pedidos de entrada (`join_approval_mode: approval_required`); `{ "join_request_ids": [...] }` → `{ approved \| rejected, failed[] }` | | `DELETE /v1/groups/{id}` | apaga o grupo na Meta (chave `admin`) | ## Mensagens [Seção intitulada “Mensagens”](#mensagens) Mande com o mesmo `POST /v1/messages`, com o id do grupo em `to`: ```json { "connection_id": "conn_...", "to": "grp_...", "type": "text", "text": { "body": "Aula confirmada às 9h" } } ``` * Não há checagem de janela de 24 h: a Meta decide. * Grupo que não está `active` → `409` [`group_not_active`](/errors#group_not_active). * Tipo de conteúdo que a Meta não aceita em grupo → `422` [`group_message_type_not_supported`](/errors#group_message_type_not_supported). A conversa do grupo tem `kind: "group"`. Os eventos `message.*` trazem `group: { id, external_id, subject }` (ou `null` fora de grupo); numa mensagem recebida, o `contact` é o participante que escreveu. ## Limites [Seção intitulada “Limites”](#limites) | Limite | Valor | | ------------------------- | ------------------------------------------------------------------------------ | | Participantes por grupo | 8 (acima → `422` [`group_participant_limit`](/errors#group_participant_limit)) | | Grupos por número | 10.000 (o Messajo só avisa; a Meta decide) | | Participantes por remoção | 8 | ## Eventos [Seção intitulada “Eventos”](#eventos) | Tipo | Quando | | --------------------------------------- | ----------------------------------------------------------------------- | | `group.created` · `group.create_failed` | a Meta terminou de criar (ou não) | | `group.settings_updated` | assunto, descrição, foto ou modo de entrada mudaram | | `group.participants_updated` | alguém entrou, saiu ou foi removido (`joined[]`, `left[]`, `removed[]`) | | `group.join_requested` | chegou um pedido de entrada (`join_request`) | | `group.suspended` · `group.unsuspended` | a Meta suspendeu ou liberou o grupo | | `group.deleted` | o grupo foi apagado | Os eventos `group.*` não têm `sequence`. Filtre por família com `group.*` no [destino](/webhooks/events/). # Templates: criar e enviar > Crie templates do WhatsApp com POST /v1/templates, acompanhe a aprovação da Meta e envie com type template, com variáveis, cabeçalho de mídia e botão de URL. Template é uma mensagem com texto fixo e variáveis, **aprovada pela Meta antes de poder ser usada**. No WhatsApp ele é o único jeito de iniciar uma conversa ou de falar com o contato depois que a janela de 24 horas fechou (veja [Janelas de conversa](/start/concepts/#janelas-de-conversa)). Dentro da janela, você pode mandar [texto livre](/send/text/) ou qualquer outro tipo. Esta página cobre templates de qualquer categoria. Para códigos de verificação, veja [Templates de autenticação](/guides/authentication-templates/); para disparos em massa, [Campanhas](/guides/campaigns/). ## Criar [Seção intitulada “Criar”](#criar) `POST /v1/templates` cria o template na conta do WhatsApp da conexão e o envia para a revisão da Meta. Precisa de uma chave com a permissão `templates`. No painel: **Templates → Novo template**. | Campo | Regra | | ------------------ | ------------------------------------------------------------------------------------------------ | | `connection_id` | Opcional com chave de conexão (`mjc_…`); obrigatório com chave de organização (`mj_…`) | | `name` | Letras minúsculas, números e `_` | | `language` | Código da Meta, como `pt_BR`, `en_US` ou `es` | | `category` | `MARKETING`, `UTILITY` ou `AUTHENTICATION` | | `parameter_format` | Opcional: `POSITIONAL` (`{{1}}`) ou `NAMED` | | `components` | Lista com no máximo um de cada: `HEADER`, `BODY` (com `text`, obrigatório), `FOOTER` e `BUTTONS` | * `HEADER` aceita `format` `TEXT`, `IMAGE`, `VIDEO`, `DOCUMENT` ou `LOCATION`. * `BUTTONS` aceita botões `QUICK_REPLY`, `URL`, `PHONE_NUMBER`, `COPY_CODE`, `OTP`, `FLOW`, `CATALOG`, `MPM` e `VOICE_CALL`. * Os componentes seguem o formato de criação da Meta. Variáveis no texto precisam de um exemplo (`example`), como no corpo abaixo. * **Cabeçalho de mídia** (`IMAGE`, `VIDEO`, `DOCUMENT`) exige um arquivo de exemplo: `components.HEADER.example.header_handle`, o identificador devolvido pelo upload retomável da Meta. Sem ele a chamada volta `400` [`validation_failed`](/errors#validation_failed). No painel, o Messajo faz esse upload quando você escolhe o arquivo. Exemplo: corpo com duas variáveis, rodapé e um botão de resposta rápida. * cURL ```bash curl https://api.messajo.com/v1/templates \ -H "Authorization: Bearer $MESSAJO_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{ "connection_id": "conn_...", "name": "pedido_enviado", "language": "pt_BR", "category": "UTILITY", "components": [ { "type": "BODY", "text": "Olá {{1}}, seu pedido {{2}} saiu para entrega.", "example": { "body_text": [ [ "Ana", "12345" ] ] } }, { "type": "FOOTER", "text": "Obrigado por comprar com a gente" }, { "type": "BUTTONS", "buttons": [ { "type": "QUICK_REPLY", "text": "Falar com a loja" } ] } ] }' ``` * TypeScript ```ts import { Messajo } from "@messajo/sdk"; const messajo = new Messajo({ apiKey: process.env.MESSAJO_API_KEY! }); const template = await messajo.templates.create({ connection_id: "conn_...", name: "pedido_enviado", language: "pt_BR", category: "UTILITY", components: [ { type: "BODY", text: "Olá {{1}}, seu pedido {{2}} saiu para entrega.", example: { body_text: [ [ "Ana", "12345" ] ] } }, { type: "FOOTER", text: "Obrigado por comprar com a gente" }, { type: "BUTTONS", buttons: [ { type: "QUICK_REPLY", text: "Falar com a loja" } ] } ] }); ``` * n8n **Configurações do nó HTTP Request do n8n** * Método: `POST` * URL: `https://api.messajo.com/v1/templates` * Autenticação: Generic Credential Type, depois Header Auth. Nome: `Authorization`; Valor: `Bearer mj_...` * Cabeçalhos: ative Send Headers e adicione `Idempotency-Key` (um valor único por item) * Corpo: ative Send Body; Body Content Type: JSON; Specify Body: Using JSON ```json { "connection_id": "conn_...", "name": "pedido_enviado", "language": "pt_BR", "category": "UTILITY", "components": [ { "type": "BODY", "text": "Olá {{1}}, seu pedido {{2}} saiu para entrega.", "example": { "body_text": [ [ "Ana", "12345" ] ] } }, { "type": "FOOTER", "text": "Obrigado por comprar com a gente" }, { "type": "BUTTONS", "buttons": [ { "type": "QUICK_REPLY", "text": "Falar com a loja" } ] } ] } ``` Substitua mj\_... pela sua chave de API. A resposta é `201` com o template: `id` (`tpl_…`), `status`, `category`, `components` e `rejected_reason` quando houver recusa. ## Ciclo de vida [Seção intitulada “Ciclo de vida”](#ciclo-de-vida) Depois de criado, o template vai para a revisão da Meta. Cada mudança de status chega no evento [`template.status`](/webhooks/events/); consulte também `GET /v1/templates/{id}`. | Status | O que significa | | ---------- | -------------------------------------------------------------------------------- | | `PENDING` | Em revisão. Ainda não dá para enviar. | | `APPROVED` | Aprovado. Pode ser enviado. | | `REJECTED` | A Meta recusou; o motivo vem em `rejected_reason`. Edite e reenvie para revisão. | | `PAUSED` | A Meta pausou por baixa qualidade. Não envia até voltar. | | `DISABLED` | A Meta desativou. | Há ainda `IN_APPEAL`, `PENDING_DELETION`, `DELETED`, `ARCHIVED`, `LIMIT_EXCEEDED`, `LOCKED`, `FLAGGED` e `REINSTATED`, que vêm da Meta como estão. * **Listar e consultar:** `GET /v1/templates` (com filtros e paginação) e `GET /v1/templates/{id}`, com a permissão `read`. * **Editar:** `PATCH /v1/templates/{id}` troca `components` ou `category`. A Meta só deixa editar template `APPROVED`, `REJECTED` ou `PAUSED`, e um template aprovado não troca de categoria. * **Excluir:** `DELETE /v1/templates/{id}` exclui na Meta e no Messajo. * **Sincronizar:** o Messajo relê os templates da Meta todo dia. `POST /v1/templates/sync` faz a leitura na hora; o template que sumiu da Meta fica marcado como excluído. ## Enviar [Seção intitulada “Enviar”](#enviar) `POST /v1/messages` com `type: "template"`: | Campo | Regra | | --------------------- | ------------------------------------------------------------------------------------------------------ | | `template.name` | Nome do template, de 1 a 512 caracteres | | `template.language` | Código do idioma, como `pt_BR` | | `template.components` | Opcional. Valores das variáveis, **no formato de envio da Meta**: o Messajo repassa como você escreveu | Os campos comuns (`to`, `reply_to`, `typing`…) estão em [Campos comuns](/send/text/#campos-comuns). Template não depende da janela de 24 horas: sai a qualquer momento. ### Variáveis do corpo [Seção intitulada “Variáveis do corpo”](#variáveis-do-corpo) * cURL ```bash curl https://api.messajo.com/v1/messages \ -H "Authorization: Bearer $MESSAJO_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{ "connection_id": "conn_...", "to": "5511999999999", "type": "template", "template": { "name": "pedido_enviado", "language": "pt_BR", "components": [ { "type": "body", "parameters": [ { "type": "text", "text": "Ana" }, { "type": "text", "text": "12345" } ] } ] } }' ``` * TypeScript ```ts import { Messajo } from "@messajo/sdk"; const messajo = new Messajo({ apiKey: process.env.MESSAJO_API_KEY! }); const sent = await messajo.messages.send({ connection_id: "conn_...", to: "5511999999999", type: "template", template: { name: "pedido_enviado", language: "pt_BR", components: [ { type: "body", parameters: [ { type: "text", text: "Ana" }, { type: "text", text: "12345" } ] } ] } }); ``` * n8n **Configurações do nó HTTP Request do n8n** * Método: `POST` * URL: `https://api.messajo.com/v1/messages` * Autenticação: Generic Credential Type, depois Header Auth. Nome: `Authorization`; Valor: `Bearer mj_...` * Cabeçalhos: ative Send Headers e adicione `Idempotency-Key` (um valor único por item) * Corpo: ative Send Body; Body Content Type: JSON; Specify Body: Using JSON ```json { "connection_id": "conn_...", "to": "5511999999999", "type": "template", "template": { "name": "pedido_enviado", "language": "pt_BR", "components": [ { "type": "body", "parameters": [ { "type": "text", "text": "Ana" }, { "type": "text", "text": "12345" } ] } ] } } ``` Substitua mj\_... pela sua chave de API. ### Cabeçalho de imagem [Seção intitulada “Cabeçalho de imagem”](#cabeçalho-de-imagem) Para um template com cabeçalho de imagem, passe a imagem por link público. * cURL ```bash curl https://api.messajo.com/v1/messages \ -H "Authorization: Bearer $MESSAJO_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{ "connection_id": "conn_...", "to": "5511999999999", "type": "template", "template": { "name": "promo_da_semana", "language": "pt_BR", "components": [ { "type": "header", "parameters": [ { "type": "image", "image": { "link": "https://exemplo.com/promo.jpg" } } ] }, { "type": "body", "parameters": [ { "type": "text", "text": "Ana" } ] } ] } }' ``` * TypeScript ```ts import { Messajo } from "@messajo/sdk"; const messajo = new Messajo({ apiKey: process.env.MESSAJO_API_KEY! }); const sent = await messajo.messages.send({ connection_id: "conn_...", to: "5511999999999", type: "template", template: { name: "promo_da_semana", language: "pt_BR", components: [ { type: "header", parameters: [ { type: "image", image: { link: "https://exemplo.com/promo.jpg" } } ] }, { type: "body", parameters: [ { type: "text", text: "Ana" } ] } ] } }); ``` * n8n **Configurações do nó HTTP Request do n8n** * Método: `POST` * URL: `https://api.messajo.com/v1/messages` * Autenticação: Generic Credential Type, depois Header Auth. Nome: `Authorization`; Valor: `Bearer mj_...` * Cabeçalhos: ative Send Headers e adicione `Idempotency-Key` (um valor único por item) * Corpo: ative Send Body; Body Content Type: JSON; Specify Body: Using JSON ```json { "connection_id": "conn_...", "to": "5511999999999", "type": "template", "template": { "name": "promo_da_semana", "language": "pt_BR", "components": [ { "type": "header", "parameters": [ { "type": "image", "image": { "link": "https://exemplo.com/promo.jpg" } } ] }, { "type": "body", "parameters": [ { "type": "text", "text": "Ana" } ] } ] } } ``` Substitua mj\_... pela sua chave de API. ### Botão de URL com sufixo dinâmico [Seção intitulada “Botão de URL com sufixo dinâmico”](#botão-de-url-com-sufixo-dinâmico) Quando a URL do botão termina em `{{1}}`, mande o sufixo em um componente `button` com `sub_type: "url"`. `index` é a posição do botão, a partir de `"0"`. * cURL ```bash curl https://api.messajo.com/v1/messages \ -H "Authorization: Bearer $MESSAJO_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{ "connection_id": "conn_...", "to": "5511999999999", "type": "template", "template": { "name": "acompanhar_pedido", "language": "pt_BR", "components": [ { "type": "button", "sub_type": "url", "index": "0", "parameters": [ { "type": "text", "text": "12345" } ] } ] } }' ``` * TypeScript ```ts import { Messajo } from "@messajo/sdk"; const messajo = new Messajo({ apiKey: process.env.MESSAJO_API_KEY! }); const sent = await messajo.messages.send({ connection_id: "conn_...", to: "5511999999999", type: "template", template: { name: "acompanhar_pedido", language: "pt_BR", components: [ { type: "button", sub_type: "url", index: "0", parameters: [ { type: "text", text: "12345" } ] } ] } }); ``` * n8n **Configurações do nó HTTP Request do n8n** * Método: `POST` * URL: `https://api.messajo.com/v1/messages` * Autenticação: Generic Credential Type, depois Header Auth. Nome: `Authorization`; Valor: `Bearer mj_...` * Cabeçalhos: ative Send Headers e adicione `Idempotency-Key` (um valor único por item) * Corpo: ative Send Body; Body Content Type: JSON; Specify Body: Using JSON ```json { "connection_id": "conn_...", "to": "5511999999999", "type": "template", "template": { "name": "acompanhar_pedido", "language": "pt_BR", "components": [ { "type": "button", "sub_type": "url", "index": "0", "parameters": [ { "type": "text", "text": "12345" } ] } ] } } ``` Substitua mj\_... pela sua chave de API. A resposta é a mesma do envio de texto (`201`, `status: "queued"`); veja [Resposta](/send/text/#resposta). ## Custos [Seção intitulada “Custos”](#custos) A Meta cobra por mensagem de template, conforme a categoria. Veja [Custos da Meta](/guides/costs/). ## Erros [Seção intitulada “Erros”](#erros) | Erro | Quando | O que fazer | | ------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- | | `422` [`template_error`](/errors#template_error) | A Meta recusou o template ou os parâmetros (códigos 132000, 132001, 132005, 132007, 132012, 132015, 132016, 132068, 132069) | Leia `details[].message`: diz qual item falhou | | `404` [`template_not_found`](/errors#template_not_found) | O template não existe | Confira `name` e `language`; rode `POST /v1/templates/sync` | | `422` [`marketing_limit_reached`](/errors#marketing_limit_reached) | A Meta limitou marketing para esse contato (131049) | Não reenvie logo em seguida | | `429` [`meta_spam_rate_limited`](/errors#meta_spam_rate_limited) | Limite por spam (131048) | Nunca reenvie | | `402` [`meta_payment_required`](/errors#meta_payment_required) | Problema de pagamento na conta da Meta (131042) | Corrija a forma de pagamento | Mais passos em [Falhas de envio](/troubleshooting/send-failures/). # Migrar da Evolution API > Como trocar a Evolution API pelo Messajo e manter o número. Esta página mostra o que muda ao sair da Evolution API e como cada rota dela vira uma chamada do Messajo. As tabelas gerais de qualquer provedor estão em [Migrar de outro provedor](/operate/migrate/); aqui ficam só os pontos da Evolution API. ## O que muda no modelo [Seção intitulada “O que muda no modelo”](#o-que-muda-no-modelo) A Evolution API pareia um telefone, como o WhatsApp Web. O Messajo usa a API oficial da Meta. Na prática: | Na Evolution API | No Messajo | | --------------------------------- | -------------------------------------------------------------------------------------------------------------------- | | Ler o QR code | Cadastro oficial da Meta (Embedded Signup), pelo painel | | Instância | Conexão (`conn_…`) | | Mensagem livre a qualquer hora | Mensagem livre só dentro de 24 h do último contato da pessoa; fora disso, um [template aprovado](/guides/templates/) | | Contato que nunca falou com você | Exige opt-in: a pessoa precisa ter aceitado receber mensagens | | Sem cobrança por mensagem da Meta | A Meta cobra por mensagem de template, direto de você. Veja [Custos da Meta](/guides/costs/) | | Número pareado | Número oficial, com qualidade e limites medidos pela Meta | ## Manter o número [Seção intitulada “Manter o número”](#manter-o-número) Para não perder o atendimento no celular, conecte em **coexistência**: o app do WhatsApp Business continua funcionando e o Messajo importa os contatos e até 6 meses de histórico, uma única vez, na hora de conectar. * Exige o app WhatsApp Business 2.24.17 ou mais novo, com confirmação por QR code no app. * A vazão fica fixa em 20 mensagens por segundo. * Grupos não sincronizam na coexistência. Se você depende de grupos, veja [Grupos](/guides/groups/): eles pedem o modo só API. * Para volume maior ou para um número novo, use o modo **só API**. O passo a passo está em [Conectar o WhatsApp](/connect/whatsapp/); se algo travar, veja [Problemas na coexistência](/troubleshooting/coexistence/). ## Autenticação [Seção intitulada “Autenticação”](#autenticação) A Evolution API autentica com o cabeçalho `apikey` (global ou da instância) e identifica a instância pelo nome no caminho. No Messajo toda chamada leva `Authorization: Bearer `: * **chave de organização** (`mj_…`): enviada com `connection_id` no corpo; * **chave de conexão** (`mjc_…`): vale só para uma conexão e dispensa o `connection_id`. É a mais próxima de “uma chave por instância”. Veja [Tipos de chave](/api/authentication/#tipos-de-chave). ## Rotas lado a lado [Seção intitulada “Rotas lado a lado”](#rotas-lado-a-lado) Os caminhos da Evolution API vêm da [documentação da Evolution Foundation](https://docs.evolutionfoundation.com.br/llms.txt); todos recebem o nome da instância no final. | Rota na Evolution API | No Messajo | | --------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `POST /message/sendText/{instanceName}` | `POST /v1/messages` com `type: "text"`. Veja [Enviar texto](/send/text/) | | `POST /message/sendMedia/{instanceName}` (imagem, vídeo, documento e áudio) | `type: "image"`, `"video"`, `"document"` ou `"audio"`. Veja [Enviar imagem](/send/image/), [vídeo](/send/video/), [documento](/send/document/) e [áudio](/send/audio/) | | Enviar sticker (sem rota na documentação consultada) | `type: "sticker"`. Veja [Enviar figurinha](/send/sticker/) | | `POST /message/sendLocation/{instanceName}` | `type: "location"`. Veja [Enviar e pedir localização](/send/location/) | | `POST /message/sendContact/{instanceName}` | `type: "contacts"`. Veja [Enviar contato](/send/contacts/) | | `POST /message/sendButtons/{instanceName}` | `type: "interactive"`, botões de resposta. Veja [Enviar botões](/send/buttons/) | | `POST /message/sendList/{instanceName}` | `type: "interactive"`, lista. Veja [Enviar lista](/send/list/) | | `POST /message/sendReaction/{instanceName}` | `type: "reaction"`. Veja [Enviar reação](/send/reaction/) | | Opção de citar uma mensagem (`quoted`) | `reply_to` no corpo do envio | | `POST /chat/markMessageAsRead/{instanceName}` | `POST /v1/messages/{id}/read`. Veja [Marcar como lida](/send/mark-as-read/) | | Mídia por URL | `link` (URL pública) ou `media_id`, obtido com `POST /v1/media` (multipart) | ### Exemplo: enviar um texto [Seção intitulada “Exemplo: enviar um texto”](#exemplo-enviar-um-texto) O corpo do texto varia entre versões da Evolution API (`text` direto ou dentro de `textMessage`); confira o da sua instalação. * Evolution API ```bash curl https://SEU-SERVIDOR/message/sendText/minha-instancia \ -H "apikey: $EVOLUTION_APIKEY" \ -H "Content-Type: application/json" \ -d '{ "number": "5511999999999", "text": "Olá! Seu pedido saiu para entrega." }' ``` * Messajo cURL ```bash curl https://api.messajo.com/v1/messages \ -H "Authorization: Bearer $MESSAJO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "connection_id": "conn_...", "to": "5511999999999", "type": "text", "text": { "body": "Olá! Seu pedido saiu para entrega." } }' ``` * Messajo TypeScript ```ts import { Messajo } from "@messajo/sdk"; const messajo = new Messajo({ apiKey: process.env.MESSAJO_API_KEY! }); await messajo.messages.send({ connection_id: "conn_...", to: "5511999999999", type: "text", text: { body: "Olá! Seu pedido saiu para entrega." }, }); ``` ### Formato do destinatário [Seção intitulada “Formato do destinatário”](#formato-do-destinatário) O Messajo aceita o telefone com DDI, só dígitos (por exemplo `5511999999999`), ou um contato `ctc_…`. Sufixos como `@s.whatsapp.net` não existem; qualquer caractere que não seja dígito é descartado. ## Webhooks [Seção intitulada “Webhooks”](#webhooks) | Na Evolution API | No Messajo | | ------------------------------------------- | ---------------------------------------------- | | Evento de mensagem recebida | Evento `message.received` | | Evento de atualização de status da mensagem | Evento `message.status` | | Evento de estado da conexão da instância | Eventos `connection.*` | | Evento de QR code | Sem equivalente: a conexão é feita pelo painel | Você cadastra um [destino de eventos](/webhooks/events/) e o Messajo assina cada entrega com `Messajo-Signature` (HMAC-SHA256). Verifique a assinatura no seu servidor, como em [Verificar a assinatura](/webhooks/verify-signature/). Na coexistência, as mensagens enviadas pelo app do celular chegam como `message.echo`. ## O que não tem equivalente ou funciona diferente [Seção intitulada “O que não tem equivalente ou funciona diferente”](#o-que-não-tem-equivalente-ou-funciona-diferente) * **Enviar a qualquer pessoa, a qualquer hora.** No Messajo vale a janela de 24 h e, fora dela, só template aprovado. Veja [Limites](/api/limits/#janelas). * **Grupos.** Na coexistência não sincronizam; para usar grupos, o modo é só API. Veja [Grupos](/guides/groups/). ## Checklist de virada [Seção intitulada “Checklist de virada”](#checklist-de-virada) * [ ] Conexão criada (coexistência ou só API) e **Ativa** no painel. * [ ] Templates criados e aprovados para as mensagens que você manda fora da janela. * [ ] Destinos de eventos criados, com a assinatura verificada no seu servidor. * [ ] Uma chave de API por integração, com só as permissões e conexões necessárias. * [ ] Teste de ponta a ponta com um número seu: enviar, receber, status e template. * [ ] Integração trocada de `apikey` para `Authorization` e de formato de corpo, e o destinatário sem sufixos. * [ ] Instância da Evolution API desligada **só depois** de a conexão oficial estar ativa e testada, e o aparelho pareado por QR code desconectado dela. # Migrar da Z-API > Como trocar a Z-API pelo Messajo e manter o número. Esta página mostra o que muda ao sair da Z-API e como cada operação dela vira uma chamada do Messajo. As tabelas gerais de qualquer provedor (Cloud API, 360dialog, Twilio e APIs não oficiais) estão em [Migrar de outro provedor](/operate/migrate/); aqui ficam só os pontos da Z-API. ## O que muda no modelo [Seção intitulada “O que muda no modelo”](#o-que-muda-no-modelo) A Z-API pareia um telefone, como o WhatsApp Web. O Messajo usa a API oficial da Meta. Na prática: | Na Z-API | No Messajo | | --------------------------------- | -------------------------------------------------------------------------------------------------------------------- | | Ler o QR code | Cadastro oficial da Meta (Embedded Signup), pelo painel | | Instância | Conexão (`conn_…`) | | Mensagem livre a qualquer hora | Mensagem livre só dentro de 24 h do último contato da pessoa; fora disso, um [template aprovado](/guides/templates/) | | Contato que nunca falou com você | Exige opt-in: a pessoa precisa ter aceitado receber mensagens | | Sem cobrança por mensagem da Meta | A Meta cobra por mensagem de template, direto de você. Veja [Custos da Meta](/guides/costs/) | | Número pareado | Número oficial, com qualidade e limites medidos pela Meta | ## Manter o número [Seção intitulada “Manter o número”](#manter-o-número) Para não perder o atendimento no celular, conecte em **coexistência**: o app do WhatsApp Business continua funcionando e o Messajo importa os contatos e até 6 meses de histórico, uma única vez, na hora de conectar. * Exige o app WhatsApp Business 2.24.17 ou mais novo, com confirmação por QR code no app. * A vazão fica fixa em 20 mensagens por segundo. * Grupos não sincronizam na coexistência. Se você depende de grupos, veja [Grupos](/guides/groups/): eles pedem o modo só API. * Para volume maior ou para um número novo, use o modo **só API**. O passo a passo está em [Conectar o WhatsApp](/connect/whatsapp/); se algo travar, veja [Problemas na coexistência](/troubleshooting/coexistence/). ## Autenticação [Seção intitulada “Autenticação”](#autenticação) A Z-API identifica a instância pelo ID e pelo token dela, que aparecem no painel da Z-API. No Messajo, toda chamada leva `Authorization: Bearer `: * **chave de organização** (`mj_…`): enviada com `connection_id` no corpo; * **chave de conexão** (`mjc_…`): vale só para uma conexão e dispensa o `connection_id`. É a mais próxima de “um token por instância”. Veja [Tipos de chave](/api/authentication/#tipos-de-chave). ## Operações lado a lado [Seção intitulada “Operações lado a lado”](#operações-lado-a-lado) Os caminhos da Z-API não estão aqui: confira-os na [documentação da Z-API](https://developer.z-api.io/). A coluna da esquerda nomeia a operação. | Operação na Z-API | No Messajo | | ------------------------------ | ------------------------------------------------------------------------------- | | Enviar texto | `POST /v1/messages` com `type: "text"`. Veja [Enviar texto](/send/text/) | | Enviar imagem | `type: "image"`. Veja [Enviar imagem](/send/image/) | | Enviar vídeo | `type: "video"`. Veja [Enviar vídeo](/send/video/) | | Enviar áudio | `type: "audio"`. Veja [Enviar áudio](/send/audio/) | | Enviar documento | `type: "document"`. Veja [Enviar documento](/send/document/) | | Enviar sticker | `type: "sticker"`. Veja [Enviar figurinha](/send/sticker/) | | Enviar localização | `type: "location"`. Veja [Enviar e pedir localização](/send/location/) | | Enviar contato | `type: "contacts"`. Veja [Enviar contato](/send/contacts/) | | Enviar botões | `type: "interactive"`, botões de resposta. Veja [Enviar botões](/send/buttons/) | | Enviar lista de opções | `type: "interactive"`, lista. Veja [Enviar lista](/send/list/) | | Reagir a uma mensagem | `type: "reaction"`. Veja [Enviar reação](/send/reaction/) | | Responder citando uma mensagem | `reply_to` no corpo do envio | | Marcar como lida | `POST /v1/messages/{id}/read`. Veja [Marcar como lida](/send/mark-as-read/) | | Enviar arquivo por URL | `link` (URL pública) ou `media_id`, obtido com `POST /v1/media` (multipart) | O texto da Z-API usa os campos `phone` e `message` ([Enviar texto simples](https://developer.z-api.io/message/send-text)). No Messajo eles viram `to` e `text.body`. ### Formato do destinatário [Seção intitulada “Formato do destinatário”](#formato-do-destinatário) O Messajo aceita o telefone com DDI, só dígitos (por exemplo `5511999999999`), ou um contato `ctc_…`. Sufixos como `@c.us` não existem; qualquer caractere que não seja dígito é descartado. ## Webhooks [Seção intitulada “Webhooks”](#webhooks) | Na Z-API | No Messajo | | ------------------------------------------------------- | ---------------------------------------------- | | Retorno de mensagem recebida | Evento `message.received` | | Retorno de status da mensagem (enviada, entregue, lida) | Evento `message.status` | | Retorno de estado da instância | Eventos `connection.*` | | Retorno do QR code | Sem equivalente: a conexão é feita pelo painel | Você cadastra um [destino de eventos](/webhooks/events/) e o Messajo assina cada entrega com `Messajo-Signature` (HMAC-SHA256). Verifique a assinatura no seu servidor, como em [Verificar a assinatura](/webhooks/verify-signature/). Na coexistência, as mensagens enviadas pelo app do celular chegam como `message.echo`. ## O que não tem equivalente ou funciona diferente [Seção intitulada “O que não tem equivalente ou funciona diferente”](#o-que-não-tem-equivalente-ou-funciona-diferente) * **Enviar a qualquer pessoa, a qualquer hora.** No Messajo vale a janela de 24 h e, fora dela, só template aprovado. Veja [Limites](/api/limits/#janelas). * **Grupos.** Na coexistência não sincronizam; para usar grupos, o modo é só API. Veja [Grupos](/guides/groups/). ## Checklist de virada [Seção intitulada “Checklist de virada”](#checklist-de-virada) * [ ] Conexão criada (coexistência ou só API) e **Ativa** no painel. * [ ] Templates criados e aprovados para as mensagens que você manda fora da janela. * [ ] Destinos de eventos criados, com a assinatura verificada no seu servidor. * [ ] Uma chave de API por integração, com só as permissões e conexões necessárias. * [ ] Teste de ponta a ponta com um número seu: enviar, receber, status e template. * [ ] Integração trocada de `Authorization` e de formato de corpo, e o destinatário sem sufixos. * [ ] Instância da Z-API desligada **só depois** de a conexão oficial estar ativa e testada, e o aparelho pareado por QR code desconectado dela. # Dados e privacidade > Retenção do conteúdo, o que o expurgo diário apaga, exportação em ZIP, exclusão do conteúdo ou da organização e os prazos fixos. Tudo fica em **Configurações → Dados e privacidade**. O Messajo guarda o conteúdo das conversas só pelo prazo que a organização escolher, e o dono pode exportar ou apagar tudo quando quiser (LGPD e GDPR). ## Retenção [Seção intitulada “Retenção”](#retenção) O dono ou um admin escolhe por quantos dias o **conteúdo** fica guardado: de 7 até o teto da instância (`RETENTION_MAX_DAYS`, 730 por padrão). Sem escolha, valem 90 dias (`RETENTION_DEFAULT_DAYS`). Fora dessa faixa, a API responde `422` [`retention_out_of_range`](/errors#retention_out_of_range). * O prazo conta da **gravação** no Messajo, não da data original da mensagem. O histórico de 6 meses importado na coexistência é gravado no dia da importação e conta a partir dali. * Antes de salvar um prazo menor, o painel mostra quantas mensagens e arquivos saem no próximo expurgo e a partir de que data o conteúdo fica. * Diminuir é irreversível: o que passou do prazo some no expurgo seguinte. ## O que o expurgo diário apaga [Seção intitulada “O que o expurgo diário apaga”](#o-que-o-expurgo-diário-apaga) O expurgo roda todo dia às 02:40 UTC. Para cada organização, sai o que é mais velho que o prazo: | Sai | Regra | | ---------------------------------------------------------------------- | ------------------------------------------------------ | | Mensagens e os arquivos de mídia delas | prazo da organização | | Conversas sem mensagem restante e contatos sem conversa | prazo da organização | | Destinatários e importações de campanhas terminadas | prazo da organização (a campanha fica, com os números) | | Comentários, insights de stories e publicações terminadas do Instagram | prazo da organização | | Eventos, entregas e logs de requisição da API | o menor entre 30 dias e o prazo | Ficam: organização, membros, conexões, chaves de API, destinos, templates e auditoria. Mídia de cabeçalho usada por uma campanha ainda ativa só sai quando a campanha termina. Se o armazenamento falhar ao apagar um arquivo, ele fica marcado e o expurgo seguinte tenta de novo: nada fica órfão. ## Prazos fixos [Seção intitulada “Prazos fixos”](#prazos-fixos) Estes não mudam com a retenção: | Dado | Prazo | | ------------------------------------------------------------ | -------- | | Evento bruto recebido da Meta | 7 dias | | Eventos de cadastro das conexões | 90 dias | | Auditoria | 365 dias | | Pedidos de exportação e exclusão (o registro, não o arquivo) | 1 ano | | Arquivo da exportação | 7 dias | ## Exportar [Seção intitulada “Exportar”](#exportar) Só o **dono**, com o 2FA ligado. 1. Em **Exportar dados**, marque se quer os arquivos de mídia (o ZIP fica bem maior) e clique em **Pedir exportação**. 2. O Messajo monta o ZIP em segundo plano e avisa por e-mail quando estiver pronto. O e-mail leva para o painel, nunca para o arquivo. 3. Em **Pedidos**, clique em **Baixar**. O link vale 15 minutos e cada download fica na auditoria. O arquivo fica disponível por 7 dias. Depois disso, `410` [`data_export_expired`](/errors#data_export_expired). Até 3 exportações por 24 horas (`429` [`data_request_limit`](/errors#data_request_limit)) e uma de cada tipo por vez (`409` [`data_request_in_progress`](/errors#data_request_in_progress)). O ZIP traz `manifest.json` e um arquivo por tipo de dado, em NDJSON (um objeto JSON por linha): organização, membros, convites, conexões, contatos e identidades, conversas, mensagens (`messages/AAAA-MM.ndjson`), mídias (e `media/` com os arquivos, se pedido), templates, campanhas e destinatários, destinos, entregas, eventos, chaves de API, auditoria e dados do Instagram. **Nunca** entram tokens, segredos, hashes de senha ou de chave, códigos de 2FA nem sessões. ## Apagar o conteúdo [Seção intitulada “Apagar o conteúdo”](#apagar-o-conteúdo) **Apagar conteúdo** remove mensagens, mídias, contatos, conversas, campanhas, eventos, entregas e logs. Ficam a organização, os membros, as conexões, as chaves, os destinos, os templates e a auditoria. Para confirmar, digite o slug da organização. Não dá para desfazer; um e-mail avisa quando terminar. ## Excluir a organização [Seção intitulada “Excluir a organização”](#excluir-a-organização) Em **Configurações → Organização → Excluir organização**, o dono confirma com o slug. A exclusão roda em segundo plano: 1. desconecta cada conexão da Meta; 2. apaga todo o conteúdo e os arquivos; 3. apaga a organização, os membros, as chaves e o resto. O painel mostra **Exclusão em andamento** até o fim, e quem pediu recebe um e-mail. Se um passo falhar, o pedido fica `failed` e **Tentar de novo** continua do passo que parou. O registro do pedido fica guardado por 1 ano como prova da exclusão. # Migrar de outro provedor > O que muda ao trazer sua integração de outro provedor para o Messajo. ## Quanto muda [Seção intitulada “Quanto muda”](#quanto-muda) O esforço depende de onde você vem. Quem já usa a API oficial troca pouco; quem vem de uma API não oficial troca o modelo. | Você vem de | Envio | Webhooks | Esforço | | ------------------------------ | ------------------------------------------------------------------------------------------------- | ------------------------------------------------- | ------- | | Cloud API direto | Mesmo corpo na camada espelho; troca a URL base e o token | Formato `meta`: o mesmo `value` que você já trata | Pequeno | | 360dialog | Mesmo corpo na camada espelho; troca a URL, o `D360-API-KEY` e põe o `phone_number_id` no caminho | Formato `meta` | Pequeno | | Twilio | Reescrever: camada simples ou espelho | Status viram `message.status` | Médio | | Evolution, WAHA, Z-API, uazapi | Reescrever e adotar as regras da Meta (janela, templates, opt-in) | Formato `normalized` ou `meta` | Grande | As duas camadas da API (espelho da Meta e simples) usam a mesma chave. Veja [Conceitos](/start/concepts/). ## Vindo da Cloud API ou da 360dialog [Seção intitulada “Vindo da Cloud API ou da 360dialog”](#vindo-da-cloud-api-ou-da-360dialog) A camada espelho recebe o **mesmo corpo da Meta**, campo por campo. O código que monta a mensagem fica igual; mudam a URL e a autenticação. | | Antes | No Messajo | | ------------ | --------------------------------------------------------------------- | --------------------------------------------------------------------- | | Cloud API | `POST https://graph.facebook.com//{phone_number_id}/messages` | `POST https://api.messajo.com/v1/whatsapp/{phone_number_id}/messages` | | 360dialog | `POST https://waba-v2.360dialog.io/messages` | `POST https://api.messajo.com/v1/whatsapp/{phone_number_id}/messages` | | Autenticação | `Authorization: Bearer ` ou `D360-API-KEY: ` | `Authorization: Bearer mj_...` | ```bash curl -X POST "https://api.messajo.com/v1/whatsapp/$PHONE_NUMBER_ID/messages" \ -H "Authorization: Bearer $MESSAJO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "messaging_product": "whatsapp", "to": "5511999999999", "type": "text", "text": { "body": "Olá do Messajo" } }' ``` * Na 360dialog a chave já diz qual é o número. No Messajo a chave vale para a organização, então o `phone_number_id` vai no caminho. Ele aparece na página da conexão. * O cabeçalho `D360-API-KEY` sai; entra `Authorization: Bearer` com uma [chave de API](/api/authentication/) com permissão `send`. * O token da Meta não fica mais no seu código: o Messajo guarda o token da conexão, cifrado. * A resposta e os erros da Meta voltam como vieram, com o mesmo corpo `{ "error": { "code", … } }` que o seu código já trata. Só os erros do próprio Messajo (chave, permissão, limite) usam o [formato único](/errors/). * Nos webhooks, escolha o formato `meta` no destino para receber o mesmo `value` que a Meta manda, dentro do envelope do Messajo. Veja [Eventos](/webhooks/events/). ### O que o espelho aceita [Seção intitulada “O que o espelho aceita”](#o-que-o-espelho-aceita) O caminho é `/v1/whatsapp/{id}/`, com o método, a query e o corpo da Meta. A versão da Graph API é a do servidor. | `{id}` | Vai para | Exemplo | | ------------------------------------------------- | -------------------- | ------------------------------------------------------------------------------------------------- | | `phone_number_id` de uma conexão sua | o número | `POST /v1/whatsapp/{phone_number_id}/messages`, `GET …/whatsapp_business_profile`, `POST …/media` | | `waba_id` (conta de mensagens) de uma conexão sua | a conta | `GET /v1/whatsapp/{waba_id}/message_templates` | | `phone_number_id` + `nodes/{node_id}` | um nó avulso da Meta | `GET /v1/whatsapp/{phone_number_id}/nodes/{media_id}`, `DELETE …/nodes/{template_id}` | O `waba_id` aparece na página da conexão, em **Conta de mensagens (WABA)**. Nós avulsos (mídia, template por id) passam pelo número, para o Messajo saber de qual conexão é o pedido. * **Permissão da chave:** `POST …/messages` pede `send`; `message_templates` e nós de template pedem `templates`; outros `GET`, `read`; outras alterações, `admin`. Chave presa a algumas conexões só alcança essas. * **Bloqueados** com `403` [`mirror_path_blocked`](/errors#mirror_path_blocked), porque derrubam a conexão: `register`, `deregister`, `request_code`, `verify_code`, `smb_app_data`, `DELETE …/subscribed_apps` e `POST …/subscribed_apps` com `override_callback_uri`. * **Envio:** `POST …/messages` passa pelo mesmo limite por número da camada simples ([Envio por número](/api/limits#envio-por-n%C3%BAmero)), grava a mensagem nos logs, emite `message.sent` e devolve o id do Messajo no cabeçalho `X-Messajo-Message-Id`. O Messajo não repete o envio quando a Meta falha. * **Resposta:** status, corpo e `content-type` da Meta, mais `X-Request-Id`. O `Authorization` que você manda nunca segue para a Meta. ## Vindo do Twilio [Seção intitulada “Vindo do Twilio”](#vindo-do-twilio) O Twilio tem formato próprio (`From`, `To` e `Body` com o prefixo `whatsapp:`, em formulário), então a chamada de envio é reescrita: * **camada simples** (`POST /v1/messages`), para texto, mídia, template e botões com o mesmo formato nos 3 canais; * **camada espelho**, para usar qualquer recurso da Meta com o corpo dela. Os status do Twilio (`queued`, `sent`, `delivered`, `read`, `failed`) chegam como o evento `message.status`, e as mensagens recebidas como `message.received`. Troque o `StatusCallback` e o webhook de entrada por um [destino de eventos](/webhooks/events/) e passe a [verificar a assinatura](/webhooks/verify-signature/) do Messajo no lugar da `X-Twilio-Signature`. Os templates aprovados ficam na sua conta da Meta: sincronize ou recrie no Messajo. ## Vindo de API não oficial [Seção intitulada “Vindo de API não oficial”](#vindo-de-api-não-oficial) Evolution, WAHA, Z-API e uazapi simulam um celular. O Messajo usa a API oficial da Meta, e isso muda o modelo: | Na API não oficial | No Messajo | | -------------------------------------------------- | ----------------------------------------------------------- | | Ler o QR code | Cadastro oficial da Meta (Embedded Signup), pelo painel | | Instância | Conexão | | Mandar qualquer mensagem a qualquer hora | Fora da janela de 24 h, só **template aprovado** | | Lista comprada ou contato que nunca falou com você | **Opt-in**: a pessoa precisa ter aceitado receber mensagens | | Sem custo por mensagem | A Meta cobra por mensagem de template, direto de você | | Risco de bloqueio do número | Número oficial, com qualidade e limite medidos pela Meta | Para não perder o atendimento no celular, conecte em **coexistência**: o app do WhatsApp Business continua funcionando e o Messajo traz os contatos e até 6 meses de histórico, uma única vez, na hora de conectar. Grupos não sincronizam na coexistência. Veja [Conectar o WhatsApp](/connect/whatsapp/). Desligue a API antiga só depois que a conexão oficial estiver ativa e testada, e desconecte dela o aparelho pareado pelo QR code. ## O número já está em outro parceiro [Seção intitulada “O número já está em outro parceiro”](#o-número-já-está-em-outro-parceiro) Depende do modo: * **Só API**: no novo modelo de conta da Meta, o número pode ter vários parceiros ao mesmo tempo. Conecte pelo Messajo sem tirar do parceiro atual, migre aos poucos e desligue o antigo quando terminar. Veja o [guia da Meta sobre o novo modelo de conta](https://developers.facebook.com/documentation/business-messaging/whatsapp/account-model-evolution/onboarding/). * **Coexistência**: um parceiro por vez. Desconecte no app do celular e conecte de novo pelo Messajo, como em [Trocar de parceiro na coexistência](/connect/whatsapp/#trocar-de-parceiro-na-coexist%C3%AAncia). ## Checklist de virada [Seção intitulada “Checklist de virada”](#checklist-de-virada) * [ ] Templates sincronizados ou recriados no Messajo, e aprovados. * [ ] Destinos de eventos criados, com a assinatura verificada no seu servidor. * [ ] Uma chave de API por integração, com só as permissões e conexões necessárias. * [ ] Um teste de ponta a ponta com um número seu: enviar, receber, status e template. * [ ] Integração antiga desligada só depois do teste, e o número desconectado do provedor antigo, se for o caso. # Notificações > Como o Messajo avisa a sua equipe: sino, e-mail, quem recebe cada aviso, regras da organização, preferências de cada pessoa e banners. O Messajo avisa a sua equipe quando algo precisa de atenção: uma conexão caiu, um template foi reprovado, um destino foi pausado, uma campanha parou. Cada aviso aparece no **sino** do painel e, quando o tipo pede, também chega por **e-mail**. ## Sino e página [Seção intitulada “Sino e página”](#sino-e-página) O sino fica no topo do painel e mostra o número de avisos não lidos e os 20 mais recentes. Em cada aviso você pode marcar como lido ou não lido e limpar. **Ver todas** abre a página `Notificações`, com paginação, filtros por grupo, nível e leitura, seleção em massa e **Limpar todas**. O painel atualiza a cada 30 segundos e quando a aba volta ao foco. O seletor de organização mostra quantos avisos não lidos cada organização tem. ## Canais e níveis [Seção intitulada “Canais e níveis”](#canais-e-níveis) * **Canais:** sino (`inbox`) e e-mail (`email`). * **Níveis:** crítico (precisa de ação agora), atenção e informativo. O texto do aviso sai no idioma de quem recebe. ## Quem recebe [Seção intitulada “Quem recebe”](#quem-recebe) A decisão tem quatro camadas, nesta ordem: 1. **Padrão do tipo**, por papel (tabela abaixo). 2. **Regra da organização** em `Configurações › Avisos`: dono e admin ligam ou desligam sino e e-mail por tipo e por papel. 3. **Preferência de cada pessoa** em `Minha conta › Avisos`: por organização, tipo e canal. Dá para voltar ao padrão. 4. **Avisos obrigatórios** não mudam por regra nem por preferência: segurança da conta (troca de senha, 2FA, e-mail, papel), exclusão da organização e pronto do export de dados chegam sempre. ## Tipos de aviso [Seção intitulada “Tipos de aviso”](#tipos-de-aviso) | Tipo | Grupo | Nível | Quem recebe por padrão | Obrigatório | | ----------------------------------------------------- | ----------------- | ----------- | ----------------------------------------------------------------------------------------------- | ----------- | | `connection.disconnected` | `connection` | crítico | Dono: sino + e-mail; Admin: sino + e-mail; Dev: sino | | | `connection.needs_reconnect` | `connection` | crítico | Dono: sino + e-mail; Admin: sino + e-mail; Dev: sino | | | `connection.restricted` | `connection` | crítico | Dono: sino + e-mail; Admin: sino + e-mail; Dev: sino | | | `connection.unrestricted` | `connection` | informativo | Dono: sino + e-mail; Admin: sino + e-mail; Dev: sino | | | `connection.banned` | `connection` | crítico | Dono: sino + e-mail; Admin: sino + e-mail; Dev: sino | | | `connection.reinstated` | `connection` | informativo | Dono: sino + e-mail; Admin: sino + e-mail; Dev: sino | | | `connection.scheduled_for_disable` | `connection` | crítico | Dono: sino + e-mail; Admin: sino + e-mail; Dev: sino | | | `connection.quality_changed` | `connection` | atenção | Dono: sino + e-mail; Admin: sino + e-mail; Dev: sino | | | `connection.messaging_limit_changed` | `connection` | informativo | Dono: sino; Admin: sino | | | `connection.display_name_reviewed` | `connection` | informativo | Dono: sino + e-mail; Admin: sino + e-mail | | | `connection.account_review` | `connection` | atenção | Dono: sino + e-mail; Admin: sino + e-mail | | | `connection.account_alert` | `connection` | atenção | Dono: sino + e-mail; Admin: sino + e-mail | | | `connection.capability_changed` (ainda sem emissor) | `connection` | informativo | Dono: sino; Admin: sino | | | `connection.coex_unlinked` | `connection` | crítico | Dono: sino + e-mail; Admin: sino + e-mail; Dev: sino | | | `connection.history_sync_stalled` | `connection` | atenção | Dono: sino; Admin: sino | | | `connection.token_expiring` | `connection` | atenção | Dono: sino + e-mail; Admin: sino + e-mail | | | `connection.page_role_lost` | `connection` | crítico | Dono: sino + e-mail; Admin: sino + e-mail | | | `connection.pin_required` | `connection` | atenção | Dono: sino + e-mail; Admin: sino + e-mail | | | `connection.created` | `connection` | informativo | Dono: sino; Admin: sino | | | `connection.reconnected` | `connection` | informativo | Dono: sino; Admin: sino | | | `template.approved` | `template` | informativo | Dono: sino; Admin: sino; Dev: sino | | | `template.rejected` | `template` | atenção | Dono: sino + e-mail; Admin: sino + e-mail; Dev: sino + e-mail | | | `template.paused` | `template` | crítico | Dono: sino + e-mail; Admin: sino + e-mail; Dev: sino + e-mail | | | `template.disabled` | `template` | crítico | Dono: sino + e-mail; Admin: sino + e-mail; Dev: sino + e-mail | | | `template.quality_changed` (ainda sem emissor) | `template` | atenção | Dono: sino; Admin: sino; Dev: sino | | | `template.category_changed` (ainda sem emissor) | `template` | atenção | Dono: sino + e-mail; Admin: sino + e-mail; Dev: sino + e-mail | | | `template.components_changed` (ainda sem emissor) | `template` | informativo | Dono: sino; Admin: sino; Dev: sino | | | `destination.paused` | `delivery` | crítico | Dono: sino + e-mail; Admin: sino + e-mail; Dev: sino + e-mail | | | `destination.failure_rate_high` (ainda sem emissor) | `delivery` | atenção | Dono: sino; Admin: sino; Dev: sino | | | `destination.secret_rotated` | `delivery` | informativo | Dono: sino; Admin: sino | | | `flow.endpoint_unhealthy` | `flow` | crítico | Dono: sino + e-mail; Admin: sino + e-mail; Dev: sino + e-mail | | | `flow.status_changed` | `flow` | informativo | Dono: sino; Admin: sino; Dev: sino | | | `campaign.completed` | `campaign` | informativo | Dono: sino; Admin: sino; Dev: sino | | | `campaign.auto_paused` | `campaign` | crítico | Dono: sino + e-mail; Admin: sino + e-mail; Dev: sino + e-mail; quem o aviso cita: sino + e-mail | | | `campaign.paused_spend_cap` (ainda sem emissor) | `campaign` | crítico | Dono: sino + e-mail; Admin: sino + e-mail; Dev: sino | | | `cost.threshold_reached` (ainda sem emissor) | `cost` | atenção | Dono: sino + e-mail; Admin: sino + e-mail | | | `cost.reconciliation_diff` (ainda sem emissor) | `cost` | informativo | Dono: sino; Admin: sino | | | `group.suspended` | `groups_commerce` | atenção | Dono: sino; Admin: sino; Dev: sino | | | `order.received` | `groups_commerce` | informativo | ninguém | | | `publication.failed` | `publication` | atenção | Dono: sino; Admin: sino; Dev: sino | | | `org.standing_changed` (ainda sem emissor) | `org` | crítico | Dono: sino + e-mail; Admin: sino; Dev: sino; Leitura: sino | sim | | `org.deletion_scheduled` | `org` | crítico | Dono: sino + e-mail; Admin: sino + e-mail | sim | | `org.deletion_canceled` | `org` | informativo | Dono: sino + e-mail; Admin: sino + e-mail | sim | | `billing.payment_failed` | `org` | crítico | Dono: sino + e-mail | sim | | `billing.deletion_warning` | `org` | atenção | Dono: sino + e-mail | sim | | `org.member_joined` | `org` | informativo | Dono: sino; Admin: sino | | | `org.member_left` | `org` | informativo | Dono: sino; Admin: sino | | | `org.api_keys_orphaned` | `org` | atenção | Dono: sino + e-mail; Admin: sino + e-mail | | | `org.api_key_expiring` | `org` | atenção | Dono: sino + e-mail; Admin: sino + e-mail; quem o aviso cita: sino + e-mail | | | `org.data_export_ready` | `org` | informativo | quem o aviso cita: sino + e-mail | sim | | `org.retention_purged` (ainda sem emissor) | `org` | informativo | Dono: sino; Admin: sino | | | `security.password_changed` | `security` | crítico | quem o aviso cita: sino + e-mail | sim | | `security.two_factor_changed` | `security` | crítico | quem o aviso cita: sino + e-mail | sim | | `security.two_factor_reset` | `security` | crítico | quem o aviso cita: sino + e-mail | sim | | `security.email_changed` | `security` | crítico | quem o aviso cita: sino + e-mail | sim | | `security.new_device_login` (ainda sem emissor) | `security` | crítico | quem o aviso cita: sino + e-mail | sim | | `security.role_changed` | `security` | crítico | quem o aviso cita: sino + e-mail | sim | | `security.removed_from_org` | `security` | crítico | quem o aviso cita: sino + e-mail | sim | | `instance.meta_signature_failing` (ainda sem emissor) | `instance` | crítico | quem o aviso cita: sino + e-mail | sim | | `instance.queue_stalled` (ainda sem emissor) | `instance` | crítico | quem o aviso cita: sino + e-mail | sim | | `instance.media_storage_down` (ainda sem emissor) | `instance` | crítico | quem o aviso cita: sino + e-mail | sim | | `instance.rate_card_sync_failed` | `instance` | crítico | super-admins da instância: sino + e-mail | sim | Os tipos marcados como “ainda sem emissor” já existem no catálogo e na matriz, mas nenhum evento os dispara nesta versão. ## Banners [Seção intitulada “Banners”](#banners) Banner é **estado**, não aviso: aparece no topo do painel enquanto a condição vale e some sozinho quando ela passa. Hoje existem três: conexões que precisam de atenção (fora de `active`), exclusão da organização em andamento e conexões desconectadas por falta de pagamento depois que a organização volta ao normal (`connections_reconnect`, pede reconectar). ## Retenção e anti-spam [Seção intitulada “Retenção e anti-spam”](#retenção-e-anti-spam) Os avisos ficam **90 dias**; depois um job diário apaga. Para não encher o sino, um mesmo assunto (por exemplo, a mesma conexão caindo pelo mesmo motivo) não repete aviso por **6 horas**. # Segurança > Resumo público do modelo de ameaças do Messajo, como cada dado sensível é guardado e como reportar uma vulnerabilidade. Esta página resume a revisão de segurança do `1.0.0`: as fronteiras do sistema, os controles de cada uma e como os dados sensíveis são guardados. A revisão segue o [OWASP API Security Top 10 (2023)](https://owasp.org/API-Security/editions/2023/en/0x11-t10/) e uma análise STRIDE por fronteira. ## Fronteiras e controles [Seção intitulada “Fronteiras e controles”](#fronteiras-e-controles) | Fronteira | Controles | | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Meta → webhooks de entrada | assinatura `X-Hub-Signature-256` conferida em tempo constante sobre o corpo cru; corpo até 5 MiB; deduplicação do corpo bruto; canal sem credencial responde `503` | | Meta → endpoint de Flows → seu handler | assinatura da Meta, limite de falhas por IP e de trocas por Flow, decifragem com a chave da conta; o handler recebe o pedido assinado com `Messajo-Signature`, só em `https` público | | Sua aplicação → `/v1` e WebSocket | chave de API com permissões e escopo de conexões; limite por chave e por organização; corpo com teto por rota; campo desconhecido recusado; toda leitura filtra pela organização da chave | | Navegador → painel e páginas públicas | sessão com cookie `HttpOnly`, 2FA obrigatório para dono e admin, conferência de `Origin` nas escritas, CSP e cabeçalhos de segurança; páginas públicas (links de conexão, convites, exclusão de dados) com limite por IP | | Messajo → seus destinos | assinatura HMAC-SHA256 em todo envio; anti-SSRF que resolve o DNS, recusa IP privado e conecta no IP conferido | | Messajo → Graph da Meta | origem fixa; tokens cifrados no banco; resposta validada antes de usar | | Operador | super-admin, filas e `/metrics` atrás de autenticação própria; logs com redação automática de segredos | | Cadeia de fornecimento | versões fixas, `bun audit` e varredura de segredos na CI; imagem roda sem `root` | Toda rota do servidor tem uma política declarada (autenticação, limite e corpo máximo); um teste falha a CI se aparecer rota sem política. ## Dados sensíveis [Seção intitulada “Dados sensíveis”](#dados-sensíveis) | Dado | Como fica | | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | Tokens da Meta, PIN do número, chave privada de Flow | cifrados (AES-256-GCM) no banco; a API mostra no máximo os 4 últimos caracteres | | Segredos de destino e do handler de Flow | cifrados; aparecem só na resposta que os gera | | Chaves de API, tokens de link de conexão | só o hash | | Credencial SIP | não fica: repassada à Meta e mostrada uma vez | | Código OTP | não gravado; mensagem, eventos e logs levam o código mascarado ([Templates de autenticação](/guides/authentication-templates/)) | | SDP das ligações (IP do contato) | apagado 1 h depois do fim da ligação; a API mostra só `has_sdp` | | Dados digitados num Flow com endpoint | não gravados; o Messajo guarda só os metadados da troca, por 7 dias | | Mensagens, contatos e mídia | retenção da organização (padrão 90 dias), exportação e apagamento em [Dados e privacidade](/operate/data-privacy/) | ## Reportar uma vulnerabilidade [Seção intitulada “Reportar uma vulnerabilidade”](#reportar-uma-vulnerabilidade) **Não abra issue pública.** Escreva para `security@messajo.com`, com a descrição, a versão, o passo a passo para reproduzir e como quer ser creditado. | Etapa | Prazo | | -------------------------- | ------------------------------------------------------------- | | Confirmação do recebimento | até 72 horas úteis | | Avaliação inicial | até 7 dias | | Divulgação pública | até 90 dias depois do reporte, ou antes se a correção já saiu | A política completa está no `SECURITY.md` do repositório. # SDK TypeScript > @messajo/sdk: instalar, primeira chamada, paginação, erros, repetição segura, webhooks e eventos por WebSocket. `@messajo/sdk` é o SDK oficial da API `/v1`. Os tipos são gerados do mesmo OpenAPI da [referência](/reference), então todo campo e todo código de erro aparecem no autocompletar. * Zero dependências, ESM. Roda no Node 20+, Bun, Deno, Workers e navegador. * Licença **MIT**: pode embutir no seu código fechado. ## Instalar [Seção intitulada “Instalar”](#instalar) ```bash npm install @messajo/sdk ``` ## Primeira chamada [Seção intitulada “Primeira chamada”](#primeira-chamada) ```ts import { Messajo } from "@messajo/sdk"; const messajo = new Messajo({ apiKey: process.env.MESSAJO_API_KEY!, }); const me = await messajo.me.get(); console.log(me.organization.name, me.api_key.permissions); const sent = await messajo.messages.send({ connection_id: "conn_...", to: "5511999999999", type: "text", text: { body: "Olá! Mensagem enviada pelo SDK." }, }); console.log(sent.id, sent.status); ``` | Opção | Padrão | O que é | | ------------ | ---------------------------- | ------------------------------------------------- | | `apiKey` | — | a chave `mj_…` (organização) ou `mjc_…` (conexão) | | `baseUrl` | `https://api.messajo.com/v1` | a URL base da API | | `maxRetries` | `2` | repetições automáticas (veja abaixo) | | `timeoutMs` | `30000` | limite de cada tentativa | | `fetch` | o global | para injetar outro `fetch` (proxy, testes) | Recursos: `me`, `messages`, `conversations`, `contacts`, `campaigns`, `templates`, `media`, `connections`, `destinations`, `deliveries`, `events`, `connectionLinks`, `publications` e `apiKeys`. A camada espelho da Meta sai crua em `messajo.mirror("whatsapp", connectionId, "message_templates")`. ## Chave de conexão [Seção intitulada “Chave de conexão”](#chave-de-conexão) Uma chave `mjc_…` (criada na conexão) enxerga só aquela conexão: a `/v1` resolve o `connection_id` pela chave e ele pode ser omitido. Chaves da organização (`mj_…`) enxergam todas as conexões e são as únicas que gerenciam chaves; a `mjc_` recebe `403 organization_key_required` ali. Veja [Autenticação](/api/authentication/). `messajo.connection(id?)` devolve um cliente que injeta o `connection_id`: ```ts // Chave de conexão: sem connection_id. const scoped = new Messajo({ apiKey: process.env.MESSAJO_CONNECTION_KEY! }).connection(); await scoped.messages.send({ to: "5511999999999", type: "text", text: { body: "Olá!" } }); // Chave da organização: fixa a conexão uma vez. const sales = messajo.connection("conn_..."); await sales.messages.send({ to: "5511999999999", type: "text", text: { body: "Olá!" } }); // Gerenciar chaves da conexão (só chave da organização). const key = await sales.apiKeys.create({ name: "Integração CRM", permissions: ["send", "read"] }); ``` Ficam com o `connection_id` fixado: `messages`, `conversations`, `contacts`, `campaigns`, `templates`, `media`, `publications`, `events`, `destinations.create` e `apiKeys`; `apiKeys.list`/`create` exigem `connection(id)`. ## Paginação [Seção intitulada “Paginação”](#paginação) `paginate` percorre qualquer lista `{ data, next_cursor }` seguindo o cursor: ```ts for await (const conversation of messajo.paginate(messajo.conversations.list, { window: "open", })) { console.log(conversation.id, conversation.contact.display_name); } ``` Para uma página só, chame a lista direto: `await messajo.messages.list({ limit: 50 })`. Veja [Histórico](/api/history/). ## Erros [Seção intitulada “Erros”](#erros) Toda resposta de erro vira um `MessajoError` com os campos do [corpo de erro](/errors/): ```ts import { MessajoError } from "@messajo/sdk"; try { await messajo.messages.send({ /* ... */ }); } catch (error) { if (error instanceof MessajoError) { console.error(error.status, error.code, error.metaCode, error.requestId, error.docsUrl); if (error.code === "outside_service_window") { // fora da janela de 24 h: mande um template } } } ``` `retryable`, `retryAfterMs` e `details` também estão no erro. ## Repetição segura [Seção intitulada “Repetição segura”](#repetição-segura) * O SDK gera um `Idempotency-Key` em toda escrita (`POST`). Para controlar a chave, passe `{ idempotencyKey }` como último argumento, por exemplo `messajo.messages.send(body, { idempotencyKey: pedido.id })`. * `GET` e escritas com `Idempotency-Key` repetem sozinhos em `429`, `503` e falha de rede, respeitando `retry_after_ms` e `Retry-After`, até `maxRetries`. * `502` [`meta_unknown_outcome`](/errors#meta_unknown_outcome) **nunca** é repetido: a mensagem pode ter saído. Confira pelo `message.status` antes de reenviar. ## Webhooks [Seção intitulada “Webhooks”](#webhooks) ```ts import { verifyWebhookSignature } from "@messajo/sdk"; const body = await request.text(); // corpo cru, antes do JSON.parse const result = await verifyWebhookSignature({ header: request.headers.get("Messajo-Signature"), body, secret: process.env.MESSAJO_WEBHOOK_SECRET!, }); if (!result.ok) { return new Response(result.reason, { status: 400 }); } const event = JSON.parse(body); ``` `reason` é `missing`, `malformed`, `outside_tolerance` (mais de 5 minutos) ou `mismatch`. Usa WebCrypto, então funciona igual no Node, no Bun, no Deno e em Workers. Detalhes em [Verificar a assinatura](/webhooks/verify-signature/). ## Eventos por WebSocket [Seção intitulada “Eventos por WebSocket”](#eventos-por-websocket) Para um destino do tipo `websocket` ([Tipos de destino](/webhooks/destinations/#websocket)): ```ts import { connectEvents } from "@messajo/sdk"; const socket = connectEvents({ client: messajo, destinationId: "dst_...", onEvent: async (event) => { // o ack sai quando isto resolve; se lançar, o Messajo entrega de novo }, onError: (error) => console.error(error), }); await socket.ready; // id da sessão // socket.close() para encerrar ``` A ordem não é garantida e o mesmo evento pode chegar mais de uma vez: desduplique por `event.id`. No Node 20, que não tem `WebSocket` global, passe a opção `WebSocket` (do pacote `ws`). ## Versões [Seção intitulada “Versões”](#versões) A versão do SDK acompanha a do servidor (`0.3.0-beta.1` com o beta). Versões de pré-lançamento saem na tag `beta` do npm: `npm install @messajo/sdk@beta`. # Enviar áudio > Envie um arquivo de áudio ou uma mensagem de voz por WhatsApp, Instagram ou Messenger. Envie um áudio em `POST /v1/messages` com `type: "audio"`. Os campos comuns a todos os tipos (`to`, `reply_to`, `typing`, `delay_ms`, janela de 24 h) estão em [Campos comuns](/send/text/#campos-comuns). * cURL ```bash curl -X POST https://api.messajo.com/v1/messages \ -H "Authorization: Bearer $MESSAJO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "connection_id": "con_123", "to": "5511999990000", "type": "audio", "audio": { "link": "https://cdn.exemplo.com/audio.mp3" } }' ``` * TypeScript ```ts import { Messajo } from "@messajo/sdk"; const messajo = new Messajo({ apiKey: process.env.MESSAJO_API_KEY! }); const message = await messajo.messages.send({ connection_id: "con_123", to: "5511999990000", type: "audio", audio: { link: "https://cdn.exemplo.com/audio.mp3" }, }); console.log(message.id, message.status); ``` * n8n **Configurações do nó HTTP Request do n8n** * Método: `POST` * URL: `https://api.messajo.com/v1/messages` * Autenticação: Generic Credential Type, depois Header Auth. Nome: `Authorization`; Valor: `Bearer mj_...` * Cabeçalhos: ative Send Headers e adicione `Idempotency-Key` (um valor único por item) * Corpo: ative Send Body; Body Content Type: JSON; Specify Body: Using JSON ```json { "connection_id": "con_123", "to": "5511999990000", "type": "audio", "audio": { "link": "https://cdn.exemplo.com/audio.mp3" } } ``` Substitua mj\_... pela sua chave de API. A resposta é `201` com `id` (`msg_…`), `status: "queued"` e `conversation_id`. O estado final chega por webhook. Áudio não tem legenda. ## Link ou upload [Seção intitulada “Link ou upload”](#link-ou-upload) Informe **exatamente um** entre `link` e `media_id`. Mandar os dois, ou nenhum, devolve `400 validation_failed` com `exactly one of media_id or link is required`. * `link`: URL do áudio. * `media_id` (`med_…`): vem de `POST /v1/media`, um `multipart/form-data` com `file` (e `connection_id`, exceto com chave de conexão `mjc_…`). Exige a permissão `send`. O tipo é lido dos bytes do arquivo, não da extensão. - cURL ```bash curl -X POST https://api.messajo.com/v1/media \ -H "Authorization: Bearer $MESSAJO_API_KEY" \ -F connection_id=con_123 \ -F file=@audio.mp3 ``` - TypeScript ```ts import { readFile } from "node:fs/promises"; const media = await messajo.media.upload({ file: new Blob([await readFile("audio.mp3")]), connection_id: "con_123", }); await messajo.messages.send({ connection_id: "con_123", to: "5511999990000", type: "audio", audio: { media_id: media.id }, }); ``` O upload devolve o `id` da mídia (`med_…`), que você usa em `audio.media_id`. ## WhatsApp [Seção intitulada “WhatsApp”](#whatsapp) Upload de até **16 MiB**. O upload reconhece `audio/ogg` (somente Opus: OGG com Vorbis é recusado), `audio/mpeg`, `audio/amr`, `audio/aac` e `audio/mp4`. ### Mensagem de voz [Seção intitulada “Mensagem de voz”](#mensagem-de-voz) Com `voice: true` o áudio chega como mensagem de voz (a que mostra a onda sonora). Ela precisa ser OGG com Opus, e o Messajo converte quando o arquivo é de outro formato: * Com `media_id` ou `link` e `voice: true`, o Messajo converte para OGG/Opus se o arquivo ainda não for. Com `link`, ele baixa o arquivo antes (URL pública `https`, até 16 MiB). * Você também pode converter no upload, com `convert=voice`, e enviar o `media_id` que volta já em OGG/Opus. A entrada da conversão tem no máximo 16 MiB e precisa ser um arquivo de áudio. Se a conversão falhar, a resposta é `422 voice_conversion_failed`. * cURL ```bash curl -X POST https://api.messajo.com/v1/media \ -H "Authorization: Bearer $MESSAJO_API_KEY" \ -F connection_id=con_123 \ -F convert=voice \ -F file=@audio.mp3 ``` * TypeScript ```ts import { readFile } from "node:fs/promises"; const media = await messajo.media.upload({ file: new Blob([await readFile("audio.mp3")]), connection_id: "con_123", convert: "voice", }); await messajo.messages.send({ connection_id: "con_123", to: "5511999990000", type: "audio", audio: { media_id: media.id, voice: true }, }); ``` ## Instagram e Messenger [Seção intitulada “Instagram e Messenger”](#instagram-e-messenger) O corpo é o mesmo, sem `voice`: * `link` precisa ser `https`. * Não há conversão: o arquivo precisa estar em um formato aceito pelo canal. | Canal | Tamanho máximo | Formatos | | --------- | -------------- | ---------------------------------------------------- | | Instagram | 25 MiB | `audio/aac`, `audio/mp4`, `audio/x-m4a`, `audio/wav` | | Messenger | 25 MiB | `audio/mpeg`, `audio/mp4`, `audio/aac`, `audio/wav` | ## Erros [Seção intitulada “Erros”](#erros) | Código | Status | Quando | | -------------------------- | ------ | ---------------------------------------------- | | `validation_failed` | 400 | `link` e `media_id` juntos, ou nenhum dos dois | | `media_too_large` | 413 | Arquivo acima do limite | | `media_type_not_supported` | 415 | Formato que o canal não aceita | | `media_error` | 422 | A Meta não conseguiu processar a mídia | | `voice_conversion_failed` | 422 | Falha ao converter para mensagem de voz | | `outside_service_window` | 422 | Mensagem livre fora da janela de 24 h | Detalhes de cada código no [catálogo de erros](/errors/). # Enviar botões > Envie botões de resposta ou de link no WhatsApp, e botões de ação no Instagram e no Messenger, com POST /v1/messages. `POST /v1/messages` com `type: "interactive"` envia botões de resposta ou de link no WhatsApp. No Instagram e no Messenger, o equivalente é `type: "buttons"`. Os campos que valem para todos os envios estão em [Campos comuns](/send/text/#campos-comuns). ## Antes de começar [Seção intitulada “Antes de começar”](#antes-de-começar) * Uma chave de API com a permissão `send` (veja [Autenticação](/api/authentication/)). * Uma conexão **Ativa** do canal. * Mensagem interativa é mensagem livre: só sai dentro da janela de 24 horas depois da última mensagem do contato (veja [Janelas](/api/limits/#janelas)). Fora dela, use um template. ## Botões de resposta (WhatsApp) [Seção intitulada “Botões de resposta (WhatsApp)”](#botões-de-resposta-whatsapp) `interactive.type: "button"` mostra de 1 a 3 botões. Quando o contato toca em um, o `id` do botão volta para você. * cURL ```bash curl https://api.messajo.com/v1/messages \ -H "Authorization: Bearer $MESSAJO_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{ "connection_id": "conn_...", "to": "5511999999999", "type": "interactive", "interactive": { "type": "button", "header": { "type": "text", "text": "Seu pedido" }, "body": { "text": "Seu pedido #123 chegou. Deu tudo certo?" }, "footer": { "text": "Responda em um toque" }, "action": { "buttons": [ { "type": "reply", "reply": { "id": "sim", "title": "Sim" } }, { "type": "reply", "reply": { "id": "nao", "title": "Não" } } ] } } }' ``` * TypeScript ```ts import { Messajo } from "@messajo/sdk"; const messajo = new Messajo({ apiKey: process.env.MESSAJO_API_KEY! }); const sent = await messajo.messages.send({ "connection_id": "conn_...", "to": "5511999999999", "type": "interactive", "interactive": { "type": "button", "header": { "type": "text", "text": "Seu pedido" }, "body": { "text": "Seu pedido #123 chegou. Deu tudo certo?" }, "footer": { "text": "Responda em um toque" }, "action": { "buttons": [ { "type": "reply", "reply": { "id": "sim", "title": "Sim" } }, { "type": "reply", "reply": { "id": "nao", "title": "Não" } } ] } } }); ``` * n8n **Configurações do nó HTTP Request do n8n** * Método: `POST` * URL: `https://api.messajo.com/v1/messages` * Autenticação: Generic Credential Type, depois Header Auth. Nome: `Authorization`; Valor: `Bearer mj_...` * Cabeçalhos: ative Send Headers e adicione `Idempotency-Key` (um valor único por item) * Corpo: ative Send Body; Body Content Type: JSON; Specify Body: Using JSON ```json { "connection_id": "conn_...", "to": "5511999999999", "type": "interactive", "interactive": { "type": "button", "header": { "type": "text", "text": "Seu pedido" }, "body": { "text": "Seu pedido #123 chegou. Deu tudo certo?" }, "footer": { "text": "Responda em um toque" }, "action": { "buttons": [ { "type": "reply", "reply": { "id": "sim", "title": "Sim" } }, { "type": "reply", "reply": { "id": "nao", "title": "Não" } } ] } } } ``` Substitua mj\_... pela sua chave de API. | Campo | Regra | | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------- | | `interactive.body.text` | Obrigatório, de 1 a 1024 caracteres. | | `interactive.header` | Opcional. `{ "type": "text", "text": "…" }` com até 60 caracteres. O tipo também pode ser `image`, `video` ou `document`. | | `interactive.footer.text` | Opcional, até 60 caracteres. | | `interactive.action.buttons` | De 1 a 3 itens `{ "type": "reply", "reply": { "id", "title" } }`. | | `reply.id` | De 1 a 256 caracteres. É o que você recebe de volta. | | `reply.title` | De 1 a 20 caracteres. É o texto do botão. | ## Botão com link (cta_url) [Seção intitulada “Botão com link (cta_url)”](#botão-com-link-cta_url) `interactive.type: "cta_url"` mostra um único botão que abre uma URL. `header` e `footer` são opcionais, como nos botões de resposta. * cURL ```bash curl https://api.messajo.com/v1/messages \ -H "Authorization: Bearer $MESSAJO_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{ "connection_id": "conn_...", "to": "5511999999999", "type": "interactive", "interactive": { "type": "cta_url", "body": { "text": "Acompanhe a entrega pelo link." }, "action": { "name": "cta_url", "parameters": { "display_text": "Rastrear pedido", "url": "https://exemplo.com/pedido/123" } } } }' ``` * TypeScript ```ts import { Messajo } from "@messajo/sdk"; const messajo = new Messajo({ apiKey: process.env.MESSAJO_API_KEY! }); const sent = await messajo.messages.send({ "connection_id": "conn_...", "to": "5511999999999", "type": "interactive", "interactive": { "type": "cta_url", "body": { "text": "Acompanhe a entrega pelo link." }, "action": { "name": "cta_url", "parameters": { "display_text": "Rastrear pedido", "url": "https://exemplo.com/pedido/123" } } } }); ``` * n8n **Configurações do nó HTTP Request do n8n** * Método: `POST` * URL: `https://api.messajo.com/v1/messages` * Autenticação: Generic Credential Type, depois Header Auth. Nome: `Authorization`; Valor: `Bearer mj_...` * Cabeçalhos: ative Send Headers e adicione `Idempotency-Key` (um valor único por item) * Corpo: ative Send Body; Body Content Type: JSON; Specify Body: Using JSON ```json { "connection_id": "conn_...", "to": "5511999999999", "type": "interactive", "interactive": { "type": "cta_url", "body": { "text": "Acompanhe a entrega pelo link." }, "action": { "name": "cta_url", "parameters": { "display_text": "Rastrear pedido", "url": "https://exemplo.com/pedido/123" } } } } ``` Substitua mj\_... pela sua chave de API. `display_text` tem de 1 a 20 caracteres e `url` é a página que abre. ## Receber o clique [Seção intitulada “Receber o clique”](#receber-o-clique) O toque chega como um evento [`message.received`](/webhooks/events/), com `data.message.content` do tipo `reply`: ```json { "type": "message.received", "data": { "message": { "direction": "inbound", "content": { "type": "reply", "kind": "button", "id": "sim", "title": "Sim", "description": null, "payload": null } } } } ``` `id` e `title` são os do botão tocado. Ligue o `id` à sua lógica, e não o texto, que você pode mudar. ## Instagram e Messenger [Seção intitulada “Instagram e Messenger”](#instagram-e-messenger) Nesses canais use `type: "buttons"`: um texto de 1 a 640 caracteres e de 1 a 3 botões. Cada botão é `postback` (`title` de 1 a 20 e `payload` de 1 a 1000 caracteres, devolvido quando o contato toca) ou `web_url` (`title` de 1 a 20 e `url` com https). `quick_replies` também é aceito. * cURL ```bash curl https://api.messajo.com/v1/messages \ -H "Authorization: Bearer $MESSAJO_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{ "connection_id": "conn_...", "to": "17841400000000000", "type": "buttons", "buttons": { "text": "Como podemos ajudar?", "buttons": [ { "type": "postback", "title": "Falar com vendas", "payload": "vendas" }, { "type": "web_url", "title": "Ver site", "url": "https://exemplo.com" } ] } }' ``` * TypeScript ```ts import { Messajo } from "@messajo/sdk"; const messajo = new Messajo({ apiKey: process.env.MESSAJO_API_KEY! }); const sent = await messajo.messages.send({ "connection_id": "conn_...", "to": "17841400000000000", "type": "buttons", "buttons": { "text": "Como podemos ajudar?", "buttons": [ { "type": "postback", "title": "Falar com vendas", "payload": "vendas" }, { "type": "web_url", "title": "Ver site", "url": "https://exemplo.com" } ] } }); ``` * n8n **Configurações do nó HTTP Request do n8n** * Método: `POST` * URL: `https://api.messajo.com/v1/messages` * Autenticação: Generic Credential Type, depois Header Auth. Nome: `Authorization`; Valor: `Bearer mj_...` * Cabeçalhos: ative Send Headers e adicione `Idempotency-Key` (um valor único por item) * Corpo: ative Send Body; Body Content Type: JSON; Specify Body: Using JSON ```json { "connection_id": "conn_...", "to": "17841400000000000", "type": "buttons", "buttons": { "text": "Como podemos ajudar?", "buttons": [ { "type": "postback", "title": "Falar com vendas", "payload": "vendas" }, { "type": "web_url", "title": "Ver site", "url": "https://exemplo.com" } ] } } ``` Substitua mj\_... pela sua chave de API. Para vários cartões com imagem, título e botões, use `type: "cards"`: de 1 a 10 cartões, com `title` de até 80 caracteres e, se quiser, `subtitle`, `image_url`, `default_url` e `buttons`. Veja [Tipos de mensagem](/connect/instagram/#tipos-de-mensagem). ## Outros tipos interativos [Seção intitulada “Outros tipos interativos”](#outros-tipos-interativos) * Fluxos (Flows): [Flows](/guides/flows/). * Catálogo, produtos e pedido com Pix: [Vendas no WhatsApp](/guides/commerce/). * Pedido de permissão de ligação: [Ligações](/guides/calls/). * Lista de opções: [Enviar lista](/send/list/). ## Erros comuns [Seção intitulada “Erros comuns”](#erros-comuns) * [`outside_service_window`](/errors#outside_service_window) (422): fora das 24 horas ([janelas](/api/limits/#janelas)). O fim da janela vem em `details[0].message`. * [`type_not_supported_by_channel`](/errors#type_not_supported_by_channel) (422): o canal não aceita esse tipo. Exemplo: `interactive` no Instagram ou no Messenger, ou `buttons` no WhatsApp. * [`validation_failed`](/errors#validation_failed) (400): corpo fora das regras, como mais de 3 botões ou título acima do limite. # Enviar contato > Envie de 1 a 10 cartões de contato pelo WhatsApp com POST /v1/messages e type contacts, com nome, telefones e e-mails. `type: "contacts"` envia cartões de contato que o destinatário salva com um toque. Só no WhatsApp. Os campos comuns a todos os tipos (`to`, `reply_to`, `typing`, `delay_ms`, janela de 24 h) estão em [Campos comuns](/send/text/#campos-comuns). ## Campos [Seção intitulada “Campos”](#campos) `contacts` é uma lista de 1 a 10 cartões. | Campo | Regra | | -------------------------------- | --------------------------------------------------------------------------- | | `contacts[].name.formatted_name` | Obrigatório, de 1 a 256 caracteres | | `contacts[].name.first_name` | Opcional, até 128 caracteres | | `contacts[].name.last_name` | Opcional, até 128 caracteres | | `contacts[].phones` | Opcional, até 10 itens | | `contacts[].phones[].phone` | De 1 a 64 caracteres | | `contacts[].phones[].type` | Opcional, até 32 caracteres (ex.: `CELL`, `WORK`) | | `contacts[].phones[].wa_id` | Opcional, até 64 caracteres: o número no WhatsApp, para o botão de conversa | | `contacts[].emails` | Opcional, até 10 itens | | `contacts[].emails[].email` | De 1 a 128 caracteres | | `contacts[].emails[].type` | Opcional, até 32 caracteres | ## Enviar um contato [Seção intitulada “Enviar um contato”](#enviar-um-contato) * cURL ```bash curl https://api.messajo.com/v1/messages \ -H "Authorization: Bearer $MESSAJO_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{ "connection_id": "conn_...", "to": "5511999999999", "type": "contacts", "contacts": [ { "name": { "formatted_name": "Ana Souza", "first_name": "Ana", "last_name": "Souza" }, "phones": [{ "phone": "+55 11 98888-7777", "type": "CELL", "wa_id": "5511988887777" }], "emails": [{ "email": "ana@exemplo.com", "type": "WORK" }] } ] }' ``` * TypeScript ```ts import { Messajo } from "@messajo/sdk"; const messajo = new Messajo({ apiKey: process.env.MESSAJO_API_KEY! }); const sent = await messajo.messages.send({ connection_id: "conn_...", to: "5511999999999", type: "contacts", contacts: [ { name: { formatted_name: "Ana Souza", first_name: "Ana", last_name: "Souza" }, phones: [{ phone: "+55 11 98888-7777", type: "CELL", wa_id: "5511988887777" }], emails: [{ email: "ana@exemplo.com", type: "WORK" }], }, ], }); ``` * n8n **Configurações do nó HTTP Request do n8n** * Método: `POST` * URL: `https://api.messajo.com/v1/messages` * Autenticação: Generic Credential Type, depois Header Auth. Nome: `Authorization`; Valor: `Bearer mj_...` * Cabeçalhos: ative Send Headers e adicione `Idempotency-Key` (um valor único por item) * Corpo: ative Send Body; Body Content Type: JSON; Specify Body: Using JSON ```json { "connection_id": "conn_...", "to": "5511999999999", "type": "contacts", "contacts": [ { "name": { "formatted_name": "Ana Souza", "first_name": "Ana", "last_name": "Souza" }, "phones": [ { "phone": "+55 11 98888-7777", "type": "CELL", "wa_id": "5511988887777" } ], "emails": [ { "email": "ana@exemplo.com", "type": "WORK" } ] } ] } ``` Substitua mj\_... pela sua chave de API. A resposta é a mesma do envio de texto (`201`, `status: "queued"`); veja [Resposta](/send/text/#resposta). ## Erros [Seção intitulada “Erros”](#erros) * `422` [`outside_service_window`](/errors#outside_service_window): contato é mensagem livre, então só sai dentro de 24 horas da última mensagem do destinatário. Fora da janela, use um [template](/guides/templates/). * `422` [`type_not_supported_by_channel`](/errors#type_not_supported_by_channel): conexão do Instagram ou do Messenger. Contato é só do WhatsApp. * `400` [`validation_failed`](/errors#validation_failed): lista vazia ou com mais de 10 cartões, `formatted_name` ausente, limite de tamanho excedido ou campo desconhecido. # Enviar documento > Envie um PDF ou outro documento com nome de arquivo e legenda por WhatsApp, Instagram ou Messenger. Envie um documento em `POST /v1/messages` com `type: "document"`. Os campos comuns a todos os tipos (`to`, `reply_to`, `typing`, `delay_ms`, janela de 24 h) estão em [Campos comuns](/send/text/#campos-comuns). * cURL ```bash curl -X POST https://api.messajo.com/v1/messages \ -H "Authorization: Bearer $MESSAJO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "connection_id": "con_123", "to": "5511999990000", "type": "document", "document": { "link": "https://cdn.exemplo.com/fatura-novembro.pdf", "filename": "fatura-novembro.pdf", "caption": "Sua fatura de novembro" } }' ``` * TypeScript ```ts import { Messajo } from "@messajo/sdk"; const messajo = new Messajo({ apiKey: process.env.MESSAJO_API_KEY! }); const message = await messajo.messages.send({ connection_id: "con_123", to: "5511999990000", type: "document", document: { link: "https://cdn.exemplo.com/fatura-novembro.pdf", filename: "fatura-novembro.pdf", caption: "Sua fatura de novembro" }, }); console.log(message.id, message.status); ``` * n8n **Configurações do nó HTTP Request do n8n** * Método: `POST` * URL: `https://api.messajo.com/v1/messages` * Autenticação: Generic Credential Type, depois Header Auth. Nome: `Authorization`; Valor: `Bearer mj_...` * Cabeçalhos: ative Send Headers e adicione `Idempotency-Key` (um valor único por item) * Corpo: ative Send Body; Body Content Type: JSON; Specify Body: Using JSON ```json { "connection_id": "con_123", "to": "5511999990000", "type": "document", "document": { "link": "https://cdn.exemplo.com/fatura-novembro.pdf", "filename": "fatura-novembro.pdf", "caption": "Sua fatura de novembro" } } ``` Substitua mj\_... pela sua chave de API. A resposta é `201` com `id` (`msg_…`), `status: "queued"` e `conversation_id`. O estado final chega por webhook. ## Link ou upload [Seção intitulada “Link ou upload”](#link-ou-upload) Informe **exatamente um** entre `link` e `media_id`. Mandar os dois, ou nenhum, devolve `400 validation_failed` com `exactly one of media_id or link is required`. * `link`: URL do documento. * `media_id` (`med_…`): vem de `POST /v1/media`, um `multipart/form-data` com `file` (e `connection_id`, exceto com chave de conexão `mjc_…`). Exige a permissão `send`. O tipo é lido dos bytes do arquivo, não da extensão. - cURL ```bash curl -X POST https://api.messajo.com/v1/media \ -H "Authorization: Bearer $MESSAJO_API_KEY" \ -F connection_id=con_123 \ -F file=@fatura-novembro.pdf ``` - TypeScript ```ts import { readFile } from "node:fs/promises"; const media = await messajo.media.upload({ file: new Blob([await readFile("fatura-novembro.pdf")]), connection_id: "con_123", }); await messajo.messages.send({ connection_id: "con_123", to: "5511999990000", type: "document", document: { media_id: media.id, filename: "fatura-novembro.pdf" }, }); ``` O upload devolve o `id` da mídia (`med_…`), que você usa em `document.media_id`. ## WhatsApp [Seção intitulada “WhatsApp”](#whatsapp) * `document.caption`: legenda de até 1024 caracteres. * `document.filename`: nome exibido ao contato, até 240 caracteres. Envie sempre, com a extensão (`fatura-novembro.pdf`), para o contato ver um nome legível. * Upload: até **100 MiB**. O upload reconhece estes formatos: | Formato | Extensões | | ------------- | ------------------------- | | PDF | `.pdf` | | Office antigo | `.doc`, `.xls`, `.ppt` | | Office | `.docx`, `.xlsx`, `.pptx` | | Texto puro | `.txt` | Os arquivos do Office são identificados pelos bytes **e** pela extensão do nome do arquivo. Outros formatos devolvem `415 media_type_not_supported`. ## Instagram e Messenger [Seção intitulada “Instagram e Messenger”](#instagram-e-messenger) O corpo é só `link` ou `media_id`, com duas diferenças: * `link` precisa ser `https`. * Não existem `caption` nem `filename`. Mande a legenda como mensagem de texto à parte. | Canal | Tamanho máximo | Formatos | | --------- | -------------- | ----------------- | | Instagram | 25 MB | `application/pdf` | | Messenger | 25 MB | `application/pdf` | ## Erros [Seção intitulada “Erros”](#erros) | Código | Status | Quando | | -------------------------- | ------ | ---------------------------------------------- | | `validation_failed` | 400 | `link` e `media_id` juntos, ou nenhum dos dois | | `media_too_large` | 413 | Arquivo acima do limite do canal | | `media_type_not_supported` | 415 | Formato que o canal não aceita | | `media_error` | 422 | A Meta não conseguiu processar o arquivo | | `outside_service_window` | 422 | Mensagem livre fora da janela de 24 h | # Enviar imagem > Envie uma imagem com legenda opcional por WhatsApp, Instagram ou Messenger. Envie uma imagem em `POST /v1/messages` com `type: "image"`. Os campos comuns a todos os tipos (`to`, `reply_to`, `typing`, `delay_ms`, janela de 24 h) estão em [Campos comuns](/send/text/#campos-comuns). * cURL ```bash curl -X POST https://api.messajo.com/v1/messages \ -H "Authorization: Bearer $MESSAJO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "connection_id": "con_123", "to": "5511999990000", "type": "image", "image": { "link": "https://cdn.exemplo.com/foto.jpg", "caption": "Seu pedido saiu para entrega" } }' ``` * TypeScript ```ts import { Messajo } from "@messajo/sdk"; const messajo = new Messajo({ apiKey: process.env.MESSAJO_API_KEY! }); const message = await messajo.messages.send({ connection_id: "con_123", to: "5511999990000", type: "image", image: { link: "https://cdn.exemplo.com/foto.jpg", caption: "Seu pedido saiu para entrega" }, }); console.log(message.id, message.status); ``` * n8n **Configurações do nó HTTP Request do n8n** * Método: `POST` * URL: `https://api.messajo.com/v1/messages` * Autenticação: Generic Credential Type, depois Header Auth. Nome: `Authorization`; Valor: `Bearer mj_...` * Cabeçalhos: ative Send Headers e adicione `Idempotency-Key` (um valor único por item) * Corpo: ative Send Body; Body Content Type: JSON; Specify Body: Using JSON ```json { "connection_id": "con_123", "to": "5511999990000", "type": "image", "image": { "link": "https://cdn.exemplo.com/foto.jpg", "caption": "Seu pedido saiu para entrega" } } ``` Substitua mj\_... pela sua chave de API. A resposta é `201` com `id` (`msg_…`), `status: "queued"` e `conversation_id`. O estado final chega por webhook. ## Link ou upload [Seção intitulada “Link ou upload”](#link-ou-upload) Informe **exatamente um** entre `link` e `media_id`. Mandar os dois, ou nenhum, devolve `400 validation_failed` com `exactly one of media_id or link is required`. * `link`: URL da imagem. * `media_id` (`med_…`): vem de `POST /v1/media`, um `multipart/form-data` com `file` (e `connection_id`, exceto com chave de conexão `mjc_…`). Exige a permissão `send`. O tipo é lido dos bytes do arquivo, não da extensão. - cURL ```bash curl -X POST https://api.messajo.com/v1/media \ -H "Authorization: Bearer $MESSAJO_API_KEY" \ -F connection_id=con_123 \ -F file=@foto.jpg ``` - TypeScript ```ts import { readFile } from "node:fs/promises"; const media = await messajo.media.upload({ file: new Blob([await readFile("foto.jpg")]), connection_id: "con_123", }); await messajo.messages.send({ connection_id: "con_123", to: "5511999990000", type: "image", image: { media_id: media.id }, }); ``` O upload devolve o `id` da mídia (`med_…`), que você usa em `image.media_id`. ## WhatsApp [Seção intitulada “WhatsApp”](#whatsapp) * `image.caption`: legenda de até 1024 caracteres. * Upload: até **5 MiB**, em **JPEG** ou **PNG**. ## Instagram e Messenger [Seção intitulada “Instagram e Messenger”](#instagram-e-messenger) O corpo é o mesmo, com duas diferenças: * `link` precisa ser `https`. * Não existe `caption`. Enviar legenda devolve `422 type_not_supported_by_channel` apontando `image.caption`. Mande a legenda como mensagem de texto à parte. | Canal | Tamanho máximo | Formatos | | --------- | -------------- | -------------------------------------- | | Instagram | 8 MiB | `image/jpeg`, `image/png`, `image/gif` | | Messenger | 25 MiB | `image/jpeg`, `image/png`, `image/gif` | ### Várias imagens (só Instagram) [Seção intitulada “Várias imagens (só Instagram)”](#várias-imagens-só-instagram) `type: "images"` envia de 2 a 10 imagens em uma única mensagem. Cada item aceita `link` ou `media_id`. ```json { "connection_id": "con_123", "to": "17841400000000000", "type": "images", "images": { "items": [ { "link": "https://cdn.exemplo.com/a.jpg" }, { "link": "https://cdn.exemplo.com/b.jpg" } ] } } ``` ## Erros [Seção intitulada “Erros”](#erros) | Código | Status | Quando | | ------------------------------- | ------ | ---------------------------------------------- | | `validation_failed` | 400 | `link` e `media_id` juntos, ou nenhum dos dois | | `media_too_large` | 413 | Arquivo acima do limite | | `media_type_not_supported` | 415 | Formato que o canal não aceita | | `media_error` | 422 | A Meta não conseguiu processar a mídia | | `type_not_supported_by_channel` | 422 | `caption` no Instagram ou Messenger | | `outside_service_window` | 422 | Mensagem livre fora da janela de 24 h | Detalhes de cada código no [catálogo de erros](/errors/). # Enviar lista > Envie uma lista de opções com seções no WhatsApp usando POST /v1/messages e receba a escolha do contato. `POST /v1/messages` com `type: "interactive"` e `interactive.type: "list"` mostra um botão que abre uma lista de opções. Só existe no WhatsApp. Os campos que valem para todos os envios estão em [Campos comuns](/send/text/#campos-comuns). ## Antes de começar [Seção intitulada “Antes de começar”](#antes-de-começar) * Uma chave de API com a permissão `send` (veja [Autenticação](/api/authentication/)). * Uma conexão **Ativa** do WhatsApp. * Mensagem interativa é mensagem livre: só sai dentro da janela de 24 horas (veja [Janelas](/api/limits/#janelas)). Fora dela, use um template. ## Enviar uma lista [Seção intitulada “Enviar uma lista”](#enviar-uma-lista) * cURL ```bash curl https://api.messajo.com/v1/messages \ -H "Authorization: Bearer $MESSAJO_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{ "connection_id": "conn_...", "to": "5511999999999", "type": "interactive", "interactive": { "type": "list", "header": { "type": "text", "text": "Atendimento" }, "body": { "text": "Sobre o que você quer falar?" }, "footer": { "text": "Escolha uma opção" }, "action": { "button": "Ver opções", "sections": [ { "title": "Pedidos", "rows": [ { "id": "status", "title": "Status do pedido", "description": "Onde está minha entrega" }, { "id": "troca", "title": "Troca ou devolução" } ] }, { "title": "Conta", "rows": [ { "id": "fatura", "title": "Segunda via da fatura" }, { "id": "humano", "title": "Falar com uma pessoa", "description": "Atendimento em horário comercial" } ] } ] } } }' ``` * TypeScript ```ts import { Messajo } from "@messajo/sdk"; const messajo = new Messajo({ apiKey: process.env.MESSAJO_API_KEY! }); const sent = await messajo.messages.send({ "connection_id": "conn_...", "to": "5511999999999", "type": "interactive", "interactive": { "type": "list", "header": { "type": "text", "text": "Atendimento" }, "body": { "text": "Sobre o que você quer falar?" }, "footer": { "text": "Escolha uma opção" }, "action": { "button": "Ver opções", "sections": [ { "title": "Pedidos", "rows": [ { "id": "status", "title": "Status do pedido", "description": "Onde está minha entrega" }, { "id": "troca", "title": "Troca ou devolução" } ] }, { "title": "Conta", "rows": [ { "id": "fatura", "title": "Segunda via da fatura" }, { "id": "humano", "title": "Falar com uma pessoa", "description": "Atendimento em horário comercial" } ] } ] } } }); ``` * n8n **Configurações do nó HTTP Request do n8n** * Método: `POST` * URL: `https://api.messajo.com/v1/messages` * Autenticação: Generic Credential Type, depois Header Auth. Nome: `Authorization`; Valor: `Bearer mj_...` * Cabeçalhos: ative Send Headers e adicione `Idempotency-Key` (um valor único por item) * Corpo: ative Send Body; Body Content Type: JSON; Specify Body: Using JSON ```json { "connection_id": "conn_...", "to": "5511999999999", "type": "interactive", "interactive": { "type": "list", "header": { "type": "text", "text": "Atendimento" }, "body": { "text": "Sobre o que você quer falar?" }, "footer": { "text": "Escolha uma opção" }, "action": { "button": "Ver opções", "sections": [ { "title": "Pedidos", "rows": [ { "id": "status", "title": "Status do pedido", "description": "Onde está minha entrega" }, { "id": "troca", "title": "Troca ou devolução" } ] }, { "title": "Conta", "rows": [ { "id": "fatura", "title": "Segunda via da fatura" }, { "id": "humano", "title": "Falar com uma pessoa", "description": "Atendimento em horário comercial" } ] } ] } } } ``` Substitua mj\_... pela sua chave de API. ## Campos da lista [Seção intitulada “Campos da lista”](#campos-da-lista) | Campo | Regra | | ------------------------------------------ | ------------------------------------------------------------- | | `interactive.body.text` | Obrigatório, de 1 a 1024 caracteres. | | `interactive.header`, `interactive.footer` | Opcionais. Cabeçalho de texto e rodapé com até 60 caracteres. | | `action.button` | De 1 a 20 caracteres. É o rótulo do botão que abre a lista. | | `action.sections` | De 1 a 10 seções. | | `sections[].title` | Opcional, até 24 caracteres. | | `sections[].rows` | Pelo menos 1 linha. | | `rows[].id` | De 1 a 200 caracteres. É o que você recebe de volta. | | `rows[].title` | De 1 a 24 caracteres. | | `rows[].description` | Opcional, até 72 caracteres. | ## Receber a escolha [Seção intitulada “Receber a escolha”](#receber-a-escolha) A escolha chega como um evento [`message.received`](/webhooks/events/), com `data.message.content` do tipo `reply` e `kind: "list"`: ```json { "type": "message.received", "data": { "message": { "direction": "inbound", "content": { "type": "reply", "kind": "list", "id": "status", "title": "Status do pedido", "description": "Onde está minha entrega", "payload": null } } } } ``` `id`, `title` e `description` são os da linha escolhida. Ligue o `id` à sua lógica. ## Outros tipos interativos [Seção intitulada “Outros tipos interativos”](#outros-tipos-interativos) * Botões de resposta e de link: [Enviar botões](/send/buttons/). * Fluxos: [Flows](/guides/flows/). * Catálogo e pedido com Pix: [Vendas no WhatsApp](/guides/commerce/). ## Erros comuns [Seção intitulada “Erros comuns”](#erros-comuns) * [`outside_service_window`](/errors#outside_service_window) (422): fora das 24 horas ([janelas](/api/limits/#janelas)). O fim da janela vem em `details[0].message`. * [`type_not_supported_by_channel`](/errors#type_not_supported_by_channel) (422): o canal não aceita esse tipo. Exemplo: `interactive` no Instagram ou no Messenger, ou `buttons` no WhatsApp. * [`validation_failed`](/errors#validation_failed) (400): corpo fora das regras, como mais de 3 botões ou título acima do limite. # Enviar e pedir localização > Envie um ponto no mapa ou peça ao contato que compartilhe a localização dele no WhatsApp. Duas tarefas de localização, ambas só no WhatsApp: enviar um ponto no mapa e pedir a localização do contato. Os campos comuns a todos os tipos (`to`, `reply_to`, `typing`, `delay_ms`, janela de 24 h) estão em [Campos comuns](/send/text/#campos-comuns). ## Enviar uma localização [Seção intitulada “Enviar uma localização”](#enviar-uma-localização) Use `type: "location"` em `POST /v1/messages`. | Campo | Regra | | -------------------- | ---------------------------- | | `location.latitude` | Número de -90 a 90 | | `location.longitude` | Número de -180 a 180 | | `location.name` | Opcional, até 256 caracteres | | `location.address` | Opcional, até 512 caracteres | * cURL ```bash curl -X POST https://api.messajo.com/v1/messages \ -H "Authorization: Bearer $MESSAJO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "connection_id": "con_123", "to": "5511999990000", "type": "location", "location": { "latitude": -23.5614, "longitude": -46.6559, "name": "Loja Paulista", "address": "Av. Paulista, 1000, São Paulo" } }' ``` * TypeScript ```ts import { Messajo } from "@messajo/sdk"; const messajo = new Messajo({ apiKey: process.env.MESSAJO_API_KEY! }); const message = await messajo.messages.send({ connection_id: "con_123", to: "5511999990000", type: "location", location: { latitude: -23.5614, longitude: -46.6559, name: "Loja Paulista", address: "Av. Paulista, 1000, São Paulo", }, }); console.log(message.id, message.status); ``` * n8n **Configurações do nó HTTP Request do n8n** * Método: `POST` * URL: `https://api.messajo.com/v1/messages` * Autenticação: Generic Credential Type, depois Header Auth. Nome: `Authorization`; Valor: `Bearer mj_...` * Cabeçalhos: ative Send Headers e adicione `Idempotency-Key` (um valor único por item) * Corpo: ative Send Body; Body Content Type: JSON; Specify Body: Using JSON ```json { "connection_id": "con_123", "to": "5511999990000", "type": "location", "location": { "latitude": -23.5614, "longitude": -46.6559, "name": "Loja Paulista", "address": "Av. Paulista, 1000, São Paulo" } } ``` Substitua mj\_... pela sua chave de API. A resposta é `201` com `id` (`msg_…`), `status: "queued"` e `conversation_id`. O estado final chega por webhook. ## Pedir a localização do contato [Seção intitulada “Pedir a localização do contato”](#pedir-a-localização-do-contato) Use `type: "interactive"` com `interactive.type: "location_request_message"`. O contato vê o texto e um botão para compartilhar a localização. `body.text` tem até 1024 caracteres e `action.name` é sempre `send_location`. * cURL ```bash curl -X POST https://api.messajo.com/v1/messages \ -H "Authorization: Bearer $MESSAJO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "connection_id": "con_123", "to": "5511999990000", "type": "interactive", "interactive": { "type": "location_request_message", "body": { "text": "Para onde enviamos o pedido?" }, "action": { "name": "send_location" } } }' ``` * TypeScript ```ts await messajo.messages.send({ connection_id: "con_123", to: "5511999990000", type: "interactive", interactive: { type: "location_request_message", body: { text: "Para onde enviamos o pedido?" }, action: { name: "send_location" }, }, }); ``` * n8n **Configurações do nó HTTP Request do n8n** * Método: `POST` * URL: `https://api.messajo.com/v1/messages` * Autenticação: Generic Credential Type, depois Header Auth. Nome: `Authorization`; Valor: `Bearer mj_...` * Cabeçalhos: ative Send Headers e adicione `Idempotency-Key` (um valor único por item) * Corpo: ative Send Body; Body Content Type: JSON; Specify Body: Using JSON ```json { "connection_id": "con_123", "to": "5511999990000", "type": "interactive", "interactive": { "type": "location_request_message", "body": { "text": "Para onde enviamos o pedido?" }, "action": { "name": "send_location" } } } ``` Substitua mj\_... pela sua chave de API. ### Receber a resposta [Seção intitulada “Receber a resposta”](#receber-a-resposta) Quando o contato compartilha a localização, chega um evento [`message.received`](/webhooks/events/) com `content.type: "location"`: ```json { "type": "location", "latitude": -23.5614, "longitude": -46.6559, "name": null, "address": null, "url": null } ``` `name`, `address` e `url` vêm `null` quando o contato não os informa. Se ele ignorar o pedido, nada chega. ## Instagram e Messenger [Seção intitulada “Instagram e Messenger”](#instagram-e-messenger) Não aceitam `location` nem `interactive`: devolvem `422 type_not_supported_by_channel`. ## Erros [Seção intitulada “Erros”](#erros) | Código | Status | Quando | | ------------------------------- | ------ | ------------------------------------------------------------- | | `outside_service_window` | 422 | Mensagem livre fora da janela de 24 h | | `validation_failed` | 400 | Latitude ou longitude fora da faixa, ou texto acima do limite | | `type_not_supported_by_channel` | 422 | Instagram ou Messenger | # Marcar como lida > Marque uma mensagem recebida como lida com POST /v1/messages/{id}/read e, se quiser, mostre o indicador de digitação. `POST /v1/messages/{id}/read` marca como lida uma mensagem que o contato mandou. Com `typing: true`, mostra também o indicador de “digitando”. ## Antes de começar [Seção intitulada “Antes de começar”](#antes-de-começar) * Uma chave de API com a permissão `send`. * O `id` (`msg_…`) da mensagem **recebida**, que vem no evento `message.received`. ## Marcar como lida [Seção intitulada “Marcar como lida”](#marcar-como-lida) * cURL ```bash curl -X POST https://api.messajo.com/v1/messages/msg_.../read \ -H "Authorization: Bearer $MESSAJO_API_KEY" ``` Com o indicador de digitação: ```bash curl -X POST https://api.messajo.com/v1/messages/msg_.../read \ -H "Authorization: Bearer $MESSAJO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "typing": true }' ``` * TypeScript ```ts import { Messajo } from "@messajo/sdk"; const messajo = new Messajo({ apiKey: process.env.MESSAJO_API_KEY! }); await messajo.messages.markRead("msg_..."); ``` O método do SDK não recebe `typing`. Para mostrar “digitando”, chame a API REST (aba cURL) ou mande `typing: true` no próximo envio. * n8n **Configurações do nó HTTP Request do n8n** * Método: `POST` * URL: `https://api.messajo.com/v1/messages/msg_.../read` * Autenticação: Generic Credential Type, depois Header Auth. Nome: `Authorization`; Valor: `Bearer mj_...` * Cabeçalhos: ative Send Headers e adicione `Idempotency-Key` (um valor único por item) * Corpo: ative Send Body; Body Content Type: JSON; Specify Body: Using JSON ```json { "typing": true } ``` Substitua mj\_... pela sua chave de API. A resposta traz o id e a confirmação: ```json { "id": "msg_...", "read": true } ``` ## Campos [Seção intitulada “Campos”](#campos) | Campo | Descrição | | -------------------------- | ------------------------------------------ | | `id` (caminho) | Id `msg_…` da mensagem recebida. | | `typing` (corpo, opcional) | `true` mostra “digitando”. Padrão `false`. | ## Por canal [Seção intitulada “Por canal”](#por-canal) * **WhatsApp:** o indicador de digitação sempre marca a mensagem como lida. * **Instagram:** `typing: true` mostra “digitando” antes do envio e `POST /v1/messages/{id}/read` marca a conversa como vista. * **Messenger:** usa o mesmo motor do Instagram, veja [Mensagens](/connect/messenger/#mensagens). O `typing` gasta uma ficha do balde do número (veja [Limites](/api/limits/)). ## Erros comuns [Seção intitulada “Erros comuns”](#erros-comuns) * [`not_found`](/errors#not_found) (404): o `id` não existe. * [`connection_rate_limited`](/errors#connection_rate_limited) (429): sem ficha no balde. Espere o `Retry-After` e repita. # Enviar reação > Reaja a uma mensagem com um emoji, ou remova a reação, com POST /v1/messages no WhatsApp, no Instagram e no Messenger. `POST /v1/messages` com `type: "reaction"` coloca um emoji numa mensagem que já existe na conversa. Funciona no WhatsApp, no Instagram e no Messenger. Os campos que valem para todos os envios estão em [Campos comuns](/send/text/#campos-comuns). ## Antes de começar [Seção intitulada “Antes de começar”](#antes-de-começar) * Uma chave de API com a permissão `send` (veja [Autenticação](/api/authentication/)). * Uma conexão **Ativa** do canal. * Reação segue a janela de atendimento: fora das 24 horas ([janelas](/api/limits/#janelas)) o envio é recusado. ## Reagir a uma mensagem [Seção intitulada “Reagir a uma mensagem”](#reagir-a-uma-mensagem) * cURL ```bash curl https://api.messajo.com/v1/messages \ -H "Authorization: Bearer $MESSAJO_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{ "connection_id": "conn_...", "to": "5511999999999", "type": "reaction", "reaction": { "message_id": "msg_...", "emoji": "👍" } }' ``` * TypeScript ```ts import { Messajo } from "@messajo/sdk"; const messajo = new Messajo({ apiKey: process.env.MESSAJO_API_KEY! }); const sent = await messajo.messages.send({ "connection_id": "conn_...", "to": "5511999999999", "type": "reaction", "reaction": { "message_id": "msg_...", "emoji": "👍" } }); ``` * n8n **Configurações do nó HTTP Request do n8n** * Método: `POST` * URL: `https://api.messajo.com/v1/messages` * Autenticação: Generic Credential Type, depois Header Auth. Nome: `Authorization`; Valor: `Bearer mj_...` * Cabeçalhos: ative Send Headers e adicione `Idempotency-Key` (um valor único por item) * Corpo: ative Send Body; Body Content Type: JSON; Specify Body: Using JSON ```json { "connection_id": "conn_...", "to": "5511999999999", "type": "reaction", "reaction": { "message_id": "msg_...", "emoji": "👍" } } ``` Substitua mj\_... pela sua chave de API. ## Remover a reação [Seção intitulada “Remover a reação”](#remover-a-reação) Para tirar a reação, envie o mesmo corpo com `emoji` vazio. * cURL ```bash curl https://api.messajo.com/v1/messages \ -H "Authorization: Bearer $MESSAJO_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{ "connection_id": "conn_...", "to": "5511999999999", "type": "reaction", "reaction": { "message_id": "msg_...", "emoji": "" } }' ``` * TypeScript ```ts import { Messajo } from "@messajo/sdk"; const messajo = new Messajo({ apiKey: process.env.MESSAJO_API_KEY! }); const sent = await messajo.messages.send({ "connection_id": "conn_...", "to": "5511999999999", "type": "reaction", "reaction": { "message_id": "msg_...", "emoji": "" } }); ``` * n8n **Configurações do nó HTTP Request do n8n** * Método: `POST` * URL: `https://api.messajo.com/v1/messages` * Autenticação: Generic Credential Type, depois Header Auth. Nome: `Authorization`; Valor: `Bearer mj_...` * Cabeçalhos: ative Send Headers e adicione `Idempotency-Key` (um valor único por item) * Corpo: ative Send Body; Body Content Type: JSON; Specify Body: Using JSON ```json { "connection_id": "conn_...", "to": "5511999999999", "type": "reaction", "reaction": { "message_id": "msg_...", "emoji": "" } } ``` Substitua mj\_... pela sua chave de API. ## Campos [Seção intitulada “Campos”](#campos) | Campo | Regra | | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | `reaction.message_id` | A mensagem alvo: o id do Messajo (`msg_…`) ou o id da Meta. O Messajo troca o `msg_…` pelo id da Meta antes de enviar. De 1 a 256 caracteres. | | `reaction.emoji` | Até 16 caracteres. Texto vazio (`""`) remove a reação. | ## Curtida no Instagram [Seção intitulada “Curtida no Instagram”](#curtida-no-instagram) No Instagram, `type: "like"` envia o coração, sem corpo. Só existe no Instagram. ## Erros comuns [Seção intitulada “Erros comuns”](#erros-comuns) * [`not_found`](/errors#not_found) (404): o `msg_…` informado em `message_id` não existe. * [`outside_service_window`](/errors#outside_service_window) (422): fora das 24 horas. O fim da janela vem em `details[0].message`. * [`validation_failed`](/errors#validation_failed) (400): `emoji` com mais de 16 caracteres ou campo desconhecido. # Enviar figurinha > Envie uma figurinha (sticker) WebP, estática ou animada, por WhatsApp. Envie uma figurinha em `POST /v1/messages` com `type: "sticker"`. Só o WhatsApp aceita esse tipo. Os campos comuns a todos os tipos (`to`, `reply_to`, `typing`, `delay_ms`, janela de 24 h) estão em [Campos comuns](/send/text/#campos-comuns). * cURL ```bash curl -X POST https://api.messajo.com/v1/messages \ -H "Authorization: Bearer $MESSAJO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "connection_id": "con_123", "to": "5511999990000", "type": "sticker", "sticker": { "link": "https://cdn.exemplo.com/joia.webp" } }' ``` * TypeScript ```ts import { Messajo } from "@messajo/sdk"; const messajo = new Messajo({ apiKey: process.env.MESSAJO_API_KEY! }); const message = await messajo.messages.send({ connection_id: "con_123", to: "5511999990000", type: "sticker", sticker: { link: "https://cdn.exemplo.com/joia.webp" }, }); console.log(message.id, message.status); ``` * n8n **Configurações do nó HTTP Request do n8n** * Método: `POST` * URL: `https://api.messajo.com/v1/messages` * Autenticação: Generic Credential Type, depois Header Auth. Nome: `Authorization`; Valor: `Bearer mj_...` * Cabeçalhos: ative Send Headers e adicione `Idempotency-Key` (um valor único por item) * Corpo: ative Send Body; Body Content Type: JSON; Specify Body: Using JSON ```json { "connection_id": "con_123", "to": "5511999990000", "type": "sticker", "sticker": { "link": "https://cdn.exemplo.com/joia.webp" } } ``` Substitua mj\_... pela sua chave de API. A resposta é `201` com `id` (`msg_…`), `status: "queued"` e `conversation_id`. O estado final chega por webhook. ## Link ou upload [Seção intitulada “Link ou upload”](#link-ou-upload) Informe **exatamente um** entre `link` e `media_id`. Mandar os dois, ou nenhum, devolve `400 validation_failed` com `exactly one of media_id or link is required`. Figurinha não tem legenda. * `link`: URL do arquivo `.webp`. * `media_id` (`med_…`): vem de `POST /v1/media`, um `multipart/form-data` com `file` (e `connection_id`, exceto com chave de conexão `mjc_…`). Exige a permissão `send`. O tipo é lido dos bytes do arquivo, não da extensão. - cURL ```bash curl -X POST https://api.messajo.com/v1/media \ -H "Authorization: Bearer $MESSAJO_API_KEY" \ -F connection_id=con_123 \ -F file=@joia.webp ``` - TypeScript ```ts import { readFile } from "node:fs/promises"; const media = await messajo.media.upload({ file: new Blob([await readFile("joia.webp")]), connection_id: "con_123", }); await messajo.messages.send({ connection_id: "con_123", to: "5511999990000", type: "sticker", sticker: { media_id: media.id }, }); ``` O upload devolve o `id` da mídia (`med_…`), que você usa em `sticker.media_id`. ## Formato e tamanho [Seção intitulada “Formato e tamanho”](#formato-e-tamanho) Só **WebP**. O upload detecta no arquivo se a figurinha é animada: | Tipo | Tamanho máximo | | -------- | -------------- | | Estática | 100 KiB | | Animada | 500 KiB | Acima do limite, o upload devolve `413 media_too_large`. ## Instagram e Messenger [Seção intitulada “Instagram e Messenger”](#instagram-e-messenger) Não aceitam figurinha: `type: "sticker"` devolve `422 type_not_supported_by_channel`. ## Erros [Seção intitulada “Erros”](#erros) | Código | Status | Quando | | ------------------------------- | ------ | ------------------------------------------------ | | `validation_failed` | 400 | `link` e `media_id` juntos, ou nenhum dos dois | | `media_too_large` | 413 | Acima de 100 KiB (estática) ou 500 KiB (animada) | | `media_type_not_supported` | 415 | Arquivo que não é WebP | | `media_error` | 422 | A Meta não conseguiu processar a mídia | | `type_not_supported_by_channel` | 422 | Instagram ou Messenger | | `outside_service_window` | 422 | Mensagem livre fora da janela de 24 h | # Enviar texto > Envie uma mensagem de texto com POST /v1/messages por WhatsApp, Instagram ou Messenger, com prévia de link, resposta, "digitando" e atraso. `POST /v1/messages` com `type: "text"` envia texto livre. Funciona no WhatsApp, no Instagram e no Messenger. ## Antes de começar [Seção intitulada “Antes de começar”](#antes-de-começar) * Uma chave de API com a permissão `send` (veja [Autenticação](/api/authentication/)). * Uma conexão **Ativa** do canal que você vai usar. * Mensagem livre só sai dentro da janela de 24 horas depois da última mensagem do contato (veja [Janelas](/api/limits/#janelas)). Fora dela, use um template. ## Enviar um texto [Seção intitulada “Enviar um texto”](#enviar-um-texto) * cURL ```bash curl https://api.messajo.com/v1/messages \ -H "Authorization: Bearer $MESSAJO_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{ "connection_id": "conn_...", "to": "5511999999999", "type": "text", "text": { "body": "Olá! Seu pedido saiu para entrega." } }' ``` * TypeScript ```ts import { Messajo } from "@messajo/sdk"; const messajo = new Messajo({ apiKey: process.env.MESSAJO_API_KEY! }); const sent = await messajo.messages.send({ connection_id: "conn_...", to: "5511999999999", type: "text", text: { body: "Olá! Seu pedido saiu para entrega." }, }); ``` * n8n **Configurações do nó HTTP Request do n8n** * Método: `POST` * URL: `https://api.messajo.com/v1/messages` * Autenticação: Generic Credential Type, depois Header Auth. Nome: `Authorization`; Valor: `Bearer mj_...` * Cabeçalhos: ative Send Headers e adicione `Idempotency-Key` (um valor único por item) * Corpo: ative Send Body; Body Content Type: JSON; Specify Body: Using JSON ```json { "connection_id": "conn_...", "to": "5511999999999", "type": "text", "text": { "body": "Olá! Seu pedido saiu para entrega." } } ``` Substitua mj\_... pela sua chave de API. ## Resposta [Seção intitulada “Resposta”](#resposta) A resposta é `201`: ```json { "id": "msg_...", "external_id": "wamid.HBgNNTUxMTk5OTk5OTk5ORUCABEYEjQ", "status": "queued", "meta_status": "accepted", "conversation_id": "cnv_...", "contact_id": "ctc_...", "created_at": "2026-11-09T12:00:00.000Z" } ``` * `id` é o id da mensagem no Messajo (`msg_…`); `external_id` é o da Meta. * `status` sai como `queued`. A entrega e a leitura chegam depois, no evento `message.status`. * `meta_status` é `accepted`, `held_for_quality_assessment`, `paused` ou `null`. ## Prévia de link [Seção intitulada “Prévia de link”](#prévia-de-link) No WhatsApp, `text.preview_url: true` pede que o link da mensagem apareça com prévia. ```json { "type": "text", "text": { "body": "Acompanhe em https://exemplo.com/pedido/123", "preview_url": true } } ``` ## Responder a uma mensagem [Seção intitulada “Responder a uma mensagem”](#responder-a-uma-mensagem) `reply_to` cita uma mensagem anterior. Aceita o id do Messajo (`msg_…`) ou o id da Meta. Um `msg_…` que não existe volta `404` [`not_found`](/errors#not_found). ## Digitando e atraso [Seção intitulada “Digitando e atraso”](#digitando-e-atraso) * `typing: true` mostra o indicador de “digitando” antes de a mensagem sair. * `delay_ms` espera de 0 a 20000 milissegundos antes de enviar (padrão 0). O `typing` também gasta uma ficha do balde do número (veja [Limites](/api/limits/)). ## Campos comuns [Seção intitulada “Campos comuns”](#campos-comuns) Valem para todas as páginas de envio. | Campo | Descrição | | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `connection_id` | Conexão que envia. Opcional com chave de conexão (`mjc_…`); obrigatório com chave de organização (`mj_…`). | | `to` | Destino. WhatsApp: telefone com código do país (só dígitos contam), BSUID, `ctc_…` (contato) ou `grp_…` (grupo). Instagram: IGSID ou `ctc_…`. Messenger: PSID ou `ctc_…`. | | `type` | Tipo da mensagem. Aqui, `text`. | | `reply_to` | Mensagem citada: `msg_…` ou id da Meta. | | `typing` | `true` mostra “digitando” antes do envio. Padrão `false`. | | `delay_ms` | Espera antes do envio, de 0 a 20000. Padrão 0. | | `biz_opaque_callback_data` | WhatsApp: texto de até 512 caracteres devolvido junto do status. | | `tag` | `"human_agent"`, só no Instagram e no Messenger. No WhatsApp volta `422` [`tag_not_supported_by_channel`](/errors#tag_not_supported_by_channel). | | Cabeçalho `Idempotency-Key` | Evita envio duplicado ao repetir a chamada; vale 24 horas (veja [Idempotência](/start/concepts/#idempot%C3%AAncia)). | Campo desconhecido no corpo é recusado com `400` [`validation_failed`](/errors#validation_failed). ## Limites e canais [Seção intitulada “Limites e canais”](#limites-e-canais) | Canal | Tamanho do texto | | --------- | -------------------- | | WhatsApp | 1 a 4096 caracteres | | Instagram | até 1.000 bytes | | Messenger | até 2.000 caracteres | No Instagram e no Messenger, `text.quick_replies` aceita de 1 a 13 itens `{ "title", "payload" }`, com `title` de até 20 e `payload` de até 1000 caracteres. `text.preview_url` é do WhatsApp. ## Grupos [Seção intitulada “Grupos”](#grupos) Com `to: "grp_…"` o WhatsApp aceita texto, mídia e template. Veja [Grupos](/guides/groups/). ## Erros comuns [Seção intitulada “Erros comuns”](#erros-comuns) * [`outside_service_window`](/errors#outside_service_window) (422): fora das 24 horas. O fim da janela vem em `details[0].message`. * [`connection_rate_limited`](/errors#connection_rate_limited) (429): sem ficha no balde do número. Espere o `Retry-After` (ou `retry_after_ms`) e repita. * [`pair_rate_limited`](/errors#pair_rate_limited) (429): mensagens demais para o mesmo contato em pouco tempo. * [`recipient_unavailable`](/errors#recipient_unavailable) (422): a Meta não conseguiu entregar a esse destino. * [`type_not_supported_by_channel`](/errors#type_not_supported_by_channel) (422): o canal não aceita esse tipo. * [`meta_unknown_outcome`](/errors#meta_unknown_outcome) (502): não se sabe se a mensagem saiu. Não reenvie às cegas; confira antes. * [`connection_needs_reconnect`](/errors#connection_needs_reconnect) (409): a conexão perdeu o acesso e precisa ser reconectada. # Enviar vídeo > Envie um vídeo com legenda opcional por WhatsApp, Instagram ou Messenger. Envie um vídeo em `POST /v1/messages` com `type: "video"`. Os campos comuns a todos os tipos (`to`, `reply_to`, `typing`, `delay_ms`, janela de 24 h) estão em [Campos comuns](/send/text/#campos-comuns). * cURL ```bash curl -X POST https://api.messajo.com/v1/messages \ -H "Authorization: Bearer $MESSAJO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "connection_id": "con_123", "to": "5511999990000", "type": "video", "video": { "link": "https://cdn.exemplo.com/video.mp4", "caption": "Como montar" } }' ``` * TypeScript ```ts import { Messajo } from "@messajo/sdk"; const messajo = new Messajo({ apiKey: process.env.MESSAJO_API_KEY! }); const message = await messajo.messages.send({ connection_id: "con_123", to: "5511999990000", type: "video", video: { link: "https://cdn.exemplo.com/video.mp4", caption: "Como montar" }, }); console.log(message.id, message.status); ``` * n8n **Configurações do nó HTTP Request do n8n** * Método: `POST` * URL: `https://api.messajo.com/v1/messages` * Autenticação: Generic Credential Type, depois Header Auth. Nome: `Authorization`; Valor: `Bearer mj_...` * Cabeçalhos: ative Send Headers e adicione `Idempotency-Key` (um valor único por item) * Corpo: ative Send Body; Body Content Type: JSON; Specify Body: Using JSON ```json { "connection_id": "con_123", "to": "5511999990000", "type": "video", "video": { "link": "https://cdn.exemplo.com/video.mp4", "caption": "Como montar" } } ``` Substitua mj\_... pela sua chave de API. A resposta é `201` com `id` (`msg_…`), `status: "queued"` e `conversation_id`. O estado final chega por webhook. ## Link ou upload [Seção intitulada “Link ou upload”](#link-ou-upload) Informe **exatamente um** entre `link` e `media_id`. Mandar os dois, ou nenhum, devolve `400 validation_failed` com `exactly one of media_id or link is required`. * `link`: URL do vídeo. * `media_id` (`med_…`): vem de `POST /v1/media`, um `multipart/form-data` com `file` (e `connection_id`, exceto com chave de conexão `mjc_…`). Exige a permissão `send`. O tipo é lido dos bytes do arquivo, não da extensão. - cURL ```bash curl -X POST https://api.messajo.com/v1/media \ -H "Authorization: Bearer $MESSAJO_API_KEY" \ -F connection_id=con_123 \ -F file=@video.mp4 ``` - TypeScript ```ts import { readFile } from "node:fs/promises"; const media = await messajo.media.upload({ file: new Blob([await readFile("video.mp4")]), connection_id: "con_123", }); await messajo.messages.send({ connection_id: "con_123", to: "5511999990000", type: "video", video: { media_id: media.id }, }); ``` O upload devolve o `id` da mídia (`med_…`), que você usa em `video.media_id`. ## WhatsApp [Seção intitulada “WhatsApp”](#whatsapp) * `video.caption`: legenda de até 1024 caracteres. * Upload: até **16 MiB**. O upload reconhece os contêineres `video/mp4` e `video/3gpp`. ## Instagram e Messenger [Seção intitulada “Instagram e Messenger”](#instagram-e-messenger) O corpo é o mesmo, com duas diferenças: * `link` precisa ser `https`. * Não existe `caption`. Enviar legenda devolve `422 type_not_supported_by_channel` apontando `video.caption`. Mande a legenda como mensagem de texto à parte. | Canal | Tamanho máximo | Formatos | | --------- | -------------- | ---------------------------------------------------------------------------- | | Instagram | 25 MiB | `video/mp4`, `video/ogg`, `video/x-msvideo`, `video/quicktime`, `video/webm` | | Messenger | 25 MiB | `video/mp4` | ## Erros [Seção intitulada “Erros”](#erros) | Código | Status | Quando | | ------------------------------- | ------ | ---------------------------------------------- | | `validation_failed` | 400 | `link` e `media_id` juntos, ou nenhum dos dois | | `media_too_large` | 413 | Arquivo acima do limite | | `media_type_not_supported` | 415 | Formato que o canal não aceita | | `media_error` | 422 | A Meta não conseguiu processar a mídia | | `type_not_supported_by_channel` | 422 | `caption` no Instagram ou Messenger | | `outside_service_window` | 422 | Mensagem livre fora da janela de 24 h | Detalhes de cada código no [catálogo de erros](/errors/). # Problemas na coexistência > O que fazer quando a conexão em coexistência não conclui, não sincroniza ou cai. Cada sintoma abaixo segue o mesmo formato: o que você vê, a causa e o que fazer. O passo a passo da conexão está em [Conectar o WhatsApp](/connect/whatsapp/). ## Antes de conectar [Seção intitulada “Antes de conectar”](#antes-de-conectar) * O número está ativo no app WhatsApp Business **2.24.17 ou mais novo**. * Você é admin do portfólio de negócios na Meta. * No painel, você é dono ou admin, com o 2FA ligado. ## O número não está no app WhatsApp Business [Seção intitulada “O número não está no app WhatsApp Business”](#o-número-não-está-no-app-whatsapp-business) * **Sintoma:** `422` [`coex_not_on_business_app`](/errors#coex_not_on_business_app). * **Causa:** na coexistência o número precisa estar no app WhatsApp Business do celular, e este não está. * **O que fazer:** instale e ative o número no app WhatsApp Business, ou conecte no modo **Número novo, só pela API**. ## A janela da Meta terminou sem número [Seção intitulada “A janela da Meta terminou sem número”](#a-janela-da-meta-terminou-sem-número) * **Sintoma:** [`signup_incomplete`](/errors#signup_incomplete). A janela criou ou escolheu a conta, mas não terminou com exatamente um número. * **O que fazer:** conecte de novo e escolha (ou adicione) o número na janela da Meta até o fim. ## A sessão expirou [Seção intitulada “A sessão expirou”](#a-sessão-expirou) * **Sintoma:** [`signup_session_expired`](/errors#signup_session_expired) (`410`). * **Causa:** a sessão de conexão dura 30 minutos e acabou, ou foi cancelada. * **O que fazer:** comece de novo pelo painel ou pelo link de conexão. ## Faltaram permissões [Seção intitulada “Faltaram permissões”](#faltaram-permissões) * **Sintoma:** [`signup_scope_mismatch`](/errors#signup_scope_mismatch). * **Causa:** a janela da Meta terminou sem as permissões para gerenciar e enviar mensagens pela conta. * **O que fazer:** conecte de novo e mantenha todas as permissões marcadas. ## O popup não abre [Seção intitulada “O popup não abre”](#o-popup-não-abre) * **Causa:** o navegador bloqueou o popup da Meta. * **O que fazer:** libere popups do endereço do painel e tente de novo. Não feche a página do painel enquanto o popup estiver aberto. ## Conta banida ou sinalizada [Seção intitulada “Conta banida ou sinalizada”](#conta-banida-ou-sinalizada) * **Sintoma:** `403` [`account_flagged`](/errors#account_flagged). * **Causa:** a Meta baniu ou sinalizou a conta. O Messajo recusa antes de alterar qualquer coisa na Meta. * **O que fazer:** resolva com a Meta no Gerenciador do WhatsApp. Depois de liberada, conecte de novo. ## Número já conectado [Seção intitulada “Número já conectado”](#número-já-conectado) * **Sintoma:** `409` [`connection_already_exists`](/errors#connection_already_exists) ou [`waba_owned_by_other_org`](/errors#waba_owned_by_other_org). * **Causa:** o número já tem uma conexão ativa, na sua organização ou em outra. Uma conta do WhatsApp Business (WABA) pertence a uma organização só. * **O que fazer:** use a conexão existente. Para mover para outra organização, desconecte lá primeiro. ## O número já está com outro parceiro [Seção intitulada “O número já está com outro parceiro”](#o-número-já-está-com-outro-parceiro) * **Causa:** na coexistência o número aceita um parceiro por vez. * **O que fazer:** 1. Faça backup das conversas no app. 2. No app, vá em **Configurações > Conta > Plataforma Business > Desconectar**. 3. Conecte de novo pelo Messajo. * O parceiro antigo recebe o aviso `PARTNER_REMOVED` da Meta. ## A conexão ficou Pendente [Seção intitulada “A conexão ficou Pendente”](#a-conexão-ficou-pendente) * **Causa:** um passo depois da inscrição falhou. O painel mostra o motivo. * **O que fazer:** na página da conexão, **Concluir conexão** refaz o que faltou, sem abrir o popup. A aba **Histórico** mostra cada passo, inclusive onde um cancelamento no popup aconteceu. ## Histórico ou contatos não vieram [Seção intitulada “Histórico ou contatos não vieram”](#histórico-ou-contatos-não-vieram) Abra a aba **Sincronização** da conexão. | Status | O que fazer | | ------------------------- | ---------------------------------------------------------------------------- | | **Na fila** | Aguarde. Ainda não foi pedida ou vai ser pedida de novo depois de uma falha | | **Pedida à Meta** | Aguarde. A Meta aceitou e está mandando os dados | | **Concluída** | Os dados chegaram: contatos em `contacts.sync`, conversas em `history.batch` | | **Recusada** | A pessoa recusou compartilhar o histórico no celular | | **Prazo de 24 h vencido** | A Meta só aceita o pedido até 24 h depois da conexão | A sincronização é pedida uma vez só. Se falhar, o Messajo tenta de novo em 1 min, 5 min, 15 min, 1 h, 3 h e 6 h, sempre dentro das 24 h. Grupos não sincronizam. ## A conexão caiu sozinha [Seção intitulada “A conexão caiu sozinha”](#a-conexão-caiu-sozinha) * **O app precisa ser aberto a cada \~14 dias**, uma regra da Meta para todo número em coexistência. * **O número saiu do app WhatsApp Business:** a conexão manda `connection.updated` com `reason` `coex_unlinked`. * **A conta removeu o Messajo como parceiro:** a conexão fica **Desconectada** com `reason` `partner_removed`. Os motivos e o que fazer em cada status estão em [Quando a conexão cai](/connect/whatsapp/#quando-a-conex%C3%A3o-cai) e em [Motivos da conexão](/webhooks/events/#motivos-da-conex%C3%A3o). ## Não consigo editar perfil, nome ou username pela API [Seção intitulada “Não consigo editar perfil, nome ou username pela API”](#não-consigo-editar-perfil-nome-ou-username-pela-api) * **Sintoma:** `422` [`coex_not_supported`](/errors#coex_not_supported). * **Causa:** na coexistência a Meta não deixa a API mudar o perfil, o nome exibido nem o username. * **O que fazer:** altere no app WhatsApp Business do celular, ou use um número só API. ## Limites que parecem bug [Seção intitulada “Limites que parecem bug”](#limites-que-parecem-bug) * **Velocidade fixa de 20 msg/s.** Passou disso, `429` `connection_rate_limited` com `Retry-After`. Veja [Limites](/api/limits/). * **Ligações:** [`calling_not_supported_in_coex`](/errors#calling_not_supported_in_coex). Use um número só API. * **Grupos:** [`group_not_supported`](/errors#group_not_supported). Use um número só API. * **Mensagem enviada pelo celular** chega como `message.echo` e **não abre** a janela de 24 h: só a mensagem do contato abre. Veja [Janelas](/api/limits/#janelas). # Número restrito ou banido > Como reconhecer e tratar um número restrito, bloqueado ou banido pela Meta. Cada sintoma abaixo segue o mesmo formato: o que você vê, a causa e o que fazer. ## Onde ver o que está acontecendo [Seção intitulada “Onde ver o que está acontecendo”](#onde-ver-o-que-está-acontecendo) Na página da conexão, aba **Visão geral**, o card **Saúde** mostra: * **Qualidade**, **Faixa de envio** e **Velocidade**; * **Envio**: Liberado, Limitado ou Bloqueado; * **Restrição**, com o prazo (`Até {data}`) ou “Sem prazo informado”; * a lista **O que está bloqueado ou limitado**, agrupada por **Número**, **Conta do WhatsApp**, **Empresa** e **App**, cada item com o código da Meta, a descrição e a solução sugerida; * **O que continua funcionando**. O Messajo lê a saúde a cada 15 minutos. **Atualizar saúde** lê na hora. ## A conexão aparece como Restrita ou Desativada [Seção intitulada “A conexão aparece como Restrita ou Desativada”](#a-conexão-aparece-como-restrita-ou-desativada) | Status | Motivo (`reason`) | O que fazer | | -------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | | **Restrita** | `account_restriction`: a Meta restringiu a conta por um prazo | Esperar o prazo e corrigir a causa no Gerenciador do WhatsApp | | **Restrita** | `policy_blocked`: a Meta bloqueou um envio por política (`368` ou `131031`) | Idem | | **Desativada** | `violation:` ou `banned` | Recorrer na Meta. Se ela reativar (`reinstated`), a conexão volta a **Ativa** sozinha | | **Ativa** | `restriction_lifted`: a restrição acabou | Nada | `scheduled_for_disable` avisa antes: a Meta agendou a desativação da conta, sem mudar o status. Enquanto a conexão está restrita, os envios voltam `403` [`policy_blocked`](/errors#policy_blocked) ou `409` [`connection_restricted`](/errors#connection_restricted). Desativada, `409` [`connection_disabled`](/errors#connection_disabled). ## Envio Limitado ou Bloqueado, sem mudar o status [Seção intitulada “Envio Limitado ou Bloqueado, sem mudar o status”](#envio-limitado-ou-bloqueado-sem-mudar-o-status) A conexão segue **Ativa**, mas o **Envio** mudou. O Messajo emite `connection.updated` com `reason` `can_send_changed`. Os casos que o painel explica: * **Sem forma de pagamento** (código `141006`): a empresa não pode iniciar conversas (templates). Respostas a clientes que escreveram nas últimas 24 h continuam funcionando. Ação: **Adicionar forma de pagamento** no Meta Business. * **Empresa não verificada** (código `141010`): limites de envio menores. Os envios dentro do limite atual continuam. Ação: verificar a empresa. Para o erro de envio por falta de pagamento, veja também [`meta_payment_required`](/errors#meta_payment_required). ## Qualidade ou faixa de envio mudaram [Seção intitulada “Qualidade ou faixa de envio mudaram”](#qualidade-ou-faixa-de-envio-mudaram) O Messajo emite `connection.updated` com `reason` `quality_changed` (qualidade) ou `limit_changed` (faixa de envio ou capacidade). Entenda a faixa em [Limite de mensagens da Meta](/api/limits/#limite-de-mensagens-da-meta). ## Sinais de spam nos envios [Seção intitulada “Sinais de spam nos envios”](#sinais-de-spam-nos-envios) * `429` [`meta_spam_rate_limited`](/errors#meta_spam_rate_limited) (Meta `131048`): muitas mensagens do número foram denunciadas ou bloqueadas. **Não reenvie.** As campanhas pausam sozinhas. Revise a lista (só quem deu opt-in), o conteúdo do template e a frequência, e espere a qualidade se recuperar. * `422` [`marketing_limit_reached`](/errors#marketing_limit_reached) (Meta `131049`): a Meta segurou o template de marketing para proteger o engajamento do contato. Não reenvie na hora. ## O que o Messajo faz sozinho [Seção intitulada “O que o Messajo faz sozinho”](#o-que-o-messajo-faz-sozinho) * Manda e-mail para donos e admins a cada mudança de status (no máximo um por motivo a cada 6 h). * Emite eventos `connection.*` com o motivo em `reason`. ## O que o Messajo não faz [Seção intitulada “O que o Messajo não faz”](#o-que-o-messajo-não-faz) Não levanta restrição nem reverte banimento. Recursos e contestações são feitos nas ferramentas da Meta, no Gerenciador do WhatsApp. ## Receber o aviso no seu sistema [Seção intitulada “Receber o aviso no seu sistema”](#receber-o-aviso-no-seu-sistema) Crie um [destino](/webhooks/destinations/#global-ou-por-conex%C3%A3o) global que assine os eventos de conexão: ```json { "connection_id": null, "event_types": ["connection.*", "org.*"] } ``` Cada evento traz `data.connection.status`, `previous_status` e `reason`. A tabela completa está em [Motivos da conexão](/webhooks/events/#motivos-da-conex%C3%A3o). # Falhas de envio: pagamento e templates > Por que um envio falha por forma de pagamento ou por template, e como corrigir. Cada sintoma abaixo segue o mesmo formato: o que você vê, a causa e o que fazer. Os textos de significado e ação são os mesmos do [catálogo de erros](/errors/). ## Como ler uma falha de envio [Seção intitulada “Como ler uma falha de envio”](#como-ler-uma-falha-de-envio) Há dois caminhos para uma falha: * **Na resposta de `POST /v1/messages`.** O erro vem no [formato padrão](/errors/#formato-do-erro): `code`, `meta_code` (o código original da Meta, quando o erro veio dela), `details`, `retryable`, `retry_after_ms` nos erros de limite, `request_id` e `docs_url`. Trate o erro pelo `code`, nunca pelo texto de `message`. Num erro da Meta, `details[0].message` traz o detalhe que ela mandou. * **Depois, pelo webhook.** A Meta pode aceitar o envio e falhar mais tarde. Nesse caso chega o evento `message.status` com o status `failed`. Veja [Eventos](/webhooks/events/). Repita só quando `retryable` for `true`. A tabela no fim da página resume cada código. ## Pagamento [Seção intitulada “Pagamento”](#pagamento) **Você vê:** `402` [`meta_payment_required`](/errors#meta_payment_required), com `meta_code` 131042. **Causa:** a conta do WhatsApp Business está sem forma de pagamento válida, o pagamento falhou ou o limite de crédito acabou. A cobrança das mensagens é da Meta, não do Messajo. **O que fazer:** ajuste a forma de pagamento no Gerenciador de Negócios da Meta. No painel, o card **Saúde** da conexão mostra o mesmo problema com o código 141006 e a ação **Adicionar forma de pagamento**. Enquanto isso, respostas a clientes que escreveram nas últimas 24 h continuam funcionando; templates, que iniciam conversas, não. ## O template não sai [Seção intitulada “O template não sai”](#o-template-não-sai) **Você vê:** `422` [`template_error`](/errors#template_error), com `meta_code` 132000, 132001, 132005, 132007, 132012, 132015, 132016, 132068 ou 132069. **Causa:** o template não existe nesse idioma, os parâmetros não batem em quantidade ou formato, o texto passou do limite, ou ele está pausado ou desativado. **O que fazer:** leia `details[].message` e `meta_code`. Confira nome, idioma e parâmetros em **Templates**; um template pausado ou desativado precisa ser editado. Veja [Templates](/guides/templates/). **Você vê:** `404` [`template_not_found`](/errors#template_not_found). **Causa:** não há template com esse id, ou com esse nome e idioma, nesta conta do WhatsApp Business. **O que fazer:** confira nome e idioma, ou sincronize a lista com `POST /v1/templates/sync`. **Você vê:** `422` [`otp_template_invalid`](/errors#otp_template_invalid). **Causa:** o template de autenticação citado não existe ou não está `APPROVED`. **O que fazer:** crie o template em `POST /v1/templates/authentication` e espere a aprovação antes de mandar códigos. Veja [Templates de autenticação](/guides/authentication-templates/). **Você vê:** o template continua `PENDING` ou aparece como `REJECTED`. **Causa:** só template aprovado pode ser enviado. O status vem da Meta e chega no evento `template.status`. **O que fazer:** espere a aprovação, ou edite o template rejeitado e reenvie para revisão. Veja o [ciclo de vida](/guides/templates/#ciclo-de-vida). **Em campanhas,** dois códigos extras podem aparecer. [`campaign_template_not_approved`](/errors#campaign_template_not_approved): o template não está `APPROVED` ou é de uma categoria que não entra em campanha (só `MARKETING` e `UTILITY`). [`campaign_template_mapping_invalid`](/errors#campaign_template_mapping_invalid): algum parâmetro ficou sem fonte no `variable_mapping`; `details` mostra o `path` de cada um. Veja [Campanhas](/guides/campaigns/). ## O template de marketing não chega [Seção intitulada “O template de marketing não chega”](#o-template-de-marketing-não-chega) **Você vê:** `422` [`marketing_limit_reached`](/errors#marketing_limit_reached), com `meta_code` 131049. **Causa:** a Meta segurou o template de marketing para manter o engajamento do contato saudável (limite por usuário). **O que fazer:** não reenvie em seguida. Espere alguns dias ou mande algo que o contato peça; reenvio imediato não passa. **Você vê:** `429` [`meta_spam_rate_limited`](/errors#meta_spam_rate_limited), com `meta_code` 131048. **Causa:** muitas mensagens deste número foram denunciadas ou bloqueadas. Campanhas pausam sozinhas com este erro. **O que fazer:** não reenvie. Revise a lista (só quem pediu para receber), o conteúdo do template e a frequência, e espere a qualidade do número voltar antes de retomar. ## Fora da janela [Seção intitulada “Fora da janela”](#fora-da-janela) **Você vê:** `422` [`outside_service_window`](/errors#outside_service_window), com `meta_code` 131047. **Causa:** o contato não manda mensagem há mais de 24 h (72 h se veio de anúncio), e só template pode abrir a conversa. O fim da janela vem em `details[0].message`. **O que fazer:** envie um template aprovado. Quando o contato responder, a janela abre de novo. Veja [Janelas](/api/limits/#janelas). ## Destinatário [Seção intitulada “Destinatário”](#destinatário) **Você vê:** `422` [`recipient_unavailable`](/errors#recipient_unavailable), com `meta_code` 131026. **Causa:** o número não tem WhatsApp, o app do contato está desatualizado ou ele não aceitou os termos novos. **O que fazer:** confira o número com DDI. Não repita em seguida: o resultado é o mesmo até o destinatário resolver do lado dele. **Você vê:** `422` [`recipient_not_allowed`](/errors#recipient_not_allowed), com `meta_code` 131030. **Causa:** o número de teste da Meta só envia para os destinatários cadastrados no app dela. **O que fazer:** cadastre o destinatário no painel do app da Meta ou conecte um número de verdade. ## Vazão [Seção intitulada “Vazão”](#vazão) **Você vê:** `429` [`connection_rate_limited`](/errors#connection_rate_limited). **Causa:** o número já envia na velocidade máxima da faixa dele (20 msg/s na coexistência, 80 ou 1000 msg/s só na API). O `typing` também gasta uma vaga. **O que fazer:** espere `retry_after_ms` e repita. Nada fica na fila: quem repete é a sua integração. Veja [Limites](/api/limits/#envio-por-n%C3%BAmero). **Você vê:** `429` [`pair_rate_limited`](/errors#pair_rate_limited), com `meta_code` 131056. **Causa:** o limite por par (este número e este contato) foi atingido. Outros contatos não são afetados. **O que fazer:** espere `retry_after_ms` (6 s) antes de mandar de novo para o mesmo contato. **Você vê:** `429` [`meta_rate_limited`](/errors#meta_rate_limited), com `meta_code` 130429, 80007 ou 4. **Causa:** a Meta recusou por limite de vazão do número, da conta ou do app, sem processar o pedido. **O que fazer:** espere `retry_after_ms` (ou o cabeçalho `Retry-After`) e repita. ## Conexão [Seção intitulada “Conexão”](#conexão) **Você vê:** `409` com um destes códigos. | Código | Causa | O que fazer | | ------------------------------------------------------------------------------------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------ | | [`connection_needs_reconnect`](/errors#connection_needs_reconnect) (`meta_code` 190 ou 102) | O token da Meta foi revogado ou expirou. | Reconecte pelo painel ou pelo link do e-mail que enviamos. Nada sai até reconectar. | | [`connection_restricted`](/errors#connection_restricted) | A Meta restringiu a conexão. | Veja [Número restrito ou banido](/troubleshooting/number-restricted/). | | [`connection_disabled`](/errors#connection_disabled) | A Meta desativou a conexão. | Veja [Número restrito ou banido](/troubleshooting/number-restricted/). | | [`connection_disconnected`](/errors#connection_disconnected) | A conexão foi desconectada. | Conecte de novo pelo painel. | | [`connection_pending`](/errors#connection_pending) | O cadastro da conexão não terminou. | Conclua a conexão no painel. | | [`number_not_registered`](/errors#number_not_registered) (`meta_code` 133010) | O registro do número na Cloud API falhou ou foi desfeito. | Abra a conexão e use **Tentar registrar de novo**. Se persistir, reconecte o número. | ## Mídia [Seção intitulada “Mídia”](#mídia) **Você vê:** `422` [`media_error`](/errors#media_error) (`meta_code` 131052, 131053 ou 131051), `413` [`media_too_large`](/errors#media_too_large) ou `415` [`media_type_not_supported`](/errors#media_type_not_supported). **Causa:** a Meta não baixou ou não aceitou a mídia: tipo não suportado, arquivo grande demais ou link inacessível. **O que fazer:** leia `details[].message`. Confira tipo e tamanho aceitos (imagem 5 MiB, áudio e vídeo 16 MiB, documento 100 MiB) e, se mandou link, que ele é público e responde rápido. Converta para um formato aceito (JPEG ou PNG, MP4, OGG com Opus, PDF) ou mande como documento. Veja [Enviar imagem](/send/image/). ## Resultado desconhecido [Seção intitulada “Resultado desconhecido”](#resultado-desconhecido) **Você vê:** `502` [`meta_unknown_outcome`](/errors#meta_unknown_outcome). **Causa:** timeout ou falha temporária da Meta num envio. Não dá para saber se a mensagem saiu; ela fica `queued` até o status chegar por webhook. **O que fazer:** não reenvie às cegas. Confirme pelo `message.status` ou com o contato. Repetir com a mesma `Idempotency-Key` devolve o mesmo 502 sem reenviar; para enviar de novo de propósito, use uma chave nova. O SDK nunca repete esse erro (veja [Repetição segura](/sdk/typescript/#repeti%C3%A7%C3%A3o-segura)). ## Repetir ou não [Seção intitulada “Repetir ou não”](#repetir-ou-não) | Código | Status | Repetir? | | ----------------------------------------------------------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------- | | `meta_payment_required` | 402 | Não: corrija o pagamento | | `template_error` | 422 | Não: corrija o template | | `template_not_found` | 404 | Não: corrija o nome ou sincronize | | `otp_template_invalid` | 422 | Não | | `campaign_template_not_approved` | 422 | Não | | `campaign_template_mapping_invalid` | 422 | Não | | `marketing_limit_reached` | 422 | Não | | `meta_spam_rate_limited` | 429 | Não | | `outside_service_window` | 422 | Não: envie um template | | `recipient_unavailable` | 422 | Não | | `recipient_not_allowed` | 422 | Não | | `connection_rate_limited` | 429 | Sim, depois de `retry_after_ms` | | `pair_rate_limited` | 429 | Sim, depois de `retry_after_ms` | | `meta_rate_limited` | 429 | Sim, depois de `retry_after_ms` | | `connection_needs_reconnect` | 409 | Não: reconecte | | `connection_restricted`, `connection_disabled`, `connection_disconnected`, `connection_pending` | 409 | Não | | `number_not_registered` | 409 | Não | | `media_error` | 422 | Não | | `media_too_large` | 413 | Não | | `media_type_not_supported` | 415 | Não | | `meta_unknown_outcome` | 502 | Não às cegas: confirme pelo `message.status`; a mesma `Idempotency-Key` devolve o mesmo 502, para reenviar use chave nova | ## Falar com o suporte [Seção intitulada “Falar com o suporte”](#falar-com-o-suporte) Mande o `request_id` do erro, que é o mesmo valor do cabeçalho `X-Request-Id`. Com ele o suporte acha a chamada exata, sem que você precise mandar a chave. Veja [X-Request-Id para suporte](/api/authentication/#x-request-id-para-suporte). # Webhook não chega > O que conferir quando os eventos não chegam ao seu endpoint. Cada sintoma abaixo segue o mesmo formato: o que você vê, a causa e o que fazer. ## Comece por um teste [Seção intitulada “Comece por um teste”](#comece-por-um-teste) Mande um evento `destination.test` ao destino e veja o resultado. No painel, abra as entregas do destino: cada tentativa guarda o status e os primeiros 1024 bytes da sua resposta. * cURL ```bash curl -X POST https://api.messajo.com/v1/destinations/$DESTINATION_ID/test \ -H "Authorization: Bearer $MESSAJO_API_KEY" ``` * TypeScript ```ts import { Messajo } from "@messajo/sdk"; const messajo = new Messajo({ apiKey: process.env.MESSAJO_API_KEY }); await messajo.destinations.test(destinationId); ``` O teste vai só para esse destino, numa tentativa única, mesmo com ele pausado. ## Nada chega [Seção intitulada “Nada chega”](#nada-chega) * **Destino pausado**, por você ou pela pausa automática (`auto_paused`). Cada evento novo vira uma entrega `failed` com `destination_paused`. Retome o destino e reenvie as falhas ([abaixo](#recuperar-o-que-ficou-para-tr%C3%A1s)). * **Filtro não casa.** Confira `event_types` (`*`, `message.*` ou o tipo exato) e se o destino é de uma conexão ou global (`connection_id: null`). Um destino de conexão só recebe os eventos dela; eventos de organização, como `org.standing_changed`, só chegam a destinos globais. Veja [Filtros](/webhooks/events/#filtros). * **Conexão que não está Ativa.** Confira o status dela no painel. Se estiver Restrita, Desativada ou Desconectada, veja [Número restrito ou banido](/troubleshooting/number-restricted/). * **URL recusada na criação:** `400` [`destination_url_not_allowed`](/errors#destination_url_not_allowed). Rede privada, `http` e host inválido não são aceitos. Use uma URL `https` pública; `details[].message` diz o motivo. ## Chega, mas aparece como falha [Seção intitulada “Chega, mas aparece como falha”](#chega-mas-aparece-como-falha) Sucesso é uma resposta `2xx` em até **10 segundos**, no total. Qualquer outra coisa conta como falha: outro status, tempo esgotado, erro de rede ou endereço bloqueado. Redirecionamento (`3xx`) **não** é seguido e conta como falha. Responda `2xx` rápido e processe depois, numa fila sua. Trabalho pesado dentro da requisição estoura o tempo. ## A assinatura não confere [Seção intitulada “A assinatura não confere”](#a-assinatura-não-confere) As cinco causas de [Erros comuns](/webhooks/verify-signature/#erros-comuns): 1. JSON re-serializado: assine o corpo cru, nunca `JSON.stringify(req.body)`. 2. Relógio fora da tolerância de 5 minutos: sincronize o servidor (NTP). 3. Espaço ou quebra de linha no fim do segredo (comum em `.env`). 4. Segredo sem o prefixo: a chave é o segredo inteiro, **com** `whsec_`. 5. Corpo lido com outro charset: leia os bytes como UTF-8. Durante a [rotação do segredo](/webhooks/verify-signature/#girar-o-segredo-sem-parar) vão dois valores `v1` no cabeçalho, um por segredo ativo. Basta um conferir. ## Evento repetido ou fora de ordem [Seção intitulada “Evento repetido ou fora de ordem”](#evento-repetido-ou-fora-de-ordem) A entrega é **pelo menos uma vez**. Desduplique por `Messajo-Event-Id` (o mesmo `id` do envelope) e, dentro de uma conversa, ordene por `sequence`. Veja [Ordem e duplicatas](/webhooks/events/#ordem-e-duplicatas). ## Quantas vezes ele tenta [Seção intitulada “Quantas vezes ele tenta”](#quantas-vezes-ele-tenta) 1 tentativa imediata e mais 14, ao longo de pouco mais de 23 horas: esperas de 10 s, 30 s, 1 min, 2 min, 5 min, 10 min, 20 min, 40 min, 1 h, 2 h, 3 h, 4 h, 6 h e 6 h. Cada espera varia ±10 % e nenhuma tentativa sai depois de 24 horas da criação da entrega. A tabela completa está em [Tentativas e falhas](/webhooks/events/#tentativas-e-falhas). ## O destino foi pausado sozinho [Seção intitulada “O destino foi pausado sozinho”](#o-destino-foi-pausado-sozinho) O destino é pausado quando junta **10 falhas seguidas** e está falhando há **pelo menos 24 horas**. Qualquer `2xx` zera a contagem. Ao pausar, donos e admins recebem um e-mail. Detalhes em [Pausa automática](/webhooks/events/#pausa-autom%C3%A1tica). ## Recuperar o que ficou para trás [Seção intitulada “Recuperar o que ficou para trás”](#recuperar-o-que-ficou-para-trás) Corrija o endpoint, retome o destino e reenvie as falhas: **Reenviar falhas** no painel, ou a API com `since` (até 1000 por chamada; com `has_more: true`, chame de novo). * cURL ```bash curl -X POST https://api.messajo.com/v1/destinations/$DESTINATION_ID/redeliver-failed \ -H "Authorization: Bearer $MESSAJO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "since": "2026-11-17T00:00:00Z" }' ``` * TypeScript ```ts const { queued, has_more } = await messajo.destinations.redeliverFailed( destinationId, { since: "2026-11-17T00:00:00Z" } ); ``` A resposta é `{ queued, has_more }`. Entregas e eventos ficam guardados por 30 dias. Veja [Lista de falhas e reenvio](/webhooks/events/#lista-de-falhas-e-reenvio). ## Desenvolvendo sem URL pública [Seção intitulada “Desenvolvendo sem URL pública”](#desenvolvendo-sem-url-pública) Se o seu processo não tem URL pública (script, desktop, ambiente local), veja o destino [WebSocket](/webhooks/destinations/#websocket). # Tipos de destino > Webhook, RabbitMQ, SQS, Kafka e WebSocket: configuração, exemplo de consumidor em Node e Python e como verificar a assinatura em cada um. Todo destino recebe o mesmo envelope, com a mesma assinatura, os mesmos [filtros](/webhooks/events/#filtros), as mesmas [tentativas](/webhooks/events/#tentativas-e-falhas), a mesma lista de falhas e a mesma pausa automática. Muda só o transporte. | Tipo | Quando usar | Ligado por padrão | | ----------- | ------------------------------------------------------------------ | ----------------- | | `webhook` | Você tem uma URL HTTPS | sim | | `rabbitmq` | Seus serviços já consomem de um exchange AMQP | não | | `sqs` | Você está na AWS e quer uma fila gerenciada | não | | `kafka` | Você tem um cluster Kafka e quer ordem por conexão | não | | `websocket` | Seu processo não tem URL pública (script, desktop, ambiente local) | não | Tipo desligado não aparece no painel e criar ou editar um destino dele devolve `422` [`destination_type_disabled`](/errors#destination_type_disabled). ## Criar [Seção intitulada “Criar”](#criar) No painel, **Destinos de eventos → Novo destino** e escolha o tipo. Pela API, `POST /v1/destinations` com `type` e um bloco com o nome do tipo: ```bash curl https://api.messajo.com/v1/destinations \ -H "Authorization: Bearer $MESSAJO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "label": "Fila de eventos", "type": "rabbitmq", "rabbitmq": { "url": "amqps://messajo:senha@mq.suaempresa.com:5671/producao", "exchange": "messajo", "routing_key": "messajo.{type}" }, "event_types": ["message.*"], "format": "normalized" }' ``` A resposta traz o segredo de assinatura (`whsec_…`) uma vez só, como no webhook. Senhas e chaves do bloco nunca voltam: a resposta mostra só os 4 últimos caracteres. `POST /v1/destinations/{id}/test` funciona para todos os tipos. Em `routing_key` (RabbitMQ), `message_group_id` (SQS) e `key` (Kafka) valem os marcadores `{type}`, `{family}`, `{connection}`, `{channel}` e `{org}`; o resto é texto fixo. ## Global ou por conexão [Seção intitulada “Global ou por conexão”](#global-ou-por-conexão) Todo destino é de uma conexão ou **global** (da organização). O campo `connection_id` decide: um id é o destino daquela conexão; `null` é o global. * **Por conexão**: recebe só os eventos daquela conexão. Criado no painel da conexão, em **Destinos**. * **Global**: é o webhook da organização. Recebe os eventos sem conexão (`org.standing_changed`), o ciclo de vida das conexões (`connection.*`) e qualquer evento de qualquer conexão que o `event_types` aceitar. Só chave de organização e membro com acesso a todas as conexões criam ou enxergam. O receptor separa as conexões pelo campo `connection` do envelope. O global casa uma vez por evento. Dois filtros de exemplo: ```json { "connection_id": null, "event_types": ["connection.*", "org.*"] } ``` Global só com os eventos da organização: ciclo de vida das conexões e situação da conta. ```json { "connection_id": null, "event_types": ["*"] } ``` Global com todos os eventos de todas as conexões. `connection_ids` (lista) é um apelido **obsoleto** de `connection_id`: aceita `null` ou um único id. Mais de um id devolve `400` `validation_failed`; crie um destino por conexão. A resposta traz os dois campos. ## Assinatura em todos os tipos [Seção intitulada “Assinatura em todos os tipos”](#assinatura-em-todos-os-tipos) O corpo é o mesmo envelope JSON do webhook e os cabeçalhos `Messajo-*` vão como **cabeçalhos da mensagem** (headers no RabbitMQ e no Kafka, `MessageAttributes` no SQS). Verifique `Messajo-Signature` sobre o corpo cru, igual ao webhook: veja [Verificar a assinatura](/webhooks/verify-signature/). Nos exemplos abaixo, `verify` é a função daquela página (Python) e `verifyWebhookSignature` vem do [SDK](/sdk/typescript/) (Node). A entrega é **pelo menos uma vez**: desduplique por `Messajo-Event-Id`. ## RabbitMQ [Seção intitulada “RabbitMQ”](#rabbitmq) | Campo | Padrão | O que é | | ------------- | ---------------- | --------------------------------------- | | `url` | — | `amqps://usuário:senha@host:5671/vhost` | | `exchange` | — | exchange que já existe no seu servidor | | `routing_key` | `messajo.{type}` | chave de roteamento | | `persistent` | `true` | mensagem gravada em disco no broker | O Messajo publica num canal com confirmação e espera o `ack` do broker por até 10 segundos. `nack` ou tempo esgotado contam como falha e entram nas tentativas. Cada mensagem leva `messageId` = id do evento e `type` = tipo do evento. Node (amqplib) ```ts import amqp from "amqplib"; import { verifyWebhookSignature } from "@messajo/sdk"; const connection = await amqp.connect(process.env.AMQP_URL!); const channel = await connection.createChannel(); const { queue } = await channel.assertQueue("messajo-eventos", { durable: true }); await channel.bindQueue(queue, "messajo", "messajo.message.*"); await channel.consume(queue, async (msg) => { if (!msg) return; const body = msg.content.toString("utf8"); const header = String(msg.properties.headers?.["Messajo-Signature"] ?? ""); const check = await verifyWebhookSignature({ header, body, secret: process.env.MESSAJO_SECRET! }); if (!check.ok) return channel.nack(msg, false, false); const event = JSON.parse(body); // processe event.type / event.data channel.ack(msg); }); ``` Python (pika) ```python import json import os import pika from verify import verify # a função de "Verificar a assinatura" connection = pika.BlockingConnection(pika.URLParameters(os.environ["AMQP_URL"])) channel = connection.channel() channel.queue_declare("messajo-eventos", durable=True) channel.queue_bind("messajo-eventos", "messajo", "messajo.message.*") def handle(ch, method, properties, body: bytes) -> None: header = (properties.headers or {}).get("Messajo-Signature", "") if not verify(header, body, os.environ["MESSAJO_SECRET"]): ch.basic_nack(method.delivery_tag, requeue=False) return event = json.loads(body) # processe event["type"] / event["data"] ch.basic_ack(method.delivery_tag) channel.basic_consume("messajo-eventos", handle) channel.start_consuming() ``` ## Amazon SQS [Seção intitulada “Amazon SQS”](#amazon-sqs) | Campo | Padrão | O que é | | ------------------------------------------------------- | -------------- | --------------------------------------------------- | | `queue_url` | — | `https://sqs..amazonaws.com//` | | `region` | — | região da fila | | `access_key_id` · `secret_access_key` · `session_token` | — | credencial IAM só com `sqs:SendMessage` nessa fila | | `message_group_id` | `{connection}` | só em fila `.fifo`: ordem por conexão | Em fila `.fifo`, o `MessageDeduplicationId` é o id da entrega. Os cabeçalhos `Messajo-*` vão em `MessageAttributes`. O SQS aceita até 1 MiB por mensagem: evento maior falha sem nova tentativa com `payload_too_large` (aparece na lista de falhas). Node (@aws-sdk/client-sqs) ```ts import { DeleteMessageCommand, ReceiveMessageCommand, SQSClient } from "@aws-sdk/client-sqs"; import { verifyWebhookSignature } from "@messajo/sdk"; const sqs = new SQSClient({}); const QueueUrl = process.env.QUEUE_URL!; for (;;) { const { Messages = [] } = await sqs.send( new ReceiveMessageCommand({ QueueUrl, MessageAttributeNames: ["All"], WaitTimeSeconds: 20 }) ); for (const msg of Messages) { const header = msg.MessageAttributes?.["Messajo-Signature"]?.StringValue ?? null; const check = await verifyWebhookSignature({ header, body: msg.Body!, secret: process.env.MESSAJO_SECRET! }); if (check.ok) { const event = JSON.parse(msg.Body!); // processe event.type / event.data } await sqs.send(new DeleteMessageCommand({ QueueUrl, ReceiptHandle: msg.ReceiptHandle })); } } ``` Python (boto3) ```python import json import os import boto3 from verify import verify sqs = boto3.client("sqs") queue_url = os.environ["QUEUE_URL"] while True: response = sqs.receive_message( QueueUrl=queue_url, MessageAttributeNames=["All"], WaitTimeSeconds=20 ) for msg in response.get("Messages", []): attributes = msg.get("MessageAttributes", {}) header = attributes.get("Messajo-Signature", {}).get("StringValue", "") if verify(header, msg["Body"].encode(), os.environ["MESSAJO_SECRET"]): event = json.loads(msg["Body"]) # processe event["type"] / event["data"] sqs.delete_message(QueueUrl=queue_url, ReceiptHandle=msg["ReceiptHandle"]) ``` ## Kafka [Seção intitulada “Kafka”](#kafka) | Campo | Padrão | O que é | | ----------- | -------------- | ---------------------------------------------------------------------------------- | | `brokers` | — | até 10, `host:porta` | | `topic` | — | tópico que já existe | | `ssl` | `true` | TLS | | `sasl` | `null` | `{ mechanism: "plain" \| "scram-sha-256" \| "scram-sha-512", username, password }` | | `key` | `{connection}` | chave da mensagem: mesma chave, mesma partição, mesma ordem | | `client_id` | `messajo` | id do cliente no cluster | O produtor é idempotente e espera todas as réplicas (`acks: -1`), com 10 segundos de limite. Os cabeçalhos `Messajo-*` vão nos headers da mensagem. Node (kafkajs) ```ts import { Kafka } from "kafkajs"; import { verifyWebhookSignature } from "@messajo/sdk"; const kafka = new Kafka({ brokers: process.env.KAFKA_BROKERS!.split(","), ssl: true }); const consumer = kafka.consumer({ groupId: "messajo-eventos" }); await consumer.connect(); await consumer.subscribe({ topic: "messajo" }); await consumer.run({ eachMessage: async ({ message }) => { const body = message.value?.toString("utf8") ?? ""; const header = message.headers?.["Messajo-Signature"]?.toString() ?? null; const check = await verifyWebhookSignature({ header, body, secret: process.env.MESSAJO_SECRET! }); if (!check.ok) return; const event = JSON.parse(body); // processe event.type / event.data }, }); ``` Python (confluent-kafka) ```python import json import os from confluent_kafka import Consumer from verify import verify consumer = Consumer({ "bootstrap.servers": os.environ["KAFKA_BROKERS"], "security.protocol": "SSL", "group.id": "messajo-eventos", }) consumer.subscribe(["messajo"]) while True: msg = consumer.poll(1.0) if msg is None or msg.error(): continue headers = dict(msg.headers() or []) header = headers.get("Messajo-Signature", b"").decode() if verify(header, msg.value(), os.environ["MESSAJO_SECRET"]): event = json.loads(msg.value()) # processe event["type"] / event["data"] ``` ## WebSocket [Seção intitulada “WebSocket”](#websocket) O seu processo abre a conexão e o Messajo empurra os eventos por ela. Não precisa de URL pública nem de porta aberta. O destino `websocket` não tem configuração: crie com `"type": "websocket"`. ### Conectar [Seção intitulada “Conectar”](#conectar) 1. Peça um ticket com uma chave `read`: `POST /v1/destinations/{id}/ws-tickets` devolve `{ ticket, url, expires_at }`. O ticket vale 60 segundos e uma conexão só. 2. Abra `url` (`wss://api.messajo.com/v1/ws?ticket=wst_…`). 3. Sem ticket, também vale `Authorization: Bearer ` com `?destination_id=dst_…`, para clientes que mandam cabeçalho no handshake. ### Protocolo [Seção intitulada “Protocolo”](#protocolo) Todos os quadros são JSON em texto. | Direção | Quadro | O que fazer | | --------------- | -------------------------------------------------------------------- | ---------------------------------------------- | | servidor → você | `{"type":"ready","destination_id","session_id","heartbeat_s":30}` | conectado | | servidor → você | `{"type":"event","delivery_id","attempt","signature","event":{...}}` | processe e mande o `ack` | | servidor → você | `{"type":"ping","t"}` | responda `{"type":"pong","t"}` com o mesmo `t` | | você → servidor | `{"type":"ack","delivery_id"}` | confirma a entrega | * **Ack:** sem `ack`, a entrega fica pendente e volta na próxima tentativa, como um webhook sem `2xx`. O `ack` só vale na sessão do mesmo destino. * **Assinatura:** `signature` é o mesmo `Messajo-Signature`, calculado sobre os bytes de `event` exatamente como aparecem no quadro. A sessão já é autenticada pelo ticket; verificar é opcional. * **Sessões:** até 5 por destino. Todas recebem os eventos: desduplique por `event.id`. A ordem não é garantida. * Sem cliente conectado, a entrega falha com `no_client_connected` e entra nas tentativas normais. | Código de fechamento | Motivo | | -------------------- | ---------------------------------------------------------------------------- | | `4401` | ticket ou chave inválidos ([`ws_ticket_invalid`](/errors#ws_ticket_invalid)) | | `4403` | o destino não é `websocket` ou não está ativo | | `4408` | sem `pong` por 75 segundos | | `4410` | o destino foi apagado | | `4429` | já há 5 sessões ([`ws_session_limit`](/errors#ws_session_limit)) | Node (SDK) ```ts import { Messajo, connectEvents } from "@messajo/sdk"; const messajo = new Messajo({ apiKey: process.env.MESSAJO_API_KEY! }); const socket = connectEvents({ client: messajo, destinationId: "dst_...", onEvent: async (event) => { // o ack sai quando isto resolve; se lançar, o Messajo entrega de novo console.log(event.type); }, }); await socket.ready; ``` O `connectEvents` pede o ticket, responde o `ping`, manda o `ack` e reconecta com espera crescente (1 s até 30 s). No Node 20, passe a opção `WebSocket` (do pacote `ws`). Python (websockets) ```python import asyncio import json import os import requests import websockets API = "https://api.messajo.com/v1" HEADERS = {"Authorization": f"Bearer {os.environ['MESSAJO_API_KEY']}"} async def main(destination_id: str) -> None: while True: ticket = requests.post( f"{API}/destinations/{destination_id}/ws-tickets", headers=HEADERS, timeout=10 ).json() async with websockets.connect(ticket["url"]) as ws: async for raw in ws: frame = json.loads(raw) if frame["type"] == "ping": await ws.send(json.dumps({"type": "pong", "t": frame["t"]})) elif frame["type"] == "event": event = frame["event"] # processe event["type"] / event["data"] await ws.send(json.dumps({"type": "ack", "delivery_id": frame["delivery_id"]})) await asyncio.sleep(1) asyncio.run(main("dst_...")) ``` # Eventos > Como os eventos chegam ao seu webhook, o envelope e o catálogo de tipos. ## Como chega [Seção intitulada “Como chega”](#como-chega) Cada evento chega como um `POST` com corpo JSON na URL que você cadastrou como destino. Os cabeçalhos de cada entrega: | Cabeçalho | Valor | | -------------------------- | ------------------------------------------------------------------------------------------- | | `Content-Type` | `application/json` | | `User-Agent` | `Messajo-Webhooks/1` | | `Messajo-Signature` | `t=,v1=` — veja [Verificar a assinatura](/webhooks/verify-signature/) | | `Messajo-Event-Id` | id do evento (`evt_…`), o mesmo em todas as tentativas e reenvios | | `Messajo-Event-Type` | tipo do evento, por exemplo `message.received` | | `Messajo-Delivery-Id` | id desta entrega para este destino (`dlv_…`). Um reenvio cria uma entrega nova, com id novo | | `Messajo-Delivery-Attempt` | número da tentativa desta entrega, começando em `1` | Os cabeçalhos próprios que você cadastrar no destino vão junto. Eles nunca substituem os `Messajo-*`, e `Host`, `Content-Type`, `Content-Length`, `User-Agent`, `Transfer-Encoding` e `Connection` não podem ser cadastrados. ## Envelope [Seção intitulada “Envelope”](#envelope) Todo evento vem no mesmo envelope: | Campo | Tipo | O que é | | ------------ | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | | `id` | `string` | id do evento (`evt_…`). Use para descartar duplicatas. | | `type` | `string` | tipo do evento, por exemplo `message.received`. | | `format` | `"normalized"` \| `"meta"` | formato **usado** em `data` (veja abaixo). | | `org` | `string` | id da organização. | | `connection` | `string` \| `null` | id da conexão (`conn_…`); `null` em evento da organização, como `destination.test`. | | `channel` | `"whatsapp"` \| `"instagram"` \| `"messenger"` \| `null` | canal da conexão; `null` quando `connection` é `null`. | | `timestamp` | `string` | data e hora do fato, ISO 8601 em UTC. | | `sequence` | `number` \| `null` | crescente por conversa; `null` em eventos fora de conversa (veja o [catálogo](#cat%C3%A1logo)). | | `data` | `object` | o conteúdo do evento, no formato de `format`. | ### Os dois formatos [Seção intitulada “Os dois formatos”](#os-dois-formatos) Cada destino escolhe um formato: * **`normalized`**: formato do Messajo, igual em todos os canais, em snake_case. * **`meta`**: o pedaço do webhook da Meta que gerou o evento. No WhatsApp é o `value` do *change* reduzido a este fato: o array `messages` (ou `statuses`, ou `message_echoes`) com um elemento só, e o `metadata` e o `contacts` correspondentes intactos. No Instagram e no Messenger é o item de `messaging[]`. Evento que não nasce de um webhook da Meta (por exemplo `message.sent` e `destination.test`) não tem versão `meta`: sai `normalized` mesmo para destino `meta`. Por isso o campo `format` diz o formato que foi **usado**, não o que o destino pediu. Confira `format` antes de ler `data`. O mesmo `message.received` nos dois formatos: format: normalized ```json { "id": "evt_01JC9W3X6V2Q8T5M4R7N1K0HZB", "type": "message.received", "format": "normalized", "org": "org_01JC9V8F2D3S4A5Q6W7E8R9T0Y", "connection": "conn_01JC9VB2N3M4L5K6J7H8G9F0DS", "channel": "whatsapp", "timestamp": "2026-11-09T14:03:27.000Z", "sequence": 42, "data": { "contact": { "display_name": "Maria", "id": "ctc_01JC9W3X5R1P0N9M8L7K6J5H4G", "identities": [{ "kind": "wa_id", "scope": "", "value": "5511999999999" }] }, "conversation": { "extended_window_ends_at": null, "id": "cnv_01JC9W3X5S2Q1P0N9M8L7K6J5H", "window_ends_at": "2026-11-10T14:03:27.000Z" }, "message": { "content": { "body": "Olá! Meu pedido já saiu?", "type": "text" }, "context": null, "direction": "inbound", "external_id": "wamid.HBgNNTUxMTk5OTk5OTk5ORUCABIYFjNFQjA", "id": "msg_01JC9W3X6T3R2Q1P0N9M8L7K6J", "source": "customer", "timestamp": "2026-11-09T14:03:27.000Z" } } } ``` format: meta ```json { "id": "evt_01JC9W3X6V2Q8T5M4R7N1K0HZB", "type": "message.received", "format": "meta", "org": "org_01JC9V8F2D3S4A5Q6W7E8R9T0Y", "connection": "conn_01JC9VB2N3M4L5K6J7H8G9F0DS", "channel": "whatsapp", "timestamp": "2026-11-09T14:03:27.000Z", "sequence": 42, "data": { "contacts": [{ "profile": { "name": "Maria" }, "wa_id": "5511999999999" }], "messages": [ { "from": "5511999999999", "id": "wamid.HBgNNTUxMTk5OTk5OTk5ORUCABIYFjNFQjA", "text": { "body": "Olá! Meu pedido já saiu?" }, "timestamp": "1762697007", "type": "text" } ], "messaging_product": "whatsapp", "metadata": { "display_phone_number": "5511988887777", "phone_number_id": "106540352242922" } } } ``` As chaves de `data` saem em ordem alfabética e o mesmo evento gera sempre os mesmos bytes, em todas as tentativas. Mesmo assim, verifique a assinatura sobre o corpo cru, nunca sobre um JSON re-serializado. A [referência da API](/reference) traz o schema completo de cada `data`. ## Catálogo [Seção intitulada “Catálogo”](#catálogo) | Tipo | Quando | `sequence` | Canais | | -------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | --------- | | `message.received` | chegou uma mensagem do contato | sim | todos | | `message.sent` | uma mensagem sua foi aceita pela Meta | sim | todos | | `message.status` | mudou o status de uma mensagem sua (entregue, lida, falhou) | sim | todos | | `message.echo` | mensagem enviada por fora da API (app no celular, Inbox da Meta) | sim | todos | | `message.edited` | o contato editou uma mensagem | sim | todos | | `message.revoked` | o contato apagou uma mensagem | sim | todos | | `call.incoming` | o contato está ligando para o número (com o `sdp` da oferta) | sim | WhatsApp | | `call.sdp_answer` | o contato atendeu uma [ligação](/guides/calls/) sua (com o `sdp` da resposta) | sim | WhatsApp | | `call.status` | a ligação mudou de estado (`RINGING`, `ACCEPTED`, `REJECTED`) | sim | WhatsApp | | `call.ended` | a ligação terminou, com `end_reason` e a duração em `duration_s` | sim | WhatsApp | | `call.permission_updated` | mudou a permissão de chamada do contato (`status`, `expires_at`) | sim | WhatsApp | | `group.created` · `group.create_failed` | a Meta criou (ou não) um [grupo](/guides/groups/) | `null` | WhatsApp | | `group.settings_updated` · `group.participants_updated` · `group.join_requested` | mudaram os dados ou os participantes do grupo, ou chegou um pedido de entrada | `null` | WhatsApp | | `group.suspended` · `group.unsuspended` · `group.deleted` | o grupo foi suspenso, liberado ou apagado | `null` | WhatsApp | | `flow.response` | o contato terminou um [Flow](/guides/flows/) (com `response` e `flow_token`) | sim | WhatsApp | | `flow.status_changed` · `flow.endpoint_alert` · `flow.endpoint_error` | mudou o status do Flow, a Meta alertou sobre a saúde do endpoint, ou o app do contato avisou um erro | `null` | WhatsApp | | `order.received` · `order.updated` | chegou um carrinho ou mudou um [pedido](/guides/commerce/) (cobrança, status, pagamento) | sim | WhatsApp | | `payment.updated` | a Meta avisou o pagamento de um pedido | sim | WhatsApp | | `template.status` | a Meta aprovou, recusou ou pausou um template | `null` | WhatsApp | | `connection.created` | nova conexão ativa | `null` | todos | | `connection.updated` | mudou o status (para ativa, restrita ou desativada), a saúde ou os dados da conexão; o motivo vem em `reason` | `null` | todos | | `connection.disconnected` | a conexão foi desligada | `null` | todos | | `connection.needs_reconnect` | o acesso caiu e a conexão precisa ser refeita | `null` | todos | | `connection.error` | a Meta avisou um erro da conta ou do número, fora de uma mensagem (`errors[]`) | `null` | WhatsApp | | `history.batch` | lote do histórico de 6 meses importado na coexistência | `null` | WhatsApp | | `contacts.sync` | contatos sincronizados do app na coexistência | `null` | WhatsApp | | `comment.received` | chegou um comentário (ou resposta a comentário) num post ou live da conta | `null` | Instagram | | `comment.replied` | você respondeu um comentário em público | `null` | Instagram | | `comment.private_replied` | você mandou uma resposta privada a um comentário (vem com a mensagem e o contato) | `null` | Instagram | | `comment.hidden` · `comment.unhidden` | você ocultou ou voltou a mostrar um comentário | `null` | Instagram | | `comment.deleted` | você apagou um comentário | `null` | Instagram | | `mention.received` | a conta foi mencionada num comentário, legenda ou story (`source`) | `null` | Instagram | | `publication.published` | uma [publicação](/connect/instagram-content/#publicar) saiu, com `external_media_id` e `permalink` | `null` | Instagram | | `publication.failed` | uma publicação falhou, com o motivo em `publication.error` | `null` | Instagram | | `campaign.scheduled` · `campaign.started` · `campaign.completed` · `campaign.canceled` | uma [campanha](/guides/campaigns/) foi agendada, começou, terminou ou foi cancelada (`data.campaign` com status e números) | `null` | WhatsApp | | `campaign.paused` · `campaign.resumed` | a campanha pausou ou voltou; `reason` diz o motivo e `auto: true` quando foi o Messajo (inclusive `limit_reached`, a faixa de 24 h, e `org_suspended`, quando a organização é suspensa) | `null` | WhatsApp | | `campaign.progress` | os números da campanha mudaram (no máximo 1 por minuto) | `null` | WhatsApp | | `org.standing_changed` | a situação da organização mudou (`active`, `restricted` ou `suspended`), desde a `1.1.0` | `null` | — | | `destination.test` | você clicou em **Testar** no destino (ou chamou `POST /v1/destinations/{id}/test`) | `null` | — | Atender, recusar, encerrar e fazer ligações pela API: veja [Ligações no WhatsApp](/guides/calls/). `message.sent` e `message.status` trazem `campaign: { id, recipient_id }` quando a mensagem saiu de uma campanha, e `null` nos outros casos. Os eventos `message.*` trazem `group: { id, external_id, subject }` numa mensagem de grupo (e `null` fora dele) e o tipo da conversa em `conversation.kind`. `message.status` traz `cost: { estimate, currency, rate_card_version }` no status que gerou cobrança da Meta e `null` nos demais; veja [Custos da Meta](/guides/costs/). ### Organização [Seção intitulada “Organização”](#organização) `org.standing_changed` avisa quando a situação da organização muda. `reason` é `payment`, `abuse`, `manual` ou `meta_request`, e vem `null` quando a organização volta a `active`. ```json { "type": "org.standing_changed", "data": { "organization": { "id": "org_1", "standing": "suspended", "previous_standing": "restricted", "reason": "payment", "since": "2026-11-13T12:00:00.000Z" } } } ``` * É emitido **antes** de os webhooks da organização serem retidos e nunca é retido: você sempre recebe o aviso da suspensão. * Enquanto a organização está suspensa, as entregas ficam com status `held`. Ao voltar, saem na ordem de criação do evento (ordem de enfileiramento); dentro de uma conversa vale a `sequence`. * Uma entrega `held` com mais de **15 dias** vira `failed` com o erro `org_suspended`. ### Eventos de WABA e de organização [Seção intitulada “Eventos de WABA e de organização”](#eventos-de-waba-e-de-organização) Dois grupos de eventos não pertencem a uma só conexão: * **Eventos de WABA** (`template.*`, `flow.status_changed`, `flow.endpoint_alert` e `flow.endpoint_error`; `flow.response` não, é do número que recebeu): a Meta os emite para a conta do WhatsApp Business (WABA), que pode ter vários números. O Messajo entrega o evento a um destino de **qualquer conexão da mesma WABA**, e uma vez por destino. O destino global também recebe e não duplica. * **Eventos de organização** (`org.*`, como `org.standing_changed`): não têm conexão, então só chegam a **destinos globais** cujo filtro os inclua (`org.*` ou `*`). Um destino de conexão nunca os recebe. ### Motivos da conexão [Seção intitulada “Motivos da conexão”](#motivos-da-conexão) Os eventos `connection.*` trazem a conexão em `data.connection`, com `status`, `previous_status` e o motivo em `reason`: | `reason` | Status depois | O que houve | | ---------------------------------------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | | `reconnected` | ativa | A conexão foi refeita (pelo painel, por link ou porque a Meta reconectou a conta) | | `reinstated` | ativa | A Meta reativou a conta depois de uma violação ou banimento | | `restriction_lifted` | ativa | A restrição da Meta acabou | | `account_restriction` | restrita | A Meta restringiu a conta por um prazo | | `policy_blocked` | restrita | A Meta bloqueou um envio por política (`368` ou `131031`) | | `violation:` | desativada | A Meta apontou uma violação de política | | `banned` | desativada | A Meta baniu a conta | | `token_invalid` · `meta_token_invalid` | precisa reconectar | A Meta invalidou o token (erro `190`), numa leitura de saúde ou num envio | | `partner_removed` · `partner_removed:` | desconectada | A conta tirou o Messajo como parceiro | | `app_uninstalled` | desconectada | O app foi desinstalado da conta | | `account_deleted` | desconectada | A conta ou o número foi apagado na Meta | | `offboarded` | desconectada | A conta saiu da plataforma da Meta | | `user_requested` | desconectada | Alguém da organização desconectou pelo painel ou pela API | | `billing_suspended` | desconectada | A organização foi suspensa por falta de pagamento e as conexões foram desconectadas | | `token_expired` | precisa reconectar | Legado: não é mais emitido (o erro 190 agora vira `token_invalid`) | | `app_deauthorized` | desconectada (Instagram) · precisa reconectar (Messenger) | A pessoa que autorizou removeu o app nas configurações da Meta | | `data_deleted` | desconectada | A pessoa pediu a exclusão dos dados à Meta e o Messajo apagou os dados da conta do Instagram | | `scheduled_for_disable` | sem mudança | A Meta agendou a desativação da conta | | `quality_changed` | sem mudança | Mudou a qualidade do número | | `limit_changed` | sem mudança | Mudou a faixa de envio ou a capacidade da conta | | `send_rate_changed` | sem mudança | Mudou a velocidade (20, 80 ou 1.000 msg/s) | | `can_send_changed` | sem mudança | Mudou o **Envio** (liberado, limitado ou bloqueado) | | `name_approved` · `name_rejected` | sem mudança | A Meta decidiu o pedido de troca do nome exibido | | `alert` | sem mudança | A Meta mandou um alerta da conta | | `dm_access_disabled` | sem mudança | A conta do Instagram desativou o acesso às mensagens fora do app (detectado ao conectar ou pelo health check) | | `resubscribed` | sem mudança | O app tinha saído da inscrição de webhooks da conta ou da Página e o Messajo inscreveu de novo | | `policy_enforcement` | restrita ou ativa | A Meta bloqueou ou liberou a Página no Messenger por política | Quando o status não muda, `previous_status` é igual a `status`. Mudança de status também manda e-mail para donos e admins (no máximo um por motivo a cada 6 h). ## Ordem e duplicatas [Seção intitulada “Ordem e duplicatas”](#ordem-e-duplicatas) * A entrega é **pelo menos uma vez**: o mesmo evento pode chegar mais de uma vez. Deduplique pelo `Messajo-Event-Id` (igual ao `id` do envelope). * Eventos podem chegar fora de ordem, inclusive entre entregas e reenvios. Dentro de uma conversa, use `sequence` para ordenar: ela só cresce. * Responda `2xx` rápido e processe depois (numa fila sua). Trabalho pesado dentro da requisição faz a entrega estourar o tempo e voltar como tentativa. ## Tentativas e falhas [Seção intitulada “Tentativas e falhas”](#tentativas-e-falhas) * **Sucesso** = resposta `2xx` em até **10 segundos**, no total. Qualquer outra coisa conta como falha: outro status, tempo esgotado, erro de rede ou endereço bloqueado. Redirecionamento (`3xx`) **não** é seguido e conta como falha. * O Messajo guarda os primeiros 1024 bytes da resposta de cada tentativa, para você ver no painel. * Depois de uma falha, tenta de novo segundo a tabela abaixo: 1 tentativa imediata e mais 14, ao longo de pouco mais de 23 horas. Cada espera varia ±10% e nenhuma tentativa sai depois de 24 horas da criação da entrega. | Tentativa | Espera desde a anterior | Desde a 1ª (aprox.) | | --------- | ----------------------- | ------------------- | | 1 | — | 0 | | 2 | 10 s | 10 s | | 3 | 30 s | 40 s | | 4 | 1 min | 1 min 40 s | | 5 | 2 min | 3 min 40 s | | 6 | 5 min | 8 min 40 s | | 7 | 10 min | 18 min 40 s | | 8 | 20 min | 38 min 40 s | | 9 | 40 min | 1 h 18 min | | 10 | 1 h | 2 h 18 min | | 11 | 2 h | 4 h 18 min | | 12 | 3 h | 7 h 18 min | | 13 | 4 h | 11 h 18 min | | 14 | 6 h | 17 h 18 min | | 15 | 6 h | 23 h 18 min | ### Lista de falhas e reenvio [Seção intitulada “Lista de falhas e reenvio”](#lista-de-falhas-e-reenvio) * Esgotadas as tentativas, a entrega fica `failed` e entra na **lista de falhas** do destino, no painel. * **Reenviar** cria uma entrega nova do mesmo evento (mesmo `Messajo-Event-Id`, novo `Messajo-Delivery-Id`, tentativa `1`). Só funciona com o destino ativo. * Para reenviar várias de uma vez, use **Reenviar falhas** no painel ou `POST /v1/destinations/{id}/redeliver-failed` com `since` (e `until`, opcional). Cada chamada põe na fila até 1000 falhas e devolve `{ queued, has_more }`: com `has_more: true`, chame de novo. * Entregas e eventos ficam guardados por **30 dias**. ### Pausa automática [Seção intitulada “Pausa automática”](#pausa-automática) * Um destino é pausado sozinho (`auto_paused`) quando junta **10 falhas seguidas** e está falhando há **pelo menos 24 horas**. Qualquer `2xx` zera a contagem. * Ao pausar, as entregas ainda em andamento desse destino viram `failed` com o erro `destination_paused`, e donos e admins da organização recebem um **e-mail**. * Enquanto o destino estiver pausado (sozinho ou por você), cada evento novo gera uma entrega `failed` com `destination_paused`. Nada se perde: depois de corrigir o endpoint e **retomar** o destino, reenvie as falhas do período. ## Filtros [Seção intitulada “Filtros”](#filtros) Cada destino recebe só o que você escolher: * **por evento**: uma lista de padrões. Vale `*` (tudo), `.*` (por exemplo `message.*` ou `connection.*`) e o tipo exato (por exemplo `message.status`). Padrão que não é tipo conhecido nem família conhecida ou reservada é recusado com `validation_failed`; * **por conexão**: um destino de conexão recebe só os eventos dela; um destino global (sem conexão) recebe os de todas. Veja [Tipos de destino](/webhooks/destinations/#global-ou-por-conex%C3%A3o); * **formato**: `normalized` ou `meta`. O evento chega quando algum padrão casa com o tipo **e** o destino aceita a conexão do evento. O `destination.test` não passa pelos filtros: vai só para o destino testado, numa tentativa única, mesmo com o destino pausado. ## Outros destinos [Seção intitulada “Outros destinos”](#outros-destinos) O webhook é o destino padrão. RabbitMQ, SQS, Kafka e WebSocket recebem o mesmo envelope, com a mesma assinatura, os mesmos filtros e as mesmas tentativas: veja [Tipos de destino](/webhooks/destinations/). # Verificar a assinatura > Como confirmar que um webhook veio mesmo do Messajo, com exemplos em várias linguagens. ## Por que verificar [Seção intitulada “Por que verificar”](#por-que-verificar) A URL do seu webhook é pública. Sem verificar a assinatura, qualquer um que descubra a URL pode mandar eventos falsos — uma “mensagem recebida” inventada, um “pagamento” que nunca aconteceu. A assinatura prova que o corpo veio do Messajo, com o seu segredo, e que não foi alterado no caminho. O horário dentro dela impede que alguém grave uma entrega e a repita depois. ## O cabeçalho [Seção intitulada “O cabeçalho”](#o-cabeçalho) Cada entrega traz o cabeçalho `Messajo-Signature`: ```text Messajo-Signature: t=1762697007,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd ``` * `t` é o horário da assinatura, em segundos Unix. Aparece uma vez só. * `v1` é o HMAC-SHA256 em hexadecimal. Durante a [rotação do segredo](#girar-o-segredo-sem-parar) vêm **dois** `v1`, um por segredo ativo: basta um bater. * Ignore esquemas que você não conhece (um `v2=` futuro, por exemplo). O segredo do destino começa com `whsec_` e aparece **uma vez só**, ao criar o destino (no painel ou na resposta de `POST /v1/destinations`). Depois o painel mostra só os 4 últimos caracteres. Perdeu? Gire o segredo. ## Passo a passo [Seção intitulada “Passo a passo”](#passo-a-passo) 1. Leia o **corpo cru** da requisição, exatamente os bytes que chegaram, **antes** de qualquer parse de JSON. 2. Separe `t` e os `v1` do cabeçalho. 3. Monte a mensagem `${t}.${corpo}` — o horário, um ponto e o corpo cru. 4. Calcule o HMAC-SHA256 dessa mensagem usando como chave o **segredo inteiro**, com o prefixo `whsec_`, em UTF-8. O resultado em hexadecimal minúsculo. 5. Compare com cada `v1` em **tempo constante** (`timingSafeEqual`, `hmac.compare_digest`, `hash_equals`). Comparação com `==` vaza informação pelo tempo de resposta. 6. Recuse se `t` estiver a mais de **5 minutos** do seu relógio, para trás ou para frente. Assinatura inválida → responda `400` e descarte o evento. Válida → responda `2xx` rápido e processe depois (veja [Eventos](/webhooks/events/#ordem-e-duplicatas)). ## Exemplos [Seção intitulada “Exemplos”](#exemplos) Os três exemplos não usam biblioteca externa e são testados a cada build contra o assinador do Messajo. ### Node.js [Seção intitulada “Node.js”](#nodejs) verify.ts ```ts import { createHmac, timingSafeEqual } from "node:crypto"; const TOLERANCE_SECONDS = 300; const DIGITS = /^\d+$/; /** * Checks the Messajo-Signature header ("t=,v1=[,v1=…]"). * `rawBody` must be the exact body received, before any JSON parsing. */ export function verify( header: string, rawBody: string, secret: string, nowSeconds: number = Math.floor(Date.now() / 1000) ): boolean { const timestamps: string[] = []; const signatures: string[] = []; for (const part of header.split(",")) { const [key, value = ""] = part.trim().split("=", 2); if (key === "t") { timestamps.push(value); } else if (key === "v1") { signatures.push(value); } } const [rawTimestamp = ""] = timestamps; if (timestamps.length !== 1 || !DIGITS.test(rawTimestamp)) { return false; } const timestamp = Number(rawTimestamp); if (Math.abs(nowSeconds - timestamp) > TOLERANCE_SECONDS) { return false; } const expected = Buffer.from( createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest("hex") ); return signatures.some((signature) => { const received = Buffer.from(signature); return ( received.length === expected.length && timingSafeEqual(received, expected) ); }); } ``` ### Python [Seção intitulada “Python”](#python) verify.py ```python """Verify a Messajo webhook signature. Usage: python3 verify.py < raw_body Exit code 0 = valid signature, 1 = invalid. """ import hashlib import hmac import sys import time TOLERANCE_SECONDS = 300 def verify(header: str, raw_body: bytes, secret: str, now: int | None = None) -> bool: """`raw_body` must be the exact bytes received, before any JSON parsing.""" timestamps, signatures = [], [] for part in header.split(","): key, _, value = part.strip().partition("=") if key == "t": timestamps.append(value) elif key == "v1": signatures.append(value) if len(timestamps) != 1 or not (timestamps[0].isascii() and timestamps[0].isdigit()): return False timestamp = int(timestamps[0]) now = int(time.time()) if now is None else now if abs(now - timestamp) > TOLERANCE_SECONDS: return False signed = f"{timestamp}.".encode() + raw_body expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest() return any(hmac.compare_digest(expected, signature) for signature in signatures) if __name__ == "__main__": secret, header = sys.argv[1], sys.argv[2] sys.exit(0 if verify(header, sys.stdin.buffer.read(), secret) else 1) ``` ### PHP [Seção intitulada “PHP”](#php) verify.php ```php < raw_body // Exit code 0 = valid signature, 1 = invalid. const MESSAJO_TOLERANCE_SECONDS = 300; // $rawBody must be the exact body received, before json_decode. function messajo_verify(string $header, string $rawBody, string $secret, ?int $now = null): bool { $timestamps = []; $signatures = []; foreach (explode(',', $header) as $part) { [$key, $value] = array_pad(explode('=', trim($part), 2), 2, ''); if ($key === 't') { $timestamps[] = $value; } elseif ($key === 'v1') { $signatures[] = $value; } } if (count($timestamps) !== 1 || !ctype_digit($timestamps[0])) { return false; } $timestamp = (int) $timestamps[0]; if (abs(($now ?? time()) - $timestamp) > MESSAJO_TOLERANCE_SECONDS) { return false; } $expected = hash_hmac('sha256', "{$timestamp}.{$rawBody}", $secret); foreach ($signatures as $signature) { if (hash_equals($expected, $signature)) { return true; } } return false; } if (PHP_SAPI === 'cli' && realpath($argv[0]) === __FILE__) { exit(messajo_verify($argv[2], file_get_contents('php://stdin'), $argv[1]) ? 0 : 1); } ``` Como pegar o corpo cru em cada framework: | Framework | Corpo cru | | --------- | -------------------------------------------------------------------------------------------------- | | Express | `app.post("/webhook", express.raw({ type: "application/json" }), …)` e `req.body.toString("utf8")` | | Hono | `await c.req.text()` | | FastAPI | `await request.body()` | | Laravel | `$request->getContent()` | Use o corpo cru na verificação e só depois faça o `JSON.parse` / `json.loads` / `json_decode`. ## n8n [Seção intitulada “n8n”](#n8n) 1. No nó **Webhook**, em **Options**, ligue **Raw Body**. 2. Depois dele, um nó **Code** (JavaScript) com o código do exemplo Node.js, lendo o cabeçalho `messajo-signature` e o corpo cru do item recebido. 3. O nó Code só carrega `crypto` se o n8n permitir: defina `NODE_FUNCTION_ALLOW_BUILTIN=crypto` no ambiente do n8n e reinicie. 4. Assinatura inválida → pare o fluxo (nó **Stop and Error** ou um **IF**). ## Girar o segredo sem parar [Seção intitulada “Girar o segredo sem parar”](#girar-o-segredo-sem-parar) 1. No painel, abra o destino e clique em **Girar segredo**, ou chame `POST /v1/destinations/{id}/rotate-secret`. O Messajo gera um segredo novo e o mostra uma vez só. 2. Escolha a **janela de convivência**: de 0 a 72 horas, padrão **24 horas** (`keep_previous_hours` na API). Durante a janela os dois valem e cada entrega vem com dois `v1`, primeiro o do segredo novo, depois o do antigo: ```text Messajo-Signature: t=1762697007,v1=,v1= ``` 3. Troque o segredo na sua aplicação dentro da janela. Como basta um `v1` bater, não há momento em que eventos sejam recusados. O fim da janela aparece no destino (`previous_secret_expires_at` na API). 4. Passada a janela, o segredo antigo deixa de assinar e as entregas voltam a ter um `v1` só. Com janela `0` o antigo para de assinar na hora: use só quando o segredo vazou. Girar de novo dentro da janela descarta o antigo anterior: valem só o segredo atual e o que acabou de ser substituído. ## Erros comuns [Seção intitulada “Erros comuns”](#erros-comuns) * **JSON re-serializado.** O framework fez parse do corpo e você assinou `JSON.stringify(req.body)`. Espaços, ordem de chaves e escape de acentos mudam e o HMAC não bate. Use o corpo cru. * **Relógio errado.** Servidor sem NTP fica fora dos 5 minutos e recusa tudo como antigo. Sincronize o relógio. * **Segredo com espaço.** Espaço ou quebra de linha no fim do segredo copiado (comum em `.env`). Confira o tamanho e remova espaços. * **Segredo sem o prefixo.** A chave do HMAC é o segredo inteiro, **com** `whsec_`. * **Corpo decodificado com outro charset.** Leia os bytes como UTF-8; acentos e emojis fazem diferença.