Telegram Bot
Getting Started with Telegram Bot
Prerequisites
- A configured Bot via Telegram app. You can download the Telegram Desktop app at desktop.telegram.org.
- In order to use the Telegram app, your mobile phone number has to be provided.
Configuring the Telegram Bot
1. Go to https://telegram.me/BotFather.
2. To create a new bot type /newbot
to the message box and press enter.
3. Enter the name of the user name of your new bot.
You have received the message from BotFather containing the token, which you can use to connect Telegram Bot to Integromat.
To add your bot to your Telegram application, click the link in the message from BotFather or enter it manually to your browser. The link is t.me/yourBotName
.
Adding Telegram Bot to your Scenario
Follow Step 1 in the Creating a scenario article (choose the Telegram Bot module instead of Twitter and Facebook module).
After the module is added to your scenario you can then see the Scenario editor.
Define what function you need your module to have. Here you can choose between three types of modules – Triggers, Actions, and Searches.
Did you know?
You can find more than 65 sample scenario templates with Telegram Bot modules at www.integromat.com/en/templates/telegram
Triggers
Watch Updates
Use this trigger to watch for Telegram updates, such as a new message or a new file.
Webhook | In order to add a webhook you need to establish a connection to your Telegram bot. Use the token provided by the BotFather (see the steps above, Configuring the Telegram Bot). |
The connection between Telegram Bot and Integromat is now established. You can continue with other Telegram Bot actions.
Restrict a Chat Member
This function allows you to set user rights within a supergroup.
Promote the bot to Admin via the View group info option:
Connection | Establish a connection to your Telegram Bot using the provided token. |
Chat ID |
You can determine the Chat ID using the Telegram Bot > Watch Updates trigger: 1. Place the Watch Updates module in the scenario. 6. Find the ID in the output bundle: 7. Use the ID in the desired module field (you can also use the loaded tag). |
User ID |
Enter the ID of the user you want to restrict. User ID can be retrieved with the help of the special Telegram bot userinfobot. 1. Add the userinfobot to your Telegram app.
2. Go to the chat with the user you want to retrieve the ID from. 3. Forward his message to userinfobot. 4. Copy the User ID and paste it to the desired Integromat module. |
Until date | Set the date that the restrictions will apply til. Valid date formats can be found here. (E.g. 06/20/2016 ) |
Set if the user can send messages | Set Yes if the user is allowed to send messages. Set No to disallow user to send messages in the supergroup. Message can be text message, contact, location and venue. |
Set if the user can send media messages | Set Yes if the user is allowed to send media messages. Set No to disallow user to send audio files, documents, photos, videos, video notes and voice notes in the supergroup. |
Set if the user can send other messages | Set Yes if the user is allowed to send other messages. Set No to disallow user to send animations, games, stickers and use inline bots. |
Set if the user can add web page previews | Set Yes if the user may add web page previews to their messages. |
Promote a Chat Member
Use this action to promote or demote a member of a supergroup or a channel.
Connection | Establish a connection to your Telegram Bot using the provided token. |
Chat ID | To set the Chat ID follow these instructions. |
User ID | To set the User ID follow these instructions. |
Set if the administrator can change info | Select Yes if the administrator can change the chat title, photo and other settings. |
Set if the administrator can create channel posts | Select Yes if the administrator can create channel posts [channels only]. |
Set if the administrator can edit messages | Select Yes if the administrator can edit messages of other users and can pin messages [channels only]. |
Set if the administrator can delete messages | Select Yes if the administrator can delete messages of other users [channels only]. |
Set if the administrator can invite users | Select Yes if the administrator can invite new users to the chat. |
Set if the administrator can restrict members | Select Yes if the administrator can restrict, ban or unban chat members. |
Set if the administrator can pin messages | Select Yes if the administrator can pin messages [supergroups only]. |
Set if the administrator can promote members | Select Yes if the administrator can add new administrators with a subset of his own privileges or demote administrators that he has promoted, directly or indirectly (promoted by administrators that were appointed by him). |
Send a text message or reply
This action sends a message or a reply to your Telegram desktop app.
Connection | Establish a connection to your Telegram Bot using the provided token. |
Chat ID | To set the Chat ID follow these instructions. |
User ID | To set the User ID follow these instructions. |
Text | Enter (or map) the text content of the message you want to send. |
Parse mode |
Specify how you want your text to be recognized. HTML or Markdown. Markdown syntax:
HTML syntax:
|
Disable notification | Select Yes to send messages silently. iOS users will not receive a notification, Android users will receive a notification with no sound. |
Disable link previews | Select Yes to disable link previews for links in this message. |
ID of the original message |
ID of the original message if the message is a reply. |
Reply markup - additional interface options |
Enter additional interface options that are a JSON-serialized object for an inline keyboard, custom reply keyboard, instructions to remove reply keyboard or to force a reply from the user, e.g. {"inline_keyboard":[[{"text":"Some button text 2","url":"https://botpress.org"}]]} or {"keyboard":[["Yes","No"],["Maybe"]]} More information about custom keyboards can be found on the Telegram Bot API page. |
Kick a Chat Member
Use this action to kick a user from a channel, group or supergroup.
Connection | Establish a connection to your Telegram Bot using the provided token. |
Chat ID | To set the Chat ID follow these instructions. |
User ID | To set the User ID follow these instructions. |
Until date | Set the date that the user will be banned from the chat til. Valid date formats can be found here. (E.g. 06/20/2016 ) |
Send an Audio File
Connection | Establish a connection to your Telegram Bot using the provided token. |
Chat ID | To set the Chat ID follow these instructions. |
Caption | Enter the caption of the audio. |
Send by |
Audio file to send. Pass a file_id as a string to send an audio file that exists on the Telegram servers (recommended), pass an HTTP URL as a string for Telegram to get an audio file from the Internet, or upload a new one using multipart/form-data. Further details about sending audio files can be found on the Telegram Bot API page. For example, you can use your Dropbox to process the file. |
Disable notification | Select Yes to send messages silently. iOS users will not receive a notification, Android users will receive a notification with no sound. |
Duration | Enter the duration of the sent video in seconds. |
Performer | Enter a performer. |
Title | Enter a track name. |
Reply markup - additional interface options |
Enter additional interface options that are a JSON-serialized object for an inline keyboard, custom reply keyboard, instructions to remove reply keyboard or to force a reply from the user, e.g. {"inline_keyboard":[[{"text":"Some button text 2","url":"https://botpress.org"}]]} or {"keyboard":[["Yes","No"],["Maybe"]]} More information about custom keyboards can be found on the Telegram Bot API page. |
Content type |
Select or enter the MIME type of data. |
Send a Document or an Image
Connection | Establish a connection to your Telegram Bot using the provided token. |
Chat ID | To set the Chat ID follow these instructions. |
Caption | Enter the caption of the audio. |
Send by | Image file to send. Pass a file_id as a string to send a file that exists on the Telegram servers (recommended), pass an HTTP URL as a string for Telegram to get a file from the Internet, or upload a new one using multipart/form-data. Further details about sending files can be found on the Telegram Bot API page. |
Parse mode |
Specify how you want your text to be recognized. HTML or Markdown. Markdown syntax:
HTML syntax:
|
Disable notification | Select Yes to send messages silently. iOS users will not receive a notification, Android users will receive a notification with no sound. |
Content type | Select or enter the MIME type of data. |
ID of the original message | The ID of the original message if the message is a reply. |
Reply markup - additional interface options |
Enter additional interface options that are a JSON-serialized object for an inline keyboard, custom reply keyboard, instructions to remove reply keyboard or to force a reply from the user, e.g. {"inline_keyboard":[[{"text":"Some button text 2","url":"https://botpress.org"}]]} or {"keyboard":[["Yes","No"],["Maybe"]]} More information about custom keyboards can be found on the Telegram Bot API page. |
Send a Video
Connection | Establish a connection to your Telegram Bot using the provided token. |
Chat ID | To set the Chat ID follow these instructions. |
Caption | Enter the caption of the video. |
Send by | Image file to send. Pass a file_id as a string to send a file that exists on the Telegram servers (recommended), pass an HTTP URL as a string for Telegram to get a file from the Internet, or upload a new one using multipart/form-data. Further details about sending files can be found on the Telegram Bot API page. |
Disable notification | Select Yes to send messages silently. iOS users will not receive a notification, Android users will receive a notification with no sound. |
Content type | Select or enter the MIME type of data. |
Duration | Enter the duration of sent video in seconds. |
Width | Enter the video width. |
Height | Enter the video height. |
Reply markup - additional interface options |
Enter additional interface options that are a JSON-serialized object for an inline keyboard, custom reply keyboard, instructions to remove reply keyboard or to force a reply from the user, e.g. {"inline_keyboard":[[{"text":"Some button text 2","url":"https://botpress.org"}]]} or {"keyboard":[["Yes","No"],["Maybe"]]} More information about custom keyboards can be found on the Telegram Bot API page. |
Send a Sticker
Connection | Establish a connection to your Telegram Bot using the provided token. |
Chat ID | To set the Chat ID follow these instructions. |
Send by | Image file to send. Pass a file_id as a string to send a file that exists on the Telegram servers (recommended), pass an HTTP URL as a string for Telegram to get a file from the Internet, or upload a new one using multipart/form-data. Further details about sending files can be found on the Telegram Bot API page. |
Disable notification | Select Yes to send messages silently. iOS users will not receive a notification, Android users will receive a notification with no sound. |
ID of the original message | ID of the original message if the message is a reply. |
Reply markup - additional interface options |
Enter additional interface options that are a JSON-serialized object for an inline keyboard, custom reply keyboard, instructions to remove reply keyboard or to force a reply from the user, e.g. {"inline_keyboard":[[{"text":"Some button text 2","url":"https://botpress.org"}]]} or {"keyboard":[["Yes","No"],["Maybe"]]} More information about custom keyboards can be found on the Telegram Bot API page. |
Send an Album
Connection | Establish a connection to your Telegram Bot using the provided token. |
Chat ID | To set the Chat ID follow these instructions. |
Media | Select the items you want to add to your album. |
Disable notification | Select Yes to send messages silently. iOS users will not receive a notification, Android users will receive a notification with no sound. |
Reply markup - additional interface options |
Enter additional interface options that are a JSON-serialized object for an inline keyboard, custom reply keyboard, instructions to remove reply keyboard or to force a reply from the user, e.g. {"inline_keyboard":[[{"text":"Some button text 2","url":"https://botpress.org"}]]} or {"keyboard":[["Yes","No"],["Maybe"]]} More information about custom keyboards can be found on the Telegram Bot API page. |
Send a Video Note
Connection | Establish a connection to your Telegram Bot using the provided token. |
Chat ID | To set the Chat ID follow these instructions. |
Send by |
Image file to send. Pass a file_id as a string to send a file that exists on the Telegram servers (recommended), pass an HTTP URL as a string for Telegram to get a file from the Internet, or upload a new one using multipart/form-data. Further details about sending files can be found on the Telegram Bot API page. |
Disable notification | Select Yes to send messages silently. iOS users will not receive a notification, Android users will receive a notification with no sound. |
Content type | Select or enter the MIME type of data. |
Length | Video width and height, i.e. diameter of the video message. |
Duration | Enter the duration of sent video (in seconds). |
Reply markup - additional interface options |
Enter additional interface options that are a JSON-serialized object for an inline keyboard, custom reply keyboard, instructions to remove reply keyboard or to force a reply from the user, e.g. {"inline_keyboard":[[{"text":"Some button text 2","url":"https://botpress.org"}]]} or {"keyboard":[["Yes","No"],["Maybe"]]} More information about custom keyboards can be found on the Telegram Bot API page. |
ID of the original message |
ID of the original message if the message is a reply. |
Send a Photo
Connection | Establish a connection to your Telegram Bot using the provided token. |
Chat ID | To set the Chat ID follow these instructions. |
Caption | Enter the caption of the video. |
Send by |
Image file to send. Pass a file_id as a string to send a file that exists on the Telegram servers (recommended), pass an HTTP URL as a string for Telegram to get a file from the Internet, or upload a new one using multipart/form-data. Further details about sending files can be found on the Telegram Bot API page. |
Parse mode |
Specify how you want your text to be recognized. HTML or Markdown. Markdown syntax:
HTML syntax:
|
ID of the original message | ID of the original message if the message is a reply. |
Reply markup - additional interface options |
Enter additional interface options that are a JSON-serialized object for an inline keyboard, custom reply keyboard, instructions to remove reply keyboard or to force a reply from the user, e.g. {"inline_keyboard":[[{"text":"Some button text 2","url":"https://botpress.org"}]]} or {"keyboard":[["Yes","No"],["Maybe"]]} More information about custom keyboard can be found on the Telegram Bot API page. |
Send a Voice Message
Connection | Establish a connection to your Telegram Bot using the provided token. |
Chat ID | To set the Chat ID follow these instructions. |
Caption | Enter the caption of the voice message. |
Send by | Image file to send. Pass a file_id as a string to send a file that exists on the Telegram servers (recommended), pass an HTTP URL as a string for Telegram to get a file from the Internet, or upload a new one using multipart/form-data. Further details about sending files can be found on the Telegram Bot API page. |
Disable notification | Select Yes to send messages silently. iOS users will not receive a notification, Android users will receive a notification with no sound. |
Content type | Select or enter the MIME type of data. |
Duration | Enter the duration of sent video in seconds. |
Reply markup - additional interface options |
Enter additional interface options that are a JSON-serialized object for an inline keyboard, custom reply keyboard, instructions to remove reply keyboard or to force a reply from the user, e.g. {"inline_keyboard":[[{"text":"Some button text 2","url":"https://botpress.org"}]]} or {"keyboard":[["Yes","No"],["Maybe"]]} More information about custom keyboards can be found on the Telegram Bot API page. |
Delete a Message
Connection | Establish a connection to your Telegram Bot using the provided token. |
Chat ID | To set the Chat ID follow these instructions. |
Caption | Enter the caption of the voice message. |
Message ID |
Enter the Message ID. |
Get the Number of Members in a Chat
Connection | Establish a connection to your Telegram Bot using the provided token. |
Chat ID | To set the Chat ID follow these instructions. |
Download a File
Downloads a file from the Telegram server.
Connection | Establish a connection to your Telegram Bot using the provided token. |
File ID |
Enter the ID of the file that has been already uploaded to the Telegram server. |
Forward a Message
Connection | Establish a connection to your Telegram Bot using the provided token. |
Chat ID | To set the Chat ID follow these instructions. |
From chat ID | Enter an ID of the chat where the original message was sent. |
Message ID | Enter the message ID of the message you want to forward. |
Edit a media message
Connection | Establish a connection to your Telegram Bot using the provided token. |
Chat ID | To set the Chat ID follow these instructions. |
Message ID | Enter the message ID of the message you want to forward. |
Media type | Select whether you want to edit a photo or video. |
Caption | Enter the photo/video caption. |
Source file | Define the source file you want to edit. More information about working with files. |
Parse mode |
Specify how you want your text to be recognized. HTML or Markdown. Markdown syntax:
HTML syntax:
|
Edit a Text Message
Connection | Establish a connection to your Telegram Bot using the provided token. |
Chat ID | To set the Chat ID follow these instructions. |
Message ID | Enter the message ID of the message you want to forward. |
Text | Enter (or map) the text content of the message you want to send. |
Parse mode |
Specify how you want your text to be recognized. HTML or Markdown. Markdown syntax:
HTML syntax:
|
Disable link previews |
Select Yes to disable link previews. |
Reply markup - additional interface options |
Enter additional interface options that are a JSON-serialized object for an inline keyboard, custom reply keyboard, instructions to remove reply keyboard or to force a reply from the user, e.g. {"inline_keyboard":[[{"text":"Some button text 2","url":"https://botpress.org"}]]} or {"keyboard":[["Yes","No"],["Maybe"]]} More information about custom keyboards can be found on the Telegram Bot API page. |
Send media by URL or ID
Connection | Establish a connection to your Telegram Bot using the provided token. |
Chat ID | To set the Chat ID follow these instructions. |
Media type | Select whether you want to edit a photo or video. |
Caption | Enter the photo/video caption. |
Send by |
Select a file. Set a file_id as a string to send a file that exists on the Telegram servers (recommended), or select an HTTP URL as a string for Telegram to get a file from the Internet. |
Disable notification | Select Yes to send messages silently. iOS users will not receive a notification, Android users will receive a notification with no sound. |
ID of the original message |
ID of the original message if the message is a reply. |
Reply markup - additional interface options |
Enter additional interface options that are a JSON-serialized object for an inline keyboard, custom reply keyboard, instructions to remove reply keyboard or to force a reply from the user, e.g. {"inline_keyboard":[[{"text":"Some button text 2","url":"https://botpress.org"}]]} or {"keyboard":[["Yes","No"],["Maybe"]]} More information about custom keyboards can be found on the Telegram Bot API page. |
Searches
Get Updates
List of possible updates can be found on the Telegram Bot API page.
Connection | |
limit | Set the limit of returned updates. Values between 1—100 are accepted. |
offset | Identifier of the first update to be returned. Must be greater by one integer than the highest among the identifiers of the previously received updates. |
Get a List of Administrators in a Chat
Retrieves a list of administrators from a selected chat.
Chat ID |
Enter the chat ID of the chat you want to retrieve the list of administrators from |
Get Chats
Use this search to get up-to-date information about the chat.
Troubleshooting
Adding Your Bot To the Channel:
1. Click the right mouse button on the channel name and select the View channel info option.
2. Click the Add Member icon next to the member number.
3. Start typing the name of your bot in the search field.
4. Click on the bot name to select the bot you want to add to the channel.
5. Click the INVITE button.
6. Make the bot admin by clicking the respective button.
7. Assign the permissions to your bot and click the SAVE button.
The bot has been added to the channel.
Testing a Public Channel
To test the public channel you need to obtain the Chat ID. The Chat ID is part of the channel link.
If the public channel link is, for example, t.me/IMTtest, then @IMTtest
is your Chat ID.
Now, you can send a message to the public channel using the Send a Text Message or a Reply module.
Testing a Private Channel:
You need to obtain the Chat ID to test the private channel.
There are three options to retrieve the ID:
- Retrieve the ID from the web version of Telegram.
- Switch the private channel to the public channel, then retrieve the ID (by sending or receiving the message in Integromat) and switch back the channel type to private.
- Invite the bot
get_id_bot
to your private channel and using the/my_id@get_id_bot
command.
Retrieving the ID From the Web Version of Telegram
1. Log in to your Telegram account via https://web.telegram.org.
2. Click on the private channel you want to retrieve the chat ID for.
3. Copy the number between the c letter and the underscore from the URL.
If the URL is https://web.telegram.org/#/im?p=c1424271061_11793697872942794544 then copy the 1424271061
4. Paste the number to the desired field and add the prefix -100
5. The Chat ID of the private channel is then -1001424271061.
You can now use the ID in the desired Telegram Bot module in Integromat.
Registration and Login
It is not required. You can sign in on the site, telegram.org/auth where you can change your public settings. You will receive a key in your desktop application to submit your login.
My bot is hitting limits, how do I avoid this?
When sending messages inside a particular chat, avoid sending more than one message per second. We may allow short bursts that go over this limit, but eventually you'll begin receiving 429 errors.
If you're sending bulk notifications to multiple users, the API will not allow more than 30 messages per second or so. Consider spreading out notifications over large intervals of 8—12 hours for best results.
Also note that your bot will not be able to send more than 20 messages per minute to the same group.
(source: https://core.telegram.org/bots/faq#my-bot-is-hitting-limits-how-do-i-avoid-this)
How to determine the ID of a private channel/group:
One possible way to determine the ID of a private channel/group is as follows:
1. Create a new scenario.
2. Place Telegram Bot > Watch updates module in the scenario.
3. Configure the module by creating a webhook.
4. Execute the scenario.
5. Send a message to the private channel/group.
6. Verify the output of the module by clicking the bubble above the module.
7. Find the ID in the output bundle:
My bot is hitting limits, how do I avoid this?
When sending messages inside a particular chat, avoid sending more than one message per second. We may allow short bursts that go over this limit, but eventually you'll begin receiving 429 errors.
If you're sending bulk notifications to multiple users, the API will not allow more than 30 messages per second or so. Consider spreading out notifications over large intervals of 8—12 hours for best results.
Also note that your bot will not be able to send more than 20 messages per minute to the same group.
(source: https://core.telegram.org/bots/faq#my-bot-is-hitting-limits-how-do-i-avoid-this)