Começar
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”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).
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.
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”O endereço de cada tela da organização começa pelo slug: /<slug>/api-keys, /<slug>/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 comorg_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”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 |
instagram |
Uma conta profissional do Instagram, sem precisar de Página do Facebook | Conectar o Instagram |
messenger |
Uma Página do Facebook | Conectar o 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”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. Toda chave tem validade e limite por minuto próprios. Veja 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”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):
POSTHTTPS assinado com o cabeçalhoMessajo-Signature. Veja Eventos e Verificar a assinatura. - RabbitMQ, SQS, Kafka e WebSocket: opcionais, com o mesmo envelope e a mesma assinatura. Veja Tipos de destino.
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”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 documenta a camada simples e as rotas da plataforma.
Janelas de conversa
Seção intitulada “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.
Idempotência
Seção intitulada “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):
POST /v1/messagesIdempotency-Key: 6f1c0f3e-9b1a-4c55-9a3e-2d8c1b7e4a10A 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 | 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.