Build bot experiences on MPChat.

getMe Get bot information

Returns the current Bot as a Telegram `User`. `result.id` (that is, `getMe.id`) is the Bot's global surrogate user ID. It is identical to the Bot ID in `Message.from`, `CallbackQuery.message.from`, and `ChatMember.user`, and `getMe.id` can be used directly as `getChatMember.user_id` when querying the current Bot.

No request body fields.

curl -X GET "https://call.mp.net/bot/bot<bot-token>/getMe" \
  -H "Content-Type: application/json" \
  -d '{}'

getMe Get bot information (POST)

Returns the current Bot as a Telegram `User`. `result.id` (that is, `getMe.id`) is the Bot's global surrogate user ID. It is identical to the Bot ID in `Message.from`, `CallbackQuery.message.from`, and `ChatMember.user`, and `getMe.id` can be used directly as `getChatMember.user_id` when querying the current Bot.

No request body fields.

curl -X POST "https://call.mp.net/bot/bot<bot-token>/getMe" \
  -H "Content-Type: application/json" \
  -d '{}'

getMyDefaultNotification Get the Bot default notification policy

Returns the current Bot's global default notification policy. Private and group chats share this one value; an unset value returns `false` to preserve audible delivery.

No request body fields.

curl -X POST "https://call.mp.net/bot/bot<bot-token>/getMyDefaultNotification" \
  -H "Content-Type: application/json" \
  -d '{}'

getUpdates Get updates by polling

Polls for pending updates. **Note**: calling this method while a webhook is configured returns 409 Conflict. **Retention**: pending updates that have not been successfully delivered are retained for at most 24 hours; older updates are no longer returned. **timeout**: supports `0..50` seconds of long polling. If updates are already available, the response returns immediately; otherwise the server waits up to `timeout` seconds before returning an empty array. **allowed_updates**: a non-empty array stores and uses an explicit type set; an empty array resets the policy to the default set; omission keeps the Bot's stored policy, using the default set only when none exists. The default set excludes `chat_member`, `message_reaction`, and `message_reaction_count`. A successful response consumes only the updates actually returned in that batch.

The group-service contract includes `group_chat_created`, `new_chat_members`, `left_chat_member`, `new_chat_title`, `new_chat_photo`, `pinned_message`, and `chat_owner_changed`; member updates include `my_chat_member` / `chat_member`, and join requests include `chat_join_request.user_chat_id`. Omitted `allowed_updates` keeps the stored policy, an empty array resets to the default set, and a non-empty array stores an explicit set; the default excludes `chat_member`, `message_reaction`, and `message_reaction_count`. Kafka-sourced group events remain pre-release, while join-request actions remain unavailable.

No request body fields.

curl -X GET "https://call.mp.net/bot/bot<bot-token>/getUpdates" \
  -H "Content-Type: application/json" \
  -d '{
  "timeout": 30,
  "limit": 50
}'

getUpdates Get updates by polling (POST)

Same behavior as GET. Supports `0..50` seconds of long polling; when no updates are currently available, the server waits up to `timeout` seconds. Omitted **allowed_updates** keeps the stored policy, an empty array resets it to the default set, and a non-empty array stores an explicit set. A successful response consumes only the returned batch.

The group-service contract includes `group_chat_created`, `new_chat_members`, `left_chat_member`, `new_chat_title`, `new_chat_photo`, `pinned_message`, and `chat_owner_changed`; member updates include `my_chat_member` / `chat_member`, and join requests include `chat_join_request.user_chat_id`. Omitted `allowed_updates` keeps the stored policy, an empty array resets to the default set, and a non-empty array stores an explicit set; the default excludes `chat_member`, `message_reaction`, and `message_reaction_count`. Kafka-sourced group events remain pre-release, while join-request actions remain unavailable.

curl -X POST "https://call.mp.net/bot/bot<bot-token>/getUpdates" \
  -H "Content-Type: application/json" \
  -d '{
  "timeout": 30,
  "limit": 50
}'

logOut Log out bot

Marks the bot as inactive, clears related cache, and disables associated webhooks.

No request body fields.

curl -X POST "https://call.mp.net/bot/bot<bot-token>/logOut" \
  -H "Content-Type: application/json" \
  -d '{}'

setMyDefaultNotification Set the Bot default notification policy

Sets the current Bot's global default notification policy. Future send or pin calls that omit `disable_notification` use this value; an explicit request value takes precedence.

curl -X POST "https://call.mp.net/bot/bot<bot-token>/setMyDefaultNotification" \
  -H "Content-Type: application/json" \
  -d '{}'

answerCallbackQuery Answer a callback query

Ends client loading within 300 seconds of the callback. Currently, only `callback_query_id` has an effect in IM clients. To preserve Telegram compatibility, the API still accepts `text` and `show_alert`; the server currently filters user-provided `text`, while `show_alert` remains in the protocol but clients do not yet display a Toast or Alert. Each button press creates a distinct callback query. The same `callback_query_id` can succeed only once; repeated, in-flight, expired, or invalid IDs return 400 without sending another control message. Telegram `url` and `cache_time` are not supported.

Only callback_query_id currently has an effect in MP clients. For Telegram compatibility, the API still accepts text up to 200 characters and show_alert, but the server filters user-provided text; show_alert remains in the protocol and clients do not display a Toast or Alert yet. The answer window is fixed at 300 seconds; url and cache_time are not supported. Each button press creates a distinct callback query. The same callback_query_id can succeed only once; repeated, in-flight, expired, or invalid IDs return 400 without sending another control message.

curl -X POST "https://call.mp.net/bot/bot<bot-token>/answerCallbackQuery" \
  -H "Content-Type: application/json" \
  -d '{
  "callback_query_id": "callback-message-uid"
}'

sendAnimation Send an animation

