Integração com o bot do Telegram

Criar um bot no Telegram

1. Abra o Telegram e procure por @BotFather.
2. Inicie uma conversa com o BotFather e envie /newbot.
3. Escolha um nome de exibição e um nome de usuário para o bot. O nome de usuário precisa terminar em bot, por exemplo AcmeSupportBot.
4. O BotFather responde com um token de API. Copie esse token, você vai precisar dele no próximo passo.

Importante: mantenha o token em sigilo. Qualquer pessoa que tenha o token pode controlar o seu bot.

Conectar o bot ao Deskwoot

1. Acesse Configurações > Caixas de entrada e escolha Telegram em Adicionar um canal.
2. Informe o Nome da caixa de entrada e cole o token em Token do bot.
3. Clique em Criar caixa de entrada.

O Deskwoot conecta o bot ao Telegram na hora. Se o Telegram não aceitar o token, você vê o motivo e nenhuma caixa de entrada é criada. O último passo, Caixa de entrada criada, mostra em Mensagens de grupo se o bot lê todas as mensagens nos grupos (veja abaixo).

Os agentes que você adiciona em Colaboradores, nas configurações da caixa de entrada, são os que recebem as conversas dela pelo round robin. Veja Atribuição automática e round robin.

Chats privados

Quando alguém escreve para o seu bot, o chat aparece como uma conversa na sua caixa de entrada, com essa pessoa como contato. Sua equipe responde no Deskwoot e a resposta chega à pessoa no Telegram. Suas respostas podem levar texto e arquivos: imagens, vídeos, áudio e documentos. Quando o Fynn responde, uma linha como "Fynn, o assistente de IA de Acme" aparece acima da primeira resposta dele, veja Como os clientes sabem que o Fynn é uma IA.

O Telegram só deixa um bot escrever para quem já iniciou uma conversa com ele, então o cliente sempre escreve primeiro.

Grupos do Telegram

Adicione o seu bot a um grupo do Telegram e o grupo vira uma conversa na sua caixa de entrada, com o nome do grupo como contato. Seus clientes e a sua própria equipe podem escrever ali.

• Quem escreveu o quê. Cada mensagem mostra o nome do membro que a escreveu. Clique no nome ou na foto redonda ao lado para abrir o cartão do membro: o nome, o @ dele (um link para o perfil no Telegram) e o ID do Telegram. A seta ao lado do nome abre o contato numa nova aba.
• Um contato para cada membro. Cada pessoa que escreve no grupo ganha um contato próprio, o mesmo que o Deskwoot usa quando ela escreve para o seu bot num chat privado. Em mensagens mais antigas, um membro pode ainda não ter contato. O cartão então oferece Salvar como contato, que exige a permissão de gerenciar contatos (a função padrão Agente tem essa permissão).
• Responder a uma mensagem específica. Passe o mouse sobre uma mensagem e clique em Responder. Uma barra acima da caixa de resposta mostra Respondendo a Anna, e a sua resposta chega no Telegram como resposta àquela mensagem. Cancelar resposta (o x na barra) remove a barra.
• Citações dos clientes. Quando alguém responde no Telegram a uma mensagem anterior, o Deskwoot mostra a mensagem citada acima da resposta. Clique na citação para ir até ela.
• Seu bot de IA só responde quando é chamado. A sua equipe vê todas as mensagens do grupo que o bot recebe, mas o Fynn só responde a uma mensagem que menciona o seu bot (por exemplo @AcmeSupportBot) ou que responde a uma das mensagens do próprio Fynn. Uma resposta à mensagem de um agente não conta, mesmo que os agentes respondam pelo mesmo bot. Nenhuma outra mensagem automática, como uma resposta de ausência ou uma pesquisa de satisfação, vai para um grupo.

Responder a uma mensagem específica também funciona em chats privados do Telegram. No app para iPhone e Android, toque e segure uma mensagem e escolha Responder. Toque no nome de um membro para ver os detalhes dele, com Abrir contato ou Salvar como contato.

Fazer o bot ler todas as mensagens do grupo

O modo de privacidade do Telegram vem ativo em todo bot novo. Com ele ativo, um bot num grupo só recebe mensagens que o mencionam, comandos e respostas às mensagens dele, e a sua equipe perde a maior parte do grupo. Para receber todas as mensagens, faça uma destas opções:

