Your browser version is too low, some content may not display properly, please download the latest version!

Create Bot

  • Search in Potato software for @BotFather,As shown in the image below:
  • Start a chat with BotFather and send /newbot command:
  • Send the bot a nick:
  • Send the bot an username to complete registration:

Receive the message

Receiving Method

  • When a new message is sent to the bot, Potato bot server send the message to the bot user in two ways:
  • Active Mode: The Potato bot server uses https request where the method is using post and the content-type is application/json. It automatically visit the webhook address provided by the user with the message data.
  • Passive Mode: User regularly needs to request https://api.potato.im:8443/getUpdates to retrieve bot updates ( represents the bot user token value. With the chat you can search within Potato for BotCreator user to view and make changes). Upon success request, a json object containing the list of message updates will be returned. Details will be explained in later documents.

getUpdates

Request URL
  • https://api.potato.im:8443/<bot_token>/getUpdates
A brief description
  • Use this method to receive incoming updates using long polling (wiki). containing all bot related Updates.This method will not work if an outgoing webhook is set up.
Request Method
  • GET
Return parameter

An Array of Update objects is returned.

Request Parameter
Parameter Required Description
Return Example
{
    "ok": true,
    "result": [
        {
            "update_id": 1,
            "message": {
                "message_id": 57,
                "chat": {
                    "id": 11370003,
                    "type": 2,
                    "title": "group1"
                },
                "from": {
                    "id": 22800001,
                    "first_name": "David",
                    "last_name": "Smith",
                    "username": ""
                },
                "text": "123",
                "date": 1544440630
            },
            "inline_query": null
        }
    ]
}

setWebhook

Request URL
  • https://api.potato.im:8443/<bot_token>/setWebhook
A brief description
  • Use this method to specify a url and receive incoming updates via an outgoing webhook. Whenever there is an update for the bot, we will send an HTTPS POST request to the specified url, containing a JSON-serialized Update. In case of an unsuccessful request, we will give up after a reasonable amount of attempts. Returns True on success.
  • If you'd like to make sure that the Webhook request comes from Potato, we recommend using a secret path in the URL, e.g. https://www.example.com/ Since nobody else knows your bot‘s token, you can be pretty sure it’s us.
Request Method
  • POST
Request Parameter
Parameter Required Type Description
url Yes string HTTP url to send updates to
certificate no InputFile or string A digital certificate that sends an existing file on the server through the file_id string. Or upload new files, using multipart/form-data
Request Example
{
    "url": "https://127.0.0.1/web-mobile",
    "certificate": "00050000321djau921030213"
}

delWebhook

Request URL
  • https://api.potato.im:8443/<bot_token>/delWebhook
A brief description
  • Use this method to remove webhook integration if you decide to switch back to getUpdates. Returns True on success. Requires no parameters.
Request Method
  • GET

Getting Information

getMe

Request URL
  • https://api.potato.im:8443/<bot_token>/getMe
A brief description
  • A simple method for testing your bot's auth token. Requires no parameters. Returns basic information about the bot in form of a User object.
Request Method
  • GET
Return Example
{
    "id": 1000365,
    "first_name": "David",
    "last_name": "Smith",
    "username": "username"
}

getFile

Request URL
  • https://api.potato.im:8443/<bot_token>/getFile
A brief description
  • Use this method to get a URL of a file and prepare it for downloading. On success, a URL is returned. The file can then be downloaded via the link https://api.bot.potato.im/files/<bot_token>/<file_path> ;, where <file_path>is taken from the response.
Request Method
  • POST
Request Parameter
Parameter Required Type Description
file_id Yes string file unique ID
Request Example
{
    "file_id": "000001009814fcd09659fdcd80bf5224",
}
Request Parameter
Parameter Type Description
url string URL of the file
Return Example
{
    "ok": true,
    "result": {
        "url": "https://api.bot.potato.im/files/10000000:p6KKlJ7JWa64WP7lXKEj7cJ6/000001009814fcd09659fdcd80bf5224.mp3"
    }
}

Send A Message

sendTextMessage

Request URL
  • https://api.potato.im:8443/<bot_token>/sendTextMessage
A brief description
  • Use this method to send text messages. On success, the sent MessageID is returned.
Request Method
  • POST
Request Parameter
Parameter Required Type Description
chat_type Yes ChatType chat type
chat_id Yes int Unique identifier for the target chat
text Yes string Text of the message to be sent
reply_to_message_id Optional int If the message is a reply, ID of the original message
markdown Optional bool Whether to use MarkDown rendering, Entities will be generated automatically based on the text field. Refer Rich Text Support for detail
reply_markup Optional ReplyMarkup Additional interface options. A JSON-serialized object for an inline keyboard, custom reply keyboard, instructions to remove reply keyboard or to force a reply from the use
Request Example
{
  "chat_type":1,
  "chat_id":20216742,
  "text":"aaqwerwqerwqerwerqwrqwerqwerqrqwerqwerwerqa",
  "markdown" : true,
  "reply_markup":{
        "type": 4,
        "inline_keyboard": [
            {
                "buttons": [
                    {
                        "text": "Button1",
                        "callback_data": "123"
                    },
                    {
                        "text": "Button2",
                        "callback_data": "abcde"
                    }
                ]
            },
            {
                "buttons": [
                    {
                        "text": "Button3",
                        "callback_data": "22222"
                    },
                    {
                        "text": "Button4",
                         "callback_data": "333"
                    }
                ]
            }
        ]
    }
}
Request Parameter
Parameter Type Description
message_id int Indicates the unique ID of the message
Return Example
{
    "ok": true,
    "result": {
        "message_id": 27315
    }
}

forwardMessage

