DChat Bot API

The Bot API is a small HTTP interface that the dchat-bot program serves on your own machine. Your bot code, in any language, talks to it with plain JSON. This page is the full reference: every method, every type, every limit. New to bots? Start with the overview.

Recent changes

Bot API 1.4October 2026

Mini apps.

• New methods setChatMenuButton and validateWebAppData. getMe reports has_main_web_app and web_app_url.
• A web_app button on inline and reply keyboards, see WebAppInfo.
• A mini app opened from a reply keyboard button can send data back as message.web_app_data, see WebAppData.
• Read Mini apps first.

Bot API 1.3October 2026

Inline mode.

• A person can type @yourbot and a query in any chat. It arrives as an inline_query update, and you answer it with answerInlineQuery. Read Inline mode first.
• New methods answerInlineQuery and setMyInlinePlaceholder. getMe reports supports_inline_queries.
• New types InlineQuery, InlineQueryResultArticle, InputTextMessageContent and ViaBot. A text sent from a result carries message.via_bot.
• A switch_inline_query_current_chat button on inline keyboards. switch_inline_query is still accepted and still does nothing.
• The profile gained inline_placeholder.

Bot API 1.2October 2026

Groups and channels.

• A bot can be added to a group like a person. Texts it is allowed to see arrive as updates with the group as the chat, and reply_to_message when they answer another message. Privacy mode is on by default, see Bots in groups.
• New methods setMyPrivacy, setMyJoinGroups and leaveChat. getMe now reports can_join_groups and can_read_all_group_messages. The profile gained group_privacy and join_groups.
• sendMessage takes group:<id> and channel:<id> chat ids, and reply_to_message_id in groups. editMessageText and deleteMessage change or remove the bot's own messages.
• A bot made an admin of a channel can post, edit and delete, see Bots in channels.
• Send limits: 20 a minute for each group or channel and 30 a second over all chats, answered with 429 and retry_after, see Limits and errors.

Bot API 1.1October 2026

Buttons and keyboards.

• reply_markup on sendMessage: an inline keyboard, a reply keyboard or ReplyKeyboardRemove.
• A tap on a callback button arrives as a callback_query update. Answer it with answerCallbackQuery.
• setMyCommands sets the command menu and the / suggestions in the apps.
• Markup limits: 8 KB, 12 rows, 8 buttons a row, 100 buttons in all.

Bot API 1.0October 2026

The first bots.

• Bot accounts, marked by the bot registry. The dchat-bot program with init, run and set-profile.
• The local HTTP interface with a bearer token on 127.0.0.1.
• getMe, getUpdates and sendMessage for private chats. A bot answers; it never writes first.

Authorizing your bot

A DChat bot is an ordinary account whose username ends in bot. There is no central server that holds your bot. You run the gateway yourself, and three secrets keep it yours. Keep all three out of source control, screenshots and chat messages.

How the interface is locked

• By default the gateway listens on 127.0.0.1 only, so the token works only from the same machine. Listening on any other address needs --allow-remote, prints a warning, and leaves the token as the only lock over plain HTTP. Put it behind TLS or a private network.
• The Host header must be 127.0.0.1:<port>, localhost:<port> or [::1]:<port>. That stops a web page that points its own name at your machine.
• A POST must be Content-Type: application/json, bodies over 64 KB are refused, and the gateway sends no CORS headers and answers no preflight, so a page you visit cannot drive the bot.
• The token is compared in constant time. The gateway never prints message text, the recovery phrase, the passphrase or the token (except the token once at the end of init).

Making requests

The base address is http://127.0.0.1:8081, or whatever you pass to dchat-bot run --listen. A method is a path on it: http://127.0.0.1:8081/sendMessage. Method names match without regard to case.

Requests

• getMe and getUpdates accept GET or POST. Every other method is POST only, and answers 405 to anything else.
• A GET sends its parameters in the query string and carries no body. A GET with a body is a 400.
• A POST sends a JSON object with Content-Type: application/json. Values in the body win over a query value of the same name.
• Whole numbers may be sent as numbers or as decimal strings. Booleans may be true and false or the text true and false.
• Every request needs the Authorization: Bearer <token> header. A token in the URL is not accepted.

