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.
Instalar
Sección titulada «Instalar»npm install @messajo/sdkPrimera llamada
Sección titulada «Primera llamada»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").
Clave de conexión
Sección titulada «Clave de conexión»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).
Paginación
Sección titulada «Paginación»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.
Errores
Sección titulada «Errores»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.
Reintentos seguros
Sección titulada «Reintentos seguros»- El SDK genera un
Idempotency-Keyen toda escritura (POST). Para controlar la clave, pasa{ idempotencyKey }como último argumento, por ejemplomessajo.messages.send(body, { idempotencyKey: pedido.id }). GETy las escrituras conIdempotency-Keyse repiten solos ante429,503y fallos de red, respetandoretry_after_msyRetry-After, hastamaxRetries.502meta_unknown_outcomenunca se repite: el mensaje puede haber salido. Revisamessage.statusantes de reenviar.
Webhooks
Sección titulada «Webhooks»import { verifyWebhookSignature } from "@messajo/sdk";
const body = await request.text(); // cuerpo crudo, antes del 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 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.
Eventos por WebSocket
Sección titulada «Eventos por WebSocket»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 terminarEl 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).
Versiones
Sección titulada «Versiones»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.