API and SDK
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, 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
Section titled “Install”npm install @messajo/sdkFirst call
Section titled “First call”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
Section titled “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. messajo.connection(id?) returns a client that injects connection_id:
// 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
Section titled “Pagination”paginate walks any { data, next_cursor } list by following the cursor:
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.
Errors
Section titled “Errors”Every error response becomes a MessajoError with the fields of the error body:
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
Section titled “Safe retries”- The SDK generates an
Idempotency-Keyfor every write (POST). To control the key, pass{ idempotencyKey }as the last argument, for examplemessajo.messages.send(body, { idempotencyKey: order.id }). GETand writes with anIdempotency-Keyretry on their own on429,503and network failures, honoringretry_after_msandRetry-After, up tomaxRetries.502meta_unknown_outcomeis never retried: the message may have gone out. Checkmessage.statusbefore resending.
Webhooks
Section titled “Webhooks”import { verifyWebhookSignature } from "@messajo/sdk";
const body = await request.text(); // raw body, before JSON.parseconst 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.
WebSocket events
Section titled “WebSocket events”For a destination of type websocket (Destination types):
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 stopOrder 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
Section titled “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.