Уебкукички
Уебкукичката е заявка, която телефонът изпраща на адрес по ваш избор всеки път, когато с обаждането се случи нещо. Така 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 като едно. |