Pular para o conteúdo

Começar

Conceitos

As peças do Messajo: organização, conexões, chaves, destinos de eventos e as duas camadas da API.

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.

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 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.

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.

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.

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 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.

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.

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.

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/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 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.