> For the complete documentation index, see [llms.txt](https://docs.mikopbx.com/mikopbx/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.mikopbx.com/mikopbx/modules/miko/module-local-speech-to-text/rest-api.md).

# REST API

Получение расшифровок и кратких содержаний звонков из модуля «Локальная транскрибация» через REST API

Модуль отдает готовые расшифровки звонков во внешние системы — CRM, телеграм-бота, корпоративную аналитику. Для этого не нужно обращаться к базе данных АТС: все доступно через несколько простых запросов.

Базовый путь:

```
/pbxcore/api/v3/module-local-speech-to-text
```

## Ключ доступа

1. Откройте в веб-интерфейсе АТС раздел **Система → API-ключи** и создайте новый ключ.
2. В разрешениях ключа оставьте одну строку — чтение `/api/v3/module-local-speech-to-text/call-transcripts`.
3. Передавайте ключ в заголовке каждого запроса:

```bash
Authorization: Bearer ВАШ_КЛЮЧ
```

Запросы с самой АТС (например, от другого установленного модуля) ключа не требуют.

{% hint style="info" %}
Каждый ответ обернут в стандартный конверт: `result` (успех или нет), `data` (сами данные) и `messages` (текст ошибки). Ниже описано содержимое `data`.
{% endhint %}

## Диалог звонка

Самый частый сценарий — получить готовый диалог по идентификатору звонка. Подойдет `linkedid` звонка или `UNIQUEID` любой его записанной части (виден в журнале звонков и в имени файла записи):

```bash
curl -H "Authorization: Bearer ВАШ_КЛЮЧ" \
  "https://адрес-атс/pbxcore/api/v3/module-local-speech-to-text/call-transcripts/mikopbx-1791275140.999663_claea922:dialog"
```

Ответ всегда содержит самую свежую опубликованную версию расшифровки:

* `turns` — реплики диалога: `text`, время `start_ms`/`end_ms`, канал `channel` и говорящий `speaker` (`client` или `employee`) с именем сотрудника `speaker_name`;
* `text` — весь диалог одним текстом, каждая строка начинается с имени говорящего;
* `direction` — направление звонка: `incoming`, `outgoing` или `internal`;
* `language` — язык разговора.

Если звонок еще не расшифрован, придет ответ `404` с кодом `call_transcript_not_found`.

## Краткое содержание

```bash
curl -H "Authorization: Bearer ВАШ_КЛЮЧ" \
  "https://адрес-атс/pbxcore/api/v3/module-local-speech-to-text/call-transcripts/mikopbx-1791275140.999663_claea922:summary"
```

Возвращает одно краткое содержание на весь звонок: тему `topic`, текст `summary`, модель `model` и время готовности `finished_at`. Поле `status` подсказывает, что с содержанием делать:

| Статус        | Значение                                                        |
| ------------- | --------------------------------------------------------------- |
| `done`        | Содержание готово.                                              |
| `pending`     | В очереди или еще формируется; повторите запрос позже.          |
| `skipped`     | Разговор слишком короткий, содержания не будет.                 |
| `error`       | Составить содержание не удалось.                                |
| `unavailable` | Суммаризация выключена либо звонок расшифрован до ее включения. |

## Список расшифрованных звонков

```bash
curl -H "Authorization: Bearer ВАШ_КЛЮЧ" \
  "https://адрес-атс/pbxcore/api/v3/module-local-speech-to-text/call-transcripts?limit=50&offset=0&date_from=2026-10-01&date_to=2026-10-31&search=отгрузка"
```

Список отсортирован от новых звонков к старым. Параметры:

* `limit` — сколько записей вернуть (от 1 до 200, по умолчанию 50), `offset` — сколько пропустить;
* `date_from`, `date_to` — период по дате звонка;
* `search` — поиск по тексту расшифровки.

Каждый элемент списка содержит `call_id`, `aggregate_id`, `revision`, дату звонка `call_started_at` и число частей `part_count`, а объект `pagination` — общее количество записей.

## Полная расшифровка

```bash
curl -H "Authorization: Bearer ВАШ_КЛЮЧ" \
  "https://адрес-атс/pbxcore/api/v3/module-local-speech-to-text/call-transcripts/77"
```

Вместо числа можно передать тот же идентификатор звонка, что и для диалога. В ответе:

* `transcript.segments` — все фразы с точными таймкодами внутри звонка и внутри записи;
* `transcript.turns` — фразы, объединенные в реплики по каналу и участнику;
* `transcript.text` — весь текст;
* `part_manifest` — из каких записей собран звонок;
* `revision` и `is_current` — версия расшифровки и является ли она текущей (старую версию можно получить параметром `?revision=N`).

## Событие о новой расшифровке

Чтобы не опрашивать список, подпишитесь на ленту событий:

```bash
curl -H "Authorization: Bearer ВАШ_КЛЮЧ" \
  "https://адрес-атс/pbxcore/api/v3/module-local-speech-to-text/call-transcripts:events?limit=100"
```

* Первый запрос — без параметра `cursor`, он вернет события с самого начала. Сохраняйте `next_cursor` из ответа только после успешной обработки всех полученных событий и передавайте его в следующем запросе.
* `call-transcript.completed` и `call-transcript.updated` — звонок расшифрован или расшифровка обновлена; после них запрашивайте диалог или полную расшифровку.
* `include_deleted=true` — добавит события `call-transcript.deleted` с причиной удаления: `manual` (удалено администратором) или `retention` (истек срок хранения).
* `include_summaries=true` — добавит события `call-summary.completed` о готовности краткого содержания.

## Идентификаторы

* `call_id` — постоянный идентификатор звонка в АТС (`linkedid`); для поиска подходит и `UNIQUEID` записанной части.
* `aggregate_id` — номер расшифровки звонка в модуле.
* `source_instance_id` — постоянный идентификатор этого набора данных модуля; сохраняйте его в интеграционной системе, чтобы после переустановки модуля не обрабатывать одни и те же звонки заново.
* `contract_version` — версия формата ответов (сейчас `4`).

{% hint style="info" %}
Остальные возможности API модуля (управление заданиями и обработчиками) служебные: они нужны веб-интерфейсу модуля и приложениям-обработчикам. Для интеграций предназначены только запросы, описанные выше.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.mikopbx.com/mikopbx/modules/miko/module-local-speech-to-text/rest-api.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
