МТС Линк API: как забирать записи встреч без ручной выгрузки

Сколько шагов проходит запись, прежде чем станет текстом

Запись встречи не лежит в кабинете готовым файлом. Сначала её ставят на конвертацию, потом ждут, потом скачивают mp4 и только потом отправляют на расшифровку — и так с каждой встречей. Пока встреч три в неделю, это привычная рутина; на тридцати появляется резонный вопрос: умеет ли МТС Линк API отдавать записи сам, без похода в кабинет за каждой.

Что МТС Линк API умеет с записями

Работа с записями устроена в три приёма: найти запись, попросить платформу собрать из неё mp4, забрать ссылку на готовый файл. Плюс два метода для текста — если встроенная расшифровка у вас включена. Все адреса начинаются с userapi.mts-link.ru/v3, и в каждый запрос кладётся заголовок x-auth-token.

Первый метод — единственный, где легко промахнуться на ровном месте. У списка записей параметр from обязателен по смыслу: без него выборка идёт от текущей даты и времени, то есть возвращает пустоту, а разработчик полчаса ищет ошибку в авторизации. Рядом живут period (day, week, month, year), offset и limit — до 500 записей за запрос при значении по умолчанию 10. Для ночного дозапроса «что появилось за сутки» этого хватает с большим запасом.

Вебхуки: платформа сама говорит, что запись готова

Опрашивать список записей раз в 5 минут — самое частое и самое дорогое решение в такой интеграции. Посчитайте: 24 × 60 ÷ 5 = 288 запросов в сутки, больше 105 000 в год. При тридцати встречах в неделю новую запись покажут около 1 400 из них — примерно 1 %, остальные вернут то же, что и предыдущий. МТС Линк умеет сообщать о событиях сам. Вы регистрируете адрес своего обработчика, выбираете события — и платформа шлёт на него POST с телом в JSON, где всегда есть event (что случилось), occurredAt (когда, в формате ISO 8601) и объект data с идентификаторами.

• eventSession.created — мероприятие создано. Пригодится, чтобы завести карточку встречи у себя заранее, до того как она началась.
• recordFile.ready — онлайн-запись стала доступна. В data приезжают recordId и eventSessionId; с этого события и начинается вся автоматика.
• convertedRecord.ready — конвертация закончена, mp4 собран. В data — convertedRecordId и тот же eventSessionId.
• transcript.ready — готова текстовая расшифровка на стороне платформы, в теле приходит transcriptId.
• Плюс события про ход самого мероприятия: старт, завершение, «все участники покинули мероприятие», регистрация участника, отправленное напоминание.

Обработчик стоит открытым в интернет, поэтому каждый хук нужно проверять на подлинность. При создании вебхука задаётся секретная фраза, ею подписывается тело запроса, подпись приезжает в заголовке X-Webhook-Signature, алгоритм — HMAC SHA-256. Вы считаете HMAC от полученного тела своим секретом и сравниваете строки; в справке МТС Линк для этого лежат готовые примеры на PHP, Go, Ruby, JavaScript, TypeScript и Python. Приём универсальный: webhook о готовой расшифровке на нашей стороне подписывается так же и проверяется так же.

Почему mp4 не появляется сам: шаг конвертации

Онлайн-запись и файл mp4 — разные вещи, и это первая заминка почти в каждой интеграции. Событие recordFile.ready говорит только, что запись появилась в кабинете; чтобы получить файл, её надо поставить на конвертацию отдельным запросом. Обработчик, который сразу после первого хука идёт за ссылкой, стабильно получает пустоту и выглядит как «API не работает».

