Campanhas no painel — como funcionam e como usar | Documentações

O que são campanhas

As campanhas permitem enviar a mesma mensagem (ou template aprovado no WhatsApp Business, quando aplicável) para vários destinatários de uma vez, pela integração que escolher (ex.: WhatsApp oficial, WhatsApp no número, Telegram).

O envio é processado por um worker em background: depois de criar a campanha e confirmar o disparo (ou na hora agendada), o sistema coloca trabalhos numa fila e o envio real faz-se fora do browser — não é preciso manter a página aberta.

Antes de começar

Integração ativa (ex.: WhatsApp já conectado ou oficial configurado).
Template de campanha (menu Campanhas → Templates): texto e variáveis (ex.: nome, telefone) ou, para WhatsApp oficial, configuração alinhada ao template aprovado na Meta.
Para WhatsApp oficial, o custo por conversa/template é faturado pela Meta; o painel pode mostrar uma estimativa informativa no passo final.

Criar uma campanha (passo a passo)

Abra Campanhas → Nova campanha (ou equivalente no menu).
No assistente, à esquerda vê os passos; à direita preenche cada etapa:
- Canal: escolha a integração e, se quiser, o nome da campanha.
- Template: escolha o template guardado.
- Público: contactos da base ou ficheiro CSV (indique as colunas de telefone e, se quiser, nome).
- Quando enviar: Agora ou Agendar data/hora.
- Revisão: confira o resumo; para WhatsApp oficial pode indicar a categoria do template (utilidade, marketing, autenticação) para a estimativa de custo.
Clique em Criar campanha.

Se escolheu agora, o sistema tenta iniciar o processamento em seguida (depende do worker de campanha e da fila estarem ativos no ambiente).
Se agendou, o processamento típico ocorre quando o cron (ou operação manual) chama o endpoint interno de processamento de agendadas — o administrador da infraestrutura deve garantir esse agendamento.

Onde ver o resultado

Campanhas: lista e detalhe com estado (rascunho, agendada, a enviar, concluída, cancelada) e contadores de enviados/falhados.
Conversas: cada envio bem-sucedido gera (ou reutiliza) a conversa com o contacto e uma mensagem enviada com indicação de que veio de campanha — o cliente vê no mesmo histórico que o bot.

Cancelar

Pode cancelar uma campanha quando ainda fizer sentido para o negócio: envios ainda não tratados deixam de ser feitos; o detalhe da campanha deve refletir o estado cancelado. Destinatários que ainda estavam pendentes podem aparecer como falha com motivo de cancelamento (comportamento técnico para fechar o ciclo).

Automação externa (n8n, CRM)

Para criar campanhas, adicionar destinatários e disparar via API (sem usar o assistente do painel), é necessário:

plano Professional;
chave de API da organização em Configurações da organização → Chaves de API;
seguir a documentação API pública — organização e campanhas (/api/v1/campaigns/...).

Listas, consentimento e regras legais de contacto continuam sua responsabilidade no CRM ou na automação; o OSBChat fornece o canal técnico de envio.

Resolução de problemas (resumo)

Situação	O que verificar
Campanha criada mas ninguém recebe	Worker de campanha a correr; base de dados com fila atualizada; integração e template válidos para o canal.
Agendada não dispara	Job de cron ou chamada a `process-scheduled` no ambiente.
API devolve 401	Chave revogada/expirada ou plano inferior a Professional.

Para detalhes técnicos (tabelas, workers, deploy), a equipa interna pode usar docs/campaign/ no repositório.