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.
Instalar
Seção intitulada “Instalar”npm install @messajo/sdkPrimeira chamada
Seção intitulada “Primeira chamada”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").
Chave de conexão
Seção intitulada “Chave de conexão”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).
Paginação
Seção intitulada “Paginação”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.
Repetição segura
Seção intitulada “Repetição segura”- O SDK gera um
Idempotency-Keyem toda escrita (POST). Para controlar a chave, passe{ idempotencyKey }como último argumento, por exemplomessajo.messages.send(body, { idempotencyKey: pedido.id }). GETe escritas comIdempotency-Keyrepetem sozinhos em429,503e falha de rede, respeitandoretry_after_mseRetry-After, atémaxRetries.502meta_unknown_outcomenunca é repetido: a mensagem pode ter saído. Confira pelomessage.statusantes de reenviar.
Webhooks
Seção intitulada “Webhooks”import { verifyWebhookSignature } from "@messajo/sdk";
const body = await request.text(); // corpo cru, antes do 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 é 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.
Eventos por WebSocket
Seção intitulada “Eventos por WebSocket”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 encerrarA 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).
Versões
Seção intitulada “Versões”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.