• Desativar o modo de privacidade. No Telegram, abra o @BotFather e envie /setprivacy. Escolha o seu bot e depois Disable. Em seguida, remova o bot de cada grupo e adicione de novo, para que a mudança valha lá.
• Tornar o bot administrador do grupo. Administradores recebem todas as mensagens.

Para ver como está o seu bot, acesse Configurações > Caixas de entrada, clique em Configurar ao lado da sua caixa de entrada do Telegram e abra a aba Configuração. Em Mensagens de grupo aparece Lê todas as mensagens de grupo, ou que só parte das mensagens de grupo chega ao Deskwoot, junto com os passos acima. Depois de mudar a configuração no BotFather, clique em Verificar de novo.

O @ do Telegram nos contatos

Um contato guarda o @ do Telegram em Redes sociais, na página do contato, com um botão que abre o perfil no Telegram. Quando você escolhe um contato no painel, por exemplo para uma nova mensagem ou para mesclar dois contatos, e na busca de contatos do app, dá para encontrá-lo pelo @, digitado com ou sem o @.

• Quando um contato já conversou com o seu bot ou escreveu num dos grupos dele, o Telegram preenche o @ (se a pessoa tiver um) e o ID do Telegram. O campo mostra Preenchido a partir do Telegram. e não pode ser alterado.
• Em qualquer outro contato, você pode digitar o @ no campo Telegram, inclusive ao criar um contato novo. Salve com Atualizar contato. Um nome de usuário tem de 5 a 32 letras, números ou sublinhados.

Solução de problemas

• Só parte das mensagens do grupo chega: o modo de privacidade ainda está ativo, ou o bot não foi removido do grupo e adicionado de novo depois que você o desativou. Veja "Fazer o bot ler todas as mensagens do grupo" acima.
• Nenhuma mensagem chega: se você gerou um novo token no BotFather depois de conectar (/revoke), a caixa de entrada para de receber mensagens. Não é possível trocar o token de uma caixa de entrada existente. Exclua a caixa de entrada antiga do Telegram em Configurações > Caixas de entrada (as conversas dela continuam no Deskwoot) e conecte o novo token como uma nova caixa de entrada do Telegram.
• "Este bot do Telegram já está conectado a outra caixa de entrada do Deskwoot": o Telegram envia as mensagens de um bot para uma única caixa de entrada. Remova o bot de lá primeiro ou crie um novo bot com o @BotFather.
• O bot estava conectado a outro serviço antes: um bot do Telegram envia as mensagens para um único webhook. Ao conectá-lo ao Deskwoot, o webhook do outro serviço é substituído e esse serviço deixa de receber as mensagens do bot. Se o outro serviço definir o webhook dele de novo, as mensagens deixam de chegar ao Deskwoot.

Dicas

• Dê ao seu bot um nome claro, que combine com a sua marca, para que os clientes o reconheçam.
• Defina uma descrição e uma foto de perfil no BotFather com /setdescription e /setuserpic.
• Use etiquetas e atribuição para organizar as conversas do Telegram junto com os seus outros canais.

Perguntas frequentes

Por que só vejo parte das mensagens do grupo?

O modo de privacidade do Telegram está ativo para o seu bot, então num grupo ele só recebe mensagens que o mencionam, comandos e respostas às mensagens dele. Desative no @BotFather (/setprivacy, escolha o bot, Disable), depois remova o bot de cada grupo e adicione de novo. Ou torne o bot administrador do grupo. Mensagens de grupo, na aba Configuração da caixa de entrada, mostra a configuração de privacidade; clique em Verificar de novo depois de uma mudança. Um bot que é administrador de um grupo recebe todas as mensagens dele, mesmo com o modo de privacidade ativo. Mensagens de antes da mudança não chegam depois.

Posso responder a uma mensagem específica num grupo?

Sim. Passe o mouse sobre a mensagem e clique em Responder, ou no app toque e segure a mensagem e escolha Responder. A sua resposta chega no Telegram como resposta àquela mensagem. Isso funciona com mensagens de clientes e com mensagens da sua equipe que já foram enviadas, em grupos e em chats privados. Se a mensagem foi apagada no Telegram nesse meio tempo, a sua resposta é enviada assim mesmo, só que sem a citação.

