Conceitos
Cinco ideias explicam as Integrações: quem é o contato, em que conta ele está, o que a IA pode fazer, o que o seu sistema fica sabendo e o que ele pode pedir.
Agência, cliente e chatbot
A agência atende vários clientes (os negócios). Cada cliente tem um ou mais chatbots, e cada chatbot responde em até três canais: o chat do site, o WhatsApp e o Instagram. Ações são cadastradas por chatbot; webhooks e chaves de API são da agência, com escopo (todos os chatbots, os de um cliente ou alguns).
Identidade: quem é o contato
| Nível | Como o BoaVoz sabe | Exemplo de uso |
|---|---|---|
| anônimo | Ninguém garante: o visitante do site. | Cardápio, horários, preços. |
| canal | A Meta garante o número no WhatsApp e a conta no Instagram. | Status do pedido do telefone que está falando. |
| usuário | A empresa identificou a pessoa: token assinado no site ou no app, ou pareamento no WhatsApp ou no Instagram. | Saldo, segunda via, dados da conta. |
Cada ação tem um nível mínimo: abaixo dele, a IA nem vê a ação. O que a pessoa digita (nome, CPF, número de pedido) nunca sobe o nível.
Contexto: em que conta ele está
Uma pessoa pode ter várias contas no seu sistema (duas lojas, um workspace da família e um da empresa). O contexto é a conta ativa da conversa, assinado pela empresa (no token ou no pareamento). Ele vai para as ações no campo context e nunca para a IA, que vê só o nome de exibição. Trocar de contexto abre um trecho novo da conversa: a IA só lê o que veio depois.
Ferramentas: o que a IA pode fazer
A IA de todo chatbot tem ferramentas próprias do BoaVoz:
- registrar o contato de quem quer comprar, agendar ou orçar (lead, um por contato);
- chamar alguém da equipe (com prioridade em risco à vida);
- registrar a pergunta que a base não respondeu, para a equipe completar;
- mostrar opções e botão de link;
- pedir a confirmação de 18 anos no WhatsApp e no Instagram.
As suas ações entram ao lado delas. Os nomes das ferramentas do BoaVoz e o prefixo boavoz_ são reservados, então uma ação nunca substitui o caminho para a equipe.
Eventos: o que o seu sistema fica sabendo
Os webhooks avisam na hora: mensagens, leads, pedidos de atendente, aceite de novidades, vínculos, canal, modelos, campanhas e conformidade.
API: o que o seu sistema pode pedir
A API envia mensagens e campanhas, lê conversas, contatos e leads, pausa a IA numa conversa para o seu sistema responder e liga contatos às contas do seu sistema.
A janela de 24 horas
No WhatsApp e no Instagram, mensagem livre (texto, botões, carrossel, arquivo) só sai até 24 horas depois da última mensagem do contato. Fora da janela:
- no WhatsApp, só modelo aprovado pela Meta (é o que as campanhas e os lembretes usam);
- no Instagram, a equipe ainda pode responder pelo painel por até 7 dias (tag de atendimento humano da Meta); a IA e a API não.
No WhatsApp, a resposta dentro da janela é uma mensagem de serviço: desde 01/10/2026, a Meta dá 1.000 por mês em cada número e cobra as seguintes (cerca de R$ 0,035 cada no Brasil), direto na conta do negócio. No Instagram, a Meta não cobra.
No chat do site, não há janela.
As regras da Meta
No WhatsApp e no Instagram, o BoaVoz confere tudo o que sai, venha da IA, das ações ou da API: produtos proibidos pela Meta não saem; bebida alcoólica e remédio só aparecem para quem confirmou ter 18 anos, e a venda deles nunca fecha no chat (vai para o site, o app ou o telefone do negócio). No site, essa trava não se aplica.