Bots: uma introdução para desenvolvedores

Bots são aplicativos de terceiros executados dentro do Telegram. Os usuários podem interagir com os bots, enviando-lhes mensagens, comandos e solicitações inline . Você controla seus bots usando solicitações HTTPS para nossa API de bot .

1. O que posso fazer com bots?

Para citar apenas algumas coisas, você pode usar bots para:

• Receba notificações e notícias personalizadas . Um bot pode atuar como um jornal inteligente, enviando conteúdo relevante assim que for publicado.

• Integre com outros serviços . Um bot pode enriquecer os bate-papos do Telegram com conteúdo de serviços externos.
  Gmail Bot , GIF bot , IMDB bot , Wiki bot , Music bot , Youtube bot , GitHubBot

• Aceite pagamentos de usuários do Telegram . Um bot pode oferecer serviços pagos ou funcionar como uma loja virtual. Leia mais »
  Demo Shop Bot

• Crie ferramentas personalizadas . Um bot pode fornecer alertas, previsões do tempo, traduções, formatação ou outros serviços.
  Bot de Markdown , bot de adesivos , bot de votação , bot de curtir

• Crie jogos para um ou vários jogadores . Um bot pode oferecer experiências ricas em HTML5 , desde fliperamas e quebra-cabeças simples até jogos de tiro em 3D e estratégia em tempo real.
  GameBot , Gamee

• Construir serviços sociais . Um bot pode conectar pessoas que procuram parceiros de conversa com base em interesses comuns ou proximidade.

• Faça praticamente qualquer outra coisa . Exceto por pratos - os bots são péssimos em lavar pratos.

2. Como funcionam os bots?

Basicamente, os Bots do Telegram são contas especiais que não requerem um número de telefone adicional para serem configuradas. Os usuários podem interagir com os bots de duas maneiras:

• Envie mensagens e comandos para bots abrindo um bate-papo com eles ou adicionando-os a grupos.
• Envie solicitações diretamente do campo de entrada, digitando @username do bot e uma consulta. Isso permite o envio de conteúdo de bots inline diretamente para qualquer chat, grupo ou canal.

Mensagens, comandos e solicitações enviadas por usuários são passados ​​para o software executado em seus servidores. Nosso servidor intermediário lida com toda a criptografia e comunicação com a API do Telegram para você. Você se comunica com este servidor por meio de uma interface HTTPS simples que oferece uma versão simplificada da API do Telegram. Chamamos essa interface de nossa API de bot .

Uma descrição detalhada da API do Bot está disponível nesta página »

3. Como faço para criar um bot?

Existe um ... bot para isso. Basta falar com BotFather (descrito abaixo ) e seguir alguns passos simples. Depois de criar um bot e receber seu token de autorização, vá até o manual da API do Bot para ver o que você pode ensinar seu bot a fazer.

Você também pode verificar alguns exemplos de código aqui »

4. Como os bots são diferentes dos humanos?

• Os bots não têm status online e nenhum carimbo de data / hora visto pela última vez, a interface mostra o rótulo 'bot' .
• Os bots têm armazenamento em nuvem limitado - mensagens mais antigas podem ser removidas pelo servidor logo após terem sido processadas.
• Os bots não podem iniciar conversas com os usuários. Um usuário deve adicioná-los a um grupo ou enviar-lhes uma mensagem primeiro. As pessoas podem usar t.me/<bot_username>links ou pesquisa de nome de usuário para encontrar seu bot.
• Nicks Bot sempre terminam em 'bot' (por exemplo @TriviaBot , @GitHub_bot ).
• Quando adicionados a um grupo, os bots não recebem todas as mensagens por padrão (consulte Modo de privacidade ).
• Bots nunca comem, dormem ou reclamam (a menos que expressamente programado de outra forma).

---

5. Benefícios do bot

Os bots do Telegram são únicos de várias maneiras - oferecemos dois tipos de teclado, interfaces adicionais para comandos padrão e links diretos , bem como formatação de texto e muito, muito mais.

Modo inline

Os usuários podem interagir com o seu bot por meio de consultas in - line direto do campo de entrada de texto em qualquer chat. Tudo o que eles precisam fazer é iniciar uma mensagem com o nome de usuário do seu bot e digitar uma consulta.

Tendo recebido a consulta, seu bot pode retornar alguns resultados. Assim que o usuário toca em um deles, ele é enviado para o bate-papo atualmente aberto do usuário. Dessa forma, as pessoas podem solicitar conteúdo do seu bot em qualquer um de seus chats, grupos ou canais.

