Potato API
We offer APIs for developers. The Bot API allows you to easily create programs that use Potato messages for an interface. The Potato API allows you to build your own customized Potato clients. You are welcome to use it free of charge.
  • Create Bot
  • Receive the message
    • Receiving Message Introduction
    • Get updated data
    • Set Webhook
    • Remove Webhook
  • Getting information
    • Get your personal information
    • Get file information
  • Send a message
    • Send a text message
    • Forward the existing message
    • Answer the query callback
    • Send the location
    • Send detailed address
    • Send photo file
    • Send document file
  • Edit Messages
    • Edit message text
    • Edit the message title
    • Delete message
  • Object type
    • Chat type
    • Entity type
    • ReplyMarkup type
    • User
    • Chat
    • Entity
    • Button
    • ReplyMarkup
    • Location
    • Venue
    • PhotoSize
    • Audio
    • Document
    • Video
    • Voice
    • Contact
    • MessageAction
    • CallbackQuery
    • Message
    • Update
  • Rich text support
    • Grammar introduction
  • error code
    • Return value list

Create Bot

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

Receiving Message Introduction


Receiving Method

When a new message is sent to the bot, Potato bot server send the message to the bot user in two ways:

1.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.

2.Passive Mode: User regularly needs to request https://api.potato.im:8443/<bot token>/getUpdates to retrieve bot updates (<toke> 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.

Get Updated Data

A brief description:

Used to get bot related data updates

Request URL:https://api.potato.im:8443/<bot_token>/getUpdates

Request Method:GET

Return parameter description:

This interface will return an array containing the Json data. The array of elements type is Update, containing all bot related updates.

Set Webhook

A brief description:

Use to set the bot webhook

Request URL:https://api.potato.im:8443/<bot_token>/setWebhook

Request method:POST

Parameter:

Parameter Name Required Type Description
url yes string callback address
certificate no InputFile A digital certificate that sends an existing file on the server through the file_id string. Or upload new files, using multipart/form-data

Remove Webhook

A brief description:

Use to delete the set bot webhook

Request URL:https://api.potato.im:8443/<bot_token>/delWebhook

Request Method:GET

Getting Information


Get Your Personal Information

A brief description:

Use to obtain the bot's own information

Request URL:https://api.potato.im:8443/<bot_token>/getMe

Request Method:GET

Return parameter description:

This interface will return a User object that contains the user information.

Get File Information

A brief description:

The URL used to get the file

Request URL:https://api.potato.im:8443/<bot_token>/getFile

Request method:POST

Parameter:

Parameter Name Required Type Description
file_id yes string file unique ID

Return parameter description:

Filed Type Description
url string URL of the file

Send A Message


Send A Text Message

A brief description:

Interface for bot users to send text messages

Request URL:https://api.potato.im:8443/<bot_token>/sendTextMessage

Request method:POST

Parameter:

Parameter Name Required Type Description
chat_type yes ChatType chat type
chat_id yes integer Chat ID
text yes string message text
reply_to_message_id no integer The unique ID of the reply message
markdown no boolean Whether to use MarkDown rendering, Entities will be generated automatically based on the text field. Refer Rich Text Support for detail
reply_markup no ReplyMarkup Use to describe the reply tag

Return parameter description:

Field Type Description
message_id integer Indicates the unique ID of the message

Forward The Existing Message

A brief description:

Interface for bot users to forward any type of message

Request URL:https://api.potato.im:8443/<bot_token>/forwardMessage

Request Method:POST

Parameter:

Parameter Name Required Type Description
chat_type yes ChatType target chat type
chat_id yes integer target Chat ID
from_chat_type yes ChatType source target chat type
from_chat_id yes integer source chat ID/td>
message_id yes integer Unique ID of the message to be forwarded

Return parameter description

Field Type Description
message_id integer A unique ID that represents the new message

Answer The Query Callback

A brief description:

Use by bot users to answer user-sent query callbacks

Request URL:https://api.potato.im:8443/<bot_token>/answerCallbackQuery

Request method:POST

Parameter:

Parameter Name 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 no string notification text, 0-200 characters
show_alert no boolean Default false, set whether to display a warning
url no string Open the URL, the game mode is valid
cache_time no integer Default 0, query result cache time

Send The Location

A brief description:

Use to send the user a geographic location.

Request URL:https://api.potato.im:8443/<bot_token>/sendLocation

Request method:Post

Parameter:

Parameter Name Required Type Description
chat_type yes ChatType chat type
chat_id yes integer target Chat ID
latitude yes number latitude
longitude yes integer number
reply_to_message_id no integer The unique ID of the reply message
reply_markup no ReplyMarkup use to describe the reply tag

Return parameter description:

Field Type Description
message_id integer Indicates the unique ID of the message

Send Detailed Address

A brief description:

Use to send the user a detailed address.

Request URL:https://api.potato.im:8443/<bot_token>/sendVenue

