## Visão geral

As **Integrações** conectam a ConversaLabs ao resto do seu ecossistema. A partir da área de
integrações você ativa conexões prontas e cria pontos de extensão próprios:

- **Slack**: espelha conversas em um canal do Slack e responda de lá.
- **Dialogflow**: conecte um bot do Dialogflow para respostas automáticas.
- **Notion** e **Linear**: leve contexto da conversa para suas ferramentas de produtividade e
  desenvolvimento.
- **Shopify**: traga dados de pedidos/cliente da sua loja para o atendimento.
- **Chamadas de vídeo e voz (Cloudflare RealtimeKit)**: o atendente inicia uma chamada com o
  cliente dentro da própria conversa. Esta integração antes se chamava **Dyte** e passou a usar o
  Cloudflare RealtimeKit — as credenciais mudaram.
- **Provedores por credencial**: conecte tradução, vídeo, CRM, IA, voz e busca com chaves ou contas
  de serviço próprias.
- **Webhooks**: receba eventos da plataforma em um endpoint seu, em tempo real.
- **Aplicativos de painel (Dashboard Apps)**: incorpore uma aplicação web na conversa ou barra lateral
  da conta, com controles nativos de público, ordem e compatibilidade quando habilitados.
- **API**: automatize e integre via tokens de acesso.

## Pré-requisitos

- Perfil de **Administrador** ou papel nativo com a permissão **Gerenciar integrações** para configurar conexões da conta.
- Credenciais/contas das ferramentas que você vai conectar (por exemplo, workspace do Slack, projeto
  do Dialogflow, loja Shopify).
- Para webhooks/API: um endpoint acessível e/ou um token de acesso gerado na conta.
- Para **chamadas de vídeo/voz**: uma conta na Cloudflare com um aplicativo **RealtimeKit** criado e
  um token de API com permissão **Realtime Admin**. Conectar e desconectar essa integração pede o
  mesmo acesso das demais: **Administrador** ou papel nativo com **Gerenciar integrações**.
- Para verificar a assinatura dos **webhooks do Slack**: o *Signing Secret* do seu aplicativo Slack,
  aplicado na instalação (não na conta) — veja abaixo.

## Passo a passo

1. Abra a área de **Integrações** nas Configurações.
2. Escolha a integração desejada. Nos formulários por credencial, os atalhos acima dos campos já
   mostram o nome do provedor:
   - **Obter credenciais do _provedor_** abre a página oficial de chaves ou contas de serviço;
   - **Abrir console do _provedor_** abre a API ou console que precisa ser habilitado, quando houver;
   - **Ver documentação de configuração do _provedor_** abre o guia oficial correspondente.
3. Preencha os campos com dados do mesmo projeto/conta e conclua a criação.
4. Para **webhooks**, cadastre a URL do seu endpoint e selecione os eventos de interesse; valide o
   recebimento no seu sistema.
5. Para a **API**, gere um token de acesso (perfil/agente) e use-o nas chamadas autenticadas.
6. Teste a integração com uma conversa real antes de colocar em produção.

### Configurar chamadas de vídeo com o Cloudflare RealtimeKit

1. Na Cloudflare, crie (ou localize) o aplicativo **RealtimeKit** e anote o **ID do aplicativo**.
2. Anote também o **ID da conta** da Cloudflare e gere um **token de API** com permissão
   **Realtime Admin** para essa conta.
3. Na ConversaLabs, abra **Integrações** e escolha a integração de vídeo. Preencha os três campos:
   - **Cloudflare Account ID**
   - **RealtimeKit App ID**
   - **Cloudflare API Token**

   Nesta integração, os atalhos acima dos campos ainda levam às páginas do provedor anterior
   (`dev.dyte.io` e `docs.dyte.io`). Ignore-os: os três valores vêm do painel da Cloudflare.
4. Salve. A plataforma valida as credenciais na hora: confere se o token está ativo e se o
   **RealtimeKit App ID** existe naquela conta da Cloudflare. Se algo não bater, a conexão não é
   criada e a mensagem de erro indica exatamente qual campo revisar.