Sends a GIF or silent H.264/MPEG-4 animation from an HTTPS URL, form URL, or multipart upload. Animations always use `MM:MpBotInlineMsg V2`; `reply_markup` accepts the four strict Telegram variants documented by this service. Existing `file_id` reuse is not supported. A group target where the bot is not a member returns 403. `caption_entities` supports the same explicit `text_mention` validation and UTF-16 offsets as text entities. When omitted, a non-empty caption automatically resolves raw `@username`; an explicit empty array disables automatic enhancement. If the user has blocked the bot in a private chat, sending returns HTTP `403`, `error_code: 403`, and `Forbidden: bot was blocked by the user`.

MP supports animation HTTPS URLs, multipart upload, caption_entities, disable_notification, and the documented reply_markup subset. It always maps to MM:MpBotInlineMsg V2 and does not support existing file_id reuse. Omitted caption_entities enables raw-mention enhancement; an explicit empty array disables it. Ordinary Inline button url also supports HTTP/HTTPS/mppay:// with the same client support as sendMessage.

curl -X POST "https://call.mp.net/bot/bot<bot-token>/sendAnimation" \
  -H "Content-Type: application/json" \
  -d '{
  "chat_id": "12345",
  "animation": "https://example.com/animation.gif",
  "caption": "animation"
}'

sendChatAction Send chat action

Sends a temporary chat action indicator. Clients usually show this state briefly and do not persist it as a message.

This method is currently not supported and returns 501.

curl -X POST "https://call.mp.net/bot/bot<bot-token>/sendChatAction" \
  -H "Content-Type: application/json" \
  -d '{}'

sendDocument Send document message

Sends a document message to the specified MPChat conversation. Supports public file URLs and multipart uploads; existing `file_id` reuse is not currently supported. `caption_entities` supports the same explicit `text_mention` validation and UTF-16 offsets as text entities. When omitted, a non-empty caption automatically resolves raw `@username`; an explicit empty array disables automatic enhancement. `reply_markup` is intentionally unsupported for documents and is rejected with 400. If the user has blocked the bot in a private chat, sending returns HTTP `403`, `error_code: 403`, and `Forbidden: bot was blocked by the user`.

MP supports public file URLs, multipart upload, caption_entities, and disable_notification, but not existing file_id reuse; reply_markup is explicitly rejected with 400.

curl -X POST "https://call.mp.net/bot/bot<bot-token>/sendDocument" \
  -H "Content-Type: application/json" \
  -d '{
  "chat_id": "12345",
  "document": "https://example.com/file.pdf",
  "caption": "document"
}'

sendLocation Send location message (not supported)

This method is not supported in the current release and returns `501`. The request body is still validated using the existing field rules; invalid parameters return `400`.

This method is not supported in the current release and returns 501.

curl -X POST "https://call.mp.net/bot/bot<bot-token>/sendLocation" \
  -H "Content-Type: application/json" \
  -d '{}'

sendMessage Send text message

Sends a text message to the specified MPChat conversation. Supports the `parse_mode` and `reply_to_message_id` parameters. Supports Telegram-style `reply_markup.inline_keyboard[].web_app` for MiniApp entry messages. Ordinary `web_app` inline keyboards, reply keyboards, and message edits are supported only in private chats with the current bot. `sendMessage` keeps one MPChat group-sharing compatibility path: when `inline_keyboard` contains exactly one row with one button and that button contains only `text` and `web_app`, it may be sent to a group or supergroup that the bot has joined. Channels are not supported by this exception; all other `web_app` combinations in groups or supergroups return 400. An unsupported chat context returns the chat-type error before MiniApp lookup. MiniApp resolution runs only for an allowed private chat or strict group share. Positive tests require a matching enabled MiniApp configured for the current bot; otherwise the response is `MiniApp not found` or `MiniApp is disabled`, which does not verify the chat-type restriction. A `web_app.url` must be either the current bot's registered MiniApp `entryUrl` or a platform direct link in the form `https://mp.net/{currentBotUsername}/{shortName}`. A direct link may include query parameters such as `?startapp=...&mode=compact`; query parameters do not participate in MiniApp ownership resolution. The server never infers a MiniApp from an arbitrary URL's final path segment. Supports Telegram-style `link_preview_options`; `is_disabled = true` disables normal link previews and makes `web_app` MiniApp entries send as text without an entry card. Supports `entities` for @ text ranges; currently only `text_mention` is supported. Explicit entities retain strict group-member validation and group @ reminder semantics. When a private, group, or supergroup request omits the `entities` field entirely, the server attempts global exact resolution of raw `@username` text and applies automatic enhancement. An explicit empty array disables automatic enhancement. A raw username consumes `[A-Za-z0-9_-]+`, preserves its original case, and is matched case-sensitively; email-like text is not recognized as a mention, and nicknames, display names, and fuzzy matches are never used to infer identity. The default limit is 100 raw mention tokens per message. More than 100 tokens sends the original text and must not read mention caches, perform a global lookup, replace nicknames, or build automatic entities. A cache hit cannot bypass the over-limit decision. Nickname replacement can be disabled by configuration while identity resolution and entity construction remain enabled. A clickable display entity is separate from a group @ reminder: private-chat users and group non-members can still receive display entities, while only confirmed group members produce group reminders. If the user has blocked the bot in a private chat, sending returns HTTP `403`, `error_code: 403`, and `Forbidden: bot was blocked by the user`.

