Telegram¶

A connector for Telegram.

⚠️ Breaking Changes introduced in opsdroid 0.20.0¶

We have moved this connector from calling the API to get updates, to subscribe to webhook events. This means that if you are running this connector in older versions, the connector will receiving updates from Telegram.

Migration requirements¶

expose opsdroid to the web through a secure connection (https) - you can use ngrok to forward your traffic through a secure url.
Include the following in your opsdroid configuration

web:
  base-url: <secure url/ngrok url>

If you need any help migrating, please asks on our matrix channel.

Requirements¶

A Telegram account - to create a bot
A Bot API Token
A secure URL where opsdroid is running (could be forwarded by ngrok)

Note: To register a new bot, open Telegram, write @BotFather and type /newbot. Provide a name and username (ending in bot) and BotFather will give you your API Token.

Configuration¶

web:
  base-url: <https://your-opsdroid-url-or-ngrok-url>

connectors:
  telegram:
    # required
    token: "123456789:ABCDEFGHIJKLMNOPQRSTUVWXYZ-ZYXWVUT"  # Telegram bot token
    # optional
    bot-name: opsdroid # Name to be used by the bot in some replies, defaults to opsdroid
    reply-unauthorized: True # Should the bot reply to unauthorized users?
    whitelisted-users:  # List of users who can speak to the bot, if not set anyone can speak
      - user1
      - user2

Note: You MUST specify the base-url in the web config, otherwise opsdroid won’t be able to receive webhook notifications.

Usage¶

You can add this connector to:

Direct Messages
Groups
Channels

If you want opsdroid to work on your group or channel, you should add it by opening your channel/group details and select the Add Members button, then search for your bot username and add it. It’s a good idea to add the bot as admin, because in some cases where you have privacy active, opsdroid won’t be able to read user’s names.

Direct Messages¶

To interact with your bot directly, start a new message, click search and type your bot name. For example, if you named your bot: MyAwesome_Bot you can just search for that name and wait for the result to show up, then click on the name of your bot and a new chat window will start. You can now talk with your bot and give him commands.

[6:13:11 PM] Fabio:
hello

Unread messages
[6:13:12 PM] opsdroid:
Hi FabioRosado

If you are using a list of users that can interact with the bot by using the configuration parameter whitelisted-users, you might want to set the parameter reply-unauthorized to True to make opsdroid reply to an unauthorized user, that the user can’t interact with the bot.

Groups¶

Opsdroid will listen to every message sent to a group, so it’s a good idea to set a list of users that can interact with the bot if you are using opsdroid skills that some users shouldn’t be able to trigger.

To set up a list of users that can interact with the bot, you can set the option configuration parameter whitelisted-users - you should try to use the user id obtained from Telegram response. Also, if you set up the configuration parameter reply-unauthorized you might want to set it to false so the bot doesn’t send a message every time someone says something to the group.

Channels¶

By default Telegram doesn’t show the name of the user that sends messages to a channel, if you want to change this behaviour, you can open your channel, click the channel name to open the settings, chose edit and toggle the option Sign Messages.

Note: If you have a discussion group, opsdroid will reply to any command sent to a channel in that group.

Whitelisting users¶

This is an optional config option that you can include on your config.yaml to prevent unauthorized users to interact with your bot. Currently, you can specify a user nickname or a userID. Using the userID method is preferable as it will increase the security of the connector since users can’t change this ID.

Here is how you can whitelist a user:

  telegram:
    token: <your bot token>
    whitelisted-users:
      - user1
      - 124324234 # this is a userID

Finding your userID is not straight forward. This value is sent by Telegram when a user sends a private message to someone (the bot in this case) or when someone calls the getUpdate from the API. To find a userID by a private message, set the logging level to debug and start a new private message to the bot. You will see the API response on your console - it will look similar to this:

{
   "update_id": 539026743,
   "message": {
      "message_id": 109,
      "from": {
         "id": 4532189818,
         "is_bot": false,
         "first_name": "user",
         "language_code": "en"
      },
      "chat": {}
   }
}

Use the id value from the message["from"] field and add it to your whitelisted-users config option.

Parsing images/videos/files¶

Unfortunately, we are unable to parse any of these formats, the reason for that is because Telegram doesn’t send us any real useful information that we can feed to opsdroid. When you send an image to a channel, Telegram sends us a file id, format and sizes, but no URL or anything that we could use to download the image.

Events Available¶

The Telegram Connector contains a few events that you can access on your skills. These events were created to allow you to use these messages types on your custom made skills.

… py:class:: Poll(poll, question, options, total_votes, *args, **kwargs)

module:

opsdroid.connector.telegram.events

Event class that triggers when a poll is sent.

… py:class:: Contact(contact, phone_number, first_name, *args, **kwargs)

module:

opsdroid.connector.telegram.events

Event class that triggers when a contact is sent.

… py:class:: Location(location, latitude, longitude, *args, **kwargs)

module:

opsdroid.connector.telegram.events

Event class that triggers when a location message is sent.

… py:class:: JoinGroup(user_id=None, user=None, target=None, connector=None, raw_event=None, raw_parses=None, event_id=None, linked_event=None)

module:

opsdroid.events

Event to represent joining a group (not a room).

The group could be a slack team or a matrix community.

… py:class:: LeaveGroup(user_id=None, user=None, target=None, connector=None, raw_event=None, raw_parses=None, event_id=None, linked_event=None)

module:

opsdroid.events

Even to represent leaving a group(not a room).

The group could be a slack team, matrix community or a telegram group.

:members:

… py:class:: PinMessage(user_id=None, user=None, target=None, connector=None, raw_event=None, raw_parses=None, event_id=None, linked_event=None)

module:

opsdroid.events

Event to represent pinning a message or other event.

… py:class:: Reply(text, *args, **kwargs)

module:

opsdroid.events

Event class representing a message sent in reply to another Message.

The linked_event property should hold either an opsdroid.events.Event class or an id for an event to which this message is replying.

:members:

… py:class:: EditedMessage(*args, **kwargs)

module:

opsdroid.events

A opsdroid.events.Message which has been edited.

The linked_event property should hold either an opsdroid.events.Event class or an id for an event to which the edit applies. The linked_event for Slack is the ts (timestamp) of the message to be edited

Reference¶

… py:class:: ConnectorTelegram(*args, **kwargs)

module:

opsdroid.connector.telegram

A connector for the chat service Telegram.

… py:method:: ConnectorTelegram.build_url(method)

module:

opsdroid.connector.telegram

Build the url to connect to the API.

type method:

param method:

API call end point.

type method:

string

returns:

String that represents the full API url.

… py:method:: ConnectorTelegram.connect()

module:

opsdroid.connector.telegram

async:

Create route and subscribe to Telegram webhooks.

The first thing we do on connect is to set up the route to receive events from Telegram, we also pass some arguments to the webhook to get events from messages, edited messages, channel posts and update id which is basically the event id.

One thing that is worth mentioning here, is that Telegram doesn’t implement a request authenticity policy, instead they suggest that we use our token on the webhook route, but using the token on the url doesn’t seem like a good idea, we are instead generating a strong pseudo-random string using the secrets library and add that string to our webhook route.

… py:method:: ConnectorTelegram.disconnect()

module:

opsdroid.connector.telegram

async:

Telegram¶

⚠️ Breaking Changes introduced in opsdroid 0.20.0¶

Migration requirements¶

Requirements¶

Configuration¶

Usage¶

Direct Messages¶

Groups¶

Channels¶

Whitelisting users¶

Parsing images/videos/files¶

Events Available¶

Reference¶

Navigation

Related Topics