Request URL
  • https://api.potato.im:8443/<bot_token>/forwardMessage
A brief description
  • Use this method to forward messages of any kind. On success, the sent MessageID is returned.
Request Method
  • POST
Request Parameter
Parameter Required Type Description
chat_type Yes ChatType chat type
chat_id Yes int Unique identifier for the target chat
from_chat_type Yes ChatType source target chat type
from_chat_id Yes int Unique identifier for the chat where the original message was sent
message_id Yes int Unique ID of the message to be forwarded
Request Example
{
    "chat_type": 1,
    "chat_id": 8000012,
    "from_chat_type": 1,
    "from_chat_id": 8000042,
    "message_id": 523621234
}
Request Parameter
Parameter Type Description
message_id int Indicates the unique ID of the message
Return Example
{
    "ok": true,
    "result": {
        "message_id": 27315
    }
}

answerCallbackQuery

Request URL
  • https://api.potato.im:8443/<bot_token>/answerCallbackQuery
A brief description
  • Use this method to send answers to callback queries sent from inline keyboards. The answer will be displayed to the user as a notification at the top of the chat screen or as an alert. On success, True is returned.
Request Method
  • POST
Request Parameter
Parameter Required Type Description
inline_message_id Yes string An unique identifier for the string query callback, uploaded by the user when sending a query callback request
text Yes Optional Text of the notification. If not specified, nothing will be shown to the user, 0-200 characters
show_alert Optional bool If true, an alert will be shown by the client instead of a notification at the top of the chat screen. Defaults to false
url Optional string URL that will be opened by the user's client. If you have created a Game and accepted the conditions via @Botfather, specify the URL that opens your game – note that this will only work if the query comes from a callback_game button.
cache_time Optional int Default 0,The maximum amount of time in seconds that the result of the callback query may be cached client-side
Request Example
{
    "inline_message_id": "521521325217527362323",
    "text": "Alert",
    "show_alert": true
}
Return Example
{
    "ok": true,
    "result": null
}

sendLocation

Request URL
  • https://api.potato.im:8443/<bot_token>/sendLocation
A brief description
  • Use this method to send the user a geographic location. On success, the sent MessageID is returned.
Request Method
  • POST
Request Parameter
Parameter Required Type Description
chat_type Yes ChatType chat type
chat_id Yes int Unique identifier for the target chat
latitude Yes float Latitude of the location
longitude Yes float Longitude of the location
reply_to_message_id Optional int If the message is a reply, ID of the original message
reply_markup Optional ReplyMarkup Additional interface options. A JSON-serialized object for an inline keyboard, custom reply keyboard, instructions to remove reply keyboard or to force a reply from the use
Request Example
{
    "chat_type": 1,
    "chat_id": 8000023,
    "latitude": 212.03,
    "longitude": 54.12
}
Request Parameter
Parameter Type Description
message_id int Indicates the unique ID of the message
Return Example
{
    "ok": true,
    "result": {
        "message_id": 27315
    }
}

sendVenue

Request URL
  • https://api.potato.im:8443/<bot_token>/sendVenue
A brief description
  • Use this method to send the user a detailed address. On success, the sent MessageID is returned.
Request Method
  • POST
Request Parameter
Parameter Required Type Description
chat_type Yes ChatType chat type
chat_id Yes int Unique identifier for the target chat
latitude Yes float Latitude of the location
longitude Yes float Longitude of the location
title Yes string Name of the venue
address Yes string Address of the venue
foursquare_id Optional string Foursquare identifier of the venue
reply_to_message_id Optional int If the message is a reply, ID of the original message
reply_markup Optional ReplyMarkup Additional interface options. A JSON-serialized object for an inline keyboard, custom reply keyboard, instructions to remove reply keyboard or to force a reply from the use
Request Example
{
    "chat_type": 1,
    "chat_id": 8000023,
    "latitude": 33.6,
    "longitude": -111.9,
    "title": "Musical Instrument Museum",
    "address": "Phoenix,Arizona"
}
Request Parameter
Parameter Type Description
message_id int Indicates the unique ID of the message
Return Example
{
    "ok": true,
    "result": {
        "message_id": 27315
    }
}

sendPhoto

Request URL
  • https://api.potato.im:8443/<bot_token>/sendPhoto
A brief description
  • It is used to send image files to users. Currently, it supports sending image files below 2M and only supports JPEG/PNG/BMP/WEBP format. On success, the sent FileID adn MessageID is returned.
Request Method
  • POST
Request Parameter
Parameter Required Type Description
chat_type Yes ChatType chat type
chat_id Yes int Unique identifier for the target chat
photo Yes InputFile or string Sends a photo. Sends the existing photo on the server via the file_id string. Or upload new photos using multipart/form-data
caption Optional string Photo caption (0-200 characters)
reply_to_message_id Optional int If the message is a reply, ID of the original message
reply_markup Optional ReplyMarkup Additional interface options. A JSON-serialized object for an inline keyboard, custom reply keyboard, instructions to remove reply keyboard or to force a reply from the use
Request Example
{
    "chat_type": 1,
    "chat_id": 8000023,
    "photo": "000002209a0baffe1d5c536b619cbad4",
}
Request Parameter
Parameter Type Description
message_id int Indicates the unique ID of the message
file_id string Indicates the unique ID of the file
Return Example
{
    "ok": true,
    "result": {
        "message_id": 27315,
        "file_id": "00050000321djau921030213"
    }
}

sendDocument

Request URL
  • https://api.potato.im:8443/<bot_token>/sendDocument
A brief description
  • Use this method to send general files. On success, the sent Message is returned. Bots can currently send files of any type of up to 50 MB in size, this limit may be changed in the future.
Request Method
  • POST
