> For the complete documentation index, see [llms.txt](https://multiagents.gitbook.io/multiagents-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://multiagents.gitbook.io/multiagents-docs/documentacao-de-tools/readme/google-contatos.md).

# Google Contatos

## Importar Leads pelo Google Contacts

Com a integração **Google Contacts**, você pode importar seus contatos do Google diretamente para a plataforma Multiagents como leads — sem precisar exportar planilhas ou digitar dados manualmente.

***

### Como funciona

1. Você cria um aplicativo gratuito no Google Cloud Console
2. Configura a credencial na Multiagents com o Client ID e Client Secret
3. Autoriza o acesso à sua conta Google via OAuth
4. Na tela de Leads, o botão **"Importar do Google Contacts"** aparece automaticamente
5. Você escolhe quais contatos importar e para qual funil eles vão

> **Privacidade:** A Multiagents acessa apenas a leitura dos seus contatos. Nenhum dado é compartilhado com terceiros.

***

### Pré-requisitos

* Conta Google (Gmail ou Google Workspace)
* Acesso ao [Google Cloud Console](https://console.cloud.google.com)
* Perfil de **Admin** ou **Gerente** na Multiagents

***

### Parte 1 — Criar o App no Google Cloud Console

#### Passo 1 — Criar um projeto

1. Acesse [console.cloud.google.com](https://console.cloud.google.com)
2. No topo da página, clique no **seletor de projetos**
3. Clique em **"Novo Projeto"**
4. Dê um nome (ex: `Multiagents`) e clique em **"Criar"**
5. Aguarde a criação e certifique-se de que o novo projeto está selecionado

***

#### Passo 2 — Ativar a People API

1. No menu lateral, clique em **"APIs e Serviços"** → **"Biblioteca"**
2. Na barra de busca, digite **`People API`**
3. Clique em **"Google People API"**
4. Clique no botão **"Ativar"**

{% hint style="warning" %}
**Atenção:** Este é o passo mais esquecido. Sem ativar a People API, a importação vai retornar erro mesmo com as credenciais corretas.
{% endhint %}

***

#### Passo 3 — Configurar a Tela de Consentimento OAuth

A tela de consentimento é o que o Google exibe para o usuário antes de autorizar o acesso.

1. No menu lateral, clique em **"APIs e Serviços"** → **"Tela de permissão OAuth"**
2. Em "Tipo de usuário", selecione **"Externo"** → clique em **"Criar"**

{% hint style="info" %}
Selecione "Externo" mesmo que seja uso interno — contas Gmail comuns não têm a opção "Interno".
{% endhint %}

3. Preencha os campos obrigatórios:
   * **Nome do app:** `Multiagents` (ou o nome da sua empresa)
   * **E-mail de suporte do usuário:** seu e-mail
   * **Informações de contato do desenvolvedor:** seu e-mail
4. Clique em **"Salvar e Continuar"**

**Adicionando os escopos:**

5. Na tela seguinte (**Escopos**), clique em **"Adicionar ou Remover Escopos"**
6. Na caixa de busca, digite `contacts`
7. Marque os dois escopos abaixo:
   * `https://www.googleapis.com/auth/contacts.readonly`
   * `https://www.googleapis.com/auth/contacts.other.readonly`
8. Clique em **"Atualizar"** → **"Salvar e Continuar"**

**Adicionando usuários de teste:**

9. Na tela **"Usuários de teste"**, clique em **"+ Add Users"**
10. Digite o e-mail da conta Google que vai autorizar a integração
11. Clique em **"Adicionar"** → **"Salvar e Continuar"** → **"Voltar para o Painel"**

{% hint style="info" %}
**Por que adicionar usuários de teste?** Apps não verificados pelo Google só funcionam para e-mails explicitamente adicionados como "usuários de teste". Para uso interno (você mesmo ou sua equipe), isso é suficiente e não tem custo.
{% endhint %}

***

#### Passo 4 — Criar as Credenciais OAuth 2.0

1. No menu lateral, clique em **"APIs e Serviços"** → **"Credenciais"**
2. Clique em **"+ Criar Credenciais"** → **"ID do cliente OAuth"**
3. Em **"Tipo de aplicativo"**, selecione **"Aplicativo da Web"**
4. Dê um nome (ex: `Multiagents OAuth`)
5. Em **"URIs de redirecionamento autorizados"**, clique em **"+ Adicionar URI"** e insira:

```
https://api.multiagents.pro/callback-oauth
```

6. Clique em **"Criar"**

Uma janela vai exibir suas credenciais:

| Campo             | Descrição                            |
| ----------------- | ------------------------------------ |
| **Client ID**     | Identificador público do seu app     |
| **Client Secret** | Chave privada — guarde com segurança |

{% hint style="danger" %}
**Não feche essa janela antes de copiar o Client Secret.** Após fechar, o Google não exibe o secret novamente (você pode criar um novo se precisar).
{% endhint %}

***

### Parte 2 — Configurar na Multiagents

#### Passo 5 — Criar a credencial

1. Na Multiagents, acesse **Configurações → Credenciais**
2. Clique em **"Nova Credencial"**
3. Na lista de integrações, selecione **"Google Contacts"**
4. Preencha os campos:
   * **Nome:** ex. `Google Contacts` ou `Conta João`
   * **Client ID:** cole o valor copiado do Console Google
   * **Client Secret:** cole o valor copiado do Console Google
5. Clique em **"Salvar"**

***

#### Passo 6 — Autorizar o acesso via OAuth

1. Na tela da credencial recém-criada, clique em **"Conectar ao Google"**
2. Uma janela pop-up vai abrir com a tela de login do Google
3. Selecione a conta Google cujos contatos você quer importar

{% hint style="warning" %}
**Aviso esperado:** O Google pode exibir a mensagem *"Google não verificou este app"*. Isso é normal para apps em modo de desenvolvimento. Clique em **"Avançado"** → **"Acessar \[nome do app] (não seguro)"** para continuar.
{% endhint %}

4. Autorize as permissões de leitura de contatos
5. A janela fecha automaticamente e a credencial fica com status **"Conectado"**

***

### Parte 3 — Importar Contatos como Leads

#### Passo 7 — Acessar o botão de importação

1. Na Multiagents, acesse **Leads** no menu lateral
2. No topo da página, procure o botão **"Importar do Google Contacts"**

{% hint style="info" %}
O botão só aparece quando há uma credencial Google Contacts ativa e autenticada. Se não aparecer, verifique se o OAuth foi concluído no passo anterior.
{% endhint %}

***

#### Passo 8 — Selecionar os contatos

1. Clique em **"Importar do Google Contacts"**
2. O modal exibe seus contatos do Google com foto, nome, e-mail, telefone e empresa
3. Use a **barra de busca** para filtrar por nome ou e-mail
4. Marque o checkbox ao lado de cada contato que deseja importar
5. Para selecionar todos de uma vez, clique em **"Selecionar todos"**

***

#### Passo 9 — Definir o destino (opcional)

Na parte inferior do modal, você pode definir onde os leads vão entrar:

| Campo               | Descrição                                                                    |
| ------------------- | ---------------------------------------------------------------------------- |
| **Trabalho**        | Funil/pipeline de destino (opcional)                                         |
| **Estágio inicial** | Estágio onde os leads entram. Se não selecionar, vai para o primeiro estágio |

> Se não selecionar nenhum trabalho, os contatos são importados apenas como leads na base de contatos, sem entrar em nenhum funil.

***

#### Passo 10 — Confirmar a importação

1. Clique em **"Importar X contato(s)"**
2. Aguarde o processamento
3. O resultado exibe um resumo:

| Resultado               | Descrição                                                          |
| ----------------------- | ------------------------------------------------------------------ |
| **Novos leads criados** | Contatos que não existiam na plataforma                            |
| **Leads atualizados**   | Contatos já existentes — dados atualizados (nome, foto, empresa)   |
| **Ignorados**           | Contatos sem e-mail e sem telefone (não é possível identificá-los) |

***

### Perguntas Frequentes

**Posso importar os contatos mais de uma vez?** Sim. A plataforma detecta duplicatas pelo e-mail e não cria dois leads para o mesmo contato — apenas atualiza os dados.

**Meus contatos do Google são alterados quando eu importa?** Não. A integração é somente leitura — a Multiagents nunca modifica, cria ou exclui contatos na sua conta Google.

**O que são "Outros Contatos"?** O Google salva automaticamente endereços de e-mail de pessoas com quem você trocou mensagens. Esses aparecem como "Outros Contatos" e também são incluídos na listagem de importação.

**Posso conectar mais de uma conta Google?** Sim. Basta criar uma nova credencial em Configurações → Credenciais para cada conta. O modal de importação permite selecionar qual conta usar se houver mais de uma.

**Por que aparece o aviso "Google não verificou este app"?** Apps que não passaram pela verificação oficial do Google (um processo pago e burocrático) exibem esse aviso. Para uso interno ou com poucos usuários, é seguro prosseguir. A integração funciona normalmente.

***

### Solução de Problemas

| Problema                                        | Solução                                                                                |
| ----------------------------------------------- | -------------------------------------------------------------------------------------- |
| Botão "Importar do Google Contacts" não aparece | Verifique se a credencial está com status "Conectado" em Configurações → Credenciais   |
| Erro ao autorizar no Google                     | Confirme que seu e-mail foi adicionado como "usuário de teste" no Google Cloud Console |
| Erro 403 na importação                          | A People API não está ativada no projeto Google Cloud. Siga o Passo 2 novamente        |
| Nenhum contato aparece                          | A conta Google autorizada não tem contatos salvos, ou a busca está muito restrita      |
| Pop-up de autorização não abre                  | Permita pop-ups para o domínio da Multiagents no seu navegador                         |
