Integrando Telegram ao Rocket.Chat

Recentemente já mostramos como realizar a integração manual de um sistema de chat com o Rocket utilizando o Omnichannel. Nesse post, inclusive, citamos os recursos que já foram desenvolvidos pela equipe do Rocket e disponibilizados via Marketplace.

E hoje vamos conhecer um desses recursos: Integração com o Telegram. Vamos entender quais configurações devem ser realizadas no Rocket e no Telegram para que isso seja possível. Ao término, você terá uma integração entre o Telegram e Rocket funcional e poderá pôr em prática na sua empresa.

Requisitos da integração

Sim, eu disse que isso seria simples. Mas existem alguns requisitos além das configurações que necessitam ser aplicados. Mas não se preocupe, pois vou passar por todos os passos até tudo ficar funcional.

Dentre os requisitos, temos:

• HTTPS – É necessário que o seu Rocket esteja sendo executado e acessível via protocolo seguro da web. Isso é um requisito do Telegram para que a integração funcione, além de ser um recurso mínimo de segurança para os seus usuários. E claro, ele deve estar disponível na internet para que o Telegram se comunique. Para resolver esse problema, mesmo no ambiente local, vamos nos auxiliar dos recursos do ngrok. Não se preocupe que falarei mais sobre no momento de configura-lo.
• Rocket.Chat Cloud – Esse é um recurso necessário para baixar aplicativos na loja do Rocket. A sua instalação deve estar logada e sincronizada com a Cloud do Rocket. Essa configuração não demanda de nenhum pagamento ou algo do tipo. É simples e rápido e vou mostrar como realizar.
• Bot do Telegram – Será necessário criar um bot no Telegram utilizando os recursos que a plataforma disponibiliza. Esse bot será acessível como se fosse um usuário comum, e seus clientes irão falar com ele para ser atendido.

Esses são os requisitos que dependem de algo externo. Além disso, claro, vamos precisar de uma instalação do Rocket em execução com o Omnichannel habilitado e pelo menos um departamento criado. Será nesse departamento que, inicialmente, todos os contatos serão inseridos e terão uma sala criada.

Vamos então começar a atender os requisitos.

Instalando e configurando o ngrok

O ngrok é um aplicativo muito útil no dia a dia de desenvolvedores. Se você ainda não conhece ou não utiliza, chegou a hora!

Basicamente o ngrok permite que uma aplicação que esteja rodando em sua máquina seja acessível pela internet. Além disso, permite que essa comunicação seja feita via HTTPS sem você precisar comprar certificado, instalar Let’s Encrypt ou qualquer coisa do tipo. Tudo isso sem precisar alterar o firewall da sua máquina ou redirecionar portas no seu roteador!

Ele funciona basicamente da seguinte forma: você inicia via linha de comando informando qual porta ele vai disponibilizar. A partir disso, ele vai criar um túnel entre a sua máquina e os servidores da plataforma e, com isso, a sua aplicação se torna disponível. Ele irá fornecer uma URL pública que poderá ser aberta de qualquer lugar para acessar a sua aplicação. Além disso, é fornecido um endereço local para que você acompanhe todas as requisições realizadas. Tudo isso de graça!

Você pode ter uma assinatura na plataforma. Com isso terá alguns recursos extras, como domínios personalizados e aceitar mais conexões por minuto. Porém, para nossos testes, a versão gratuita já basta.

Vamos então começar a configuração! Primeiramente acesse a dashboard do aplicativo e crie sua conta caso ainda não possua, em seguida realize o login.

Assim que realizar o seu login, você será redirecionado para uma tela que já tem todos os passos para realizar download do aplicativo e configurá-lo. Ele não é instalado, apenas é realizado o download de um executável. Baixe a versão referente ao SO que esteja utilizando e extraia o executável. Você pode colocá-lo na pasta de sua preferência. Seria interessante adicionar a sua localização nas variáveis do sistema para que possa ser executado a partir de qualquer diretório.

Após isso você precisa fornecer seu token de acesso para que ele funcione sem limite de tempo de uso. Nessa tela deverá ser disponibilizado o comando com o seu token, algo como:

