Toda vez que algo acontece no seu sistema — pedido pago, entrega saiu, boleto vencendo — dá para avisar o cliente pelo WhatsApp automaticamente. A API foi feita para isso, e é compatível com integrações que já usavam o formato do BotBot.
1. Crie um aplicativo
No painel, em API e webhooks, crie um aplicativo e escolha por qual número ele vai enviar. Você recebe dois valores:
- appKey: identifica o aplicativo.
- authKey: a senha da integração. Guarde em variável de ambiente, nunca no código público.
2. Envie a primeira mensagem
curl -X POST https://SEU-DOMINIO/api/v2/sendText \
-H "appKey: SEU_APP_KEY" \
-H "authKey: SEU_AUTH_KEY" \
-H "Content-Type: application/json" \
-d '{"to":"5531999999999","message":"Seu pedido #123 foi aprovado ✅"}'A resposta traz success, o identificador da mensagem e a situação.
3. Outros tipos de envio
| Endpoint | Para quê |
|---|---|
| sendImage, sendVideo, sendDocument | Mídia por URL, com legenda |
| sendVoice | Áudio que aparece como gravado na hora |
| sendContact | Cartão de contato |
| sendTemplate | Um modelo salvo no painel (texto ou mídia) |
| sendReply | Dispara uma resposta do chatbot (listas e botões inclusos) |
| messages | Vários canais de uma vez (WhatsApp, e-mail, SMS) |
Para não travar o seu sistema, use a fila: com queue: true a API responde na hora e envia em segundo plano; delay agenda alguns segundos depois.
4. Receba eventos com webhooks
Cadastre uma URL e escolha os eventos: mensagem recebida, mensagem enviada, falha, número conectado ou desconectado, envio em massa concluído. Cada chamada vem com o cabeçalho X-Signature, um HMAC SHA-256 do corpo usando o segredo do webhook. Confira a assinatura antes de confiar no conteúdo.
5. Boas práticas
- Idempotência: guarde o id do pedido e não reenvie o mesmo aviso duas vezes se o seu sistema repetir a chamada.
- Números no formato internacional: 55 + DDD + número. Se faltar o 55, a API completa para números brasileiros.
- Trate falhas: se o número desconectar, a API responde com erro claro. Vale ter um alerta.
A documentação completa e o arquivo OpenAPI têm todos os campos.