Como vejo quem escreveu uma mensagem num grupo?

O nome do membro aparece acima de cada mensagem dele. Clique no nome para abrir o cartão com o @, o ID do Telegram e a seta que abre o contato. No app, toque no nome.

Todo membro do grupo vira contato?

Toda pessoa que escreve no grupo vira, e é o mesmo contato que o Deskwoot usa quando ela escreve direto para o seu bot. Outros bots e administradores que escrevem de forma anônima em nome do grupo não ganham contato. Em mensagens mais antigas, o cartão do membro pode mostrar Salvar como contato.

O Fynn responde em grupos do Telegram?

Só quando uma mensagem menciona o seu bot ou responde a uma das mensagens do próprio Fynn. Todo o resto do grupo chega à sua equipe sem resposta automática. Num chat privado, o Fynn responde como nos seus outros canais.

Consigo ver o número de telefone de um membro do grupo?

Não. O Telegram nunca passa o número de telefone de um membro para um bot. Um número de telefone só aparece quando o contato do membro no Deskwoot já tem um.

Que tipos de mensagem chegam ao Deskwoot?

Texto, fotos, vídeos, arquivos de áudio, mensagens de voz e documentos, com as legendas. Figurinhas, localizações, enquetes e mensagens de vídeo redondas não chegam ao Deskwoot, e uma mensagem editada depois no Telegram não muda no Deskwoot. Suas respostas podem incluir texto, imagens, vídeos, áudio e documentos. Mensagens de voz e arquivos de áudio são transcritos automaticamente, para o Fynn poder responder e a sua equipe poder ler, veja O Fynn e as mensagens de voz.

E se uma resposta não chegar ao cliente?

Abaixo da resposta aparece Falha na entrega. com o motivo do Telegram, por exemplo quando o cliente bloqueou o bot. Se o seu texto chegou mas um arquivo não, um clique envia de novo só o arquivo que faltou, veja Quando uma resposta não é entregue.

Existe custo por mensagem no Telegram?

Não. O Telegram não cobra pela API de bots. Quando o Fynn responde, isso conta como uma conversa de IA no Deskwoot, igual a qualquer outro canal.

Como crio um bot no Telegram?

Abra o Telegram, procure por @BotFather, envie /newbot e siga as instruções. No final, o BotFather envia um token de API. Cole esse token no Deskwoot.

E se o nome de usuário do bot já estiver em uso?

Nomes de usuário de bots no Telegram são únicos e terminam em "bot". Tente variações como AcmeSupportBot, AcmeHelpBot ou AcmeChatBot e fique com uma que esteja livre.

Posso conectar vários bots do Telegram?

Sim. Cada bot vira uma caixa de entrada própria, o que ajuda com marcas, linhas de produto ou idiomas separados. Um bot só pode estar conectado a uma caixa de entrada do Deskwoot.

E se eu gerar um novo token do bot depois de conectar?

A caixa de entrada para de funcionar com o token antigo, e não é possível trocar o token de uma caixa de entrada existente. Exclua a caixa de entrada antiga do Telegram em Configurações > Caixas de entrada (as conversas dela continuam no Deskwoot) e conecte o novo token como uma nova caixa de entrada do Telegram. Use /revoke no BotFather só quando for realmente necessário.

O bot pode iniciar uma conversa no Telegram?

Não. O Telegram exige que a pessoa escreva para o bot primeiro. Depois disso, a sua equipe pode responder a qualquer momento, sem janela de tempo.

Mensagens antigas do Telegram são importadas?

Não. O Telegram não passa para os bots as mensagens de antes de eles entrarem num chat. No Deskwoot só aparecem mensagens enviadas depois que você conectou o bot (e, num grupo, depois que o bot foi adicionado).

E se o bot parar de funcionar?

As causas mais comuns são um token revogado, um bot excluído no BotFather ou um bot bloqueado pelo Telegram por quebrar as regras. Confira o seu bot em /mybots no BotFather. Se você gerar um novo token, conecte-o como uma nova caixa de entrada do Telegram, como descrito acima.

Posso mudar a foto de perfil e a descrição do bot?

Sim, no BotFather com /setdescription, /setuserpic e /setname. As pessoas veem essas informações quando abrem o seu bot pela primeira vez.