reply_markup supports InlineKeyboardMarkup, ReplyKeyboardMarkup, ReplyKeyboardRemove, and ForceReply. Reply Keyboard drives an independent right-side keyboard toggle without affecting the left-side Bot Menu Button. one_time_keyboard collapses after use but remains summonable, is_persistent requests continued visibility, remove_keyboard deletes effective state, and force_reply preserves the keyboard snapshot. Buttons are limited to callback_data, HTTP/HTTPS/MPPAY url, an enabled MiniApp web_app owned by the current bot, object-form copy_text, and optional style. Ordinary web_app inline keyboards, reply keyboards, and message edits are supported only in private chats with the current bot. When sendMessage receives an inline_keyboard with exactly one row and one button containing only text and web_app, that MiniApp sharing card is an MPChat group-sharing compatibility exception and may target a group or supergroup that the bot has joined. Channels are not supported by this exception; all other web_app combinations in groups or supergroups return 400 before MiniApp lookup. Allowed contexts still require a matching enabled MiniApp configured for the current bot; MiniApp not found or MiniApp is disabled means the positive-test prerequisite is missing and does not verify the chat-type restriction. Other Telegram button fields return 400. LinkPreviewOptions, text_mention, and disable_notification (request value overrides the Bot default) are supported; full web_app_data, sendData, and answerWebAppQuery return flows are not supported yet. Ordinary Inline button url supports HTTP/HTTPS and the MPChat payment scheme mppay:// (for example mppay://ord_example), preserved unchanged. This extension requires an MPChat client with MPPAY support; clients reading only the legacy keyboard projection cannot display ordinary URL buttons. The server does not validate orders or execute payments; web_app and Bot Menu Button retain separate HTTPS rules.

curl -X POST "https://call.mp.net/bot/bot<bot-token>/sendMessage" \
  -H "Content-Type: application/json" \
  -d '{
  "chat_id": "12345",
  "text": "@Chen @Lei invites you to this activity",
  "entities": [
    {
      "type": "text_mention",
      "offset": 0,
      "length": 5,
      "user": {
        "id": "2000000154"
      }
    },
    {
      "type": "text_mention",
      "offset": 6,
      "length": 4,
      "user": {
        "id": "2000000168"
      }
    }
  ]
}'

sendPhoto Send photo message

Sends a photo message to the specified MPChat conversation. Supports public image URLs and multipart uploads; existing `file_id` reuse is not currently supported. When source metadata is available, the server uses the actual media dimensions and file size in the returned Message. Generated thumbnails target a 240-pixel longest side while preserving aspect ratio and avoiding enlargement of smaller images; a valid candidate slightly above that recommendation does not fail the request. If thumbnail generation fails, the photo is still sent without a thumbnail. `caption_entities` supports the same explicit `text_mention` validation and UTF-16 offsets as text entities. When omitted, a non-empty caption automatically resolves raw `@username`; an explicit empty array disables automatic enhancement. If the user has blocked the bot in a private chat, sending returns HTTP `403`, `error_code: 403`, and `Forbidden: bot was blocked by the user`.

MP supports public image URLs, multipart upload, caption_entities, disable_notification, and the documented reply_markup subset, but not existing file_id reuse. Omitted caption_entities enables raw-mention enhancement; an explicit empty array disables it. Ordinary Inline button url also supports HTTP/HTTPS/mppay:// with the same client support as sendMessage.

curl -X POST "https://call.mp.net/bot/bot<bot-token>/sendPhoto" \
  -H "Content-Type: application/json" \
  -d '{
  "chat_id": "12345",
  "photo": "https://example.com/cat.jpg",
  "caption": "hello"
}'

sendPoll Send poll message (currently unsupported)

This route currently retains only the shared authentication and request validation entry point; poll delivery is not supported. Parameters that do not match the request schema return `400` before the Service is called, while a valid request returns `501`. `options` must be an array of strings; a `400` caused by object options does not mean poll delivery is implemented.

This method is currently not supported and returns 501.

curl -X POST "https://call.mp.net/bot/bot<bot-token>/sendPoll" \
  -H "Content-Type: application/json" \
  -d '{}'

sendVideo Send video message

Sends a video message to the specified MPChat conversation. Supports public video URLs and multipart uploads; existing `file_id` reuse is not currently supported. The server uses metadata from the final server-managed media object for the returned Message dimensions, duration, and file size. Request duration, width, and height values remain accepted as compatibility hints but are not used as fallback values. Display dimensions account for rotation, and the returned duration is the actual fractional duration rounded up to a whole second. Video transcoding is not performed. Videos up to 500 MiB are delivered with original-video semantics (`full=true`); videos above 500 MiB and up to 1 GiB are delivered as file messages, while larger inputs are rejected with `error_code: 400`. Every new native video requires a valid first-frame thumbnail. Thumbnails target a 240-pixel longest side while preserving aspect ratio and avoiding enlargement; server-side fallback processing is used when local generation is unavailable. The request fails before delivery with `error_code: 50001` when metadata or both thumbnail stages fail, or when bounded compression cannot keep the complete video message with its thumbnail within 131072 UTF-8 bytes. `caption_entities` supports the same explicit `text_mention` validation and UTF-16 offsets as text entities. When omitted, a non-empty caption automatically resolves raw `@username`; an explicit empty array disables automatic enhancement. If the user has blocked the bot in a private chat, sending returns HTTP `403`, `error_code: 403`, and `Forbidden: bot was blocked by the user`.

MP supports public video URLs, multipart upload, caption_entities, disable_notification, and the documented reply_markup subset, but not existing file_id reuse. Omitted caption_entities enables raw-mention enhancement; an explicit empty array disables it. Ordinary Inline button url also supports HTTP/HTTPS/mppay:// with the same client support as sendMessage.

curl -X POST "https://call.mp.net/bot/bot<bot-token>/sendVideo" \
  -H "Content-Type: application/json" \
  -d '{
  "chat_id": "12345",
  "video": "https://example.com/video.mp4",
  "caption": "video"
}'

copyMessage Copy message

Copies an existing message into the target conversation and returns the new `message_id`. The result does not include `forward_from`. Returns 400 when the source message does not exist, is not accessible, or the message type is not currently supported for copying. If the user has blocked the bot in a private chat, sending returns HTTP `403`, `error_code: 403`, and `Forbidden: bot was blocked by the user`.

curl -X POST "https://call.mp.net/bot/bot<bot-token>/copyMessage" \
  -H "Content-Type: application/json" \
  -d '{}'

copyMessages Copy messages in batch

Copies the specified messages one by one using `copyMessage` semantics. Returns 400 when any source message does not exist, is not accessible, or the message type is not currently supported for copying. The response does not include partial `message_ids` results. If the user has blocked the bot in a private chat, sending returns HTTP `403`, `error_code: 403`, and `Forbidden: bot was blocked by the user`. If the user blocks the bot during a batch, subsequent sends stop; messages already sent remain and are not rolled back.