Request Parameter
Parameter Required Type Description
chat_type Yes ChatType chat type
chat_id Yes int Unique identifier for the target chat
document Yes InputFile or string Sends a file document. You can send an existing file on the server via the file_id string. Or upload new files, using multipart/form-data
caption Optional string Document caption (0-200 characters)
reply_to_message_id Optional int If the message is a reply, ID of the original message
reply_markup Optional ReplyMarkup Additional interface options. A JSON-serialized object for an inline keyboard, custom reply keyboard, instructions to remove reply keyboard or to force a reply from the use
Request Example
{
    "chat_type": 1,
    "chat_id": 8000012,
    "document": "aaadeaamadf6knpuata7w2sceqpdjrpq"
}
Request Parameter
Parameter Type Description
message_id int Indicates the unique ID of the message
file_id string Indicates the unique ID of the file
Return Example
{
    "ok": true,
    "result": {
        "message_id": 27315,
        "file_id": "00050000321djau921030213"
    }
}

Edit A Message

editMessageText

Request URL
  • https://api.potato.im:8443/<bot_token>/editMessageText
A brief description
  • Use this method to edit text sent by the bot or via the bot (for inline bots). On success, True is returned.
Request Method
  • POST
Request Parameter
Parameter Required Type Description
chat_type Yes ChatType chat type
chat_id Yes int Unique identifier for the target chat
text Yes string Text of the message to be sent
message_id Yes int the unique ID of the message being edited
markdown Optional bool Whether to use MarkDown rendering, Entities will be generated automatically based on the text field. Refer Rich Text Support for detail
reply_markup Optional ReplyMarkup Additional interface options. A JSON-serialized object for an inline keyboard, custom reply keyboard, instructions to remove reply keyboard or to force a reply from the use
Request Example
{
	"chat_type":1,
	"chat_id":20000009,
	"message_id": 16,
	"text":"abcde",
	"markdown" : true,
	"reply_markup":{
        "type": 2,
        "resize_keyboard": true,
        "single_use": false,
        "selective": false,
        "keyboard": [
            {
                "buttons": [
                    {
                        "text": "new Button1"
                    },
                    {
                        "text": "new Button2"
                    }
                ]
            },
            {
                "buttons": [
                    {
                        "text": "new Button3"
                    },
                    {
                        "text": "new Button4"
                    }
                ]
            }
            ]
        }
}
Request Parameter
Parameter Type Description
ok bool Whether the operation is successful or not
Return Example
{
    "ok": true,
    "result": null
}

editMessageCaption

Request URL
  • https://api.potato.im:8443/<bot_token>/editMessageText
A brief description
  • Use this method to edit text sent by the bot or via the bot (for inline bots). On success, True is returned.
Request Method
  • POST
Request Parameter
Parameter Required Type Description
chat_type Yes ChatType chat type
chat_id Yes int Unique identifier for the target chat
message_id Yes int the unique ID of the message being edited
reply_markup Optional ReplyMarkup Additional interface options. A JSON-serialized object for an inline keyboard, custom reply keyboard, instructions to remove reply keyboard or to force a reply from the use
Request Example
{
	"chat_type":1,
	"chat_id":20000009,
	"message_id": 16,
	"text":"abcde",
	"caption" : "new text",
	"reply_markup":{
        "type": 4,
        "inline_keyboard": [
            {
                "buttons": [
                    {
                        "text": "new Button1",
                        "callback_data": "123"
                    },
                    {
                        "text": "new Button2",
                            "callback_data": ""
                    }
                ]
            },
            {
                "buttons": [
                    {
                        "text": "new Button3",
                            "callback_data": ""
                    },
                    {
                        "text": "new Button4",
                            "callback_data": ""
                    }
                ]
            }
        ]
        }
}
Request Parameter
Parameter Type Description
ok bool Whether the operation is successful or not
Return Example
{
    "ok": true,
    "result": null
}

deleteMessage

Request URL
  • https://api.potato.im:8443/<bot_token>/deleteMessage
A brief description
  • Use this method to delete a message, including service messages, with the following limitations:
  • private chats bots can only delete the message sent by itself
  • group if bots is an administrator of the group, it can delete any message there. otherwise ,can only delete the message sent by itself.If all members are administrators ,bot can only delete messages by itself
  • super group or channel if bots is an administrator of the group, it can delete any message there. otherwise ,can only delete the message sent by itself.
Request Method
  • POST
Request Parameter
Parameter Required Type Description
chat_type Yes ChatType chat type
chat_id Yes int Unique identifier for the target chat
message_id Yes int the unique ID of the message being edited
Request Example
{
    "chat_type": 1,
    "chat_id": 8000012,
    "message_id": 27315634
}
Request Parameter
Parameter Type Description
ok bool Whether the operation is successful or not
Return Example
{
    "ok": true,
    "result": null
}

Available methods

leaveChat

Request URL
  • https://api.potato.im/<bot_token>/leaveChat
A brief description
  • Use this method for your bot to leave a group, supergroup or channel. Returns True on success.
Request Method
  • POST
Request Parameter
Parameter Required Type Description
chat_type Yes ChatType chat type
chat_id Yes int Unique identifier for the target chat
Request Example
{
    "chat_type": 2,
    "chat_id": 8000012
}
Return Parameter
Parameter Type Description
ok bool Whether the operation is successful or not
Return Example
{
    "ok": true
}

getChat

Request URL
  • https://api.potato.im/<bot_token>/getChat
A brief description
  • Use this method to get up to date information about the chat (current name of the user for one-on-one conversations, current username of a user, group or channel, etc.). Returns a Chat object on success.
Request Method
  • POST
