Pular para o conteúdo

API e SDK

SDK TypeScript

@messajo/sdk: instalar, primeira chamada, paginação, erros, repetição segura, webhooks e eventos por WebSocket.

@messajo/sdk é o SDK oficial da API /v1. Os tipos são gerados do mesmo OpenAPI da referência, então todo campo e todo código de erro aparecem no autocompletar.

  • Zero dependências, ESM. Roda no Node 20+, Bun, Deno, Workers e navegador.
  • Licença MIT: pode embutir no seu código fechado.
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: "Olá! Mensagem enviada pelo SDK." },
});
console.log(sent.id, sent.status);
Opção Padrão O que é
apiKey — a chave mj_… (organização) ou mjc_… (conexão)
baseUrl https://api.messajo.com/v1 a URL base da API
maxRetries 2 repetições automáticas (veja abaixo)
timeoutMs 30000 limite de cada tentativa
fetch o global para injetar outro fetch (proxy, testes)

Recursos: me, messages, conversations, contacts, campaigns, templates, media, connections, destinations, deliveries, events, connectionLinks, publications e apiKeys. A camada espelho da Meta sai crua em messajo.mirror("whatsapp", connectionId, "message_templates").

Uma chave mjc_… (criada na conexão) enxerga só aquela conexão: a /v1 resolve o connection_id pela chave e ele pode ser omitido. Chaves da organização (mj_…) enxergam todas as conexões e são as únicas que gerenciam chaves; a mjc_ recebe 403 organization_key_required ali. Veja Autenticação. messajo.connection(id?) devolve um cliente que injeta o connection_id:

// Chave de conexão: sem connection_id.
const scoped = new Messajo({ apiKey: process.env.MESSAJO_CONNECTION_KEY! }).connection();
await scoped.messages.send({ to: "5511999999999", type: "text", text: { body: "Olá!" } });
// Chave da organização: fixa a conexão uma vez.
const sales = messajo.connection("conn_...");
await sales.messages.send({ to: "5511999999999", type: "text", text: { body: "Olá!" } });
// Gerenciar chaves da conexão (só chave da organização).
const key = await sales.apiKeys.create({ name: "Integração CRM", permissions: ["send", "read"] });

Ficam com o connection_id fixado: messages, conversations, contacts, campaigns, templates, media, publications, events, destinations.create e apiKeys; apiKeys.list/create exigem connection(id).

paginate percorre qualquer lista { data, next_cursor } seguindo o cursor:

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

Para uma página só, chame a lista direto: await messajo.messages.list({ limit: 50 }). Veja Histórico.

Toda resposta de erro vira um MessajoError com os campos do corpo de erro:

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") {
// fora da janela de 24 h: mande um template
}
}
}

retryable, retryAfterMs e details também estão no erro.

  • O SDK gera um Idempotency-Key em toda escrita (POST). Para controlar a chave, passe { idempotencyKey } como último argumento, por exemplo messajo.messages.send(body, { idempotencyKey: pedido.id }).
  • GET e escritas com Idempotency-Key repetem sozinhos em 429, 503 e falha de rede, respeitando retry_after_ms e Retry-After, até maxRetries.
  • 502 meta_unknown_outcome nunca é repetido: a mensagem pode ter saído. Confira pelo message.status antes de reenviar.
import { verifyWebhookSignature } from "@messajo/sdk";
const body = await request.text(); // corpo cru, antes do 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 é missing, malformed, outside_tolerance (mais de 5 minutos) ou mismatch. Usa WebCrypto, então funciona igual no Node, no Bun, no Deno e em Workers. Detalhes em Verificar a assinatura.

Para um destino do tipo websocket (Tipos de destino):

import { connectEvents } from "@messajo/sdk";
const socket = connectEvents({
client: messajo,
destinationId: "dst_...",
onEvent: async (event) => {
// o ack sai quando isto resolve; se lançar, o Messajo entrega de novo
},
onError: (error) => console.error(error),
});
await socket.ready; // id da sessão
// socket.close() para encerrar

A ordem não é garantida e o mesmo evento pode chegar mais de uma vez: desduplique por event.id. No Node 20, que não tem WebSocket global, passe a opção WebSocket (do pacote ws).

A versão do SDK acompanha a do servidor (0.3.0-beta.1 com o beta). Versões de pré-lançamento saem na tag beta do npm: npm install @messajo/sdk@beta.