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.

Authorizing your bot

Each bot is given a unique authentication token when it is created. The token looks something like 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11, but we'll use simply <token> in this document instead. You can learn about obtaining tokens and generating new ones in Create Bot.

All queries to the Potato Bot API must be served over HTTPS and need to be presented in this form:
https://api.sydney.im:8443/<bot_token>/METHOD_NAME.
Like this for example:
https://api.sydney.im:8443/123456909:ABC-DEF1234ghIkl-zyx57W2v1u123ew11/getMe

We support GET and POST HTTP methods. We support four ways of passing parameters in Bot API requests:

  • URL query string
  • Application/json (except for uploading files)
  • Multipart/form-data (use to upload files)

The response contains a JSON object, which always has a Boolean field 'ok' and may have an optional String field 'description' with a human-readable description of the result. If 'ok' equals true, the request was successful and the result of the query can be found in the 'result' field. In case of an unsuccessful request, 'ok' equals false and the error is explained in the 'description'. An Integer 'error_code' field is also returned, but its contents are subject to change in the future. Some errors may also have an optional field 'parameters' of the type ResponseParameters, which can help to automatically handle the error.

  • All methods in the Bot API are case-sensitive.
  • All queries must be made using UTF-8.

Bots how to receive message

  • 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.sydney.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.

Making requests when getting updates

If you're using webhooks, you can perform a request to the Bot API while sending an answer to the webhook. Use either application/json or application/x-www-form-urlencoded or multipart/form-data response content type for passing parameters. Specify the method to be invoked in the method parameter of the request. It's not possible to know that such a request was successful or get its result.

Getting updates

Here are two mutually exclusive ways of receiving updates for your bot — the getUpdates method on one hand and Webhooks on the other. Incoming updates are stored on the server until the bot receives them either way, but they will not be kept longer than 24 hours.

Regardless of which option you choose, you will receive JSON-serialized Update objects as a result.

Update

This object represents an incoming update.
At most one of the optional parameters can be present in any given update.

Parameter Type Description
update_id Integer The update's unique identifier. Update identifiers start from a certain positive number and increase sequentially. This ID becomes especially handy if you're using Webhooks, since it allows you to ignore repeated updates or to restore the correct update sequence, should they get out of order. If there are no new updates for at least a week, then identifier of the next update will be chosen randomly instead of sequentially.
message Message Optional. New incoming message of any kind — text, photo, sticker, etc.
edited_message Message OPtional. a message that is known to the bot and was edited.
inline_query InlineQuery Optional. New incoming inline query.
callback_query CallbackQuery Optional. New incoming callback query.
lang String Message source client language type, e.g. 'en' in English or 'zh' in Chinese.
os_type String Message source client type, e.g. 'pc'.

getUpdates

Request URL

  • https://api.sydney.im:8443/<bot_token>/getUpdates

Request Method

  • GET

A brief description

  • Use this method to receive incoming updates using long polling(wiki). An Array of Update objects is returned.
Return parameter

An Array of Update objects is returned.

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,
            "lang": "en"
        }
    ]
}

Notes

  • This method will not work if an outgoing webhook is set up.

setWebhook

Request URL

  • https://api.sydney.im:8443/<bot_token>/setWebhook

Request Method

  • POST

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/<bot_token> Since nobody else knows your bot‘s token, you can be pretty sure it's us.
Request Parameter
Parameter Required Type Description
url Yes String HTTP url to send updates to
certificate Optional 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"
}

Notes

  1. You will not be able to receive updates using getUpdates for as long as an outgoing webhook is set up.
  2. To use a self-signed certificate, you need to upload your public key certificate using certificate parameter. Please upload as InputFile, sending a String will not work.

delWebhook

Request URL

  • https://api.sydney.im:8443/<bot_token>/delWebhook

Request Method

  • GET

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.

Getting Information

getMe

Request URL

  • https://api.sydney.im:8443/<bot_token>/getMe

Request Method

  • GET

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.
Return Example
{
    "ok": true,
    "result": {
        "id": 10100427,
        "first_name": "ll_bot",
        "last_name": "",
        "username": "ll_bot"
    }
}
Return Parameter
Parameter Description
id The bot's unique identifier. bot identifiers start from a certain positive number and increase sequentially.
first_name The bot's first name
last_name Always be null. Ignore this parameter for Potato bot user.
username The bot's username

getFile

Request URL

  • https://api.sydney.im:8443/<bot_token>/getFile

