Skip to content

Get started

Quickstart

From a new account to your first API call and first message, step by step.

You need an account at app.messajo.com. You also need a terminal with curl.

The examples use https://api.messajo.com/v1.

1. Create the account and the organization

Section titled “1. Create the account and the organization”
  1. Open the panel and click Create account. Enter your name, email and password.
  2. Confirm your email with the link sent to your inbox.
  3. Name your organization. You become its owner.

Everything in Messajo — connections, keys, event destinations — belongs to the organization, not to a person. See Concepts.

Two-factor authentication is mandatory for owners and admins. Until it is on, the panel locks the organization areas, including key creation.

  1. In Settings → Security, turn on Two-step verification (2FA).
  2. Scan the QR code with an authenticator app (Google Authenticator, 1Password, Authy…) and type the 6-digit code.
  3. Store the backup codes somewhere safe: they are your way back in if you lose your phone.
  1. Open API keys and click Create key.
  2. Give it a name (for example, test) and tick only the Read permission (read), which is enough for this guide.
  3. Keep All connections, choose an expiration and confirm.

The full key, starting with mj_, is shown only once. Copy it and keep it in an environment variable:

Janela do terminal
export MESSAJO_API_KEY="mj_..."

Details in Authentication and API keys.

GET /v1/me accepts any valid key and returns the organization and the key itself. It is the quickest way to confirm that authentication works.

Janela do terminal
curl https://api.messajo.com/v1/me \
-H "Authorization: Bearer $MESSAJO_API_KEY"

200 OK response:

{
"organization": {
"id": "Kq3vT9xZ2mWb7LpR4nYc8sDf1gHj6aEu",
"name": "Acme",
"slug": "acme"
},
"api_key": {
"id": "Zt5rB8wQ1nXc4LmV7pYd2sGf9hJk3aRe",
"name": "test",
"start": "mj_A1b2c3d",
"permissions": ["read"],
"connection_ids": null,
"kind": "org",
"connection_id": null,
"connection": null,
"expires_at": "2027-01-01T00:00:00.000Z"
},
"request_id": "req_0193a1b2c3d47e8f9a0b1c2d3e4f5a6b"
}
  • start is the visible prefix of the key, the same one the panel shows.
  • kind is org (mj_ key) or connection (mjc_ key). On a connection key, connection_id and connection { id, channel, label } identify its connection; on an organization key they are null.
  • connection_ids: null means the organization key works for every connection; on a connection key it holds only that connection’s id.
  • expires_at is null when the key never expires.

Got a 401? The body carries the error code, for example missing_api_key (the header is missing) or invalid_api_key (wrong or revoked key).

  1. In the panel, open Connections → Connect WhatsApp.
  2. Pick the mode: Keep my WhatsApp Business (coexistence: the number stays in the app) or New number, API only, and click Continue.
  3. Click Open Meta’s popup, follow Meta’s official signup in the window that opens and wait for the panel to show WhatsApp connected.

The connection shows up as Active, with an id like conn_…, used in send calls (the list is also at GET /v1/connections). The full walkthrough is in Connect WhatsApp.

Create a key with the send permission and call POST /v1/messages. A free-form message only goes to a contact who wrote to you in the last 24 hours; outside that window, use an approved template (see Concepts).

Janela do terminal
curl https://api.messajo.com/v1/messages \
-H "Authorization: Bearer $MESSAJO_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"connection_id": "conn_...",
"to": "5511999999999",
"type": "text",
"text": { "body": "Hi! Message sent with Messajo." }
}'

The SDK generates the Idempotency-Key for you and retries safely when the network fails. See TypeScript SDK.

If your code only talks to one number, create a connection key (mjc_…) in the connection’s own panel, under API keys. It already knows which connection it belongs to: the body’s connection_id goes away, and the key cannot reach other connections. An organization key (mj_) still requires connection_id.

Janela do terminal
curl https://api.messajo.com/v1/messages \
-H "Authorization: Bearer $MESSAJO_CONNECTION_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{ "to": "5511999999999", "type": "text", "text": { "body": "Hello!" } }'

See Key types.

The response is 201:

{
"id": "msg_...",
"external_id": "wamid.HBgNNTUxMTk5OTk5OTk5ORUCABEYEjQ",
"status": "queued",
"meta_status": "accepted",
"conversation_id": "cnv_...",
"contact_id": "ctc_...",
"created_at": "2026-11-09T12:00:00.000Z"
}

external_id is Meta’s id (wamid). Delivery and read arrive later, in the message.status event. Outside the window, the response is 422 outside_service_window. Each type has its own page in the Send messages group, starting with Send text; the fields of each are also in the API reference.

  1. In Event destinations, add the HTTPS URL that will receive events. The panel shows the secret (whsec_…) once.
  2. Reply 2xx within 10 seconds. Otherwise Messajo retries with growing delays for up to 24 hours.
  3. Send a message to your number: a message.received event arrives.
{
"id": "evt_...",
"type": "message.received",
"format": "normalized",
"org": "Kq3vT9xZ2mWb7LpR4nYc8sDf1gHj6aEu",
"connection": "conn_...",
"channel": "whatsapp",
"timestamp": "2026-11-09T12:00:00.000Z",
"sequence": 1,
"data": {}
}

The content of data depends on the event type and on the destination format. Before trusting the body, check the Messajo-Signature header with the secret: see Verify the signature. The full catalog is in Events.