# Локальний REST API

> Дозвольте іншим програмам на цьому комп'ютері керувати телефоном — здійснювати виклики й керувати ними, читати контакти, історію та облікові записи.

AI Softphone має REST API для CTI-інтеграції: програма на тому самому комп'ютері може здійснювати виклики й керувати ними, читати контакти, історію викликів і SIP-облікові записи, а також стежити за поточними викликами. Без SDK, без хмарного посередника і без слухача, відкритого в мережу. Запити й відповіді — у JSON, тож досить `curl` або будь-якого HTTP-клієнта.

Після встановлення API **вимкнено**; ніщо не слухає, доки ви його не ввімкнете. Після цього він слухає лише на інтерфейсі loopback — *невеликий вебінтерфейс, що відповідає лише цьому комп'ютеру*, — і до нього не можна дістатися з офісної мережі, через VPN чи з іншого комп'ютера.

Використовуйте API, коли вашій програмі потрібні дані з телефона або треба керувати викликом. Використовуйте [вебхуки](https://docs.ai-softphone.com/uk/integration/webhooks/index.md), коли вона має реагувати на виклики в міру того, як вони відбуваються, без опитування. Більшість інтеграцій використовують і те, й інше; вони незалежні одне від одного.

## Як його ввімкнути {#turning-it-on}

Відкрийте **Налаштування → Інтеграція** і перейдіть до **Локальне керування**.

![Налаштування → Інтеграція: локальне керування](https://docs.ai-softphone.com/screenshots/macos/uk/17b_settings_integration_scrolled.png)

1. Увімкніть **Дозволити іншим програмам на цьому комп'ютері керувати телефоном**. Сервер запускається одразу.
2. Залиште типовий **Порт**, `8377`, якщо його вже не використовує інша програма.
3. За бажанням задайте **Токен**. Після збереження поле показує *Збережено — введіть, щоб замінити*.
4. У розділі **Доступ** виберіть групи, які відкрити: **Контакти**, **Історія викликів**, **Виклики і керування ними**, **Облікові записи**, **Налаштування**, **Лічильники** (метрики). Вимкнена група не фільтрується, а взагалі не обслуговується.
5. Перевірте: `curl http://127.0.0.1:8377/accounts`. Якщо відповідь — JSON, API працює.

Жодної окремої служби не встановлюється, і перезапуск не потрібен. Частину програми, яка це робить, можна вимкнути в [Модулях](https://docs.ai-softphone.com/uk/application/modules/index.md) (**Інтеграція**).

## Власна сторінка API {#the-apis-own-page}

**Відкрити власну сторінку API** відкриває `http://127.0.0.1:8377` у браузері. Ця адреса відповідає переліком усього, що вона обслуговує, англійською мовою; адреси, що щось читають, — це посилання, за якими можна перейти.

![Власна сторінка API, http://127.0.0.1:8377/, відкрита в браузері](https://docs.ai-softphone.com/screenshots/macos/uk/23_api_page.png)

## Доступ і токен {#access-and-the-token}

Що може робити програма, залежить від того, чи змінює вона збережені дані, а не від того, чи вона читає:

- **Без токена** будь-яка програма на комп'ютері може читати все в увімкнених групах і керувати викликами: здійснювати, відповідати, класти слухавку, утримувати, відновлювати, переадресовувати і надсилати DTMF.
- **З токеном** у заголовку `Authorization` вона може також використовувати [кінцеві точки, що змінюють збережене](#endpoints-that-need-the-token). Без токена ці кінцеві точки не наводяться на власній сторінці API і відповідають `401`. Якщо токен не задано зовсім, збережене не може змінити ніщо.

Токен зберігається у сховищі ключів комп'ютера, а не у файлі налаштувань, і ніколи не повертається через `/settings`.

:::caution
Без токена будь-яка програма, що працює на цьому комп'ютері, може керувати телефоном, зокрема відповідати на виклики. На особистій робочій станції це зазвичай прийнятно. На спільному чи керованому комп'ютері задайте токен і поводьтеся з ним як з будь-яким іншим паролем. Токен захищає лише запити, що змінюють збережені дані, але не виклики: щоб інші програми не могли керувати викликами, вимкніть групу **Виклики і керування ними** у розділі **Доступ**.
:::

## Кінцеві точки {#endpoints}

Базова адреса — `http://127.0.0.1:8377`. Кінцевим точкам, наведеним нижче, токен не потрібен.

| Метод | Шлях | Що робить |
| --- | --- | --- |
| GET | `/metrics` | Лічильники у форматі Prometheus. |
| GET | `/ui` | Список записів у вигляді HTML-сторінки. |
| GET | `/ui/recordings/{id}` | Запис із його розшифровкою у вигляді HTML-сторінки. |
| GET | `/ui/recordings/{id}/audio` | Звук для сторінки вище. |
| GET | `/contacts` | Контакти. |
| GET | `/contacts/{id}` | Один контакт. |
| GET | `/history` | Журнал викликів, від найновіших. Приймає `?limit=`, `?missed=true` і `?declined=true`. |
| GET | `/calls` | Поточні виклики. |
| POST | `/calls` | Здійснює виклик: `{"number": "...", "account_id": "..."}`. |
| POST | `/calls/{id}/answer` | Відповідає на виклик. |
| POST | `/calls/{id}/hangup` | Кладе слухавку. |
| POST | `/calls/{id}/hold` | Ставить виклик на утримання. |
| POST | `/calls/{id}/resume` | Знімає його з утримання. |
| POST | `/calls/{id}/dtmf` | Надсилає тони: `{"digits": "..."}`. |
| POST | `/calls/{id}/transfer` | Переадресовує виклик: `{"target": "..."}`. |
| GET | `/accounts` | SIP-облікові записи та стан їх реєстрації. Ніколи — пароль. |
| GET | `/settings` | Уся конфігурація, без секретів. |
| GET | `/taxonomy` | Категорії, мітки й червоні прапорці з їхніми кодами. |

### Кінцеві точки, яким потрібен токен {#endpoints-that-need-the-token}

Вони змінюють збережене, тож кожен запит має нести токен у заголовку `Authorization`. Власна сторінка API показує їх лише запиту, що його несе.

| Метод | Шлях | Що робить |
| --- | --- | --- |
| POST | `/contacts` | Додає контакт: `{"name": "...", "number": "...", "account_id": "..."}`; `account_id` необов'язковий. |
| PUT | `/contacts/{id}` | Замінює контакт. |
| DELETE | `/contacts/{id}` | Вилучає контакт. |
| DELETE | `/history/{id}` | Забуває один виклик із журналу викликів. |
| DELETE | `/history` | Забуває весь журнал викликів. Скасувати це неможливо. |
| PUT | `/accounts/{id}` | Замінює налаштування облікового запису. Пароля серед них немає. |
| PUT | `/settings` | Замінює налаштування. |

Кожен ідентифікатор — це UUID, виданий телефоном: `id` виклику береться з `/calls` або з відповіді на `POST /calls`, `id` облікового запису — з `/accounts`.

Назви полів записано в snake_case, а закінчення вказує на тип: `_id` — посилання на UUID, `_ts` — момент у мілісекундах Unix (UTC), `_s` — тривалість у секундах. Те саме стосується вебхуків; лише `/settings` зберігає власні назви. У REST API ці значення є числами JSON, а невідомий момент — `null`.

## Приклад: здійснення виклику {#example-placing-a-call}

`POST /calls` здійснює вихідний виклик. Тіло — JSON із номером `number`, який треба набрати, і, за бажанням, `account_id` облікового запису, з якого дзвонити:

```bash
curl --location 'http://127.0.0.1:8377/calls' \
--header 'Content-Type: application/json' \
--data '{
    "number": "1020",
    "account_id": "0d7a4c52-6f2e-4a51-8f46-7d9a3e1b2c90"
}'
```

Відповідь — ідентифікатор нового виклику:

```json
{ "id": "9a3e5c71-2d48-4b6f-8e10-3c5f7a1b9d24" }
```

- `number` обов'язковий. Без нього відповідь — `400 {"error":"a call needs a number"}`, і нічого не набирається.
- Номер доповнюється на вибраному обліковому записі так само, як його доповнює набирач: `1020` надсилається як `sip:1020@pbx.example.com`. `POST /calls/{id}/transfer` доповнює свій `target` так само; ціль, яка вже має схему або `@`, надсилається як є.
- `account_id` необов'язковий; візьміть його з `GET /accounts`. Без нього виклик іде з облікового запису, вибраного в головному вікні.
- Використовуйте `id` у `/calls/{id}/…`: `hangup`, `hold`, `resume`, `dtmf` і `transfer`. [Вебхуки](https://docs.ai-softphone.com/uk/integration/webhooks/index.md#an-outgoing-call-event-by-event) цього виклику мають той самий `id`.

### З вебсторінки: дзвінок одним клацанням {#from-a-web-page-click-to-call}

Сторінка, яка звертається до `127.0.0.1`, потрапляє на комп'ютер, де працює браузер, — той самий, де працює телефон, — тож кнопці дзвінка одним клацанням у CRM не потрібен власний сервер:

```javascript
async function dial(number) {
  const r = await fetch("http://127.0.0.1:8377/calls", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ number }),
  });
  if (!r.ok) console.warn("softphone:", (await r.json()).error);
}
```

## Що містять відповіді {#what-the-answers-contain}

### Поточні виклики: `GET /calls` {#calls-in-progress-get-calls}

Кожен виклик має свої `id`, `seance_id`, `account_id`, `direction`, `state`, `number`, `name`, `uri`, `dialed`, `muted`, `event_ts`, `callstart_ts` і `callstate_ts`.

- `state` має значення `dialing`, `ringing-out`, `ringing-in`, `active`, `hold` (утримується цим телефоном), `onhold` (утримується іншою стороною), `conference` або `ended`. Коли підходить більше одного, `conference` переважає `hold`, а `hold` — `onhold`.
- `muted` показує, чи вимкнено мікрофон у виклику; вимкнення мікрофона не змінює `state`.
- `seance_id` — це розмова: виклики, пов'язані переадресацією, консультацією чи конференцією, мають спільний `seance_id`.
- `event_ts` — це момент, коли сформовано відповідь. Порівняйте його з `callstate_ts`, щоб побачити, скільки часу виклик перебуває у своєму стані, не покладаючись на власний годинник.

### Облікові записи: `GET /accounts` {#accounts-get-accounts}

Кожен обліковий запис має свій `id` (усюди в інших місцях це `account_id`), свої налаштування — `transport` (`udp`, `tcp` або `tls`), `port`, `registrar`, `outbound_proxy`, `expiry_s` та інші, — ознаку `enabled` і свій `state` на АТС: `registered`, поки лінія працює. Паролі ніколи не включаються.

### Історія викликів: `GET /history` {#call-history-get-history}

Від найновіших, 100 записів, якщо `?limit=` не вказує інакше. `?missed=true` повертає лише пропущені виклики, `?declined=true` — лише виклики, які відхилив цей телефон.

| Поле | Значення |
| --- | --- |
| `id` | Власний ідентифікатор запису історії. Це не `id` виклику з `/calls` і вебхуків; їх пов'язує `seance_id`. |
| `outcome` | Основна класифікація: `answered`, `missed`, `declined` або `failed`. |
| `answered` | `true` або `false`. |
| `duration_s` | `0` для виклику, який так і не з'єднався. |
| `number`, `uri` | Інша сторона — як номер і як SIP-адреса. |
| `name` | З Контактів, якщо номер відомий, інакше порожнє. Зіставляйте за `number`, а не за цим полем. |
| `dialed` | Набрані цифри для вихідного виклику; порожнє для вхідного. |
| `account`, `account_id` | Лінія, на якій був виклик. |
| `reason` | Як він завершився: `local-hangup`, `remote-hangup`, `cancelled`… |
| `answered_by` | `no`, якщо на виклик відповіла людина; інакше — те, що на нього відповіло. |

### Контакти: `GET /contacts` {#contacts-get-contacts}

Кожен контакт має свої `id`, `name`, `number` і лінію, до якої належить, — `account_id` і `account`; порожній `account` означає, що контакт не прив'язаний до лінії.

### Записи {#recordings}

Записи й розшифровки не видаються у вигляді JSON. API обслуговує їх як HTML-сторінки, `/ui` і `/ui/recordings/{id}`: посилайтеся на ці сторінки з вашої CRM, замість того щоб переносити звук. Посилання відкривається на комп'ютері, що зберігає запис, і звук ніколи його не залишає.

## Таксономія і налаштування {#taxonomy-and-settings}

Кожен запис `/taxonomy` має сталий `code`, `title` і `description` мовою інтерфейсу, `kind` (`category`, `tag` або `red_flag`), а для червоних прапорців — ще й `severity`. **Зіставляйте за `code`, ніколи — за `title`**: назви надходять тією мовою, на яку налаштовано телефон. Запис із `retired: true` зберігається, щоб давніші виклики й надалі розпізнавалися; новим викликам його більше не призначають. Завантажте таксономію один раз під час запуску, щоб зіставити слова телефона з вашими власними полями.

`/settings` повертає конфігурацію, крім секретів: звукові пристрої та гучність, пріоритет кодеків, вигляд і мову, запуск, клавіатурні скорочення, рівень діагностики і стан обох інтеграцій, — це корисно для інструмента підтримки, який має перевірити робочу станцію без демонстрації екрана. `api.disabled` перелічує вимкнені групи доступу, а `webhooks.silenced` — вимкнені події; порожні списки означають, що ввімкнено все. Він ніколи не містить пароля SIP, токена API чи значення заголовка вебхука.

## Помилки {#errors}

Кожна помилка — це JSON з єдиним ключем `error`, призначеним для людей, а не для розбору програмою.

| Статус | Тіло | Значення |
| --- | --- | --- |
| 404 | `{"error":"no such endpoint"}` | Шлях не існує або його групу доступу вимкнено; в обох випадках відповідь навмисно однакова. |
| 405 | `{"error":"that endpoint does not take this method"}` | Шлях існує, але цього методу не приймає: наприклад, `POST /settings` замість `PUT`. |
| 401 | `{"error":"writing needs a token, and none is configured"}` | Кінцева точка, що змінює збережене, на телефоні, де поле **Токен** порожнє. Заповніть його в розділі **Локальне керування**. |
| 401 | `{"error":"this endpoint needs the authorization token"}` | Кінцева точка, що змінює збережене, без правильного токена. |
| 404 | `{"error":"no contact with that id"}` | Шлях правильний, а ідентифікатор — ні. |
| 400 | `{"error":"no call with that id"}` | Виклик завершився або ніколи не існував. |
| 400 | `{"error":"a call needs a number"}` | `POST /calls` без номера. Нічого не набрано. |
| 400 | `{"error":"no digits to send"}` | `POST /calls/{id}/dtmf` без цифр. |
| 400 | `{"error":"a transfer needs a target"}` | `POST /calls/{id}/transfer` без цілі. |
| 400 | `{"error":"the account this call is on is no longer set up"}` | Обліковий запис виклику видалили під час виклику, тож ціль неможливо доповнити. На АТС нічого не надіслано. |

Відхилені запити рахуються в `api_requests_refused_total`, тож інтеграція, яка тихо не працює, видна в метриках, а не лише у ваших власних журналах.

## Метрики {#metrics}

`GET /metrics` повертає кожен лічильник телефона, кожен із довідковим текстом. Збирайте їх Prometheus або читайте вручну.

| Лічильник | Що рахує |
| --- | --- |
| `calls_incoming_total` | Отримані вхідні виклики. |
| `calls_outgoing_total` | Здійснені вихідні виклики. |
| `calls_answered_total` | Виклики, на які відповіли. |
| `calls_missed_total` | Вхідні виклики, на які не відповіли. |
| `calls_declined_total` | Виклики, відхилені тут або іншою стороною. |
| `calls_failed_total` | Виклики, які не вдалося встановити. |
| `registrations_succeeded_total` | Успішні SIP-реєстрації. |
| `registrations_failed_total` | SIP-реєстрації, відхилені або завершені за тайм-аутом. |
| `webhooks_delivered_total` | Вебхуки, які прийняв одержувач. |
| `webhooks_failed_total` | Вебхуки, відхилені або не доставлені. |
| `webhooks_dropped_total` | Вебхуки, викинуті через переповнену чергу. |
| `api_requests_total` | Запити, оброблені API. |
| `api_requests_refused_total` | Відхилені запити: хибний токен, вимкнена група або невідомий шлях. |

## Оновлення давнішої інтеграції {#updating-an-older-integration}

Давніші версії використовували назви в camelCase і короткі ідентифікатори. `accountId` тепер `account_id`, `startedAt` — `callstart_ts`, `durationSeconds` — `duration_s`, `answeredBy` — `answered_by`, а поле вебхука `at` — `event_ts`. Виклики й облікові записи ідентифікуються лише за UUID: `runtimeId` та ідентифікатори на кшталт `call-3` чи `account-2` більше не повертаються і не приймаються.

## Коли не працює {#when-it-does-not-work}

| Симптом | Що перевірити |
| --- | --- |
| У з'єднанні з `127.0.0.1:8377` відмовлено | Локальне керування вимкнено, телефон не запущено або порт змінено. |
| `404 {"error":"no such endpoint"}` для шляху з цієї сторінки | Його групу доступу вимкнено. |
| Читання працює, запис відхиляється з `401` | Кінцевим точкам, що змінюють збережені дані, потрібен токен у заголовку `Authorization`, а на телефоні спершу треба заповнити поле **Токен**. |
| Назви категорій не англійською | Назви йдуть мовою інтерфейсу. Зіставляйте за `code` з `/taxonomy`. |
| Немає `accountId`, `startedAt` чи `at` | Інтеграцію написано для давніших назв; див. вище. |

Якщо проблема з реєстрацією або самим викликом, відкрийте [Діагностику](https://docs.ai-softphone.com/uk/troubleshooting/diagnostics/index.md).
