Ações

Consulta e executa

O BoaVoz também classifica as ações: a que cria pedido, reserva ou cobrança sempre pede o Confirmar, mesmo cadastrada como consulta. A IA nunca decide sozinha uma operação dessas: quem decide é o toque do contato.

Cadastro

No painel: chatbot → aba Ações (dono ou administrador da agência, com a verificação em duas etapas). O segredo de ações do chatbot precisa existir antes (botão Gerar segredo).

A chamada

O BoaVoz faz um POST com JSON. Cabeçalhos: content-type: application/json, user-agent: BoaVoz-Acoes/1, os três da assinatura e os seus personalizados.

{
  "call_id": "call_3f1c9a0b…",
  "action": "consultar_pedido",
  "params": { "pedido": "1234" },
  "confirmed": false,
  "bot": { "id": "bot_8c1e…" },
  "conversation": { "id": "conv_14a2…", "channel": "whatsapp" },
  "contact": {
    "id": "ctc_77d0…",
    "level": "canal",
    "verified_by": "meta",
    "phone": "5511999990000",
    "whatsapp_user_id": null,
    "age_confirmed": true,
    "age_confirmed_source": "chat"
  },
  "context": null
}

Assinatura

Toda chamada vai assinada no padrão Standard Webhooks com o segredo de ações do chatbot: cabeçalhos webhook-id (o call_id), webhook-timestamp e webhook-signature. Confira com a biblioteca oficial (há para Node, Python, Go, PHP, Ruby, Java e outras) e recuse o que falhar ou tiver mais de 5 minutos.

// Node: npm i standardwebhooks
import { Webhook } from "standardwebhooks";
const wh = new Webhook(process.env.BOAVOZ_ACTION_SECRET); // whsec_...

// corpo cru (string ou Buffer) e os cabeçalhos da requisição
const chamada = wh.verify(corpoCru, cabecalhos); // lança erro se a assinatura não bate ou passou de 5 minutos

Troca do segredo: ao gerar um novo, o anterior continua valendo por 24 horas, e as chamadas vão com as duas assinaturas nesse período. Se o segredo vazou, marque invalidar o anterior agora.

Prazos, tamanho e repetição

• Consulta: 8 segundos. Executa: 20 segundos. Passou disso, a consulta conta como falha e a executa fica incerta (veja o Confirmar).
• Resposta de até 32 KB. Acima de 8 KB no data, o painel avisa: tudo isso vai para a IA em cada resposta.
• Redirecionamento (3xx) não é seguido: dá erro com o endereço para você cadastrar.
• Repetição: numa consulta, o call_id sai da mensagem do contato, da ação e dos parâmetros; se o BoaVoz processar a mesma mensagem de novo, a chamada vai com o mesmo id e, se a anterior deu certo, a resposta gravada é reaproveitada sem chamar você. Numa executa, o call_id é o do Confirmar e se repete em todo “Tentar de novo”. O BoaVoz nunca refaz uma executa sozinho.

A resposta

{
  "data": { "pedido": "1234", "status": "saiu para entrega", "previsao": "20h" },
  "internal": { "cliente_inadimplente": false },
  "components": {
    "type": "buttons",
    "buttons": [{ "title": "Falar com a loja", "id": "falar_loja" }]
  },
  "attachments": [{ "url": "https://seu-sistema.com/notas/1234.pdf", "filename": "nota-1234.pdf" }]
}

Arquivos

O BoaVoz baixa cada arquivo (até 25 MB), confere o tipo pelo conteúdo e recusa executável, HTML e SVG. Imagem que o canal aceita vai como imagem; PDF e os documentos aceitos pelo canal vão como documento; o resto vai como link que vale 7 dias. Os arquivos saem logo depois do texto. Se um falhar, o contato recebe “Não consegui anexar o arquivo agora.”.

Ações que criam ou alteram: o Confirmar

1. A IA chama a ação com todos os parâmetros obrigatórios. O seu endpoint ainda não é chamado.
2. O BoaVoz manda ao contato um resumo fixo, sem texto da IA: “Confere antes de eu concluir:”, as linhas do pedido e “Nada é feito antes do Confirmar.”, com os botões Confirmar e Cancelar.
3. No Confirmar, o BoaVoz chama o seu endpoint com "confirmed": true. A IA conta o resultado a partir do data (citando o número do pedido ou o protocolo que você devolver), ou vai o seu reply.

O resumo e a prévia

Sem prévia, o resumo lista os parâmetros (com os nomes dos itens que uma consulta anterior trouxe, em vez dos ids). Com aceita prévia, antes do resumo o BoaVoz chama o seu endpoint com "mode": "preview": não crie nada e devolva o resumo calculado pelo seu sistema (preço atual, taxa, total).

{
  "confirmation": {
    "summary": "Pedido para entrega na Rua das Flores, 10",
    "items": [{ "name": "Pizza Calabresa", "quantity": 2 }, "Coca-Cola 2L"],
    "total_cents": 11180
  }
}

Regras

• Os botões valem por 24 horas e uma vez só. Tocar de novo responde “Esse pedido já foi confirmado.”.
• Um resumo novo da mesma ação na mesma conversa substitui o anterior.
• “sim”, “confirmo” ou “1”, escritos sozinhos logo depois do resumo, valem como Confirmar; “não”, “cancelar” ou “2”, como Cancelar.
• Incerta (passou de 20 s ou 409): o contato recebe “Não consegui confirmar se deu certo” com Tentar de novo (mesmo call_id, sem duplicar) e Falar com alguém.
• Um botão com ação (em Mensagens ricas) também vale como confirmação: o toque chama a ação direto, com os parâmetros guardados no BoaVoz.

Nível do contato

A ação só aparece para a IA quando o contato alcança o nível mínimo dela.

age_confirmed diz se a pessoa confirmou ter 18 anos (age_confirmed_source: chat ou company). Para dados pessoais, autorize sempre pelo contato verificado, nunca só pelo que a pessoa digitou: pedido de outra pessoa responde 404, como se não existisse.

WhatsApp e Instagram: o portão

Nesses canais, o BoaVoz confere o que a ação devolve pelas regras da Meta antes de qualquer coisa chegar ao contato:

• No data, itens proibidos saem, e bebida alcoólica e remédio ficam de fora até a pessoa confirmar 18 anos. Depois do “Sim”, a mesma consulta é chamada de novo.
• O reply nunca é editado: com item 18+ sem confirmação, ele espera o “Sim”; com item proibido, é descartado e a IA responde com o data já filtrado.
• Botões, cards e arquivos são conferidos um a um.
• A venda de bebida alcoólica e de remédio nunca fecha no chat: o pedido desses itens vai para o site, o app ou o telefone que o chatbot tiver.

Limites

• 15 chamadas de ação por minuto em cada conversa e 600 por minuto em cada chatbot.
• No mês, até 10 vezes a cota do chatbot (no mínimo 1.000 chamadas). Passou disso, a IA oferece a equipe até o dia 1º. No teto por minuto ou no do mês, o dono recebe e-mail e o aviso aparece na aba Ações do chatbot.
• 5 respostas “não encontrado” da mesma ação na mesma conversa em 1 hora: a ação fica indisponível nessa conversa por um tempo (ninguém varre números de pedido).