Request Method

  • POST

A brief description

  • Use this method to get basic info about a file and prepare it for downloading. For the moment, bots can download files of up to 100MB in size. On success, a File object is returned. The file can then be downloaded via the link https://api.sydney.im:8443/<bot_token>/<file_path>.
Request Parameter
Parameter Required Type Description
file_id Yes String File identifier to get info about
Request Example
{
    "file_id": "000001009814fcd09659fdcd80bf5224"
}
Return Parameter
Parameter Type Description
url String URL of the file
Return Example
{
    "ok": true,
    "result": {
        "url": "https://api.sydney.im:8443/files/10000000:p6KKlJ7JWa6XKEj7cJ6/0000fcd09659fdcd80bf5224.mp3"
    }
}

Send A Message

sendTextMessage

Request URL

  • https://api.sydney.im:8443/<bot_token>/sendTextMessage

Request Method

  • POST

A brief description

  • Use this method to send text messages. On success, the sent MessageID is returned.
Request Parameter
Parameter Required Type Description
chat_type Yes ChatType Type for the target chat
chat_id Yes Integer Unique identifier for the target chat
text Yes String Text of the message to be sent
reply_to_message_id Optional Integer If the message is a reply, ID of the original message
markdown Optional Boolean 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"
                    }
                ]
            }
        ]
    }
}
Return Parameter
Parameter Type Description
message_id Integer Indicates the unique ID of the message
Return Example
{
    "ok": true,
    "result": {
        "message_id": 27315
    }
}

Formatting options

  • The Bot API supports basic formatting for messages. You can use bold and italic text, as well as inline links and pre-formatted code in your bots' messages. Potato clients will render them accordingly. You can use either markdown-style.
  • Note that Potato clients will display an alert to the user before opening an inline link ('Open this link?' together with the full URL).
  • go to Rich Text for detail of markdown.

forwardMessage

Request URL

  • https://api.sydney.im:8443/<bot_token>/forwardMessage

Request Method

  • POST

A brief description

  • Use this method to forward messages of any kind. On success, the sent MessageID is returned.
Request Parameter
Parameter Required Type Description
chat_type Yes ChatType Type for the target chat
chat_id Yes Integer Unique identifier for the target chat
from_chat_type Yes ChatType Source target chat type
from_chat_id Yes Integer Unique identifier for the chat where the original message was sent
message_id Yes Integer 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
}
Return 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.sydney.im:8443/<bot_token>/answerCallbackQuery

Request Method

  • POST

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.
  • Alternatively, the user can be redirected to the specified Game URL. For this option to work, you must first create a game for your bot via @Botfather and accept the terms. Otherwise, you may use links like pt.im/your_bot?start=XXXX that open your bot with a parameter.
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 String Text of the notification. If not specified, nothing will be shown to the user, 0-200 characters
show_alert Optional Boolean 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 Integer 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.sydney.im:8443/<bot_token>/sendLocation

Request Method

  • POST

A brief description

  • Use this method to send the user a geographic location. On success, the sent MessageID is returned.
Request Parameter
Parameter Required Type Description
chat_type Yes ChatType Type for the target chat
chat_id Yes Integer 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 Integer 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
}
Return Parameter
Parameter Type Description
message_id Integer Indicates the unique ID of the message
Return Example
{
    "ok": true,
    "result": {
        "message_id": 27315
    }
}

sendVenue

Request URL

  • https://api.sydney.im:8443/<bot_token>/sendVenue

Request Method

  • POST

A brief description

  • Use this method to send the user a detailed address. On success, the sent MessageID is returned.
Request Parameter
Parameter Required Type Description
chat_type Yes ChatType Type for the target chat
chat_id Yes Integer 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 Integer 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"
}
Return Parameter
Parameter Type Description
message_id Integer Indicates the unique ID of the message
Return Example
{
    "ok": true,
    "result": {
        "message_id": 27315
    }
}

sendPhoto

Request URL

  • https://api.sydney.im:8443/<bot_token>/sendPhoto

Request Method

  • POST

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 and MessageID is returned.
Request Parameter
Parameter Required Type Description
chat_type Yes ChatType Type for the target chat
chat_id Yes Integer 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 Integer 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,
    "photo": "00000220aa47fca4bf5dfd5b49d552b9"
}
Return Parameter
Parameter Type Description
message_id Integer 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.sydney.im:8443/<bot_token>/sendDocument

