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

# Como importar contactos para a CloudTalk a partir de um ficheiro

> Um guia simples para importar contactos para a CloudTalk a partir de um ficheiro Excel/CSV

<Note>
  Neste artigo, vamos guiá-lo no carregamento de um ficheiro de contactos para a CloudTalk.
</Note>

**Nível de utilizador**:

* Admin

***

<Warning>
  ⚠️ **A importação de contactos através de ficheiros CSV pode demorar algum tempo.** Para obter os melhores resultados, recomendamos que conte com tempo de processamento adicional durante as horas de maior tráfego.

  Se o tempo for crítico para a sua importação, considere métodos alternativos, como utilizar uma integração de CRM ou a API da CloudTalk para sincronização em tempo real.

  📘 **Saiba mais**: [Como importo contactos para a CloudTalk?](/pt/articles/2145547-how-to-import-contacts-into-cloudtalk)
</Warning>

<h2 id="data-preparation">
  Preparação dos dados
</h2>

<Warning>
  **É suportado um máximo de 8MB (normalmente \~ 80 mil contactos).** Ficheiros maiores não serão carregados.
</Warning>

Ao importar contactos a partir de um ficheiro, é atualmente necessário o formato **`.csv`** . Existem vários tipos de software que lhe permitem guardar os seus dados em CSV. No caso mais comum, a utilização do Excel, pode aceder a **Ficheiro > Guardar como**. No campo *Nome do ficheiro*, selecione o formato **CSV** .