5. Abra uma conversa e inicie a chamada. A plataforma publica na conversa uma mensagem com o convite;
   quem participa usa **Clique aqui para entrar** e encerra com **Sair da sala**.

**Se você já usava a integração antiga (Dyte):** ela continua registrada, mas não consegue mais
abrir chamadas. Ao tentar iniciar uma reunião aparece a mensagem *"As credenciais do Cloudflare
RealtimeKit são obrigatórias. Exclua a integração existente do Dyte e crie-a novamente usando as
credenciais do Cloudflare RealtimeKit."* — o caminho é exatamente esse: **excluir a conexão antiga e
criar uma nova** com os três campos acima. A tela dessa integração oferece apenas **Conectar** e
**Desconectar**, então não há formulário para trocar os campos antigos (*organization ID* e
*API key*) no lugar.

### Ativar a verificação de assinatura dos webhooks do Slack

1. No painel do seu aplicativo Slack, copie o **Signing Secret**.
2. Aplique o valor na instalação, em uma destas formas:
   - no **Super Admin**, no grupo de configurações do Slack, no campo **Slack Signing Secret**; ou
   - na variável de ambiente `SLACK_SIGNING_SECRET` do servidor.
3. Reenvie um evento pelo Slack e confirme que a conversa continua chegando normalmente.

Enquanto o segredo **não** estiver configurado, a plataforma **não** recusa o webhook: ela apenas
registra um aviso no log e processa o evento — instalações antigas continuam funcionando sem
mudança. A verificação só passa a valer depois que você preenche o segredo, e é isso que protege o
endpoint contra chamadas forjadas.

## Configurações & opções

- **Conexões por autorização** (Slack, Shopify, etc.): seguem o login da ferramenta externa.
- **Conexões por chave/projeto** (Dialogflow, Google Translate, Cloudflare RealtimeKit, LeadSquared
  e provedores de IA/voz/busca): exigem credenciais do provedor.
- **Webhooks por evento**: você escolhe quais eventos quer receber.
- **Tokens de API**: trate-os como senhas; revogue se vazarem ou caírem em desuso.

### Campos do Cloudflare RealtimeKit

| Campo no formulário | Obrigatório | O que é | Fica visível depois de salvar |
|---|---|---|---|
| Cloudflare Account ID | Sim | ID da sua conta na Cloudflare | Sim |
| RealtimeKit App ID | Sim | ID do aplicativo RealtimeKit dentro dessa conta | Sim |
| Cloudflare API Token | Sim | Token de API com permissão **Realtime Admin** | Não |

Os três campos são obrigatórios e o formulário não aceita nenhum outro campo além deles. A coluna
"Fica visível depois de salvar" vale para administradores; o token de API nunca é devolvido pela
plataforma a ninguém. Como a integração só tem **Conectar** e **Desconectar**, trocar qualquer um dos
três valores significa desconectar e conectar de novo.

### Onde vive o Slack Signing Secret

O segredo é da **instalação**, não de uma conta. A plataforma procura o valor nesta ordem:

1. a configuração de instalação **Slack Signing Secret** (Super Admin);
2. a variável de ambiente `SLACK_SIGNING_SECRET`.

Se o campo do painel existir mas estiver **vazio**, a variável de ambiente ainda é usada — então uma
instalação que já configurava o segredo pelo ambiente continua protegida depois da atualização.

A verificação usa a assinatura enviada pelo Slack nos cabeçalhos `X-Slack-Signature` e
`X-Slack-Request-Timestamp`, com HMAC-SHA256 sobre o corpo bruto da requisição. Um webhook é
recusado com **401** quando falta um desses cabeçalhos, quando o horário da requisição está a mais
de **5 minutos** de distância do relógio do servidor, ou quando a assinatura não confere.

## Casos de uso