Request Method:POST

Parameter:

Parameter Name Required Type Description
chat_type yes ChatType chat type
chat_id yes integer target Chat ID
latitude yes number latitude
longitude yes integer number
title yes string title
address yes string address
foursquare_id no string Foursquare identifier (ID)
reply_to_message_id no integer The unique ID of the reply message
reply_markup no ReplyMarkup use to describe the reply tag

Return parameter description:

Field Type Description
message_id integer Indicates the unique ID of the message

Send Photo File

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.

Request URL:https://api.potato.im:8443/<bot_token>/sendPhoto

Request Method:POST

Parameter:

Parameter Name Required Type Description
chat_type yes ChatType ctarget chat type
chat_id yes integer target Chat ID
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 no string Caption (0-200 characters)
reply_to_message_id no integer The unique ID of the reply message
reply_markup no ReplyMarkup use to describe the reply tag

Return parameter description:

Field Type Description
message_id integer Indicates the unique ID of the message
file_id string Indicates the unique ID of the file

Send Document File

A brief description:

Interface for bot users to forward any type of message

Request URL:https://api.potato.im:8443/<bot_token>/sendDocument

Request method:POST

Parameter:

Parameter Name Required Type Description
chat_type yes ChatType ctarget chat type
chat_id yes integer target Chat ID
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 no string Caption (0-200 characters)
reply_to_message_id no integer The unique ID of the reply message
reply_markup no ReplyMarkup use to describe the reply tag

Return parameter description

Field Type Description
message_id integer Indicates the unique ID of the message
file_id string Indicates the unique ID of the file

Edit Messages


Edit Message Text

A brief description:

Use to edit text messages sent by bot users.

Request URL:https://api.potato.im:8443/<bot_token>/editMessageText

Request Method:POST

parameter:

Parameter Name Required Type Description
chart_type yes ChatType target chat type
chart_id yes integer target Chat ID
message_id yes integer the unique ID of the message being edited
text yes string message text
markdown no boolean Whether to use MarkDown rendering, Entities will be generated automatically based on the text field. Refer Rich Text Support for detail
reply_markup no ReplyMarkup use to describe the reply tag

Return parameter description:

Field type Description
ok boolean Whether the operation is successful or not

Edit The Message Title

A brief description:

Edit the title of bot user's sent message or media.

Request URL:https://api.potato.im:8443/<bot_token>/editMessageCaption

Request Method:POST

parameter:

Parameter Name Required Type Description
chart_type yes ChatType target chat type
chat_id yes integer target Chat ID
message_id yes integer the unique ID of the message being edited
caption yes string Message or Media Caption
reply_markup no ReplyMarkup use to describe the reply tag

Return parameter description:

Filed Type Description
ok Boolean Whether the operation is successful or not

Delete Message

A brief description:

Use for bot users to delete a message. If the bot is an administrator in group chat, it can delete any message.

Request URL:https://api.potato.im:8443/<bot_token>/deleteMessage

Request Method:POST

parameter:

Parameter Name Required Type Description
chart_type yes ChatType target chat type
chat_id yes integer target Chat ID
message_id yes integer The unique ID of the deleted message

Return parameter description:

Filed Type Description
ok Boolean Whether the operation is successful or not

Object Type


Chat Type

Used to define the type of chat dialog box, the following is the type of Chat object can be used.

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.

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.

Field Type Required Comments
id integer yes the user's unique ID
first_name string no User First name
last_name no string User Last name
username yes string the user name

Chat

Chat is used to describe chatting dialog information.

Field Type Required Comments
id integer yes the user's unique ID
type ChatType yes Chat Type
title no string The title of the dialog takes effect only if the type field is 2 (PeerChat) or 3 (ChannelChat)
invite_link no string Invite link, only when the type field is 3 (ChannelChat) will take effect

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 needs to be set as 1(ForceReplyType), indicating a forced response.
single_use boolean no "False" by default, hides 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 4(InlineKeyboardMarkupType), indicating inline keyboard
inline_keyboard array of InlineKeyboardButtonRow yes Inline Keyboard, referencing "Button" object "InlineKeyboardButton"

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!");

Text Link

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

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

Email Link

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

<username@mail.com>

Hyper Link

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 return system failure, as well as http status code 500
1002 ineffective token, also return http status code 401
1003 unknown command, also return http status code 400
1004 wrong parameters, also return http status code 400
1005 wrong data format, also return http status code 400
1006 no permission to send, also return http status code 400
1007 frequency of APIs sent exceeded limit, also return http status code 429
1008 cannot send message to target user, also return http status code 400
1009 uploaded file size too large, also return http status code 400
1010 illegal characters in message, also return http status code 400
1011 "entities" exceeds length limit, also return http status code 400
1012 "reply markup" exceeds length limit, also return http status code 400
1013 Document does not exist
© 2017 ALL Rights Reserved Horsemen Technologies SA