1. Отправьте POST на records/{recordId}/conversions. В ответ придёт идентификатор конвертации — сохраните его рядом с идентификатором встречи, он понадобится на последнем шаге.
2. Выберите качество. Параметр quality принимает 720 или 1080, по умолчанию 720. Для текста больше не нужно: распознаётся звук, а не картинка. Разница в весе считается от битрейта: типичные 1,5 Мбит/с для 720p дают 1 500 000 × 3600 ÷ 8 = 675 МБ за час, а 3 Мбит/с для 1080p — 1,35 ГБ. На тридцати часовых встречах в месяц это 20 ГБ против 40, и весь этот трафик едет через ваш сервер.
3. Выберите раскладку. Параметр view задаёт, что попадёт в кадр: эфир, эфир с чатом, с вопросами, с боковой панелью, с видео ведущего. На расшифровку это не влияет — влияет на вес файла и на то, можно ли будет отдать это видео людям.
4. Не запускайте конвертацию дважды. Если она уже идёт, метод отвечает 403: превышен лимит одновременных конвертаций. Повтор по таймауту делает только хуже — дождитесь события.
5. Проверьте длительность. Записи длиннее 24 часов на конвертацию не принимаются, такую сначала подрезают в кабинете. Для суточных марафонов и вебинарных стримов это не теория.
6. Дождитесь convertedRecord.ready — и только после него идите за ссылкой: методом fileSystem/file/{conversionId} или сразу по встрече, eventsessions/{eventSessionId}/converted-records. Оба отдают downloadUrl.

Как связать выгрузку с расшифровкой: маршрут целиком

Готовый mp4 сам по себе задачу не решает: искать по видео нельзя, читать его нельзя, в протокол он не превращается. Нужен текст — и вторая половина маршрута стыкуется с первой почти дословно, событие в событие. У нас для этого есть API расшифровки аудио и видео: POST с файлом или ссылкой, в ответ идентификатор задачи, на готовность — свой вебхук.

1. Поднимите обработчик. Один эндпоинт, который принимает POST, проверяет подпись и быстро отвечает 2xx. Тяжёлую работу делайте после ответа, а не до него.
2. Зарегистрируйте вебхуки recordFile.ready и convertedRecord.ready, задайте секретную фразу и сохраните её у себя рядом с ключом API.
3. На recordFile.ready ставьте запись на конвертацию и запоминайте пару eventSessionId → conversionId.
4. На convertedRecord.ready идите за downloadUrl — по conversionId или по eventSessionId, как удобнее вашей схеме хранения.
5. Отправьте запись на расшифровку — файлом или ссылкой. В ответ придёт идентификатор задачи, положите его в ту же строку, где лежат идентификаторы встречи.
6. Дождитесь события transcript.completed — в нём тот же идентификатор задачи, по которому забирают результат.
7. Заберите результат в нужном виде: JSON с репликами, спикерами и таймкодами — для системы, DOCX или PDF — для людей, SRT и VTT — если из встречи потом делают видео с субтитрами.

1. Встреча закончиласьплатформа дописывает запись
2. recordFile.readyставим на конвертацию
3. convertedRecord.readyберём ссылку, шлём на расшифровку
4. transcript.completedтекст, протокол и задачи у вас

Отдельно стоит подумать, что вы храните у себя. Минимум — четыре поля в одной строке: eventSessionId, conversionId, идентификатор задачи на расшифровку и статус. Этого достаточно, чтобы через месяц ответить на два вопроса, которые обязательно возникнут: «почему по этой встрече нет текста» и «не отправили ли мы её дважды».

Тариф с разделом API: PRO / Enterprise / Total — ___
Ключ заведён отдельный под интеграцию, не общий с отделами: да / нет
Заголовок x-auth-token уходит во всех запросах: проверено
Секретная фраза вебхука сохранена рядом с ключом: ___
Проверка X-Webhook-Signature (HMAC SHA-256) включена до разбора тела: да / нет
Обработчик отвечает 2xx раньше, чем начинает качать файл: да / нет
Подписки: recordFile.ready, convertedRecord.ready, transcript.ready — ___
Ключ идемпотентности: eventSessionId
Таблица: eventSessionId | conversionId | id задачи расшифровки | статус | дата
Страховка: один ночной GET /v3/records с параметром from за прошедшие сутки
Мониторим: ответы 403 от API и встречи без текста старше 24 часов
Кому приходит письмо, когда сутки без текста: ___

Что приходит на выходе, кроме видеофайла

На этом месте автоматизация обычно и оправдывает себя. Из записи получается не одна простыня текста, а несколько документов разного назначения — и все они появляются раньше, чем участники успевают дойти до следующей встречи.

