Отправка альбома по идентификаторам
Метод позволяет отправлять альбом из ранее загруженных изображений в приватные или групповые чаты по их идентификаторам (file_id), без повторной загрузки содержимого файлов. Идентификаторы изображений можно получить из обновлений или из ответа метода отправки альбома.
Важно
В обновлениях помимо оригинала приходят версии изображений в других разрешениях (с ?size= в file_id) — для отправки нужно использовать file_id именно оригинала.
HTTP метод: POST
URL: https://botapi.messenger.yandex.net/bot/v1/messages/shareGallery/
Заголовки
Authorization: OAuth <токен>
Content-Type: application/json
Тело запроса (JSON)
| Имя параметра | Обязательный | Тип | Описание | Ограничения, значение по умолчанию |
|---|---|---|---|---|
chat_id |
Нет* | string |
ID чата, в который нужно отправить альбом | Бот должен состоять в чате |
login |
Нет* | string |
Логин пользователя, которому нужно отправить альбом | Бот должен состоять в чате |
images |
Да | object[] |
Массив изображений для отправки | От 1 до 10 изображений |
images[].file_id |
Да | string |
Идентификатор ранее загруженного изображения. Значение можно взять из поля file_id объекта Image в обновлении или из ответа метода отправки альбома |
— |
images[].width |
Да | integer |
Ширина изображения в пикселях. Значение можно взять из поля width объекта Image в обновлении или из ответа метода отправки альбома |
— |
images[].height |
Да | integer |
Высота изображения в пикселях. Значение можно взять из поля height объекта Image в обновлении или из ответа метода отправки альбома |
— |
text |
Нет | string |
Текст сообщения | Не более 6 000 символов |
thread_id |
Нет | integer |
Идентификатор треда (timestamp сообщения) | — |
message_id |
Нет | integer |
ID сообщения для редактирования | Сообщение должно быть из того же чата |
reply_message_id |
Нет | integer |
ID сообщения, на которое будет ответ | Сообщение должно быть из того же чата |
suggest_buttons |
Нет | SuggestButtons | Клавиатура с кнопками под сообщением | Не более 100 кнопок |
(*) Параметры chat_id и login являются необязательными, но необходимо заполнить хотя бы один из двух:
- При заполнении
chat_idальбом будет отправлен в групповой чат, заданный этим ID. - При заполнении
loginальбом будет отправлен пользователю в приватный чат.
Ограничения
Ограничения аналогичны ограничениям для метода отправки текстового сообщения.
Результат
Результатом успешного запроса является ответ с кодом 200 и телом с JSON, где содержится информация об отправленном альбоме.
| Имя параметра | Обязательный | Тип | Описание |
|---|---|---|---|
ok |
Да | boolean |
Флаг успешности выполнения |
message_id |
Да | integer |
ID сообщения в чате |
images |
Да | object[] |
Массив с информацией об отправленных изображениях |
Каждый элемент массива images содержит следующие поля:
| Имя параметра | Обязательный | Тип | Описание |
|---|---|---|---|
file_id |
Да | string |
Идентификатор загруженного файла |
width |
Да | integer |
Ширина изображения в пикселях |
height |
Да | integer |
Высота изображения в пикселях |
В случае ошибки возвращается соответствующий статус HTTP. Описание ошибки приходит в поле description.
| Имя параметра | Обязательный | Тип | Описание |
|---|---|---|---|
ok |
Да | boolean |
Флаг успешности выполнения |
description |
Да | string |
Описание ошибки |
Пример запроса
curl -X POST -H 'Authorization: OAuth AtXXXXXXXXXXX' -H "Content-Type: application/json" -d '{"login":"vasya@example.org", "images": [{"file_id": "<file_id_1>", "width": 1920, "height": 1080}, {"file_id": "<file_id_2>", "width": 1280, "height": 720}]}' 'https://botapi.messenger.yandex.net/bot/v1/messages/shareGallery/'
Пример успешного ответа
{"ok": true, "message_id": 1647523230504005, "images": [{"file_id": "<new_file_id_1>", "width": 1920, "height": 1080}, {"file_id": "<new_file_id_2>", "width": 1280, "height": 720}]}
Пример ответа с ошибкой
{"ok": false, "description": "Bot is not a member of the chat"}