Confira este blog para ver um exemplo de bot embutido em ação. Você também pode tentar os @sticker e @music bots para ver por si mesmo.

\

Também implementamos uma maneira fácil de seu bot alternar entre os modos embutido e PM .

Plataforma de pagamentos

Você pode usar bots para aceitar pagamentos de usuários do Telegram em todo o mundo.

Do ponto de vista dos usuários, o sistema é totalmente integrado. Seu bot envia uma mensagem de fatura formatada especialmente . Essas mensagens apresentam uma foto e uma descrição do produto, juntamente com um botão Pagar em destaque . Tocar neste botão abre uma interface especial de pagamento direto no aplicativo Telegram.

O usuário insere as informações necessárias, escolhe um de seus cartões salvos ou insere um novo (o Telegram também oferece suporte a Apple Pay e Android Pay) - e paga pelo seu produto. Veja como o processo pode ser:

Plataforma de jogos

Os bots podem oferecer aos usuários jogos em HTML5 para jogar sozinho ou competir entre si em grupos e bate-papos um-a-um. A plataforma permite que seu bot acompanhe as pontuações mais altas de cada jogo disputado em cada chat. Sempre que há um novo líder no jogo, os outros membros do chat são notificados de que precisam ser promovidos.

  \

Como a tecnologia subjacente é o HTML5, os jogos podem ser qualquer coisa, desde simples fliperamas e quebra-cabeças até jogos de tiro em 3D para vários jogadores e jogos de estratégia em tempo real. Nossa equipe criou algumas demonstrações simples para você experimentar:

• Batalha matemática
• Lenhador
• Corsários

Você também pode verificar o bot @gamee que tem mais de 20 jogos.

Leia mais sobre a plataforma de jogos »

Teclados

Os bots de bate-papo tradicionais podem ser ensinados a entender a linguagem humana. Mas às vezes você quer uma entrada mais formal do usuário - e é aqui que os teclados personalizados podem se tornar extremamente úteis.

Sempre que o seu bot envia uma mensagem, ele pode passar um teclado especial com opções de resposta predefinidas (consulte ReplyKeyboardMarkup ). Os aplicativos do Telegram que receberem a mensagem exibirão seu teclado para o usuário. Tocar em qualquer um dos botões enviará imediatamente o comando respectivo. Dessa forma, você pode simplificar drasticamente a interação do usuário com o seu bot.

Atualmente, oferecemos suporte para texto e emoji para seus botões. Aqui estão alguns exemplos de teclado personalizado:

  \ \

Para obter mais informações técnicas sobre teclados personalizados, consulte o manual da API do Bot (consulte sendMessage ).

Teclados embutidos e atualização instantânea

Há momentos em que você prefere fazer coisas sem enviar nenhuma mensagem para o chat. Por exemplo, quando o usuário está alterando as configurações ou folheando os resultados da pesquisa. Nesses casos, você pode usar os teclados embutidos integrados diretamente às mensagens às quais pertencem.

Ao contrário dos teclados de resposta personalizados, pressionar botões em teclados embutidos não resulta em mensagens enviadas para o chat. Em vez disso, os teclados embutidos oferecem suporte a botões que funcionam nos bastidores: botões de retorno de chamada , botões de URL e botões de alternar para embutidos .

  \

Quando botões de retorno de chamada são usados, seu bot pode atualizar suas mensagens existentes (ou apenas seus teclados) para que o bate-papo permaneça organizado. Confira esses bots de amostra para ver os teclados embutidos em ação: @music , @vote , @like .

Leia mais sobre teclados embutidos e edição instantânea »

Comandos

Os comandos apresentam uma maneira mais flexível de se comunicar com seu bot. A seguinte sintaxe pode ser usada:

/command

Um comando deve sempre começar com o símbolo '/' e não pode ter mais de 32 caracteres. Os comandos podem usar letras latinas, números e sublinhados. Aqui estão alguns exemplos:

/get_messages_stats
/set_timer 10min Alarm!
/get_timezone London, UK

As mensagens que começam com uma barra são sempre passadas para o bot (junto com as respostas às suas mensagens e mensagens que @ mencionam o bot pelo nome de usuário). Os aplicativos do Telegram irão:

• Sugira uma lista de comandos suportados com descrições quando o usuário digitar '/' (para que isso funcione, você precisa ter fornecido uma lista de comandos para o BotFather ). Tocar em um comando na lista envia imediatamente o comando.
• Mostrar um botão adicional (/) no campo de entrada em todos os chats com bots. Tocar nele digita um '/' e mostra a lista de comandos.
• Destaque / comandos nas mensagens. Quando o usuário toca em um comando destacado, o comando é enviado imediatamente.

   \ \