É muito importante configurar o seu ficheiro CSV de acordo com o nosso **modelo de ficheiro CSV**. Para aceder a este modelo, na sua conta do **[CloudTalk Dashboard](https://dashboard.cloudtalk.io/)**, navegue até ***Contactos*** *> **Lista** > **Importar contatos em massa*** e depois clique em **Descarregar modelo** no canto inferior esquerdo. Note que pode eliminar com segurança quaisquer colunas não utilizadas do modelo.Se só precisar de importar dados básicos como **name**, **phone** ou **email**, pode remover todas as outras colunas sem qualquer problema.

<Frame>
  <img src="https://mintcdn.com/cloudtalk/6Hiy83aLw1wFZVvu/images/help-center/articles/3422012/2dadc89fbf39-screenshot-2026-03-18-at-11-36-16.png?fit=max&auto=format&n=6Hiy83aLw1wFZVvu&q=85&s=7c677bcda4a98521e4afc2be17bbe2fe" alt="" width="1258" height="824" data-path="images/help-center/articles/3422012/2dadc89fbf39-screenshot-2026-03-18-at-11-36-16.png" />
</Frame>

<Info>
  #### Requisitos do ficheiro CSV

  É **altamente recomendável** descarregar e seguir o modelo. Acima de tudo, não se esqueça de:

  * Escrever todos os nomes das colunas em **minúsculas** (os atributos personalizados podem ser diferentes)

  * **Evitar tipos de letra especiais ou texto estilizado** (por exemplo, tipos de letra cursivos, caligráficos ou decorativos) nos nomes dos contactos ou noutros campos. Estes podem impedir que o seu ficheiro seja carregado corretamente.

  * Utilizar apenas **caracteres ASCII padrão** no nome e no conteúdo do ficheiro. As importações de CSV podem falhar se forem utilizados caracteres especiais ou não ASCII (por exemplo, ö, ü, ç).

  * Preencher os valores de **`name`** e **`phone`** ou **`email`** para **todos os contactos.**

  O não cumprimento destas indicações pode originar linhas com falha ou importações incompletas.\
  Alguns problemas (como cabeçalhos incorretos ou uma estrutura de ficheiro errada) podem impedir por completo o início da importação.
</Info>

<Warning>
  **Importante: código de país padrão**\
  O país predefinido nas suas **Definições da conta** determina qual o indicativo internacional (`+`) que será aplicado automaticamente aos números de telefone carregados que ainda não o incluam.

  Antes de importar o ficheiro, verifique novamente se o país selecionado em **Conta > Definições > Código de país padrão** corresponde ao país dos números de telefone do seu CSV.

  Se o país predefinido for diferente, os seus números podem ser importados com o prefixo internacional errado.
</Warning>

<h3 id="h_603d66a186">
  Exemplo de colunas na sua folha de cálculo
</h3>

<table>
  <tbody>
    <tr>
      <td>
        **Coluna**
      </td>

      <td>
        **Descrição**
      </td>

      <td>
        **Exemplo**
      </td>
    </tr>

    <tr>
      <td>
        `name`
      </td>

      <td>
        Nome próprio e apelido do contacto. Este campo tem de conter pelo menos um carácter.
      </td>

      <td>
        `Jane Smith`
      </td>
    </tr>

    <tr>
      <td>
        `phone`
      </td>

      <td>
        Os números de telefone podem ser indicados em formato internacional (E.164) ou em formato local. Se um número não incluir o indicativo do país, a CloudTalk aplica o código de país padrão das definições da sua conta.

        Para obter os melhores resultados, recomendamos o formato E.164. Pode incluir **vários números de telefone** separados por dois pontos (`:`).
      </td>

      <td>
        `+14155550123`

        `0908678545`

        `+14155550123:+12125550189`
      </td>
    </tr>

    <tr>
      <td>
        `email`
      </td>

      <td>
        Endereço de email principal. Pode incluir **vários endereços de email** neste campo, separados por dois pontos (`:`).
      </td>

      <td>
        [`jane.smith@company.com`](mailto:jane.smith@company.com)

        [`jane@company.com`](mailto:jane@company.com)`:j.smith@company.com`
      </td>
    </tr>

    <tr>
      <td>
        `email2`
      </td>

      <td>
        Endereço de email adicional. Este campo é mantido por **retrocompatibilidade** com o sistema original.
      </td>

      <td>
        [`jane.alt@company.com`](mailto:jane.alt@company.com)
      </td>
    </tr>

    <tr>
      <td>
        `title`
      </td>

      <td>
        Cargo do contacto.
      </td>

      <td>
        `Head of Sales`
      </td>
    </tr>

    <tr>
      <td>
        `company`
      </td>

      <td>
        Nome da empresa a que o contacto pertence.
      </td>

      <td>
        `Acme Corp`
      </td>
    </tr>

    <tr>
      <td>
        `address`
      </td>

      <td>
        Morada do contacto.
      </td>

      <td>
        `Main Street 1, San Francisco`
      </td>
    </tr>

    <tr>
      <td>
        `favorite_agent`
      </td>

      <td>
        Endereço de email de um agente da CloudTalk a atribuir como agente preferido do contacto. Se o email corresponder a um agente existente, o agente é atribuído. Se não for encontrada correspondência, a importação desta linha falha.
      </td>

      <td>
        [`agent@company.com`](mailto:agent@company.com)
      </td>
    </tr>

    <tr>
      <td>
        `tag`
      </td>

      <td>
        Uma ou mais tags a atribuir ao contacto. Várias tags têm de ser separadas por dois pontos (`:`). As tags existentes são reutilizadas; as novas tags são criadas automaticamente se ainda não existirem.
      </td>

      <td>
        `coldlead:webinar:priority`
      </td>
    </tr>

    <tr>
      <td>
        Atributos personalizados
      </td>

      <td>
        Quaisquer campos adicionais que queira importar. Estes têm de ser criados primeiro como atributos personalizados nas Definições da conta e os nomes das colunas têm de corresponder exatamente.
      </td>

      <td>
        `industry` → `Saúde`
      </td>
    </tr>
  </tbody>
</table>

<h4 id="h_fe7c42c7f4">
  Coluna do país (formatos suportados)
</h4>

Se o seu ficheiro CSV incluir uma coluna `country`, a CloudTalk aceita vários formatos de país para facilitar as importações.

Pode utilizar:

* **Códigos de país de duas letras**, por exemplo: `US`, `GB`, `DE`

* **Códigos de país de três letras**, por exemplo: `USA`, `FRA`, `DEU`

* **Nomes completos dos países em inglês**, por exemplo: `United States`, `Germany`, `France`

* **Variantes comuns e inequívocas**, por exemplo: `United States of America`, `Great Britain`, `Trinidad & Tobago`

A CloudTalk normaliza automaticamente as diferenças de formatação mais comuns, incluindo:

* valores em maiúsculas e minúsculas

* espaços adicionais antes, depois ou dentro do valor

* a utilização de `&` em vez de `and` (e vice-versa)

Se o valor do país não puder ser reconhecido, a linha falha com uma mensagem de erro clara a indicar que o valor do país é inválido.

<h4 id="h_202c0f0772">
  Atributos personalizados
</h4>

Para garantir que os campos de contacto adicionais do seu ficheiro CSV são apresentados corretamente nos contactos, terá de os adicionar como *[atributos personalizados](/pt/articles/2144934-custom-attributes)* nas definições do seu dashboard.

1. No dashboard, navegue até **Conta > Definições**.

2. No separador *Definições gerais*, desça até à secção *Contactos*.

3. É aqui que pode adicionar os nomes dos seus campos personalizados, selecionando `+ Adicionar Atributo Personalizado`. Certifique-se de que os nomes que introduz aqui correspondem aos nomes do seu CSV, tanto na ortografia como nas maiúsculas e minúsculas.

<Frame>
  <img src="https://mintcdn.com/cloudtalk/6Hiy83aLw1wFZVvu/images/help-center/articles/3422012/4850012ef211-screenshot-2024-12-13-at-16-49-46.png?fit=max&auto=format&n=6Hiy83aLw1wFZVvu&q=85&s=a015e03e061b2611efa613f935921644" alt="" width="2155" height="598" data-path="images/help-center/articles/3422012/4850012ef211-screenshot-2024-12-13-at-16-49-46.png" />
</Frame>

<h2 id="importing-contacts-from-a-file">
  Importar contactos a partir de um ficheiro
</h2>

Quando o ficheiro CSV estiver concluído e guardado no formato correto, está pronto a ser importado.

1. Aceda a **Contactos > Lista > Importar contatos em massa.**

   <Frame>
     <img src="https://mintcdn.com/cloudtalk/6Hiy83aLw1wFZVvu/images/help-center/articles/3422012/f91509de118b-screenshot-2026-01-08-at-15-43-57.png?fit=max&auto=format&n=6Hiy83aLw1wFZVvu&q=85&s=0eec35d6d5fb6ceea39b5c54d7e61384" alt="" width="350" data-path="images/help-center/articles/3422012/f91509de118b-screenshot-2026-01-08-at-15-43-57.png" />
   </Frame>

2. Carregue o ficheiro CSV.

3. **Adicione tags aos seus contactos**: crie uma tag como forma de identificação dos contactos que está a importar. Esta tag é importante para as [campanhas do Dialer](/pt/articles/8428838-setting-up-campaigns-legacy-dialer) e pode ser utilizada para filtrar contactos.

   <Frame>
     <img src="https://mintcdn.com/cloudtalk/6Hiy83aLw1wFZVvu/images/help-center/articles/3422012/1439c01d7f67-screenshot-2024-12-13-at-14-32-52.png?fit=max&auto=format&n=6Hiy83aLw1wFZVvu&q=85&s=5e302a417b9525143b19e4db27742204" alt="" width="330" data-path="images/help-center/articles/3422012/1439c01d7f67-screenshot-2024-12-13-at-14-32-52.png" />
   </Frame>

4. Selecione `Confirmar` para iniciar a importação.

Depois de carregar o ficheiro, a importação aparece em **Contactos > Arquivos importados**, onde pode acompanhar o respetivo progresso e analisar os resultados.

<h3 id="h_8ecaab147c">
  Arquivos importados
</h3>

A CloudTalk mantém um histórico claro de todas as importações de CSV, para que possa acompanhar facilmente o que aconteceu, detetar problemas e corrigi-los sem contactar o Suporte.

<Frame>
  <img src="https://mintcdn.com/cloudtalk/6Hiy83aLw1wFZVvu/images/help-center/articles/3422012/fb7aedb0243a-screenshot-2026-01-08-at-17-01-15.png?fit=max&auto=format&n=6Hiy83aLw1wFZVvu&q=85&s=3d5d8da94cc5adcf32045b1a36a8b883" alt="" width="2398" height="488" data-path="images/help-center/articles/3422012/fb7aedb0243a-screenshot-2026-01-08-at-17-01-15.png" />
</Frame>

Quando abre uma tarefa de importação, a CloudTalk apresenta um detalhe completo, incluindo:

* Número total de linhas do ficheiro

* Número de contactos importados com sucesso

* Número de contactos que falharam (caso existam)

* Um estado linha a linha com mensagens de resultado claras. Cada linha com falha inclui um motivo específico que explica por que razão o contacto não pôde ser importado.

<Frame>
  <img src="https://mintcdn.com/cloudtalk/6Hiy83aLw1wFZVvu/images/help-center/articles/3422012/661d3101fb1a-screenshot-2026-01-08-at-14-47-34.png?fit=max&auto=format&n=6Hiy83aLw1wFZVvu&q=85&s=83f8e6224f56f95c8f949e3db3f1e927" alt="" width="2852" height="1139" data-path="images/help-center/articles/3422012/661d3101fb1a-screenshot-2026-01-08-at-14-47-34.png" />
</Frame>

<h2 id="h_bb7f784856">
  O que acontece se uma importação falhar
</h2>

<h3 id="h_3e4dc60c74">
  Erros globais de importação
</h3>

Se a importação falhar antes de processar as linhas, verá uma mensagem de erro global a explicar o motivo, por exemplo:

* Não foi possível carregar o ficheiro

* Indisponibilidade temporária do serviço (normalmente resolve-se sozinha ao fim de pouco tempo. Se o problema persistir ou ocorrer várias vezes no espaço de algumas horas, o [Suporte da CloudTalk](mailto:support@cloudtalk.io) pode ajudar a investigar)

* O tamanho do ficheiro excede 8 MB

<Frame>
  <img src="https://mintcdn.com/cloudtalk/6Hiy83aLw1wFZVvu/images/help-center/articles/3422012/fb6879d5840a-screenshot-2026-03-18-at-15-45-34.png?fit=max&auto=format&n=6Hiy83aLw1wFZVvu&q=85&s=b108cea23b1f53953bc1068920aacff3" alt="" width="500" data-path="images/help-center/articles/3422012/fb6879d5840a-screenshot-2026-03-18-at-15-45-34.png" />
</Frame>

<h3 id="h_21e352821e">
  Importações parciais
</h3>

A CloudTalk já não rejeita o ficheiro inteiro por causa de um contacto inválido.

* Os contactos válidos são importados com sucesso

* Os contactos inválidos são marcados como **Falhou**

* Uma importação com este resultado é apresentada com um **estado «Concluído» a laranja**, indicando que a importação terminou, mas que algumas linhas falharam.

* Se demasiadas linhas falharem (o limite é de **1000** registos com falha), a importação pode ser interrompida para evitar dados incorretos.

Pode descarregar o relatório de erros, corrigir apenas as linhas com falha e voltar a carregá-las.

<Frame>
  <img src="https://mintcdn.com/cloudtalk/6Hiy83aLw1wFZVvu/images/help-center/articles/3422012/2b0125eb2640-screenshot-2026-01-08-at-15-10-53.png?fit=max&auto=format&n=6Hiy83aLw1wFZVvu&q=85&s=2ea927d02e569d430aa07eaecfcfe2a5" alt="" width="2416" height="1176" data-path="images/help-center/articles/3422012/2b0125eb2640-screenshot-2026-01-08-at-15-10-53.png" />
</Frame>

<h3 id="h_f4f028935e">
  Como corrigir as linhas com falha
</h3>

1. Abra **Contactos > Arquivos importados**

2. Clique em **Ver detalhes** na importação que falhou

3. Analise o motivo da falha de cada contacto

4. Descarregue o relatório de erros (se estiver disponível)

5. Corrija apenas as linhas com falha no seu CSV

6. Volte a carregar o ficheiro corrigido

<h3 id="h_9a3fafc70c">
  Lista de erros das linhas com falha e como resolvê-los
</h3>

<table>
  <tbody>
    <tr>
      <td>
        **Nome do erro**
      </td>

      <td>
        **Descrição**
      </td>

      <td>
        **Como corrigir**
      </td>
    </tr>

    <tr>
      <td>
        `The value X in column Y is not a valid phone number.`

        `[phone, columnIndex]`
      </td>

      <td>
        O número não é um número de telefone local ou internacional válido.
      </td>

      <td>
        Introduza um número de telefone válido, em formato internacional (por exemplo, `+14155550123`) ou em formato local com o país predefinido correto configurado.
      </td>
    </tr>

    <tr>
      <td>
        `The value X in column Y is not a valid email address.`

        `[email, columnIndex]`
      </td>

      <td>
        O valor indicado é um email inválido.
      </td>

      <td>
        Introduza um formato de email válido (por exemplo, [firstName\_lastName@gmail.com](mailto:firstName_lastName@gmail.com))
      </td>
    </tr>

    <tr>
      <td>
        `The [columnName] value in column 1 is required.`
      </td>

      <td>
        Falta uma coluna obrigatória ou está vazia.
      </td>

      <td>
        Verifique se existem espaços adicionais nos cabeçalhos das colunas e garanta que as colunas obrigatórias estão corretamente identificadas e preenchidas.
      </td>
    </tr>

    <tr>
      <td>
        `The X value in column Y is required.`

        `[fieldName, columnIndex]`
      </td>

      <td>
        Está a tentar carregar o contacto sem o número de telefone ou o email.

        O campo **`phone`** ou **`email`** é obrigatório para que a CloudTalk importe este contacto.
      </td>

      <td>
        Reveja o contacto e certifique-se de que é indicado pelo menos um identificador válido (número de telefone em formato E.164 ou endereço de email).
      </td>
    </tr>

    <tr>
      <td>
        `The provided X value in column Y exceeds the maximum length of N characters.`

        `[fieldName, columnIndex, max]`
      </td>

      <td>
        Foi excedido o número máximo de caracteres permitido para uma coluna.
      </td>

      <td>
        Encurte o valor para que fique dentro do limite de caracteres permitido para este campo.
      </td>
    </tr>

    <tr>
      <td>
        `The provided X value in column Y must be at least N characters long.`

        `[fieldName, columnIndex, max]`
      </td>

      <td>
        O número de caracteres indicado é inferior ao comprimento mínimo exigido.
      </td>

      <td>
        A coluna **`name`** tem de conter pelo menos 1 carácter. Este campo é obrigatório.

        Todos os outros campos (como **`company`**, **`website`**, **`title`**, **`industry`**, **`address`**, **`city`**, **`zip`**, etc.) são opcionais.

        Se algum campo opcional ficar vazio, não será importado qualquer valor para esse campo.
      </td>
    </tr>

    <tr>
      <td>
        `The value X in column Y is not a valid website address.`

        `[columnName]`
      </td>

      <td>
        O valor na coluna website não é um endereço de site válido.
      </td>

      <td>
        Reveja e volte a carregar um endereço de site válido.
      </td>
    </tr>

    <tr>
      <td>
        `The value X in column Y is invalid.`

        `[displayFieldName, columnIndex]`
      </td>

      <td>
        Trata-se de um erro genérico. O valor na coluna é inválido.
      </td>

      <td>
        Reveja o valor deste contacto e corrija eventuais erros óbvios. Se não tiver a certeza de como o resolver, contacte a nossa [equipa de suporte](mailto:support@cloudtalk.io).
      </td>
    </tr>
  </tbody>
</table>

<h4 id="h_fae39d618e">
  Comprimento máximo de caracteres
</h4>

| Campo | Número máximo de caracteres |
| - | - |
| `name` | 150 |
| `zip` | 15 |
| `title` | 255 |
| `company` | 100 |
| `industry` | 100 |
| `website` | 100 |
| `address` | 255 |
| `city` | 255 |

Se um valor exceder o comprimento máximo, reduza o número de caracteres e volte a carregar o ficheiro.

Todos os outros campos são opcionais. Se um campo opcional ficar vazio, não será importado qualquer valor para esse campo.

<Warning>
  Se continuar a ter problemas depois de corrigir as linhas com falha ou se quiser ajuda com outros sintomas específicos da importação, consulte estes guias de resolução de problemas:

  * **[Importação de CSV bloqueada](/pt/articles/12958920-csv-import-stuck)** – explica por que motivo uma importação pode permanecer *Em processamento* durante muito tempo, quando isso é normal e quando deve agir.

  * **[O carregamento do ficheiro CSV falha](/pt/articles/12930295-upload-of-csv-file-fails)** – percorre os problemas comuns de formatação e de estrutura (como codificação, cabeçalhos em falta ou delimitadores errados) e explica como resolvê-los.
</Warning>

***

*Precisa de ajuda ou tem alguma questão?* Basta contactar-nos através do nosso [portal de suporte](https://support.cloudtalk.io/hc/en-us/requests/new?ticket_form_id=26305535257884) — estamos aqui para si.


## Related topics

- [Como importar contactos para a CloudTalk](/pt/articles/2145547-how-to-import-contacts-into-cloudtalk.md)
- [Falha no carregamento do ficheiro CSV](/pt/articles/12930295-upload-of-csv-file-fails.md)
- [Contactos duplicados com comportamento inesperado](/pt/articles/12929922-duplicate-contacts-behave-unexpectedly.md)


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