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

# Importar contatos

> Adicione contatos em massa usando um arquivo CSV.

## O que são contatos?

Contatos são as pessoas que já conversaram com você na plataforma e também as que você adiciona manualmente.

## Quando usar a importação

Use a importação quando você precisa colocar muitos contatos de uma só vez, por exemplo para organizar uma base existente ou preparar uma campanha.

## Antes de começar

* Tenha o arquivo em **CSV** com os contatos que deseja importar.
* Apenas **administradores** podem importar contatos.
* Garanta que esses contatos tenham consentimento para receber mensagens (LGPD). Veja mais em [LGPD e privacidade](/administradores/lgpd-privacidade).

## Formato do CSV

Use a primeira linha com os nomes das colunas. O sistema reconhece as colunas abaixo e tudo o que for extra vira **atributo personalizado** do contato.

**Colunas reconhecidas pelo sistema**

| Coluna         | Obrigatória | Observação                                      |
| -------------- | ----------- | ----------------------------------------------- |
| `name`         | Recomendada | Nome do contato                                 |
| `email`        | Sim\*       | E-mail do contato                               |
| `phone_number` | Sim\*       | Com DDI, ex: `+5511999999999`                   |
| `identifier`   | Não         | Identificador único externo                     |
| `company`      | Não         | Nome da empresa                                 |
| `city`         | Não         | Cidade do contato                               |
| `labels`       | Não         | Etiquetas separadas por pipe (ver seção abaixo) |

\*Ao menos **email** ou **phone\_number** deve estar preenchido para o contato ser localizável.

<Tip>
  O campo <strong>identifier</strong> é opcional e não é gerado automaticamente. Se ele vier vazio, o contato continua válido desde que tenha <strong>email</strong> ou <strong>telefone</strong>.
</Tip>

<Warning>
  Evite importar contatos sem <strong>identifier</strong>, <strong>email</strong> e <strong>telefone</strong> ao mesmo tempo. Esses contatos ficam fora da lista padrão e podem ser difíceis de localizar.
</Warning>

**Modelo de exemplo da plataforma**

Ao clicar em **Importar**, você pode baixar um modelo CSV de exemplo. O modelo vem com estas colunas:

* `name`
* `email`
* `identifier`
* `phone_number`
* `labels`
* `atributo_exemplo_1`
* `atributo_exemplo_2`

As duas últimas colunas são exemplos de **atributos personalizados**. Substitua pelo nome do atributo que você criou na plataforma. Veja [como criar atributos personalizados](/administradores/importar-contatos) para mais detalhes.

<Warning>
  Qualquer coluna que <strong>não</strong> seja uma das reconhecidas (<code>name</code>, <code>email</code>, <code>phone\_number</code>, <code>identifier</code>, <code>company</code>, <code>city</code>, <code>labels</code>) será salva automaticamente como <strong>atributo personalizado</strong> do contato. Escolha nomes de coluna que façam sentido para sua operação.
</Warning>

## Como importar contatos

<Steps>
  <Step title="Abra a área de Contatos">
    No menu lateral, clique em <strong>Contatos</strong>.
  </Step>

  <Step title="Clique em Importar">
    Clique no menu de ações (<strong>⋮</strong>) e selecione <strong>Importar contatos</strong>.

    <Frame caption="Menu com a opção Importar contatos">
      <img src="https://mintcdn.com/maketalk-7da59a87/49FRsX9ofeZH9mLK/images/administradores/importar-contatos/botao_importar_contatos.png?fit=max&auto=format&n=49FRsX9ofeZH9mLK&q=85&s=29db93cdccdd9dfbda68e06b786f1a78" alt="Menu com opção Importar contatos" width="1334" height="794" data-path="images/administradores/importar-contatos/botao_importar_contatos.png" />
    </Frame>
  </Step>

  <Step title="Selecione o CSV">
    Escolha o arquivo CSV do seu computador e envie para a plataforma. Você pode baixar o modelo de exemplo clicando no link disponível na janela de importação.
  </Step>

  <Step title="Aguarde o e-mail de conclusão">
    A importação roda em segundo plano. Ao finalizar, você recebe um e-mail com o resumo: quantos contatos foram importados e quantos falharam.

    <Frame caption="E-mail de conclusão da importação">
      <img src="https://mintcdn.com/maketalk-7da59a87/49FRsX9ofeZH9mLK/images/administradores/importar-contatos/email_conclusao_importacao.png?fit=max&auto=format&n=49FRsX9ofeZH9mLK&q=85&s=c3643436318835334252e6a16928a30a" alt="E-mail de conclusão da importação" width="1364" height="718" data-path="images/administradores/importar-contatos/email_conclusao_importacao.png" />
    </Frame>
  </Step>

  <Step title="Confira a lista">
    Após a importação, os contatos aparecem na lista de contatos.
  </Step>
</Steps>

## Dúvidas rápidas

**Posso adicionar só um contato?**\
Sim. Na área de Contatos existe o botão **Novo contato** para cadastrar um contato individualmente.

**Contatos também aparecem automaticamente?**\
Sim. Quando alguém conversa com você, essa pessoa passa a fazer parte da sua lista de contatos.

## Importar contatos com etiquetas