Se vários bots estiverem em um grupo, é possível adicionar nomes de usuários de bot aos comandos para evitar confusão:

/start@TriviaBot
/start@ApocalypseBot

Isso é feito automaticamente quando os comandos são selecionados por meio da lista de sugestões. Lembre-se de que seu bot precisa ser capaz de processar comandos seguidos de seu nome de usuário.

Comandos globais

Para tornar mais fácil para os usuários navegar no multiverso do bot, pedimos a todos os desenvolvedores que ofereçam suporte a alguns comandos básicos. Os aplicativos do Telegram terão atalhos de interface para esses comandos.

• / start - inicia a interação com o usuário, por exemplo, enviando uma mensagem de saudação. Este comando também pode ser usado para passar parâmetros adicionais para o bot (consulte Link direto )
• / help - retorna uma mensagem de ajuda. Pode ser um pequeno texto sobre o que seu bot pode fazer e uma lista de comandos.
• / settings - (se aplicável) retorna as configurações do bot para este usuário e sugere comandos para editar essas configurações.

Os usuários verão um botão Iniciar quando abrirem pela primeira vez uma conversa com seu bot. Os links de Ajuda e Configurações estarão disponíveis no menu da página de perfil do bot.

 \

Formatação: negrito, itálico, texto de largura fixa e links embutidos

Você pode usar texto em negrito, itálico ou de largura fixa, bem como links embutidos nas mensagens de seus bots. Os clientes do Telegram os processarão de acordo.

Leia mais no manual da API do Bot »

Modo de privacidade

Os bots são frequentemente adicionados a grupos para aumentar a comunicação entre usuários humanos, por exemplo, fornecendo notícias, notificações de serviços externos ou funcionalidade de pesquisa adicional. Isso é especialmente verdadeiro para grupos relacionados ao trabalho. Agora, quando você compartilha um grupo com um bot, você tende a se perguntar “Como posso ter certeza de que o malandro não está vendendo meu histórico de bate-papo para meus concorrentes?” A resposta é - modo de privacidade .

Um bot em execução no modo de privacidade não receberá todas as mensagens que as pessoas enviam ao grupo. Em vez disso, ele receberá apenas:

• Mensagens que começam com uma barra '/' (consulte os comandos acima)
• Respostas às próprias mensagens do bot
• Mensagens de serviço (pessoas adicionadas ou removidas do grupo, etc.)
• Mensagens de canais dos quais é membro

Por um lado, isso ajuda alguns de nós a dormir melhor à noite (em nossos nightcaps de papel alumínio), por outro - permite que o desenvolvedor do bot economize muitos recursos, uma vez que eles não precisarão processar dezenas de milhares de mensagens irrelevantes cada dia.

O modo de privacidade é habilitado por padrão para todos os bots, exceto bots que foram adicionados ao grupo como administradores (os administradores de bots sempre recebem todas as mensagens). Ele pode ser desabilitado, para que o bot receba todas as mensagens como um usuário comum (o bot precisará ser adicionado novamente ao grupo para que esta alteração tenha efeito). Recomendamos fazer isso apenas nos casos em que for absolutamente necessário para o funcionamento do seu bot - os usuários sempre podem ver a configuração de privacidade atual de um bot na lista de membros do grupo. Na maioria dos casos, usar a opção de forçar resposta para as mensagens do bot deve ser mais do que suficiente.

Então, quais mensagens exatamente meu bot receberá? »

Deep linking

Os bots do Telegram têm um mecanismo de deep linking , que permite passar parâmetros adicionais ao bot na inicialização. Pode ser um comando que inicia o bot - ou um token de autenticação para conectar a conta do Telegram do usuário à sua conta em algum serviço externo.

Cada bot possui um link que abre uma conversa com ele no Telegram - https://t.me/<bot username>. Você pode adicionar os parâmetros start ou startgroup a este link, com valores de até 64 caracteres. Por exemplo:

https://t.me/triviabot?startgroup=test

A-Z, a-z, 0-9, _E -são permitidos. Recomendamos o uso de base64url para codificar parâmetros com conteúdo binário e outros tipos.

