Към основното съдържание

Уебкукички

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

След инсталиране уебкукичките са изключени, докато не ги включите. Те работят заедно с локалния REST API: събитието казва, че нещо се е променило, а API дава текущите подробности.

Включване​

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

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

Частта от програмата, която изпраща заявките, е модулът Интеграция; той може да се изключи в Модули.

Събитията​

Отметнато катоСъбитиеИзпраща се, когато
Ново обажданеcall-startedВходящо обаждане започне да звъни или бъде проведено изходящо обаждане.
Обаждане, което сменя състоянието сиcall-state-changedstate на обаждането се промени: то бъде прието, задържано или продължено от която и да е страна, или се присъедини към конференция или я напусне. Заглушаването не го изпраща.
Приключващо обаждане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-startedringing-indialing
call-state-changedactiveringing-out, след това active
call-endedendedended

Полетата​

Всяка стойност е низ, включително числата и времевите отметки: "duration_s": "42". Неизвестен момент е празен низ. Имената следват една конвенция: _id е идентификатор, _ts е Unix време в милисекунди (UTC), _s е продължителност в секунди — същото като в REST API, където стойностите са JSON числа.

ПолеЗначение
eventcall-started, call-state-changed или call-ended.
idОбаждането: същият UUID като в GET /calls и /calls/{id}/…, един и същ във всяко събитие на обаждането.
seance_idРазговорът, към който принадлежи обаждането; вижте по-долу.
directionin или out.
stateСъщите стойности като в GET /calls: dialing, ringing-out, ringing-in, active, hold (задържано от този телефон), onhold (задържано от другата страна), conference или ended.
numberНомерът на другата страна. Свързвайте записите в CRM по това поле.
nameИмето на другата страна от Контакти; може да е празно и може да бъде попълнено по-късно по време на обаждането, както при изходящото обаждане по-горе.
uriSIP адресът на другата страна.
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_byno, ако обаждането е прието от човек; иначе — какво го е приело.

Един разговор през прехвърлянията​

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 като едно.