ngrok authtoken xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Basta executar esse comando no seu terminal. Tudo referente ao ngrok está pronto. Você pode dar uma olhada na documentação para conhecer mais suas opções e configurações, mas vamos ficar no mais simples.

Vamos disponibilizar a porta 3000 utilizada pelo Rocket com o comando:

ngrok http 3000

Isso já basta para o Rocket ser acessível via internet. Mas ainda não temos ele rodando, certo? Vamos resolver isso agora.

Preparando o ambiente do Rocket

Como não é o foco a parte de infraestrutura, vamos novamente utilizar o Docker nesse processo. Já disponibilizei anteriormente um docker-compose. Você pode visualizar ele aqui. Ele está configurado com tudo que precisa, já criando um usuário administrador (Login rocket e senha PZxs7wsHWEJLP98z).

Mas para o uso desse post, temos que realizar uma alteração nesse arquivo para facilitar nossa vida. Abrindo-o, teremos que alterar a variável de ambiente nomeada ROOT_URL. Vamos colocar nesse endereço a URL que o ngrok nos disponibilizou. Você já pode ter o ngrok rodando antes da aplicação, isso não causará problemas.

Após realizar essa alteração, basta subir o projeto com o comando:

docker-compose up

Durante a configuração, é importante que você marque a opção de se registrar na Cloud e aceite os termos de uso. É possível ajustar isso posteriormente, porém nesse momento está mais simples.

Um ponto importante a se destacar é que como estamos utilizando a versão gratuita do ngrok, sempre que iniciamos seu uso ele irá disponibilizar uma URL diferente. Então tenha atenção a isso. Se precisar parar o Docker, será necessário alterar novamente o docker-compose e provavelmente algumas configurações dentro do Rocket.

Use esse ambiente apenas para testes de integração. Em um ambiente produtivo você não irá utilizar o ngrok, logo, não ocorrerão esses problemas.

Conectando na Cloud

Você já deve ter percebido que no topo do Rocket está uma mensagem informando que o registro na Cloud está pendente.

Vamos então começar essa ativação. Acesso e menu e vá em Administração.

Na tela de administração, procure por Serviços de Ligação e selecione. Após, clique em Clique aqui para registrar seu workspace.

Ocorrerá um erro referente à ativação, mas isso se deve a estarmos em um ambiente local e utilizarmos para o registro do usuário administrador um e-mail inexistente. Ele não recebe o e-mail de ativação.

Vamos realizar o registro manual. Basta clicar em Registre manualmente.

Na tela aberta, copie o código gerado e clique em Próximo.

Deixe essa tela aberta e vá para outra aba do navegador.

Acesse o endereço da Cloud da Rocket: cloud.rocket.chat. Crie uma conta, caso não possua uma, e em seguida faça login.

Após o login, será aberta a área dos seus Workspaces. Vamos começar a registrar o nosso clicando em Register self-managed.

Na tela aberta, selecione No internet access e clique em Continue.

Cole o código que foi copiado do Rocket e clique em Continue.

Será gerado um novo código. Copie, pois ele será utilizado no Rocket.

Essa aba da Cloud já pode ser fechada.

Volte para o Rocket e cole o código fornecido pelo Rocket Cloud. Em seguida, clique em Finish Registration.

Após isso, seu Rocket já está conectado com a Cloud. Agora precisamos realizar login para conseguir acesso à loja.

Basta clicar em Login do Rocket.Chat Cloud.

Será redirecionado para uma tela do Cloud solicitando autorização. Caso você não esteja logado, será necessário realizar login.

Clique em Authorize para autorizar o login com sua conta.

Agora você será redirecionado novamente para o Rocket e poderá visualizar que está logado com a Cloud e com o Workspace conectado.

Caso ainda não apareça que você está logado, tente realizar o processo novamente.

Com isso, já estamos com tudo certo referente à Cloud. Agora podemos continuar com mais algumas configurações.

Configurando o Omnichannel

Primeiramente, precisamos habilitar o Omnichannel, visto que com a instalação nova ele vem desabilitado.

Para isso, é necessário acessar a Administração, procurar pelo menu Omnichannel e marcar a opção Omnichannel habilitado. Não esqueça de salvar.

Agora que temos o Omnichannel habilitado, é necessário adicionar um agente e criar um departamento. Todos os atendimentos vindos do Telegram serão atribuídos a esse departamento.