Request Parameter
Parameter Required Type Description
chat_type Yes ChatType chat type
chat_id Yes int Unique identifier for the target chat
Request Example
{
    "chat_type": 2,
    "chat_id": 8000012
}
Return Parameter
Parameter Type Description
ok bool Whether the operation is successful or not
chat Chat Returns a Chat object on success.
Return Example
{
    "ok": true,
    "result": {
        "id": 11190291,
        "type": 2,
        "title": "grpnaga"
    }
}

getChatMembersCount

Request URL
  • https://api.potato.im/<bot_token>/getChatMembersCount
A brief description
  • Use this method to get the number of members in a chat. Returns Int on success.
Request Method
  • POST
Request Parameter
Parameter Required Type Description
chat_type Yes ChatType chat type
chat_id Yes int Unique identifier for the target chat
Request Example
{
    "chat_type": 2,
    "chat_id": 8000012
}
Return Parameter
Parameter Type Description
ok int Whether the operation is successful or not
count int the number of members in a chat
Return Example
{
    "ok": true,
    "result": {
        "count": 4
    }
}

getChatAdministrators

Request URL
  • https://api.potato.im/<bot_token>/getChatAdministrators
A brief description
  • Use this method to get a list of administrators in a chat. On success, returns an Array of ChatMember objects that contains information about all chat administrators. If the chat is a group or a supergroup and no administrators were appointed, only the creator will be returned.
Request Method
  • POST
Request Parameter
Parameter Required Type Description
chat_type Yes ChatType chat type
chat_id Yes int Unique identifier for the target chat
Request Example
{
    "chat_type": 3,
    "chat_id": 8000012
}
Return Parameter
Parameter Type Description
ok int Whether the operation is successful or not
chat_member ChatMember an Array of ChatMember objects that contains information about all chat administrators
Return Example
{
    "ok": true,
    "result": [
        {
            "user": {
                "id": 20239276,
                "first_name": "ray",
                "last_name": "ray",
                "username": ""
            },
            "status": "creator"
        },
        {
            "user": {
                "id": 10100091,
                "first_name": "ABCD",
                "last_name": "",
                "username": "ABCD"
            },
            "status": "administrator",
            "can_change_info": true,
            "can_post_messages": true,
            "can_edit_messages": true,
            "can_delete_messages": true,
            "can_invite_users": true,
            "can_restrict_members": true,
            "can_pin_messages": true,
            "can_promote_members": true
        }
    ]
}

setChatTitle

Request URL
  • https://api.potato.im/<bot_token>/setChatTitle
A brief description
  • Use this method to change the title of a chat. Titles can't be changed for private chats. The bot must be an administrator in the chat for this to work and must have the appropriate admin rights. Returns True on success.
  • Note: In regular groups (non-supergroups), this method will only work if the ‘All Members Are Admins’ setting is off in the target group.
Request Method
  • POST
Request Parameter
Parameter Required Type Description
chat_type Yes ChatType chat type
chat_id Yes int Unique identifier for the target chat
title Yes string New chat title, 1-255 characters
Request Example
{
    "chat_type": 2,
    "chat_id": 8000012,
    "title": "plane"
}
Return Parameter
Parameter Type Description
ok bool Whether the operation is successful or not
Return Example
{
    "ok": true
}

setChatDescription

Request URL
  • https://api.potato.im/<bot_token>/setChatDescription
A brief description
  • Use this method to change the description of a supergroup or a channel. The bot must be an administrator in the chat for this to work and must have the appropriate admin rights. Returns True on success.
Request Method
  • POST
Request Parameter
Parameter Required Type Description
chat_type Yes ChatType chat type
chat_id Yes int Unique identifier for the target chat
description No string New chat description, 0-255 characters
Request Example
{
    "chat_type": 2,
    "chat_id": 8000012,
    "description": "plane"
}
Return Parameter
Parameter Type Description
ok bool Whether the operation is successful or not
Return Example
{
    "ok": true
}

pinChatMessage

Request URL
  • https://api.potato.im/<bot_token>/pinChatMessage
A brief description
  • Use this method to pin a message in a supergroup or a channel. The bot must be an administrator in the chat for this to work and must have the ‘can_pin_messages’ admin right in the supergroup or ‘can_edit_messages’ admin right in the channel. Returns True on success.
Request Method
  • POST
Request Parameter
Parameter Required Type Description
chat_type Yes ChatType chat type
chat_id Yes int Unique identifier for the target chat
message_id Yes int Identifier of a message to pin
disable_notification No bool Pass True, if it is not necessary to send a notification to all chat members about the new pinned message. Notifications are always disabled in channels.
Request Example
{
    "chat_type": 3,
    "chat_id": 8000012,
    "message_id": 6234,
    "disable_notification": false
}
Return Parameter
Parameter Type Description
ok bool Whether the operation is successful or not
Return Example
{
    "ok": true
}

unpinChatMessage

Request URL
  • https://api.potato.im/<bot_token>/unpinChatMessage
A brief description
  • Use this method to unpin a message in a supergroup or a channel. The bot must be an administrator in the chat for this to work and must have the ‘can_pin_messages’ admin right in the supergroup or ‘can_edit_messages’ admin right in the channel. Returns True on success.
Request Method
  • POST
Request Parameter
Parameter Required Type Description
chat_type Yes ChatType chat type
chat_id Yes int Unique identifier for the target chat
Request Example
{
    "chat_type": 3,
    "chat_id": 8000012
}
Return Parameter
Parameter Type Description
ok bool Whether the operation is successful or not
Return Example
{
    "ok": true
}

sendChatAction

Request URL
  • https://api.potato.im/<bot_token>/sendChatAction