Seguir um link com o parâmetro de início abrirá uma conversa um-a-um com o bot, mostrando um botão INICIAR no lugar do campo de entrada. Se o parâmetro startgroup for usado, o usuário é solicitado a selecionar um grupo para adicionar o bot. Assim que um usuário confirmar a ação (pressiona o botão START em seu aplicativo ou seleciona um grupo para adicionar o bot), seu bot receberá uma mensagem desse usuário neste formato:

/start PAYLOAD

PAYLOADrepresenta o valor do parâmetro start ou startgroup que foi transmitido no link.

Exemplo de deep linking

Suponha que o site example.com queira enviar notificações a seus usuários por meio de um bot do Telegram. Veja o que eles podem fazer para habilitar notificações para um usuário com o ID 123.

1. Crie um bot com um nome de usuário adequado, por exemplo, @ExampleComBot
2. Configure um webhook para mensagens recebidas
3. Gere uma string aleatória de comprimento suficiente, por exemplo $memcache_key = "vCH1vGWJxfSeofSAs0K5PA"
4. Coloque o valor 123com a chave $memcache_keyno Memcache por 3600 segundos (uma hora)
5. Mostre ao nosso usuário o botão https://t.me/ExampleComBot?start=vCH1vGWJxfSeofSAs0K5PA
6. Configure o processador webhook para consultar o Memcached com o parâmetro que é passado nas mensagens de entrada começando com /start. Se a chave existir, registre o chat_id passado para o webhook como telegram_chat_id para o usuário 123. Remova a chave do Memcache.
7. Agora quando quisermos enviar uma notificação para o usuário 123, verifique se ele possui o campo telegram_chat_id . Se sim, use o método sendMessage na API do Bot para enviar uma mensagem no Telegram.

Localização e número

Alguns bots precisam de dados extras do usuário para funcionar corretamente. Por exemplo, saber a localização do usuário ajuda a fornecer resultados geo-específicos mais relevantes. O número de telefone do usuário pode ser muito útil para integrações com outros serviços, como bancos, etc.

Os bots podem solicitar a localização e o número de telefone de um usuário usando botões especiais. Observe que os botões de número de telefone e de solicitação de localização funcionam apenas em bate-papos privados.

\

Quando esses botões são pressionados, os clientes do Telegram exibem um alerta de confirmação que informa ao usuário o que está para acontecer.

Manual: botões de número e localização »

---

6. BotFather

Vá para o início para aprender tudo sobre os bots do Telegram »

BotFather é o único bot que comanda todos eles. Isso o ajudará a criar novos bots e alterar as configurações dos existentes.

Criar um novo bot

Use o comando / newbot para criar um novo bot. O BotFather solicitará um nome e nome de usuário e, em seguida, gerará um token de autorização para seu novo bot.

O nome do seu bot é exibido nos detalhes de contato e em outros lugares.

O nome de usuário é um nome curto, para ser usado em menções e links t.me. Os nomes de usuário têm de 5 a 32 caracteres e não diferenciam maiúsculas de minúsculas, mas podem incluir apenas caracteres latinos, números e sublinhados. O nome de usuário do seu bot deve terminar em 'bot', por exemplo, 'tetris_bot' ou 'TetrisBot'.

O token é uma string ao longo das linhas 110201543:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsawque é necessária para autorizar o bot e enviar solicitações para a API do bot . Mantenha seu token seguro e armazene-o com segurança, ele pode ser usado por qualquer pessoa para controlar seu bot.

Gerando um token de autorização

Se o token existente estiver comprometido ou se você o perdeu por algum motivo, use o comando / token para gerar um novo.

Comandos do botfather

Os comandos restantes são autoexplicativos:

• / mybots - retorna uma lista de seus bots com controles úteis para editar suas configurações
• / mygames - faz o mesmo com seus jogos

Editar bots

• / setname - muda o nome do seu bot.
• / setdescription - muda a descrição do bot , um texto curto de até 512 caracteres, descrevendo seu bot. Os usuários verão este texto no início da conversa com o bot, intitulado 'O que este bot pode fazer?'.
• / setabouttext - altera as informações sobre o bot , um texto ainda mais curto de até 120 caracteres. Os usuários verão este texto na página de perfil do bot. Quando eles compartilham seu bot com alguém, este texto é enviado junto com o link.
• / setuserpic - muda as fotos de perfil do bot. É sempre bom colocar um rosto em um nome.
• / setcommands - altera a lista de comandos suportados pelo seu bot. Os usuários verão esses comandos como sugestões quando digitarem /no chat com o seu bot. Cada comando tem um nome (deve começar com uma barra '/', alfanumérico mais sublinhados, não mais do que 32 caracteres, não diferencia maiúsculas de minúsculas), parâmetros e uma descrição de texto. Os usuários verão a lista de comandos sempre que digitarem '/' em uma conversa com seu bot.
• / deletebot - exclui seu bot e libera seu nome de usuário.