curl -X POST "https://call.mp.net/bot/bot<bot-token>/copyMessages" \
  -H "Content-Type: application/json" \
  -d '{}'

deleteMessage Delete message

Deletes a message sent by the current bot or received by the current bot in a private chat. Every deletable message requires a trusted sent time and can be deleted only within 48 hours of that time; missing, already-deleted, or expired messages return 400. In group chats, an administrator bot with the Recall messages permission can also delete messages sent by regular members. Messages sent by the group owner or administrators cannot be deleted by another administrator bot; administrator permission does not exempt the message from the 48-hour limit, and insufficient permission returns 403.

Bot-authored messages and messages received by the Bot in a private chat require a trusted sent time and can be deleted only within 48 hours; missing, already-deleted, or expired messages return 400. An administrator bot with the Recall messages permission can delete a regular group member message, but is subject to the same time limit.

curl -X POST "https://call.mp.net/bot/bot<bot-token>/deleteMessage" \
  -H "Content-Type: application/json" \
  -d '{
  "chat_id": "12345",
  "message_id": 678
}'

deleteMessages Delete messages in batch

Deletes multiple messages sent by the current bot or received by the current bot in a private chat. Every deletable message requires a trusted sent time and can be deleted only within 48 hours of that time. An administrator bot can delete a regular group member's message only within that same time limit. In group chats, an administrator bot with the Recall messages permission can also delete messages sent by regular members. Messages sent by the group owner or administrators cannot be deleted by another administrator bot. Each request uses one chat_id and must contain 1 to 100 distinct message_ids after numeric-string normalization. Every message is checked for mapping, sender, sent time, and permission before any deletion is sent. If preflight fails, no other message in the batch is deleted. After preflight, remote deletion is sequential; an execution failure returns an error while earlier completed deletions remain effective, with no cross-service rollback.

Each request accepts one chat_id and 1 to 100 distinct message_ids after numeric-string normalization. Numeric strings and numbers are both accepted, but for example 123 and "123" are duplicates and return 400. All local preflight checks finish before sequential deletion starts; an execution failure returns an error, completed earlier items remain deleted, and no rollback is promised.

curl -X POST "https://call.mp.net/bot/bot<bot-token>/deleteMessages" \
  -H "Content-Type: application/json" \
  -d '{
  "chat_id": "12345",
  "message_ids": [
    678,
    "679"
  ]
}'

editMessageCaption Edit a media caption

Edits the `caption` of a bot-authored photo, video, animation, or document using `chat_id + message_id`. Omitting the caption or passing an empty string clears both caption and entities; entities and buttons use replacement semantics. Native photo/video/document messages can update caption/entities but cannot accept non-empty buttons. V2 photo/video/animation messages can update caption/entities/buttons atomically. Business/inline messages, `parse_mode`, and `show_caption_above_media` return 400.

MP edits bot-authored photo/video/animation/document via chat_id + message_id and supports JSON/form caption, caption_entities, and replacement reply_markup. Native photo/video/document can update caption/entities but reject non-empty buttons; V2 photo/video/animation can update all three atomically. Omitted or empty caption clears old caption/entities. Business, inline_message_id, parse_mode, and show_caption_above_media return 400.

curl -X POST "https://call.mp.net/bot/bot<bot-token>/editMessageCaption" \
  -H "Content-Type: application/json" \
  -d '{
  "chat_id": 12345,
  "message_id": 678,
  "caption": "Updated caption"
}'

editMessageMedia Replace media with the same type

Replaces a bot-authored photo, video, animation, or document with media of the same type using `chat_id + message_id`. JSON/form URLs and multipart `attach://<file_attach_name>` are accepted. External URLs and uploaded files enter controlled OSS only after permission, ownership, target type, entity, and button validation. Omitting or emptying `media.caption` clears the old caption/entities. Omitting top-level `reply_markup`, passing null, or passing an empty keyboard clears old buttons. Native media does not accept non-empty buttons. Audio/live-photo, albums, cross-type edits, text-to-media conversion, Business messages, and inline messages return 400.

MP replaces bot-authored photo/video/animation/document only with the same type via chat_id + message_id. JSON/form URLs and multipart attach:// uploads are supported; controlled OSS ingestion starts only after permission, ownership, type, entity, and button validation. media caption/entities and top-level reply_markup use replacement semantics, so omission clears old values. Native media rejects non-empty buttons. Business, inline_message_id, audio/live-photo, albums, cross-type edits, text/rich-to-media, and file_id reuse are unsupported.

curl -X POST "https://call.mp.net/bot/bot<bot-token>/editMessageMedia" \
  -H "Content-Type: application/json" \
  -d '{
  "chat_id": 12345,
  "message_id": 678,
  "media": {
    "type": "photo",
    "media": "https://cdn.example.com/replacement.jpg",
    "caption": "Optional new caption"
  }
}'

editMessageReplyMarkup Edit a message Inline Keyboard

Uses `chat_id + message_id` to replace only the buttons of a native text or locally readable Inline message sent by the current bot. For native text, the InlineKeyboardMarkup is written to `content.extra.reply_markup`, preserving the original text, `message_id`, and other message identity fields without converting it to an Inline message. Inline messages preserve text, entities, media, and other content. Omitting `reply_markup`, passing `null`, or passing an empty `inline_keyboard` removes the buttons. A replacement `web_app.url` must remain either the current bot's registered MiniApp `entryUrl` or a platform direct link in the form `https://mp.net/{currentBotUsername}/{shortName}`. A direct link may include query parameters such as `?startapp=...&mode=compact`, which do not participate in MiniApp ownership resolution. Business messages and `inline_message_id` are unsupported. Body, caption, entity, and media fields are rejected by the strict schema with 400. Success always returns `Message`.

