Get started
Quickstart
From a new account to your first API call and first message, step by step.
Before you start
Section titled “Before you start”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”- Open the panel and click Create account. Enter your name, email and password.
- Confirm your email with the link sent to your inbox.
- Name your organization. You become its owner.
Everything in Messajo — connections, keys, event destinations — belongs to the organization, not to a person. See Concepts.
2. Turn on 2FA
Section titled “2. Turn on 2FA”Two-factor authentication is mandatory for owners and admins. Until it is on, the panel locks the organization areas, including key creation.
- In Settings → Security, turn on Two-step verification (2FA).
- Scan the QR code with an authenticator app (Google Authenticator, 1Password, Authy…) and type the 6-digit code.
- Store the backup codes somewhere safe: they are your way back in if you lose your phone.
3. Create an API key
Section titled “3. Create an API key”- Open API keys and click Create key.
- Give it a name (for example,
test) and tick only the Read permission (read), which is enough for this guide. - 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:
export MESSAJO_API_KEY="mj_..."Details in Authentication and API keys.
4. Test with GET /v1/me
Section titled “4. Test with GET /v1/me”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.
curl https://api.messajo.com/v1/me \ -H "Authorization: Bearer $MESSAJO_API_KEY"// npm install @messajo/sdkimport { Messajo } from "@messajo/sdk";
const messajo = new Messajo({ apiKey: process.env.MESSAJO_API_KEY! });const me = await messajo.me.get();console.log(me.organization.name, me.api_key.permissions);import os
import requests
response = requests.get( "https://api.messajo.com/v1/me", headers={"Authorization": f"Bearer {os.environ['MESSAJO_API_KEY']}"}, timeout=10,)response.raise_for_status()me = response.json()print(me["organization"]["name"], me["api_key"]["permissions"])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"}startis the visible prefix of the key, the same one the panel shows.kindisorg(mj_key) orconnection(mjc_key). On a connection key,connection_idandconnection { id, channel, label }identify its connection; on an organization key they arenull.connection_ids: nullmeans the organization key works for every connection; on a connection key it holds only that connection’s id.expires_atisnullwhen 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).
5. Connect a WhatsApp number
Section titled “5. Connect a WhatsApp number”- In the panel, open Connections → Connect WhatsApp.
- Pick the mode: Keep my WhatsApp Business (coexistence: the number stays in the app) or New number, API only, and click Continue.
- 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.
6. Send your first message
Section titled “6. Send your first message”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).
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." } }'const sent = await messajo.messages.send({ connection_id: "conn_...", to: "5511999999999", type: "text", text: { body: "Hi! Message sent with Messajo." },});n8n HTTP Request node settings
- Method:
POST - URL:
https://api.messajo.com/v1/messages - Authentication: Generic Credential Type, then Header Auth. Name:
Authorization; Value:Bearer mj_... - Headers: turn on Send Headers and add
Idempotency-Key(a unique value per item) - Body: turn on Send Body; Body Content Type: JSON; Specify Body: Using JSON
{ "connection_id": "conn_...", "to": "5511999999999", "type": "text", "text": { "body": "Hi! Message sent with Messajo." }}Replace mj_... with your API key.
The SDK generates the Idempotency-Key for you and retries safely when the network fails. See TypeScript SDK.
With a connection key
Section titled “With a connection key”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.
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!" } }'const sent = await messajo.connection().messages.send({ 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.
7. Receive the webhook
Section titled “7. Receive the webhook”- In Event destinations, add the HTTPS URL that will receive events. The panel shows the secret (
whsec_…) once. - Reply
2xxwithin 10 seconds. Otherwise Messajo retries with growing delays for up to 24 hours. - Send a message to your number: a
message.receivedevent 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.
Next steps
Section titled “Next steps”- Concepts: organizations, connections, keys and the two API layers.
- Authentication and API keys: permissions, expiration and good practices.
- Errors and Limits: what to handle in your code.
- Verify the signature: required before going to production.
- TypeScript SDK, History and Campaigns.
- Send text: the first of one page per message type.
- Build with AI:
llms.txt, per-page Markdown and the OpenAPI file.