Integrações: provedores, credenciais, OAuth, webhooks e API

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

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.
• 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
• Custom Scripts: injetar JS/CSS
• Papéis personalizados e governança (RBAC)
• Logs de auditoria
• Visão geral de Administração