Telegram Bot Setup

This guide walks you through creating a Telegram bot and obtaining the credentials needed to use Telegram components in GrailHub.

Prerequisites

A Telegram account
Telegram app installed on your device (mobile or desktop)

Creating Your Bot

Step 1: Start a Chat with BotFather

Open Telegram and search for @BotFather (or click this link)
Start a conversation by clicking Start or sending /start

BotFather is the official Telegram bot for creating and managing bots.

Step 2: Create a New Bot

Send the command /newbot to BotFather
BotFather will ask for a name for your bot (this is the display name)
- Example: My Trading Alerts
Next, provide a username for your bot (must end in bot)
- Example: my_trading_alerts_bot

Step 3: Get Your Bot Token

After creating the bot, BotFather will send you a message containing your bot token. It looks like this:

123456789:ABCdefGHIjklMNOpqrsTUVwxyz

Step 4: Save Your Token

Copy the token and store it securely. You’ll need it when configuring Telegram components in GrailHub.

Getting Your Chat ID

To send messages, you need the Chat ID of the recipient (yourself, a group, or a channel).

Personal Chat ID

Start a conversation with your bot by searching for its username
Send any message to your bot (e.g., /start)
Open this URL in your browser (replace YOUR_BOT_TOKEN with your actual token):
```
https://api.telegram.org/botYOUR_BOT_TOKEN/getUpdates
```
Look for the "chat":{"id": field in the response. The number is your Chat ID.

Example response:

{
  "ok": true,
  "result": [
    {
      "message": {
        "chat": {
          "id": 123456789,
          "type": "private"
        }
      }
    }
  ]
}

Your Chat ID in this example is 123456789.

Group Chat ID

Add your bot to the group
Send a message in the group (mention the bot or just send any message)
Use the same getUpdates URL as above
Find the group’s Chat ID in the response (group IDs are typically negative numbers)

Example: -1001234567890

Channel Chat ID

Add your bot as an administrator to your channel
Post a message in the channel
Use the getUpdates URL
The channel ID will appear in the response

Alternatively, for public channels, you can use the channel username with @ prefix:

Example: @mychannel

Configuring Bot Permissions

Depending on your use case, you may need to adjust bot settings:

For Receiving Commands

Your bot can receive commands by default. Users send commands like /start, /help, or custom commands you define.

For Group Messages

If you want your bot to receive all messages in a group (not just commands):

Send /setprivacy to BotFather
Select your bot
Choose Disable

This allows your bot to see all messages in groups it’s added to.

For Inline Mode

To enable inline queries (users can type @yourbot query):

Send /setinline to BotFather
Select your bot
Provide a placeholder text

Using Credentials in GrailHub

Notification Component

The Notification component sends messages to Telegram:

Config	Description
Bot Token	Your bot token from BotFather
Chat ID	The recipient’s Chat ID
Message Template	The message content (supports templates)
Parse Mode	Plain Text, Markdown, or HTML

Command Component

The Command component listens for bot commands:

Config	Description
Bot Token	Your bot token from BotFather
Command	The command to listen for (without `/`)
Poll Interval	How often to check for new messages (seconds)

Example: Setting Up Price Alerts

Here’s a typical workflow for price alerts:

Create a bot using BotFather
Get your Chat ID by messaging your bot
Add a Notification component to your flow
Configure the component:
- Bot Token: 123456789:ABCdefGHIjklMNOpqrsTUVwxyz
- Chat ID: 987654321
- Message Template: 🚨 Price Alert: {{.Symbol}} is now ${{.Price}}
- Parse Mode: Plain Text

Troubleshooting

Bot Not Responding

Verify your bot token is correct
Ensure you’ve started a conversation with the bot first
Check that the bot hasn’t been blocked

Can’t Find Chat ID

Make sure you’ve sent at least one message to the bot/group/channel
The getUpdates response is empty if there are no recent messages
Try sending a new message and checking again

Messages Not Sending to Group

Verify the bot is a member of the group
Check that the Chat ID is correct (group IDs are negative)
Ensure the bot has permission to send messages

Messages Not Sending to Channel

The bot must be an administrator of the channel
Use the correct channel ID or username

Security Best Practices

Never share your bot token - Treat it like a password
Use environment variables - Don’t hardcode tokens in flows
Rotate tokens if compromised - Use /revoke with BotFather to get a new token
Limit bot permissions - Only enable features you need