SDK Node

Envelope fino e tipado sobre a API REST, sem dependências de runtime.

Preview público 0.31.0

Os pacotes @botozap/sdk, @botozap/cli e @botozap/mcp estão publicados no npm em versão preview 0.x, sem promessa de estabilidade até a 1.0. A API REST continua sendo o fallback estável. Veja a referência da API /v1 e o guia de Enviar mensagens. No terminal, use a CLI; em agentes, o MCP.

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

Instalação

pnpm add @botozap/sdk@0.31.0

Requer Node 22.12 ou superior, por causa do fetch global. O pacote publica ESM, CommonJS e tipos TypeScript. Fixe a versão: enquanto o pacote estiver em 0.x, uma versão menor pode mudar assinaturas.

Início rápido

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

const boto = new BotoZap({ apiKey: process.env.BOTOZAP_API_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.

O construtor aceita apiKey (obrigatória), baseUrl (padrão https://botozap.com.br/api/v1) e fetch, para injetar outra implementação em testes ou em runtimes sem fetch global.

Recursos e métodos

O cliente expõe 30 recursos como propriedades. A tabela mostra cada método e a rota da API /v1 que ele chama. Escopos, parâmetros e respostas ficam na referência.

RecursoMétodos e rotas
me
Identidade, ambiente e escopos da chave autenticada.
  • get → GET /me
messages
Envio no WhatsApp e no Instagram (texto, template, mídia por link, botões e listas, localização e reação); histórico por cursor. No Instagram o recibo traz wamid null, channel "instagram" e o mid em external_id. Todo envio aceita { idempotencyKey } no último argumento.
  • send → POST /messages: texto; quick_replies (até 13) só no Instagram; reply_to { message_id } responde citando
  • sendTemplate → POST /messages: template aprovado (só WhatsApp)
  • sendMedia → POST /messages: image, video, audio ou document por URL https; audio.voice: true manda mensagem de voz (.ogg Opus, só WhatsApp)
  • sendInteractive → POST /messages: button/list/cta_url no WhatsApp; button/generic no Instagram
  • sendLocation → POST /messages: localização (só WhatsApp)
  • sendReaction → POST /messages: emoji numa mensagem; emoji vazio retira
  • list → GET /messages: content.edited ({ count, at }) e revoked_at em mensagens do Instagram; reply_to, played_at e transcription quando houver
  • get → GET /messages/:id
customers
Clientes da revenda e links de setup (Embedded Signup).
  • list → GET /customers
  • get → GET /customers/:id
  • create → POST /customers
  • update → PATCH /customers/:id
  • delete → DELETE /customers/:id
  • listSetupLinks → GET /customers/:id/setup_links
  • createSetupLink → POST /customers/:id/setup_links
  • updateSetupLink → PATCH /customers/:id/setup_links/:linkId
templates
Templates de mensagem submetidos à Meta.
  • list → GET /templates
  • get → GET /templates/:id
  • create → POST /templates: opt_out_buttons marca os botões de resposta rápida que são de saída
  • update → PATCH /templates/:id: components (e category) editam e devolvem à análise da Meta; só opt_out_buttons é anotação do BotoZap
  • delete → DELETE /templates/:id: exclui na Meta e aqui; não dá para desfazer
  • sync → POST /templates/sync: traz da Meta status, categoria e conteúdo; customer_id limita a um Cliente
broadcasts
Transmissões: rascunho, destinatários, agendamento e envio.
  • list → GET /broadcasts
  • get → GET /broadcasts/:id
  • create → POST /broadcasts
  • update → PATCH /broadcasts/:id
  • listRecipients → GET /broadcasts/:id/recipients
  • addRecipients → POST /broadcasts/:id/recipients: itens { to_recipient, components? }; falhas por item voltam em errors { index, to_recipient?, reason }
  • removeRecipients → DELETE /broadcasts/:id/recipients
  • schedule → POST /broadcasts/:id/schedule
  • send → POST /broadcasts/:id/send
  • cancel → POST /broadcasts/:id/cancel
contacts
Contatos por Número, com nome dado pela empresa (display_name), tags e vínculo ao Cliente.
  • list → GET /contacts: filtro ig_follows_business; campos ig_* de seguidores são só leitura
  • get → GET /contacts/:id
  • create → POST /contacts: display_name opcional, independente do profile_name do canal; consents iniciais; warnings consent_opted_out ou consent_unconfirmed no 201
  • update → PATCH /contacts/:id: display_name null ou "" limpa o nome
  • delete → DELETE /contacts/:id: apaga a mídia; a recusa fica guardada como código cifrado e vale se o contato voltar
  • listConsents → GET /contacts/:id/consents: current e history; origens incluem contact_keyword, template_button, meta_opt_out e owner_declaration
  • recordConsent → POST /contacts/:id/consents: origem api; sobre uma recusa do contato responde 409 consent_opted_out
conversations
Conversas (com origem entry_point, anúncio de clique em referral e janela grátis fep_*), resposta direta, "digitando…" e leitura, controle do agente e atribuições.
  • list → GET /conversations: filtros channel (whatsapp | instagram), channel_account_id e ig_follows_business
  • get → GET /conversations/:id
  • update → PATCH /conversations/:id
  • reply → GET /conversations/:id + POST /messages: resolve o Contato e a origem (Número no WhatsApp, Conta do Instagram) e envia texto; aceita quick_replies no Instagram e reply_to para citar
  • typing → POST /conversations/:id/typing: "digitando…" ao contato na última mensagem recebida, que fica como lida; janela de 24h aberta; scope messages:send
  • listPendingSends → GET /conversations/:id/pending-sends: envios manuais que a Meta não confirmou, como o aviso na conversa; scope conversations:read
  • markPendingSend → POST /conversations/:id/pending-sends/:sendId: outcome sent (saiu) ou not_sent (não saiu); scope messages:send
  • markRead → POST /conversations/:id/read: marca a conversa como lida, como abrir no painel; o contato vê os tiques azuis; scope conversations:write
  • controlAgent → POST /conversations/:id/agent-control: pause | resume
  • requestConsent → POST /conversations/:id/consent-request: pedido de consentimento no WhatsApp e no Instagram, com channel na resposta; janela de 24h aberta (outside_window no WhatsApp, window_closed no Instagram)
  • delete → DELETE /conversations/:id: exclui sem volta, com mídia; o contato fica; só Administrador
  • listAssignments → GET /conversations/:id/assignments
  • createAssignment → POST /conversations/:id/assignments
  • getAssignment → GET /conversations/:id/assignments/:assignmentId
  • updateAssignment → PATCH /conversations/:id/assignments/:assignmentId
webhooks
Endpoints de webhook, filtro por Cliente e por canal, rotação do secret e teste assinado.
  • list → GET /webhooks
  • get → GET /webhooks/:id
  • create → POST /webhooks: customer_id opcional limita as entregas a um Cliente; channel_account_ids, a canais
  • update → PATCH /webhooks/:id: secret rotaciona; customer_id null remove o filtro; channel_account_ids null volta a todos os canais
  • delete → DELETE /webhooks/:id
  • test → POST /webhooks/:id/test
phoneNumbers
Números conectados, nome local (label) e saúde, e as configurações do número no WhatsApp, lidas e gravadas na Meta: perfil e foto, perguntas prontas e comandos, QR codes e contatos bloqueados. Em coexistência o perfil só muda pelo app do celular.
  • list → GET /phone_numbers
  • get → GET /phone_numbers/:id
  • update → PATCH /phone_numbers/:id: só o label; null ou "" limpa
  • delete → DELETE /phone_numbers/:id
  • health → GET /phone_numbers/:id/health
  • resubscribeWebhooks → POST /phone_numbers/:id/webhook-subscription: inscreve de novo as mensagens do número; 409 reconnect_required pede o link de setup
  • getHistoryImport → GET /phone_numbers/:id/history-import: conversas antigas do app em coexistência; 404 history_import_not_available
  • setHistoryImport → PUT /phone_numbers/:id/history-import: window_days 0, 30 ou 180; uma vez por conexão, 409 history_import_locked
  • getProfile → GET /phone_numbers/:id/profile: Sobre, descrição, endereço, e-mail, sites, categoria e foto; editable false em coexistência
  • updateProfile → PATCH /phone_numbers/:id/profile: só painel e chave de API; pelo OAuth responde 403
  • uploadProfilePhoto → POST /phone_numbers/:id/profile/photo: multipart, campo file; JPG ou PNG até 4 MB
  • getConversationalAutomation → GET /phone_numbers/:id/conversational-automation: perguntas prontas e comandos
  • updateConversationalAutomation → PATCH /phone_numbers/:id/conversational-automation: campo omitido mantém; gravar exige plano com automações
  • clearConversationalAutomation → DELETE /phone_numbers/:id/conversational-automation: remove tudo; livre em qualquer plano
  • qrCodes.list → GET /phone_numbers/:id/qr-codes
  • qrCodes.create → POST /phone_numbers/:id/qr-codes: mensagem pronta até 140 caracteres; não é idempotente
  • qrCodes.get → GET /phone_numbers/:id/qr-codes/:code: qr_image_url temporária, PNG ou SVG
  • qrCodes.update → PATCH /phone_numbers/:id/qr-codes/:code: troca só a mensagem pronta
  • qrCodes.delete → DELETE /phone_numbers/:id/qr-codes/:code: sem volta: o código impresso passa a dizer expirado
  • blockedUsers.list → GET /phone_numbers/:id/blocked-users: 100 por página, cursor after
  • blockedUsers.block → POST /phone_numbers/:id/blocked-users: contact_id ou user; só quem escreveu nas últimas 24 h
  • blockedUsers.unblock → DELETE /phone_numbers/:id/blocked-users/:user
channelAccounts
Contas de canal, conexão, IA de comentários, Regras de comentário e mensagem, QR, perguntas e menu do Instagram. Regras aceitam require_follow e non_follower_text; comentários aceitam live. O bloco instagram traz a saúde do token: token_status ok | expiring | expired | invalid | revoked | unknown.
  • list → GET /channel_accounts: filtros channel e customer_id; scope numbers:read
  • get → GET /channel_accounts/:id: UUID ou id na Meta (external_id)
  • getConnection → GET /channel_accounts/:id/connection: scope numbers:read; estado e diagnóstico, sem sandbox
  • resubscribeConnection → POST /channel_accounts/:id/connection/resubscribe: scope numbers:write; reassina com a autorização existente
  • disconnect → DELETE /channel_accounts/:id/connection: scope numbers:write; desconecta por chave de API
  • getCommentAi → GET /channel_accounts/:id/comment-ai: scope agents:read; configuração, uso diário e prontidão; sem sandbox
  • updateCommentAi → PATCH /channel_accounts/:id/comment-ai: scope agents:write; enabled, agent_id e daily_limit (1 a 200); plano com IA, exceto só desligar; OAuth somente painel
  • listCommentAiRuns → GET /channel_accounts/:id/comment-ai/runs: scope agents:read; decisões e envios, paginação por página; sem sandbox
  • getMessageRuleQr → GET /channel_accounts/:id/message-rules/:ruleId/qr: scope message-rules:read; ArrayBuffer PNG ou SVG; informe format
  • listCommentRules → GET /channel_accounts/:id/comment-rules: scope comment-rules:read
  • getCommentRule → GET /channel_accounts/:id/comment-rules/:ruleId
  • createCommentRule → POST /channel_accounts/:id/comment-rules: scope comment-rules:write; plano com Regras de comentário
  • updateCommentRule → PATCH /channel_accounts/:id/comment-rules/:ruleId: só os campos enviados; is_active false desliga
  • deleteCommentRule → DELETE /channel_accounts/:id/comment-rules/:ruleId
  • getCommentRuleMetrics → GET /channel_accounts/:id/comment-rules/:ruleId/metrics: from e to obrigatórios; resultados por período e post, incluindo live
  • listMessageRules → GET /channel_accounts/:id/message-rules: scope message-rules:read; paginação por página
  • getMessageRule → GET /channel_accounts/:id/message-rules/:ruleId
  • createMessageRule → POST /channel_accounts/:id/message-rules: scope message-rules:write; keyword, story_reply, story_mention, share, ref ou ad
  • updateMessageRule → PATCH /channel_accounts/:id/message-rules/:ruleId: PATCH parcial; ref_link calculado pelo servidor
  • deleteMessageRule → DELETE /channel_accounts/:id/message-rules/:ruleId
  • getMessengerProfile → GET /channel_accounts/:id/messenger-profile: scope messenger-profile:read; espelho salvo de perguntas e menu
  • updateMessengerProfile → PATCH /channel_accounts/:id/messenger-profile: scope messenger-profile:write; null ou [] remove a seção
  • deleteMessengerProfile → DELETE /channel_accounts/:id/messenger-profile
  • syncMessengerProfile → POST /channel_accounts/:id/messenger-profile/sync: verifica e reaplica a configuração salva; sem sandbox
contactStages
Etapas do funil por Cliente.
  • list → GET /contact-stages
  • create → POST /contact-stages
  • update → PATCH /contact-stages/:id
  • delete → DELETE /contact-stages/:id
  • reorder → PATCH /contact-stages/reorder
contactFields
Campos personalizados da Conta.
  • list → GET /contact-fields
  • create → POST /contact-fields
  • update → PATCH /contact-fields/:id
  • delete → DELETE /contact-fields/:id
calendar
Google Calendar autorizado no Painel: calendários, sincronização e conflitos.
  • connections → GET /calendar/connections
  • disconnect → DELETE /calendar/connections/:id
  • calendars → GET /calendar/connections/:id/calendars
  • refresh → POST /calendar/connections/:id/refresh
  • select → PATCH /calendar/selections/:id
  • jobs → GET /calendar/jobs
  • retryJob → POST /calendar/jobs/:id/retry
  • resolveConflict → POST /calendar/conflicts/:appointmentId/resolve
ai
Módulo de IA BYOK: 23 sub-recursos e 154 operações tipadas, mais invoke(group, name, input); ai.agents.diagnostic lê o diagnóstico do painel sem custo, e ai.files cuida da biblioteca de arquivos do agente.
154 operações em /ai/*, agrupadas em 23 sub-recursos (uploads, files, agents, credentials, providers, executions, knowledge, memory, skills, followupFlows, followups, routers, cases, alerts, notices, proposals, usage, commercialProposals, eligibility, inferences, operator, evolution, styleAdjustments). Veja Agente de IA.
appointments
Agenda: compromissos, disponibilidade e configuração (serviços, jornadas, exceções).
  • list → GET /appointments
  • get → GET /appointments/:id
  • create → POST /appointments
  • update → PATCH /appointments/:id
  • delete → DELETE /appointments/:id
  • history → GET /appointments/:id/history
  • availability → GET /appointments/availability
  • services.list → GET /appointments/services
  • services.create → POST /appointments/services
  • services.update → PATCH /appointments/services/:id
  • schedules.list → GET /appointments/schedules
  • schedules.create → POST /appointments/schedules
  • schedules.update → PATCH /appointments/schedules/:id
  • exceptions.list → GET /appointments/exceptions
  • exceptions.create → POST /appointments/exceptions
  • exceptions.update → PATCH /appointments/exceptions/:id
  • exceptions.delete → DELETE /appointments/exceptions/:id
journeys
Réguas e suas execuções, e os modelos prontos da galeria de Automações.
  • list → GET /journeys
  • get → GET /journeys/:id
  • create → POST /journeys
  • update → PUT /journeys/:id
  • delete → DELETE /journeys/:id: arquiva, preservando histórico
  • control → POST /journeys/:id/control
  • runs → GET /journeys/:id/runs
  • enroll → POST /journeys/:id/runs
  • getRun → GET /journey-runs/:id
  • controlRun → POST /journey-runs/:id/control
  • catalog → GET /journeys/catalog: modelos prontos com o texto do template e o exemplo de cada variável
  • enableModel → POST /journeys/catalog/:key/enable: liga o modelo no Cliente e envia o template à Meta; reenvia o recusado; exige plano com automações
savedReplies
Respostas salvas compartilhadas.
  • list → GET /saved-replies
  • get → GET /saved-replies/:id
  • create → POST /saved-replies
  • update → PATCH /saved-replies/:id
  • delete → DELETE /saved-replies/:id
inbox
Notas internas, retornos, arquivo e adiamento de uma Conversa.
  • get → GET /conversations/:id/tools
  • mutate → PATCH /conversations/:id/tools
opportunities
Oportunidades do CRM.
  • list → GET /opportunities
  • get → GET /opportunities/:id
  • create → POST /opportunities
  • update → PATCH /opportunities/:id
  • activities → GET /opportunities/:id/activities
  • conversations → GET /opportunities/:id/conversations
  • linkConversation → POST /opportunities/:id/conversations
  • unlinkConversation → DELETE /opportunities/:id/conversations
demands
Demandas do CRM (mesmos métodos de opportunities).
  • list → GET /demands
  • get → GET /demands/:id
  • create → POST /demands
  • update → PATCH /demands/:id
  • activities → GET /demands/:id/activities
  • conversations → GET /demands/:id/conversations
  • linkConversation → POST /demands/:id/conversations
  • unlinkConversation → DELETE /demands/:id/conversations
radar
Pendências do CRM e critérios por etapa.
  • list → GET /radar
  • stageRules → GET /radar/stage-rules
  • configureStageRule → PUT /radar/stage-rules/:stageId
media
Ingestão de mídia por URL e metadados de mídia recebida.
  • upload → POST /media: a BotoZap baixa a URL source e devolve media_id ou handle
  • get → GET /media/:id: inclui download_url assinada; 202 vira media_not_ready
events
Replay do log de Eventos por cursor.
  • list → GET /events: external_id é o id da mensagem no canal; message_id é o wamid ou null; instagram.message.edited e .revoked chegam aqui e no webhook
usage
Custo aproximado da Meta por moeda, dia e categoria (Pricing Analytics).
  • metaCosts → GET /usage/meta-costs: scope customers:read; customer_id, from e to opcionais; custo ausente fica null, nunca 0
billing
Plano da Conta, slots adicionais e garantia de 7 dias (só chave de API).
  • get → GET /billing: plano, negócios incluídos, slots e guarantee (garantia de 7 dias); billing:read
  • slots.create → POST /billing/slots: compra um slot (R$ 47/mês); idempotencyKey evita compra dupla; billing:write
  • slots.cancel → DELETE /billing/slots/:id: cancela um slot vazio, sem reembolso; billing:write
exports
Exportação de dados da Conta ou de um Cliente, em zip por tipo de dado (json ou csv), com link de download curto.
  • create → POST /exports: scope exports:write; customer_id e format opcionais; 202 no pedido novo, 200 no mesmo ainda na fila
  • list → GET /exports: scope exports:read; últimos 50 pedidos, sem o link
  • get → GET /exports/:id: scope exports:read; com o pedido pronto traz download.url, que vale poucos minutos
teamEvents
Registro de atividades da equipe (leitura, só Administrador).
  • list → GET /team_events: scope team:read; filtros since, until, actor_id, action, target_type e target_id; paginação por cursor
users
Membros da Conta (leitura).
  • list → GET /users
apiLogs
Auditoria de requisições à API e os avisos da Meta contados por hora (leitura).
  • list → GET /api_logs
  • metaHourly → GET /api_logs/meta_hourly
webhookDeliveries
Histórico de Entregas de webhook e reenvio das esgotadas.
  • list → GET /webhook_deliveries
  • replay → POST /webhook_deliveries/:id/replay

boto.ai também oferece invoke(group, name, input), que executa só operações declaradas no catálogo do SDK. O cliente tem putArtifact(url, contentType, file) para enviar um arquivo à URL assinada devolvida por ai.uploads.prepare.

Exemplos de uso

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

await boto.messages.sendMedia({
  to: "+5531988887777",
  type: "document",
  link: "https://cdn.exemplo.com/fatura.pdf",
  caption: "Fatura de agosto",
  filename: "fatura-agosto.pdf",
});

// Responde a Conversa sem montar to/from: o SDK lê a Conversa e envia texto.
await boto.conversations.reply(conversationId, { text: "Já te respondo!" });

const broadcast = await boto.broadcasts.create({
  name: "Promo de sexta",
  phone_number_id,
  template_name: "promo_sexta",
  template_language: "pt_BR",
});
const { added, duplicates, errors } = await boto.broadcasts.addRecipients(broadcast.id, [
  { to_recipient: "+5531988887777" },
  {
    to_recipient: "+5531977776666",
    components: [{ type: "body", parameters: [{ type: "text", text: "Ana" }] }],
  },
]);
for (const e of errors) console.warn(e.index, e.to_recipient, e.reason);
await boto.broadcasts.send(broadcast.id);

const { data: numeros } = await boto.phoneNumbers.list({ customer_id });
await boto.phoneNumbers.update(numeros[0].id, { label: "Loja Centro" }); // null limpa

// Custo aproximado da Meta por moeda; custo ausente vem null, nunca 0.
const custos = await boto.usage.metaCosts({ from: "2026-09-01", to: "2026-09-24" });
for (const total of custos.totals) console.log(total.currency, total.cost ?? "indisponível");

// Endpoint que só recebe as entregas de um Cliente da Conta.
const hook = await boto.webhooks.create({
  url: "https://seu-dominio.example/webhooks/botozap",
  events: ["messages", "statuses"],
  customer_id,
});
await boto.webhooks.update(hook.id, { secret: novoSecret }); // rotaciona
await boto.webhooks.update(hook.id, { customer_id: null }); // volta a receber de toda a Conta

broadcasts.addRecipients aceita até 1000 objetos { to_recipient, components? } por chamada, com os parâmetros do template de cada destinatário; strings soltas não são aceitas. Item inválido não derruba o lote: ele volta em errors como { index, to_recipient?, reason }, e as repetições contam em duplicates.

Em webhooks.update, secret rotaciona o secret de assinatura (16 a 256 caracteres, sem quebra de linha) e não volta na resposta; veja Rotacionar o secret. customer_id limita as entregas a um Cliente da Conta, e null no update remove o filtro.

Instagram

O mesmo messages.send manda direct no Instagram: o to é o IGSID do contato, e com mais de uma conta do Instagram ativa o from é o UUID da Conta de canal. O recibo do Instagram traz wamid: null, channel: "instagram" e o mid da Meta em external_id; ramifique por channel, não pela presença de wamid. As regras do canal (janela, etiqueta de atendente humano, arquivos) estão em Enviar para o Instagram.

const sent = await boto.messages.send({
  to: igsid,
  text: "Qual tamanho você procura?",
  quick_replies: [
    { title: "P", payload: "TAM_P" },
    { title: "M", payload: "TAM_M" },
    { content_type: "user_email" },
  ],
});
console.log(sent.channel, sent.external_id); // "instagram", mid da Meta

// Só as conversas do Instagram; reply usa a Conta do Instagram como origem.
const { data: directs } = await boto.conversations.list({ channel: "instagram" });
await boto.conversations.reply(directs[0].id, { text: "Já te respondo!" });

// Contas de canal: o bloco instagram traz a saúde do token.
const { data: contas } = await boto.channelAccounts.list({ channel: "instagram" });
for (const conta of contas) console.log(conta.display, conta.instagram?.token_status);

// IA de comentários: comece consultando a prontidão, sem ativar.
const ia = await boto.channelAccounts.getCommentAi(contas[0].id);
console.log(ia.status, ia.readiness, ia.answered_today, ia.reserved_today);
await boto.channelAccounts.updateCommentAi(contas[0].id, {
  agent_id: agentePublicadoId,
  daily_limit: 50,
});
// Ativar permite respostas públicas e DMs automáticas:
// await boto.channelAccounts.updateCommentAi(contas[0].id, { enabled: true });
const { data: execucoes, meta } = await boto.channelAccounts.listCommentAiRuns(contas[0].id, {
  page: 1, per_page: 20,
});
for (const execucao of execucoes) console.log(execucao.status, execucao.reason_message);

// Regra de comentário: quem comentar "quero" no post recebe o direct.
await boto.channelAccounts.createCommentRule(contas[0].id, {
  keyword: "quero",
  dm_text: "Oi! Te mandei o link por aqui.",
  media_id: postId,
});

// Estado confirmado, reassinatura e desconexão (sem sandbox).
const conexao = await boto.channelAccounts.getConnection(contas[0].id);
console.log(conexao.health, conexao.diagnostic.next_step);
await boto.channelAccounts.resubscribeConnection(contas[0].id);
// await boto.channelAccounts.disconnect(contas[0].id);

// O link de uma Regra de mensagem pode virar QR local em PNG ou SVG.
const regra = await boto.channelAccounts.getMessageRule(contas[0].id, ruleId);
console.log(regra.ref_link);
const qr = await boto.channelAccounts.getMessageRuleQr(contas[0].id, ruleId, { format: "png" });
await writeFile("qr.png", new Uint8Array(qr));

A IA de comentários exige uma conta real do Instagram. Consultar a configuração e o histórico exige agents:read; alterar exige agents:write e plano com IA. Envie ao menos um de enabled, agent_id ou daily_limit: campos omitidos são preservados, agent_id: null limpa o agente e o limite diário aceita inteiros de 1 a 200 (padrão 50), no fuso America/Sao_Paulo. Enviar somente { enabled: false } permite desligar mesmo sem plano com IA. No OAuth, o PATCH fica restrito ao painel. A Regra de comentário tem prioridade sobre a IA. Veja IA de comentários.

getConnection exige numbers:read; reassinar e desconectar exigem numbers:write. O QR exige message-rules:read e uma regra com link. Informe format: "png" ou format: "svg"; o resultado é um ArrayBuffer. No exemplo, importe writeFile de node:fs/promises.

Regras de comentário e mensagem aceitam require_follow e non_follower_text; comentários também aceitam live. Contatos expõem os campos de seguidor ig_* somente para leitura. Filtre contatos e conversas por ig_follows_business: omitir o filtro, enviar true e enviar false têm significados diferentes.

token_status vale ok, expiring (vence em até 7 dias; a renovação automática ainda tenta), expired, invalid, revoked ou unknown; com expired, invalid ou revoked os envios falham até a conta ser reconectada. quick_replies (até 13) só existem no Instagram. Em messages.list e messages.get, a mensagem do Instagram editada pelo contato traz content.edited ({ count, at }) e a apagada traz revoked_at; os Eventos instagram.message.edited e instagram.message.revoked chegam por events.list e pelo webhook, como os demais.

Paginação

As listas por cursor (messages, contacts, conversations, webhooks, journeys, apiLogs, webhookDeliveries) devolvem { data, paging }. Para a próxima página, passe paging.next em after. As listas por página usam page/per_page e devolvem { data, meta }. Listas curtas, como contactStages.list e contactFields.list, devolvem o array direto. Rotas de item são desempacotadas: o método devolve a entidade, sem o envelope { data }.

events.list é o replay do stream de Eventos: leia até paging.has_more ficar falso e persista paging.cursor para a próxima leitura.

let after = cursorSalvo ?? "0";
while (true) {
  const page = await boto.events.list({ after, limit: 100 });
  for (const event of page.data) console.log(event.type, event.id, event.external_id);
  after = page.paging.cursor;
  if (!page.paging.has_more) break;
}

Em cada Evento de mensagem, external_id é o identificador da mensagem no canal (o wamid no WhatsApp). message_id continua sendo o wamid, mas vem null fora do WhatsApp; os dois são null em Eventos sem mensagem, como os de CRM.

O que o SDK não cobre

Estas rotas da API /v1 não têm método dedicado no 0.31.0:

  • GET /media/:id/download: proposital: media.get já devolve a mesma download_url, sem o redirect 302.

Para chamá-las com a mesma autenticação e o mesmo tratamento de erro, use o método de baixo nível request, com o caminho relativo à URL base:

const consents = await boto.request("GET", `/contacts/${contactId}/consents`);

Tratamento de erro

Respostas fora de 2xx, ou com o envelope { error: { code, message } } mesmo em 2xx, viram BotoZapError com code, message, status HTTP e os headers da resposta. Use os headers para ler Retry-After num 429 ou no 202 media_not_ready de media.get. Falha de rede vira network_error e resposta fora do contrato vira malformed_response, ambos com status 0. Veja a 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, err.headers?.["retry-after"]);
  } 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, com a chave sempre em variável de ambiente:

  • node-javascript: envio no sandbox, leitura da resposta e BotoZapError.
  • node-typescript: envio tipado, leitura paginada por cursor e erro estruturado.
  • webhook-receiver: valida o X-Webhook-Signature-V2 do BotoZap (HMAC-SHA256 hex de timestamp, chave de idempotência e bytes crus, com 5 minutos de tolerância), deduplica por X-Idempotency-Key na mesma transação do efeito e só então responde 2xx.
  • agent-endpoint: Endpoint durável com fila PostgreSQL, worker de agente por LISTEN/NOTIFY e resposta pela API.
  • mcp-sandbox: configuração mínima do @botozap/mcp com chave sandbox.

Para receber Eventos, veja Webhooks e o Endpoint para agentes.