Канал Telegram смотрит истории собеседников и публикует свои: фото или видео с подписью, на сутки или в «Публикации» профиля. В MAX, WhatsApp и почте методы историй отвечают 501.
| Метод | Что делает |
|---|---|
| getStories | истории собеседника или свои: активные, «Публикации», архив |
| sendStory | опубликовать свою историю |
| editStory | сменить подпись, файл или аудиторию |
| deleteStory | удалить свои истории |
| pinStory | добавить в «Публикации» профиля или убрать оттуда |
| getStoryViews | кто посмотрел вашу историю и как отреагировал |
Правила
- Чужие истории — незаметно. Gratio получает историю и её файл, но не отмечает просмотр: автор не увидит аккаунт среди зрителей.
- Свои — только по вызову API. Сам Gratio истории не публикует: история появляется, только когда приложение вызвало sendStory.
- Аудитория по умолчанию — контакты. Чтобы история была видна всем, передайте
audience: "everyone".
Есть ли у собеседника активные истории — поле hasStories в getContactInfo.
Объект истории
Так историю отдают getStories и sendStory:
{
"storyId": "2",
"chatId": "8600000001",
"date": 1791823658,
"expiresAt": 1791910058,
"caption": "День открытых дверей в субботу, 11:00",
"media": "photo",
"pinned": false,
"isSelf": true,
"urlFile": "https://api.gratio.net/media/7100000001/8600000001/story-2/0/9b2e…",
"audience": "contacts",
"views": 0,
"reactions": 0
}
| Поле | Тип | Описание |
|---|---|---|
storyId |
string | id истории — для правки, удаления, закрепа и просмотров |
chatId |
string | чья история: id собеседника или аккаунта канала |
date |
integer | когда опубликована, Unix |
expiresAt |
integer или null | когда исчезнет из активных, Unix |
caption |
string | подпись |
media |
string | photo, video, file или none |
pinned |
boolean | в «Публикациях» профиля |
isSelf |
boolean | история аккаунта канала |
urlFile |
string | подписанная ссылка на фото или видео, без токена — см. Файлы и ссылки на них. Нет файла — пустая строка |
audience |
string | кому видна: everyone, contacts, close_friends, selected. Нет поля — Telegram не сообщил |
views |
integer | просмотров — только у своих историй |
reactions |
integer | реакций — только у своих историй |
Аудитория
audience |
Кто видит |
|---|---|
contacts |
контакты аккаунта — по умолчанию |
everyone |
все |
close_friends |
близкие друзья из приложения Telegram |
selected |
только те, кого вы перечислили в allowChatIds |
Лимиты
| Что | Сколько | При превышении |
|---|---|---|
| Срок истории | 24 часа; 6, 12 и 48 часов — с Telegram Premium | другое значение — 400 bad_period |
| Сколько историй можно опубликовать | лимит Telegram: активных, в неделю, в месяц; без Premium ниже | 429 story_limit, Retry-After — если Telegram назвал срок |
| Файл | фото JPEG или PNG, видео MP4 | другой формат — 400 bad_story_media |
Публикация идёт в общем темпе отправки канала — см. Темп и лимиты.
Что дальше
- sendStory — опубликовать историю.
- getStories — посмотреть истории собеседника.
- getStoryViews — кто посмотрел.