Layers

Telegram bots in Layers

Your Telegram bot works in Layers. One line changes.

Layers answers Telegram Bot API requests. The bot stays the same code: you change the address and the token, and it writes to the group, shows buttons and receives what people reply.

Layers for teams: the first 5 seats are free, then $4 per seat a month

Buy seats · $4/seat

This text was prepared with the help of AI.

Moving

Five steps, five minutes

The bot code stays untouched. You need to be the owner or an admin of the group.

  1. 1

    Add the bot to a group

    Open a group or channel in Layers, choose “More” → “Bots” → “Add bot” and name the bot. It appears in the chat as a member marked “bot”.
  2. 2

    Copy the token and chat_id

    The window shows a token like 1043:Qm7v… and the chat’s chat_id. The token is shown once: keep it where you keep the Telegram token. If you lose it, issue a new one in the same window; the old one stops working at once.
    What to put into the bot
    BOT_TOKEN=1043:Qm7v…
    CHAT_ID=-1000000000042
    API_BASE=https://app.layers.md/tgapi
  3. 3

    Replace the API address

    Wherever the bot calls https://api.telegram.org, put https://app.layers.md/tgapi. On your own Layers server it is your server address plus /tgapi. In libraries this is a single setting.
    python-telegram-bot
    from telegram.ext import ApplicationBuilder
    
    app = (
        ApplicationBuilder()
        .token(BOT_TOKEN)
        .base_url("https://app.layers.md/tgapi/bot")
        .base_file_url("https://app.layers.md/tgapi/file/bot")
        .build()
    )
    aiogram
    from aiogram import Bot
    from aiogram.client.session.aiohttp import AiohttpSession
    from aiogram.client.telegram import TelegramAPIServer
    
    session = AiohttpSession(api=TelegramAPIServer.from_base("https://app.layers.md/tgapi"))
    bot = Bot(BOT_TOKEN, session=session)
    Without a library
    - https://api.telegram.org/bot$BOT_TOKEN/sendMessage
    + https://app.layers.md/tgapi/bot$BOT_TOKEN/sendMessage
  4. 4

    Check the connection

    Call getMe and send a message. Answers come in the same shape as Telegram’s: {"ok": true, "result": …}, and errors carry error_code and description.
    A check from the terminal
    curl https://app.layers.md/tgapi/bot$BOT_TOKEN/getMe
    
    curl https://app.layers.md/tgapi/bot$BOT_TOKEN/sendMessage \
      -d chat_id=$CHAT_ID -d text="ok"
  5. 5

    Turn on incoming messages

    The bot receives messages the same way as in Telegram: by polling getUpdates or through a setWebhook webhook to your https address. In a group the bot sees commands, mentions and replies to its own messages; in a direct chat it sees everything.
    Webhook
    curl https://app.layers.md/tgapi/bot$BOT_TOKEN/setWebhook \
      -d url=https://bot.example.com/telegram

What works

Telegram Bot API methods Layers answers

Method names, request fields and answers are the same as in Telegram. On the right is how it looks in the chat.

WhatMethodsIn Layers
MessagessendMessage, editMessageText, deleteMessage, forwardMessage, copyMessageOrdinary chat messages: with HTML and MarkdownV2 formatting, replies and search.
Photos, files, voice and videosendPhoto, sendDocument, sendAudio, sendVideo, sendVoice, sendMediaGroup, getFileMessage attachments; a voice message plays as a voice message. The bot downloads people’s files through getFile.
Buttons under a messageinline_keyboard: callback_data, url, copy_text; answerCallbackQuery, editMessageReplyMarkupButtons under the bot’s message. A press reaches the bot as a callback_query.
Keyboard and reply to the botkeyboard, one_time_keyboard, resize_keyboard, remove_keyboard, force_replyA panel of buttons above the message box; force_reply opens the box as a reply to the bot’s message.
CommandssetMyCommands, getMyCommands, deleteMyCommandsA command hint when a person types “/” in the message box.
Incoming updatesgetUpdates, setWebhook, deleteWebhook, getWebhookInfoMessages, edits, button presses, channel posts, reactions and poll answers.
Reactions and pinningsetMessageReaction, pinChatMessage, unpinChatMessage, unpinAllChatMessagesChat reactions and pinned messages. A bot that is a group admin can pin.
PollssendPoll, stopPollA Layers poll; votes reach the bot as poll_answer.
Group and membersgetChat, getChatMember, getChatAdministrators, getChatMemberCount, banChatMember, unbanChatMember, setChatTitle, setChatPhotoA bot that is a group admin deletes other people’s messages, removes members, changes the title and the picture.
Location, contact, dicesendLocation, sendVenue, sendContact, sendDiceA message with coordinates and a map link, with a name and a phone number, with a roll.

What is missing

What a bot cannot do

Layers does not have some of what Telegram has. Layers answers such calls with a clear error instead of staying silent.

WhatWhat Layers answers
Inline mode: the bot in any chat through @name (answerInlineQuery)400 Bad Request: method … is not supported by Layers
Payments, Stars, giftsThe same 400 error. An invoice can be sent as a link in an ordinary message.
Sticker sets, games, stories, forum topics, business accountsThe same 400 error. A single sticker is sent as a picture.
web_app, login_url and pay buttons, phone and location requests400 Bad Request naming the button. Link buttons and callback_data buttons work.
Bot buttons and keyboard in the phone appFor now they show in the browser and in the desktop app. On a phone the message text arrives.
Member permissions: restrictChatMember, setChatPermissions, promoteChatMember, setChatDescription400 Bad Request: not enough rights …. A bot that is an admin can remove a member (banChatMember) and delete a message.

The numbers differ: chat_id, user_id and message_id are Layers’ own. If the bot stores them in a database, keep separate records for Layers.

Questions

The short version

What people ask most often.

Do I have to rewrite the bot?

No. The API address and the token change. If the bot uses only the methods in the “What works” table, the code stays as it is.

Can the bot run in Telegram and in Layers at the same time?

Yes. Start a second instance with the Layers address and token. Each has its own token and its own chats, and they do not get in each other’s way.

Does the bot see the whole group conversation?

No. In a group the bot receives commands, mentions and replies to its own messages, like a Telegram bot with privacy mode on. In a direct chat with the bot it receives everything.

Who can add a bot?

The owner or an admin of the group or channel. The same person issues a new token and removes the bot. A removed bot stops receiving messages at once, and its token stops working.

Does it work on our own Layers server?

Yes. The address is your server address plus /tgapi. The bot needs access to the server, and for a webhook the server needs access to the bot’s https address.

What about rate limits?

As in Telegram: when you send to one chat too often, you get 429 Too Many Requests with a retry_after field. Libraries wait and retry on their own.

Connect the bot and try it on your group

Five minutes: add the bot, change the address and the token, send the first message.

The Layers workspace