Проксирование

Подключение ботов через метод проксирование.

Мы рекомендуем использовать методы подключение MtProto и API. Они более надежные и не могут повлиять на работу бота.

Проксирование

Telegram Bot API имеет две схемы работы:

1. webhook - когда пользователь пишет боту, сервер телеграм автоматически отправляет https запрос на адрес вашего бота

2. getUpdates (long polling) - ваш бот самостоятельно запрашивает обновления у сервера телеграм

На схеме выше изображена стандартная схема обмена данными бота с Telegram серверами.

Чтобы сделать подключение к платформе простым и быстрым мы разработали специальный проксирующий сервер, который встраивается между сервером Телеграм и вашим ботом.

Так выглядит схема работы после подключения graspi.

Если бот работает через Webhook

Вы можете подключить бота вручную (не вводя токен), для этого при добавлении бота необходимо выбрать соответствующий пункт и следовать инструкциям. Вам будет нужно заменить ваш webhook на наш.

Если бот работает через getUpdate

Подключить бота работающего через метод getUpdate можно двумя способами, через API (см. раздел "Подключение бота через API") или заменой адрса api.telegram.org.

Боты такого типа самостоятельно запрашивают обновления у Telegram, с помощью HTTPS запросов используя метод getUpdate. Чтобы подключить бота к аналитике нужно изменить адрес api.telegram.org на адрес который выдаст вам система при подключении.

После смены адреса наша платформа будет проксировать все запросы на адрес api.telegram.org и собирать для вас статистику. На этот адресс можно слать не только запросы типа getUpdate но и все остальные типы запросов (отправка сообщений, файлов и т.д.) все запросы проксируются на сервера Telegram в неизменном виде.

Как изменить адрес подключение в боте

Изменение адреса api.telegram.org предусмотренно Telegram Bot API, большинство библиотек имеют возможности для смены этого адреса.

Важно. В примерах используется адрес "https://tgrasp.co", вы можете использовать этот адрес только в случае если в личном кабинете был указан токен бота. В иных случаях используйте только тот адрес который вы получили в личном кабинете на этапе настройки бота.

Если в личном кабинете вы задали токен для бота, система выдаст вам адрес "https://tgrasp.co" иначе адрес будет "https://кодбота.tgrasp.co"

Инструкции для различных библиотек

Если вы не нашли инструкцию для своей библиотеки или у вас возникли проблемы с подключением обратитесь к нам в техническую поддержку или заполните форму в конце этой страницы.

Python

aiogram/aiogram v3

Репозиторий - https://github.com/aiogram/aiogram

Информация как сменить хост в документации https://docs.aiogram.dev/en/dev-3.x/api/session/custom_server.html

Чтобы изменить адрес подключения, необходимо добавить код:

from aiogram.client.session.aiohttp import AiohttpSession
from aiogram.client.telegram import TelegramAPIServer


session = AiohttpSession(
    api=TelegramAPIServer.from_base('https://tgrasp.co')
)

И необходимо изменить вызов функции Bot добавив параметр session=session

bot = Bot(..., session=session)

Полный листинг кода

Обратите внимание на строки 11 и 12, в них импортируются объекты. В строках 51-53 задается адрес. В строке 56 добавляется атрибут , session=session

import asyncio
import logging
import sys
from os import getenv

from aiogram import Bot, Dispatcher, Router, types
from aiogram.enums import ParseMode
from aiogram.filters import CommandStart
from aiogram.types import Message
from aiogram.utils.markdown import hbold
from aiogram.client.session.aiohttp import AiohttpSession
from aiogram.client.telegram import TelegramAPIServer

# Bot token can be obtained via https://t.me/BotFather
TOKEN = getenv("BOT_TOKEN")

# All handlers should be attached to the Router (or Dispatcher)
dp = Dispatcher()


@dp.message(CommandStart())
async def command_start_handler(message: Message) -> None:
    """
    This handler receives messages with `/start` command
    """
    # Most event objects have aliases for API methods that can be called in events' context
    # For example if you want to answer to incoming message you can use `message.answer(...)` alias
    # and the target chat will be passed to :ref:`aiogram.methods.send_message.SendMessage`
    # method automatically or call API method directly via
    # Bot instance: `bot.send_message(chat_id=message.chat.id, ...)`
    await message.answer(f"Hello, {hbold(message.from_user.full_name)}!")


