Skip to content

Get started

Concepts

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

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

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.

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.

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.

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
instagram An Instagram professional account, no Facebook Page needed Connect Instagram
messenger A Facebook Page 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.

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. Every key has its own expiration and per-minute limit. See 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.

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 and Verify the signature.
  • RabbitMQ, SQS, Kafka and WebSocket: optional, with the same envelope and the same signature. See Destination types.

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.

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 documents the simple layer and the platform routes.

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.

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):

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