Request Method

  • POST

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 Parameter
Parameter Required Type Description
chat_type Yes ChatType Type for the target chat
chat_id Yes Integer 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 Integer 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"
}
Return Parameter
Parameter Type Description
message_id Integer 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"
    }
}

sendVideo

Request URL

  • https://api.sydney.im:8443/<bot_token>/sendVideo

Request Method

  • POST

A brief description

  • Use this method to send video files, Potato clients support MP4 videos (other formats may be sent as Document). 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 Parameter
Parameter Required Type Description
chat_type Yes ChatType Type for the target chat
chat_id Yes Integer Unique identifier for the target chat
video Yes InputFile or String Sends a video . You can send an existing file on the server via the file_id String. Or upload new files, using multipart/form-data
duration Optional Integer Duration of sent video in seconds
thumb Optional InputFile or String Thumbnail of the file sent; can be ignored if thumbnail generation for the file is supported server-side. The thumbnail should be less than 3MB in size.
width Optional Integer Video width
height Optional Integer Video height
caption Optional String Video caption (0-200 characters)
reply_to_message_id Optional Integer 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,
    "video": "000002229ad7056e1e5ddc6018da56dc"
}
Return Parameter
Parameter Type Description
message_id Integer 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": "000002229ad7056e1e5ddc6018da56dc"
    }
}

Edit A Message

editMessageText

Request URL

  • https://api.sydney.im:8443/<bot_token>/editMessageText

Request Method

  • POST

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 Parameter
Parameter Required Type Description
chat_type Yes ChatType Type for the target chat
chat_id Yes Integer Unique identifier for the target chat
text Yes String Text of the message to be sent
message_id Yes Integer The unique ID of the message being edited
markdown Optional Boolean 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"
                    }
                ]
            }
            ]
        }
}
Return Parameter
Parameter Type Description
ok Boolean Whether the operation is successful or not
Return Example
{
    "ok": true,
    "result": null
}

editMessageCaption

Request URL

  • https://api.sydney.im:8443/<bot_token>/editMessageCaption

Request Method

  • POST

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 Parameter
Parameter Required Type Description
chat_type Yes ChatType Type for the target chat
chat_id Yes Integer Unique identifier for the target chat
message_id Yes Integer 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": ""
                    }
                ]
            }
        ]
        }
}
Return Parameter
Parameter Type Description
ok Boolean Whether the operation is successful or not
Return Example
{
    "ok": true,
    "result": null
}

deleteMessage

Request URL

  • https://api.sydney.im:8443/<bot_token>/deleteMessage
Request Method
  • POST

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 Parameter
Parameter Required Type Description
chat_type Yes ChatType Type for the target chat
chat_id Yes Integer Unique identifier for the target chat
message_id Yes Integer the unique ID of the message being edited
Request Example
{
    "chat_type": 1,
    "chat_id": 8000012,
    "message_id": 27315634
}
Return Parameter
Parameter Type Description
ok Boolean Whether the operation is successful or not
Return Example
{
    "ok": true,
    "result": null
}

Available methods

leaveChat

Request URL

  • https://api.sydney.im:8443/<bot_token>/leaveChat

Request Method

  • POST

A brief description

  • Use this method for your bot to leave a group, supergroup or channel. Returns True on success.
Request Parameter
Parameter Required Type Description
chat_type Yes ChatType Type for the target chat
chat_id Yes Integer Unique identifier for the target chat
Request Example
{
    "chat_type": 2,
    "chat_id": 8000012
}
Return Parameter
Parameter Type Description
ok Boolean Whether the operation is successful or not
Return Example
{
    "ok": true
}

getChat

Request URL

  • https://api.sydney.im:8443/<bot_token>/getChat

Request Method

  • POST

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 Parameter
Parameter Required Type Description
chat_type Yes ChatType Type for the target chat
chat_id Yes Integer Unique identifier for the target chat
Request Example
{
    "chat_type": 2,
    "chat_id": 8000012
}
Return Parameter
Parameter Type Description
ok Boolean 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.sydney.im:8443/<bot_token>/getChatMembersCount

Request Method

  • POST

A brief description

  • Use this method to get the number of members in a chat. Returns Int on success.