A brief description
  • se this method when you need to tell the user that something is happening on the bot's side. The status is set for 5 seconds or less (when a message arrives from your bot, Potato clients clear its typing status). Returns True on success.
  • Example: The StickerBot needs some time to process a request and upload the image. Instead of sending a text message along the lines of “Retrieving image, please wait…”, the bot may use sendChatAction with action = upload_photo. The user will see a “sending photo” status for the bot.
  • We only recommend using this method when a response from the bot will take a noticeable amount of time to arrive.
Request Method
  • POST
Request Parameter
Parameter Required Type Description
chat_type Yes ChatType chat type
chat_id Yes int Unique identifier for the target chat
action Yes string Type of action to broadcast. Choose one, depending on what the user is about to receive: typing for text messages, upload_photo for photos, record_video or upload_video for videos, record_audio or upload_audio for audio files, upload_document for general files, find_location for location data, record_video_note or upload_video_note for video notes. All actions "typing","record_video","upload_video","record_audio","upload_audio","upload_photo","upload_document","geo_location","choose_contact","game_play","record_round","upload_round","cancel"
Request Example
{
    "chat_type": 2,
    "chat_id": 8000012,
    "action":"upload_document"
}
Return Parameter
Parameter Type Description
ok bool Whether the operation is successful or not
Return Example
{
    "ok": true
}

sendContact

Request URL
  • https://api.potato.im/<bot_token>/sendContact
A brief description
  • Use this method to send phone contacts. Returns True on success.
Request Method
  • POST
Request Parameter
Parameter Required Type Description
chat_type Yes ChatType chat type
chat_id Yes int Unique identifier for the target chat
phone_number Yes string Contact's phone number
first_name Yes string Contact's first name
last_name No string Contact's last name
disable_notification No bool Sends the message silently. Users will receive a notification with no sound.
reply_to_message_id No int If the message is a reply, ID of the original message
reply_markup No ReplyMarkup Additional interface options. A JSON-serialized object for an inline keyboard, custom reply keyboard, instructions to remove reply keyboard or to force a reply from the use
Request Example
{
    "chat_type": 2,
    "chat_id": 8000012,
    "phone_number":"10102020",
    "first_name":"James Bond"
}
Return Parameter
Parameter Type Description
ok bool Whether the operation is successful or not
Return Example
{
    "ok": true
}

Game

Description

  • Your bot can offer users HTML5 games to play solo or to compete against each other in groups and one-on-one chats. Create games via @BotFather using the /newgame command. Please note that this kind of power requires responsibility: you will need to accept the terms for each game that your bots will be offering.

  • Games are a new type of content on Potato, represented by the Game and InlineQueryResultGame objects.

  • Once you've created a game via BotFather, you can send games to chats as regular messages using the sendGame method, or use inline mode with InlineQueryResultGame.

  • If you send the game message without any buttons, it will automatically have a 'Play GameName' button. When this button is pressed, your bot gets a CallbackQuery with the game_short_name of the requested game. You provide the correct URL for this particular user and the app opens the game in the in-app browser.

  • You can manually add multiple buttons to your game message. Please note that the first button in the first row must always launch the game, using the field callback_game in InlineKeyboardButton. You can add extra buttons according to taste: e.g., for a description of the rules, or to open the game's official community.

  • To make your game more attractive, you can upload a GIF animation that demostrates the game to the users via BotFather (see 2048 for example).

  • A game message will also display high scores for the current chat. Use setGameScore to post high scores to the chat with the game, add the edit_message parameter to automatically update the message with the current scoreboard.

  • Use getGameHighScores to get data for in-game high score tables.

  • You can also add an extra sharing button for users to share their best score to different chats.

  • For examples of what can be done using this new stuff, check the @gamebot.

sendGame

Request URL
  • https://api.potato.im:8443/<bot_token>/sendGame
A brief description
  • Use this method to send a game. On success, the sent MessageID is returned.
Request Method
  • POST
Request Parameter
Parameter Required Type Description
chat_type Yes ChatType chat type
chat_id Yes int Unique identifier for the target chat
game_short_name Yes string Short name of the game, serves as the unique identifier for the game. Set up your games via Botfather.
reply_to_message_id Optional int If the message is a reply, ID of the original message
disable_notification Optional bool WSends the message silently. Users will receive a notification with no sound.
reply_markup Optional InlineKeyboardMarkup AA JSON-serialized object for an inline keyboard. If empty, one ‘Play game_title’ button will be shown. If not empty, the first button must launch the game.
Request Example

{
"chat_type":1,
"chat_id":22800001,
"game_short_name":"2048"
}

Return Parameter
Parameter Type Description
message_id int Indicates the unique ID of the message
Return Example
{
    "ok": true,
    "result": {
        "message_id": 27315
    }
}

setGameScore

Request URL
  • https://api.potato.im:8443/<bot_token>/setGameScore
A brief description
  • Use this method to set the score of the specified user in a game. On success, if the message was sent by the bot, returns the edited Message, otherwise returns True. Returns an error, if the new score is not greater than the user's current score in the chat and force is False.
Request Method
  • POST
Request Parameter
Parameter Required Type Description
chat_type Yes ChatType chat type
chat_id Yes int Unique identifier for the target chat
user_id Yes int Unique identifier of the user
score Yes int New score, must be non-negative
message_id Yes int Identifier of the sent game message
force Optional bool Pass True, if the high score is allowed to decrease. This can be useful when fixing mistakes or banning cheaters
Request Example
{
	"message_id":204,
	"user_id":22800001,
	"chat_type":1,
	"chat_id":22800001,
	"bot_id":10006000,
	"score":70
}
Return Parameter
Parameter Type Description
message_id int Indicates the unique ID of the message
Return Example
{
    "ok": true,
    "result": {
        "message_id": 27315
    }
}