- Notificar um canal do Slack quando chega uma nova conversa.
- Triagem automática com um bot de Dialogflow antes de chegar ao agente.
- Criar um item no Linear a partir de um bug relatado pelo cliente.
- Mostrar dados do pedido da Shopify direto na tela da conversa.
- Sincronizar eventos com seu CRM ou ERP via webhooks.
- Resolver na hora um atendimento complexo abrindo uma chamada de vídeo com o cliente, sem tirá-lo
  do canal em que ele já estava.
- Blindar o endpoint de webhooks do Slack contra chamadas forjadas ativando o *signing secret*.

## Dicas, limites e boas práticas

- Comece por **uma** integração, valide o fluxo e só então adicione outras.
- Para webhooks, implemente **idempotência** e responda rápido (processe em segundo plano).
- Guarde tokens em variáveis de ambiente do seu sistema — nunca no código-fonte público.
- Revise integrações e tokens periodicamente; remova o que não é mais usado.
- No token da Cloudflare, use o **menor escopo possível** que ainda inclua **Realtime Admin**: é a
  permissão que a validação e as chamadas exigem.
- Confirme os três campos do RealtimeKit **na mesma conta** da Cloudflare. Um App ID válido em outra
  conta é recusado com a mensagem de aplicativo não encontrado.
- A janela de 5 minutos da assinatura do Slack depende do relógio do servidor: mantenha a sincronia
  de horário (NTP) em dia, ou webhooks legítimos passam a ser recusados.
- Ao rotacionar o Signing Secret no Slack, atualize o valor na plataforma na mesma janela — entre a
  troca e a atualização, os eventos são recusados.

## Solução de problemas

- **A integração não conecta**: confira credenciais/permissões e tente reautorizar. Para Shopify, consulte o [guia dedicado](/hc/ajuda/articles/administration-shopify-pt-br).
- **O webhook não chega**: verifique se a URL é pública, responde com sucesso (2xx) e está nos
  eventos certos.
- **Erro 401 na API**: o token está incorreto, expirado ou foi revogado — gere um novo.
- **Não vejo a integração desejada**: ela pode depender do plano ou de uma habilitação específica.
- **"O token da API do Cloudflare é inválido ou está inativo"**: o token não passou na verificação da
  Cloudflare. Crie um novo token com permissões de **Realtime Admin**.
- **"O ID da conta do Cloudflare é inválido ou o token da API não possui acesso de Realtime Admin a
  esta conta"**: o token é válido, mas não alcança essa conta. Revise o ID da conta e o escopo do
  token.
- **"O ID do aplicativo RealtimeKit não foi encontrado nesta conta do Cloudflare"**: o aplicativo não
  existe nessa conta. Confira se copiou o App ID do ambiente certo.
- **"Não foi possível verificar as credenciais do Cloudflare RealtimeKit no momento"**: a Cloudflare
  não respondeu a tempo ou devolveu erro temporário. Tente salvar de novo.
- **A chamada de vídeo não abre e pede credenciais do RealtimeKit**: a conexão ainda é a antiga do
  Dyte. Exclua-a e crie a integração novamente com os três campos do Cloudflare RealtimeKit.
- **Os eventos do Slack pararam com 401**: o segredo configurado não corresponde ao do aplicativo
  Slack, ou o relógio do servidor está fora da janela de 5 minutos. Compare o Signing Secret e
  verifique a hora do servidor.

## Veja também

- [Dashboard Apps: superfícies nativas, público e segurança](/hc/ajuda/articles/administration-dashboard-apps-native-surfaces-pt-br)
- [Custom Scripts: injetar JS/CSS](/hc/ajuda/articles/administration-custom-scripts-pt-br)
- [Papéis personalizados e governança (RBAC)](/hc/ajuda/articles/administration-custom-roles-governanca-rbac-pt-br)
- [Logs de auditoria](/hc/ajuda/articles/administration-auditoria-pt-br)
- [Visão geral de Administração](/hc/ajuda/articles/administration-overview-pt-br)