Você pode atribuir etiquetas aos contatos diretamente no CSV, sem precisar aplicá-las manualmente depois.

**Como funciona:**

* Adicione a coluna `labels` ao seu CSV
* Separe múltiplas etiquetas com pipe (`|`), por exemplo: `vip|lead|hotel`
* As etiquetas são convertidas para **minúsculo** automaticamente
* Não use espaços dentro do nome da etiqueta
* Se a etiqueta não existir na conta, ela é criada automaticamente durante a importação

**Exemplo de CSV com etiquetas:**

```csv theme={null}
name,email,phone_number,labels
João Silva,joao@email.com,+5511999999999,vip|lead
Maria Santos,maria@email.com,+5521888888888,suporte
```

<Tip>
  As etiquetas importadas ficam visíveis imediatamente no perfil do contato e podem ser usadas como audiência de <strong>campanhas</strong>.
</Tip>

## Exportar contatos com etiquetas

A exportação de contatos inclui automaticamente a coluna `labels`. As etiquetas de cada contato aparecem separadas por pipe (`|`), no mesmo formato aceito pela importação. Isso facilita exportar, editar no Excel e reimportar.

## Regras de duplicidade

* Se o sistema encontrar um contato existente pelo **identifier**, **email** ou **telefone**, ele **atualiza** esse contato em vez de criar um novo.
* Repetições de **email** ou **identifier** no mesmo CSV tendem a ser ignoradas na importação.
* Repetições de **telefone** dentro do mesmo CSV podem gerar contatos duplicados. Se possível, dedupe o arquivo antes de importar.
* Contatos ignorados por duplicidade aparecem no **CSV de falhas** enviado por e-mail, com o motivo específico da rejeição.

## Aplicar etiquetas em massa após a importação

Depois de importar, você pode filtrar os contatos pelo atributo personalizado da importação e aplicar etiquetas em massa. Isso é útil para segmentar campanhas ou organizar a base por origem.

<Steps>
  <Step title="Abra os filtros">
    Em <strong>Contatos</strong>, clique no ícone de filtro e selecione o atributo personalizado que você usou na importação. Defina a condição (ex: <strong>Igual a</strong>) e o valor.

    <Frame caption="Filtro por atributo personalizado da importação">
      <img src="https://mintcdn.com/maketalk-7da59a87/49FRsX9ofeZH9mLK/images/administradores/importar-contatos/aplicar_filtro_atributo.png?fit=max&auto=format&n=49FRsX9ofeZH9mLK&q=85&s=5ef2c189ae6dd29e50c1c50f568f592f" alt="Filtro por atributo personalizado" width="1778" height="616" data-path="images/administradores/importar-contatos/aplicar_filtro_atributo.png" />
    </Frame>
  </Step>

  <Step title="Verifique os resultados">
    Após aplicar o filtro, apenas os contatos da importação aparecem na lista.

    <Frame caption="Contatos filtrados pelo atributo da importação">
      <img src="https://mintcdn.com/maketalk-7da59a87/49FRsX9ofeZH9mLK/images/administradores/importar-contatos/filtrar_contatos_atributo.png?fit=max&auto=format&n=49FRsX9ofeZH9mLK&q=85&s=684737fcf5f100e11c978e4cc73f8056" alt="Lista de contatos filtrados" width="2120" height="1186" data-path="images/administradores/importar-contatos/filtrar_contatos_atributo.png" />
    </Frame>
  </Step>

  <Step title="Selecione e aplique a etiqueta">
    Marque <strong>Selecionar todos</strong>, clique em <strong>Atribuir rótulo</strong> e escolha a etiqueta desejada. Clique em <strong>Atribuir etiquetas selecionadas</strong> para aplicar.

    <Frame caption="Seleção em massa e aplicação de etiqueta">
      <img src="https://mintcdn.com/maketalk-7da59a87/49FRsX9ofeZH9mLK/images/administradores/importar-contatos/selecionar_contatos_aplicar_rotulo.png?fit=max&auto=format&n=49FRsX9ofeZH9mLK&q=85&s=cd183c58ed7c5cf2d921780b31b8f982" alt="Selecionar contatos e aplicar etiqueta em massa" width="2006" height="1228" data-path="images/administradores/importar-contatos/selecionar_contatos_aplicar_rotulo.png" />
    </Frame>
  </Step>
</Steps>

<Tip>
  Você também pode salvar o filtro como um <strong>segmento</strong> para reutilizar depois sem precisar refazer a configuração.
</Tip>

## Limites e processamento

* A importação roda em segundo plano e processa os contatos em lotes de **1.000**.
* Não há um limite fixo de linhas no código da aplicação. Em arquivos muito grandes, a importação pode demorar e depender dos limites do servidor/armazenamento. Se necessário, divida o CSV em partes.
* Ao terminar, um e-mail é enviado para o administrador com o resumo da importação, indicando quantos contatos foram **efetivamente importados** e quantos foram **ignorados** (por duplicidade ou erro). Se houver falhas, o e-mail inclui um CSV com as linhas rejeitadas e o motivo de cada uma.

## Próximo passo

<Card title="Etiquetas e organização" icon="arrow-right" href="/operacao/etiquetas">
  Organize seus contatos com etiquetas para facilitar buscas e campanhas.
</Card>