Para realizar essa ação, vamos acessar o menu do Omnichannel.

Agora vamos procurar pelo menu Agentes e acessá-lo. Na tela aberta, selecione o usuário que deseja incluir como agente e clique em Adicionar.

Nessa mesma área, procure pelo menu Departamentos e selecione. Então, clique em Novo para adicionar um.

Na tela de criação, você precisa marcá-lo como ativado, fornecer um nome e um e-mail para o departamento. Além disso, adicione o agente anteriormente criado como membro. Você pode adicionar quantos agentes desejar.

No final, cliquem em Salvar para criar o departamento.

Após esses passos, tudo referente ao Omnichannel já está preparado. Vamos então iniciar as configurações do Telegram.

Criando o bot no Telegram

A API de integração do Telegram não funciona com uma conta comum, necessitando que um bot seja criado. Porém, esse bot não significa que terá automatizações, fluxos de atendimento etc.

Simplesmente é um usuário de bot para ser utilizado em integrações. Você pode interligar ele a um sistema de bot que irá responder tudo de forma automática e tomar decisões, mas esse não será nosso caso.

Iremos gerar esse bot para ser o meio de comunicação entre os clientes no Telegram e o Rocket. Quando alguém enviar uma mensagem para ele, nenhuma resposta automática será dada. Na realidade, será aberta uma sala no Omnichannel e tudo dependerá de respostas manuais de um agente.

Depois das explicações, vamos então começar! Nesse caso, espero que você já tenha uma conta criada no Telegram e esteja com acesso a ela.

Dentro do Telegram, procure por @BotFather

Esse usuário é um bot disponibilizado pelo Telegram responsável pelo gerenciamento de seus bots. Preste bem atenção ao usuário, pois há alguns com nomes parecidos. O oficial possui sinal de verificado no nome.

Encontrando o usuário correto, pode clicar sobre ele para iniciar uma conversa.

Ao abrir a conversa com esse usuário pela primeira vez, serão abertas algumas informações e links da documentação.

Para iniciar a conversa, você precisa clicar sobre o botão Começar.

Após isso, será enviar o comando /start. Isso é uma característica do Telegram. Sempre que você conversar pela primeira vez com um bot, ele solicita essa ação.

Ele irá exibir uma lista de comandos que possui com suas respectivas descrições.

Para começarmos a criar nosso bot, basta enviar uma mensagem com o texto /newbot.

Ele solicitará um nome para esse bot. Você pode colocar o nome que desejar. Esse será o nome exibido enquanto os seus clientes conversam com os agentes.

Basta inserir o nome desejado e enviar a mensagem.

Em seguida, será solicitado um usuário para esse bot. Esse usuário será o valor que os clientes irão procurar para encontrá-lo.

O nome de usuário pode conter letras e números, porém não pode começar com números. Além disso, no final deve ter a palavra bot. Ela pode tanto ser inserida diretamente, como MeuBot, ou separada por um underline, como em meu_bot.

Digite o valor desejado e em seguida envie a mensagem.

Após isso, seu bot já está criado! Ele envia algumas informações sobre o bot, e o mais importante, o token de acesso para uso do bot criado.

Guarde muito bem esse token. Ele será utilizado em seguida em configurações do Rocket. Além disso, se alguém conseguir acesso a esse token, poderá realizar qualquer ação com seu bot.

Você ainda pode editar esse bot, adicionando uma imagem, descrição, um sobre e alterar seu nome. O nome de usuário não pode ser alterado.

Agora que temos o bot criado, estamos prontos para integrá-lo ao Rocket.

Instalando aplicativo e configurando a integração

Vamos voltar para o Rocket para finalizar a integração. Acesse o menu de Administração.

Agora procure pelo menu Marketplace. Ao abri-lo pela primeira vez, será solicitado que sejam habilitados os Apps.

Basta clicar no botão Habilitar.

Agora o Marketplace será carregado. Procure por um aplicativo com o nome Telegram. Após encontrá-lo, clique em Instalar.

Tenha atenção ao nome do aplicativo e quem disponibiliza (by Rocket.Chat), pois, no futuro, outros aplicativos com nomes semelhantes podem aparecer.

