Перейти до основного вмісту

Локальний REST API

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

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

Використовуйте API, коли вашій програмі потрібні дані з телефона або треба керувати викликом. Використовуйте вебхуки, коли вона має реагувати на виклики в міру того, як вони відбуваються, без опитування. Більшість інтеграцій використовують і те, й інше; вони незалежні одне від одного.

Як його ввімкнути​

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

  1. Увімкніть Дозволити іншим програмам на цьому комп'ютері керувати телефоном. Сервер запускається одразу.
  2. Залиште типовий Порт, 8377, якщо його вже не використовує інша програма.
  3. За бажанням задайте Токен. Після збереження поле показує Збережено — введіть, щоб замінити.
  4. У розділі Доступ виберіть групи, які відкрити: Контакти, Історія викликів, Виклики і керування ними, Облікові записи, Налаштування, Лічильники (метрики). Вимкнена група не фільтрується, а взагалі не обслуговується.
  5. Перевірте: 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/accountsSIP-облікові записи та стан їх реєстрації. Ніколи — пароль.
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.
answeredtrue або false.
duration_s0 для виклику, який так і не з'єднався.
number, uriІнша сторона — як номер і як SIP-адреса.
nameЗ Контактів, якщо номер відомий, інакше порожнє. Зіставляйте за number, а не за цим полем.
dialedНабрані цифри для вихідного виклику; порожнє для вхідного.
account, account_idЛінія, на якій був виклик.
reasonЯк він завершився: local-hangup, remote-hangup, cancelled…
answered_byno, якщо на виклик відповіла людина; інакше — те, що на нього відповіло.

Контакти: 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_totalSIP-реєстрації, відхилені або завершені за тайм-аутом.
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Інтеграцію написано для давніших назв; див. вище.

Якщо проблема з реєстрацією або самим викликом, відкрийте Діагностику.