Primeira ação
Em 5 minutos: o contato pergunta “cadê meu pedido 1234?” no WhatsApp e o assistente responde com o status que vem do seu sistema.
1. Gere o segredo de ações
No painel, abra o chatbot, vá na aba Ações e toque em Gerar segredo. Ele começa com whsec_ e aparece uma vez só: guarde no seu servidor (aqui, na variável BOAVOZ_ACTION_SECRET). Toda chamada do BoaVoz vai assinada com ele.
2. Suba o endpoint
Um POST em HTTPS que recebe JSON e devolve JSON. A assinatura segue o padrão Standard Webhooks, então a biblioteca oficial confere tudo numa linha.
// npm i express standardwebhooks
import express from "express";
import { Webhook } from "standardwebhooks";
const app = express();
// o segredo de ações que o painel mostrou (whsec_...)
const wh = new Webhook(process.env.BOAVOZ_ACTION_SECRET);
// exemplo: os pedidos do seu sistema
const pedidos = {
"1234": { status: "saiu para entrega", previsao: "hoje, até as 20h", telefone: "5511999990000" },
};
// o corpo cru: a assinatura é conferida sobre ele
app.post("/boavoz/consultar-pedido", express.text({ type: "*/*" }), (req, res) => {
let chamada;
try {
// confere a assinatura e o horário (até 5 minutos) e devolve o JSON
chamada = wh.verify(req.body, req.headers);
} catch {
return res.status(401).json({ error: "assinatura inválida" });
}
// botão Testar do painel: sem conversa nem contato
if (chamada.test) return res.json({ data: { pedido: "TESTE", status: "teste ok" } });
const pedido = pedidos[String(chamada.params.pedido)];
// só o dono do pedido: o telefone que o WhatsApp garante
if (!pedido || pedido.telefone !== chamada.contact?.phone) {
return res.status(404).json({ error: "pedido não encontrado" });
}
res.json({ data: { pedido: chamada.params.pedido, status: pedido.status, previsao: pedido.previsao } });
});
app.listen(3000);contact.phone é o número garantido pela Meta (só dígitos, com o 55). Pedido de outra pessoa responde igual a pedido que não existe (404).3. Cadastre a ação
Na aba Ações do chatbot, crie a ação:
| Campo | Valor |
|---|---|
| Nome | consultar_pedido |
| URL | https://seu-sistema.com/boavoz/consultar-pedido |
| Descrição | Consulta o status e a previsão de entrega de um pedido pelo número. Use quando a pessoa perguntar do pedido dela. |
| Parâmetros | o JSON Schema abaixo |
| Tipo | consulta |
| Nível mínimo do contato | canal (a ação só aparece para a IA quando o canal garante quem é o contato) |
| Contexto | não exige |
{
"type": "object",
"properties": {
"pedido": { "type": "string", "description": "número do pedido" }
},
"required": ["pedido"]
}A descrição é o que a IA lê para decidir quando chamar: diga o que a ação faz e quando usar. A descrição dos parâmetros ajuda a IA a pedir o dado certo (“qual o número do pedido?”) quando a pessoa não disse.
4. Teste
Na ação cadastrada, use Testar com {"pedido": "1234"}. O BoaVoz chama o seu endpoint de verdade, com "test": true e sem conversa nem contato, e mostra a resposta.
5. Converse
No WhatsApp conectado ao chatbot, mande “cadê meu pedido 1234?”. A IA chama a ação e responde com o status e a previsão. Sem o número, ela pergunta qual é. Com um pedido de outra pessoa, diz que não encontrou.
É isto que o seu endpoint recebeu:
{
"call_id": "call_3f1c9a…",
"action": "consultar_pedido",
"params": { "pedido": "1234" },
"confirmed": false,
"bot": { "id": "bot_…" },
"conversation": { "id": "conv_…", "channel": "whatsapp" },
"contact": {
"id": "ctc_…",
"level": "canal",
"verified_by": "meta",
"phone": "5511999990000",
"whatsapp_user_id": null,
"age_confirmed": null,
"age_confirmed_source": null
},
"context": null
}O detalhe de cada campo, os prazos, o que você pode devolver (texto exato, botões, arquivos) e as ações que criam ou alteram algo, com o Confirmar do contato, estão em Ações.