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

# Contatos

> Como os contatos entram na OctaSend, como duplicatas são evitadas e como criar, importar e manter a sua base

O **contato** é o cadastro de uma pessoa com quem a sua conta se comunica: nome, e-mail, telefone e os identificadores de cada canal. A base de contatos alimenta as listas das [campanhas](https://docs.octasend.com.br/plataforma/campanhas.md), os gatilhos por segmento e por data das [automações](https://docs.octasend.com.br/plataforma/automacoes.md) e o nome exibido nas conversas de WhatsApp.

A tela fica em **Comunicações → Contatos**. Todos os usuários da sua conta têm o mesmo acesso a ela: ver, criar, editar, importar, remover e restaurar.

## Como os contatos entram na base

Você não precisa cadastrar todo mundo à mão. A maior parte dos contatos é criada ou atualizada automaticamente, a partir do que já passa pela OctaSend:

| Origem | Quando o contato é criado ou atualizado | De onde vem o nome |
| - | - | - |
| Envio pela [API](https://docs.octasend.com.br/api-reference/enviar-mensagens.md) | A cada envio cujo destinatário tenha e-mail ou telefone | Variável `nome` (ou `name`) da chamada, aproveitada só quando a chamada traz `recipient.email` |
| [Automações](https://docs.octasend.com.br/plataforma/automacoes.md) | Quando uma automação começa para um destinatário com e-mail ou telefone | Variável `cliente_nome`, quando existir |
| Loja conectada (ex.: [Nuvem Shop](https://docs.octasend.com.br/integracoes/nuvemshop.md)) | Quando chega da loja um evento de pedido ou de cliente com e-mail ou telefone | Nome do cliente na loja |
| [Conversas de WhatsApp](https://docs.octasend.com.br/plataforma/whatsapp-conversas-e-grupos.md) | Quando alguém manda mensagem numa conversa individual para um número conectado, inclusive as atendidas pelo [chatbot](https://docs.octasend.com.br/plataforma/chatbot.md) e mesmo que a conta não tenha nenhum chatbot | Nome do perfil do WhatsApp, só enquanto o contato ainda não tem nome |
| [Grupos de WhatsApp](https://docs.octasend.com.br/plataforma/whatsapp-conversas-e-grupos.md) | Quando um participante escreve no grupo, ou quando você salva participantes na aba **Participantes** | Ao salvar pela aba **Participantes**: nome do perfil do WhatsApp, só enquanto o contato ainda não tem nome. Sem nome de perfil, o contato fica **Sem nome** |
| [Chatbot do site](https://docs.octasend.com.br/plataforma/chatbot-do-site.md) | Quando o visitante informa e-mail ou telefone na conversa, ou quando o seu site já identifica o visitante | Nome informado pelo visitante ou pelo site |
| [E-commerce](https://docs.octasend.com.br/plataforma/ecommerce.md) | Ao adicionar um cliente, importar clientes por planilha ou importar pedidos | Nome do cliente no cadastro ou na planilha |
| Painel | Em **Novo Contato** ou **Importar CSV**, nesta tela | O que você digitar |

Contatos criados sem um nome conhecido aparecem como **Sem nome** na lista até que alguma origem traga o nome. No detalhe, o título mostra o e-mail ou o telefone do contato no lugar do nome, e ao editar o campo **Nome** vem vazio para você preencher. Se você salvar a edição com o campo vazio, o contato continua **Sem nome**.

Nas mensagens, o nome de um contato **Sem nome** fica vazio: `{{name}}` nas [campanhas](https://docs.octasend.com.br/plataforma/campanhas.md) e `{{cliente_nome}}` nas [automações](https://docs.octasend.com.br/plataforma/automacoes.md) por segmento e por data.

> [!NOTE]
>
> Um envio que identifica o destinatário só por `user_id`, `fcm_token` ou identificadores de Telegram e Slack, sem e-mail nem telefone, **não** cria contato.

## Como a OctaSend evita contatos duplicados

Antes de criar um contato a partir de uma origem automática, a OctaSend procura se a pessoa já existe:

**1. Procura pelo e-mail**

Se já existe um contato com o mesmo e-mail, é ele que recebe os dados novos.

**2. Procura pelo telefone**

Sem e-mail correspondente, procura um contato com o mesmo telefone **que ainda não tenha e-mail próprio**.

**3. Cria um contato novo**

Se nenhuma das duas buscas encontrar alguém, um contato novo é criado.

Regras que decorrem disso:

* **Um e-mail pertence a um único contato** na sua conta. Cadastrar ou importar pelo painel o e-mail de um contato ativo dá erro. O e-mail de um contato removido não dá erro: ele restaura esse contato (veja [Remover e restaurar um contato](#remover-e-restaurar-um-contato)).
* **Telefone igual não basta para juntar dois cadastros.** Duas pessoas podem compartilhar um número (linha da empresa, telefone da família). Se o contato encontrado pelo telefone já tem outro e-mail, a OctaSend cria um contato separado em vez de misturar os dois. Por isso, sempre que tiver o e-mail, envie-o junto com o telefone.
* **Maiúsculas contam no e-mail**: `Ana@exemplo.com` e `ana@exemplo.com` viram dois contatos. O cadastro e a importação de clientes do E-commerce, a importação de pedidos e o chatbot do site já convertem o e-mail para minúsculas; no envio pela API e no painel de Contatos, o e-mail é gravado como você enviou. Padronize os e-mails em minúsculas.
* **Ao atualizar um contato existente**, o telefone passa a ser o mais recente informado, um e-mail que faltava é preenchido e, quando a origem traz um nome (API com `nome`, automação, loja, E-commerce), o nome é substituído por ele. Uma célula de nome vazia numa planilha de E-commerce não apaga o nome já cadastrado.
* **Mensagens recebidas no WhatsApp e participantes salvos de grupos nunca trocam um nome já cadastrado.** O nome do perfil do WhatsApp só preenche contatos que ainda estão **Sem nome**.
* **Salvar participantes de grupo reconhece o mesmo celular com e sem o nono dígito** e não cria duplicata. Um contato que já tem e-mail não é usado para o participante com o mesmo telefone: nesse caso, nasce um contato novo. Um participante que era um contato removido é restaurado e volta para a lista.
* **O chatbot do site nunca altera um cadastro existente.** Se o e-mail ou o telefone informado pelo visitante já pertence a um contato, a conversa só é vinculada a ele; nenhum dado do contato muda.

### Formato do telefone

Nas origens automáticas, o telefone é padronizado no formato internacional: `+` seguido só dos dígitos (ex.: `+5511999999999`). A mesma regra vale no envio pelo WhatsApp e na conferência do descadastro. Há uma exceção, descrita logo abaixo da tabela.

| Telefone recebido | Como é interpretado |
| - | - |
| Com `+` e código do país | Mantido como está, só sem a formatação |
| 10 dígitos, sem `+` | Fixo brasileiro com DDD: recebe `+55` |
| 11 dígitos com `9` na terceira posição, sem `+` | Celular brasileiro com DDD: recebe `+55` |
| Outros números com 11 dígitos ou mais, sem `+` | Número que já traz o código do país: recebe só o `+` |
| Menos de 10 dígitos | Descartado: o contato fica sem telefone |

> [!TIP]
>
> Para não depender da interpretação, envie sempre o telefone com `+` e o código do país, principalmente os números de fora do Brasil.

Exceção à padronização: no **cadastro e na importação de clientes do E-commerce**, o `+` é descartado antes da padronização, e o número é lido como se tivesse chegado sem `+`. Lá, informe o número com o código do país (ex.: `55 11 99999-9999`).

No **Novo Contato** e no **Importar CSV** desta tela, o telefone é gravado exatamente como você digitou. Use o mesmo formato internacional sugerido no campo (`+5511999999999`).

## A lista de contatos

A tabela mostra os contatos da conta conforme o seletor **Mostrar**: **Ativos** (o padrão) ou **Removidos** (veja [Remover e restaurar um contato](#remover-e-restaurar-um-contato)). As colunas são **Nome**, **Email**, **Telefone**, **Descadastrado de** e **Criado em**, além de colunas de canal que só aparecem quando o canal está ativo na sua conta. **Descadastrado de** mostra os canais (E-mail, WhatsApp, SMS) de que o contato se descadastrou, ou um traço quando ele recebe por todos (veja [Descadastro por canal](#descadastro-por-canal)).

| Coluna | Aparece quando | O que indica |
| - | - | - |
| **User ID** | Web Push ou In-App está ativo | O contato tem o identificador do usuário no seu sistema |
| **Telegram** | Telegram está ativo | O contato tem Telegram Chat ID |
| **Slack User** e **Slack Ch.** | Slack está ativo | O contato tem Slack User ID e Slack Channel |
| **FCM** | Web Push está ativo | O contato tem token FCM |

Nas colunas de canal, um sinal de confirmação indica que o dado está preenchido; um traço indica que falta.

* **Busca** — o campo *Buscar por nome, email ou telefone…* encontra qualquer contato que contenha o trecho digitado no nome, no e-mail ou no telefone, sem diferenciar maiúsculas. Para telefone, digite só os números (ex.: `11999`).
* **Ordenação** — clique no título de **Nome**, **Email**, **Telefone** ou **Criado em** para ordenar; clique de novo para inverter. A ordem inicial é por nome, de A a Z.
* **Paginação** — 50 contatos por página. Com mais de 50, aparecem o total de contatos e os botões **Anterior** e **Próxima**.
* **Detalhes** — clique numa linha para abrir o contato, com a data de criação, os **Dados principais** (Email, Telefone, User ID), os **Canais** (Telegram Chat ID, Slack User ID, Slack Channel, FCM Token) e o **Descadastro** de cada canal. Cada valor tem um botão de copiar; o telefone é copiado só com os dígitos. Num contato removido, o botão **Editar** dá lugar a **Restaurar**.

## Criar e editar um contato

Clique em **Novo Contato**, preencha e clique em **Salvar**. Para editar, use o lápis na linha do contato ou o botão **Editar** nos detalhes.

| Campo | Obrigatório | Para que serve |
| - | - | - |
| Nome | Sim | Nome exibido em toda a plataforma |
| Email | Não | Destinatário de e-mail; é a chave que identifica o contato |
| Telefone | Não | Destinatário de WhatsApp e demais canais por telefone, no formato `+5511999999999` |
| User ID (Web Push / In-App) | Não | O identificador do usuário no seu sistema, o mesmo usado em `recipient.user_id` na API |
| Telegram Chat ID | Não | Chat do usuário no Telegram |
| Slack User ID | Não | Usuário do Slack (ex.: `U01234ABCDE`) |
| Slack Channel | Não | Canal do Slack (ex.: `#geral`) |
| FCM Token (Web Push) | Não | Token do dispositivo para Web Push |

O formulário mostra todos os campos, mesmo os de canais que você não usa. Num contato novo, o botão **Salvar** só fica disponível com o nome preenchido. Na edição de um contato **Sem nome**, você pode salvar com o nome vazio, por exemplo para preencher só um campo de canal, e ele continua **Sem nome**. Na edição de um contato já criado, o formulário também tem o quadro **Descadastro** (veja [Descadastro por canal](#descadastro-por-canal)).

| Mensagem | O que houve |
| - | - |
| Contato criado / Contato atualizado | Deu certo |
| Esse e-mail era de um contato removido. Ele foi restaurado com os dados novos. | Em **Novo Contato**, o e-mail era de um contato removido. Em vez de criar outro, a OctaSend restaurou esse contato com os dados que você digitou; os campos deixados em branco mantêm o que ele já tinha. O descadastro dele continua como estava |
| Já existe um contato com este e-mail | O e-mail já pertence a outro contato ativo da conta. Na edição, vale também para o e-mail de um contato removido |
| Erro ao criar contato / Erro ao atualizar contato | Falha ao gravar; tente de novo |

Salvar uma edição pelo painel mantém os campos extras que o formulário não mostra: os gravados pelo passo **Atualizar contato** das automações (como um campo de data usado no gatilho **Data de um campo do contato**) e a origem do contato continuam no cadastro. Só mudam os campos que aparecem no formulário. Apagar o valor de um campo de canal (User ID, Telegram Chat ID, Slack User ID, Slack Channel ou FCM Token) remove esse dado do contato.

## Descadastro por canal

O contato pode estar descadastrado do **E-mail**, do **WhatsApp** e do **SMS**, de forma independente. O descadastro vale para as mensagens de **marketing**: as mensagens **transacionais**, sobre um pedido ou a conta do próprio contato, continuam chegando.

| Envio | Respeita o descadastro? |
| - | - |
| [Campanhas](https://docs.octasend.com.br/plataforma/campanhas.md) | Sim |
| [Automações](https://docs.octasend.com.br/plataforma/automacoes.md) com gatilho **Segmento de contatos**, **Data de um campo do contato** ou **Chamada de API** | Sim |
| Carrinho abandonado configurado na integração da loja | Sim |
| Automações com gatilho **Chegou um pedido** ou **Evento de uma loja** | Não: são transacionais |
| Eventos de pedido e de cliente mapeados na integração da loja | Não: são transacionais |
| Envios pela [API](https://docs.octasend.com.br/api-reference/enviar-mensagens.md) | Só quando a chamada envia `respect_opt_out: true`. Sem isso, são tratados como transacionais |

Quando o descadastro é respeitado, o canal descadastrado não recebe: o envio é pulado e aparece em [Logs de mensagens](https://docs.octasend.com.br/plataforma/logs-de-mensagens.md) como **Ignorada**, com o motivo "Contato descadastrado". Os outros canais da mesma mensagem seguem normalmente.

Onde o descadastro aparece:

* na coluna **Descadastrado de** da lista;
* no detalhe do contato, no quadro **Descadastro**: cada canal mostra **Recebe campanhas e automações de marketing** ou **Descadastrado**, com a data e a origem (por exemplo, "Desde 20/09/2026 10:00 · link no e-mail"). Quando outro contato da conta com o mesmo e-mail ou telefone se descadastrou, o canal aparece como **Descadastrado por outro contato com o mesmo e-mail/telefone**, porque o envio também é pulado para este contato;
* na edição do contato, no quadro **Descadastro**, com uma caixa por canal.

| Origem | Quando acontece |
| - | - |
| link no e-mail | O destinatário clicou no link de descadastro do rodapé de um e-mail de campanha ou de automação de marketing e confirmou em **Confirmar descadastro** |
| descadastro em um clique do provedor de e-mail | O destinatário usou o descadastro em um clique do próprio programa de e-mail (cabeçalho `List-Unsubscribe`) |
| descadastro no SendGrid, grupo de descadastro do SendGrid, denúncia de spam no SendGrid | O SendGrid informou esse evento pelo webhook de eventos configurado no canal E-mail (veja [E-mail](https://docs.octasend.com.br/guias/email.md)) |
| painel | Alguém da sua conta marcou o canal na edição do contato |

Para descadastrar ou recadastrar pelo painel, edite o contato, marque ou desmarque o canal no quadro **Descadastro** e clique em **Salvar**. Só os canais que você mudou são gravados: salvar o contato sem mexer no quadro mantém a data e a origem do descadastro original.

Regras:

* O descadastro do e-mail vale para o endereço de e-mail, sem diferenciar maiúsculas: um envio para o mesmo e-mail é pulado mesmo que parta de outro cadastro. O descadastro do WhatsApp e do SMS vale para o mesmo telefone.
* A conferência é feita no momento de cada envio. Descadastrar um contato no meio de uma campanha já vale para os envios seguintes.
* Os e-mails de campanhas e de automações de marketing levam no rodapé o link de descadastro. Os e-mails transacionais e os enviados pela API não levam.

## Remover e restaurar um contato

Clique na lixeira da linha e confirme em **Remover contato?**. O contato sai da lista de ativos, deixa de entrar nas automações por segmento e por data e deixa de receber campanhas.

> [!NOTE]
>
> * Remover **não** tira o contato das listas de campanha em que ele já está. Ele fica de fora quando a campanha começa a enviar e, numa campanha que já está enviando, o envio para ele é pulado com o motivo "Contato removido".
> * As origens automáticas não trazem um contato removido de volta à lista: envios pela API, pedidos da loja, conversas e a importação de clientes do E-commerce podem atualizar os dados dele, mas ele continua removido.

Para ver os contatos removidos, escolha **Removidos** no seletor **Mostrar**. Cada linha tem o botão **Restaurar**, que também aparece no detalhe do contato. O contato restaurado volta para os ativos com os mesmos dados e descadastros de antes.

Um contato removido também é restaurado quando:

* você cria em **Novo Contato**, ou importa em **Importar CSV**, um contato com o mesmo e-mail dele: em vez de dar erro, a OctaSend restaura o removido com os dados novos;
* você salva, na aba **Participantes** de um grupo de WhatsApp, um participante que era esse contato.

## Importar contatos por planilha

Há dois caminhos de importação. Os dois criam contatos; a importação de clientes do E-commerce também cria o cliente em **E-commerce → Clientes** e é mais tolerante com o formato do arquivo.

> [tab] Contatos (Importar CSV)
>
> Em **Comunicações → Contatos**, clique em **Importar CSV**.
>
> **1. Baixe o modelo**
>
> Clique em **Baixar modelo** para obter um arquivo com o cabeçalho `nome,email,telefone`.
>
> **2. Envie o arquivo**
>
> Arraste o `.csv` para a área indicada ou clique em **Selecionar arquivo CSV**.
>
> **3. Confira a prévia**
>
> A tela mostra quantos contatos estão prontos para importação e as 20 primeiras linhas. Linhas ignoradas aparecem em **Avisos**.
>
> **4. Importe**
>
> Clique em **Importar N contatos**. Ao terminar, aparece *N contatos importados com sucesso*. Se alguma linha restaurou um contato removido, a mensagem diz quantos (por exemplo, *(2 restaurados que estavam removidos)*).
>
> **Formato do arquivo**
>
> * Apenas `.csv`, com as colunas **separadas por vírgula** e codificação UTF-8.
> * A primeira linha é o cabeçalho. Maiúsculas e minúsculas no cabeçalho não importam.
> * Colunas reconhecidas:
>
> | Coluna | Nomes aceitos no cabeçalho | Obrigatória |
> | - | - | - |
> | Nome | `nome` ou `name` | Sim |
> | E-mail | `email` | Não |
> | Telefone | `telefone`, `phone`, `cel` ou `celular` | Não |
>
> Qualquer outra coluna é ignorada, inclusive variações como `e-mail`.
>
> **Validações e erros**
>
> | Situação | Resultado |
> | - | - |
> | Arquivo sem cabeçalho ou sem nenhuma linha de dados | *O arquivo precisa ter cabeçalho e ao menos uma linha de dados.* |
> | Cabeçalho sem a coluna de nome, ou arquivo separado por ponto e vírgula | *Coluna "nome" não encontrada no cabeçalho.* |
> | Linha com o nome vazio | Ignorada e listada em **Avisos** (*Linha N: nome vazio, ignorada.*) |
> | Linha com o e-mail de um contato removido | O contato removido é restaurado com o nome da linha e, se houver, o telefone dela |
> | Algum e-mail do arquivo já pertence a um contato ativo, ou um e-mail novo se repete no próprio arquivo | Nada é importado: *Erro ao importar contatos* |
>
> > [!WARNING]
> >
> > Esta importação é **tudo ou nada** e não atualiza contatos ativos: ela só cria contatos novos e restaura os removidos. Um único e-mail de contato ativo cancela o arquivo inteiro. Remova do arquivo os e-mails que já estão na base antes de importar.
>
> > [!TIP]
> >
> > O Excel em português salva CSV com ponto e vírgula, e esta importação não aceita esse formato. Exporte pelo Google Planilhas (**Arquivo → Fazer download → Valores separados por vírgula (.csv)**), que usa vírgula e UTF-8, ou use a importação de clientes do E-commerce, que aceita ponto e vírgula e o formato do Excel. Evite vírgulas dentro dos valores: mesmo entre aspas, elas dividem a célula.
>
> O e-mail não passa por validação de formato e o telefone é gravado como está no arquivo.

> [tab] Clientes do E-commerce
>
> Em **E-commerce → Clientes**, clique em **Importar planilha**. Cada linha importada cria ou atualiza o cliente do E-commerce e também o contato correspondente, seguindo as regras de [unificação](#como-a-octasend-evita-contatos-duplicados).
>
> **1. Baixe o modelo**
>
> Clique em **Baixar modelo**. Colunas: nome, e ao menos uma entre email ou telefone.
>
> **2. Envie o arquivo**
>
> Arraste o `.csv` ou clique na área indicada. A plataforma lê a planilha e monta um **Resumo da importação** sem gravar nada.
>
> **3. Confira o resumo**
>
> O resumo mostra **Clientes reconhecidos**, **Novos** e **Já existem e serão atualizados**, além das **Linhas descartadas** com o motivo.
>
> **4. Confirme**
>
> Clique em **Confirmar importação de N clientes**. Ao terminar, a tela mostra **Clientes criados** e **Clientes atualizados**.
>
> **Formato do arquivo**
>
> * `.csv` separado por vírgula ou por ponto e vírgula (detectado automaticamente), em UTF-8 ou no formato padrão do Excel no Windows.
> * Valores entre aspas podem conter o separador.
> * Cabeçalho sem diferenciar maiúsculas nem acentos:
>
> | Coluna | Nomes aceitos no cabeçalho |
> | - | - |
> | Nome | `nome`, `name`, `cliente`, `cliente_nome`, `nome do cliente` |
> | E-mail | `email`, `e-mail`, `e mail`, `mail`, `cliente_email` |
> | Telefone | `telefone`, `phone`, `celular`, `whatsapp`, `fone`, `cliente_telefone` |
>
> **Regras**
>
> * Limite de **2.000 clientes por importação**. Acima disso, a planilha é recusada: divida o arquivo em partes menores.
> * A planilha precisa de ao menos uma das colunas de e-mail ou telefone; sem nenhuma das duas, é recusada inteira.
> * Uma linha sem e-mail válido e sem telefone válido é descartada (*o cliente não seria alcançável*). O telefone precisa ter ao menos 8 dígitos.
> * O e-mail é convertido para minúsculas. Cada cliente é identificado pelo e-mail ou, na falta dele, pelo telefone.
> * O mesmo cliente repetido na planilha vale uma vez só: a **última** linha prevalece e a anterior aparece em **Linhas descartadas**.
> * Reenviar a mesma planilha atualiza os clientes em vez de duplicá-los.
> * Na atualização, só mudam os dados das colunas que a planilha traz. O CPF e o endereço cadastrados à mão no cliente continuam, e uma planilha sem a coluna de nome ou de telefone não apaga esses dados. Uma célula vazia numa coluna que existe na planilha limpa o campo do cliente do E-commerce, mas não apaga o nome nem o telefone já gravados no contato.
>
> Veja mais sobre clientes, pedidos e produtos em [E-commerce](https://docs.octasend.com.br/plataforma/ecommerce.md).

## Onde os contatos são usados

* **Campanhas** — em **Campanhas → Listas** você busca contatos e os adiciona às listas que as campanhas usam como público. Veja [Campanhas](https://docs.octasend.com.br/plataforma/campanhas.md).
* **Automações** — os gatilhos **Segmento de contatos** e **Data de um campo do contato** partem da base de contatos e consideram só contatos ativos (não removidos). O campo de data precisa estar no formato `AAAA-MM-DD`. Os passos **Atualizar contato** e **Marcar contato** gravam dados e marcações no contato; esses dados extras não aparecem na tela de Contatos. Veja [Automações](https://docs.octasend.com.br/plataforma/automacoes.md).
* **WhatsApp** — o nome do contato aparece junto do telefone nas conversas e nos grupos. Na aba **Participantes** de um grupo, quem já está na base aparece como *já é contato*; os demais podem ser salvos um a um (**Salvar como contato**) ou todos de uma vez (**Salvar todos**). Veja [WhatsApp: conversas e grupos](https://docs.octasend.com.br/plataforma/whatsapp-conversas-e-grupos.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.