MP accepts JSON/form and locates bot-authored native text or locally readable V1/V2 Inline messages by chat_id + message_id. It replaces buttons only and preserves text, entities, link preview, caption, media, and mp_ext. Omitted/null/empty reply_markup removes buttons. Business, inline_message_id, and body/caption/entity/media fields return 400; success always returns Message. Ordinary Inline button url also supports HTTP/HTTPS/mppay://.

curl -X POST "https://call.mp.net/bot/bot<bot-token>/editMessageReplyMarkup" \
  -H "Content-Type: application/json" \
  -d '{
  "chat_id": "12345",
  "message_id": 678,
  "reply_markup": {
    "inline_keyboard": [
      [
        {
          "text": "Refresh",
          "callback_data": "menu:refresh"
        }
      ]
    ]
  }
}'

editMessageText Edit message text

Edits a bot-authored native text message or a V1/V2 Inline message whose canonical `media` is `null`. `entities`, `link_preview_options`, and `reply_markup` use replacement semantics: omitted `entities` reruns raw-mention enhancement, an empty entity array clears entities, omitted preview options reset explicit preview settings, and omitted/null/empty markup removes buttons. Inline media, Business/inline messages, `parse_mode`, `rich_message`, and game messages are unsupported and return 400. MPChat supports only `chat_id + message_id`; success always returns `Message`, never Telegram's inline-message `True` branch.

MP edits bot-authored native text or V1/V2 Inline text whose canonical media is null via chat_id + message_id. JSON/form entities, link_preview_options, and reply_markup are supported. Compound edits use replacement semantics: omitted entities rerun enhancement, omitted preview options reset explicit settings, and omitted/null/empty markup removes buttons. Business, inline_message_id, parse_mode, rich_message, game, and Inline media return 400; success always returns Message. Ordinary Inline button url also supports HTTP/HTTPS/mppay://.

curl -X POST "https://call.mp.net/bot/bot<bot-token>/editMessageText" \
  -H "Content-Type: application/json" \
  -d '{
  "chat_id": "12345",
  "message_id": 678,
  "text": "Order completed",
  "reply_markup": {
    "inline_keyboard": []
  }
}'

forwardMessage Forward message

Forwards an existing message to the target conversation. The result includes `forward_from`. Returns 400 when the source message cannot be read, has been deleted, or the message type is not currently supported. If the user has blocked the bot in a private chat, sending returns HTTP `403`, `error_code: 403`, and `Forbidden: bot was blocked by the user`.

curl -X POST "https://call.mp.net/bot/bot<bot-token>/forwardMessage" \
  -H "Content-Type: application/json" \
  -d '{}'

forwardMessages Forward messages in batch

Forwards the specified messages one by one using `forwardMessage` semantics. Returns 400 when any source message does not exist, is not accessible, or the message type is not currently supported for forwarding. No partial success is returned. If the user has blocked the bot in a private chat, sending returns HTTP `403`, `error_code: 403`, and `Forbidden: bot was blocked by the user`. If the user blocks the bot during a batch, subsequent sends stop; messages already sent remain and are not rolled back.

curl -X POST "https://call.mp.net/bot/bot<bot-token>/forwardMessages" \
  -H "Content-Type: application/json" \
  -d '{}'

pinChatMessage Pin message

Pins a message in a group chat. Currently supported for group conversations only. Returns 404 when the message does not exist and 403 when the bot lacks permission.

curl -X POST "https://call.mp.net/bot/bot<bot-token>/pinChatMessage" \
  -H "Content-Type: application/json" \
  -d '{}'

recallMessage Recall message

Recalls a message sent by the current bot or received by the current bot in a private chat. Every recallable message requires a trusted sent time and can be recalled only within 48 hours of that time; missing, already-deleted, or expired messages return 400. In group chats, an administrator bot with the Recall messages permission can also recall messages sent by regular members. Messages sent by the group owner or administrators cannot be recalled by another administrator bot; administrator permission does not exempt the message from the 48-hour limit, and insufficient permission returns 403. This method is an MPChat Bot API extension for separating recall from compatible deletion. deleteMessage remains the compatible delete method.

MPChat extension method for recall; deleteMessage remains the compatible delete method. In group chats, administrator bots with the Recall messages permission can recall regular member messages, but not owner or administrator messages.

curl -X POST "https://call.mp.net/bot/bot<bot-token>/recallMessage" \
  -H "Content-Type: application/json" \
  -d '{
  "chat_id": "12345",
  "message_id": 678
}'

recallMessages Recall messages in batch

Recalls multiple messages sent by the current bot or received by the current bot in a private chat. Every recallable message requires a trusted sent time and can be recalled only within 48 hours of that time; missing, already-deleted, or expired messages return 400. In group chats, an administrator bot with the Recall messages permission can also recall messages sent by regular members. Messages sent by the group owner or administrators cannot be recalled by another administrator bot; administrator permission does not exempt the message from the 48-hour limit. This method is an MPChat Bot API extension for separating recall from compatible batch deletion. deleteMessages remains the compatible delete method. Each request uses one chat_id and must contain 1 to 100 distinct message_ids after numeric-string normalization. Every message is checked for mapping, sender, sent time, and permission before any recall is sent. If preflight fails, no other message in the batch is recalled. After preflight, remote recall is sequential; an execution failure at item N returns an error while earlier completed recalls remain effective, with no cross-service rollback.

MPChat extension method for batch recall; deleteMessages remains the compatible batch delete method. If any message fails the recall precondition, the whole request fails without partial success.

curl -X POST "https://call.mp.net/bot/bot<bot-token>/recallMessages" \
  -H "Content-Type: application/json" \
  -d '{
  "chat_id": "12345",
  "message_ids": [
    678,
    679
  ]
}'

unpinChatMessage Unpin message

Unpins a pinned message in a group chat. Currently supported for group conversations only. Returns 404 when the message does not exist and 403 when the bot lacks permission.

curl -X POST "https://call.mp.net/bot/bot<bot-token>/unpinChatMessage" \
  -H "Content-Type: application/json" \
  -d '{}'

approveChatJoinRequest Approve a chat join request

