> For the complete documentation index, see [llms.txt](https://docs.sprinthub.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sprinthub.com/topicos/integracoes/integracao-google-ads-e-gmail/conectar-o-gmail-em-tempo-real-pub-sub.md).

# Conectar o Gmail em tempo real (Pub/Sub)

Este guia mostra, **tela por tela**, como configurar o Google Cloud Pub/Sub para o SprintHub receber e-mails do Gmail em **tempo real** no SAC360 (segundos), em vez de esperar a sincronização periódica via IMAP (1–5 min).

> As telas foram capturadas percorrendo o processo real do zero (projeto novo). Os nomes de projeto/tópico/conta usados aqui são exemplos — troque pelos seus.

**Resumo do que será criado no Google Cloud:**

| Recurso           | Exemplo neste guia                                                     |
| ----------------- | ---------------------------------------------------------------------- |
| Projeto           | `sprinthub-gmail-pubsub`                                               |
| Conta de serviço  | `sprinthub-pubsub-push@sprinthub-gmail-pubsub.iam.gserviceaccount.com` |
| Tópico Pub/Sub    | `projects/sprinthub-gmail-pubsub/topics/gmail-notifications`           |
| Assinatura (push) | `gmail-notifications-sub`                                              |

Ao final, dois valores são levados para o SprintHub: o **nome do tópico** e a **URL do webhook** (esta última já vem pronta na tela de configuração da integração).

***

### Pré-requisitos

* Conta Google com acesso ao [Google Cloud Console](https://console.cloud.google.com/).
* Cartão de crédito cadastrado no Google Cloud (exigência do Google; o uso fica dentro do free tier — na prática, grátis).
* A **URL do webhook** da sua instância SprintHub, que aparece na própria tela de configuração da integração Gmail (algo como `https://sprinthub-api-XXXX.sprinthub.app/email/webhook/gmail`). O caminho `/email/webhook/gmail` é fixo.

***

### Passo 1 — Acessar o console e fazer login

Acesse <https://console.cloud.google.com/> e faça login com sua conta Google.

<figure><img src="/files/vOwMIu5tbiCL3Bdb0muH" alt=""><figcaption></figcaption></figure>

***

### Passo 2 — Criar (ou selecionar) o projeto

1. Clique no **seletor de projetos** no topo (ao lado de "Google Cloud").

<figure><img src="/files/yymAfUO30QyquF47MMAV" alt=""><figcaption></figcaption></figure>

2. Clique em **Novo projeto**, dê um nome (ex.: `sprinthub-gmail-pubsub`) e clique em **Criar**.

<figure><img src="/files/AxWqt1Is0akQC1YVukPE" alt=""><figcaption></figcaption></figure>

3. Aguarde a criação (\~30s) e **selecione o projeto recém-criado** no seletor de projetos.

> Projeto recém-criado pode levar alguns segundos até liberar o acesso (IAM). Se aparecer "Você precisa de acesso adicional", aguarde um instante e recarregue.

***

### Passo 3 — Criar a conta de serviço

1. Na **barra de pesquisa** do topo, digite `contas de serviço` e clique no resultado **Contas de serviço** (IAM e admin).

<figure><img src="/files/cLB6NyOoWwC6wtzOHPXV" alt=""><figcaption></figcaption></figure>

2. Na página de Contas de serviço, clique em **Criar conta de serviço**.

<figure><img src="/files/Z7uU91SBqJvOWL4gb4DI" alt=""><figcaption></figcaption></figure>

3. Preencha o **Nome da conta de serviço** (ex.: `sprinthub-pubsub-push`) — o ID e o e-mail são gerados automaticamente. As etapas de permissão são opcionais.

<figure><img src="/files/cxKA0Rk0wugsOmwXQ5Hh" alt=""><figcaption></figcaption></figure>

4. Clique em **Criar e fechar**. A conta aparece na lista.

<figure><img src="/files/yjGN1w8qP9XeEIwdSIQS" alt=""><figcaption></figcaption></figure>

> Guarde o e-mail da conta de serviço — ele será selecionado na assinatura push (Passo 6). Ex.: `sprinthub-pubsub-push@sprinthub-gmail-pubsub.iam.gserviceaccount.com`.

***

### Passo 4 — Criar o tópico Pub/Sub

1. Na **barra de pesquisa**, digite `pub/sub` e clique no produto **Pub/Sub**.

<figure><img src="/files/z4F2oNIAa292KUhMdsC2" alt=""><figcaption></figcaption></figure>

> Na primeira visita, a API do Cloud Pub/Sub é ativada automaticamente para o projeto.

2. Na lista de Tópicos, clique em **Criar tópico**.

<figure><img src="/files/VU04QMQVx37kSPL3TwWO" alt=""><figcaption></figcaption></figure>

3. Defina o **ID do tópico** (ex.: `gmail-notifications`). **Não precisa alterar mais nada** — deixe a caixa "Adicione uma assinatura padrão" marcada (ela cria a assinatura que vamos editar no Passo 6). Clique em **Criar**.

<figure><img src="/files/5Dszb4JhkU2OsfvVDd8M" alt=""><figcaption></figcaption></figure>

4. O tópico é criado com uma assinatura padrão (`gmail-notifications-sub`).

<figure><img src="/files/1JUfgQWUbj4lwxVioSeD" alt=""><figcaption></figcaption></figure>

***

### Passo 5 — Autorizar o Gmail a publicar no tópico

O Gmail publica as notificações no tópico usando um agente de serviço fixo do Google. É preciso dar permissão a ele.

1. Ainda na página do tópico, no painel de permissões à direita, clique em **Adicionar principal**.
2. Em **Novos membros**, cole exatamente:

   ```
   gmail-api-push@system.gserviceaccount.com
   ```
3. Em **Atribuir papéis**, selecione o papel **Editor** (se precisar, pesquise por "editor" no seletor de papéis).

<figure><img src="/files/B4DhAGUyZZcSG4HVMDmG" alt=""><figcaption></figcaption></figure>

4. Clique em **Salvar**.

<figure><img src="/files/KcEAen8T7DfObivkDNFm" alt=""><figcaption></figcaption></figure>

> Sem esse passo, ao ativar o tempo real aparece o erro `User not authorized to publish to topic`.

***

### Passo 6 — Configurar a assinatura como Push

A assinatura é o que transforma cada mensagem do tópico em uma chamada HTTP para o SprintHub. Vamos **editar a assinatura padrão** criada junto com o tópico (se ela não existir, clique em **Criar assinatura** no tópico).

1. Abra a assinatura `gmail-notifications-sub` e clique em **Editar**.
2. Em **Tipo de envio**, selecione **Push**.
3. Em **URL do endpoint**, cole a URL do webhook que aparece na tela de configuração da integração no SprintHub:

   ```
   https://sprinthub-api-XXXX.sprinthub.app/email/webhook/gmail
   ```
4. Marque **Ativar a autenticação** e, em **Conta de serviço**, selecione a conta criada no Passo 3 (`sprinthub-pubsub-push@...`). O campo **Público** pode ficar em branco.

<figure><img src="/files/zxV6YHO11hj3ASENBxp1" alt=""><figcaption></figcaption></figure>

5. Clique em **Atualizar**.

<figure><img src="/files/8ZIfovIe9IUkZutU3kOV" alt=""><figcaption></figcaption></figure>

> A URL precisa ser **HTTPS válido**. Como usamos autenticação por conta de serviço, não é necessário verificar o domínio no Google.

***

### Passo 7 — Copiar o nome do tópico

Volte para o tópico e copie o **Nome do tópico** completo (botão de copiar ao lado):

<pre><code><strong>projects/sprinthub-gmail-pubsub/topics/gmail-notifications
</strong></code></pre>

<figure><img src="/files/rYEplAytA2qKbUhHLBEk" alt=""><figcaption></figcaption></figure>

***

### Passo 8 — Colar no SprintHub e ativar o tempo real

Na SprintHub, vá em **Configurações → Integrações → conta Gmail → SAC 360**. A configuração de tempo real fica na seção **"Recebimento em tempo real (Pub/Sub)"**, no final do card do SAC 360 (só aparece com "Criar atendimentos automaticamente" ativado):

1. **Copie a URL do webhook** exibida ali (botão de copiar) — é a mesma usada no Passo 6.
2. Cole o nome do tópico no campo **Tópico Pub/Sub do Google**.
3. Ative o toggle **Receber em tempo real (Pub/Sub)**.

> Observações da tela:
>
> * O toggle **só habilita** com um Tópico Pub/Sub em formato válido (`projects/<projeto>/topics/<tópico>`).
> * Ao **salvar a integração sem um tópico válido**, o tempo real é **desativado automaticamente** (evita um estado inconsistente).

Pronto — a partir daqui, cada e-mail novo na conta Gmail gera um atendimento/mensagem no SAC360 em segundos, sem esperar a sincronização IMAP.

***

### Como validar que está funcionando

1. Envie um e-mail de teste para a conta Gmail conectada.
2. Em poucos segundos, deve aparecer o atendimento/mensagem no SAC360 (sem dar F5).
3. No Google Cloud Console: **Pub/Sub → Assinaturas → `gmail-notifications-sub` → Métricas** deve mostrar "Mensagens publicadas" e "Mensagens entregues" subindo.

Para depurar pelo lado do servidor, os logs do backend distinguem a rota de chegada (filtre por `email_attendance`):

```
[EmailAttendance] ⇢ ENTRADA source=pubsub topico=projects/.../topics/gmail-notifications conta=... messageId=...
[EmailAttendance] ⇢ ENTRADA source=imap  conta=... messageId=...
```

`source=pubsub` = chegou em tempo real; `source=imap` = chegou pela sincronização periódica.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.sprinthub.com/topicos/integracoes/integracao-google-ads-e-gmail/conectar-o-gmail-em-tempo-real-pub-sub.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.