Telegram Actions

Methods

Messaging: Send Message, Forward Message, Copy Message, Send Photo, Send Sticker, Send Audio, Send Document, Send Video, Send Animation, Send Voice, Send Video Note, Send Location, Send Venue, Send Contact, Send Poll, Send Dice
Editing Messages: Edit Message Text, Edit Message Caption, Edit Message Media, Edit Message Keyboard, Edit Message Live Location, Stop Message Live Location, Delete Message, Stop Poll
Payments: Send Invoice, Answer Shipping Query
Misc: Get Chat Info, Answer Inline Query, Pin Chat Message, Unpin Chat Message, Unpin All Chat Messages 

Overview

One of the great things about Flow XO is that you can build bots that will work the same across multiple channels, such as Telegram, Facebook Messenger, or WhatsApp. To enable this "build once deploy anywhere" functionality, we must limit the capabilities of our core messaging tools to features that are shared by all of the channels we support. This is great if you're building for multiple channels, but it can be limiting if you want to take full advantage of a particular platform, such as Telegram. Please note that we have similar integrations for Facebook Messenger and our Web Messenger.

Telegram as a messaging platform is a powerful and feature rich platform complete with quizzes, an in-chat multi-processor payments system, the ability to edit previously sent messages, and much more. You can even ask it to generate a random number and send your users one of a variety of fun dice rolling animations. 

User Friendly Access to the Telegram API

Flow XO has always allowed users to take advantage most of each channels special features using our Custom Request action. This allows you to call a particular channels API using raw JSON code. It works, but it requires some technical skill and makes it very easy to make mistakes. So while we still provide the option of sending a Custom Request for highly technical Telegram power users, we now offer a much more user friendly way to access Telegrams powerful features, the Telegram Actions integration. You can find this powerful tool under More Services, along with our third party integrations and chat utilities:

Filtering By Platform

Since the methods in this integration will ONLY work on Telegram, you can only use them in a flow that you only intend to deploy to Telegram OR you must use a filter to only execute the task when the current channel is Telegram. Each trigger provides a 'Bot Platform' field that can be used for this purpose:

Messaging Actions

There are a LOT of different types of messages you can send in Telegram. They all have several properties in common, most of which you'll rarely use. Here they are:

1. Parse Mode
Whenever a message includes free text, such as when sending a text message or send a caption along with some media, you can set the 'Parse Mode', which tells Telegram how to interpret any formatting you have applied. Your two choices are HTML and Markdown.

2. Disable Web Page Preview
Normally when you send a link in a message it is "expanded" by Telegram, meaning it will try to find a good thumbnail and summary of the link to show in the chat. If you don't want this to happen, you can set Disable Web Page Preview to true.

3. Disable Notification
Setting Disable Notification to true will cause your message to be sent "silently" - meaning the user will not be notified that a new message has arrived. They will see your new message next time they view the chat though.

4. Message Topic ID
The topic ID for forum groups

5. Reply To Message ID
If you want to specifically indicate that the message you are sending is a reply to another message you can put the Message ID of the other message in this field. You will find the Message ID of the user message that triggered the current flow in the Metadata of the trigger, so if you need to you can pull it out of there.

6. Allow sending without reply
If you DO set a Reply To Message ID, but that ID is not a valid message on Telegram, setting Allow sending without reply will cause the message to be sent anyway, not as a reply but as a new message.

7. Keyboard
You can send a custom keyboard with every message. This is an extremely powerful feature with a lot of options, and Telegram offers several types of keyboards, a Reply Keyboard, and Inline Keyboard and a Remove Keyboard. Each has different properties and can be used in different situations. One amazing feature of Telegram is that you can edit the keyboard of a message in place, which means you can change the option buttons presented to simulate a hierarchical menu. Please see this article for more on working with keyboards: Telegram Keyboards. For the most simple use case, you can add a row of buttons on each line of the Keyboard input field, and on a single line separate buttons by the pipe symbol ( | ). Here is an example:

Buy Now | Talk to an Agent | Main Menu
Order Status | Return an Item

would result in the following keyboard:

8. Keyboard Type
There are three kinds of keyboards you can use:

Inline - an inline keyboard is attached to the message it is sent with. It is displayed immediately underneath the message as a set of buttons, NOT as a replacement or alternative to the main keyboard. Inline keyboards are special in that they can be edited later, and they can be attached to a URL or a different value than their label. Inline keyboards can also be used to send messages in a Telegram Channel, whereas a classic keyboard can not. Furthermore, when an inline keyboard button is pressed, the value of the button is not sent as a standard message, it is send behind the scenes and will not appear in the chat window.