getGameHighScores

Request URL
  • https://api.potato.im:8443/<bot_token>/getGameHighScores
A brief description
  • Use this method to get data for high score tables. Will return the score of the specified user and several of his neighbors in a game. On success, returns an Array of GameHighScore objects.
Request Method
  • POST
Request Parameter
Parameter Required Type Description
chat_type Yes ChatType chat type
chat_id Yes int Unique identifier for the target chat
user_id Yes int Unique identifier of the user
message_id Yes int Identifier of the sent game message.You can get it from CallbackQuery from the server when you click play button
Request Example
{
	"message_id":204,
	"user_id":22800001,
	"chat_type":3,
	"chat_id":10856320,
	"bot_id":10060216,
	"score":70
}
Return Parameter
Parameter Type Description
message_id int Indicates the unique ID of the message
Return Example
{
    "ok": true,
    "result": {
        "message_id": 27315
    }
}

Inline mode

  • The following methods and objects allow your bot to work in inline mode.

  • Please see our Introduction to Inline bots for more details.

  • To enable this option, send the /setinline command to @BotFather and provide the placeholder text that the user will see in the input field after typing your bot’s name.

InlineQuery

A brief description
  • This object represents an incoming inline query. When the user sends an empty query, your bot could return some default or trending results.
Field Type Description
id String Unique identifier for this query
from User Sender
location Location Optional. Sender location, only for bots that request user location
query String Text of the query (up to 512 characters)
offset String Offset of the results to be returned, can be controlled by the bot

answerInlineQuery

Request URL
  • https://api.potato.im:8443/<bot_token>/answerInlineQuery
A brief description
  • Use this method to send answers to an inline query. On success, True is returned.
    No more than 50 results per query are allowed.
Request Method
  • POST
Request Parameter
Parameter Required Type Description
inline_query_id Yes String Unique identifier for the answered query
results Yes Array of InlineQueryResult A JSON-serialized array of results for the inline query
is_personal Optional Boolean Pass True, if results may be cached on the server side only for the user that sent the query. By default, results may be returned to any user who sends the same query
next_offset Optional String Pass the offset that a client should send in the next query with the same text to receive more results. Pass an empty string if there are no more results or if you don‘t support pagination. Offset length can’t exceed 64 bytes.
switch_pm_text Optional String If passed, clients will display a button with specified text that switches the user to a private chat with the bot and sends the bot a start message with the parameter switch_pm_parameter
switch_pm_parameter Optional String parameter for the /start message sent to the bot when user presses the switch button. 1-64 characters, only A-Z, a-z, 0-9, _ and - are allowed.

InlineQueryResult

A brief description

This object represents one result of an inline query. Potato clients currently support results of the following 4 types:

InlineQueryResultArticle

A brief description
  • Represents a link to an article or web page.
Field Type Description
type String Type of the result, must be article
id String Unique identifier for this result, 1-64 Bytes
title String Title of the result
input_message_content InputMessageContent Content of the message to be sent
reply_markup InlineKeyboardMarkup Optional. Inline keyboard attached to the message
url String Optional. URL of the result
hide_url Boolean Optional. Pass True, if you don't want the URL to be shown in the message
description String Optional. Short description of the result
thumb_url String Optional. Url of the thumbnail for the result
thumb_width int Optional. Thumbnail width
thumb_height int Optional. Thumbnail height

InlineQueryResultGame

A brief description
  • Your bot can offer users HTML5 games to play solo or to compete against each other in groups and one-on-one chats.
Field Type Description
type String Type of the result, must be article
id String Unique identifier for this result, 1-64 Bytes
game_short_name String Unique identifier of the user
reply_markup ReplyMarkup Additional interface options. A JSON-serialized object for an inline keyboard, custom reply keyboard, instructions to remove reply keyboard or to force a reply from the use

InlineQueryResultGif

A brief description
  • Represents a link to an animated GIF file. By default, this animated GIF file will be sent by the user with optional caption. Alternatively, you can use input_message_content to send a message with the specified content instead of the animation.
Field Type Description
type String Type of the result, must be gif
id String Unique identifier for this result, 1-64 bytes
gif_url String A valid URL for the GIF file. File size must not exceed 1MB
gif_width int Optional. Width of the GIF
gif_height int UnOptional. Height of the GIF
gif_duration int Optional. Duration of the GIF
thumb_url String URL of the static thumbnail for the result (jpeg or gif)
title String Optional. Title for the result
caption String Optional. Caption of the GIF file to be sent, 0-1024 characters
parse_mode String Optional. Send Markdown, if you want Potato apps to show bold, italic, fixed-width text or inline URLs in the media caption.
reply_markup InlineKeyboardMarkup Optional. inline keyboard attached to the message
input_message_content InputMessageContent Optional. Content of the message to be sent instead of the GIF animation

InlineQueryResultPhoto

A brief description
  • Represents a link to a photo. By default, this photo will be sent by the user with optional caption. Alternatively, you can use input_message_content to send a message with the specified content instead of the photo.
Field Type Description
type String Type of the result, must be photo
id String Unique identifier for this result, 1-64 bytes
photo_url String A valid URL of the photo. Photo must be in jpeg format. Photo size must not exceed 5MB
thumb_url String URL of the thumbnail for the photo
photo_width int Optional. Width of the photo
photo_height int Optional. Height of the photo
title String Optional. Title for the result
description String Optional. Short description of the result
caption String Optional. Caption of the photo to be sent, 0-1024 characters
parse_mode String Optional. Send Markdown, if you want Potato apps to show bold, italic, fixed-width text or inline URLs in the media caption.
reply_markup InlineKeyboardMarkup Optional. inline keyboard attached to the message
input_message_content InputMessageContent Optional. Content of the message to be sent instead of the photo

