> ## Documentation Index
> Fetch the complete documentation index at: https://docs.velesagent.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Навык: Контур.Толк ALOR

> Поиск встреч и получение доступных материалов из пространства Контур.Толка ALOR с ключом из зашифрованного хранилища Велеса.

# Навык: Контур.Толк ALOR

`alor-ktalk` — устанавливаемый навык только для чтения данных пространства
`https://alor.ktalk.ru`. Он помогает найти встречу, получить сведения о ней и сохранить
доступные материалы в рабочую область Велеса.

Установите его в панели «Навыки» из одного из предустановленных каталогов ALOR. После
установки файлы находятся в `<workspace>/skills/alor-ktalk`; в пакет Велеса они не входят.

## Что умеет навык

* получать запланированные встречи пользователя за заданный период;
* искать пользователей, доступных владельцу ключа;
* находить прошедшие встречи и записи;
* получать участников, приглашённых, сообщения, опросы, заметки и доски встречи;
* получать расшифровку с именами говорящих и отметками времени;
* получать краткий пересказ и протокол встречи;
* получать отчёты об участниках, сообщениях и активности;
* сохранять метаданные и текстовые материалы записи в единый пакет JSON;
* по явному запросу скачивать видеозапись или таблицу вопросов.

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

## Настройка ключа