An authorized Bot can approve a user's pending chat join request using `chat_id` and `user_id`. A cancelled, expired, or already handled request returns 400.

Pre-release API. Requires chat_id and user_id, and the Bot must have permission to review join requests.

curl -X POST "https://call.mp.net/bot/bot<bot-token>/approveChatJoinRequest" \
  -H "Content-Type: application/json" \
  -d '{}'

banChatMember Restrict chat member

Current MPChat behavior restricts the member from speaking and does not remove the member from the chat. `until_date=0` or omission means the restriction remains until manually lifted. The bot must be in the target chat, and the target user must be a regular member.

Current MPChat behavior restricts the member from speaking and does not kick the user from the chat.

curl -X POST "https://call.mp.net/bot/bot<bot-token>/banChatMember" \
  -H "Content-Type: application/json" \
  -d '{
  "chat_id": "12345",
  "user_id": "2000000154",
  "until_date": 0
}'

declineChatJoinRequest Decline a chat join request

An authorized Bot can decline a user's pending chat join request using `chat_id` and `user_id`. A cancelled, expired, or already handled request returns 400.

Pre-release API. Requires chat_id and user_id, and the Bot must have permission to review join requests.

curl -X POST "https://call.mp.net/bot/bot<bot-token>/declineChatJoinRequest" \
  -H "Content-Type: application/json" \
  -d '{}'

deleteChatPhoto Delete chat photo

Deletes the chat photo. The bot may always do this when it is the chat owner. Otherwise it must have the Edit group messages permission or the request returns 403.

curl -X POST "https://call.mp.net/bot/bot<bot-token>/deleteChatPhoto" \
  -H "Content-Type: application/json" \
  -d '{}'

getChat Get chat information

Returns a Telegram-compatible `ChatFullInfo` object. The system always provides `id` and `type`; private chats may also include `first_name`, `username`, and `photo` when profile data is available. Groups, supergroups, and channels may also include `title`, `description`, and `photo` when profile data is available. `photo` uses Telegram's `ChatPhoto` shape; MPChat currently may place a downloadable avatar link in the `file_id` / `file_unique_id` fields as the media identifier. Unsupported optional Telegram `ChatFullInfo` fields are omitted.

curl -X POST "https://call.mp.net/bot/bot<bot-token>/getChat" \
  -H "Content-Type: application/json" \
  -d '{}'

getChatAdministrators Get chat administrators

Returns the administrators of a chat. The response uses the `ChatMember[]` structure with Telegram-compatible fields only; raw MPChat permission strings are not returned. Owner entries follow Telegram `ChatMemberOwner`: they return `status="creator"` and the required `is_anonymous=false`, without administrator `can_*` fields. Active Bot administrators return `user.is_bot=true` and use the authoritative Bot profile. Human administrators return `user.is_bot=false` and use the chat member profile. Returned chat-member `user.id` values are global surrogate IDs. The current Bot's value equals `getMe.id`, and `getMe.id` can be used directly as `getChatMember.user_id` to query the current Bot. This method uses the same current `group` / `supergroup` permission projection as `getChatMember`. It does not invent fine-grained administrator rights for channels, creators, or members without an authoritative permission snapshot.

curl -X POST "https://call.mp.net/bot/bot<bot-token>/getChatAdministrators" \
  -H "Content-Type: application/json" \
  -d '{}'

getChatMember Get chat member

Returns the member status and role in the specified conversation. Muted members are returned as `restricted`; otherwise the result is `creator`, `administrator`, or `member`. Chat owners follow Telegram `ChatMemberOwner`: they return `status="creator"` and the required `is_anonymous=false`. MPChat does not currently support anonymous owners or custom owner titles, and a creator does not return administrator `can_*` fields. Members backed by an active Bot record return `user.is_bot=true` and use the authoritative Bot profile. Other members return `user.is_bot=false` and use the chat member profile. Chat-member `user.id` values are global surrogate IDs. The current Bot's `getMe.id` equals its chat-member `user.id`, and `getMe.id` can be used directly as `user_id` when querying the current Bot. For other members, use the `user.id` returned by an Update or chat-member API. For MPChat `group` and `supergroup` administrators, confirmed Telegram `can_*` fields project the current permission snapshot. Channels are outside this projection. When the internal authoritative permission snapshot is missing or invalid, unsupported fine-grained projections are omitted. Raw MPChat permission strings are not returned.

curl -X POST "https://call.mp.net/bot/bot<bot-token>/getChatMember" \
  -H "Content-Type: application/json" \
  -d '{}'

getChatMemberCount Get chat member count

Returns the total number of members in the chat. The result reflects the count currently visible to the platform.

curl -X POST "https://call.mp.net/bot/bot<bot-token>/getChatMemberCount" \
  -H "Content-Type: application/json" \
  -d '{}'

leaveChat Bot leaves chat

Makes the bot leave the current conversation.

curl -X POST "https://call.mp.net/bot/bot<bot-token>/leaveChat" \
  -H "Content-Type: application/json" \
  -d '{}'

setChatDescription Set chat description

Sets the chat description or announcement. The bot may always do this when it is the chat owner. Otherwise it must have the Edit group messages permission or the request returns 403.

curl -X POST "https://call.mp.net/bot/bot<bot-token>/setChatDescription" \
  -H "Content-Type: application/json" \
  -d '{}'

setChatPhoto Set chat photo

Sets the chat photo. The bot may always do this when it is the chat owner. Otherwise it must have the Edit group messages permission or the request returns 403. The `photo` field supports a public HTTP(S) image URL, an existing MPChat avatar object identifier, or a local multipart upload. A public URL must be reachable and point to a supported image within the size limit, otherwise the request returns 400.

MP supports URL and multipart avatar upload, but does not support existing file_id reuse.

curl -X POST "https://call.mp.net/bot/bot<bot-token>/setChatPhoto" \
  -H "Content-Type: application/json" \
  -d '{
  "chat_id": "12345",
  "photo": "https://example.com/group.png"
}'