Standard - the standard keyboard provides an alternative to the normal QUERTY keyboard you use to input messages. Standard keyboards stick around for multiple messages until they are changed or removed, and aren't tied to a specific message like an inline keyboard. Standard keyboards will input the label of each keyboard button directly into the chat, so whatever the label of the button was shows as a sent message by the user. Standard Keyboards can NOT be used in Telegram Channel messages.

Remove Keyboard - The "Remove Keyboard" keyboard isn't a keyboard at all, but it sends a command to Telegram to remove the most recent custom Standard keyboard. Flow XO uses this feature regularly to remove "Quick Replies" from the chat once they have been pressed. The most common reason to use this is to present the user with some options using a standard keyboard, then once an option has been chosen, remove the keyboard since the bot is no longer going to be expecting or know how to process further button presses.

Force Reply - This is also not really a keyboard, but tells Telegram that the user MUST reply to your message. The only reply they can make is a text reply. Use this feature sparingly.

Please see more about Telegram keyboards here: https://support.flowxo.com/article/258-telegram-keyboards

Getting User Input

When using the usual Flow XO messaging tasks, if you want to gather input from the user you would use an Ask a Question task. This send the user a message, some optional quick reply options, and then pauses the flow until the users responds. Once they do, the data they sent is available as an output of the Ask a Question.

The Telegram Actions integration does not have a concept of an Ask a Question, but it DOES give you the ability to prompt the user for input in more ways than Ask a Question, using custom keyboards, for example, or when sending a user a non-anonymous quiz. To gather user input in these contexts, please use the Wait for a Response task. It behaves exactly like Ask a Question, except that it is lacking the validation features. You will have to handle any validation on our own.

As an added bonus, we have modified how file attachments are processed, and you can now ask your user to submit a file and then place a Wait for a Response action immediately afterwards. When your user uploads the file, be it an image, a video, a contact, or any other media that their messenger can send, the Wait for a Response action will capture the file info as metadata. It is no longer necessary to have separate flows and New File Triggers to collect uploads from users!

You can use this to collect media from your users and then grab the File ID from the received metadata and post that media in another group or channel, or you can simply store the file URL in a database for later use.

Send Message

Send message is as simple as it sounds. It sends a text message into the chat.
See: https://core.telegram.org/bots/api#sendmessage

Forward Message

Forward message will forward a previously sent or received message to another user/group/channel.
See: https://core.telegram.org/bots/api#forwardmessage

Copy Message

Copy message will copy a previously received/sent message to another user/group/channel, and also allow you to modify the caption or reply keyboard as needed.
See: https://core.telegram.org/bots/api#copymessage

Send Photo

Send photo will deliver an image into the chat, along with an optional caption. As with all the various "send media" commands, you can identify the photo you want to send with a publicly available URL or a Telegram File ID. Using a Telegram File ID will be more efficient and perform better. You can get the Telegram File ID of an image or any other piece of media by sending it to your Telegram Bot directly and using a "New File Trigger" to listen for incoming files. The Telegram File ID will be present in the trigger metadata.
See:  https://core.telegram.org/bots/api#sendphoto

Send Sticker

Send a Telegram sticker into the chat or an image in the new WEBP format. 
See:  https://core.telegram.org/bots/api#sendsticker

Send Audio

Send Audio lets you send a playable audio clip into the chat with an optional caption.
See: https://core.telegram.org/bots/api#sendaudio

Send Document

Send an arbitrary file into the chat for your users to download.
See: https://core.telegram.org/bots/api#senddocument

Send Video

Send a video into the chat, with an optional caption.
See: https://core.telegram.org/bots/api#sendvideo

Send Animation

Use this to send an animated GIF, with an optional caption.
See: https://core.telegram.org/bots/api#sendanimation

Send Voice

Use this to send a voice encoded audio file using a URL or a Telegram File ID. A good way to get such an audio recording is to use the audio recorder within Telegram and send an audio file to your bot. Using a New File Trigger, you can capture the metadata in Flow XO and extract the File ID in the Interactions tab, which can then be used to send the file to your audience.
See: https://core.telegram.org/bots/api#sendvoice

Send Video Note

Use this to send a video you recorded on the Telegram video recorder. Send the file to your bot and use a New Message trigger to catch it and capture the metadata, which will be available in the Interactions tab and which you can use to extract the correct File ID to send the video note to your audience.
See: https://core.telegram.org/bots/api#sendvideonote

Send Location

You can use Send Location to send your users a location on earth - it can be an address, or just a lat/lon. Telegram will display a nice little map.
See: https://core.telegram.org/bots/api#sendlocation

Send Venue