@dp.message()
async def echo_handler(message: types.Message) -> None:
    """
    Handler will forward receive a message back to the sender

    By default, message handler will handle all message types (like a text, photo, sticker etc.)
    """
    try:
        # Send a copy of the received message
        await message.send_copy(chat_id=message.chat.id)
    except TypeError:
        # But not all the types is supported to be copied so need to handle it
        await message.answer("Nice try!")


async def main() -> None:

    session = AiohttpSession(
        api=TelegramAPIServer.from_base('https://tgrasp.co') # ваш адрес
    )

    # Initialize Bot instance with a default parse mode which will be passed to all API calls
    bot = Bot(TOKEN, parse_mode=ParseMode.HTML, session=session)
    
    # And the run events dispatching
    await dp.start_polling(bot)


if __name__ == "__main__":
    logging.basicConfig(level=logging.INFO, stream=sys.stdout)
    asyncio.run(main())

aiogram/aiogram v2

Информация как сменить хост в официальной документации

Чтобы изменить адрес подключения, необходимо добавить код:

from aiogram.bot.api import TelegramAPIServer
server = TelegramAPIServer.from_base('https://tgrasp.co')

И необходимо изменить вызов функции Bot добавив параметр server=server

bot = Bot(..., server=local_server)

Полный листинг кода

Обратите внимание на строки 3, в ней импортируются объект. В строке 12 задается адрес. В строке 15 добавляется атрибут , server=server

import logging
from aiogram import Bot, Dispatcher, executor, types
from aiogram.bot.api import TelegramAPIServer
from aiogram.types import ContentType

API_TOKEN = 'BOT TOKEN HERE'

# Configure logging
logging.basicConfig(level=logging.INFO)

# Create private Bot API server endpoints wrapper
server = TelegramAPIServer.from_base('https://tgrasp.co')

# Initialize bot with using local server
bot = Bot(token=API_TOKEN, server=server)
# ... and dispatcher
dp = Dispatcher(bot)


@dp.message_handler(content_types=ContentType.ANY)
async def echo(message: types.Message):
    await message.copy_to(message.chat.id)

if __name__ == '__main__':
    executor.start_polling(dp, skip_updates=True)

eternnoir/pyTelegramBotAPI

Репозиторий - https://github.com/eternnoir/pyTelegramBotAPI

Чтобы изменить хост нужно импортировать apihelper и задать параметр API_URL. О том как изменить хост можно прочитать в официальной документации

from telebot import apihelper

apihelper.API_URL = "https://tgrasp.co/bot{0}/{1}"

Полный листинг кода

Для полноценного примера мы использовали пример из официального репозитория по адресу https://github.com/eternnoir/pyTelegramBotAPI/blob/master/examples/echo_bot.py

Обратите внимание на строки 7 и 11. В них импортируется объект и изменяется адрес

#!/usr/bin/python

# This is a simple echo bot using the decorator mechanism.
# It echoes any incoming text messages.

import telebot
from telebot import apihelper

API_TOKEN = '<api_token>'

apihelper.API_URL = "https://tgrasp.co/bot{0}/{1}" # ваш адрес

bot = telebot.TeleBot(API_TOKEN)


# Handle '/start' and '/help'
@bot.message_handler(commands=['help', 'start'])
def send_welcome(message):
    bot.reply_to(message, """\
Hi there, I am EchoBot.
I am here to echo your kind words back to you. Just say anything nice and I'll say the exact same thing to you!\
""")


# Handle all other messages with content_type 'text' (content_types defaults to ['text'])
@bot.message_handler(func=lambda message: True)
def echo_message(message):
    bot.reply_to(message, message.text)


bot.infinity_polling()

python-telegram-bot/python-telegram-bot

Репозиторий - https://github.com/python-telegram-bot/python-telegram-bot

Информация как сменить хост в документации https://github.com/python-telegram-bot/python-telegram-bot/wiki/Local-Bot-API-Server

Вы можете изменить хост с помощью метода base_url, Для наглядности мы использовали базовый пример из документации. Обратите на строку 16 в ней изменяется адрес .base_url('https://tgrasp.co/bot')

import logging
from telegram import Update
from telegram.ext import ApplicationBuilder, ContextTypes, CommandHandler

logging.basicConfig(
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
    level=logging.INFO
)

async def start(update: Update, context: ContextTypes.DEFAULT_TYPE):
    await context.bot.send_message(chat_id=update.effective_chat.id, text="I'm a bot, please talk to me!")

if __name__ == '__main__':

