Bot API 3.0

Changelog

May 18, 2017

Introducing Bot API 3.0.

NEW Payment Platform

See Introduction to Bot Payments for a brief overview. If you're not a developer, you may like this user-friendly blog post better.

NEW Video Messages

  • As of Telegram v.4.0, users can send short rounded video messages, using an interface similar to that of voice notes.
  • Added the sendVideoNote method, the new field video_note to Message, the fields record_video_note or upload_video_note to sendChatAction.

NEW Multilingual Bots

  • The User object now may have a language_code field that contains the IETF language tag of the user's language.
  • Thanks to this, your bot can now offer localized responses to users that speak different languages.

More power to admin bots

  • unbanChatMemeber now also works in channels!
  • New method deleteMessage that allows the bot to delete its own messages, as well as messages posted by other in groups and channels where the bot is an administrator.

Minor Changes

  • Replaced the field new_chat_member in Message with new_chat_members (the old field will still be available for a while for compatibility purposes).
  • Inline keyboards with switch_inline_query and switch_inline_query_current_chat can no longer be sent to channels because they are useless there.
  • New fields gif_duration in InlineQueryResultGif and mpeg4_duration in InlineQueryResultMpeg4Gif.

Payments

Your bot can accept payments from Telegram users. Please see the introduction to payments for more details on the process and how to set up payments for your bot. Please note that users will need Telegram v.4.0 or higher to use payments (released on May 18, 2017).

sendInvoice

Use this method to send invoices. On success, the sent Message is returned.

Parameters Type Required Description
chat_id Integer Yes Unique identifier for the target private chat
title String Yes Product name
description String Yes Product description
payload String Yes Bot-defined invoice payload, 1-128 bytes. This will not be displayed to the user, use for your internal processes.
provider_token String Yes Payments provider token, obtained via Botfather
start_parameter String Yes Unique deep-linking parameter that can be used to generate this invoice when used as a start parameter
currency String Yes Three-letter ISO 4217 currency code, see more on currencies
prices Array of LabeledPrice Yes Price breakdown, a list of components (e.g. product price, tax, discount, delivery cost, delivery tax, bonus, etc.)
photo_url String Optional URL of the product photo for the invoice. Can be a photo of the goods or a marketing image for a service. People like it better when they see what they are paying for.
photo_size Integer Optional Photo size
photo_width Integer Optional Photo width
photo_height Integer Optional Photo height
need_name Bool Optional Pass True, if you require the user's full name to complete the order
need_phone_number Boolean Optional Pass True, if you require the user's phone number to complete the order
need_email Bool Optional Pass True, if you require the user's email to complete the order
need_shipping_address Boolean Optional Pass True, if you require the user's shipping address to complete the order
is_flexible Boolean Optional Pass True, if the final price depends on the shipping method
disable_notification Boolean Optional Sends the message silently. Users will receive a notification with no sound.
reply_to_message_id Integer Optional If the message is a reply, ID of the original message
reply_markup InlineKeyboardMarkup Optional A JSON-serialized object for an inline keyboard. If empty, one 'Pay total price' button will be shown. If not empty, the first button must be a Pay button.

answerShippingQuery

If you sent an invoice requesting a shipping address and the parameter is_flexible was specified, the Bot API will send an Update with a shipping_query field to the bot. Use this method to reply to shipping queries. On success, True is returned.