setChatTitle Set chat title

Sets the chat title. The bot may always do this when it is the chat owner. Otherwise it must have the Edit group messages permission or the request returns 403.

curl -X POST "https://call.mp.net/bot/bot<bot-token>/setChatTitle" \
  -H "Content-Type: application/json" \
  -d '{}'

unbanChatMember Unrestrict chat member

Lifts the speaking restriction for a member. The bot must have the required group management permissions. When `only_if_banned=true`, the request succeeds immediately for members who are not currently restricted.

curl -X POST "https://call.mp.net/bot/bot<bot-token>/unbanChatMember" \
  -H "Content-Type: application/json" \
  -d '{}'

deleteMyCommands Delete bot commands

No request body fields.

curl -X POST "https://call.mp.net/bot/bot<bot-token>/deleteMyCommands" \
  -H "Content-Type: application/json" \
  -d '{}'

getMyCommands Get bot commands

No request body fields.

curl -X GET "https://call.mp.net/bot/bot<bot-token>/getMyCommands" \
  -H "Content-Type: application/json" \
  -d '{}'

getMyCommands Get bot commands (POST)

No request body fields.

curl -X POST "https://call.mp.net/bot/bot<bot-token>/getMyCommands" \
  -H "Content-Type: application/json" \
  -d '{}'

setMyCommands Set bot commands

Validates each command against the format `^[a-z0-9_]{1,32}$` and replaces the current bot command list as a whole. Passing an empty array is equivalent to `deleteMyCommands`.

curl -X POST "https://call.mp.net/bot/bot<bot-token>/setMyCommands" \
  -H "Content-Type: application/json" \
  -d '{}'

getMyDescription Get bot description

Returns the default description for the current bot. When no value is configured, `result.description` is an empty string. Localized profiles are not supported in this release; a non-empty `language_code` returns 400.

MPChat currently returns only the default description. Omit language_code or pass an empty string; a non-empty language_code returns 400.

curl -X POST "https://call.mp.net/bot/bot<bot-token>/getMyDescription" \
  -H "Content-Type: application/json" \
  -d '{
  "language_code": ""
}'

getMyShortDescription Get bot short description

Returns the default short description for the current bot. When no value is configured, `result.short_description` is an empty string. Localized profiles are not supported in this release; a non-empty `language_code` returns 400.

MPChat currently returns only the default short description. Omit language_code or pass an empty string; a non-empty language_code returns 400.

curl -X POST "https://call.mp.net/bot/bot<bot-token>/getMyShortDescription" \
  -H "Content-Type: application/json" \
  -d '{
  "language_code": ""
}'

setMyDescription Set bot description

Sets the default description for the current bot. `description` is limited to 512 characters. Omitting it or passing an empty string clears the default value. Localized profiles are not supported in this release: omit `language_code` or pass an empty string; any non-empty value returns 400.

MPChat currently manages only the default description. Omit language_code or pass an empty string; a non-empty language_code returns 400.

curl -X POST "https://call.mp.net/bot/bot<bot-token>/setMyDescription" \
  -H "Content-Type: application/json" \
  -d '{
  "description": "A helpful MPChat bot."
}'

setMyShortDescription Set bot short description

Sets the default short description for the current bot. `short_description` is limited to 120 characters. Omitting it or passing an empty string clears the default value. Localized profiles are not supported in this release: omit `language_code` or pass an empty string; any non-empty value returns 400.

MPChat currently manages only the default short description. Omit language_code or pass an empty string; a non-empty language_code returns 400.

curl -X POST "https://call.mp.net/bot/bot<bot-token>/setMyShortDescription" \
  -H "Content-Type: application/json" \
  -d '{
  "short_description": "Helpful answers in MPChat."
}'

getChatMenuButton Get effective menu button

Returns the effective left-side global or private-chat Bot Menu Button. The result describes only `commands`, `web_app`, or `default`; it does not indicate whether the independent right-side Reply Keyboard toggle is visible. Omitting `chat_id` resolves the global scope. When no menu can be displayed, the result is `{ type: "default" }`.

Returns only the left-side Bot Menu Button as `default`, `commands`, or `web_app`; it does not indicate whether the right-side Reply Keyboard toggle is visible.

No request body fields.

curl -X GET "https://call.mp.net/bot/bot<bot-token>/getChatMenuButton" \
  -H "Content-Type: application/json" \
  -d '{
  "chat_id": "12345"
}'

getChatMenuButton Get effective menu button (POST)

Behaves like GET and returns only the left-side Bot Menu Button, not the right-side Reply Keyboard toggle state. Omitting `chat_id` from the request body resolves the global scope. When no menu can be displayed, the result is `{ type: "default" }`.

Returns only the left-side Bot Menu Button as `default`, `commands`, or `web_app`; it does not indicate whether the right-side Reply Keyboard toggle is visible.

curl -X POST "https://call.mp.net/bot/bot<bot-token>/getChatMenuButton" \
  -H "Content-Type: application/json" \
  -d '{
  "chat_id": "12345"
}'

setChatMenuButton Set bot menu button

Sets the left-side global or user-scoped Bot Menu Button for the current bot. The left-side control resolves to one effective `commands` or `web_app` form. It is independent from the message-driven right-side Reply Keyboard toggle; this method never creates, removes, or expands a Reply Keyboard. Omitting `chat_id` targets the global scope; a provided value must identify a private chat that has already interacted with this bot. Omitting `menu_button` is treated as `{ type: "default" }` and removes the explicit record for that scope. `web_app` accepts `text` plus any valid HTTPS URL up to 2048 characters. It does not require MiniApp ownership, a MiniApp ID, or registration under the current bot.

Manages only the left-side Bot Menu Button; `commands` and `web_app` are mutually exclusive forms. `web_app` accepts `text` plus any valid HTTPS URL up to 2048 characters and does not require MiniApp ownership or a MiniApp ID. It is independent from the message-driven right-side Reply Keyboard toggle and never creates, removes, or expands a Reply Keyboard.

