Cosa sono i comandi dei bot Telegram e perché la mia lista non si aggiorna?

Un comando di un bot Telegram è una delle parole chiave con slash che un bot pubblica perché le persone possano vedere cosa fa. Compaiono nel menu accanto al campo di scrittura, e la definizione di Telegram è quella semplice: "A command is a simple /keyword that tells the bot what to do."

La parte che merita una pagina non è cosa sono, ma quali vede una determinata persona, perché questo è deciso da una regola di precedenza e non da una lista unica, ed è il motivo più comune per cui una modifica sembra non aver avuto effetto.

Che aspetto può avere un comando?

Le regole di formato di Telegram sono rigide e brevi. I comandi "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."

Quindi niente spazi, niente trattini, niente caratteri accentati e niente più lungo di 32 caratteri, slash compreso. Un comando che non rispetta queste regole non è un comando più corto: non è un comando.

Tre sono attesi da tutti. Telegram chiede a tutti gli sviluppatori di supportare /start, /help e /settings dove applicabile, così le persone trovano un set coerente qualunque bot aprano. Trattare quei tre come riservati è una buona abitudine anche quando il bot fa qualcosa di diverso con la stessa parola.

Come si impostano i comandi?

In due modi, ed è la stessa lista sottostante.

Puoi impostarli in modo conversazionale tramite @BotFather di Telegram, che è il percorso abituale durante lo sviluppo. Oppure puoi impostarli da codice con il metodo API del Bot setMyCommands, che accetta la lista come array, ammette al massimo 100 comandi e accetta uno scope opzionale che "Defaults to BotCommandScopeDefault".

Il percorso API è quello da usare quando qualsiasi aspetto dei comandi dipende da uno stato, perché può essere chiamato ogni volta che quello stato cambia anziché solo quando un umano se ne ricorda.

Perché la mia lista di comandi non cambia?

Perché gli scope non si uniscono, e una lista più ristretta impostata prima sta ancora prevalendo.

Il modello di Telegram prevede che un bot "is able to show different commands to different users and groups", controllato dagli scope, che sono sette:

• BotCommandScopeDefault
• BotCommandScopeAllPrivateChats
• BotCommandScopeAllGroupChats
• BotCommandScopeAllChatAdministrators
• BotCommandScopeChat
• BotCommandScopeChatAdministrators
• BotCommandScopeChatMember

E la regola di risoluzione è una singola frase nella documentazione di Telegram, sotto "Determining list of commands": "The first list of commands which is set is returned."

Questa è l'intera risposta al problema più comune. Le liste non vengono combinate. Telegram percorre una sequenza ordinata dallo scope più specifico al meno specifico e si ferma al primo che è impostato.

In una chat privata con il bot, l'ordine che Telegram percorre è: botCommandScopeChat con un language_code corrispondente, poi botCommandScopeChat, poi botCommandScopeAllPrivateChats con un codice lingua, poi botCommandScopeAllPrivateChats, poi botCommandScopeDefault con un codice lingua, poi botCommandScopeDefault.

Nei gruppi e supergruppi la sequenza è più lunga, partendo da botCommandScopeChatMember attraverso gli scope riservati agli amministratori e botCommandScopeAllGroupChats prima di raggiungere il default.

Una cosa si inverte tra i due contesti, ed è la trappola. In una chat privata botCommandScopeChat è lo scope più specifico che esista. In un gruppo no: sia botCommandScopeChatAdministrators sia la sua variante con lingua si trovano sopra di esso, quindi una lista per amministratori impostata una volta prevale sulla lista per-chat per quelle persone, proprio nel contesto in cui ti aspetteresti che per-chat vinca.

Quindi se imposti una lista per-chat durante i test e poi modifichi il default, quella chat continua a mostrare la vecchia lista per sempre. La soluzione è cancellare lo scope più ristretto anziché continuare a modificare quello più ampio, e lo stesso vale per una variante language_code, che si trova sopra il proprio scope nell'ordine.

Cosa dovrei fare concretamente?

Tre buone abitudini derivano dalla regola di precedenza.

1. Imposta lo scope default per primo e modificalo per ultimo. È il fallback che tutti raggiungono quando non esiste nulla di più ristretto, quindi è la lista che la maggior parte dei tuoi utenti vede.
2. Usa uno scope ristretto intenzionalmente, non per comodità. Qualsiasi cosa imposti a livello di chat o membro diventa invisibile in seguito a meno che non la cerchi, e sovrascrive silenziosamente tutto ciò che è più ampio.
3. Quando una lista sembra obsoleta, enumera gli scope anziché reimpostare quello che hai modificato. Quello che sta prevalendo di solito non è quello che stavi cambiando.

Bird supporta Telegram?

Per i codici di verifica sì, e per nulla di quanto descritto in questa pagina.

Bird Verify consegna codici di verifica monouso tramite Telegram insieme a email, SMS e WhatsApp, usando l'account di notifica verificato di Telegram anziché un bot gestito da te. È un meccanismo diverso da un bot con un menu di comandi: non c'è un bot da registrare, nessun comando da pubblicare, e nulla di questa pagina si applica. Se la consegna di codici di verifica è il motivo per cui sei qui, Bird Verify descrive i canali e come avviene il fallback.

Tutto quanto sopra è il comportamento della piattaforma Telegram. La loro guida alle funzionalità dei bot e il riferimento Bot API sono la fonte e il posto dove verificare eventuali cambiamenti.