Parameters Type Required Description
shipping_query_id String Yes Unique identifier for the query to be answered
ok Boolean Yes Specify True if delivery to the specified address is possible and False if there are any problems (for example, if delivery to the specified address is not possible)
shipping_options Array of ShippingOption Optional Required if ok is True. A JSON-serialized array of available shipping options.
error_message String Optional Required if ok is False. Error message in human readable form that explains why it is impossible to complete the order (e.g. "Sorry, delivery to your desired address is unavailable'). Telegram will display this message to the user.

answerPreCheckoutQuery

Once the user has confirmed their payment and shipping details, the Bot API sends the final confirmation in the form of an Update with the field pre_checkout_query. Use this method to respond to such pre-checkout queries. On success, True is returned. Note: The Bot API must receive an answer within 10 seconds after the pre-checkout query was sent.

Parameters Type Required Description
pre_checkout_query_id String Yes Unique identifier for the query to be answered
ok Boolean Yes Specify True if everything is alright (goods are available, etc.) and the bot is ready to proceed with the order. Use False if there are any problems.
error_message String Optional Required if ok is False. Error message in human readable form that explains the reason for failure to proceed with the checkout (e.g. "Sorry, somebody just bought the last of our amazing black T-shirts while you were busy filling out your payment details. Please choose a different color or garment!"). Telegram will display this message to the user.

Message

This object represents a message.

Field Type Description
invoice Invoice Optional. Message is an invoice for a payment, information about the invoice. More about payments »
successful_payment SuccessfulPayment Optional. Message is a service message about a successful payment, information about the payment. More about payments »

InlineKeyboardButton

This object represents one button of an inline keyboard. You must use exactly one of the optional fields.

Field Type Description
pay Boolean Optional. Specify True, to send a Pay button.

NOTE: This type of button must always be the first button in the first row.

LabeledPrice

This object represents a portion of goods price.

Field Type Description
label String Portion label
amount Integer Price of the product in the smallest units of the currency (integer, not float/double). For example, for a price of US$ 1.45 pass amount = 145. See the exp parameter in currencies.json, it shows the number of digits past the decimal point for each currency (2 for the majority of currencies).

Invoice

This object contains basic information about an invoice.

Field Type Description
title String Product name
description String Product description
start_parameter String Unique bot deep-linking parameter that can be used to generate this invoice
currency String Three-letter ISO 4217 currency code
total_amount Integer Total price in the smallest units of the currency (integer, not float/double). For example, for a price of US$ 1.45 pass amount = 145. See the exp parameter in currencies.json, it shows the number of digits past the decimal point for each currency (2 for the majority of currencies).

ShippingAddress

This object represents a shipping address.

Field Type Description
country_code String ISO 3166-1 alpha-2 country code
state String State, if applicable
city String City
street_line1 String First line for the address
street_line2 String Second line for the address
post_code String Address post code

OrderInfo

This object represents information about an order.

Field Type Description
name String Optional. User name
phone_number String Optional. User's phone number
email String Optional. User email
shipping_address ShippingAddress Optional. User shipping address

ShippingOption

This object represents one shipping option.

Field Type Description
id String Shipping option identifier
title String Option title
prices Array of LabeledPrice List of price portions

SuccessfulPayment

This object contains basic information about a successful payment.

Field Type Description
currency String Three-letter ISO 4217 currency code
total_amount Integer Total price in the smallest units of the currency (integer, not float/double). For example, for a price of US$ 1.45 pass amount = 145. See the exp parameter in currencies.json, it shows the number of digits past the decimal point for each currency (2 for the majority of currencies).
invoice_payload String Bot specified invoice payload
shipping_option_id String Optional. Identifier of the shipping option chosen by the user
order_info OrderInfo Optional. Order info provided by the user
telegram_payment_charge_id String Telegram payment identifier
provider_payment_charge_id String Provider payment identifier

Update

Field Type Description
shipping_query ShippingQuery Optional. New incoming shipping query. Only for invoices with flexible price
pre_checkout_query PreCheckoutQuery Optional. New incoming pre-checkout query. Contains full information about checkout

ShippingQuery

This object contains information about incoming shipping query.

Field Type Description
id String Unique query identifier
from User User who sent the query
invoice_payload String Bot specified invoice payload
shipping_address ShippingAddress User specified shipping address

PreCheckoutQuery

This object contains information about incoming pre-checkout query.

Field Type Description
id String Unique query identifier
from User User who sent the query
currency String Three-letter ISO 4217 currency code
total_amount Integer Total price in the smallest units of the currency (integer, not float/double). For example, for a price of US$ 1.45 pass amount = 145. See the exp parameter in currencies.json, it shows the number of digits past the decimal point for each currency (2 for the majority of currencies).
invoice_payload String Bot specified invoice payload
shipping_option_id String Optional. Identifier of the shipping option chosen by the user
order_info OrderInfo Optional. Order info provided by the user

Other changes

deleteMessage

Use this method to delete a message. A message can only be deleted if it was sent less than 48 hours ago. Any such recently sent outgoing message may be deleted. Additionally, if the bot is an administrator in a group chat, it can delete any message. If the bot is an administrator in a supergroup, it can delete messages from any other user and service messages about people joining or leaving the group (other types of service messages may only be removed by the group creator). In channels, bots can only remove their own messages. Returns True on success.

Parameters Type Required Description
chat_id Integer or String Yes Unique identifier for the target chat or username of the target channel (in the format @channelusername)
message_id Integer Yes Identifier of the message to delete

VideoNote

This object represents a video message (available in Telegram apps as of v.4.0).

Field Type Description
file_id String Unique identifier for this file
length Integer Video width and height as defined by sender
duration Integer Duration of the video in seconds as defined by sender
thumb PhotoSize Optional. Video thumbnail
file_size Integer Optional. File size

sendVideoNote

As of v.4.0, Telegram clients support rounded square mp4 videos of up to 1 minute long. Use this method to send video messages. On success, the sent Message is returned.

Parameters Type Required Description
chat_id Integer or String Yes Unique identifier for the target chat or username of the target channel (in the format @channelusername)
video_note InputFile or String Yes Video note to send. Pass a file_id as String to send a video note that exists on the Telegram servers (recommended) or upload a new video using multipart/form-data. More info on Sending Files ». Sending video notes by a URL is currently unsupported
duration Integer Optional Duration of sent video in seconds
length Integer Optional Video width and height
disable_notification Boolean Optional Sends the message silently. iOS users will not receive a notification, Android users will receive a notification with no sound.
reply_to_message_id Integer Optional If the message is a reply, ID of the original message
reply_markup InlineKeyboardMarkup or ReplyKeyboardMarkup or ReplyKeyboardRemove or ForceReply 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 user.

sendChatAction

Parameters Type Required Description
chat_id Integer or String Yes Unique identifier for the target chat or username of the target channel (in the format @channelusername)
action String Yes 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.

User

This object represents a Telegram user or bot.

Field Type Description
language_code String Optional. IETF language tag of the user's language

Message

This object represents a message.

Field Type Description
video_note VideoNote Optional. Message is a video note, information about the video message
new_chat_members Array of User Optional. New members that were added to the group or supergroup and information about them (the bot itself may be one of these members)

InlineQueryResultGif

Field Type Description
gif_duration Integer Optional. Duration of the GIF

InlineQueryResultMpeg4Gif

Field Type Description
mpeg4_duration Integer Optional. Video duration

unbanChatMember

Use this method to unban a previously kicked user in a supergroup or channel. The user will not return to the group or channel automatically, but will be able to join via link, etc. The bot must be an administrator for this to work. Returns True on success.

Parameters Type Required Description
chat_id Integer or String Yes Unique identifier for the target group or username of the target supergroup or channel (in the format @username)
user_id Integer Yes Unique identifier of the target user
Telegram
Telegram is a cloud-based mobile and desktop messaging app with a focus on security and speed.
About
Mobile Apps
Desktop Apps
Platform
About
Blog
Apps
Platform
Twitter