Telegram Bot Plugin for OpenPets

Control Telegram bots via the Bot API. Send messages, manage chats, handle updates, and interact with users through 122+ API operations.

Features

• Send Messages: Text, photos, documents, audio, video, polls, and more
• Chat Management: Manage groups, channels, and private chats
• Updates: Get updates via polling (getUpdates) or webhooks
• Inline Features: Keyboards, callbacks, inline queries
• Advanced: Games, payments, stickers, forums, reactions

Quick Start

1. Get Bot Token

Message @BotFather on Telegram:

1. Send /newbot
2. Follow prompts to name your bot
3. Copy the token (looks like: 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11)

2. Configure

cd pets/telegram-bot
cp .env.example .env
# Edit .env and add your token

3. Test Connection

bun run quickstart
# or
opencode run "test telegram bot connection"

Configuration

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | TELEGRAM_BOT_TOKEN | ✅ Yes | Bot token from @BotFather |

Example .env

TELEGRAM_BOT_TOKEN=123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11

Usage Examples

Send a Message

send telegram message to chat 123456789 saying "Hello from OpenPets!"

Get Bot Info

get telegram bot info

Check Updates

get telegram updates

Send a Photo

send telegram photo to chat 123456789 with url https://example.com/image.jpg

Create a Poll

create telegram poll in chat 123456789 with question "What's your favorite color?" and options red, blue, green

Available Tools (122 Total)

Core Operations

Getting Updates:

• telegram-bot-get-updates - Poll for updates
• telegram-bot-set-webhook - Set webhook URL
• telegram-bot-delete-webhook - Remove webhook
• telegram-bot-get-webhook-info - Get webhook status

Messages:

• telegram-bot-send-message - Send text messages
• telegram-bot-send-photo - Send photos
• telegram-bot-send-document - Send documents
• telegram-bot-send-audio - Send audio files
• telegram-bot-send-video - Send videos
• telegram-bot-send-voice - Send voice messages
• telegram-bot-send-animation - Send GIFs/animations
• telegram-bot-send-location - Send locations
• telegram-bot-send-venue - Send venues
• telegram-bot-send-contact - Send contacts
• telegram-bot-send-poll - Create polls
• telegram-bot-send-dice - Send animated dice
• telegram-bot-send-media-group - Send media groups

Chat Management:

• telegram-bot-get-chat - Get chat info
• telegram-bot-get-chat-members - List chat members
• telegram-bot-get-chat-member-count - Get member count
• telegram-bot-ban-chat-member - Ban users
• telegram-bot-unban-chat-member - Unban users
• telegram-bot-restrict-chat-member - Restrict users
• telegram-bot-promote-chat-member - Promote users
• telegram-bot-set-chat-title - Set chat title
• telegram-bot-set-chat-description - Set chat description
• telegram-bot-set-chat-photo - Set chat photo
• telegram-bot-delete-chat-photo - Delete chat photo
• telegram-bot-pin-chat-message - Pin messages
• telegram-bot-unpin-chat-message - Unpin messages

Message Operations:

• telegram-bot-forward-message - Forward messages
• telegram-bot-copy-message - Copy messages
• telegram-bot-delete-message - Delete messages
• telegram-bot-edit-message-text - Edit message text
• telegram-bot-edit-message-caption - Edit captions
• telegram-bot-edit-message-reply-markup - Edit keyboards

Stickers:

• telegram-bot-send-sticker - Send stickers
• telegram-bot-get-sticker-set - Get sticker sets
• telegram-bot-create-new-sticker-set - Create sticker sets
• telegram-bot-add-sticker-to-set - Add stickers
• telegram-bot-set-sticker-emoji-list - Set sticker emojis

Bot Settings:

• telegram-bot-get-me - Get bot info
• telegram-bot-set-my-commands - Set bot commands
• telegram-bot-get-my-commands - Get bot commands
• telegram-bot-set-my-name - Set bot name
• telegram-bot-get-my-name - Get bot name
• telegram-bot-set-my-description - Set description
• telegram-bot-get-my-description - Get description

Payments:

• telegram-bot-send-invoice - Send invoices
• telegram-bot-create-invoice-link - Create payment links
• telegram-bot-answer-pre-checkout-query - Handle pre-checkout

Games:

• telegram-bot-send-game - Send games
• telegram-bot-set-game-score - Set high scores
• telegram-bot-get-game-high-scores - Get high scores

Inline Mode:

• telegram-bot-answer-inline-query - Answer inline queries
• telegram-bot-answer-web-app-query - Answer Web App queries

Read-Only Mode

Enable read-only mode to disable write operations:

# Environment variable
export TELEGRAM_BOT_READ_ONLY=true

# Or CLI command
pets read-only telegram-bot on

In read-only mode, only these tools are available:

• All get* and read* operations
• No send*, set*, delete*, create* operations

Differences: Bot API vs User API

| Feature | This Plugin (Bot API) | @openpets/telegram (User API) | |---------|----------------------|------------------------------| | API | HTTP REST API | MTProto (binary protocol) | | Auth | Bot token | API ID + Hash + Phone | | Account | Bot account | Your personal account | | Access | Public chats, groups where added | All your private chats | | Setup | Token from @BotFather | API credentials from my.telegram.org |

Technical Details

• OpenAPI Spec: alserom/telegram-bot-api-spec
• API Version: 7.4 (auto-updated)
• Base URL: https://api.telegram.org/bot<token>
• Auth Method: Token in URL path (Telegram-specific)

Scripts

# Test connection
bun run quickstart

# Generate OpenAPI tools (if spec updates)
bun run generate-openapi

# Build for publishing
bun run build

Resources

• Telegram Bot API Documentation
• BotFather - Create and manage bots
• Bot API Updates
• OpenAPI Spec Repository

Troubleshooting

"Unauthorized" Error

• Check your token is correct
• Ensure bot hasn't been revoked in @BotFather

"Chat Not Found"

• Bot must be added to the chat first
• For private chats, user must start the conversation

Webhook Issues

• Must use HTTPS URL
• Supported ports: 443, 80, 88, 8443
• Check getWebhookInfo for errors

Publishing

# Validate
pets validate

# Preview
pets publish --preview

# Publish
pets publish