This is very similar to Send Location, but you can include other information about the venue, such as its Foursquare ID or Google Place ID, among other things.
See: https://core.telegram.org/bots/api#sendvenue

Send Contact

Send contact information into the chat. You can include a rich set of contact information, including an entire vCard if you like.
See: https://core.telegram.org/bots/api#sendcontact

Send Poll

This powerful function lets you send your users a poll or a quiz. They are both a single question with up to 10 answers. The poll can be single or multiple response, and displays the poll results to users once they have completed it. The quiz is like a poll, but has a single right answer, and your users will be told if they got the question correct or not. Polls will be most effective when sending messages to a Telegram Group or a Telegram Channel, as a poll of 1 may not yield interesting results. Quizzes can be useful in a group and private setting. Note that Flow XO can receive the poll response from the user only if the poll or quiz is NOT set to be anonymous. If you want to wait for the user to answer a poll and then process their response, make sure to put a Wait for a Response task AFTER your Send a Poll task.
See: https://core.telegram.org/bots/api#sendpoll

Editing Messages

Telegram provides a number of functions that allow you to edit or delete messages you have already sent. The most common use of this feature is to provide navigation within the chat window without cluttering up the chat window with buttons as your users navigate a menu hierarchy. To edit a message you must have a Telegram Message ID, a unique identifier that Telegram assigns to every message sent on the platform. The standard Flow XO messaging tools, such as Send Message, Send Video, etc, do not return the Telegram Message ID in a way that you can use. However, each of the tools provided by the Telegram Actions integration DO return the Message ID, so as long as you are using this toolkit to send your Telegram messages, you can edit them. 

Example Flow

Install this sample flow into your account to see how to combine Edit Message actions with Wait for a Response to edit the message and keyboard of a message based on the users input.

Where to Find the Message ID

When you send a message with the Telegram Actions integration, the Message ID (along with quite a bit of other potentially useful information) is returned in the Response Data of the task. The Message ID is also returned in the Response Data when you send a Custom Request. Here's what it looks like in the Interaction explorer for messages sent with the Telegram Actions integration:

You can use this ID in any of the edit tasks by using a variable, like this {{send_a_message.response_data__result__message_id}}:

Edit Message Text

As you might have guessed from the name, you can use Edit Message Text to change the text of a message. As with most of the edit methods, you can also change the keyboard when editing the message. If you ONLY want to edit the keyboard, there is a separate command for that.
See: https://core.telegram.org/bots/api#editmessagetext

Edit Message Caption

If you sent a media message, and you want to change the caption of the media, you can do so with Edit Message Caption. As with Edit Message Text, this will edit the keyboard as well.
See: https://core.telegram.org/bots/api#editmessagecaption

Edit Message Media

In addition to editing the text or caption of a message, you can also edit the media of any media message you send, replacing the picture, video, etc with another. You can only replace a media file with another media file of a similar type. For example you can replace one audio file with another, but cannot replace an audio file with a video.
See: https://core.telegram.org/bots/api#editmessagemedia

Edit Message Keyboard

Edit Message Keyboard allows you to edit the inline keyboard of a message without editing anything else about the message. Note that you can only edit inline keyboards this way - standard keyboards won't work.
See: https://core.telegram.org/bots/api#editmessagekeyboard

Edit Message Live Location

If you have started sending a live location in one your chats you can update/modify your currently reported location using this command.
See: https://core.telegram.org/bots/api#editlivelocation

Stop Message Live Location

End a live location session..
https://core.telegram.org/bots/api#stopmessagelivelocation

Delete a Message

You can use this command to delete a message entirely.
See: https://core.telegram.org/bots/api#stopmessagelivelocation

Stop Poll

Close an open poll to new responses.
See: https://core.telegram.org/bots/api#stoppoll

Payments

Telegram provides an easy to integrate, easy to payments platform that allows you to sell your products using a range of payment providers that service many different international regions. While Flow XO includes a built in Payments feature, it is limited to Stripe and uses a web-based workflow that requires your users to complete payment outside of Telegram's messenger. If you are selling mostly within Telegram, the Telegram Payments platform provides a much more streamlined user experience, and a wider range of payment providers.

The Flow XO Telegram Actions integration can help you sell both digital and physical products, including dynamic shipping information.

Telegram provides documentation on getting set up on their platform which we won't replicate here. Please follow the instructions here, and once you're done you'll have a payments token that you can use to send invoices with Flow XO. For the majority of use cases, processing payments with Flow XO is as simple as:

  • Sending an Invoice
  • Waiting for the payment confirmation

In more advanced scenarios, if you choose flexible shipping, you will also have an additional step:

  • Answering a shipping query

Send an Invoice

