# Уебкукички

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

Уебкукичката е заявка, която телефонът изпраща на адрес по ваш избор всеки път, когато с обаждането се случи нещо. Така CRM може да отвори картата на клиента преди второто позвъняване, да запише обаждането, когато приключи, или да запали лампичка на информационно табло. Уебкукичката не изисква правила на защитната стена за входящ трафик: телефонът се свързва с вас. Понеже заявките се изпращат от работната станция, адресът трябва да е достъпен само от този компютър — вътрешен адрес като `http://crm.local/calls` работи също толкова добре, колкото публичен HTTPS адрес.

След инсталиране уебкукичките са **изключени**, докато не ги включите. Те работят заедно с [локалния REST API](https://docs.ai-softphone.com/bg/integration/rest-api/index.md): събитието казва, че нещо се е променило, а API дава текущите подробности.

## Включване {#turning-them-on}

Отворете **Настройки → Интеграция**. **Уебкукички** е първият раздел на страницата.

![Настройки → Интеграция → Уебкукички, с адрес https://crm.local/calls](https://docs.ai-softphone.com/screenshots/macos/bg/24_webhooks.png)

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

Частта от програмата, която изпраща заявките, е модулът **Интеграция**; той може да се изключи в [Модули](https://docs.ai-softphone.com/bg/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/bg/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` като едно. |
