Локальний REST API
AI Softphone має REST API для CTI-інтеграції: програма на тому самому комп'ютері може здійснювати виклики й керувати ними, читати контакти, історію викликів і SIP-облікові записи, а також стежити за поточними викликами. Без SDK, без хмарного посередника і без слухача, відкритого в мережу. Запити й відповіді — у JSON, тож досить curl або будь-якого HTTP-клієнта.
Після встановлення API вимкнено; ніщо не слухає, доки ви його не ввімкнете. Після цього він слухає лише на інтерфейсі loopback — невеликий вебінтерфейс, що відповідає лише цьому комп'ютеру, — і до нього не можна дістатися з офісної мережі, через VPN чи з іншого комп'ютера.
Використовуйте API, коли вашій програмі потрібні дані з телефона або треба керувати викликом. Використовуйте вебхуки, коли вона має реагувати на виклики в міру того, як вони відбуваються, без опитування. Більшість інтеграцій використовують і те, й інше; вони незалежні одне від одного.
Як його ввімкнути
Відкрийте Налаштування → Інтеграція і перейдіть до Локальне керування.
- Увімкніть Дозволити іншим програмам на цьому комп'ютері керувати телефоном. Сервер запускається одразу.
- Залиште типовий Порт,
8377, якщо його вже не використовує інша програма. - За бажанням задайте Токен. Після збереження поле показує Збережено — введіть, щоб замінити.
- У розділі Доступ виберіть групи, які відкрити: Контакти, Історія викликів, Виклики і керування ними, Облікові записи, Налаштування, Лічильники (метрики). Вимкнена група не фільтрується, а взагалі не обслуговується.
- Перевірте:
curl http://127.0.0.1:8377/accounts. Якщо відповідь — JSON, API працює.
Жодної окремої служби не встановлюється, і перезапуск не потрібен. Частину програми, яка це робить, можна вимкнути в Модулях (Інтеграція).
Власна сторінка API
Відкрити власну сторінку API відкриває http://127.0.0.1:8377 у браузері. Ця адреса відповідає переліком усього, що вона обслуговує, англійською мовою; адреси, що щось читають, — це посилання, за якими можна перейти.
Доступ і токен
Що може робити програма, залежить від того, чи змінює вона збережені дані, а не від того, чи вона читає:
- Без токена будь-яка програма на комп'ютері може читати все в увімкнених групах і керувати викликами: здійснювати, відповідати, класти слухавку, утримувати, відновлювати, переадресовувати і надсилати DTMF.
- З токеном у заголовку
Authorizationвона може також використовувати кінцеві точки, що змінюють збережене. Без токена ці кінцеві точки не наводяться на власній сторінці API і відповідають401. Якщо токен не задано зовсім, збережене не може змінити ніщо.
Токен зберігається у сховищі ключів комп'ютера, а не у файлі налаштувань, і ніколи не повертається через /settings.
Без токена будь-яка програма, що працює на цьому комп'ютері, може керувати телефоном, зокрема відповідати на виклики. На особистій робочій станції це зазвичай прийнятно. На спільному чи керованому комп'ютері задайте токен і поводьтеся з ним як з будь-яким іншим паролем. Токен захищає лише запити, що змінюють збережені дані, але не виклики: щоб інші програми не могли керувати викликами, вимкніть групу Виклики і керування ними у розділі Доступ.
Кінцеві точки
Базова адреса — 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 | Категорії, мітки й червоні прапорці з їхніми кодами. |
Кінцеві точки, яким потрібен токен
Вони змінюють збережене, тож кожен запит має нести токен у заголовку 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.
Приклад: здійснення виклику
POST /calls здійснює вихідний виклик. Тіло — JSON із номером number, який треба набрати, і, за бажанням, account_id облікового запису, з якого дзвонити:
curl --location 'http://127.0.0.1:8377/calls' \
--header 'Content-Type: application/json' \
--data '{
"number": "1020",
"account_id": "0d7a4c52-6f2e-4a51-8f46-7d9a3e1b2c90"
}'
Відповідь — ідентифікатор нового виклику:
{ "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. Вебхуки цього виклику мають той самийid.
З вебсторінки: дзвінок одним клацанням
Сторінка, яка звертається до 127.0.0.1, потрапляє на комп'ютер, де працює браузер, — той самий, де працює телефон, — тож кнопці дзвінка одним клацанням у CRM не потрібен власний сервер:
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);
}
Що містять відповіді
Поточні виклики: 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
Кожен обліковий запис має свій id (усюди в інших місцях це account_id), свої налаштування — transport (udp, tcp або tls), port, registrar, outbound_proxy, expiry_s та інші, — ознаку enabled і свій state на АТС: registered, поки лінія працює. Паролі ніколи не включаються.
Історія викликів: 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
Кожен контакт має свої id, name, number і лінію, до якої належить, — account_id і account; порожній account означає, що контакт не прив'язаний до лінії.
Записи
Записи й розшифровки не видаються у вигляді JSON. API обслуговує їх як HTML-сторінки, /ui і /ui/recordings/{id}: посилайтеся на ці сторінки з вашої CRM, замість того щоб переносити звук. Посилання відкривається на комп'ютері, що зберігає запис, і звук ніколи його не залишає.
Таксономія і налаштування
Кожен запис /taxonomy має сталий code, title і description мовою інтерфейсу, kind (category, tag або red_flag), а для червоних прапорців — ще й severity. Зіставляйте за code, ніколи — за title: назви надходять тією мовою, на яку налаштовано телефон. Запис із retired: true зберігається, щоб давніші виклики й надалі розпізнавалися; новим викликам його більше не призначають. Завантажте таксономію один раз під час запуску, щоб зіставити слова телефона з вашими власними полями.
/settings повертає конфігурацію, крім секретів: звукові пристрої та гучність, пріоритет кодеків, вигляд і мову, запуск, клавіатурні скорочення, рівень діагностики і стан обох інтеграцій, — це корисно для інструмента підтримки, який має перевірити робочу станцію без демонстрації екрана. api.disabled перелічує вимкнені групи доступу, а webhooks.silenced — вимкнені події; порожні списки означають, що ввімкнено все. Він ніколи не містить пароля SIP, токена API чи значення заголовка вебхука.
Помилки
Кожна помилка — це 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, тож інтеграція, яка тихо не працює, видна в метриках, а не лише у ваших власних журналах.
Метрики
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 | Відхилені запити: хибний токен, вимкнена група або невідомий шлях. |
Оновлення давнішої інтеграції
Давніші версії використовували назви в camelCase і короткі ідентифікатори. accountId тепер account_id, startedAt — callstart_ts, durationSeconds — duration_s, answeredBy — answered_by, а поле вебхука at — event_ts. Виклики й облікові записи ідентифікуються лише за UUID: runtimeId та ідентифікатори на кшталт call-3 чи account-2 більше не повертаються і не приймаються.
Коли не працює
| Симптом | Що перевірити |
|---|---|
У з'єднанні з 127.0.0.1:8377 відмовлено | Локальне керування вимкнено, телефон не запущено або порт змінено. |
404 {"error":"no such endpoint"} для шляху з цієї сторінки | Його групу доступу вимкнено. |
Читання працює, запис відхиляється з 401 | Кінцевим точкам, що змінюють збережені дані, потрібен токен у заголовку Authorization, а на телефоні спершу треба заповнити поле Токен. |
| Назви категорій не англійською | Назви йдуть мовою інтерфейсу. Зіставляйте за code з /taxonomy. |
Немає accountId, startedAt чи at | Інтеграцію написано для давніших назв; див. вище. |
Якщо проблема з реєстрацією або самим викликом, відкрийте Діагностику.