Используемые типы данных

BotRequest

Запрос к боту. Приходит в поле bot_request объекта Update, когда пользователь нажимает кнопку с директивой server_action.

Имя параметра

Обязат.

Тип

Описание

Ограничения

server_action

Нет

ServerAction

Серверное действие от кнопки

—

element_id

Нет

string

ID нажатого элемента (кнопки)

—

errors

Нет

BotRequestError[]

Массив ошибок при выполнении директив

—

BotRequestError

Ошибка при выполнении директивы на клиенте.

Имя параметра

Обязат.

Тип

Описание

Ограничения

type

Да

string

Тип ошибки

Возможные значения:

  • unsupported_directive — директива не поддерживается клиентом;
  • invalid_directive_payload — невалидные данные директивы;
  • client_error — ошибка на стороне клиента.

name

Нет

string

Имя директивы, вызвавшей ошибку

Для типов unsupported_directive и invalid_directive_payload

message

Нет

string

Текст ошибки

Для типа client_error

Button

Важно

Тип Button и параметр inline_keyboard устарели. Рекомендуется использовать SuggestButtons.

Используется в запросах для описания инлайн-кнопки под текстовым сообщением.

Имя параметра

Обязат.

Тип

Описание

Ограничения

text

Да

string

Текст на инлайн-кнопке

—

callback_data

Нет

json

Данные, которые будут отправлены на сервер при нажатии кнопки

—

url

Нет

string

URL, который откроется при нажатии кнопки

—

Chat

Используется в ответах для описания чата (канала).

Имя параметра

Обязат.

Тип

Описание

Ограничения

type

Да

string

Тип чата

Возможные значения:

  • private — приватный чат;
  • group — групповой чат;
  • channel — канал.

id*

Нет

string

Идентификатор чата

У чата с типом private нет значимого идентификатора. В таком чате всегда два участника — бот и его собеседник. Собеседника нужно определять по объекту типа User, который обычно расположен рядом.

(*) Для группового чата (group) или канала (channel) идентификатор можно получить из адресной строки браузера:

  1. Откройте чат в веб-версии Мессенджера.
  2. Из адресной строки скопируйте набор символов после https://yandex.ru/chat/#/chats/.
  3. Если браузер применяет URL-кодирование в ссылке, замените %2F на слэш /.

Directive

Директива — это действие, которое выполняется при нажатии на кнопку. Одна кнопка может содержать несколько директив (до 3).

Типы директив

OpenUriDirective

Открывает URL в браузере.

Имя параметра

Обязат.

Тип

Описание

Ограничения

type

Да

string

Тип директивы

Значение: open_uri

uri

Да

string

URL для открытия

—

SendMessageDirective

Отправляет сообщение в чат от имени пользователя, нажавшего кнопку.

Имя параметра

Обязат.

Тип

Описание

Ограничения

type

Да

string

Тип директивы

Значение: send_message

text

Да

string

Текст сообщения

Не более 6000 символов

payload

Нет

json

Произвольные данные, которые бот получит вместе с сообщением

—

ServerActionDirective

Отправляет серверное действие боту. В отличие от send_message, сообщение не появляется в чате — бот получает только уведомление о нажатии кнопки.

Имя параметра

Обязат.

Тип

Описание

Ограничения

type

Да

string

Тип директивы

Значение: server_action

name

Да

string

Имя действия

—

payload

Да

json

Произвольные данные

—

При нажатии бот получит обновление с полем bot_request, содержащим server_action с указанными name и payload.

SetElementsStateDirective

Изменяет состояние элементов интерфейса (например, блокирует кнопки на время обработки).

Имя параметра

Обязат.

Тип

Описание

Ограничения

type

Да

string

Тип директивы

Значение: set_elements_state

ids

Да

string[]

Идентификаторы элементов для изменения

—

state

Да

string

Новое состояние

Значения: disabled или loading

timeout_seconds

Нет

integer

Время действия состояния в секундах

От 1 до 60. По умолчанию: 15

File

Используется в ответах для описания файла.

Имя параметра

Обязат.