Request Parameter
Parameter Required Type Description
chat_type Yes ChatType Type for the target chat
chat_id Yes Integer Unique identifier for the target chat
Request Example
{
    "chat_type": 2,
    "chat_id": 8000012
}
Return Parameter
Parameter Type Description
ok Integer Whether the operation is successful or not
count Integer The number of members in a chat
Return Example
{
    "ok": true,
    "result": {
        "count": 4
    }
}

getChatAdministrators

Request URL

  • https://api.sydney.im:8443/<bot_token>/getChatAdministrators

Request Method

  • POST

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 Parameter
Parameter Required Type Description
chat_type Yes ChatType Type for the target chat
chat_id Yes Integer Unique identifier for the target chat
Request Example
{
    "chat_type": 3,
    "chat_id": 8000012
}
Return Parameter
Parameter Type Description
ok Integer 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.sydney.im:8443/<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 Type for the target chat
chat_id Yes Integer 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 Boolean Whether the operation is successful or not
Return Example
{
    "ok": true
}

setChatDescription

Request URL

  • https://api.sydney.im:8443/<bot_token>/setChatDescription

Request Method

  • POST

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 Parameter
Parameter Required Type Description
chat_type Yes ChatType Type for the target chat
chat_id Yes Integer Unique identifier for the target chat
description Yes String New chat description, 0-255 characters
Request Example
{
    "chat_type": 2,
    "chat_id": 8000012,
    "description": "plane"
}
Return Parameter
Parameter Type Description
ok Boolean Whether the operation is successful or not
Return Example
{
    "ok": true
}

setJoinGroups

Request URL

  • https://api.sydney.im:8443/<bot_token>/setJoinGroups

Request Method

  • POST

A brief description

  • Use this method to set the personal robot is allowed to be added to the group.
Request Parameter
Parameter Required Type Description
enable Yes Boolean True, the bot can be added to groups, else can not
Request Example
{
	"enable":true
}
Return Parameter
Parameter Type Description
ok Boolean Whether the operation is successful or not
Return Example
{
    "ok": true
}

pinChatMessage

Request URL

  • https://api.sydney.im:8443/<bot_token>/pinChatMessage
Request Method
  • POST

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 Parameter
Parameter Required Type Description
chat_type Yes ChatType Type for the target chat
chat_id Yes Integer Unique identifier for the target chat
message_id Yes Integer Identifier of a message to pin
disable_notification No Boolean 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 Boolean Whether the operation is successful or not
Return Example
{
    "ok": true
}

unpinChatMessage

Request URL

  • https://api.sydney.im:8443/<bot_token>/unpinChatMessage
Request Method
  • POST

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 Parameter
Parameter Required Type Description
chat_type Yes ChatType Type for the target chat
chat_id Yes Integer Unique identifier for the target chat
Request Example
{
    "chat_type": 3,
    "chat_id": 8000012
}
Return Parameter
Parameter Type Description
ok Boolean Whether the operation is successful or not
Return Example
{
    "ok": true
}

kickChatMember

Request URL

  • https://api.sydney.im:8443/<bot_token>/kickChatMember
Request Method
  • POST

A brief description

  • Use this method to kick a user from a group, a supergroup or a channel. In the case of supergroups and channels, the user will not be able to return to the group on their own using invite links, etc., unless unbanned first. The bot must be an administrator in the chat for this to work and must have the appropriate admin rights. Returns True on success.
  • In regular groups (non-supergroups), this method will only work if the ‘All Members Are Admins’ setting is off in the target group. Otherwise members may only be removed by the group's creator or by the member that added them.
Request Parameter
Parameter Required Type Description
chat_type Yes ChatType Type for the target chat
chat_id Yes Integer Unique identifier for the target chat
user_id Yes Integer Unique identifier for the target user
Request Example
{
    "chat_type": 3,
    "chat_id": 8000012,
    "user_id": 80000001
}
Return Parameter
Parameter Type Description
ok Boolean Whether the operation is successful or not
Return Example
{
    "ok": true
}

kickNotBan

Request URL

  • https://api.sydney.im:8443/<bot_token>/kickNotBan
Request Method
  • POST

A brief description

  • Use this method to kick a user from a group, a supergroup or a channel but will be able to join via link, etc. 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 Parameter
Parameter Required Type Description
chat_type Yes ChatType Type for the target chat
chat_id Yes Integer Unique identifier for the target chat
user_id Yes Integer Unique identifier for the target user
Request Example
{
    "chat_type": 3,
    "chat_id": 8000012,
    "user_id": 80000001
}
Return Parameter
Parameter Type Description
ok Boolean Whether the operation is successful or not
Return Example
{
    "ok": true
}

