Node.js 22+ · TypeScript · ESM e CommonJS
Seu sistema conectado com um token.
Use a API da Chattoo sem instalar banco, Supabase ou Baileys no seu projeto. A biblioteca já conhece a URL da plataforma e encontra a instância quando o projeto tem apenas uma.
1. Instale e configure
npm install @chattoo-br/node
# Defina CHATTOO_TOKEN no ambiente do seu servidor.SHA-256: 6b160c9b8343a52ee7ac5331879841b0247b04cedaa61d1884bcd2805f9b645e
Gere uma chave do projeto em Integrações e API. Para o exemplo, marque Consultar instâncias, Enviar comandos e Consultar comandos. Não coloque o token em frontend, URL ou repositório. Disponível no npm e por download direto.
2. Envie e acompanhe
import { Chattoo } from '@chattoo-br/node';
const chattoo = new Chattoo(process.env.CHATTOO_TOKEN!);
const { data: command } = await chattoo.messages.sendText(
{ to: '+5511999999999', text: 'Olá!' },
{ idempotencyKey: 'pedido-123-confirmacao' },
);
const result = await chattoo.commands.wait(command.id);
console.log(result.data.status, result.data.mode);O destinatário do exemplo é fictício. Teste com uma instância conectada. queued é aceite; succeeded é execução do comando e não confirma leitura. Em resultado uncertain, consulte os eventos antes de reenviar. Preserve a mesma chave de idempotência para a mesma intenção de negócio.
3. Pareie um WhatsApp Baileys liberado
await chattoo.sessions.pair();
const { data: pairing } = await chattoo.sessions.waitForPairing();
// Entregue pairing.value somente ao usuário autorizado para escanear.
// O SDK não imprime nem armazena o QR.
const session = await chattoo.sessions.waitForConnection();Conceda Consultar sessões, Gerenciar sessões e Acessar pareamento, além da descoberta de instância. A revisão é obtida automaticamente; SESSION_CHANGED pede nova decisão. A sessão não tem prazo fixo. O prazo dos helpers limita a espera do código, sem desconectar o WhatsApp. Revogação pelo aparelho ou saída confirmada encerram o vínculo.
4. Receba eventos no seu servidor
Cadastre sua URL HTTPS com webhooks.create. A resposta traz signingSecret uma única vez: guarde-o no servidor. Use verifyWebhook nos bytes originais ou createWebhookHandler com node:http. O segredo de assinatura é diferente do token de API.
O recebimento exige um endereço público. Para texto e remetente, autorize webhooks.setContent(id, true). O serviço mantém conteúdo pendente criptografado por até 24 horas, com remoção antecipada. Não há histórico de conversas. Responda a message.received e evite loops com message.echo.
Use webhooks.test(id) e webhooks.tests(id) para validar transporte, assinatura e diagnóstico. O evento webhook.test exige Node SDK 0.3 ou mais recente; não representa mensagem. A deduplicação padrão do receptor é limitada e local ao processo. Para reinícios e várias réplicas, forneça armazenamento compartilhado ou processamento idempotente. Os exemplos completos e a referência de erros acompanham o pacote.
5. React, Vite e Next.js
Use @chattoo-br/browser no frontend e @chattoo-br/node no backend do seu aplicativo. O token permanece no servidor. O navegador envia por um gateway autenticado que obtém CSRF automaticamente e recebe eventos por SSE.
npm install @chattoo-br/browser
import { ChattooBrowser } from '@chattoo-br/browser';
const chattoo = new ChattooBrowser();
// Em um evento de clique autorizado:
await chattoo.messages.sendText(
{ to: '+5511999999999', text: 'Olá!' },
{ idempotencyKey: 'pedido-123-confirmacao' },
);
// Em useEffect, retorne a função que fecha a assinatura:
const close = chattoo.events.subscribe(event => console.log(event.type));No Next.js, use um Client Component para interações e efeitos, e createChattooGateway em um Route Handler Node. Em Node HTTP use createNodeGatewayHandler. A autenticação e as permissões vêm da sessão do seu aplicativo; authorize é obrigatório. Nenhum token de projeto deve entrar em VITE_* ou NEXT_PUBLIC_*.
O laboratório usa login restrito do piloto. Informe o destinatário e clique para enviar; não há mensagens automáticas. O texto recebido fica somente na tela aberta. Confirmação QR adicional pertence apenas ao painel Baileys, sem etapa extra nos SDKs.
Referência de recursos
commands.get retorna routingDecision com canal, política e janela registrados no aceite. costs.get exige costs:read emitido por um owner/admin; custos reais desconhecidos retornam null. Browser costs.get exige costs.get explicitamente autorizado no gateway e na sessão do aplicativo.
| Recurso | Métodos TypeScript |
|---|---|
| Instâncias | instances.list / get / create / iterate |
| Mensagens | messages.sendText / sendTemplate |
| Comandos | commands.list / get / create / wait / iterate |
| Sessões | sessions.get / pair / pairing / waitForPairing / waitForConnection / reconnect / disconnect / logout |
| Webhooks | webhooks.list / get / create / disable / setContent / iterate |
| Templates e limites | templates.list / get / iterate · usage.get |
No Swagger, cada operação mostra seu método TypeScript e escopo. A autenticação funciona com o token do projeto, sem login no painel para consultar esta documentação.
Produção: Meta, coexistência e cobrança estão desativadas. O laboratório usa o ambiente de validação e suas próprias credenciais. Baileys real requer liberação por instância e pareamento no celular. O SDK preserva o modo informado pelo servidor e não oferece fallback, mídia, grupos ou importação de histórico. A homologação com aparelho permanece separada dos testes automatizados.