Será solicitado que você aceite os termos de uso. Marque a caixa de seleção, em seguida clique em Get.

Agora o aplicativo já está instalado! Para acessá-lo, procure pelo menu Apps e selecione-o. Clique, então, sobre o aplicativo Telegram.

Será aberta a tela de configurações do aplicativo. Nela, teremos alguns ajustes possíveis. Vamos entender cada um deles:

• Token do usuário Bot no Telegram -Lembra do token que eu disse para guardar? Então, chegou a hora de utilizá-lo. Basta inserir nesse campo o token que você recebeu ao criar o bot.

• Nome ou ID do Departamento Padrão -Aqui você deve inserir o nome do departamento do Omnichannel que irá receber os clientes vindos via Telegram. No meu caso, eu criei um com o nome “Inicio Telegram”.

• Mensagem de Serviço indisponível -Essa mensagem será exibida quando um cliente tentar enviar uma mensagem e não houver agentes onlines no departamento. Ou quando estiver fora do horário de serviço, se configurado. Coloque o texto conforme desejar.

• Mensagem de Boas Vindas -Essa mensagem deve ser enviada quando o cliente entrar pela primeira vez no chat. Comigo não funcionou em nenhum momento.

• Mensagem de Encerramento -Essa mensagem será enviada quando o agente finalizar o atendimento, fechando a sala.

• Nome de Exibição do Agente -Como o nome do agente será informado ao cliente. Como ele estará conversando com uma conta de bot, sempre será exibido o nome do bot na conversa. Com essa opção, você pode fazer com que no início de cada mensagem seja inserido o nome do agente, seu usuário, ou nada.

• Upload de Arquivos Habilitado -Se você deseja receber arquivos de seus clientes (imagens, áudios, vídeos etc.), precisa marcar essa opção. Além disso, pode definir um tamanho máximo desses arquivos, ou deixar ilimitado colocando o valor -1.
  

• Tipo de Arquivos Permitidos -Defina quais tipos de arquivos os clientes podem enviar. Nesse campo é necessário informar os media type (mime type) dos arquivos que deseja receber. Ou deixe em branco para receber qualquer tipo.

Após ajustar as configurações, volte até o topo da página e clique em Salvar alterações. Após isso, clique sobre o menu de opções (três bolinhas) e desabilite o aplicativo.

Será questionado se deseja prosseguir com a desativação. Clique em Sim.

Agora você pode ir ao mesmo menu de opção e habilitar novamente o aplicativo. Essa ação é necessária, pois é no momento de ativação do aplicativo que ele irá realizar ajustes no bot, criando o Webhook de resposta necessário para receber informações do Telegram.

Com isso, já temos nossa integração funcional. Bora testar!

Testes e considerações

Antes de começar a testar, tenha certeza de que pelo menos um usuário que adicionou ao departamento esteja online no Rocket e no Omnichannel.

Agora vamos voltar para o Telegram e abrir a conversa com o bot que criamos. Ao clicar em Começar, uma nova sala já deve ser aberta no Rocket e atribuída a um atendente.

Vamos enviar uma mensagem para visualizarmos como chega.

Voltando ao Rocket, você já deve ter recebido a nova sala. Ao clicar nela, será aberto o chat com o cliente.

Pode interagir com essa sala como quiser. É uma sala comum do Omnichannel. Poderá enviar mensagens de texto, áudio, vídeo e anexos.

Como havíamos configurado para adicionar o nome do atendente nas mensagens, está sendo exibido [Administrador] – a cada mensagem enviada.

Ao final, o agente poderá encerrar a conversa. A sala irá sair da sua visualização e o cliente receberá a mensagem de encerramento definida.

Com isso já temos a integração entre o Rocket.Chat e o Telegram totalmente funcional!

Não adicionamos nenhuma automatização de pré-atendimento com menu de opções ou algo do tipo. Mas, com isso, já é possível começar a atender seus clientes só possuindo a infraestrutura do Rocket em execução.

Em breve podemos trazer mais conteúdos sobre integração do Omnichannel com outras plataformas.

Líder em Treinamento e serviços de Consultoria, Suporte e Implantação para o mundo open source. Conheça nossas soluções:

CURSOSCONSULTORIA