# Agilize Docs para IA - Página atual Este arquivo contém uma versão focada e legível por IA da página aberta na documentação pública da Agilize. Use esta versão quando a pergunta do usuário estiver restrita ao documento atual. Última geração: 2026-07-08T14:30:45.658Z ## Página - Título: Integração com Telegram - URL humana: https://agilize.app/docs/configuracao/canais-whatsapp-integracoes/integracao-telegram - Leitura completa para IA: https://agilize.app/docs/llms.txt - Descrição: Como conectar uma conta Telegram à Agilize para receber mensagens, usar fluxos do bot e responder com a equipe de atendimento. ## Seções - Antes de começar - Onde acessar - Passo a passo para integrar - Configurações do canal - Como validar - Premissas e limites da integração - Problemas comuns - Boas práticas ## Conteúdo da página # Integração com Telegram A integração com Telegram permite conectar uma conta Telegram à Agilize para receber mensagens privadas de clientes, executar fluxos do bot, distribuir atendimento e responder pela plataforma com histórico centralizado. Use este guia para ativar o canal quando sua empresa quer tratar conversas do Telegram junto aos demais canais de atendimento. --- title: "Como a integração funciona" caption: "O bot conecta a conta Telegram à Agilize. O atendimento acontece dentro da estrutura de canais, fluxos e equipe." definition: | flowchart LR A[Integrar Telegram na Agilize] --> B[Abrir o bot no Telegram] B --> C[Vincular o bot na conta Telegram] C --> D[Habilitar Gerenciar Mensagens] D --> E[Configurar fluxo e departamento] E --> F[Receber e responder clientes] --- ## Antes de começar Confirme estes pré-requisitos: - você tem acesso administrativo à Agilize para configurar canais; - a conta Telegram que será conectada está acessível no app Telegram; - a equipe já sabe qual fluxo de atendimento e qual departamento serão usados para esse canal; - o fluxo do bot já foi criado, se a entrada do Telegram deve ter triagem automática; - a conta Telegram será usada para atendimento receptivo em conversas privadas com clientes. O bot informado pela Agilize é usado para conectar a conta Telegram. Ele não é o canal de atendimento principal para seus clientes; os clientes devem conversar com a conta Telegram conectada da empresa. ## Onde acessar Para iniciar a integração, acesse [https://my.agilize.app/messenger/telegram/onboarding](https://my.agilize.app/messenger/telegram/onboarding). Acesso pela tela: abra o onboarding da plataforma, vá em **Canais de Comunicação** e clique em **Integrar Telegram**. Para revisar contas já conectadas, acesse [https://my.agilize.app/messenger/telegram/channel](https://my.agilize.app/messenger/telegram/channel). Acesso pela tela: sidebar lateral > módulo **Mensageria** > **Configurações** > tree interna **Canais Integrados** > **Contas do Telegram**. ## Passo a passo para integrar 1. Abra o onboarding de Telegram na Agilize. 2. Clique em **Integrar Telegram**. 3. Na janela de conexão, clique em **Abrir Telegram**. 4. No Telegram, use a conta que será conectada ao atendimento. 5. Na conversa com o bot, clique em **Start** ou **Iniciar** para enviar o código de pareamento. 6. No app Telegram, abra **Configurações > Telegram Business > Chatbots**. 7. Vincule o bot indicado pela Agilize. 8. Mantenha habilitada a permissão **Gerenciar Mensagens**. 9. Aguarde a confirmação enviada pelo bot. 10. Volte para a Agilize e abra a conta criada em **Contas do Telegram**. 11. Selecione o **Fluxo Atendimento - ChatBot**, se a conta usar automação inicial. 12. Selecione o **Departamento Padrão**, se as conversas devem entrar em uma área específica. 13. Ative **Gerar Protocolo** quando a operação exigir protocolo para esse canal. 14. Salve o cadastro. Se a confirmação chegar sem permissão para responder, revise no Telegram se a permissão **Gerenciar Mensagens** ficou ativa para o bot. ## Configurações do canal Depois que a conta aparece na lista de **Contas do Telegram**, revise estas configurações: | Campo | Como usar | | --- | --- | | Conta Telegram | Nome da conta conectada. Campo informativo. | | Usuário Telegram | Username da conta, quando disponível. Campo informativo. | | Fluxo Atendimento - ChatBot | Fluxo executado quando a conversa entra pelo Telegram. | | Departamento Padrão | Departamento associado às salas criadas por essa conta. | | Gerar Protocolo | Cria protocolo de atendimento para conversas do canal. | Na visualização do canal, use o diagnóstico para revisar se a conexão está ativa e pronta para atendimento. Se a tela indicar divergência, sincronize o canal antes de colocá-lo em produção. ## Como validar Faça um teste controlado antes de divulgar a conta: 1. Peça para outro usuário enviar uma mensagem privada para a conta Telegram conectada. 2. Confirme se a conversa aparece na Agilize como canal **Telegram**. 3. Verifique se o fluxo do bot executou, quando configurado. 4. Responda pela Agilize e confirme se a mensagem chega no Telegram. 5. Transfira ou conclua o atendimento, se esse for o processo da equipe. 6. Revise se o departamento, histórico e protocolo ficaram corretos. No uso diário, conversas distribuídas devem chegar ao Flow do usuário. Use telas de monitoramento apenas para supervisão, auditoria e exceções. ## Premissas e limites da integração Considere estas regras ao operar o Telegram: | Tema | Premissa | | --- | --- | | Tipo de conversa | A integração é voltada a conversas privadas entre cliente e conta Telegram conectada. Grupos e canais não fazem parte do escopo operacional inicial. | | Bot como conexão | O bot serve para parear a conta e permitir envio e recebimento pela Agilize. Ele não substitui a conta Telegram da empresa. | | Permissão de resposta | Para responder pela Agilize, a permissão **Gerenciar Mensagens** precisa estar ativa no Telegram. | | Janela de resposta | A resposta pela plataforma depende de conversa privada com mensagem recente do cliente. Se a sessão estiver fechada, aguarde o cliente enviar uma nova mensagem. | | Dados do cliente | O Telegram pode informar nome, sobrenome, username e dados da conversa usados para manter o histórico. Não conte com telefone do cliente como dado obrigatório desse canal. | | Plano da conta | A integração depende da conta conectada e das permissões concedidas no Telegram. A tela pode indicar quando a conta ainda não tem permissão para responder. | | Reações | Reações nativas do Telegram em conversas privadas ainda não devem ser usadas como sinal confiável na timeline ou em fluxos. | | Mídias e arquivos | Mídias recebidas dependem das permissões e limites do Telegram. Arquivos muito grandes podem não ficar disponíveis para download pela plataforma. | ## Problemas comuns | Sintoma | O que verificar | | --- | --- | | O link direto não aparece | Use a opção de copiar o link, tente abrir pelo app Telegram ou acione o suporte se a opção de abertura não estiver disponível. | | O bot não aparece como opção de Chatbot | Confirme se você está usando a conta Telegram correta e se o bot indicado pela Agilize foi aberto pelo link de pareamento. | | A conexão foi criada, mas não responde | Revise se **Gerenciar Mensagens** está habilitado em **Configurações > Telegram Business > Chatbots**. | | A conversa não aparece na Agilize | Envie uma mensagem privada para a conta conectada e confirme se o canal está ativo em **Contas do Telegram**. | | A resposta fica bloqueada | A sessão pode estar fechada. Peça para o cliente enviar uma nova mensagem privada para reabrir a conversa. | | O cliente não tem telefone no cadastro | Esse é um comportamento esperado do Telegram. Use nome, username e histórico para qualificação, e solicite telefone no fluxo quando ele for necessário. | ## Boas práticas - Use um nome de conta Telegram fácil de reconhecer pelo cliente. - Configure fluxo e departamento antes de divulgar o canal. - Teste entrada, resposta, transferência e conclusão com uma conversa real controlada. - Solicite telefone ou e-mail no fluxo quando esses dados forem necessários para CRM. - Evite usar o Telegram para disparos em massa sem orientação prévia sobre regras do canal e consentimento. - Revise periodicamente se a permissão **Gerenciar Mensagens** continua ativa. ## Próximos passos - Para desenhar a triagem automática, veja [Fluxos do bot](/docs/configuracao/fluxos-automacoes/fluxos-do-bot). - Para definir o time que recebe conversas, veja [Regras de roteamento e distribuição](/docs/configuracao/roteamento-distribuicao/regras-de-roteamento-e-distribuicao). - Para revisar os demais canais, volte para [Canais e integrações](/docs/configuracao/canais-whatsapp-integracoes/canais-e-integracoes).