Skip to content

Telegram Platform Integration

NekoBot supports Telegram platform through Telegram Bot API.

Telegram Bot Token

1. Create Bot

  1. Search for @BotFather in Telegram
  2. Send /newbot command
  3. Follow prompts to enter bot name and username
  4. Copy the obtained API Token

2. Configure NekoBot

Edit data/platforms_sources.json:

json
{
  "telegram": {
    "type": "telegram",
    "enable": true,
    "id": "telegram",
    "token": "your-bot-token-here",
    "command_prefix": "/"
  }
}

3. Set Webhook (Optional)

Telegram supports both Webhook and long polling modes:

Webhook Mode

python
async def set_webhook(self, webhook_url):
    await self.platform_server.call_platform_api(
        platform_id="telegram",
        action="set_webhook",
        params={"url": webhook_url}
    )

Long Polling Mode (Default)

No additional configuration needed, NekoBot automatically uses long polling to fetch messages.

Message Events

Supported Events

Event TypeDescription
MessageText, image, video, and other messages
Callback QueryCallback button click
Inline QueryInline search
Member JoinMember joins group
Member LeaveMember leaves group

Message Format

Telegram messages support Markdown and HTML formats:

Markdown Mode

python
message = """
*Bold text*
_Italic text_
`Code`
```Code block```
[Link](https://example.com)
"""

HTML Mode

python
message = """
<b>Bold text</b>
<i>Italic text</i>
<code>Code</code>
<pre>Code block</pre>
<a href="https://example.com">Link</a>
"""

Message Types

Send Text Message

python
await self.send_group_message(
    group_id=chat_id,
    user_id=user_id,
    message="Hello!",
    platform_id="telegram"
)

Send Photo

python
async def send_photo(self, chat_id, photo_url, caption=""):
    await self.platform_server.call_platform_api(
        platform_id="telegram",
        action="send_photo",
        params={
            "chat_id": chat_id,
            "photo": photo_url,
            "caption": caption
        }
    )

Send Video

python
async def send_video(self, chat_id, video_url, caption=""):
    await self.platform_server.call_platform_api(
        platform_id="telegram",
        action="send_video",
        params={
            "chat_id": chat_id,
            "video": video_url,
            "caption": caption
        }
    )

Send File

python
async def send_document(self, chat_id, file_path, caption=""):
    await self.platform_server.call_platform_api(
        platform_id="telegram",
        action="send_document",
        params={
            "chat_id": chat_id,
            "document": file_path,
            "caption": caption
        }
    )

Buttons and Keyboards

Inline Keyboard

python
async def send_inline_keyboard(self, chat_id):
    keyboard = {
        "inline_keyboard": [
            [
                {"text": "Button1", "callback_data": "btn1"},
                {"text": "Button2", "callback_data": "btn2"}
            ],
            [
                {"text": "Link", "url": "https://example.com"}
            ]
        ]
    }
    await self.platform_server.call_platform_api(
        platform_id="telegram",
        action="send_message",
        params={
            "chat_id": chat_id,
            "text": "Please select:",
            "reply_markup": keyboard
        }
    )

Reply Keyboard

python
async def send_reply_keyboard(self, chat_id):
    keyboard = {
        "keyboard": [
            [{"text": "Option1"}, {"text": "Option2"}],
            [{"text": "Cancel"}]
        ],
        "resize_keyboard": True,
        "one_time_keyboard": False
    }
    await self.platform_server.call_platform_api(
        platform_id="telegram",
        action="send_message",
        params={
            "chat_id": chat_id,
            "text": "Please select:",
            "reply_markup": keyboard
        }
    )

Handle Callback Query

python
async def on_message(self, message):
    if message.get("callback_query"):
        callback = message["callback_query"]
        callback_id = callback["id"]
        data = callback.get("data")
        
        await self.answer_callback_query(callback_id, text="Clicked")
        
        if data == "btn1":
            await self.send_group_message(
                group_id=callback["message"]["chat"]["id"],
                user_id=callback["from"]["id"],
                message="You clicked Button1",
                platform_id="telegram"
            )

async def answer_callback_query(self, callback_id, text=""):
    await self.platform_server.call_platform_api(
        platform_id="telegram",
        action="answer_callback_query",
        params={"callback_query_id": callback_id, "text": text}
    )

Advanced Features

Get User Information

python
async def get_user_profile(self, user_id):
    result = await self.platform_server.call_platform_api(
        platform_id="telegram",
        action="get_chat",
        params={"chat_id": user_id}
    )
    return result.get("data")

Get Group Information

python
async def get_group_info(self, group_id):
    result = await self.platform_server.call_platform_api(
        platform_id="telegram",
        action="get_chat",
        params={"chat_id": group_id}
    )
    return result.get("data")

Set Command Menu

python
async def set_bot_commands(self):
    commands = [
        {"command": "start", "description": "Start using"},
        {"command": "help", "description": "Help"},
        {"command": "settings", "description": "Settings"}
    ]
    await self.platform_server.call_platform_api(
        platform_id="telegram",
        action="set_my_commands",
        params={"commands": commands}
    )

Get Group Members

python
async def get_group_members(self, group_id):
    result = await self.platform_server.call_platform_api(
        platform_id="telegram",
        action="get_chat_member_count",
        params={"chat_id": group_id}
    )
    return result.get("data", {})

File Size Limits

Telegram API has the following file size limits:

File TypeSize Limit
Photo10 MB
Video50 MB
Document50 MB (Premium users 2 GB)
Audio50 MB
Animation50 MB

Common Issues

Bot Not Receiving Messages

  1. Ensure bot has been added to the group
  2. Check if bot has permission to receive messages
  3. Verify if Token is correct

Message Send Failed

  1. Confirm bot has send message permission
  2. Check if message content complies with Telegram specifications
  3. Verify if chat ID is correct

Webhook Setup Failed

  1. Ensure Webhook URL is accessible
  2. Use HTTPS (Telegram requires it)
  3. Verify if SSL certificate is valid

基于 MIT 许可发布