> ## 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.

# Contatos

> Gerencie sua base de contatos: importação, exportação, tags, filtros e histórico de interações.

# Contatos

A seção **Contatos** exibe todos os números que já interagiram com sua instância WhatsApp. É possível buscar, filtrar, organizar com tags, importar e exportar a base.

***

## Informações por Contato

| Campo                | Descrição                                                                    |
| -------------------- | ---------------------------------------------------------------------------- |
| **Nome**             | Nome do contato (salvo no WhatsApp ou editado manualmente)                   |
| **Telefone**         | Número com código de país                                                    |
| **E-mail**           | E-mail coletado via formulário, Agente de IA ou editado manualmente          |
| **Tags**             | Etiquetas aplicadas ao contato para segmentação                              |
| **Origem**           | Como o contato chegou: formulário, sincronização, agendamento, manual ou UTM |
| **Última interação** | Data e hora da última mensagem                                               |
| **Status**           | Ativo, Bloqueado, Arquivado ou Grupo                                         |
| **Favorito**         | Marcado para acesso rápido nas conversas                                     |

***

## Busca e Filtros

| Recurso       | Descrição                                      |
| ------------- | ---------------------------------------------- |
| **Busca**     | Pesquise por nome, telefone ou e-mail          |
| **Status**    | Filtre por: Ativo, Bloqueado, Arquivado, Grupo |
| **Tags**      | Filtre por uma ou mais etiquetas               |
| **Ordenação** | Ordene por nome, telefone ou última interação  |

***

## Ações por Contato

| Ação               | Descrição                                                        |
| ------------------ | ---------------------------------------------------------------- |
| **Abrir conversa** | Abre o histórico de mensagens na aba Conversas                   |
| **Editar**         | Altere nome, e-mail e outras informações do contato              |
| **Gerenciar tags** | Adicione ou remova tags                                          |
| **Favoritar**      | Marca ou remove dos favoritos                                    |
| **Arquivar**       | Move para contatos arquivados (não aparece nas conversas ativas) |
| **Bloquear**       | Bloqueia o contato — Agente de IA para de responder              |
| **Excluir**        | Remove permanentemente o contato e todo o histórico              |

***

## Ações em Massa

Selecione múltiplos contatos usando as checkboxes para:

* **Aplicar tag** em todos os selecionados
* **Remover tag** de todos os selecionados
* **Exportar** os contatos selecionados (CSV)
* **Excluir** todos os selecionados

***

## Importar Contatos

<Steps>
  <Step title="Preparar o arquivo CSV ou XLSX">
    Colunas recomendadas: `telefone` (obrigatório), `nome`, `email`, `empresa`, `cargo`, `observações`, `tags`, `metadados`.

    O telefone deve estar em formato internacional: `5511999999999`.
  </Step>

  <Step title="Acessar importação">
    Em **/u/chat/contacts**, clique em **Importar**. Faça upload do arquivo.
  </Step>

  <Step title="Mapear colunas">
    O sistema detecta as colunas automaticamente. Confirme ou ajuste o mapeamento — inclusive as duas colunas opcionais:

    * **Etiquetas (tags)**: nomes separados por vírgula. Cria tags coloridas e vincula ao contato. Ex.: `vip, lead-quente`.
    * **Metadados (customLabels)**: pares `chave=valor` separados por `;`. Gravados em `contacts.custom_labels` (mesmo campo aceito na [API pública](/api/contatos)).

    Exemplo de conteúdo da coluna de metadados:

    ```
    contratante=1346452978;vincular_vaga=1409608130;segmento=premium
    ```

    Vira o objeto:

    ```json theme={null}
    { "contratante": "1346452978", "vincular_vaga": "1409608130", "segmento": "premium" }
    ```
  </Step>

  <Step title="Revisar e confirmar">
    Veja um preview dos dados antes de confirmar. Limite de 1000 contatos por importação.
  </Step>
</Steps>

<Warning>
  Telefones já existentes na base são **atualizados** — não duplicados. Metadados são **mesclados** com os já existentes (chaves não enviadas são preservadas).
</Warning>

***

## Criar / editar contato manualmente

Ao criar ou editar um contato em **/u/chat/contacts**, o campo **Metadados (customLabels)** permite adicionar pares `chave` + `valor` livres:

<Steps>
  <Step title="Abrir a modal">
    Clique em **Novo contato** (ou no ícone de editar sobre um contato existente).
  </Step>

  <Step title="Adicionar pares">
    Na seção **Metadados (customLabels)**, clique em **+ Adicionar par** e informe uma chave e um valor por linha. Ex.: `contratante` = `1346452978`.
  </Step>

  <Step title="Salvar">
    Os pares são gravados em `contacts.custom_labels` (JSONB) — a mesma estrutura usada na [API pública](/api/contatos) e no [payload do webhook](/api/webhook) `contact_created` / `contact_updated`.
  </Step>
</Steps>

<Tip>
  Contatos antigos que ainda usam o formato de lista aparecem com um aviso "Formato antigo detectado" — basta preencher os valores e salvar para migrar automaticamente.
</Tip>

***

## Exportar Contatos

Clique em **Exportar** para baixar a lista de contatos em formato CSV. O arquivo inclui nome, telefone, e-mail, tags, data da última interação, status e origem.

Para exportar um subconjunto, aplique os filtros desejados antes de exportar.

***

## Tags (Etiquetas)

Tags são rótulos coloridos para organizar e segmentar contatos. Casos de uso comuns:

* `lead-quente` — prospects com alta probabilidade de conversão
* `cliente` — clientes ativos
* `vip` — atendimento humano exclusivo
* `pagamento-pendente` — fatura em atraso

Tags podem ser aplicadas manualmente ou automaticamente via **Ações do Agente de IA**.

<Tip>
  Use tags para filtrar conversas no painel de atendimento. O filtro por etiqueta é combinável com filtros de status.
</Tip>

***

## Origem dos Contatos

| Origem         | Descrição                                  |
| -------------- | ------------------------------------------ |
| **WhatsApp**   | Contato enviou mensagem para a instância   |
| **Formulário** | Lead capturado via formulário do Brainchat |
| **Importação** | Adicionado via CSV                         |
| **Manual**     | Criado manualmente pelo operador           |
| **API**        | Criado via API externa                     |
| **UTM**        | Origem rastreada via parâmetros UTM        |