sendChatAction

Request URL

  • https://api.sydney.im:8443/<bot_token>/sendChatAction
Request Method
  • POST

A brief description

  • use 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 Parameter
Parameter Required Type Description
chat_type Yes ChatType Type for the target chat
chat_id Yes Integer Unique identifier for the target chat or username of the target channel
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 Boolean Whether the operation is successful or not
Return Example
{
    "ok": true
}

sendContact

Request URL

  • https://api.sydney.im:8443/<bot_token>/sendContact

Request Method

  • POST

A brief description

  • Use this method to send phone contacts. Returns True on success.
Request Parameter
Parameter Required Type Description
chat_type Yes ChatType Type for the target chat
chat_id Yes Integer 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 Boolean Sends the message silently. Users will receive a notification with no sound.
reply_to_message_id No Integer 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 Boolean Whether the operation is successful or not
Return Example
{
    "ok": true
}

getGroups

Request URL

  • https://api.sydney.im:8443/<bot_token>/getGroups

Request Method

  • GET

A brief description

  • Get groups/supergroups/channels where bot staying
Return Parameter
Parameter Type Description
ok Boolean Whether the operation is successful or not
Groups String[] groups
SuperGroups String[] supergroups
Channels String[] channels
Return Example
{
    "ok": true,
    "result": {
        "Groups": [
            {
                "PeerID": 12345671,
                "PeerName": "group"
            }
        ],
        "SuperGroups": [
            {
                "PeerID": 12345672,
                "PeerName": "supergroup"
            }
        ],
        "Channels": [
            {
                "PeerID": 12345673,
                "PeerName": "channel"
            }
        ]
    }
}

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.sydney.im:8443/<bot_token>/sendGame

Request Method

  • POST

A brief description

  • Use this method to send a game. On success, the sent MessageID is returned.
Request Parameter
Parameter Required Type Description
chat_type Yes ChatType Type for the target chat
chat_id Yes Integer 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 Integer If the message is a reply, ID of the original message
disable_notification Optional Boolean WSends the message silently. Users will receive a notification with no sound.
reply_markup Optional InlineKeyboardMarkup A 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 Integer Indicates the unique ID of the message
Return Example
{
    "ok": true,
    "result": {
        "message_id": 27315
    }
}

setGameScore

Request URL

  • https://api.sydney.im:8443/<bot_token>/setGameScore

Request Method

  • POST

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 Parameter
Parameter Required Type Description
chat_type Yes ChatType Type for the target chat
chat_id Yes Integer Unique identifier for the target chat
user_id Yes Integer Unique identifier of the user
score Yes Integer New score, must be non-negative
message_id Yes Integer Identifier of the sent game message
force Optional Boolean 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 Integer Indicates the unique ID of the message
Return Example
{
    "ok": true,
    "result": {
        "message_id": 27315
    }
}

getGameHighScores

Request URL

  • https://api.sydney.im:8443/<bot_token>/getGameHighScores

Request Method

  • POST

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 Parameter
Parameter Required Type Description
chat_type Yes ChatType Type for the target chat
chat_id Yes Integer Unique identifier for the target chat
user_id Yes Integer Unique identifier of the user
message_id Yes Integer 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 Integer 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 Required Description
id String Yes Unique identifier for this query
from User Yes Sender
location Location Optional Optional. Sender location, only for bots that request user location
query String Yes Text of the query (up to 512 characters)
offset String Yes Offset of the results to be returned, can be controlled by the bot

answerInlineQuery

Request URL

  • https://api.sydney.im:8443/<bot_token>/answerInlineQuery

Request Method

  • POST
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 Parameter
Parameter Type Required Description
inline_query_id String Yes Unique identifier for the answered query
results Array of InlineQueryResult Yes A JSON-serialized array of results for the inline query
is_personal Boolean Optional 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 String Optional 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 String Optional 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 String Optional 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 5 types:

InlineQueryResultArticle

A brief description

  • Represents a link to an article.
Field Type Required Description
type String Yes Type of the result, must be article
id String Yes Unique identifier for this result, 1-64 Bytes
title String Yes Title of the result
input_message_content InputMessageContent Yes 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 Integer Optional Optional. Thumbnail width
thumb_height Integer Optional Optional. Thumbnail height

InlineQueryResultWebsite

A brief description

  • Represents a link to an web page.
