Вебхуки
Вебхук — це запит, який телефон надсилає на вибрану вами адресу щоразу, коли з викликом щось відбувається. Саме так CRM може відкрити картку клієнта ще до другого гудка, занести виклик до журналу, коли він закінчиться, або засвітити лампочку на настінному табло. Вебхуку не потрібні правила брандмауера для вхідного трафіку: телефон сам звертається до вас. Оскільки запити надсилаються з робочої станції, адреса має бути досяжною лише з цього комп'ютера — внутрішня http://crm.local/calls працює так само добре, як публічна адреса HTTPS.
Після встановлення вебхуки вимкнено, доки ви їх не ввімкнете. Вони працюють разом із локальним REST API: подія повідомляє, що щось змінилося, а API надає поточні подробиці.
Як їх увімкнути
Відкрийте Налаштування → Інтеграція. Вебхуки — перший розділ вкладки.
- Позначте Повідомляти іншу систему про виклики. Для кожної події, яку ви позначите нижче, надсилається запит.
- Введіть Адреса, на яку мають надходити події, наприклад
https://crm.local/calls. - Виберіть Метод: POST (типово) або GET.
- У розділі Події позначте, що надсилати: Новий виклик, Завершення виклику, Зміна стану виклику.
- За бажанням у розділі Авторизація задайте заголовок, який може перевіряти ваш одержувач: Назва заголовка (пропонується
Authorization) і Значення заголовка. Значення зберігається у сховищі ключів комп'ютера, ніколи — у файлі налаштувань; після збереження поле показує Збережено — введіть, щоб замінити. - Натисніть Надіслати тестову подію, щоб перевірити, чи вона надходить. Надсилається одна подія для виклику, якого ніколи не було, з тими самими заголовками, що й у справжньої. Запишіть сирий запит і будуйте свій одержувач на основі того, що ваша версія надсилає насправді.
Частина програми, що надсилає запити, — це модуль Інтеграція; його можна вимкнути в Модулях.
Події
| Позначено як | Подія | Надсилається, коли |
|---|---|---|
| Новий виклик | call-started | Вхідний виклик починає дзвонити або здійснюється вихідний виклик. |
| Зміна стану виклику | call-state-changed | Змінюється state виклику: на нього відповіли, будь-яка сторона поставила його на утримання чи відновила, або він приєднався до конференції чи вийшов з неї. Вимкнення мікрофона її не надсилає. |
| Завершення виклику | call-ended | Виклик завершився. |
Кожну подію можна позначити окремо. Для спливної картки клієнта потрібна лише перша; для журналу викликів — лише остання. call-started надсилається першою, і обробляти її слід швидко.
Як виглядає запит
З адресою https://crm.local/calls і методом POST телефон надсилає ось що. Тіло — JSON, а заголовок — той, що ви задали в розділі Авторизація:
POST /calls HTTP/1.1
Host: crm.local
Authorization: Bearer my-secret-token
Content-Type: application/json
User-Agent: ai-softphone/1.1.5-macos-dmg
User-Agent містить версію програми і спосіб, у який її встановлено.
Вхідний виклик, подія за подією
Виклик із внутрішнього номера 1020 на обліковий запис 1002 дзвонить, на нього відповідають, і через чотири секунди людина, що відповіла, кладе слухавку. Якщо позначено всі три події, одержувач отримує три запити, один за одним. Усі вони мають однакові id і seance_id.
1. Дзвонить: call-started
{
"account": "1002@pbx.example.com",
"account_id": "0d7a4c52-6f2e-4a51-8f46-7d9a3e1b2c90",
"answered_by": "no",
"callstart_ts": "1791021263333",
"callstate_ts": "1791021263333",
"dialed": "",
"direction": "in",
"duration_s": "0",
"event": "call-started",
"event_ts": "1791021263333",
"id": "5b1c0a6e-0c7e-4c53-9f57-2c4f1f0d6a11",
"name": "Jack Russel",
"number": "1020",
"reason": "none",
"seance_id": "e3f0b9f4-1a2c-4d8b-9c35-6a7b8c9d0e1f",
"state": "ringing-in",
"uri": "sip:1020@pbx.example.com"
}
Саме час знайти абонента за number і показати картку клієнта. state має значення ringing-in, а duration_s — 0.
2. На виклик відповіли: call-state-changed
Приблизно через три секунди:
{
"account": "1002@pbx.example.com",
"account_id": "0d7a4c52-6f2e-4a51-8f46-7d9a3e1b2c90",
"answered_by": "no",
"callstart_ts": "1791021263333",
"callstate_ts": "1791021266126",
"dialed": "",
"direction": "in",
"duration_s": "0",
"event": "call-state-changed",
"event_ts": "1791021266131",
"id": "5b1c0a6e-0c7e-4c53-9f57-2c4f1f0d6a11",
"name": "Jack Russel",
"number": "1020",
"reason": "none",
"seance_id": "e3f0b9f4-1a2c-4d8b-9c35-6a7b8c9d0e1f",
"state": "active",
"uri": "sip:1020@pbx.example.com"
}
state тепер active, а callstate_ts перемістився на момент зміни, тоді як callstart_ts лишився там, де був.
3. Завершується: call-ended
Після чотирьох секунд розмови:
{
"account": "1002@pbx.example.com",
"account_id": "0d7a4c52-6f2e-4a51-8f46-7d9a3e1b2c90",
"answered_by": "no",
"callstart_ts": "1791021263333",
"callstate_ts": "1791021270400",
"dialed": "",
"direction": "in",
"duration_s": "4",
"event": "call-ended",
"event_ts": "1791021270406",
"id": "5b1c0a6e-0c7e-4c53-9f57-2c4f1f0d6a11",
"name": "Jack Russel",
"number": "1020",
"reason": "local-hangup",
"seance_id": "e3f0b9f4-1a2c-4d8b-9c35-6a7b8c9d0e1f",
"state": "ended",
"uri": "sip:1020@pbx.example.com"
}
state має значення ended, duration_s — тривалість розмови, а reason каже, хто її завершив: тут local-hangup, бо слухавку поклала людина біля цього телефона.
Вихідний виклик, подія за подією
На той самий внутрішній номер дзвонять з облікового запису 1002: людина набирає 1020, телефон дзвонить, інша сторона відповідає, розмовляє сім секунд і кладе слухавку. Одержувач отримує чотири запити, на один більше, ніж для вхідного виклику, бо вихідний виклик має власний стан, поки дзвонить на іншому кінці.
1. Номер набирається: call-started
{
"account": "1002@pbx.example.com",
"account_id": "0d7a4c52-6f2e-4a51-8f46-7d9a3e1b2c90",
"answered_by": "no",
"callstart_ts": "1791023883072",
"callstate_ts": "1791023883072",
"dialed": "1020",
"direction": "out",
"duration_s": "0",
"event": "call-started",
"event_ts": "1791023883072",
"id": "9a3e5c71-2d48-4b6f-8e10-3c5f7a1b9d24",
"name": "",
"number": "1020",
"reason": "none",
"seance_id": "c47d2e90-6b13-4f85-a2d7-18e9b0f35a6c",
"state": "dialing",
"uri": "sip:1020@pbx.example.com:5060"
}
direction має значення out, state — dialing, а dialed містить номер у тому вигляді, у якому його набрали. Телефон ще не знає імені іншої сторони, тому name порожнє.
2. Дзвонить на іншому кінці: call-state-changed
Через пів секунди:
{
"account": "1002@pbx.example.com",
"account_id": "0d7a4c52-6f2e-4a51-8f46-7d9a3e1b2c90",
"answered_by": "no",
"callstart_ts": "1791023883072",
"callstate_ts": "1791023883591",
"dialed": "1020",
"direction": "out",
"duration_s": "0",
"event": "call-state-changed",
"event_ts": "1791023883591",
"id": "9a3e5c71-2d48-4b6f-8e10-3c5f7a1b9d24",
"name": "",
"number": "1020",
"reason": "none",
"seance_id": "c47d2e90-6b13-4f85-a2d7-18e9b0f35a6c",
"state": "ringing-out",
"uri": "sip:1020@pbx.example.com:5060"
}
state має значення ringing-out.
3. Інша сторона відповідає: call-state-changed
Ще через чотири секунди:
{
"account": "1002@pbx.example.com",
"account_id": "0d7a4c52-6f2e-4a51-8f46-7d9a3e1b2c90",
"answered_by": "no",
"callstart_ts": "1791023883072",
"callstate_ts": "1791023887072",
"dialed": "1020",
"direction": "out",
"duration_s": "0",
"event": "call-state-changed",
"event_ts": "1791023887076",
"id": "9a3e5c71-2d48-4b6f-8e10-3c5f7a1b9d24",
"name": "Jack Russel",
"number": "1020",
"reason": "none",
"seance_id": "c47d2e90-6b13-4f85-a2d7-18e9b0f35a6c",
"state": "active",
"uri": "sip:1020@pbx.example.com"
}
state має значення active. name тепер заповнено, а uri — це адреса абонента в тому вигляді, у якому її повідомила відповідь. duration_s досі 0: відлік іде від цього моменту.
4. Завершується: call-ended
Через сім секунд інша сторона кладе слухавку:
{
"account": "1002@pbx.example.com",
"account_id": "0d7a4c52-6f2e-4a51-8f46-7d9a3e1b2c90",
"answered_by": "no",
"callstart_ts": "1791023883072",
"callstate_ts": "1791023894781",
"dialed": "1020",
"direction": "out",
"duration_s": "7",
"event": "call-ended",
"event_ts": "1791023894789",
"id": "9a3e5c71-2d48-4b6f-8e10-3c5f7a1b9d24",
"name": "Jack Russel",
"number": "1020",
"reason": "remote-hangup",
"seance_id": "c47d2e90-6b13-4f85-a2d7-18e9b0f35a6c",
"state": "ended",
"uri": "sip:1020@pbx.example.com"
}
duration_s має значення 7, а reason — remote-hangup, бо виклик завершила інша сторона. Коли слухавку кладете ви самі, значення буде local-hangup, як у вхідному виклику вище.
Стани поруч
| Вхідний виклик | Вихідний виклик | |
|---|---|---|
call-started | ringing-in | dialing |
call-state-changed | active | ringing-out, потім active |
call-ended | ended | ended |
Поля
Кожне значення — рядок, зокрема числа й часові мітки: "duration_s": "42". Невідомий момент — порожній рядок. Назви підпорядковані одній угоді: _id — ідентифікатор, _ts — час Unix у мілісекундах (UTC), _s — тривалість у секундах, — так само, як у REST API, де значення є числами JSON.
| Поле | Значення |
|---|---|
event | call-started, call-state-changed або call-ended. |
id | Виклик: той самий UUID, що в GET /calls і /calls/{id}/…, і однаковий у кожній події виклику. |
seance_id | Розмова, до якої належить виклик; див. нижче. |
direction | in або out. |
state | Ті самі значення, що в GET /calls: dialing, ringing-out, ringing-in, active, hold (утримується цим телефоном), onhold (утримується іншою стороною), conference або ended. |
number | Номер іншої сторони. Зіставляйте записи вашої CRM саме за цим полем. |
name | Ім'я іншої сторони з Контактів; може бути порожнім і може заповнитися пізніше під час виклику, як у вихідному виклику вище. |
uri | SIP-адреса іншої сторони. |
dialed | Набрані цифри для вихідного виклику; порожнє для вхідного. |
account, account_id | Лінія, на якій відбувається виклик: username@server та ідентифікатор із GET /accounts. |
event_ts | Коли сталася подія. |
callstart_ts | Коли телефон уперше дізнався про виклик. |
callstate_ts | Коли виклик перейшов у свій поточний state. |
duration_s | Час розмови в секундах, від відповіді до поклання слухавки. Задається в call-ended для виклику, на який відповіли; в інших випадках 0. |
reason | Як завершився виклик: local-hangup, remote-hangup, busy, no-answer, cancelled…; до того — none. |
answered_by | no, якщо на виклик відповіла людина; інакше — те, що на нього відповіло. |
Одна розмова крізь переадресації
seance_id групує виклики, з яких складається одна розмова. Виклик, здійснений або прийнятий з нуля, починає нову. Виклик, створений переадресацією, виклик, що замінює інший, консультація щодо виклику і кожен виклик, приєднаний до конференції, зберігають seance_id виклику, з якого вони походять.
Між телефонами він передається в SIP-заголовку X-Seance-Id: коли виклик переадресовують колезі, який теж користується AI Softphone, і АТС передає заголовок далі, обидві робочі станції повідомляють той самий seance_id.
GET замість POST
GET призначено для одержувачів, які не можуть прийняти тіло запиту, як-от стара CRM або скрипт-міст. Ті самі поля тоді надсилаються як параметри запиту.
З GET адреса може бути шаблоном: кожен [field] замінюється значенням цього поля у відсотковому кодуванні. Наприклад:
https://crm.local/pop?phone=[number]&call=[id]
Заповнювачі використовують назви полів, наведені вище. Шаблони, збережені з давнішими назвами ([accountId], [at], [duration], [answeredBy], [seanceId]), і далі працюють.
Як доставляються події
| Поведінка | Що це означає для вас |
|---|---|
| Події ставляться в чергу, а не надсилаються з самого виклику | Повільний одержувач ніколи не затримує дзвінок, виклики чи переадресації. |
| Переповнена черга відкидає події | Якщо ваш одержувач перестає відповідати, події губляться, але телефон працює далі. Стежте за webhooks_dropped_total. |
| Відхилені й недоставлені запити рахуються | Якщо webhooks_failed_total зростає, а webhooks_delivered_total стоїть на місці, проблема в одержувачі. |
| Події надходять по порядку | Виклик почався, потім зміни стану, потім виклик закінчився. Щоб упорядкувати збережені події, використовуйте callstate_ts, а не час їх надходження. |
| Щонайменше один раз | Та сама подія може прийти двічі. id, event і callstate_ts разом ідентифікують подію: зробіть так, щоб обробник пропускав уже бачену. |
Приймання подій
Єдине правило для одержувача: відповідайте 200 одразу, а роботу виконуйте потім. Повільний одержувач не сповільнює телефон, але заповнює чергу, а переповнена черга відкидає події.
Наприклад, у Node.js з Express:
const express = require("express");
const app = express();
app.use(express.json());
const SECRET = process.env.SOFTPHONE_SECRET; // the Header value from Settings
app.all("/calls", (req, res) => {
if (req.get("Authorization") !== SECRET) return res.sendStatus(401);
// POST sends a JSON body, GET sends query parameters
const call = Object.keys(req.body || {}).length ? req.body : req.query;
res.sendStatus(200); // answer first
setImmediate(() => { // then do the work
if (call.event === "call-started" && call.direction === "in") {
openCustomerCard(call.number, call.name); // your code
}
if (call.event === "call-ended") {
logCall(call.id, Number(call.duration_s), call.reason); // your code
}
});
});
app.listen(8080);
Щоб занести до журналу результат виклику — відповіли, пропущено, відхилено, — візьміть запис із тими самими seance_id і number з GET /history?limit=20 REST API. Коли ваша служба знову запускається після перерви, прочитайте GET /history?limit=200 і збережіть те, що пропустили: вебхуки — для реального часу, історія — щоб заповнити прогалини.
Щоб побачити запити ще до того, як CRM буде готова, вкажіть у полі Адреса онлайн-інспектор запитів і натисніть Надіслати тестову подію.
Коли нічого не надходить
| Симптом | Що перевірити |
|---|---|
| Вебхуків немає зовсім | Натисніть Надіслати тестову подію. Якщо вона надходить, потрібні вам події не позначено; якщо ні — адреса хибна або недосяжна з робочої станції. |
webhooks_failed_total постійно зростає | Одержувач відхиляє запити або недосяжний. Перевірте його журнал і те, чи відповідає він на простий запит із робочої станції. |
webhooks_dropped_total більше нуля | Одержувач був надто повільним надто довго, і черга переповнилася. Спершу відповідайте 200, а потім обробляйте. |
| Та сама подія двічі | Очікувано при доставці «щонайменше один раз». Вважайте події з однаковими id, event і callstate_ts однією. |