> For the complete documentation index, see [llms.txt](https://ajuda.digitalsac.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ajuda.digitalsac.io/digicrm/operacao-uso-do-sistema/campanhas-externas/campanhas-externas-e-captura-de-leads-no-chatbot.md).

# Campanhas Externas e captura de Leads no Chatbot

> **Público:** administradores e gestores de marketing/atendimento\
> **Módulo:** Campanhas Externas + Flow Builder (modo Lead)\
> **Versão da doc:** jun/2026

***

### Visão geral

O módulo **Campanhas Externas** permite que sua empresa **cadastre campanhas de mídia paga** (Facebook, Google Ads, Instagram, site, etc.) e **vincule automaticamente cada lead** que entra pelo chatbot à campanha correta.

Com isso você consegue:

* Saber **de qual campanha/anúncio** veio cada atendimento
* Ver a origem no **card do ticket** (ícone da plataforma)
* Abrir os **detalhes completos da campanha** com um clique
* Medir resultados no relatório **Leads por Origem**, com filtro e ranking por campanha

#### Como funciona em resumo

```mermaid
flowchart LR
  A[Lead clica no anúncio] --> B[Abre WhatsApp / canal]
  B --> C[Chatbot: Boas-Vindas modo Lead]
  C --> D{Condições batem?}
  D -->|Sim| E[Próxima etapa do fluxo]
  E --> F[Interação Campanha Externa]
  F --> G[Ticket vinculado à campanha]
  G --> H[Badge no card + relatório]
```

**Importante:** a campanha **não** é escolhida na etapa Boas-Vindas. O fluxo é dividido em duas partes:

1. **Boas-Vindas (modo Lead)** — só roteia o lead com base na **primeira mensagem** (botão, texto, etc.)
2. **Etapa seguinte** — bloco **Campanha Externa** grava qual campanha gerou aquele lead

***

### Pré-requisitos

Antes de montar o fluxo, confira:

| Item                   | Onde configurar                                                     |
| ---------------------- | ------------------------------------------------------------------- |
| **Origens de lead**    | Configurações → Origens                                             |
| **Campanhas externas** | Menu lateral → **Comunicação e Marketing** → **Campanhas Externas** |
| **Fluxo de chatbot**   | Configurações → Chatbot → editar fluxo                              |
| **Permissão de admin** | Perfil com acesso a Configurações / Campanhas Externas              |

> As **Origens** são as plataformas (Facebook, Instagram, Google Ads…). Cada **Campanha Externa** aponta para uma origem e guarda os dados do anúncio (nome, UTMs, ID Meta/Google, etc.).

***

### Passo 1 — Cadastrar origens (se ainda não existirem)

1. Acesse **Configurações** → **Origens**
2. Crie ou revise as origens que você usa (Facebook, Google Ads, Instagram, Site…)
3. Para cada origem, defina **nome**, **ícone/cor** (ou logo) — isso aparece no card do ticket

As origens padrão já vêm pré-cadastradas na maioria dos tenants.

***

### Passo 2 — Cadastrar campanhas externas

1. Acesse **Comunicação e Marketing** → **Campanhas Externas**\
   \&#xNAN;*(também disponível em Configurações → grid de opções)*
2. Clique em **Adicionar**
3. Preencha os campos:

| Campo                              | Descrição                                               | Exemplo                          |
| ---------------------------------- | ------------------------------------------------------- | -------------------------------- |
| **Nome da campanha**               | Nome interno para identificar no fluxo e relatórios     | `Facebook Izing Pro`             |
| **Origem**                         | Plataforma da campanha                                  | Facebook                         |
| **Textos esperados do lead**       | Mensagens típicas que o lead envia (referência interna) | `Olá! Tenho interesse...`        |
| **ID externo**                     | ID do anúncio na Meta/Google                            | `120214567890123`                |
| **UTM Source / Medium / Campaign** | Parâmetros UTM da URL (opcional)                        | `facebook`, `cpc`, `promo-junho` |
| **URL da campanha**                | Link do anúncio ou landing page                         | `https://...`                    |
| **Período**                        | Data início e fim (opcional)                            | 01/06 – 30/06                    |
| **Observações**                    | Notas internas                                          | Budget, público, etc.            |
| **Ativa**                          | Só campanhas ativas aparecem no flow builder            | ✓                                |

4. Salve a campanha

> Você pode ter **várias campanhas** com a mesma origem (ex.: três campanhas Facebook diferentes). Cada uma é vinculada em uma etapa do fluxo.

***

### Passo 3 — Configurar o chatbot (captura do lead)

#### 3.1 Abrir o Flow Builder

1. **Configurações** → **Chatbot** → selecione o fluxo vinculado ao canal
2. Abra o editor de fluxo

#### 3.2 Etapa **Boas-Vindas** — modo Lead

1. Clique duas vezes na etapa **Boas vindas!**
2. Em **Tipo da etapa**, selecione **Lead** (em vez de *Fluxo normal*)

Ao ativar o modo Lead:

* A aba **Interações** fica oculta (não é necessário enviar mensagens aqui)
* Só a aba **Condições** é usada
* Aparece o aviso: *configure as condições com a resposta que vem do lead*

3. Na aba **Condições**, crie regras para identificar **como o lead entrou**:

| Tipo                 | Uso típico                                        |
| -------------------- | ------------------------------------------------- |
| **Resposta igual a** | Texto exato do botão do anúncio Click-to-WhatsApp |
| **Resposta contém**  | Parte da mensagem padrão do Meta/Google           |
| **Outros tipos**     | Conforme necessidade do canal                     |

4. Em **Rotear para**, aponte para a **próxima etapa** onde você vai vincular a campanha (ex.: `Nova etapa`)
5. **Salve** o fluxo

> **Dica:** anúncios Click-to-WhatsApp costumam enviar uma mensagem pré-preenchida. Copie esse texto exato e use na condição *Igual a*.

#### 3.3 Etapa seguinte — vincular a **Campanha Externa**

> O ícone **Campanha Externa** (`mdi-comment-eye-outline`) **só aparece** nas etapas quando a **Boas-Vindas está em modo Lead**.

1. Crie ou edite a etapa para onde o lead foi roteado (ex.: `Nova etapa`)
2. Aba **Interações** → clique no ícone **Campanha Externa**
3. No bloco **Campanha Externa**, selecione a campanha cadastrada (ex.: `Facebook Izing Pro`)
4. Continue o fluxo normalmente (mensagens, fila, encerramento, etc.)
5. **Salve** o fluxo

No canvas do fluxo, a etapa exibe o **nome da campanha** no rodapé do card (quando só há campanha externa) ou junto com a contagem de outras interações.

**Exemplo de fluxo mínimo**

```
Início → Boas-Vindas (Lead)
           └─ Condição: resposta = "Olá! Quero saber mais"
              └─ Nova etapa
                   └─ Campanha Externa: Facebook Izing Pro
                   └─ (demais interações do atendimento)
```

**Vários anúncios / campanhas**

Crie **uma ramificação por campanha**:

```
Boas-Vindas (Lead)
  ├─ Condição A → Etapa A → Campanha Externa: Facebook Promo Junho
  ├─ Condição B → Etapa B → Campanha Externa: Google Search Brand
  └─ Condição C → Etapa C → Campanha Externa: Instagram Stories
```

Cada condição usa o texto/botão específico daquele anúncio.

***

### Passo 4 — O que acontece quando o lead entra

Quando o contato passa pela etapa com **Campanha Externa**, o sistema automaticamente:

1. **Grava no ticket**
   * `leadCampaignId` → campanha selecionada
   * `leadSourceId` → origem vinculada à campanha (ex.: Facebook)
2. **Atualiza o contato**
   * Campo `source` com o nome da origem
3. **Registra histórico**
   * Entrada em **Leads por Origem** com contexto `external_lead_campaign`
   * Inclui nome da campanha e da origem
4. **Atualiza a tela em tempo real** (socket) para quem está na fila de atendimento

> A vinculação ocorre **no momento em que o fluxo executa** o bloco Campanha Externa — não na Boas-Vindas.

***

### Passo 5 — Visualização no atendimento

#### Card do ticket (lista de conversas)

Quando o ticket tem campanha vinculada:

* Aparece o **ícone/logo da origem** (Facebook, Instagram, etc.) ao lado da prévia da mensagem
* **Sem texto** no card — visual limpo, igual ao badge antigo de origem
* **Tooltip** ao passar o mouse: `Campanha: [nome]`
* **Clique no ícone** → abre modal com todos os detalhes:
  * Nome da campanha
  * Origem
  * ID externo (Meta/Google)
  * Período, URL, textos esperados, observações

#### O operador não precisa fazer nada

A captura é **100% automática** pelo chatbot. O atendente só vê a informação e pode consultar a campanha se quiser contexto.

***

### Passo 6 — Relatórios

#### Leads por Origem

**Menu:** Relatórios → **Leads por Origem**

Funcionalidades relacionadas a campanhas:

| Recurso                     | Descrição                                      |
| --------------------------- | ---------------------------------------------- |
| **Filtro por campanha**     | Isola uma campanha externa específica          |
| **KPI Leads de campanhas**  | Total de leads capturados via campanha externa |
| **Ranking por campanha**    | Quais campanhas geraram mais leads             |
| **Coluna Campanha externa** | Nome da campanha em cada registro              |
| **Exportação Excel**        | Inclui dados de campanha                       |

Use o **período** para comparar campanhas sazonais (Black Friday, lançamento, etc.).

***

### Boas práticas

#### Nomenclatura de campanhas

Use nomes que a equipe reconheça rapidamente:

* ✅ `Facebook - Promo Junho 2026 - Público Frio`
* ✅ `Google Ads - Marca - SP`
* ❌ `Campanha 1`

#### Condições na Boas-Vindas

* Teste com um celular real clicando no anúncio
* Copie a **mensagem exata** que o WhatsApp recebe
* Prefira *Igual a* quando a mensagem é fixa; *Contém* quando varia um pouco

#### Uma campanha por etapa

Mantenha **um bloco Campanha Externa por ramo** do fluxo. Facilita manutenção e relatório.

#### Campanhas inativas

Campanhas marcadas como **inativas** não aparecem no seletor do flow builder. Fluxos antigos continuam funcionando se a campanha ainda existir no banco.

#### Canais suportados

O módulo funciona em qualquer canal com **chatbot/flow builder** ativo (WhatsApp, WABA, etc.). A lógica é a mesma: condição na entrada + campanha na etapa seguinte.

***

### Perguntas frequentes

#### Preciso configurar origem na Boas-Vindas?

**Não.** No modo Lead atual, a Boas-Vindas só usa **condições**. A origem vem da **campanha externa** escolhida na etapa seguinte.

#### O ícone Campanha Externa não aparece no flow builder

Verifique se a etapa **Boas-Vindas** está em **modo Lead**. O ícone só é exibido nesse caso.

#### O lead entrou mas não apareceu campanha no ticket

Confira:

1. O fluxo **passou** pela etapa com Campanha Externa?
2. A campanha estava **selecionada** no bloco (não vazio)?
3. A campanha está **ativa**?
4. O fluxo foi **salvo** após as alterações?

#### Posso mudar a campanha de um ticket depois?

Hoje a vinculação é feita **automaticamente pelo fluxo** no momento da passagem. Alterações manuais não fazem parte do módulo padrão.

#### Qual a diferença entre Origem e Campanha Externa?

| Conceito             | O que é                                          | Exemplo                                   |
| -------------------- | ------------------------------------------------ | ----------------------------------------- |
| **Origem**           | Plataforma / canal de aquisição                  | Facebook, Google Ads                      |
| **Campanha Externa** | Anúncio/campanha específica dentro da plataforma | `Facebook Izing Pro`, UTMs, ID do anúncio |

#### Isso substitui campanhas de WhatsApp (disparo em massa)?

**Não.** Campanhas Externas são para **rastrear leads que chegam de anúncios externos**. As campanhas de WhatsApp/WABA/SMS do menu *Comunicação e Marketing* são módulos diferentes (disparo proativo).

***

### Referência técnica (implementação)

<details>

<summary>Para equipe técnica / suporte N2</summary>

#### Menu e rotas (frontend)

* Campanhas Externas: `/configuracoes/campanhas-externas` — menu **Comunicação e Marketing**
* Origens: `/configuracoes/origens`
* Relatório: `/relatorio-leads-origem`

#### API backend

* `GET/POST/PUT/DELETE /external-lead-campaigns`

#### Modelo de dados

* `ExternalLeadCampaigns` — cadastro de campanhas
* `Tickets.leadCampaignId` — FK campanha no ticket
* `Tickets.leadSourceId` — FK origem (derivada da campanha)
* `ContactSourceHistories` — histórico com `campaignId`, `campaignName`, context `external_lead_campaign`

#### Flow builder (JSON do nó)

* Boas-Vindas: `stepMode: "lead"` + `conditions[]`
* Interação: `type: "ExternalLeadCampaignField"`, `data.campaign` (ID), `data.campaignName` (cache visual no canvas)

#### Processamento no motor

* `BuildSendMessageService` — executa `ExternalLeadCampaignField`
* Grava ticket, contato, histórico e emite socket `ticket:update` / `contact:update`

</details>

***

### Checklist rápido para o cliente

* [ ] Origens cadastradas (Facebook, Google, etc.)
* [ ] Campanha externa criada com origem e dados do anúncio
* [ ] Boas-Vindas em **modo Lead** com condição na mensagem do lead
* [ ] Etapa seguinte com bloco **Campanha Externa** selecionado
* [ ] Fluxo salvo
* [ ] Teste real: clicar no anúncio → ver ícone no ticket → conferir relatório

***

*Documentação gerada com base no módulo Campanhas Externas (Digitalsac). Para dúvidas de implantação, consulte o suporte ou a equipe de DS.*