curl -s http://127.0.0.1:8081/getMe \
  -H "Authorization: Bearer $DCHAT_BOT_TOKEN"

curl -s http://127.0.0.1:8081/sendMessage \
  -H "Authorization: Bearer $DCHAT_BOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"chat_id":"dc1...","text":"Hello"}'

Responses

Every answer is JSON with the HTTP status of the result. A success is {"ok":true,"result":...}. A refusal is {"ok":false,"error_code":<http status>,"description":"..."}, and a 429 adds parameters.retry_after.

{ "ok": false, "error_code": 429, "description": "Too Many Requests: retry after 12",
  "parameters": { "retry_after": 12 } }

All error codes are listed under Limits and errors.

Getting updates

Your bot learns what users do by asking for updates. Call getUpdates in a loop (long polling). Webhooks do not exist yet. The gateway keeps each update until you confirm it, so nothing is lost while your code is stopped or restarting; messages sent while the gateway itself was stopped arrive when it starts again.

Update

One incoming event. Exactly one of the optional fields is present.

{
  "update_id": 17,
  "message": {
    "message_id": "<id>",
    "from": { "wallet": "dc1...", "did": "did:dchat:...", "username": null, "name": "Alice" },
    "chat": { "id": "dc1...", "type": "private" },
    "date": 1760000000,
    "text": "/start"
  }
}

{
  "update_id": 18,
  "callback_query": {
    "id": "00112233445566778899aabbccddeeff",
    "from": { "wallet": "dc1...", "did": "did:dchat:...", "username": "alice", "name": "Alice" },
    "message": { "message_id": "<the id sendMessage answered>", "chat": { "id": "dc1...", "type": "private" } },
    "data": "vote:yes"
  }
}

{
  "update_id": 20,
  "inline_query": {
    "id": "11223344556677889900aabbccddeeff",
    "from": { "wallet": "dc1...", "did": "did:dchat:...", "username": "alice", "name": "Alice" },
    "query": "cats",
    "offset": ""
  }
}

{
  "k">"update_id": 19,
  "k">"message": {
    "k">"message_id": "<id>",
    "k">"from": { "k">"wallet": "dc1...", "k">"did": "did:dchat:alice", "k">"username": "alice", "k">"name": "Alice" },
    "k">"chat": { "k">"id": "dc1...", "k">"type": "private" },
    "k">"date": 1760600007,
    "k">"text": "",
    "k">"web_app_data": { "k">"data": "{\"pick\":2}", "k">"button_text": "Order" }
  }
}

Confirming updates

