Notifications

Telegram

Sending Telegram messages on the Stubber platform.

Telegram provides a powerful notification option for Stubber users in the form of a Telegram Bot.

Telegram has some key features and advantages over other notification platforms in Stubber, namely:

1. Unlimited number of bots can be set up
2. Bots can initiate conversations and send messages to users
3. Bots are discoverable by Telegram users via search
4. Ability to participate in and manage group chats
5. Support for rich media formats (photos, videos, documents, etc.)
6. Interactive elements like buttons and inline keyboards

# How does a Telegram Bot work?

A Telegram Bot acts as a contact point between users and your Stubber templates.

You can have an unlimited number of bots set up and each bot can connect to a template on your Stubber profile. You can also have multiple bots connect to a single template should your use case require it.

For detailed instructions on how to get your first bot set up, take a look at this tutorial.

# Inner workings

Telegram bots work through the Telegram Bot API. When a message is sent to a bot, it is routed through the Stubber platform, which processes the message and sends appropriate responses back through the bot.

Stubber has a default Telegram bot that will be used if you have not set up your own Telegram bot in Stubber Manage yet. To set up your own Telegram bot with your own branding, you can create a new bot using BotFather in Telegram and then register it in Stubber Manage.

Unlike some other messaging platforms, Telegram does not require template messages to initiate conversations. Your bot can send any message to users who have previously initiated a conversation with the bot.

# Routing incoming Telegram messages

When messages are sent to a Telegram bot that has been configured on your Stubber profile, they need to be routed in some way. Stubber offers different mechanisms to route these incoming messages, providing a wide range of functionality.

Incoming messages are integrated into Stubber using a feedback action called _update_from_telegram. This feedback action is triggered when a message is sent to a Telegram bot that is correctly configured on your Stubber profile.

# Stubsession

The most basic mechanism is the stubsession. When you send a message to a Telegram bot, you can create a stubsession for that bot interaction. The stubsession contains the user's chat_id, and the Stub that the original message was sent from. When that bot receives a message (incoming message), Stubber routes that message back to the Stub of the stubsession via the feedback action, _update_from_telegram.

See the stubsession concept for more information.

Incoming stubsession messages will emit the following Heimdall event:

• mechanism: evt
• path:stubber.systems.notifications.telegram.incoming.{{bot_name}}.stubsession.{{stubsession_stubref}}

# Next reply

In some scenarios, you want to obtain/steal a single reply from a user, without potentially overwriting their active stubsession. The nextreply mechanism can be used for this.

Incoming nextreply messages will emit the following Heimdall event:

• mechanism: evt
• path: stubber.systems.notifications.telegram.incoming.{{bot_name}}.nextreply.{{nextreply_stubref}}

See the parameters and Examples.

# Specific reply

The specificreplyuuid is another useful mechanism that can be used to route incoming messages. When the user specifically replies to a message (using Telegram's reply functionality), Stubber will check if a specificreplyuuid was set on the outgoing message, and then emit on Heimdall accordingly. This is useful for outgoing messages where the user is likely to specifically reply.

Incoming specificreplyuuid messages will emit the following Heimdall events: General:

• mechanism: cbh
• path: stubber.systems.notifications.telegram.incoming.{{bot_name}}.specificreplyuuid.{{specificreplyuuid}}

Specific:

• mechanism: cbh
• path: stubber.systems.notifications.telegram.incoming.{{bot_name}}.from.{{from_chat_id}}.specificreplyuuid.{{specificreplyuuid}}

# User Initiated Messages

A conversation can be initiated by the user instead of by Stubber (an org). For these cases, no stubsession can exist yet, so these messages cannot be posted on stubs via the _update_from_telegram feedback action.

These incoming messages will emit the following Heimdall event:

• mechanism: cbh
• path: stubber.systems.notifications.telegram.incoming.{{bot_name}}.from.{{from_chat_id}}

# Basic Usage

• Setup a notification in an action as seen below

        {
  "platforms": {
    "telegram": {
      "message_type": "text",
      "text": "Hello from Stubber!",
      "stubsession": {
        "set_new_with_timeout_hours": 24
      }
    }
  },
  "send_to": {
    "telegram_user": {
      "type": "raw",
      "value": "123456789" // Telegram chat_id
    }
  }
}

      

# Parameters

Everything inside platforms.telegram should be considered parameters for this notification. There are top level parameters that describe the message type and other general message behaviors, as well as message-type specific parameters.

This page focuses on the top level parameters, the nested parameters can be found in the message type specific pages below.

# message_type

required

string

Indicates the type of message that is going to be sent. This also will determine what additional parameters should be included.

Available message types are:

• text - Simple text messages
• media - Photos, voice messages, videos, documents, etc.
• location - Geographic location
• contact - Contact cards

Default: null

# text

required for text messages

string

The text content of the message when message_type is "text". Can include formatting using markdown.

Default: null

# parse_mode

optional

string

Defines the formatting style of the text. Can be one of:

• "HTML" - Use HTML tags for formatting
• "MarkdownV2" - Use Telegram's MarkdownV2 syntax
• "Markdown" - Use Telegram's original Markdown syntax (deprecated)

Default: MarkdownV2

# media

required for media messages

object

Contains the media files to be sent and associated options. Used when message_type is "media".

Example:

# enable_lids

optional

boolean

This parameter can be set to true to enable the lids feature for the outgoing Telegram message.

# bot_name

optional

string

If you have multiple Telegram bots set up on your org, you can use this parameter to specify the bot to use for the outgoing message.

# stubsession

optional

object

Contains the properties that relate to the handling of client's stubsession. The stubsession is what is used to determine where a client's incoming Telegram message should go. If you set the stubsession on an outgoing Telegram message, all incoming replies for the duration of the stubsession will be returned to the stub the outgoing message was sent from.

Default: null

# stubsession.set_new_with_timeout_hours

optional

integer

Length in hours for the Telegram stubsession to remain open.

Default: null

# stubsession.cancel_current_existing_stubsession

optional

boolean

This can be set to true to cancel the current stubsession for a specific chat_id (client).

Default: false

# stubsession.set_nextreply_with_timeout_minutes

optional

integer

This can be used to "steal" the stubsession for a specific chat_id (client), but only for their next reply. After their next reply, their stubsession will return to what it was.

Default: false

# stubsession.specificreply_uuid

optional

string

If this parameter is supplied, incoming replies from the client will not be posted to the stub in their stubsession. This parameter makes it easy to run actions on any stub in your org for incoming messages, as opposed to specifically on the stub the message was sent from.

Incoming replies will emit on heimdall on a specific path, determined by the specificreply_uuid. You can then register on this path to run a specific action on any stub in your org.

Default: null

# stubsession.set_stubsession_stubref

optional

string

This parameter can be used to set the stubsession to a specific stub in your org. This is useful when you want to route the next incoming messages to a specific stub in your org. Setting this parameter will override the default behavior of the stubsession being set to the stub the message was sent from.

Default: null

# Result