# 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

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

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.

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

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

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

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

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

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ê

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