Разделение спикеров здесь идёт по голосу, а не по учётным записям, — и это важнее, чем кажется. На встречах в переговорке с одного ноутбука сидит полкоманды, а гости часто заходят по ссылке без имени; для платформы это один участник, для расшифровки — три разных голоса.

У самой платформы расшифровка тоже есть, но доступна она не всем и не в каждом формате мероприятия — где её включить и почему она иногда не появляется, разобрано отдельно: встроенная расшифровка встречи в МТС Линк. Если она у вас работает, забирать её можно тем же способом, вебхуком transcript.ready и методом transcript/{transcriptId}: в ответе придут реплики с именем участника и временем плюс объект summary со своим статусом — inProgress, completed или failed.

Пять мест, где связка ломается

Сама интеграция несложная, но ломается она предсказуемо и всегда тихо: никто не падает с ошибкой, просто в один день текст перестаёт приходить, а замечают это через неделю на планёрке. Пять типовых причин, по которым стоит пройтись до того, как что-то встанет.

1. 403 на ровном месте. Ключ работает от имени владельца аккаунта: сменился тариф — API молча закрылся. Первым делом проверяют не код, а раздел API в кабинете.
2. Пустой список записей. Забытый параметр from — и выборка идёт от текущего момента. Ответ формально успешный, записей ноль.
3. Повторная конвертация. Второй POST по той же записи вернёт 403, потому что первая ещё идёт. Ретрай по таймауту здесь не помогает, помогает ожидание события.
4. Дубли вебхуков. Один и тот же хук может прийти дважды — это норма для любой доставки «хотя бы один раз», а не сбой. Обработчик должен быть идемпотентным.
5. Медленный ответ обработчика. Если вы качаете часовое видео до того, как ответили 2xx, обработчик рискует не уложиться в таймаут отправителя — и тогда тот же хук прилетает снова, а вы качаете видео второй раз. Сначала ответ, потом работа.

Если ключа API нет: тот же маршрут вручную

Раздел API появляется не на всех тарифах, и это не повод отказываться от текста встреч. Ручной маршрут короче, чем кажется, и на нём же обкатывают весь сценарий, прежде чем звать разработчика.

• Поставьте запись на конвертацию в кабинете и заберите файл — порядок действий, сроки хранения и типичные ошибки собраны в отдельном разборе: скачать запись встречи из МТС Линк вручную.
• Не скачивайте, если можно не скачивать: запись, доступную по прямой ссылке, сервис забирает сам — остаётся вставить адрес.
• Проверьте, что вы получите на выходе, на одной настоящей встрече: текст встречи из МТС Линк с протоколом и задачами собирается за несколько минут и без карты.

Цена ручного маршрута считается прямо по этой таблице. 5 минут на встречу при 30 встречах в неделю — это 150 минут, 2,5 часа в неделю и около 115 часов в год: почти три рабочие недели, потраченные на конвертацию и перекладывание файлов. День работы разработчика на верхней строке окупается на втором месяце.

Порог, за которым автоматизацию стоит собирать всерьёз, у всех свой, но ориентир простой: как только одинаковый маршрут повторяется чаще пяти раз в неделю, ручные шаги начинают теряться — не потому, что люди небрежны, а потому, что встреча заканчивается ровно тогда, когда все спешат на следующую.

Частые вопросы

Проверено 14 августа 2026 по базе знаний МТС Линк, раздел «API и Webhooks»: «Интеграция API. С чего начать» (ключ, заголовок x-auth-token, тарифы PRO / Enterprise / Total), «Получить список онлайн-записей» (параметры from, period, offset, limit), «Поставить запись на конвертацию» (quality, view, ограничение на 24 часа и ответ 403 при повторном запуске), «Получить сконвертированную запись, используя EventsessionID» и «Скачать готовую MP4-запись» (downloadUrl), «Выгрузить список текстовых расшифровок» и «Выгрузить саммаризацию и текстовую расшифровку», описания вебхуков recordFile.ready, convertedRecord.ready, transcript.ready и eventSession.created, а также «Webhooks. Проверка достоверности хука» (заголовок X-Webhook-Signature, HMAC SHA-256).