Proxying

Connecting bots using the proxying method.

We recommend using the MtProto and API connection methods. They are more reliable and cannot affect your bot's operation.

Proxying

The Telegram Bot API has two operating schemes:

1. webhook — when a user writes to the bot, the Telegram server automatically sends an HTTPS request to your bot's address

2. getUpdates (long polling) — your bot independently requests updates from the Telegram server

To make connecting to the platform simple and fast, we developed a special proxying server that sits between the Telegram server and your bot.

If the bot works via Webhook

You can connect the bot manually (without entering the token) — to do this, when adding the bot, select the corresponding option and follow the instructions. You will need to replace your webhook with ours.

If the bot works via getUpdate

You can connect a bot that works via the getUpdate method in two ways: via the API (see the section "Connecting a bot via the API") or by replacing the api.telegram.org address.

Bots of this type independently request updates from Telegram using HTTPS requests via the getUpdate method. To connect the bot to analytics, you need to change the api.telegram.org address to the address provided by the system when connecting.

After changing the address, our platform will proxy all requests to the api.telegram.org address and collect statistics for you. This address can be used not only for getUpdate requests but also for all other types of requests (sending messages, files, etc.) — all requests are proxied to Telegram's servers unchanged.

How to change the connection address in your bot

Changing the api.telegram.org address is supported by the Telegram Bot API, and most libraries provide a way to change this address.

Important. The examples use the address "https://tgrasp.co" — you can only use this address if a bot token was specified in the Dashboard. Otherwise, use only the address you received in the Dashboard during the bot setup step.

If you set a token for the bot in the Dashboard, the system will give you the address "https://tgrasp.co", otherwise the address will be "https://botcode.tgrasp.co"

Instructions for various libraries

If you couldn't find instructions for your library, or you're having trouble connecting, contact our technical support or fill out the form at the bottom of this page.

Python

aiogram/aiogram v3

Repository — https://github.com/aiogram/aiogram

Information on how to change the host is in the documentation at https://docs.aiogram.dev/en/dev-3.x/api/session/custom_server.html

To change the connection address, you need to add this code:

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


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

And you need to change the Bot function call by adding the session=session parameter

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

Full code listing

Note lines 11 and 12 — they import the objects. Lines 51-53 set the address. Line 56 adds the , session=session attribute

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') # your address
    )

    # 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

Information on how to change the host is in the official documentation

To change the connection address, you need to add this code:

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

And you need to change the Bot function call by adding the server=server parameter

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

Full code listing

Note line 3 — it imports the object. Line 12 sets the address. Line 15 adds the , server=server attribute

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

Repository — https://github.com/eternnoir/pyTelegramBotAPI

To change the host you need to import apihelper and set the API_URL parameter. You can read about how to change the host in the official documentation

from telebot import apihelper

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

Full code listing

For a complete example, we used the example from the official repository at https://github.com/eternnoir/pyTelegramBotAPI/blob/master/examples/echo_bot.py

Note lines 7 and 11. They import the object and change the address

#!/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}" # your address

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

Repository — https://github.com/python-telegram-bot/python-telegram-bot

Information on how to change the host is in the documentation at https://github.com/python-telegram-bot/python-telegram-bot/wiki/Local-Bot-API-Server

You can change the host using the base_url method. For clarity, we used the basic example from the documentation. Note line 16, where the address is changed via .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__':

# Replace the address with your own
    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

Repository — https://github.com/telegram-bot-sdk/telegram-bot-sdk

The library supports working with multiple bots, so two connection options are shown below

If you have one bot

use Telegram\Bot\Api;

// replace the fourth argument with the address you received in the Dashboard.
// note the addition of /bot at the end
$telegram = new Api('<BOT TOKEN>', false, null, 'https://tgrasp.co/bot');

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

If you have multiple bots

use Telegram\Bot\BotsManager;

