# Quickstart

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

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

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](/en/start/concepts/).

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

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.

## 3. Create an API key

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:

```bash
export MESSAJO_API_KEY="mj_..."
```

Details in [Authentication and API keys](/en/api/authentication/).

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

```bash
curl https://api.messajo.com/v1/me \
  -H "Authorization: Bearer $MESSAJO_API_KEY"
```

**TypeScript**

```ts
// npm install @messajo/sdk
import { 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);
```

**Python**

```python
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:

```json
{
  "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`](/en/errors#missing_api_key) (the header is missing) or [`invalid_api_key`](/en/errors#invalid_api_key) (wrong or revoked key).

## 5. Connect a WhatsApp number

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](/en/connect/whatsapp/).

## 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](/en/start/concepts/)).

**cURL**

```bash
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." }
  }'
```

**TypeScript**

```ts
const sent = await messajo.messages.send({
  connection_id: "conn_...",
  to: "5511999999999",
  type: "text",
  text: { body: "Hi! Message sent with Messajo." },
});
```

**n8n**

n8n HTTP Request: POST https://api.messajo.com/v1/messages

```json
{
    "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](/en/sdk/typescript/).

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

```bash
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!" } }'
```

**TypeScript**

```ts
const sent = await messajo.connection().messages.send({
  to: "5511999999999",
  type: "text",
  text: { body: "Hello!" },
});
```

See [Key types](/en/api/authentication/#key-types).

The response is `201`:

```json
{
  "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`](/en/errors#outside_service_window). Each type has its own page in the **Send messages** group, starting with [Send text](/en/send/text/); the fields of each are also in the [API reference](/en/reference).

## 7. Receive the webhook

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.

```json
{
  "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](/en/webhooks/verify-signature/). The full catalog is in [Events](/en/webhooks/events/).

## Next steps

- [Concepts](/en/start/concepts/): organizations, connections, keys and the two API layers.
- [Authentication and API keys](/en/api/authentication/): permissions, expiration and good practices.
- [Errors](/en/errors/) and [Limits](/en/api/limits/): what to handle in your code.
- [Verify the signature](/en/webhooks/verify-signature/): required before going to production.
- [TypeScript SDK](/en/sdk/typescript/), [History](/en/api/history/) and [Campaigns](/en/guides/campaigns/).
- [Send text](/en/send/text/): the first of one page per message type.
- [Build with AI](/en/start/build-with-ai/): `llms.txt`, per-page Markdown and the OpenAPI file.