# Замените адрес на свой
    application = ApplicationBuilder().base_url('https://tgrasp.co/bot').token('<BOT TOKEN>').build()
    
    start_handler = CommandHandler('start', start)
    application.add_handler(start_handler)
    
    application.run_polling()

PHP

telegram-bot-sdk/telegram-bot-sdk

Репозиторий - https://github.com/telegram-bot-sdk/telegram-bot-sdk

Библиотека поддерживает работу с несколькими ботами, поэтому ниже представлено два варианта подключения

Если у вас один бот

use Telegram\Bot\Api;

// замените четвертый атрибут на адрес который вы получили в личном кабинете.
// обратите внимание на добавление /bot в конце
$telegram = new Api('<BOT TOKEN>', false, null, 'https://tgrasp.co/bot');

$response = $telegram->getUpdates([
    'offset' => 0,
    'timeout'=>10
]);

Если у вас несколько ботов

use Telegram\Bot\BotsManager;

$config = [
    'bots' => [
        'mybot' => [
            'token' => '<BOT TOKEN>',
        ],
    ],
    // замените на адрес который вы получили в личном кабинете.
    // обратите внимание на добавление /bot в конце
    'base_bot_url' => 'https://tgrasp.co/bot'
];

$telegram = new BotsManager($config);

// Example usage
$response = $telegram->bot('mybot')->getUpdates([
    'offset' => 0,
    'timeout'=> 10
]);

php-telegram-bot/core

Информация как сменить хост в документации https://github.com/php-telegram-bot/core#using-a-custom-bot-api-server

Longman\TelegramBot\Request::setCustomBotApiUri(
    $api_base_uri = 'https://tgrasp.co'
);

TelegramBot/Api

Информация как сменить хост в документации https://github.com/TelegramBot/Api?tab=readme-ov-file#local-bot-api-server

На момент написание этой документации возможность смены адреса присутствует только в dev версии 2.6. По умолчанию устанавливается версия 2.5

Обновите вашу версию библиотеки до версии 2.6

Измените в composer.json на"^2.6" и добавьте параметры "minimum-stability": "dev", "prefer-stable": true

Пример composer.json

{
    "require": {
        "telegram-bot/api": "^2.6"
    },
    "minimum-stability": "dev",
    "prefer-stable": true
}

Изменение адреса

При создании объекта BotApi передайте четвертым параметром наш адрес

try {

    $bot = new \TelegramBot\Api\BotApi(
        '<BOT TOKEN>', 
        null, 
        null, 
        'https://tgrasp.co/bot' // замените на адресс который вы получили в личном кабинете
    );
    $updates = $bot->getUpdates(0, 100, 10);
    
} catch (\TelegramBot\Api\Exception $e) {
    $e->getMessage();
}

defstudio/telegraph

Репозиторий - https://github.com/defstudio/telegraph