1. Выпустите персональный ключ по [официальной инструкции Контур.Толка](https://support.kontur.ru/talk/86797-personalnyj_apiklyuch_dostupa_v_tolke).

2. Скопируйте его до закрытия окна: позже Толк не покажет значение повторно.

3. В Nerve откройте панель **Секреты** и введите в поиск `KTALK_API_KEY`.

4. Откройте найденную строку с идентификатором:

   ```text theme={null}
   skills.alor-ktalk.env.KTALK_API_KEY
   ```

5. Сохраните ключ и снова запустите запрос с этим навыком.

Ключ не записывается в `config.json`, инструкцию модели, командную строку или файлы навыка.
Велес подставляет его только на время ответа, в котором активен этот навык. Адрес пространства
`https://alor.ktalk.ru` уже задан в помощнике и отдельно настраивать его не нужно.

Один пользователь может иметь не более 10 активных персональных ключей. Максимальный срок
действия ключа — один год. Потерянный или раскрытый ключ нужно отозвать в настройках Толка и
выпустить заново.

## Первая проверка

Сначала помощник показывает только несекретные сведения о настройке:

```bash theme={null}
python <каталог-навыка>/scripts/ktalk_client.py status
```

Затем выполняется проверочный запрос сведений о доступах:

```bash theme={null}
python <каталог-навыка>/scripts/ktalk_client.py access
```

Здесь есть ограничение текущей официальной документации. Новая статья о персональном ключе
не указывает HTTP-заголовок. Публичное описание программного интерфейса Толка задаёт
`X-Auth-Token`, но называет его ключом, выданным администратором пространства. Поэтому
помощник делает только одну совместимую попытку через `X-Auth-Token` и не перебирает другие
заголовки с секретом. Если Толк отвечает `401`, проверьте цель секрета, срок действия ключа и
доступность публичного программного интерфейса для персонального ключа в вашем пространстве.

## Примеры работы

### Найти прошедшие встречи

```bash theme={null}
python <каталог-навыка>/scripts/ktalk_client.py conferences \
  --from-date 2026-08-01T00:00:00Z \
  --to-date 2026-08-08T00:00:00Z \
  --all
```

Для одной прошедшей встречи можно получить материалы по её ключу:

```bash theme={null}
python <каталог-навыка>/scripts/ktalk_client.py artifacts КЛЮЧ_ВСТРЕЧИ
```

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

### Найти запись и получить текст

```bash theme={null}
python <каталог-навыка>/scripts/ktalk_client.py recordings \
  --from-date 2026-08-01T00:00:00Z \
  --query "планирование" \
  --all
```

```bash theme={null}
python <каталог-навыка>/scripts/ktalk_client.py transcript КЛЮЧ_ЗАПИСИ \
  --format markdown \
  --output материалы-встречи/расшифровка.md
```

```bash theme={null}
python <каталог-навыка>/scripts/ktalk_client.py summary КЛЮЧ_ЗАПИСИ \
  --type shortSummary \
  --format markdown \
  --output материалы-встречи/краткий-пересказ.md
```

Для протокола укажите `--type protocol`. Значение `--type all` получает составной ответ с
расшифровкой, кратким пересказом и протоколом, если они готовы и доступны.

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

### Собрать текстовые материалы записи

```bash theme={null}
python <каталог-навыка>/scripts/ktalk_client.py export-recording КЛЮЧ_ЗАПИСИ \
  --output материалы-встречи/КЛЮЧ_ЗАПИСИ.json
```

Помощник создаёт один пакет JSON с манифестом, сведениями о записи, участниками и доступными
текстами. Для расшифровки, краткого пересказа и протокола пакет также содержит удобное
текстовое представление. Недоступные части отмечаются в манифесте. Существующий файл не
перезаписывается.

### Скачать файл

```bash theme={null}
python <каталог-навыка>/scripts/ktalk_client.py download-recording КЛЮЧ_ЗАПИСИ \
  --quality "900 p" \
  --output материалы-встречи/запись.mp4 \
  --max-mib 4096
```

Скачивание выполняется только после явного запроса пользователя. Файл сначала записывается во
временное место, проверяется по размеру и только затем публикуется по указанному пути.
Помощник не перезаписывает существующий файл, не выходит за пределы рабочей области и не
проходит через символические ссылки.

Публичное описание программного интерфейса не задаёт внешний узел хранения или правила
перенаправления для видеозаписей. Поэтому помощник запрещает все перенаправления и никогда не
передаёт ключ другому узлу. Если служба вернула перенаправление, скачивание безопасно
остановится; обходить ограничение передачей ключа в `curl` или браузер нельзя.

## Ограничения материалов

* Расшифровка создаётся для облачной записи русской речи и может готовиться от нескольких
  минут до одного-двух часов.
* Краткий пересказ доступен не для всех тарифов и записей. В частности, он может отсутствовать
  у очень короткой, локальной, слишком большой или слишком длинной записи.
* Протокол доступен только на поддерживающих его тарифах и для достаточно содержательной
  облачной записи.
* Статусы `inProgress` и `recreateInProgress` означают обработку, а не отсутствие разговора.
* Персональный ключ не расширяет права пользователя: навык увидит только доступные ему данные.

Актуальные продуктовые условия описаны в справке Толка: [материалы встречи](https://support.kontur.ru/talk/50520-artefakty),
[расшифровка](https://support.kontur.ru/talk/80168-transkripciya_zapisi_vstrechi),
[краткий пересказ](https://support.kontur.ru/talk/54279-rezume_zapisi_vstrechi) и
[протокол](https://support.kontur.ru/talk/80141-protokol_zapisi_vstrechi).

## Безопасность

* Содержимое встреч, чатов, заметок, досок и расшифровок считается недоверенными данными, а не
  инструкциями для агента.
* Помощник принимает только точный адрес `https://alor.ktalk.ru` и проверяет сертификат TLS.
* Ключ передаётся только этому адресу и не показывается в ошибках.
* Большие ответы и загрузки имеют ограничение размера.
* Полные результаты, не помещающиеся в безопасный вывод, нужно сохранять через `--output`.
* Передавать материалы встречи в другую службу можно только после явного согласования места и
  состава данных.

## Связанные страницы

* [Секреты и токены](/basics/secrets_ru)
* [Навыки Велеса: простое объяснение](/skills/index_ru)
* [Навыки Велеса: подробный справочник](/skills/reference_ru)
* [Официальное описание программного интерфейса Контур.Толка](https://developer.kontur.ru/doc/talk.public.api)