$config = [
    'bots' => [
        'mybot' => [
            'token' => '<BOT TOKEN>',
        ],
    ],
    // replace with the address you received in the Dashboard.
    // note the addition of /bot at the end
    '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

Information on how to change the host is in the documentation at 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

Information on how to change the host is in the documentation at https://github.com/TelegramBot/Api?tab=readme-ov-file#local-bot-api-server

At the time of writing this documentation, the ability to change the address is only available in the dev version 2.6. Version 2.5 is installed by default

Update your library version to 2.6

Change "^2.6" in composer.json and add the parameters "minimum-stability": "dev", "prefer-stable": true

composer.json example

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

Changing the address

When creating the BotApi object, pass our address as the fourth parameter

try {

    $bot = new \TelegramBot\Api\BotApi(
        '<BOT TOKEN>', 
        null, 
        null, 
        'https://tgrasp.co/bot' // replace with the address you received in the Dashboard
    );
    $updates = $bot->getUpdates(0, 100, 10);
    
} catch (\TelegramBot\Api\Exception $e) {
    $e->getMessage();
}

defstudio/telegraph

Repository — https://github.com/defstudio/telegraph

You can change the connection address in the defstudio/telegraph configuration. Replace the value of the telegram_api_url parameter with the desired address (https://tgrasp.co)

More details on the configuration file in the documentation

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/', // <------- your address
]

JavaScript

yagop/node-telegram-bot-api

To change the host, pass the baseApiUrl: 'https://tgrasp.co' parameter in the options argument when creating the new TelegramBot(token, [options]) object

const options = { 
    polling: true, 
    baseApiUrl: 'https://tgrasp.co' // replace with the address you received in the Dashboard
}; 
const bot = new TelegramBot(TOKEN, options);

Full code listing

For a complete example, we used the example from the official repository at https://github.com/yagop/node-telegram-bot-api/blob/master/examples/polling.js

Note line 12, where the address is changed

/**
 * 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' // your address
};

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

Instructions on how to change the address are in the official documentation — https://grammy.dev/guide/api#configuring-grammy-to-use-the-local-bot-api-server

To connect, change the creation of the Bot object

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

Example

As an example, we used the basic example from the official documentation. Note lines 4-7, where the address is changed

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


const bot = new Bot("< BOT_TOKEN >",
{ // <-- use the same token as before
  client: { apiRoot: "https://tgrasp.co" }, // replace with the address you received in the Dashboard
});

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

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

telegraf/telegraf

Repository — https://github.com/telegraf/telegraf

To connect, change the creation of the Telegraf object.

Below is an example of a simple bot with a changed address. Note lines 5-8, where the address is changed. Replace the address with the one you received in the Dashboard. After making the changes, restart the bot.

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

// Specify here your token that you received from BotFather
const bot = new Telegraf('< BOT_TOKEN >',
  {
  telegram: {
    apiRoot: 'https://tgrasp.co' // replace with the address you received in the Dashboard
  }
});

// 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('Bot started in long polling mode');
});

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

Go

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

Repository — https://github.com/go-telegram-bot-api/telegram-bot-api

Use the SetAPIEndpoint method to change the connection host

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

bot.SetAPIEndpoint("https://tgrasp.co/bot%s/%s") // replace with the address you received in the Dashboard

Full example

Note line 17, where the address is changed

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") // replace with the address you received in the Dashboard


	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

Repository — https://github.com/tucnak/telebot

To change the connection host, pass the desired address in the URL parameter

pref := tele.Settings{
  URL: "https://tgrasp.co", //the address you received in the Dashboard
  Token:  os.Getenv("TOKEN"),
  Poller: &tele.LongPoller{Timeout: 10 * time.Second},
}

Full example

Note line 13, where the address is changed

package main

import (
	"log"
	"os"
	"time"

	tele "gopkg.in/telebot.v3"
)

func main() {
	pref := tele.Settings{
		URL: "https://tgrasp.co", //the address you received in the Dashboard
		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

Repository — https://github.com/rubenlagus/TelegramBots

As an example, we used the repository https://github.com/rubenlagus/TelegramBotsExample

To connect incoming traffic, you need to pass a TelegramUrl object to the TelegramBotsLongPollingApplication.registerBot() function

Note line 8 — this is the standard method for connecting to the TG Bot API. In the next line, we added 2 parameters to this function, including passing the new address for the connection. Replace it with the address the system gave you.

//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), //<!-- replace the address with yours
            new DefaultGetUpdatesGenerator(), 
            new CommandsHandler(BotConfig.COMMANDS_TOKEN, BotConfig.COMMANDS_USER)
         );

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

Common errors

All errors related to bot operation appear in the bot errors section in the Dashboard.

Code	Description	Solution
403,404		Make sure you're using the correct connection address. Compare it with the address the system gave you. The tgrasp.co address can only be used if a token was provided. If you're using tgrasp.co, make sure the bot ID (which the token starts with) matches the one you provided to graspil. The current bot ID in graspil is displayed under the connection address field.
409	Conflict: terminated by other getUpdates request; make sure that only one bot instance is running	This error occurs when Telegram's servers detect two simultaneous getUpdates requests. Make sure you only have one data-receiving thread running
502	502 Bad Gateway	Make sure you're sending a request with the correct structure. Sometimes there are issues on Telegram's servers, and they may respond with this error.
	No connection to the server	Specify the correct region for your bot. You should choose the region where your bot's server is physically located. Use the address provided by the system.

If you couldn't find the instructions you need, write to us in the chat on the website or fill out the form below — we write new instructions on request.