Send an Invoice is the main method you will use when working with Telegram Payments. It includes a large number of options, and lets you set your product title, image, description, pricing, etc. You can also indicate if you require email address, phone number or shipping address before accepting an order. For a complete description of each parameter and how it should be used, please see: https://core.telegram.org/bots/api#sendinvoice

One thing we'll call out here is the Pricing section - pricing is always specified as a whole number, where the last two digits of the number are the fractional amount of whatever currency you are using. For example, if you are charging in US dollars, 100 would represent $1.00, 50000 would be $500.00, etc. You can specify multiple components to your price, such as the product price, tax, service fees, etc. In the image below, the price will be $3.00 - $1.00 for something, and $2.00 for something else.

Custom Payment Button

You can include a custom keyboard in your Send Invoice message - but the first button in the keyboard MUST be a Payment button. You can specify a payment button in Flow XO by putting the word "pay" in square brackets after the label, like this:

Responding to the payment confirmation

When the user clicks your Payment button and completes the payment process, Flow XO will receive a message with the text "payments:success" as the message, and in the metadata will be information about the order, including a confirmation code from your payment provider. To respond to your users after they have made a payment, you have two options. You can create a trigger with the trigger phrase "payments:success", or you can wait for the confirmation in the same flow you sent the invoice using a Wait for a Response task:

After the payment is made, you can access information about the order in the metadata:

Answer Shipping Query

If, in your invoice, you set the "Is Flexible" parameter to true, then Telegram will need to present the user with shipping costs. This feature is only used if you plan to dynamically calculate the shipping pricing based on the shipping address provided by your customer. In this case, you will need to wait for Telegram to send a shipping query using a Wait for a Response task, like so:

Once you receive the shipping query, you can examine the metadata to help you calculate shipping costs (possibly on a per carrier basis):

Once you receive this query, you must respond with an Answer Shipping Query Message:

You will need to reference the ID of the Shipping Query, and provide the pricing information. Specify prices with the fractional component as the last two digits as with invoices:

Misc Functions

In addition to the main functions described in the article above, we also support a handful of lesser used miscellaneous functions you can use to get information about a specific channel, pin or unpin chat messages that the bot has sent, or even answer inline queries. The last one, inline queries, is a powerful feature in Telegram that can help you spread your bot virally if you have useful content users can search for and share with each other. Why aren't we featuring our support for it more prominently? The reason is that the normal chat mechanisms of Flow XO are not ideally suited to inline queries for a couple of reasons. The most import of which is that it would be very expensive for you to run inline queries using our normal pricing model, because Telegram will send an inline query every several keystrokes while users are typing out their search. Each one will cause an interaction to be counted. Another reason is that for inline queries to give a great user experience, they should get a very fast response as they are searching. Our system is not optimized for that, but is optimized for passing messages and executing bot logic. We may in the future provide more robust, special purpose support for inline queries, but in the meantime we provide the Answer Inline Query tool in case you are a very advanced user and want to use it with Flow XO despite the drawbacks just described. If your use case must have inline queries and you have coding skills or a developer available to you, we have an experimental feature that would allow you to handle inline queries using a cloud function (even a free one like Pipedream can work). Please e-mail support@flowxo.com to discuss if you are interested in exploring this feature.

Without further ado, here is the list of miscellaneous functions we support:

Get Chat Info

The Get Chat Info method is actually three telegram commands rolled into one. All three are mostly relevant to groups and channels:

Answer Inline Query

Answer Inline Query was discussed at the beginning of this section. Although it is supported using this integration, you are encouraged to use it at your own risk as it can rack up a large number of interactions quickly. Please read more about inline queries here: https://core.telegram.org/bots/api#inline-mode

Pin Chat Message

Give this command the ID of a chat message your bot sent and it will pin it to the channel, so that your users will see it in the chat at all times until unpinned.
See: https://core.telegram.org/bots/api#pinchatmessage

Unpin Chat Message

Pinned a chat message? This command lets you un-pin it.
See: https://core.telegram.org/bots/api#unpinchatmessage

Unpin All Chat Messages

Unpin all messages your bot has pinned.
See: https://core.telegram.org/bots/api#unpinallchatmessages

That's All Folks!

We hope you get some good use out of these Telegram functions. Telegram is a wonderful and powerful platform for both direct audience interactions as well as fostering communities in groups and channels, and the Telegram Actions Integration should help you take fuller advantage of all those features without fiddling with custom JSON requests. Let us know if you find any bugs, need help understanding one of these methods, or see something from the API that you need that we didn't handle here. As always, please feel free to reach out to support@flowxo.com

Still need help? Contact Us Contact Us