Editar Configurações

• / setinline - alterna o modo embutido para o seu bot.
• / setinlinegeo - solicita dados de localização para fornecer resultados embutidos baseados em localização .
• / setjoingroups - define se o seu bot pode ser adicionado a grupos ou não. Qualquer bot deve ser capaz de processar mensagens privadas, mas se o seu bot não foi projetado para funcionar em grupos, você pode desativar isso.
• / setprivacy - define quais mensagens seu bot receberá quando adicionado a um grupo. Com o modo de privacidade desativado, o bot receberá todas as mensagens. Recomendamos deixar o modo de privacidade ativado. Você precisará adicionar novamente o bot aos grupos existentes para que essa alteração tenha efeito.

Gerenciar jogos

• / newgame - cria um novo jogo .
• / listgames - obtém uma lista de seus jogos.
• / editgame - edita um jogo.
• / deletegame - apaga um jogo existente.

Observe que pode levar alguns minutos para que as alterações entrem em vigor.

Alertas de status

Milhões de pessoas escolhem o Telegram por sua velocidade. Para se manter competitivo neste ambiente, seu bot também precisa ser responsivo. A fim de ajudar os desenvolvedores a manter seus bots em forma, o Botfather enviará alertas de status se perceber que algo está errado.

Verificaremos o número de respostas e a taxa de conversão de solicitação / resposta para bots populares (cerca de 300 solicitações por minuto: mas não anote isso, pois o valor pode mudar no futuro). Se obtivermos leituras anormalmente baixas, você receberá uma notificação do Botfather.

Respondendo a alertas

Por padrão, você receberá apenas um alerta por bot por hora. Cada alerta possui os seguintes botões:

• Fixo. Use isto se você encontrou um problema com seu bot e o corrigiu. Se você pressionar o botão de correção, retomaremos o envio de alertas da maneira normal para que você possa ver se sua correção funcionou dentro de 5 a 10 minutos, em vez de ter que esperar uma hora.
• Apoio, suporte. Use isso para abrir um bate-papo com @BotSupport se você não encontrar nenhum problema com o seu bot ou se achar que o problema está do nosso lado.
• Mudo por 8h / 1s. Use isto se você não pode consertar seu bot no momento. Isso desativará todos os alertas para o bot em questão pelo período de tempo especificado. Não recomendamos o uso dessa opção, pois seus usuários podem migrar para um bot mais estável. Você pode ativar os alertas nas configurações do seu bot via Botfather.

Problemas monitorados

No momento, iremos notificá-lo sobre os seguintes problemas:

1

Too few **private messages** are sent compared to previous weeks: **{value}**

Seu bot está enviando muito menos mensagens do que nas semanas anteriores. Isso é útil para bots de boletim informativo que enviam mensagens sem avisos dos usuários. Quanto maior o valor, mais significativa é a diferença.

2

Too few replies to incoming **private messages**. Conversion rate: **{value}**

Seu bot não está respondendo a todas as mensagens que estão sendo enviadas para ele (a taxa de conversão de solicitação / resposta do seu bot foi muito baixa em pelo menos dois dos últimos três períodos de 5 minutos). Para fornecer uma boa experiência ao usuário, responda a todas as mensagens enviadas para o seu bot. Responda às atualizações de mensagens chamando os métodos send… (por exemplo, sendMessage ).

3 -

Too few answers to **inline queries**. Conversion rate: **{value}**

Seu bot não está respondendo a todas as consultas inline que estão sendo enviadas a ele, calculadas da mesma forma que acima. Responder a inline_query atualizações chamando answerInlineQuery .

4 -

Too few answers to **callback queries**. Conversion rate: **{value}**
Too few answers to **callback game queries**. Conversion rate: **{value}**

Seu bot não está respondendo a todas as consultas de retorno de chamada que estão sendo enviadas a ele (com ou sem jogos), calculado da mesma forma que acima. Responda às atualizações de callback_query chamando answerCallbackQuery .

Observe que o recurso de alertas de status ainda está sendo testado e será aprimorado no futuro.

---

É isso para a introdução. Agora você está definitivamente pronto para prosseguir para o MANUAL da API do BOT .

Se você tiver alguma dúvida, consulte nossas Perguntas frequentes sobre bots »