InputMessageContent

A brief description

This object represents the content of a message to be sent as a result of an inline query. Potato clients currently support the following 1 types:

InputTextMessageContent

A brief description
  • Represents the content of a text message to be sent as the result of an inline query.
Field Type Description
message_text String TypText of the message to be sent, 1-4096 characters

Object Type

Chat Type

  • Used to define the type of chat dialog box, the following is the type of Chat object can be used.
Field Type Description
message_text String TypText of the message to be sent, 1-4096 characters
Value Enumeration value Description
1 PeerUser user chat
2 PeerChat standard group chat
3 ChannelChat super group chat

Entity Type

  • Entity use to define rich text objects chat content, the following are the different type that can be used in the Entity object.
Value Enumeration value Description
1 EntityBold Bold
2 EntityItalic Italic
3 EntityCode Code highlighting
4 EntityURL Hyperlink
5 EntityTextURL Text link
6 EntityMention Mentioned
7 EntityMentionName Mention the name
8 EntityEMail Code highlighting
9 EntityBotCommand Bot command

ReplyMarkup Type

  • The following is a list of the type of enumeration that can be used when customizing the reply message ReplyMarkup.
Value Enumeration value Description
1 ForceReplyType Display of the reply screen so that the user has manually select the rbot message to click the "reply" button
2 ReplyKeyboardMarkupType Replies to custom keyboard
3 ReplyKeyboardRemoveType Indicates that the current custom keyboard is removed
4 InlineKeyboardMarkupType That line custom keyboard, displayed in the chat content

User

  • User is use to describe user information.
Parameter Required Type Description
id Yes int the user's unique ID
first_name Optional string the user's First name
last_name Optional string the user's Last name
username Yes string the user name
Sample code
{
    "id": 1000,
    "first_name": "David",
    "last_name": "Smith",
    "username": "username"
}

Chat

  • User is use to describe user information.