Тип

Описание

Ограничения

id

Да

string

Идентификатор файла для загрузки через API

—

name

Да

string

Имя файла

—

size

Да

integer

Размер файла в байтах

—

Image

Используется в ответах для описания изображения.

Имя параметра

Обязат.

Тип

Описание

Ограничения

file_id

Да

string

Идентификатор файла для загрузки через API

—

width

Да

integer

Ширина картинки

—

height

Да

integer

Высота картинки

—

size

Нет

integer

Размер файла в байтах

Указывается только для оригинала

name

Нет

string

Название файла (каким оно было при загрузке)

Указывается только для оригинала

InlineSuggestButton

Кнопка, отображаемая под сообщением.

Имя параметра

Обязат.

Тип

Описание

Ограничения

id

Нет

string

Уникальный идентификатор кнопки

Не более 255 символов

title

Нет

string

Текст на кнопке

Не более 255 символов

directives

Нет

Directive[]

Действия при нажатии

Не более 3 действий

Sender

Используется в ответах для описания отправителя сообщения.

Имя параметра

Обязат.

Тип

Описание

Ограничения

login

Да*

string

Логин пользователя, который отправил сообщение

Указывается для сообщений из чатов

ИЛИ id

Да*

string

id канала, администратор которого отправил сообщение

Указывается для сообщений в каналах

display_name

Нет

string

Отображаемое имя отправителя

—

robot

Нет

boolean

Признак, является ли отправитель ботом

—

(*) В ответе придет только один из параметров login или id в зависимости от того, куда было отправлено сообщение — в чат или канал.

ServerAction

Серверное действие, которое бот получает при нажатии кнопки с директивой server_action.

Имя параметра

Обязат.

Тип

Описание

Ограничения

name

Да

string

Имя действия (то, что было указано в директиве)

—

payload

Нет

json

Произвольные данные действия

—

SuggestButtons

Используется в запросах для описания клавиатуры с кнопками под сообщением.

Имя параметра

Обязат.

Тип

Описание

Ограничения

layout

Нет

string

Режим отображения кнопок. "false" — кнопки идут в одну строку с переносом. "true" — кнопки располагаются по строкам согласно двумерному массиву в buttons

—

persist

Нет

boolean

Сохранять ли кнопки после нажатия. Если true, кнопки остаются на месте после клика

—

buttons

Нет

InlineSuggestButton[] или InlineSuggestButton[][]

Массив кнопок. При layout: "false" — одномерный массив. При layout: "true" — двумерный массив, где каждый вложенный массив — это отдельная строка

Не более 100 кнопок

Vote

Используется в ответах для описания проголосовавшего в опросе.

Имя параметра

Обязат.

Тип

Описание

Ограничения

timestamp

Да

integer

ID голоса

—

user

Да

Sender

Проголосовавший пользователь

—

Update

Используется в ответах для описания сообщения в обновлении.

Имя параметра

Обязат.

Тип

Описание

Ограничения

from

Да

Sender

Отправитель сообщения

—

chat

Да

Chat

Чат, в который было отправлено сообщение

—

text

Нет

string

Текст сообщения

—

timestamp

Да

integer

Время отправки сообщения по серверным часам: UNIX timestamp

—

message_id

Да

integer

Идентификатор сообщения в чате

—

update_id

Да

integer

Идентификатор обновления

—

file

Нет

File

Информация о вложенном в сообщение файле

—

images

Нет

Image[]

Информация о картинках

—

bot_request

Нет

BotRequest

Запрос к боту

—

User

Используется в запросах для описания пользователя.

Имя параметра

Обязат.

Тип

Описание

Ограничения

login*

Да

string

Логин пользователя
  • Для аккаунтов на Яндексе (домен yandex.ru) логины могут использоваться без указания домена.
  • Для аккаунтов, созданных на других доменах, указывается полная форма логина <login>@<domain>.

(*) В качестве login может быть также указан адрес рассылки группы или подразделения, тогда в качестве User будет использоваться группа или подразделение.

Предыдущая
Получение обновлений: webhook