# TypeScript SDK

> @messajo/sdk: install, first call, pagination, errors, safe retries, webhooks and WebSocket events.

`@messajo/sdk` is the official SDK for the `/v1` API. Its types are generated from the same OpenAPI as the [reference](/en/reference), so every field and every error code shows up in autocomplete.

- Zero dependencies, ESM. Runs on Node 20+, Bun, Deno, Workers and the browser.
- **MIT** license: you can embed it in closed-source code.

## Install

```bash
npm install @messajo/sdk
```

## First call

```ts
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);

const sent = await messajo.messages.send({
  connection_id: "conn_...",
  to: "5511999999999",
  type: "text",
  text: { body: "Hello! Sent with the SDK." },
});
console.log(sent.id, sent.status);
```

| Option | Default | What it is |
|---|---|---|
| `apiKey` | — | the `mj_…` (organization) or `mjc_…` (connection) key |
| `baseUrl` | `https://api.messajo.com/v1` | the API base URL|
| `maxRetries` | `2` | automatic retries (see below) |
| `timeoutMs` | `30000` | limit for each attempt |
| `fetch` | the global one | to inject another `fetch` (proxy, tests) |

Resources: `me`, `messages`, `conversations`, `contacts`, `campaigns`, `templates`, `media`, `connections`, `destinations`, `deliveries`, `events`, `connectionLinks`, `publications` and `apiKeys`. Meta's mirror layer is available raw at `messajo.mirror("whatsapp", connectionId, "message_templates")`.

## Connection key

An `mjc_…` key (created on the connection) sees only that connection: `/v1` resolves `connection_id` from the key and it can be omitted. Organization keys (`mj_…`) see every connection and are the only ones that manage keys; an `mjc_` key gets `403 organization_key_required` there. See [Authentication](/en/api/authentication/). `messajo.connection(id?)` returns a client that injects `connection_id`:

```ts
// Connection key: no connection_id.
const scoped = new Messajo({ apiKey: process.env.MESSAJO_CONNECTION_KEY! }).connection();
await scoped.messages.send({ to: "5511999999999", type: "text", text: { body: "Hello!" } });

// Organization key: pin the connection once.
const sales = messajo.connection("conn_...");
await sales.messages.send({ to: "5511999999999", type: "text", text: { body: "Hello!" } });

// Manage the connection keys (organization key only).
const key = await sales.apiKeys.create({ name: "CRM integration", permissions: ["send", "read"] });
```

These get `connection_id` pinned: `messages`, `conversations`, `contacts`, `campaigns`, `templates`, `media`, `publications`, `events`, `destinations.create` and `apiKeys`; `apiKeys.list`/`create` require `connection(id)`.

## Pagination

`paginate` walks any `{ data, next_cursor }` list by following the cursor:

```ts
for await (const conversation of messajo.paginate(messajo.conversations.list, {
  window: "open",
})) {
  console.log(conversation.id, conversation.contact.display_name);
}
```

For a single page, call the list directly: `await messajo.messages.list({ limit: 50 })`. See [History](/en/api/history/).

## Errors

Every error response becomes a `MessajoError` with the fields of the [error body](/en/errors/):

```ts
import { MessajoError } from "@messajo/sdk";

try {
  await messajo.messages.send({ /* ... */ });
} catch (error) {
  if (error instanceof MessajoError) {
    console.error(error.status, error.code, error.metaCode, error.requestId, error.docsUrl);
    if (error.code === "outside_service_window") {
      // outside the 24-hour window: send a template
    }
  }
}
```

`retryable`, `retryAfterMs` and `details` are on the error too.

## Safe retries

- The SDK generates an `Idempotency-Key` for every write (`POST`). To control the key, pass `{ idempotencyKey }` as the last argument, for example `messajo.messages.send(body, { idempotencyKey: order.id })`.
- `GET` and writes with an `Idempotency-Key` retry on their own on `429`, `503` and network failures, honoring `retry_after_ms` and `Retry-After`, up to `maxRetries`.
- `502` [`meta_unknown_outcome`](/en/errors#meta_unknown_outcome) is **never** retried: the message may have gone out. Check `message.status` before resending.

## Webhooks

```ts
import { verifyWebhookSignature } from "@messajo/sdk";

const body = await request.text(); // raw body, before JSON.parse
const result = await verifyWebhookSignature({
  header: request.headers.get("Messajo-Signature"),
  body,
  secret: process.env.MESSAJO_WEBHOOK_SECRET!,
});
if (!result.ok) {
  return new Response(result.reason, { status: 400 });
}
const event = JSON.parse(body);
```

`reason` is `missing`, `malformed`, `outside_tolerance` (more than 5 minutes) or `mismatch`. It uses WebCrypto, so it works the same on Node, Bun, Deno and Workers. Details in [Verify the signature](/en/webhooks/verify-signature/).

## WebSocket events

For a destination of type `websocket` ([Destination types](/en/webhooks/destinations/#websocket)):

```ts
import { connectEvents } from "@messajo/sdk";

const socket = connectEvents({
  client: messajo,
  destinationId: "dst_...",
  onEvent: async (event) => {
    // the ack goes out when this resolves; if it throws, Messajo delivers again
  },
  onError: (error) => console.error(error),
});
await socket.ready; // session id
// socket.close() to stop
```

Order is not guaranteed and the same event may arrive more than once: deduplicate by `event.id`. On Node 20, which has no global `WebSocket`, pass the `WebSocket` option (from the `ws` package).

## Versions

The SDK version follows the server's (`0.3.0-beta.1` for the beta). Pre-release versions are published under the npm `beta` tag: `npm install @messajo/sdk@beta`.
