Skip to content

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.
Janela do terminal
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);
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").

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

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.

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.

  • 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 is never retried: the message may have gone out. Check message.status before resending.
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.

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

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.