Telegram Keyboards
Telegram provides a powerful method of providing your audience with convenient ways to navigate and interact with your chatbots via their Custom Keyboards. Flow XO supports taking full advantage of Custom Keyboards when using our Telegram Actions Integration. Nearly all of the functions in Telegram that let you send or edit messages accept a custom keyboard specification, letting you design very flexible and responsive interfaces for your users. Wherever a Custom Keyboard is accepted, you will be able to specify the keyboard layout and behavior you want using our simple keyboard text notation.
If you already understand the different types of keyboards in Telegram and just want to see exactly how to specify them, here's an illustrated example:
Button 1 | Button 2[b2] | Button 3[https://www.button3.com]
🎈 Button 4[{"hi":5}]
The general rule is that each line of the keyboard specification represents a keyboard row. Each keyboard button is to be separated by a pipe character ("|"). The button label is specified as regular text, and the value (if any) can be specified in square brackets after the label. In the example above, the first row has 3 buttons, and the second row has one.
Note that the second button - Button 2 - has a VALUE associated with it of "b2". This only works for special values (such as poll or quiz) on a Standard keyboard. On an inline keyboard, the label will be shown to the user but when they click the button, the VALUE will be sent back to the bot for processing. Also not that Button 3 has a value that is a URL. When Flow XO detects that a button value is a URL it will (for inline keyboards) change the button type to be a link to an external website.
That's the quick and dirty, now we'll discuss the different keyboard types in more detail.
Keyboard Types
Telegram has a couple of different Keyboard Types and you can choose which one you want when sending a custom keyboard along with most messages. You should be aware though that you can only EDIT an inline keyboard, and only an inline keyboard can be used when sending messages to a channel. The keyboard in the image above is an inline keyboard.
Inline Keyboards
Inline keyboards are the default custom keyboard type in Flow XO's Telegram Actions integration. The Inline Keyboard attaches the keyboard to the message that it is sent with. The keyboard appears directly underneath the message, and as more messages are added to the chat, the keyboard moves up the feed along with the message. We chose Inline Keyboards as the default because they are the most flexible. Inline Keyboards have the following properties:
- They can have both labels and values
- Clicking on an inline keyboard button does not place a message into the channel feed - it sends the value back to Flow XO
- If you don't specify a value for an inline keyboard key, the label will be used as a value
- You can specify a URL as the value of an inline keyboard key, and telegram will make that key an external hyperlink to the corresponding website
- Inline keyboards can be edited using the Telegrams message editing functions, and this allows you to simulate navigation through a hierarchical menu. For example, you may present a menu with Help and Contact Us, and if the user clicks Help, you may edit the menu to have two new buttons Video Help or FAQ, without adding any new messages to the channel feed.
- Inline keyboards support several special values that trigger certain functionality within Telegram:
- pay - when you use the word "pay" as the value of a button *in a send invoice message* then the keyboard button will trigger the Telegram payment flow. This must be the FIRST button in your keyboard if you use it.
Pay Me Or Else! [pay]
- login_url:... - If you are using Telegrams login feature you can specify the login url for a keyboard button like this:
Log Me In[login_url:https://loginurl]
- switch_inline_query:..., switch_inline_query_current_chat:... - you can use these special values to provide an inline query and switch the users chat UI to an inline query. This is only useful if you are using Inline Queries with Flow XO, which is not recommended under most circumstances.
- pay - when you use the word "pay" as the value of a button *in a send invoice message* then the keyboard button will trigger the Telegram payment flow. This must be the FIRST button in your keyboard if you use it.
Standard Keyboards
Standard keyboards replace the usual QWERTY keyboard with your custom keyboard. There is only one standard keyboard usable at any one time, and standard keyboards are not attached to the message with which they were sent. If you send a new standard keyboard, the previous one will be replaced. Another major difference is that clicking a standard keyboard key will put the text on the key into the message stream as if you had typed it, unlike inline keyboards that send the value to Flow XO behind the scenes. Standard keyboards have the following properties:
- They can ONLY have labels. If you specify a value for a key in a standard keyboard it will be ignored.
- Exactly what you specify in the label will be sent as a normal message when the user clicks it.
- Standard keyboards cannot be edited along with a message (because they aren't connected to a specific message). You can, however, remove a standard keyboard.
- Standard keyboards are not allowed in channels, though they can be used in groups.
- Standard keyboards also support several special values that trigger certain functionality in Telegram:
- request_contact - this special value will prompt the user to send contact information.
- request_location - this will prompt the user to send their location
- request_poll - this special value will prompt the user to create a poll or quiz to post into the group or channel
- request_quiz - this special value will prompt the user to create a quiz. A poll will not be allowed.
- request_only_poll - this special value will prompt the user to create a poll. A quiz will not be allowed.
- web_app - this special value will cause a Telegram mini app to be launched using the provided URL. You can pass data to the webapp by adding query string parameters, such as ?my_param={{my_trigger.attributes__myattribute}}. We will automatically add the current user's response path of the user as well, using the parameter name __rp.
- Some examples:
Create a Poll or Quiz[request_poll] | Create a Poll[request_only_poll] | Create a Quiz[request_quiz] | Launch my app[web_app:https://www.myapp.com]
Remove Keyboard
The Remove Keyboard keyboard type does what it says - it simply removes the standard keyboard, leaving only the regular QWERTY keyboard. Flow XO uses this function after users select a quick reply to remove the quick reply button.
Force Reply
Setting this option will require the user to reply to your message with some text. Unfortunately it is not possible to combine Force Reply with any other keyboard markup, so even if you specify a custom keyboard, if you use this Keyboard Type it will be ignored.
That's It!
You are now ready to go out and conquer the world with complex menu systems and fancy keyboard buttons. Let us know if you encounter any bugs or need any help implementing custom keyboards in your solutions.