Изменить адрес подключения вы можете в конфигурации defstudio/telegraph. Замените значение в параметре telegram_api_url на нужный адрес (https://tgrasp.co)

Подробней про файл конфигурации в документации

return [
    /*
     * Telegram api base url, it can be overridden
     * for self-hosted servers
     */
    //'telegram_api_url' => 'https://api.telegram.org/',
    'telegram_api_url' => 'https://tgrasp.co/', // <------- ваш адрес
]

JavaScript

yagop/node-telegram-bot-api

Для того чтобы изменить хост нужно передать параметр baseApiUrl: 'https://tgrasp.co' в атрибут options при создании обьекта new TelegramBot(token, [options])

const options = { 
    polling: true, 
    baseApiUrl: 'https://tgrasp.co' // замените на адрес который вы получили в личном кабинете
}; 
const bot = new TelegramBot(TOKEN, options);

Полный листинг кода

Для полноценного примера мы использовали пример из официального репозитория по адресу https://github.com/yagop/node-telegram-bot-api/blob/master/examples/polling.js

Обратите внимание на строку 12, в ней изменяется адрес

/**
 * This example demonstrates using polling.
 * It also demonstrates how you would process and send messages.
 */

const TOKEN = process.env.TELEGRAM_TOKEN || 'YOUR_TELEGRAM_BOT_TOKEN';
const TelegramBot = require('node-telegram-bot-api');
const request = require('@cypress/request');

const options = {
  polling: true,
  baseApiUrl: 'https://tgrasp.co' // ваш адрес
};

const bot = new TelegramBot(TOKEN, options);


// Matches /photo
bot.onText(/\/photo/, function onPhotoText(msg) {
  // From file path
  const photo = `${__dirname}/../test/data/photo.gif`;
  bot.sendPhoto(msg.chat.id, photo, {
    caption: "I'm a bot!"
  });
});


// Matches /audio
bot.onText(/\/audio/, function onAudioText(msg) {
  // From HTTP request
  const url = 'https://upload.wikimedia.org/wikipedia/commons/c/c8/Example.ogg';
  const audio = request(url);
  bot.sendAudio(msg.chat.id, audio);
});


// Matches /love
bot.onText(/\/love/, function onLoveText(msg) {
  const opts = {
    reply_to_message_id: msg.message_id,
    reply_markup: JSON.stringify({
      keyboard: [
        ['Yes, you are the bot of my life ❤'],
        ['No, sorry there is another one...']
      ]
    })
  };
  bot.sendMessage(msg.chat.id, 'Do you love me?', opts);
});


// Matches /echo [whatever]
bot.onText(/\/echo (.+)/, function onEchoText(msg, match) {
  const resp = match[1];
  bot.sendMessage(msg.chat.id, resp);
});


// Matches /editable
bot.onText(/\/editable/, function onEditableText(msg) {
  const opts = {
    reply_markup: {
      inline_keyboard: [
        [
          {
            text: 'Edit Text',
            // we shall check for this value when we listen
            // for "callback_query"
            callback_data: 'edit'
          }
        ]
      ]
    }
  };
  bot.sendMessage(msg.from.id, 'Original Text', opts);
});


// Handle callback queries
bot.on('callback_query', function onCallbackQuery(callbackQuery) {
  const action = callbackQuery.data;
  const msg = callbackQuery.message;
  const opts = {
    chat_id: msg.chat.id,
    message_id: msg.message_id,
  };
  let text;

  if (action === 'edit') {
    text = 'Edited Text';
  }

  bot.editMessageText(text, opts);
});

grammyjs/grammY

Инструкция как изменить адрес в официальной документации - https://grammy.dev/guide/api#configuring-grammy-to-use-the-local-bot-api-server

Для подключения измените создание объекта Bot

const bot = new Bot("", { // <-- use the same token as before
  client: { apiRoot: "https://tgrasp.co" },
});

Пример

В качестве примера мы использовали базовый пример из официальной документации. Обратите внимание на 4-7 строки в них изменяется адрес

const { Bot } = require("grammy");


const bot = new Bot("< BOT_TOKEN >",
{ // <-- use the same token as before
  client: { apiRoot: "https://tgrasp.co" }, // замените на адрес который вы получили в личном кабинете
});

// Handle the /start command.
bot.command("start", (ctx) => ctx.reply("Welcome! Up and running."));

// Start the bot.
bot.start();

telegraf/telegraf

Репозиторий - https://github.com/telegraf/telegraf

Для подключения измените создание объекта Telegraf.

Ниже пример простого бота с измененным адресом. Обратите внимание на строки 5-8, в них изменяется адрес. Замените адрес на тот который вы получили в личном кабинете. После внесения изменений перезапустите бот.

const { Telegraf } = require('telegraf');

// Specify here your token that you received from BotFather
const bot = new Telegraf('< BOT_TOKEN >',
  {
  telegram: {
    apiRoot: 'https://tgrasp.co' // замените на адрес который вы получили в личном кабинете
  }
});

// Response to the command /start
bot.start((ctx) => ctx.reply('Hi! I am a simple bot using long polling.'));

// Launching the bot in long pollin mode
bot.launch().then(() => {
  console.log('Бот запущен в режиме long polling');
});

// Processing an application shutdown
process.once('SIGINT', () => bot.stop('SIGINT'));
process.once('SIGTERM', () => bot.stop('SIGTERM'));

Go

go-telegram-bot-api/telegram-bot-api

Репозиторий - https://github.com/go-telegram-bot-api/telegram-bot-api

Используйте метод SetAPIEndpoint чтобы изменить хост подключения

bot, err := tgbotapi.NewBotAPI("<api_token>")

bot.SetAPIEndpoint("https://tgrasp.co/bot%s/%s") // замените на адрес который вы получили в личном кабинете

Полноценный пример

Обратите внимание на строку 17, в ней изменяется адрес

package main

import (
	"log"

	tgbotapi "github.com/go-telegram-bot-api/telegram-bot-api/v5"
)

func main() {
	bot, err := tgbotapi.NewBotAPI("<api_token>")
	if err != nil {
		log.Panic(err)
	}

	bot.Debug = true

	bot.SetAPIEndpoint("https://tgrasp.co/bot%s/%s") // замените на адрес который вы получили в личном кабинете


	log.Printf("Authorized on account %s", bot.Self.UserName)

	u := tgbotapi.NewUpdate(0)
	u.Timeout = 60

	updates := bot.GetUpdatesChan(u)

	for update := range updates {
		if update.Message != nil { // If we got a message
			log.Printf("[%s] %s", update.Message.From.UserName, update.Message.Text)

			msg := tgbotapi.NewMessage(update.Message.Chat.ID, update.Message.Text)
			msg.ReplyToMessageID = update.Message.MessageID

			bot.Send(msg)
		}
	}
}

tucnak/telebot

Репозиторий - https://github.com/tucnak/telebot

Чтобы изменить хост подключения, передайте нужный адрес в параметр URL

pref := tele.Settings{
  URL: "https://tgrasp.co", //адрес который вы получили в личном кабинете
  Token:  os.Getenv("TOKEN"),
  Poller: &tele.LongPoller{Timeout: 10 * time.Second},
}

Полноценный пример

Обратите внимание на строку 13, в ней изменяется адрес

package main

import (
	"log"
	"os"
	"time"

	tele "gopkg.in/telebot.v3"
)

func main() {
	pref := tele.Settings{
		URL: "https://tgrasp.co", //адрес который вы получили в личном кабинете
		Token:  os.Getenv("TOKEN"),
		Poller: &tele.LongPoller{Timeout: 10 * time.Second},
	}

	b, err := tele.NewBot(pref)
	if err != nil {
		log.Fatal(err)
		return
	}

	b.Handle("/hello", func(c tele.Context) error {
		return c.Send("Hello!")
	})

	b.Start()
}

Java

rubenlagus/TelegramBots

Репозиторий - https://github.com/rubenlagus/TelegramBots

В качестве примера мы использовали репозиторий https://github.com/rubenlagus/TelegramBotsExample

Для подключения входящего трафика нужно передать объект TelegramUrl в функцию TelegramBotsLongPollingApplication.registerBot()

Обратите внимание на строку 8 это стандартный метод подключение к TG Bot API. В следующей строке мы добавили 2 параметра в эту функцию, в том числе передаем новые адрес для подключения. Замените его на адрес который выдала вам система.

//import org.telegram.telegrambots.meta.TelegramUrl;
//import org.telegram.telegrambots.longpolling.util.DefaultGetUpdatesGenerator;

public static void main(String[] args) {

    TelegramBotsLongPollingApplication botsApplication = new TelegramBotsLongPollingApplication();
    try {
         // botsApplication.registerBot(BotConfig.COMMANDS__TOKEN, new CommandsHandler(BotConfig.COMMANDS__TOKEN, BotConfig.COMMANDS__USER));
         botsApplication.registerBot(
            BotConfig.WEATHER_TOKEN, 
            () -> new TelegramUrl("https", "tgrasp.co", 443), //<!-- замените адрес на ваш
            new DefaultGetUpdatesGenerator(), 
            new CommandsHandler(BotConfig.COMMANDS_TOKEN, BotConfig.COMMANDS_USER)
         );

        } catch (TelegramApiException e) {
            log.error("Error registering bot", e);
        }
}

Распространенные ошибки

Все ошибки связанные с работой бота попадают в раздел ошибки бота в личном кабинете.

Код	Описание	Решение
403,404		Убедитесь что используете верный адрес для подключения. Сверьте его с адресом который вам выдала система. Адрес tgrasp.co можно использовать только если был передан токен. Если вы используете tgrasp.co, убедитесь что ID бота (с него начинается токен) совпадает с тем что вы передавали в graspil. Текущий ID бота в graspil отображается под полем с адресом подключения.
409	Conflict: terminated by other getUpdates request; make sure that only one bot instance is running	Ошибка возникает когда сервера телеграм фиксируют два одновременных запроса getUpdates. Убедитесь что у вас запущен только один поток получения данных
502	502 Bad Gateway	Убедитесь что вы отправляете запрос верной структуры. Иногда на серверах телеграм случаются проблемы и они могут отвечать этой ошибкой.
	Нет соединения с сервером	Укажите верный регион вашего бота. Нужно выбрать тот регион где физически находится ваш сервер бота. Используйте адрес, который выдала вам систем.

Если вы не нашли нужную вам инструкцию напишите нам в чат на сайте или заполните форму ниже, мы пишем новые инструкции по запросу.