> ## Documentation Index
> Fetch the complete documentation index at: https://docs.brainchat.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Comportamento e Coleta

> Configure mensagem de boas-vindas, comportamento pós-coleta, coleta natural, confirmação de dados, recursos úteis e variáveis externas.

# Comportamento e Coleta

As configurações de comportamento controlam **como** o agente coleta dados, o que acontece após completar os objetivos, e como ele se apresenta ao iniciar a conversa.

***

## Mensagem de Boas-vindas

Defina uma **mensagem de abertura** enviada automaticamente quando o agente inicia uma conversa.

| Configuração                | Descrição                                                                |
| --------------------------- | ------------------------------------------------------------------------ |
| **Mensagem de boas-vindas** | Texto enviado na primeira interação                                      |
| **Variáveis**               | Use `{nome}` para personalizar com o nome do contato (quando disponível) |

Exemplo:

```
Olá! Sou a Ana, assistente virtual da {{empresa}}. 
Como posso ajudar você hoje? 😊
```

<Info>
  A mensagem de boas-vindas é enviada apenas quando o agente inicia a conversa — não quando o contato envia a primeira mensagem. Se o contato escrever primeiro, o agente responde normalmente sem enviar a boas-vindas.
</Info>

***

## Mensagem de Fallback

Mensagem enviada quando o agente encontra um **erro ao processar** a mensagem do contato (ex: falha na API do Gemini, timeout, resposta inválida).

Exemplo:

```
Desculpe, estou com uma instabilidade momentânea. 
Pode repetir sua mensagem em alguns segundos? 🙏
```

Se não configurada, o agente simplesmente não responde em caso de erro.

***

## Comportamento Pós-Coleta

Define o que o agente faz após completar todos os objetivos (goals):

| Opção                     | Descrição                                                            |
| ------------------------- | -------------------------------------------------------------------- |
| **Parar de responder**    | Agente para completamente após coletar todos os dados (padrão)       |
| **Continuar respondendo** | Agente continua a conversa normalmente mesmo após completar os goals |

<Tip>
  Use **Continuar respondendo** quando o agente tem objetivos de coleta mas também serve como assistente de FAQ. Assim, após coletar os dados, ele ainda pode responder dúvidas.
</Tip>

***

## Configurações de Coleta

### Coleta Natural

Quando ativada, o agente coleta os dados de forma **conversacional**, sem parecer um formulário. Em vez de perguntar "Por favor, informe seu e-mail:", o agente integra as perguntas naturalmente na conversa.

| Coleta Natural | Exemplo de pergunta                                          |
| -------------- | ------------------------------------------------------------ |
| **Desativada** | "Por favor, informe seu e-mail para continuarmos."           |
| **Ativada**    | "Posso te enviar mais detalhes! Qual é o seu melhor e-mail?" |

### Validar em Tempo Real

Quando ativada, o agente valida o formato dos dados no momento da coleta:

* E-mails são verificados quanto ao formato `@dominio.com`
* Telefones são validados quanto ao formato brasileiro

Se o dado for inválido, o agente solicita que o contato corrija antes de prosseguir.

### Confirmação ao Final

Quando ativada, o agente **resume os dados coletados** ao final e pede confirmação do contato antes de marcar os objetivos como completos.

Exemplo de resumo gerado:

```
Ótimo! Veja um resumo do que coletei:
• Nome: João Silva
• E-mail: joao@empresa.com
• Interesse: Plano Pro

Está correto?
```

Se o contato confirmar, os goals são marcados como completos e as ações são disparadas. Se solicitar correção, o agente ajusta o dado específico.

***

## Ignorar Grupos

Quando ativado (padrão: **sim**), o agente **não responde** em grupos do WhatsApp — apenas em conversas individuais.

Desative esta opção se quiser que o agente responda também em grupos (ex: grupo de suporte interno).

***

## Prioridade de Bloqueio

Quando um contato tem tanto uma **tag de ativação** (que ativa o agente) quanto uma **tag de bloqueio** (que bloqueia o agente), defina qual prevalece:

| Opção                  | Comportamento                                                                |
| ---------------------- | ---------------------------------------------------------------------------- |
| **Bloqueio prevalece** | A tag de bloqueio tem prioridade — agente não responde (padrão)              |
| **Ativação prevalece** | A tag de ativação tem prioridade — agente responde mesmo com tag de bloqueio |

Esta configuração evita conflitos quando um contato é marcado com ambos os tipos de tags simultaneamente.

***

## Filtro de Primeira Mensagem

Filtre a **primeira mensagem** recebida: o agente só inicia a conversa se a mensagem do contato contiver pelo menos uma das palavras-chave configuradas.

<Warning>
  O filtro de primeira mensagem é diferente do **Modo de Ativação**. O Modo de Ativação define **quais contatos** o agente responde. O filtro de primeira mensagem valida **o conteúdo da mensagem inicial** para decidir se a conversa deve ser iniciada.
</Warning>

Exemplo: se configurar as palavras `ajuda, suporte, problema`, o agente só inicia a conversa quando a primeira mensagem contiver uma dessas palavras — mensagens fora do contexto são ignoradas.

Após a conversa ser iniciada, o agente responde a todas as mensagens normalmente.

***

## Recursos Úteis

Configure **links e referências** que o agente pode citar nas respostas. Cada recurso tem:

| Campo         | Descrição                                |
| ------------- | ---------------------------------------- |
| **Título**    | Nome do recurso (ex: "Central de Ajuda") |
| **URL**       | Link do recurso                          |
| **Descrição** | Contexto sobre quando citar este recurso |

Os recursos são incluídos no prompt do agente, permitindo que ele referencie links relevantes durante a conversa.

Exemplo:

```json theme={null}
[
  {
    "title": "Central de Ajuda",
    "url": "https://docs.brainchat.app",
    "description": "Documentação completa do Brainchat"
  },
  {
    "title": "Política de Privacidade",
    "url": "https://brainchat.app/privacidade",
    "description": "Citar quando perguntarem sobre LGPD ou dados"
  }
]
```

***

## Variáveis Externas

Configure **variáveis que são injetadas no contexto** do agente via API. São úteis quando você envia dados externos (CRM, ERP) junto com a mensagem.

| Campo            | Descrição                                     |
| ---------------- | --------------------------------------------- |
| **Nome**         | Identificador da variável (ex: `plano_atual`) |
| **Descrição**    | O que a variável representa                   |
| **Fonte**        | De onde vem o dado (informativo)              |
| **Valor padrão** | Valor usado quando a variável não é enviada   |

As variáveis externas ficam disponíveis como `collected_data` quando enviadas via o endpoint [`process-ai-agent`](/api/enviar-mensagem#iniciar-conversa-com-agente-de-ia) no campo `externalContext`.

Exemplo:

```json theme={null}
[
  {
    "name": "plano_atual",
    "description": "Plano contratado pelo cliente",
    "source": "CRM",
    "default_value": "Não identificado"
  },
  {
    "name": "valor_divida",
    "description": "Valor em aberto do cliente",
    "source": "ERP"
  }
]
```

<Info>
  As variáveis externas permitem que o agente tenha contexto sobre o cliente **antes** de iniciar a conversa. Isso é especialmente útil para agentes de cobrança, suporte personalizado e vendas consultivas.
</Info>