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.
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.
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.
Acesso pela tela: sidebar lateral > módulo Mensageria > Configurações > tree interna Canais Integrados > Contas do Telegram.
Passo a passo para integrar
- Abra o onboarding de Telegram na Agilize.
- Clique em Integrar Telegram.
- Na janela de conexão, clique em Abrir Telegram.
- No Telegram, use a conta que será conectada ao atendimento.
- Na conversa com o bot, clique em Start ou Iniciar para enviar o código de pareamento.
- No app Telegram, abra Configurações > Telegram Business > Chatbots.
- Vincule o bot indicado pela Agilize.
- Mantenha habilitada a permissão Gerenciar Mensagens.
- Aguarde a confirmação enviada pelo bot.
- Volte para a Agilize e abra a conta criada em Contas do Telegram.
- Selecione o Fluxo Atendimento - ChatBot, se a conta usar automação inicial.
- Selecione o Departamento Padrão, se as conversas devem entrar em uma área específica.
- Ative Gerar Protocolo quando a operação exigir protocolo para esse canal.
- 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:
- Peça para outro usuário enviar uma mensagem privada para a conta Telegram conectada.
- Confirme se a conversa aparece na Agilize como canal Telegram.
- Verifique se o fluxo do bot executou, quando configurado.
- Responda pela Agilize e confirme se a mensagem chega no Telegram.
- Transfira ou conclua o atendimento, se esse for o processo da equipe.
- 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.
- Para definir o time que recebe conversas, veja Regras de roteamento e distribuição.
- Para revisar os demais canais, volte para Canais e integrações.