SDK TypeScript

@wabox/sdk é o pacote oficial para TypeScript e JavaScript. Ele é gerado a partir do OpenAPI da API, então cada rota, body, parâmetro e resposta desta referência tem o tipo correspondente no editor. Toda página de endpoint mostra o equivalente em SDK na aba TypeScript.

npm install @wabox/sdk

Ele exige Node ≥ 20 (ou Bun, Deno, Cloudflare Workers, Vercel Edge). A única dependência é o openapi-fetch, e o pacote tem cerca de 6 kB.

Enviar e consultar

import { createWabox } from "@wabox/sdk";

const wabox = createWabox({
  instanceId: process.env.WABOX_INSTANCE_ID!,
  token: process.env.WABOX_TOKEN!,
  // apiKey: process.env.WABOX_API_KEY, // se o workspace exigir API key nas rotas de instância
});

const { data, error } = await wabox.POST("/send-text", {
  body: { phone: "5511988887777", message: "Olá! Seu pedido *#1234* foi confirmado." },
});
if (error) throw new Error(`${error.error.code}: ${error.error.message}`);
console.log(data.message_id); // id definitivo no WhatsApp; o resultado chega no webhook delivery

O caminho é relativo à instância (/send-text, /chats/{phone}, /groups): o SDK monta https://api.wabox.me/instances/{instance_id}/token/{token} por você. Parâmetros de rota e de query vão em params:

const { data } = await wabox.GET("/contacts/{phone}", {
  params: { path: { phone: "5511988887777" } },
});

const { data: page } = await wabox.GET("/chats", {
  params: { query: { page: 1, page_size: 50, archived: false } },
});

Cada chamada resolve com { data, error, response }. data vem tipado quando a resposta é 2xx, error vem tipado como { error: { code, message } } nos demais casos, e response é o Response cru, com status e headers como Retry-After.

Preferir exceções

unwrap() devolve só o data e lança WaboxError (code, status, details) quando a API responde erro:

import { createWabox, unwrap, WaboxError } from "@wabox/sdk";

try {
  const status = await unwrap(wabox.GET("/status"));
  if (!status.connected) console.log("instância desconectada:", status.status);
} catch (e) {
  if (e instanceof WaboxError && e.code === "rate_limited") {
    // respeite e.response.headers.get("Retry-After")
  }
  throw e;
}

Receber webhooks

constructWebhookEvent verifica o X-Wabox-Signature (HMAC-SHA256 sobre o corpo cru, com janela de 5 minutos contra replay) e devolve o evento tipado, discriminado por type:

import express from "express";
import { constructWebhookEvent, WaboxWebhookError } from "@wabox/sdk/webhooks";

const app = express();

// express.raw: a assinatura é calculada sobre os bytes originais, antes do parser JSON.
app.post("/wabox", express.raw({ type: "application/json" }), async (req, res) => {
  let event;
  try {
    event = await constructWebhookEvent({
      body: req.body, // Buffer
      headers: req.headers,
      secret: process.env.WABOX_WEBHOOK_SECRET!,
    });
  } catch (e) {
    if (e instanceof WaboxWebhookError) return res.status(401).end();
    throw e;
  }
  res.status(200).end(); // responda antes de processar

  switch (event.type) {
    case "received":
      if (event.text) console.log(`${event.phone}: ${event.text.message}`);
      break;
    case "delivery":
      console.log(event.wabox_id, event.status, event.error_code);
      break;
  }
});

import { constructWebhookEvent, WaboxWebhookError } from "@wabox/sdk/webhooks";

export async function POST(request: Request) {
  try {
    const event = await constructWebhookEvent({
      body: await request.text(),
      headers: request.headers,
      secret: process.env.WABOX_WEBHOOK_SECRET!,
    });
    queueMicrotask(() => handle(event));
    return new Response(null, { status: 200 });
  } catch (e) {
    if (e instanceof WaboxWebhookError) return new Response(null, { status: 401 });
    throw e;
  }
}

WaboxWebhookError.reason diz o motivo: invalid_signature (assinatura errada, ausente ou t fora da janela), invalid_json ou unknown_event. Se você só quer a verificação, use verifyWebhookSignature(secret, header, rawBody). Para processar sem verificar (não recomendado), use parseWebhookEvent(rawBody). O secret (whsec_…) é por instância, ou do workspace quando a instância herda os webhooks dele. Você o encontra em GET /webhooks ou no painel, em Webhooks e configurações gerais.

Account API

Contas com plano criam, atualizam e excluem instâncias com uma API key do workspace, até o número de slots do plano (veja Account API). A key precisa das permissões das rotas que você chama, aqui instances:read e instances:write. Sem elas, a API responde 403 insufficient_scope:

import { createWabox, createWaboxAccount, unwrap } from "@wabox/sdk";

const account = createWaboxAccount({ apiKey: process.env.WABOX_API_KEY! });

const plan = await unwrap(account.GET("/account/plan"));
if (plan.instances_available === 0) throw new Error("sem slots livres no plano");

const inst = await unwrap(account.POST("/account/instances", { body: { name: "Loja Centro" } }));
// guarde inst.id, inst.token e inst.webhooks.secret por cliente

const wabox = createWabox({ instanceId: inst.id, token: inst.token });
const { data: qr } = await wabox.GET("/qr-code");

Tipos

O SDK exporta como tipos todos os schemas nomeados da referência, como Instance, Chat, Contact, Group, SendResponse, QueueItem, WebhookReceived e WebhookDelivery, além de WebhookEvent (a união de todos os eventos). Para tipar o resto, use InstancePaths/AccountPaths (todas as rotas) e Schemas:

import type { Chat, Schemas, WebhookEvent, InstancePaths } from "@wabox/sdk";

type SendTextBody =
  InstancePaths["/send-text"]["post"]["requestBody"]["content"]["application/json"];

function onEvent(event: WebhookEvent) {
  if (event.type === "message_status") console.log(event.status, event.ids);
}

Opções

Opção	Onde	Para quê
`baseUrl`	`createWabox`, `createWaboxAccount`	Outro host (padrão `https://api.wabox.me`)
`apiKey`	`createWabox` (opcional), `createWaboxAccount` (obrigatório)	API key do workspace, enviada em `Authorization: Bearer`
`headers`	ambos	Headers extras em toda chamada
`fetch`	ambos	`fetch` customizado (proxy, retry, testes)
`toleranceSec`	`verifyWebhookSignature`, `constructWebhookEvent`	Janela anti-replay em segundos (padrão 300; `0` desliga)

O SDK não faz retry nem fila. Trate 429 (Retry-After), 409 instance_not_connected e 402 como descrito em Rate limits e erros. Envios não são idempotentes, então confira GET /queue antes de repetir uma chamada que falhou por rede.

Começar

Autenticação e segurança

Webhooks

Guias

Migrando do z-api

Integrações

Conta

Referências

SDK TypeScript

Enviar e consultar

Preferir exceções

Receber webhooks

Account API

Tipos

Opções

​Enviar e consultar

​Preferir exceções

​Receber webhooks

​Account API

​Tipos

​Opções

Enviar e consultar

Preferir exceções

Receber webhooks

Account API

Tipos

Opções