Ir al contenido

API y SDK

SDK de TypeScript

@messajo/sdk: instalar, primera llamada, paginación, errores, reintentos seguros, webhooks y eventos por WebSocket.

@messajo/sdk es el SDK oficial de la API /v1. Los tipos se generan del mismo OpenAPI de la referencia, así que cada campo y cada código de error aparecen en el autocompletado.

  • Cero dependencias, ESM. Funciona en Node 20+, Bun, Deno, Workers y el navegador.
  • Licencia MIT: puedes incluirlo en tu código cerrado.
Ventana de 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: "¡Hola! Mensaje enviado con el SDK." },
});
console.log(sent.id, sent.status);
Opción Por defecto Qué es
apiKey — la clave mj_… (organización) o mjc_… (conexión)
baseUrl https://api.messajo.com/v1 la URL base de la API
maxRetries 2 reintentos automáticos (consulta abajo)
timeoutMs 30000 límite de cada intento
fetch el global para inyectar otro fetch (proxy, pruebas)

Recursos: me, messages, conversations, contacts, campaigns, templates, media, connections, destinations, deliveries, events, connectionLinks, publications y apiKeys. La capa espejo de Meta sale cruda en messajo.mirror("whatsapp", connectionId, "message_templates").

Una clave mjc_… (creada en la conexión) ve solo esa conexión: la /v1 resuelve el connection_id por la clave y se puede omitir. Las claves de la organización (mj_…) ven todas las conexiones y son las únicas que gestionan claves; la mjc_ recibe 403 organization_key_required ahí. Consulta Autenticación. messajo.connection(id?) devuelve un cliente que inyecta el connection_id:

// Clave de conexión: sin connection_id.
const scoped = new Messajo({ apiKey: process.env.MESSAJO_CONNECTION_KEY! }).connection();
await scoped.messages.send({ to: "5511999999999", type: "text", text: { body: "¡Hola!" } });
// Clave de la organización: fija la conexión una vez.
const sales = messajo.connection("conn_...");
await sales.messages.send({ to: "5511999999999", type: "text", text: { body: "¡Hola!" } });
// Gestionar las claves de la conexión (solo clave de la organización).
const key = await sales.apiKeys.create({ name: "Integración CRM", permissions: ["send", "read"] });

Fijan el connection_id: messages, conversations, contacts, campaigns, templates, media, publications, events, destinations.create y apiKeys; apiKeys.list/create exigen connection(id).

paginate recorre cualquier lista { data, next_cursor } siguiendo el cursor:

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

Para una sola página, llama a la lista directamente: await messajo.messages.list({ limit: 50 }). Consulta Historial.

Toda respuesta de error se convierte en un MessajoError con los campos del cuerpo de error:

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") {
// fuera de la ventana de 24 h: manda una plantilla
}
}
}

retryable, retryAfterMs y details también están en el error.

  • El SDK genera un Idempotency-Key en toda escritura (POST). Para controlar la clave, pasa { idempotencyKey } como último argumento, por ejemplo messajo.messages.send(body, { idempotencyKey: pedido.id }).
  • GET y las escrituras con Idempotency-Key se repiten solos ante 429, 503 y fallos de red, respetando retry_after_ms y Retry-After, hasta maxRetries.
  • 502 meta_unknown_outcome nunca se repite: el mensaje puede haber salido. Revisa message.status antes de reenviar.
import { verifyWebhookSignature } from "@messajo/sdk";
const body = await request.text(); // cuerpo crudo, antes del 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 es missing, malformed, outside_tolerance (más de 5 minutos) o mismatch. Usa WebCrypto, así que funciona igual en Node, Bun, Deno y Workers. Detalles en Verificar la firma.

Para un destino de tipo websocket (Tipos de destino):

import { connectEvents } from "@messajo/sdk";
const socket = connectEvents({
client: messajo,
destinationId: "dst_...",
onEvent: async (event) => {
// el ack sale cuando esto se resuelve; si lanza, Messajo entrega de nuevo
},
onError: (error) => console.error(error),
});
await socket.ready; // id de la sesión
// socket.close() para terminar

El orden no está garantizado y el mismo evento puede llegar más de una vez: deduplica por event.id. En Node 20, que no tiene WebSocket global, pasa la opción WebSocket (del paquete ws).

La versión del SDK acompaña a la del servidor (0.3.0-beta.1 en la beta). Las versiones preliminares salen con la etiqueta beta de npm: npm install @messajo/sdk@beta.