Parameter Required Type Description
id Yes int the user's unique ID
type Yes ChatType Chat Type
title Optional string The title of the dialog takes effect only if the type field is 2 (PeerChat) or 3 (ChannelChat
invite_link Optional string Invite link, only when the type field is 3 (ChannelChat) will take effect
Sample code
{
    "id": 1000,
    "type": 3,
    "title": "super group",
}

Entity

  • Entity used to define rich text objects in chat content, there are currently nine types available, the specific reference Entity type.
Field Type Required Comments
type EntityType yes Entity type
user_id integer no Required when type 7 (EntityMentionName) indicates the target user ID of @e
offset integer yes the starting offset position of the link, in bytes, of which Chinese characters and English letters count one byte, emoj count two bytes
length integer yes the length of the link, in bytes
url string no type 5 (EntityTextUrl) Mandatory, indicating the URL of the link

Button

KeyboardButtonRow

  • Used to describe custom buttons on the user's keyboard. Only one field can be filled in, otherwise only the first one will take effect.
Field Type Required Comments
text string yes the label text displayed on the button
request_contact boolean no Default false, whether to click and send your own business card
request_location boolean no Default false, whether to click and send their own geographic location

KeyboardButtonRow

  • A row of custom buttons describing the user's keyboard.
Field Type Required Comments
buttons array of KeyboardButton yes a row of custom buttons

InlineKeyboardButton

  • User Description Inline keyboard, that is, a custom keyboard in the chat content, optional fields can only be filled in, otherwise only the first one will take effect.
Field Type Required Comments
text string yes label text displayed on the button
url string no Default null, HTTP url
callback_data string no default null, callback send data
switch_inline_query string no Default null, toggles inline query data. Ask the user to select a dialog, then @ robot and send this data
switch_inline_query_current_chat string no default null, toggles the inline query data. In the current dialog @ robot and send this data

InlineKeyboardButtonRow

  • A row of custom buttons for describing chat content.
Field Type Required Comments
buttons array of InlineKeyboardButton yes a row of inline buttons

ReplyMarkup

  • There are 4 types of ReplyMarkup: ForceReplyType, ReplyKeyboardMarkupType, ReplyKeyboardRemoveType and InlineKeyboardMarkup. Each have different functions (please refer to the ReplyMarkup Types tables below)

ForceReply

  • Used to depict the reply interface, achieving the same effect of selecting the chat bot and then selecting "Reply".
Field Type Required Comments
type ReplyMarkupType yes This value needs to be 2(ReplyKeyboardMarkupType), indicates reply keyboard
keyboard array of KeyboardButtonRow yes Custom keyboard, referencing "Button" object "KeyboardButtonRow"
resize_keyboard boolean no "False" by default, adaptive keyboard height
single_use boolean no "False" by default, hide custom keyboard after use
selective boolean no "False" by default, indicates that it can only be seen by specific users: 1. Users mentioned in the message. 2. If the previous message is a reply, only the original sender can view the message.

ReplyKeyboardMarkup

  • Used to depict replying to (with?) custom keyboard.
Field Type Required Comments
type ReplyMarkupType yes This value needs to be 2(ReplyKeyboardMarkupType), indicates reply keyboard
keyboard array of KeyboardButtonRow yes Custom keyboard, referencing "Button" object "KeyboardButtonRow"
resize_keyboard boolean no "False" by default, adaptive keyboard height
single_use boolean no "False" by default, hide custom keyboard after use
selective boolean no "False" by default, indicates that it can only be seen by specific users: 1. Users mentioned in the message. 2. If the previous message is a reply, only the original sender can view the message.

ReplyKeyboardRemove

  • Used to depict the deletion/clearing of custom keyboard. When a message with an object is received, the Potato client will delete the previous custom keyboard and display the default keyboard, until the chatbot sends a new keyboard.
Field Type Required Comments
type ReplyMarkupType yes This value needs to be set as 3(ReplyKeyboardRemoveType), which will delete the custom keyboard
selective boolean no False by default, indicates that it can only be seen by specific users: 1. Users mentioned in the message. 2. If the previous message is a reply, only the original sender can view the message.

InlineKeyboardMarkup

  • Used to depict the inline keyboard displayed in the chat message.
Field Type Required Comments
type ReplyMarkupType yes This value needs to be set as 3(ReplyKeyboardRemoveType), which will delete the custom keyboard
selective boolean no False by default, indicates that it can only be seen by specific users: 1. Users mentioned in the message. 2. If the previous message is a reply, only the original sender can view the message.

Location

Field Type Required Comments
longitude number yes longitude
latitude number yes latitude

Venue

Field Type Required Comments
longitude number yes longitude
latitude number yes latitude
title string yes title
address string yes address
foursquare_id string no Foursquare Identifier

PhotoSize

Field Type Required Comments
file_id string yes File unique ID
width integer yes photo width
height integer yes photo height
file_size integer no photo size

Audio

Field Type Required Comments
file_id string yes File unique ID
duration integer yes Playing time
performer string no Author
title string no title
mime_type string no file mime_type
file_size integer no file size

Document

Field Type Required Comments
file_id string yes File unique ID
thumb PhotoSize no File thumbnail
file_name string no file name
mime_type string no file mime type
file_size integer no file size

Video

Field Type Required Comments
file_id string yes File unique ID
width integer yes Video width
height integer yes Video height
duration integer yes playing time
thumb PhotoSize no Video thumbnail
mime_type string no File MIME type
file_size integer no file size

Voice

Field Type Required Comments
file_id string yes File unique ID
duration integer yes Playing time
mime_type string no File MIME type
file_size integer no file size

Contact

Field Type Required Comments
phone_number string yes Contact phone number
first_name string yes Contact first name
last_name string no Contact last name
user_id integer no Contact user id

MessageAction

Field Type Required Comments
new_group_members array of User no Join the group
left_group_member User no Leave the group
new_group_title string no Modify the group name
migrate_from_chat_id integer no Upgrade from a normal group to a super group with the unique ID of the normal group
migrate_to_chat_id integer no Upgrade from a normal group to a super group with a unique ID of the super group

CallbackQuery

Field Type Required Comments
inline_message_id string yes The unique identifier for this query, which is needed to answer this query (in fact yes, the client and server agreed message ID)
message_id integer yes The message id that triggered this query
chat Chat yes Message conversation information
from User yes Message sender information
data string yes Query data
date integer yes Unix time stamp of the message

Message

Field Type Required Comments
message_id integer yes A unique ID for the message
chat Chat yes Message conversation information
from User yes Message sender information
forward_from User no The sender of the original message
forward_date integer no Message forwarding Unix timestamp
text string no Message text
entities array of Entity no An array of Entity objects describing the rich text information
reply_to_message Message no Reply to the original message
date integer yes Unix time stamp of the message
edit_date integer no Unix timestamp of last edited message
location Location no Address location
venue Venue no Address
photo array of PhotoSize no Photo file
audio Audio no Audio file
document Document no Document file
video Video no Video file
voice Voice no Recording files
contact Contact no Contact
caption string no Document / Picture / Video / Audio title
action MessageAction no Message action

Update

Field Type Required Comments
update_id integer yes Update ID
message Message no Messages (including text, media and forwarding messages)
edited_message Message no Edit the message
callback_query CallbackQuery no Callback inquiry

Rich Text Support

Introduction to formatting

  • Using similar MarkDown languages, you can easily generate entities object list according to the Potato message

Italics

  • Enter the text to be defined with italics between 1 asterisk "*" or underscore "_":

*this is italics* _this is italics_

Bold

  • Enter the text to be defined with bold between 2 asterisks "*" or underscores "_":

**This is bold font** __This is also bold font__

Italics and Bold

  • Enter the text to be defined with bold and italics between 3 asterisks "*" or underscores "_":

***italics and bold*** ___italics and bold___

Code Marking

  • In order to mark a small line of code, you can highlight the code between back quotation marks, for example:

`printf("Hello World!");`

  • Enter text links to be defined between the <> brackets:

<https://www.google.com/>

  • Enter email address to be defined between the <> brackets:

<username@mail.com>

  • Insert website URL in brackets behind the square brackets:

[https://www.google.com/](https://www.google.com/) [Tap here to open Google website](https://www.google.com/)

Chatbot Commands

  • Insert string "cmd" in brackets behind the square brackets:

[/new_bot](cmd)

Mentions

  • Insert string "@" in brackets behind the square brackets:

[@username](@)

Mentioned Users

  • Insert string "mention_name" in brackets behind the square brackets, then insert user_id or @user_id behind:

[@username](@100500)


Error Code

Code Type
1001 internal server error
1002 invalid token
1003 unknown Command
1004 wrong parameters
1005 wrong format data
1006 no permission
1007 frequency of apis sent exceeded limit
1008 cannot send message to target user
1009 uploaded file size too large
1010 illegal characters in message
1011 entities" exceeds length limit
1012 reply markup" exceeds length limit
1013 file not exists
1014 request body too long
1015 robots are not in groups
1016 the group does not exist
3002 have been in black list
3003 does not found user info
3004 permission Denied
3005 the group does not exist or already upgrade to a super group
3006 user is not in the group
3007 object type error
3008 frequently message
3009 Repeated message
3010 can not get group participant
3011 check media message error
3012 message not found
3013 get forward message list failed
3014 message too long
3015 message storage failed