# Вебхуки

> Нехай телефон надсилає вашій CRM чи іншій системі запит, коли виклик починається, змінюється або закінчується, — з точними запитами вхідного і вихідного викликів.

Вебхук — це запит, який телефон надсилає на вибрану вами адресу щоразу, коли з викликом щось відбувається. Саме так CRM може відкрити картку клієнта ще до другого гудка, занести виклик до журналу, коли він закінчиться, або засвітити лампочку на настінному табло. Вебхуку не потрібні правила брандмауера для вхідного трафіку: телефон сам звертається до вас. Оскільки запити надсилаються з робочої станції, адреса має бути досяжною лише з цього комп'ютера — внутрішня `http://crm.local/calls` працює так само добре, як публічна адреса HTTPS.

Після встановлення вебхуки **вимкнено**, доки ви їх не ввімкнете. Вони працюють разом із [локальним REST API](https://docs.ai-softphone.com/uk/integration/rest-api/index.md): подія повідомляє, що щось змінилося, а API надає поточні подробиці.

## Як їх увімкнути {#turning-them-on}

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

![Налаштування → Інтеграція → Вебхуки, з адресою https://crm.local/calls](https://docs.ai-softphone.com/screenshots/macos/uk/24_webhooks.png)

1. Позначте **Повідомляти іншу систему про виклики**. *Для кожної події, яку ви позначите нижче, надсилається запит.*
2. Введіть **Адреса**, на яку мають надходити події, наприклад `https://crm.local/calls`.
3. Виберіть **Метод**: **POST** (типово) або **GET**.
4. У розділі **Події** позначте, що надсилати: **Новий виклик**, **Завершення виклику**, **Зміна стану виклику**.
5. За бажанням у розділі **Авторизація** задайте заголовок, який може перевіряти ваш одержувач: **Назва заголовка** (пропонується `Authorization`) і **Значення заголовка**. Значення зберігається у сховищі ключів комп'ютера, ніколи — у файлі налаштувань; після збереження поле показує *Збережено — введіть, щоб замінити*.
6. Натисніть **Надіслати тестову подію**, щоб перевірити, чи вона надходить. Надсилається одна подія для виклику, якого ніколи не було, з тими самими заголовками, що й у справжньої. Запишіть сирий запит і будуйте свій одержувач на основі того, що ваша версія надсилає насправді.

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

## Події {#the-events}

| Позначено як | Подія | Надсилається, коли |
| --- | --- | --- |
| **Новий виклик** | `call-started` | Вхідний виклик починає дзвонити або здійснюється вихідний виклик. |
| **Зміна стану виклику** | `call-state-changed` | Змінюється `state` виклику: на нього відповіли, будь-яка сторона поставила його на утримання чи відновила, або він приєднався до конференції чи вийшов з неї. Вимкнення мікрофона її не надсилає. |
| **Завершення виклику** | `call-ended` | Виклик завершився. |

Кожну подію можна позначити окремо. Для спливної картки клієнта потрібна лише перша; для журналу викликів — лише остання. `call-started` надсилається першою, і обробляти її слід швидко.

## Як виглядає запит {#what-the-request-looks-like}

З адресою `https://crm.local/calls` і методом **POST** телефон надсилає ось що. Тіло — JSON, а заголовок — той, що ви задали в розділі **Авторизація**:

```http
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` містить версію програми і спосіб, у який її встановлено.

## Вхідний виклик, подія за подією {#an-incoming-call-event-by-event}

Виклик із внутрішнього номера `1020` на обліковий запис `1002` дзвонить, на нього відповідають, і через чотири секунди людина, що відповіла, кладе слухавку. Якщо позначено всі три події, одержувач отримує три запити, один за одним. Усі вони мають однакові `id` і `seance_id`.

### 1. Дзвонить: `call-started` {#1-it-rings-call-started}

```json
{
  "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` {#2-it-is-answered-call-state-changed}

Приблизно через три секунди:

```json
{
  "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` {#3-it-ends-call-ended}

Після чотирьох секунд розмови:

```json
{
  "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`, бо слухавку поклала людина біля цього телефона.

## Вихідний виклик, подія за подією {#an-outgoing-call-event-by-event}

На той самий внутрішній номер дзвонять з облікового запису `1002`: людина набирає `1020`, телефон дзвонить, інша сторона відповідає, розмовляє сім секунд і кладе слухавку. Одержувач отримує чотири запити, на один більше, ніж для вхідного виклику, бо вихідний виклик має власний стан, поки дзвонить на іншому кінці.

### 1. Номер набирається: `call-started` {#1-it-is-dialled-call-started}

```json
{
  "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` {#2-it-rings-at-the-other-end-call-state-changed}

Через пів секунди:

```json
{
  "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` {#3-the-other-side-answers-call-state-changed}

Ще через чотири секунди:

```json
{
  "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` {#4-it-ends-call-ended}

Через сім секунд інша сторона кладе слухавку:

```json
{
  "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`, як у вхідному виклику вище.

### Стани поруч {#the-states-side-by-side}

| | Вхідний виклик | Вихідний виклик |
| --- | --- | --- |
| `call-started` | `ringing-in` | `dialing` |
| `call-state-changed` | `active` | `ringing-out`, потім `active` |
| `call-ended` | `ended` | `ended` |

## Поля {#the-fields}

**Кожне значення — рядок**, зокрема числа й часові мітки: `"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` | Розмова, до якої належить виклик; див. [нижче](#one-conversation-across-transfers). |
| `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`, якщо на виклик відповіла людина; інакше — те, що на нього відповіло. |

## Одна розмова крізь переадресації {#one-conversation-across-transfers}

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

Між телефонами він передається в SIP-заголовку `X-Seance-Id`: коли виклик переадресовують колезі, який теж користується AI Softphone, і АТС передає заголовок далі, обидві робочі станції повідомляють той самий `seance_id`.

## GET замість POST {#get-instead-of-post}

**GET** призначено для одержувачів, які не можуть прийняти тіло запиту, як-от стара CRM або скрипт-міст. Ті самі поля тоді надсилаються як параметри запиту.

З **GET** адреса може бути шаблоном: кожен `[field]` замінюється значенням цього поля у відсотковому кодуванні. Наприклад:

```text
https://crm.local/pop?phone=[number]&call=[id]
```

Заповнювачі використовують назви полів, наведені вище. Шаблони, збережені з давнішими назвами (`[accountId]`, `[at]`, `[duration]`, `[answeredBy]`, `[seanceId]`), і далі працюють.

## Як доставляються події {#how-the-events-are-delivered}

| Поведінка | Що це означає для вас |
| --- | --- |
| Події ставляться в чергу, а не надсилаються з самого виклику | Повільний одержувач ніколи не затримує дзвінок, виклики чи переадресації. |
| Переповнена черга відкидає події | Якщо ваш одержувач перестає відповідати, події губляться, але телефон працює далі. Стежте за `webhooks_dropped_total`. |
| Відхилені й недоставлені запити рахуються | Якщо `webhooks_failed_total` зростає, а `webhooks_delivered_total` стоїть на місці, проблема в одержувачі. |
| Події надходять по порядку | Виклик почався, потім зміни стану, потім виклик закінчився. Щоб упорядкувати збережені події, використовуйте `callstate_ts`, а не час їх надходження. |
| Щонайменше один раз | Та сама подія може прийти двічі. `id`, `event` і `callstate_ts` разом ідентифікують подію: зробіть так, щоб обробник пропускав уже бачену. |

## Приймання подій {#receiving-the-events}

Єдине правило для одержувача: **відповідайте `200` одразу, а роботу виконуйте потім.** Повільний одержувач не сповільнює телефон, але заповнює чергу, а переповнена черга відкидає події.

Наприклад, у Node.js з Express:

```javascript
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](https://docs.ai-softphone.com/uk/integration/rest-api/index.md#call-history-get-history). Коли ваша служба знову запускається після перерви, прочитайте `GET /history?limit=200` і збережіть те, що пропустили: вебхуки — для реального часу, історія — щоб заповнити прогалини.

Щоб побачити запити ще до того, як CRM буде готова, вкажіть у полі **Адреса** онлайн-інспектор запитів і натисніть **Надіслати тестову подію**.

## Коли нічого не надходить {#when-nothing-arrives}

| Симптом | Що перевірити |
| --- | --- |
| Вебхуків немає зовсім | Натисніть **Надіслати тестову подію**. Якщо вона надходить, потрібні вам події не позначено; якщо ні — адреса хибна або недосяжна з робочої станції. |
| `webhooks_failed_total` постійно зростає | Одержувач відхиляє запити або недосяжний. Перевірте його журнал і те, чи відповідає він на простий запит із робочої станції. |
| `webhooks_dropped_total` більше нуля | Одержувач був надто повільним надто довго, і черга переповнилася. Спершу відповідайте `200`, а потім обробляйте. |
| Та сама подія двічі | Очікувано при доставці «щонайменше один раз». Вважайте події з однаковими `id`, `event` і `callstate_ts` однією. |