curl -X POST "https://call.mp.net/bot/bot<bot-token>/setChatMenuButton" \
  -H "Content-Type: application/json" \
  -d '{
  "menu_button": {
    "type": "web_app",
    "text": "Open App",
    "web_app": {
      "url": "https://example.com/app"
    }
  }
}'

deleteWebhook Delete webhook

When `drop_pending_updates=true`, pending updates are discarded immediately.

curl -X POST "https://call.mp.net/bot/bot<bot-token>/deleteWebhook" \
  -H "Content-Type: application/json" \
  -d '{}'

getWebhookInfo Get webhook information

Returns the current webhook configuration. `pending_update_count` only includes pending updates still within the 24-hour retention window.

No request body fields.

curl -X GET "https://call.mp.net/bot/bot<bot-token>/getWebhookInfo" \
  -H "Content-Type: application/json" \
  -d '{}'

getWebhookInfo Get webhook information (POST)

Same behavior as GET. `pending_update_count` only includes pending updates still within the 24-hour retention window.

No request body fields.

curl -X POST "https://call.mp.net/bot/bot<bot-token>/getWebhookInfo" \
  -H "Content-Type: application/json" \
  -d '{}'

setWebhook Set webhook

The URL must use HTTPS. An empty string is treated the same as `deleteWebhook`. Before saving the webhook, the server sends an HTTPS POST reachability probe to the URL. The probe body may be an empty object. The webhook endpoint must return any 2xx status code; non-2xx responses cause `setWebhook` to return 400. The endpoint should not reject the probe only because it does not contain real Update fields. When `secret_token` is set, the reachability probe and subsequent real webhook delivery requests include the same value in the `X-MpChat-Bot-Api-Secret-Token` header. A non-empty `allowed_updates` stores and uses an explicit type set. Omission keeps the Bot's stored policy, using the default set only when none exists; an empty array resets to the default set. The default set excludes `chat_member`, `message_reaction`, and `message_reaction_count`. Filtered updates are not counted in `pending_update_count`.

Webhook and getUpdates share the same three-state `allowed_updates` policy and default set, and expose the same group-event field contract. Kafka-sourced group events remain pre-release; `approveChatJoinRequest` and `declineChatJoinRequest` remain unavailable.

curl -X POST "https://call.mp.net/bot/bot<bot-token>/setWebhook" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://example.com/mp-bot/webhook",
  "secret_token": "<webhook-secret>"
}'

getUserProfilePhotos Get user profile photos

Returns the `UserProfilePhotos` structure. When `user_id` equals the current Bot's `getMe.id`, the method reads the Bot's own profile photos and does not require a private-chat snapshot. Before reading another user's photos, the current Bot and target `user_id` must have a Bot-scoped private-chat snapshot whose type is `private`. A missing or non-private snapshot returns `403`. MPChat currently returns at most one profile photo group from the user profile avatar. When both avatar sizes are available, the original avatar is preferred. When no avatar is available, `total_count` is `0` and `photos` is empty.

curl -X POST "https://call.mp.net/bot/bot<bot-token>/getUserProfilePhotos" \
  -H "Content-Type: application/json" \
  -d '{}'

abortMediaUpload Cancel an unfinished media upload

Used internally by the SDK. Cancels this bot's upload before completing/ready and removes temporary objects. Repeated cancellation of an aborted upload returns its state. Never deletes ready media or recalls sent messages. Temporary cleanup failures retain the upload for background retry.

MPChat SDK upload protocol. Prefer SDK sendVideo/sendDocument for automatic upload and sending.

curl -X POST "https://call.mp.net/bot/bot<bot-token>/abortMediaUpload" \
  -H "Content-Type: application/json" \
  -d '{}'

completeMediaUpload Validate and complete a media upload

Used internally by the SDK. Verifies all parts and freezes writes, then completes in OSS and validates actual size and MP4 video content. Documents are delivered as binary attachments. Publishes a controlled URL only after validation; repeated completion recovers the original result and temporary storage failures are retryable. Does not send a message; the SDK subsequently calls the existing send method.

MPChat SDK upload protocol. Prefer SDK sendVideo/sendDocument for automatic upload and sending.

curl -X POST "https://call.mp.net/bot/bot<bot-token>/completeMediaUpload" \
  -H "Content-Type: application/json" \
  -d '{}'

createMediaUpload Create an SDK media upload

MPChat extension for the server-side SDK; developers should use SDK sendVideo/sendDocument. Supports MP4 videos or documents up to 1 GiB. Uploads expire after one hour; at most four unfinished uploads per bot. The same request_id and arguments return the existing upload; changed arguments return 400. No OSS credentials are exposed.

MPChat SDK upload protocol. Prefer SDK sendVideo/sendDocument for automatic upload and sending.

curl -X POST "https://call.mp.net/bot/bot<bot-token>/createMediaUpload" \
  -H "Content-Type: application/json" \
  -d '{}'

getMediaUpload Get upload progress

Used internally by the SDK. Returns this bot's upload state and confirmed parts for recovery. Only ready uploads expose a platform-controlled URL. Querying does not extend expiry; ready media remains available beyond the upload's one-hour lifetime.

MPChat SDK upload protocol. Prefer SDK sendVideo/sendDocument for automatic upload and sending.

curl -X POST "https://call.mp.net/bot/bot<bot-token>/getMediaUpload" \
  -H "Content-Type: application/json" \
  -d '{}'

uploadMediaPart Upload one media part

Used internally by the SDK. Send sequential, independent 8 MiB raw binary requests, with only the final part shorter. Compressed Content-Encoding is unsupported. Retries of a part must contain identical bytes. Concurrent operations on the same upload may return 429; the SDK retries within a bound. Authentication, ownership and chat access are checked before reading file bytes.

MPChat SDK upload protocol. Prefer SDK sendVideo/sendDocument for automatic upload and sending.

No request body fields.

curl -X POST "https://call.mp.net/bot/bot<bot-token>/uploadMediaPart" \
  -H "Content-Type: application/json" \
  -d '{}'