Documentação · Integrações
Campanhas e consentimento
Mensagens que o negócio manda primeiro, fora da conversa: novidades e promoções para quem aceitou, e lembretes (consulta, vencimento, entrega). No MVP, só pelo WhatsApp e só com modelo aprovado pela Meta.
Novidades e lembretes
| Tipo | Para quem | Modelo |
|---|---|---|
Novidades (marketing) | Só quem aceitou receber novidades. Com bebida alcoólica ou remédio, só quem também confirmou ter 18 anos. | Categoria marketing. |
Lembretes (utility_reminder) | Quem tem um compromisso com o negócio. Para quem nunca conversou com o chatbot, o cliente precisa ter feito a declaração de lembretes (uma vez, no painel). | Categoria utilidade. |
Pelo painel: aba Campanhas do cliente. Pela API: POST /v1/campaigns (veja a referência). Os dois usam o mesmo motor, que confere tudo de novo na hora de cada envio.
O aceite de novidades
Cada sim e cada não fica guardado com a prova: de onde veio, o texto que a pessoa viu e a data. O registro sobrevive à exclusão do contato.
| Origem | Como |
|---|---|
| Conversa | Com a opção ligada no chatbot, o assistente oferece novidades uma vez por contato, no fim natural da conversa, com os botões “Sim, quero” e “Não, obrigado”. A IA nunca dispara marketing: só faz a oferta. |
| Site | Quem deixa o WhatsApp no chat do site recebe a mesma oferta. |
| Painel | A agência registra o aceite coletado fora do chat, no contato ou ao importar uma planilha. |
| API | Seu sistema registra o aceite que coletou (cadastro, checkout), com a prova. |
http
POST /v1/contacts/phone:5511999990000/consent
{
"bot_id": "bot_…",
"channel": "whatsapp",
"granted": true,
"source": "cadastro no site, caixa marcada",
"text": "Quero receber novidades e promoções da Loja X pelo WhatsApp.",
"collected_at": "2026-10-10T14:22:00-03:00"
}
→ 201 { "consent_id": "…" }source (3 a 200 caracteres) diz onde a pessoa aceitou; text (10 a 1.000), o que ela aceitou. "granted": false retira o aceite. O sim pela API não tira ninguém do descadastro: só um novo sim da própria pessoa, no chat.
Descadastro
- A pessoa responde SAIR, PARAR ou STOP, toca em “Parar promoções” ou para o marketing pelo próprio WhatsApp. O BoaVoz confirma (“Feito, você não vai mais receber…”) e o atendimento continua normal.
- O alcance segue a categoria do último modelo que ela recebeu: um SAIR depois de uma promoção para as promoções; depois de um lembrete, os lembretes.
- Errou? “Foi engano” desfaz e grava um novo sim.
- Vale para todos os chatbots do mesmo número. O webhook
contact.opted_outavisa o seu sistema, e envio pela API para quem saiu volta 422contact_opted_out.
Lembretes pela API
http
POST /v1/campaigns
Idempotency-Key: 8a1b…
{
"bot_id": "bot_…",
"channel": "whatsapp",
"kind": "utility_reminder",
"template": { "name": "lembrete_consulta", "language": "pt_BR" },
"sends": [
{ "contact": "phone:5511999990000", "send_at": "2026-10-20T09:00:00-03:00", "variables": ["Ruan", "21/10 às 14h"] },
{ "contact": "ext:paciente_1182", "send_at": "2026-10-20T09:00:00-03:00", "variables": ["Bia", "21/10 às 16h"] }
]
}- Cada envio tem o seu contato, horário e variáveis (na ordem dos {{1}}, {{2}}… do modelo).
- A resposta traz a estimativa de contatos e de custo na Meta. A Idempotency-Key é obrigatória: repetir a chamada não duplica a campanha.
- Quem pediu para sair é pulado; o
campaign.finishedtraz os totais, com os pulados por motivo.
Regras da Meta que o BoaVoz cuida
- Limite de contatos únicos por 24 horas do número (o nível da conta na Meta), somando todas as campanhas e lembretes dos chatbots do mesmo número.
- A campanha pausa sozinha, e o dono é avisado, se a nota de qualidade do número cair ou se a Meta pausar ou reclassificar o modelo (lembrete cobrado como marketing).
- Envio sem resposta da Meta fica incerto e nunca é reenviado sozinho.
Custo
A Meta cobra cada mensagem de modelo, à parte da assinatura do BoaVoz, direto no cartão do negócio: no Brasil, cerca de R$ 0,32 a promoção (marketing) e R$ 0,035 o lembrete (utilidade), pela tabela da Meta de outubro de 2026. Desde 01/10/2026, o lembrete mandado com a conversa aberta (janela de 24 horas) também é cobrado. O painel e a API mostram a estimativa antes de agendar.