Field Type Required Description
type String Yes Type of the result, must be website
id String Yes Unique identifier for this result, 1-64 Bytes
title String Yes Title of the result
input_message_content InputMessageContent Yes Content of the message to be sent
url String Yes URL of the website
reply_markup InlineKeyboardMarkup Optional Inline keyboard attached to the message
description String Optional Short description of the result
thumb_url String Optional Url of the thumbnail for the result

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 Required Description
type String Yes Type of the result, must be article
id String Yes Unique identifier for this result, 1-64 Bytes
game_short_name String Yes Unique identifier of the user
reply_markup ReplyMarkup Optional 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 Required Description
type String Yes Type of the result, must be gif
id String Yes Unique identifier for this result, 1-64 bytes
gif_url String Yes A valid URL for the GIF file. File size must not exceed 1MB
gif_width Integer Optional Width of the GIF
gif_height Integer Optional Height of the GIF
gif_duration Integer Optional Duration of the GIF
thumb_url String Yes 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
reply_markup InlineKeyboardMarkup Optional Inline keyboard](#inlinekeyboardmarkup) attached to the message

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 Required Description
type String Yes Type of the result, must be photo
id String Yes Unique identifier for this result, 1-64 bytes
photo_url String Yes A valid URL of the photo. Photo must be in jpeg format. Photo size must not exceed 5MB
thumb_url String Yes URL of the thumbnail for the photo
photo_width Integer Optional Width of the photo
photo_height Integer 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
reply_markup InlineKeyboardMarkup Optional Inline keyboard attached to the message

InlineQueryResultVideo

A brief description
  • Represents a link to a page containing an embedded video player or a video file. By default, this video file will be sent by the user with an optional caption. Alternatively, you can use input_message_content to send a message with the specified content instead of the video.
  • If an InlineQueryResultVideo message contains an embedded video (e.g., YouTube), you must replace its content using input_message_content.
Field Type Required Description
type String Yes Type of the result, must be video
id String Yes Unique identifier for this result, 1-64 bytes
video_url String Yes A valid URL for the embedded video player or video file and size must not exceed 50MB
mime_type String Yes Mime type of the content of video url, "text/html" or "video/mp4"
thumb_url String Yes URL of the thumbnail for the video
title String Yes Title for the result
caption String Optional Caption of the photo to be sent, 0-1024 characters
video_width Integer Optional Video width, default 686px
video_height Integer Optional Video height, default 386px
reply_markup InlineKeyboardMarkup Optional Inline keyboard attached to the message

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 Required Description
message_text String Yes TypText of the message to be sent, 1-4096 characters

InlineQueryResultCachedPhoto

A brief description

  • Represents a link to a photo stored on the Potato servers. By default, this photo will be sent by the user with an optional caption. Alternatively, you can use input_message_content to send a message with the specified content instead of the photo.
Field Type Required Description
type String Yes Type of the result, must be photo
id String Yes Unique identifier for this result, 1-64 bytes
photo_file_id String Yes A valid file identifier of the photo
title String Optional Title for the result
description String Optional 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

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 Integer 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 Type Required Description
id Yes Integer The user's unique ID
type Yes ChatType Chat Type
title String Optional The title of the dialog takes effect only if the type field is 2 (PeerChat) or 3 (ChannelChat
invite_link String Optional Invite link, only when the type field is 3 (ChannelChat) will take effect
username String Optional Username, for private chats, supergroups and channels if available
all_members_are_administrators Boolean Optional True if a group has 'All Members Are Admins' enabled.
description String Optional Description, for supergroups and channel chats. Returned only in getChat
pinned_message Message Optional Pinned message, for supergroups and channel chats. Returned only in getChat.
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 Required Type Comments
type Yes EntityType Entity type
user_id Optional Integer Required when type 7 (EntityMentionName) indicates the target user ID of @e
offset Yes Integer the starting offset position of the link, in bytes, of which Chinese characters and English letters count one byte, emoj count two bytes
length Yes Integer the length of the link, in bytes
url Optional String 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 Optional Default false, whether to click and send your own business card
request_location Boolean Optional 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 Optional Default null, HTTP url
callback_data String Optional default null, callback send data
switch_inline_query String Optional 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 Optional 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 Booleanean Optional "False" by default, adaptive keyboard height
single_use Booleanean Optional "False" by default, hide custom keyboard after use
selective Booleanean Optional "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 Booleanean Optional "False" by default, adaptive keyboard height
single_use Booleanean Optional "False" by default, hide custom keyboard after use
selective Booleanean Optional "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 Booleanean Optional 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 Booleanean Optional 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 Float Yes Longitude
latitude Float Yes Latitude

Venue

Field Type Required Comments
longitude Float Yes Longitude
latitude Float Yes Latitude
title String Yes Title
address String Yes Address
foursquare_id String Optional 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 Optional Photo size

Audio

Field Type Required Comments
file_id String Yes File unique ID
duration Integer Yes Playing time
performer String Optional Author
title String Optional Title
mime_type String Optional File mime_type
file_size Integer Optional File size

Document

Field Type Required Comments
file_id String Yes File unique ID
thumb PhotoSize Optional File thumbnail
file_name String Optional File name
mime_type String Optional File mime type
file_size Integer Optional 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 Optional Video thumbnail
mime_type String Optional File MIME type
file_size Integer Optional File size

Voice

Field Type Required Comments
file_id String Yes File unique ID
duration Integer Yes Playing time
mime_type String Optional File MIME type
file_size Integer Optional File size

Contact

Field Type Required Comments
phone_number String Yes Contact phone number
first_name String Yes Contact first name
last_name String Optional Contact last name
user_id Integer Optional Contact user id

MessageAction

Field Type Required Comments
new_group_members Array of User Optional Join the group
left_group_member User Optional Leave the group
new_group_title String Optional Modify the group name
migrate_from_chat_id Integer Optional Upgrade from a normal group to a super group with the unique ID of the normal group
migrate_to_chat_id Integer Optional 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 Optional The sender of the original message
forward_date Integer Optional Message forwarding Unix timestamp
text String Optional Message text
entities Array of Entity Optional An array of Entity objects describing the rich text information
reply_to_message Message Optional Reply to the original message
date Integer Yes Unix time stamp of the message
edit_date Integer Optional Unix timestamp of last edited message
location Location Optional Address location
venue Venue Optional Address
photo Array of PhotoSize Optional Photo file
audio Audio Optional Audio file
document Document Optional Document file
video Video Optional Video file
voice Voice Optional Recording files
contact Contact Optional Contact
caption String Optional Document / Picture / Video / Audio title
action MessageAction Optional Message action

Update

Field Type Required Comments
update_id Integer Yes Update ID
message Message Optional Messages (including text, media and forwarding messages)
edited_message Message Optional Edit the message
callback_query CallbackQuery Optional Callback inquiry
Inline_query InlineQuery Optional Incoming inline query
lang String Optional Current session client language type

ChatMember

Field Type Required Comments
user User Yes Information about the user
status String Yes The member's status in the chat. Can be "creator", "administrator", "member", "restricted", "left" or "kicked"
until_date Integer Optional Restricted and kicked only. Date when restrictions will be lifted for this user, unix time
can_be_edited Boolean Optional Administrators only. True, if the bot is allowed to edit administrator privileges of that user
can_change_info Boolean Optional Administrators only. True, if the administrator can change the chat title, photo and other settings
can_post_messages Boolean Optional Administrators only. True, if the administrator can post in the channel, channels only
can_edit_messages Boolean Optional Administrators only. True, if the administrator can edit messages of other users and can pin messages, channels only
can_delete_messages Boolean Optional Administrators only. True, if the administrator can delete messages of other users
can_invite_users Boolean Yes Administrators only. True, if the administrator can invite new users to the chat
can_restrict_members Boolean Optional Administrators only. True, if the administrator can restrict, ban or unban chat members
can_pin_messages Boolean Optional Administrators only. True, if the administrator can pin messages, supergroups only
can_promote_members Boolean Optional Administrators only. True, if the administrator can add new administrators with a subset of his own privileges or demote administrators that he has promoted, directly or indirectly (promoted by administrators that were appointed by the user)
can_send_messages Boolean Optional Restricted only. True, if the user can send text messages, contacts, locations and venues
can_send_media_messages Boolean Optional Restricted only. True, if the user can send audios, documents, photos, videos, video notes and voice notes, implies can_send_messages
can_send_other_messages Boolean Optional Restricted only. True, if the user can send animations, games, stickers and use inline bots, implies can_send_media_messages
can_add_web_page_previews Boolean Optional Restricted only. True, if user may add web page previews to his messages, implies can_send_media_messages

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
1017 not support the chat type
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
3016 none pinned msg