SDK Node

O @botozap/sdk é a camada pública sobre a API HTTP: cobrindo os recursos da /v1 com tipos, montando a autenticação e traduzindo erros da API em exceções. O core da plataforma continua fechado.

Instalação

pnpm add @botozap/sdk

Requer Node 20.19 ou superior. O pacote publica ESM, CommonJS e tipos TypeScript.

Início rápido

import { BotoZap } from "@botozap/sdk";

const boto = new BotoZap({ apiKey: process.env.BOTOZAP_KEY! });

const result = await boto.messages.send({
  to: "+5531988887777",
  text: "Seu pão tá saindo do forno",
});

console.log(result.wamid, result.status);

A conta é derivada da chave de API. Você nunca passa um id de conta: o isolamento multi-tenant é garantido no servidor. Detalhes em Autenticação.

Recursos

Cada recurso é exposto como propriedade do cliente:

• messages: enviar texto e template, buscar por id.
• customers: listar, buscar, criar.
• templates: listar, buscar.
• broadcasts: criar, adicionar destinatários, agendar, enviar, cancelar.
• contacts: listar, buscar, criar, atualizar, remover.
• conversations: listar, buscar, atualizar, atribuições.
• webhooks: CRUD e teste.
• phoneNumbers: listar, buscar, remover e consultar saúde.
• flows: criar, versionar, publicar, data endpoint.
• media: subir arquivo e obter um media_id; buscar uma mídia recebida com a URL de download.
• users, apiLogs, webhookDeliveries: leitura.

await boto.messages.sendTemplate({
  to: "+5531988887777",
  template: { name: "boas_vindas", language: { code: "pt_BR" } },
});

const broadcast = await boto.broadcasts.create({
  name: "Promo de sexta",
  phone_number_id,
});
await boto.broadcasts.addRecipients(broadcast.id, ["+5531988887777"]);
await boto.broadcasts.send(broadcast.id);

const { data: numeros } = await boto.phoneNumbers.list({ customer_id });

Tratamento de erro

Respostas fora de 2xx viram BotoZapError, com o code e a message do envelope da API e o status HTTP, o mesmo envelope { error: { code, message } } que a API REST já usa hoje (veja Referência).

import { BotoZap, BotoZapError } from "@botozap/sdk";

try {
  await boto.messages.send({ to: "+5531988887777", text: "Olá!" });
} catch (err) {
  if (err instanceof BotoZapError) {
    console.error(err.code, err.status, err.message);
  } else {
    throw err;
  }
}

Repositório e exemplos

O código do SDK, da CLI, do MCP e os exemplos vivem em github.com/bytecraft-fernando/botozap-js . O diretório examples/ traz projetos mínimos e rodáveis:

• enviar-mensagem: enviar a primeira mensagem.
• webhook-receiver: receber mensagens, validando a assinatura da Meta.
• bot-eco: bot starter que recebe e responde.

Para receber eventos, veja Webhooks.