• Pass offset set to the last update_id you handled plus one. That confirms and drops every update with a smaller id. An update you did not confirm is still there after a restart.
• Updates arrive oldest first. timeout turns the call into a long poll that waits up to that many seconds for the first arrival.
• The gateway holds at most 200 unconfirmed updates for one sender (that sender's oldest are dropped first, so one account flooding the bot cannot push out everyone else) and at most 10 000 in all.
• A text longer than 4096 characters is cut to 4096, and its message carries "truncated": true.
• Only texts and button taps become updates. Each incoming message is queued once, even if the relay delivers it again.

Group updates

A text in a group the bot is an active member of arrives as an update when its sender is an active member too. The chat is the group, chat.id is group:<id> and chat.title is its name. reply_to_message is present when the text answers another message.

{
  "update_id": 19,
  "message": {
    "message_id": "<id>",
    "from": { "wallet": "dc1...", "did": "did:dchat:...", "username": "alice", "name": "Alice" },
    "chat": { "id": "group:dc0123...", "type": "group", "title": "Team" },
    "date": 1760000000,
    "text": "/start",
    "reply_to_message": { "message_id": "<id>" }
  }
}

• While privacy mode is on (the default) the senders only hand the bot some of a group's texts, see Privacy mode.
• A text in a group never lets the bot write to that user in private. Only a private message does.
• A callback on a group message names the group as callback_query.message.chat. It is passed on only when the message is a group message this bot sent and the user is a current member of that group.
• Channels send no updates. A bot does not read a channel back.

Available types

All types are JSON objects. Field names are exactly as shown. Optional fields are left out when they have no value, unless a description says the field is always present and may be null.

User

A person or bot account. Used for from in updates.

Chat

The conversation an update or a sent message belongs to.

Message

One incoming text.

ReplyRef

Names the message another one answers. It carries the id only, not the text.

CallbackQuery

A tap on a callback button of a message this bot sent. Answer it once with answerCallbackQuery.

InlineQuery

What a person typed after @yourbot . It names no chat, no chat type and no other member. Answer it once with answerInlineQuery.

The person need not have started the bot, and a query never counts as starting it: answering it earns no private messages. One person holds at most 32 pending queries here, and the oldest go first. A query can be answered for 30 seconds.

ViaBot

The inline bot a text was sent through. It is the label "via @yourbot" the apps draw on the message.

Anyone can set this label on a text they send, so it proves nothing about what the text says or where it came from. The apps draw it only for a registered bot. Never run a command found in a text that has via_bot, and never trust its content. Such a text also never counts as a command, a mention or a reply for privacy mode.

InlineKeyboardMarkup

A keyboard of buttons that appears right under the message it is sent with. Send it as reply_markup. Works in private chats and in groups.

{ "inline_keyboard": [
  [ { "text": "Thumbs up", "callback_data": "vote:up" },
    { "text": "Thumbs down", "callback_data": "vote:down" } ],
  [ { "text": "Open dchat.online", "url": "https://dchat.online" } ]
] }

InlineKeyboardButton

One button of an inline keyboard. Exactly one of callback_data, url, switch_inline_query, switch_inline_query_current_chat and web_app must be used.

InlineQueryResultArticle

One result of an inline answer. Articles are the only kind there is: no photos, GIFs, stickers or files, and no thumbnails. A field not listed here is refused with 400.

The person sees the title, the description and the first line of the text before tapping. Nothing is sent until they tap.

InputTextMessageContent

The content of a result: a plain text message. It is the only kind DChat supports, so there is no location, contact, venue or invoice content, and no formatting parameter.

The text is sent as the person's own message, from their own account, marked via @yourbot. Your bot is not told. The sent message shows no link preview, and its links stay behind the usual question before they open.

ReplyKeyboardMarkup

A keyboard that replaces the user's own keyboard. Tapping a button sends its text as an ordinary message. It stays until a later message of yours carries ReplyKeyboardRemove, or, with one_time_keyboard, until the user taps a button. Private chats only: a group answers 400 reply_keyboard_not_supported_in_groups.

{ "keyboard": [[ { "text": "Red" }, { "text": "Green" } ], [ { "text": "Blue" } ]],
  "resize_keyboard": true, "one_time_keyboard": true, "input_field_placeholder": "Pick a colour" }

KeyboardButton

One button of a reply keyboard. A plain button sends its text as a message. A button with web_app opens your mini app instead, and that mini app can send one piece of data back, see WebAppData.

ReplyKeyboardRemove

Send it as reply_markup to take a reply keyboard away. Private chats only.

BotCommand

One command of the bot's menu. The apps show the commands in the menu and as / suggestions.

WebAppInfo

The web_app field of a button. It names the page of your mini app the button opens.

A bad link is refused with 400 and nothing is sent. One origin belongs to one bot: the registry refuses a link whose origin another bot already uses.

WebAppData

What a mini app sent back to its bot. It arrives in the web_app_data field of a Message with an empty text, only from a mini app opened with a reply keyboard button.

One piece of data is accepted each time the mini app is opened, and then the mini app closes. The sender in from is the account that sent it, checked by the app, never something the page says. Like a callback tap, it does not count as the user starting the bot: you can answer only a user who has already written to the bot.

Available methods

These fourteen methods are the whole interface. Any other name answers 404 Not Found: no such method. Where a method says it counts against the send limits, see Limits and errors.

getMeGET or POST

A simple test of your connection and token. Takes no parameters. On success, returns an object with the fields below.

Both flags are read from the registry when the gateway starts, and changed by setMyJoinGroups and setMyPrivacy. supports_inline_queries follows setMyInlinePlaceholder. The mini app fields follow setChatMenuButton.

getUpdatesGET or POST

Use this method to receive incoming updates with long polling. Updates are oldest first. On success, returns an Array of Update objects, empty when nothing arrived before the timeout.

sendMessagePOST

Use this method to send a text message. A bot only answers: sending to a user who has never written to the bot is refused with 403 This user has not started the bot. On success, returns an object with message_id (String) and date (Integer, Unix seconds). For a group or a channel the object also holds chat with the id and type of the chat.

Where the message goes

• A user. Only a wallet that has sent the bot at least one private message. A text a user sends in a group does not count.
• A group. The bot must be an active member of that group in its own store, else 403 not_a_member. Inline keyboards only: a keyboard or remove_keyboard answers 400 reply_keyboard_not_supported_in_groups.
• A channel. A plain text post, published as the bot with the rights the channel owner granted. reply_markup and reply_to_message_id answer 400 (markup_not_supported_in_channels for the markup). The answer's message_id is the post's sequence number. A bot with no right, or a disabled bot, gets a 403 from the middleware.

Every send counts against the limits: 20 a minute for each group and each channel, and 30 a second over all chats.

editMessageTextPOST

Use this method to change the text of a message the bot sent. It changes the text, not the buttons. On success, returns true.

It acts only on messages this bot sent to that chat, which the gateway checks in its own record, else 403 Forbidden: the bot did not send that message in that chat. In a group the bot must still be a member (403 not_a_member). A channel post is held to the bot's rights by the middleware. A reply_markup is a 400. An edit counts against the send limits.

deleteMessagePOST

Use this method to delete a message the bot sent. The message is removed for everyone. On success, returns true.

The same checks as editMessageText apply: only the bot's own messages, membership in a group, channel rights from the middleware. A delete counts against the send limits.

answerCallbackQueryPOST

Use this method to answer a tap on an inline callback button. Each callback can be answered once, within 5 minutes of its arrival. Until you answer, the user's button shows a progress and the app gives up after about 15 seconds. On success, returns true.

An unknown id, one older than 5 minutes, or one answered already is refused with 400 query is too old, unknown, or already answered. The answer goes only to the user who tapped.

answerInlineQueryPOST

Use this method to answer an inline_query. Each query can be answered once, within 30 seconds of its arrival, and the answer goes only to the person who asked. On success, returns true.

{
  "inline_query_id": "11223344556677889900aabbccddeeff",
  "results": [{
    "type": "article", "id": "cat-1", "title": "A cat", "description": "Fluffy",
    "input_message_content": { "message_text": "meow" },
    "reply_markup": { "inline_keyboard": [[{ "text": "Site", "url": "https://example.com" }]] }
  }],
  "cache_time": 30, "next_offset": "p2",
  "switch_pm_text": "More in chat", "switch_pm_parameter": "from_inline"
}

Every limit is checked before anything is sent. A result that breaks one is a 400 that names it, such as results[2]: title must be ..., nothing is sent, and the query stays open so you can fix it and answer again. A failed send gives the query back too. An unknown id, one older than 30 seconds, or one answered already is refused with 400 query is too old and response timeout expired or query ID is invalid. An answer counts against the 30 a second send limit over all chats, see Limits and errors. Answering never lets the bot write to the person first. A GET is refused with 405.

setMyCommandsPOST

Use this method to change the bot's command menu, the commands the apps show in the menu and as / suggestions. It replaces the commands of the bot's registry profile and keeps its name, about and description. On success, returns true.

setMyInlinePlaceholderPOST

Use this method to make the bot an inline bot, and to set the grey hint the apps show after @yourbot while the query is still empty. It publishes the registry profile again as inline_placeholder and keeps the name, about, description, commands, group settings and mini app. setMyCommands, setMyPrivacy and setMyJoinGroups keep the placeholder too. On success, returns true.

Without a placeholder the apps do not offer the bot inline. getMe reports the result as supports_inline_queries. profile.json may carry inline_placeholder as well.

setMyPrivacyPOST

Use this method to turn privacy mode on or off. It publishes the registry profile again with group_privacy set, and keeps the name, about, description and commands. On success, returns true. See Privacy mode.

setMyJoinGroupsPOST

Use this method to allow or forbid adding the bot to groups. It publishes the registry profile again with join_groups set, and keeps the name, about, description and commands. On success, returns true.

At start the gateway applies the registry's join_groups the same way. If the registry cannot be reached it uses what it applied last.

leaveChatPOST

Use this method to make the bot leave a group, the way a person does. On success, returns true.

403 not_a_member when the bot is not in that group.

setChatMenuButtonPOST

Use this method to register the bot's mini app, or to remove it. It publishes the registry profile again and keeps everything else in it: name, about, description, commands, privacy and the other settings. setMyCommands, setMyPrivacy and setMyJoinGroups keep the mini app too. On success, returns true.

The registry refuses a link whose origin another bot already uses. getMe then reports has_main_web_app and web_app_url.

validateWebAppDataPOST

Use this method from your own backend to check the launch data a mini app page gave you, and to learn which account opened it. It needs the bearer token like every method, so it can only be called on the machine that runs the gateway. On success, returns an object with the fields below.

{ "k">"ok": true, "k">"result": {
  "k">"user": { "k">"did": "did:dchat:alice", "k">"wallet": "dc1...", "k">"username": "alice" },
  "k">"chat_type": "private", "k">"start_param": "", "k">"auth_date": 1760600000
} }

What is checked, and why it can be refused

The gateway checks in this order and stops at the first failure. A refusal is a 400 with a plain sentence unless the table says otherwise. The data is spent only when every check passed, so a refused call does not use it up.

A GET to this method answers 405.

Command line: dchat-bot

dchat-bot is the program you run on your own machine. It holds the bot's keys, receives what users send, and serves the interface above. Every command needs DCHAT_BOT_PASSPHRASE.

The claim code looks like K7QW-M2PX-9RTA. You get it in the app under My bots when you pick a name and a username (5 to 32 characters of a-z, 0-9 and _, ending in bot). It is valid for 15 minutes. The claim is made on your phone and the registry only ever sees its hash; init shows you the owner's username as the chain states it, never as the registry says it.

{
  "name": "Weather",
  "about": "Forecasts for any city",
  "description": "Send me a city name and I answer with the forecast.",
  "commands": [{ "command": "start", "description": "Begin" }],
  "group_privacy": true,
  "join_groups": true
}

The data directory holds vault.json (the encrypted recovery phrase and store key), token (the HTTP token), bot.json (wallet, username, owner) and core/ (the encrypted message store, which also holds the update queue). On Unix it is 0700 and every file in it 0600; on Windows keep it inside your own user profile.

Bots in groups

A group admin adds a bot like a person, in the apps by @username. The group's 100-member limit applies. A bot account accepts being added unless its profile says join_groups is false. Removing a bot rotates the group's sender key exactly as removing a person does. A bot never sees what was said before it joined: it has no key for it.

Privacy mode

Privacy mode is on by default. While it is on, the people who send to a group hand the bot only what is addressed to it. Turn it off with setMyPrivacy or group_privacy in the profile.

The exact rules the sending apps follow while privacy mode is on:

• Only a text message that is not forwarded and has no story reference can pass.
• A command is the first word: /cmd for every bot, or /cmd@name where name equals the bot's username, ignoring ASCII case. A command is 1 to 32 of a-z, 0-9 and _.
• A mention is @username as a whole word (ignoring ASCII case, with no letter, digit or _ on either side), or dchat:<bot did> followed by the end of the text or a character that is not a letter, digit or _.
• A reply counts when it answers a message that the sender's own record shows was sent by the bot.
• An edit, a delete or a reaction reaches the bot only for a message the bot itself received.
• A bot that is an admin of the group gets all content, as other platforms do.
• Group control messages (members added or removed, admin and info changes, key distribution and rotation) go to every member, bots included. They are not updates, but without them a bot could not read what it is meant to get.

Sending in a group

• sendMessage with chat_id group:<id>. The bot must be an active member (403 not_a_member otherwise). reply_to_message_id makes the message an answer.
• Inline keyboards only. A reply keyboard answers 400 reply_keyboard_not_supported_in_groups.
• A member's tap on a button goes to the bot privately. The bot gets a callback_query naming the group, only when the tap comes from a current member, and answers it one to one.
• editMessageText and deleteMessage act on the bot's own group messages.
• leaveChat leaves the group.
• A bot has no admin powers through this interface: it cannot add or remove members, promote anyone, rename the group or make invite links, even when it is a group admin.

Inline mode

Inline mode lets a person use your bot from any chat without opening it. They type @yourbot, a space and a query. The app lists your results above the message field, and the person taps one. That result's text is sent into the chat as the person's own message, marked "via @yourbot".

Turning it on

Call setMyInlinePlaceholder once, with the hint you want people to see, such as Search cats. That makes the bot an inline bot; getMe then reports supports_inline_queries as true. An empty placeholder turns it off again. The apps offer a bot inline only while it is an active registered bot with a placeholder.

How a query goes

1. The person types @yourbot cats. The app waits 600 milliseconds after the last key press before it asks, so fast typing sends one query, not one for each letter. It sends at most 30 queries a minute to one bot.
2. You receive an inline_query update from getUpdates. Its offset is empty for the first page.
3. You call answerInlineQuery with up to 50 articles. Each query can be answered once, within 30 seconds, but the app stops waiting after 10 seconds, so answer fast.
4. The person taps a result. The app sends its message_text to the chat they are in, as their own message with via_bot. Nothing is sent without that tap.

A button with switch_inline_query_current_chat fills the message field with @yourbot and its text. It fills it quietly: no query is sent until the person types.

Paging and caching

Set next_offset and the app asks for the next page, with that value as offset, when the person scrolls near the end of the list. Set cache_time and the app may reuse the answer for the same query and offset for that many seconds, instead of asking again. The app keeps at most 20 cached answers for each bot, and drops them when the person logs out or blocks or turns off the bot.

What your bot learns

Your bot learns the account of the person (DID, wallet and chat key, which every message from them carries), when they type, and everything they type after your bot's name. It never learns which chat they are in, the chat type, who else is in it, a location, or the person's profile. It never sees which result was picked or where it went, and there is no update for that.

A query and an answer are not messages. They make no chat, no row and no receipt on either side. The first time a person uses any inline bot, the app tells them that what they type after the bot's name is sent to that bot.

Messages sent through your bot

• The message belongs to the person. It carries via_bot, and the apps draw "via @yourbot" on it only for a registered bot. Tapping the label puts @yourbot in the field, or opens your chat if the bot is not an inline bot.
• A text with via_bot never counts as a command, a mention or a reply for privacy mode, and the bot is not sent the message because of the label. So a result such as /transfer@paybot 100 cannot reach another bot under the person's name.
• The message shows no link preview, because the sender's app would otherwise fetch a link you chose. The link stays tappable behind the usual question.
• Any person can type a label by hand, so it proves nothing. Never trust a message because it says "via".

Mini apps

A mini app is your own web page, opened inside DChat from the bot's Menu button, an inline button or a reply keyboard button. The page learns, with proof, which DChat account opened it. No key ever enters the page, the page runs on your own https server, and DChat hosts nothing. The apps that open mini apps in this version are Android and the web app.

One origin for each bot

You register one link with setChatMenuButton. Every mini app button you send must be on that exact origin, or the apps refuse to open it. A page that navigates away to another origin leaves the mini app. Links follow the WebAppInfo rules.

What the page receives

The app signs launch data with the account's own key and puts it in the page's URL fragment, which no server ever sees: #dchatWebAppData=..., with dchatWebAppVersion, dchatWebAppPlatform and the theme colors beside it. The data carries the bot, the origin, the user's did and wallet, the chat type, the start parameter, the time and a one-time number. It carries no name, picture, phone number, contacts or chat id.

The page never decodes it. It hands the raw string to your backend, and your backend asks the gateway with validateWebAppData.

The page library

Include /js/dchat-web-app.js from dchat.online in your page. It finds the right way to talk to the app by itself and gives you window.DChat.WebApp:

• Values and calls: initData, initDataUnsafe, canSendData, version, platform, themeParams, colorScheme, viewportHeight, ready(), expand(), close(), sendData(text), openLink(url), showPopup(params, callback), showAlert, showConfirm, setHeaderColor, setBackgroundColor, setBottomBarColor, enableClosingConfirmation(), disableClosingConfirmation(), onEvent(name, callback), offEvent(name, callback).
• MainButton: setText, show, hide, enable, disable, showProgress, hideProgress, setParams, onClick, offClick.
• BackButton: show, hide, onClick, offClick.
• HapticFeedback: impactOccurred, notificationOccurred, selectionChanged.

initDataUnsafe is the same data, already read for you. It is named unsafe on purpose: only your backend may trust it, after validateWebAppData. sendData(text) works only for a mini app opened from a reply keyboard button; canSendData is true exactly then, so show your send button only when it is.

What a page can and cannot do

• It can: read the launch data, take the app's colors and sizes, show a main button and a back button, ask before closing, open a native popup, alert or confirm, give haptic feedback, set its header, background and bottom bar colors, open an https link (only right after a tap, and the user is asked first), send one piece of data back, and close.
• It cannot, in this version: use the camera, location, clipboard, downloads, file picking, QR scanning or payments. Every permission the page asks for is denied. It cannot draw over the app's own header, which always shows the bot name and the host. Any request the app does not support is answered as unsupported.
• Messages between the page and the app are dropped when they are over 64 KB.

The first-open notice

The first time a user opens a bot's mini app, the app shows a notice that names what the page will receive, before the page opens. The user can clear a bot's mini app data from the app's settings.

Bots in channels

A bot posts to a channel exactly as a person admin does, signing with its own account key. The channel owner makes the bot an admin in the app, and the channel service enforces what it may do, so the bot cannot bypass it.

• Channel posts are plain text, 1 to 4096 characters. Buttons on a post are not available yet: reply_markup answers 400 markup_not_supported_in_channels.
• The answer to a post carries the post's sequence number as message_id. Use it with edit and delete.
• 20 posts, edits and deletes a minute for each channel. The middleware's own 64 KB body limit still applies.
• A bot cannot post to a channel it is not an admin of, beyond the rights above, or after it has been disabled. A channel that lets anyone post does not cover a bot without its own grant.
• A bot cannot create or own a channel. Channels send no updates, so a bot does not read a channel back.

Limits and errors

Send limits

Every send, edit and delete counts. Past a limit the answer is 429 with parameters.retry_after (whole seconds, at least 1) and nothing is sent.

These limits bind an honest owner. A stolen key can run its own client; against that the owner disables the bot.

Size limits

Error codes

Examples

A complete echo bot in Python, using the standard library only, ships with dchat-bot as examples/echo_bot.py. Send it /buttons to see inline buttons and a callback answer, and /keyboard and /hide for a reply keyboard. These are its two core pieces.

import json, os, urllib.error, urllib.request

BASE = os.environ.get("DCHAT_BOT_URL", "http://127.0.0.1:8081")
TOKEN = os.environ["DCHAT_BOT_TOKEN"]

def call(method, **params):
    request = urllib.request.Request(
        f"{BASE}/{method}",
        data=json.dumps(params).encode("utf-8"),
        headers={"Content-Type": "application/json", "Authorization": f"Bearer {TOKEN}"},
        method="POST",
    )
    try:
        with urllib.request.urlopen(request, timeout=60) as response:
            answer = json.load(response)
    except urllib.error.HTTPError as e:
        answer = json.load(e)
    if not answer.get("ok"):
        raise RuntimeError(f"{method}: {answer.get('error_code')} {answer.get('description')}")
    return answer["result"]

offset = 0
while True:
    updates = call("getUpdates", offset=offset, timeout=50)
    for update in updates:
        offset = update["update_id"] + 1
        if "callback_query" in update:
            query = update["callback_query"]
            call("answerCallbackQuery", callback_query_id=query["id"], text="Got it.")
        elif "message" in update:
            message = update["message"]
            call("sendMessage", chat_id=message["chat"]["id"], text=message["text"])

Note that chat_id is simply the chat.id of the update, which is the user's wallet in a private chat and group:<id> in a group. Wrap each update in a try block in a real bot, so one refused call does not stop the loop.

curl -s http://127.0.0.1:8081/sendMessage \
  -H "Authorization: Bearer $DCHAT_BOT_TOKEN" -H "Content-Type: application/json" \
  -d '{"chat_id":"dc1...","text":"Do you like buttons?","reply_markup":{"inline_keyboard":[[{"text":"Yes","callback_data":"vote:yes"},{"text":"No","callback_data":"vote:no"}]]}}'

Coming from other bot platforms

Method names, field names and the answer envelope match the common Bot API on purpose, so code you already know ports with small changes. These are the differences that matter.