# Concepts

> The building blocks of Messajo: organization, connections, keys, event destinations and the two API layers.

## Organization, members and roles

Everything belongs to an organization: connections, API keys, event destinations, templates and logs. A person can be a member of several organizations and switches between them in the panel. Each member has a role:

| Role | Can |
|---|---|
| **Owner** | Everything, including billing and deleting the organization. Only an owner promotes or demotes another owner, and the organization is never left without one |
| **Admin** | Connections, members and invitations, API keys, event destinations, templates, logs and audit |
| **Dev** | API keys (without the `admin` permission), event destinations, templates and logs. Sees connections but cannot create or change them |
| **Viewer** | Read only: keys (without the secret), connections, destinations, templates and logs |

Owners and admins must have two-step verification (2FA) on to use the organization panel.

An owner can **reset the 2FA** of another member under **Members**: the person is signed out and sets up a new authenticator at the next sign-in. For a sole owner who lost the authenticator, the instance administrator does the reset. An invitation only works while whoever sent it can still grant the role ([`invitation_invalid`](/en/errors#invitation_invalid)).

**Access per connection.** Dev and Viewer members can have access to **all** connections or only **some** (restricted access). The role stays the same; access only defines what the member sees. Owners and admins always see everything. A restricted member does not see other connections, nor notices that do not belong to one of their connections (billing, organization status, members), and only creates keys for connections they can access. Keys they created that fall outside the new access are revoked, unless whoever changes the access chooses to keep them. See [Authentication and API keys](/en/api/authentication/).

When the organization changes its **slug**, the old slug stays reserved for 90 days: another organization cannot take it, and the organization itself can go back to it.

## Panel: organization in the URL

Every organization screen has the slug in its address: `/<slug>/api-keys`, `/<slug>/members`. Tabs open on different organizations do not mix. The person's account lives at `/account`.

- **Changing the slug** (owner only, with password and 2FA code): the old address keeps redirecting for 90 days.
- **Organizations per user limit:** `ORG_LIMIT_PER_USER` (default 5). Beyond it, creating another organization fails with `org_limit_reached`.
- **Organization time zone:** dates in emails (invitations, notices) use the time zone set in Organization.
- **Member emails:** only owners and admins see them; other roles see the name.

## Connection and channel

A **connection** is a Meta account linked to the organization. Each connection has a **channel**:

| Channel | The connection is | How to link it |
|---|---|---|
| `whatsapp` | A WhatsApp Business number, in coexistence with the app or API only | [Connect WhatsApp](/en/connect/whatsapp/) |
| `instagram` | An Instagram professional account, no Facebook Page needed | [Connect Instagram](/en/connect/instagram/) |
| `messenger` | A Facebook Page | [Connect Messenger](/en/connect/messenger/) |

A connection has an `id` (`conn_…`) used in send calls and present in every event. Someone without a Messajo account can link their own account through a **connection invite**; from then on, the organization manages it.

## API key

The key authenticates the `/v1` API through the `Authorization: Bearer` header. It belongs to the organization, not to whoever created it, and has:

| Permission | Grants |
|---|---|
| `send` | Sending messages |
| `read` | Reading connections, conversations and logs |
| `templates` | Creating and editing templates |
| `admin` | Everything, including the permissions above |

There are two types: the **organization key** (`mj_`), valid for any connection and requiring `connection_id` on message routes, and the **connection key** (`mjc_`), created in the connection's **API keys** tab, which only sees its own connection and does not need `connection_id`. Using a connection outside its scope returns [`connection_not_allowed`](/en/errors#connection_not_allowed). Every key has its own expiration and per-minute limit. See [Key types](/en/api/authentication/#key-types).

The hierarchy is **organization → connection → WABA**. Templates, flows and catalogs belong to the WABA, which can be shared by sibling connections: changing them through one connection affects the others on the same WABA.

## Event destinations

Everything that happens on your connections — message received, delivery status, template approved, connection dropped — becomes an **event** and goes out through a destination:

- **Webhook** (default): a signed HTTPS `POST` with the `Messajo-Signature` header. See [Events](/en/webhooks/events/) and [Verify the signature](/en/webhooks/verify-signature/).
- **RabbitMQ, SQS, Kafka and WebSocket**: optional, with the same envelope and the same signature. See [Destination types](/en/webhooks/destinations/).

Each destination is **global** (receives events from the whole organization) or **per connection** (only that connection's). It filters by event type and picks a format:

- `normalized`: the same Messajo format across the 3 channels, good if you serve WhatsApp, Instagram and Messenger with one codebase;
- `meta`: the raw content Meta sent, if you already have code that understands Meta's format.

## Two API layers

The same key works on both layers, and you choose per call:

| Layer | Example | What for |
|---|---|---|
| **Meta mirror**, per channel | `POST /v1/whatsapp/{phone_number_id}/messages` with the exact same body as Meta | Covers 100% of Meta's features from day one. Migrating from another provider means changing only the URL and the key. Each field is documented by Meta's official docs |
| **Simple**, unified | `POST /v1/messages` with `connection_id`, `to`, `type`… | Day-to-day work (text, media, templates, buttons), the same across the 3 channels |

The [API reference](/en/reference) documents the simple layer and the platform routes.

## Conversation windows

Meta only allows free-form messages inside a **customer service window** opened by the contact: 24 hours since the last message they sent. Outside the window:

- on **WhatsApp**, only a Meta-approved **template** (marketing, utility or authentication) goes out, and it reopens the conversation when the contact replies;
- on **Instagram** and **Messenger**, sending outside the window is rejected, except for the cases Meta allows.

Sending outside the window returns Meta's error, with the original code in `meta_code`. See [Errors](/en/errors/).

## Idempotency

Networks fail, and blindly retrying a send delivers the message twice. To avoid that, send the `Idempotency-Key` header with a unique value per operation (a UUID, for example):

```http
POST /v1/messages
Idempotency-Key: 6f1c0f3e-9b1a-4c55-9a3e-2d8c1b7e4a10
```

The same key repeated within **24 hours** returns the original response without sending again. Generate the key before the first attempt and reuse it on every retry.

## Who charges for what

| Who | Charges | Whom |
|---|---|---|
| **Messajo** | A monthly subscription per connection | Your organization |
| **Meta** | Conversations and messages, at its official rates | Your Meta account directly, with the payment method registered there |

Messajo does not resell messages or add a margin on top of Meta's charges.
