Um comando de bot do Telegram é uma das palavras-chave com barra que um bot publica para que as pessoas vejam o que ele faz. Eles aparecem no menu ao lado da caixa de mensagem, e a própria definição do Telegram é a mais direta: "A command is a simple /keyword that tells the bot what to do."
O que vale uma página não é o que eles são, mas quais deles uma determinada pessoa vê, porque isso é decidido por uma regra de precedência e não por uma lista única, e é o motivo mais comum para uma alteração parecer não ter entrado em vigor.
Como um comando pode ser?
As regras de formato do Telegram são rígidas e curtas. Comandos "must always start with the / symbol and contain up to 32 characters. They can use Latin letters, numbers and underscores, though simple lowercase text is recommended for a cleaner look."
Ou seja: sem espaços, sem hífens, sem caracteres acentuados, e nada com mais de 32 caracteres incluindo a palavra-chave da barra. Um comando fora dessas regras não é um comando mais curto; não é um comando.
Três são esperados de todos. O Telegram pede que todos os desenvolvedores suportem /start, /help e /settings quando aplicável, para que as pessoas encontrem um conjunto consistente em qualquer bot que abram. Tratar esses três como reservados é um bom hábito mesmo quando seu bot faz algo não relacionado com a mesma palavra.
Como os comandos são definidos?
De duas formas, e ambas alteram a mesma lista subjacente.
Você pode defini-los por conversa através do próprio @BotFather do Telegram, que é o caminho habitual durante o desenvolvimento. Ou pode defini-los via código com o método API do Bot setMyCommands, que recebe a lista como um array, aceita no máximo 100 comandos e recebe um escopo opcional que "Defaults to BotCommandScopeDefault".
A via API é a mais indicada quando qualquer aspecto dos seus comandos depende de estado, porque pode ser chamada sempre que esse estado muda, e não apenas quando alguém lembra de fazê-lo.
Por que minha lista de comandos não muda?
Porque escopos não são mesclados, e uma lista mais restrita que você definiu antes ainda está vencendo.
O modelo do Telegram é que um bot "is able to show different commands to different users and groups", controlado por escopos, dos quais existem sete:
BotCommandScopeDefaultBotCommandScopeAllPrivateChatsBotCommandScopeAllGroupChatsBotCommandScopeAllChatAdministratorsBotCommandScopeChatBotCommandScopeChatAdministratorsBotCommandScopeChatMember
E a regra de resolução é uma única frase na documentação do Telegram, sob "Determining list of commands": "The first list of commands which is set is returned."
Essa é a resposta completa para a reclamação mais comum. As listas não são combinadas. O Telegram percorre uma sequência ordenada do escopo mais específico ao menos específico e para no primeiro que estiver definido.
Em um chat privado com o bot, a ordem que o Telegram percorre é: botCommandScopeChat com um language_code correspondente, depois botCommandScopeChat, depois botCommandScopeAllPrivateChats com um código de idioma, depois botCommandScopeAllPrivateChats, depois botCommandScopeDefault com um código de idioma, depois botCommandScopeDefault.
Em grupos e supergrupos a sequência é mais longa, indo de botCommandScopeChatMember passando pelos escopos exclusivos de administradores e botCommandScopeAllGroupChats antes de chegar ao padrão.
Uma coisa se inverte entre os dois cenários, e é aí que está a armadilha. Em um chat privado, botCommandScopeChat é o escopo mais específico que existe. Em um grupo, não é: tanto botCommandScopeChatAdministrators quanto sua variante de idioma ficam acima dele, então uma lista de administradores definida uma vez vence a lista por chat para essas pessoas, justamente onde você esperaria que a por chat ganhasse.
Então, se você definiu uma lista por chat durante testes e depois alterou o padrão, aquele chat continua mostrando a lista antiga para sempre. A solução é limpar o escopo mais restrito em vez de continuar editando o mais amplo, e o mesmo vale para uma variante language_code, que fica acima do seu próprio escopo na ordem.
O que eu devo fazer na prática?
Três hábitos decorrem da regra de precedência.
- Defina o escopo padrão primeiro e altere-o por último. Ele é o fallback que todos alcançam quando nenhum escopo mais restrito existe, então é a lista que a maioria dos seus usuários vê.
- Use um escopo restrito deliberadamente, não por conveniência. Qualquer coisa que você definir no nível de chat ou membro fica invisível para você depois, a menos que vá procurar, e silenciosamente sobrepõe tudo que é mais amplo.
- Quando uma lista parecer desatualizada, enumere os escopos em vez de redefinir o que você editou. O que está vencendo geralmente não é o que você tem alterado.
Bird suporta Telegram?
Para códigos de verificação, sim, e para nada do que é descrito nesta página.
Bird Verify entrega códigos de verificação de uso único via Telegram junto com email, SMS e WhatsApp, usando a própria conta de notificação verificada do Telegram em vez de um bot operado por você. Esse é um mecanismo diferente de um bot com menu de comandos: não há bot para registrar, não há comandos para publicar e nada nesta página se aplica a ele. Se a entrega de códigos de verificação foi o que trouxe você aqui, Bird Verify cobre os canais e como eles fazem fallback.
Tudo acima é comportamento da própria plataforma do Telegram. O guia de funcionalidades de bots e a referência do Bot API são a fonte e o lugar para verificar mudanças.
Em resumo
Um comando é uma palavra-chave com barra que o bot divulga.
Começa com uma barra, tem no máximo 32 caracteres e usa apenas letras latinas, números e underscores.
Três comandos são esperados de todo bot.
O Telegram pede que desenvolvedores suportem
/start,/helpe/settingsquando aplicável, para que as pessoas encontrem os mesmos três em qualquer bot.Escopos decidem quem vê qual lista.
São sete, desde um padrão global até um membro específico de um chat específico.
O primeiro escopo definido vence por completo.
Listas não são mescladas. Um escopo mais restrito definido uma vez oculta a lista mais ampla daquele público até você limpá-lo.