Ugrás a fő tartalomra

Webhookok

A webhook egy kérés, amelyet a telefon egy Ön által választott címre küld minden alkalommal, amikor egy hívással történik valami. Ennek segítségével tudja egy CRM megnyitni az ügyfél adatlapját még a második csengés előtt, naplózni egy hívást, amikor véget ér, vagy felkapcsolni egy lámpát egy faliújságon. A webhookhoz nem kellenek bejövő tűzfalszabályok: a telefon kapcsolódik Önhöz. Mivel a kérések a munkaállomásról mennek ki, a címnek csak arról a számítógépről kell elérhetőnek lennie — egy belső http://crm.local/calls cím ugyanolyan jól működik, mint egy nyilvános HTTPS-cím.

A webhookok a telepítés után ki vannak kapcsolva, amíg be nem kapcsolja őket. A helyi REST API mellett működnek: egy esemény jelzi, hogy valami megváltozott, az API pedig megadja az aktuális részleteket.

Bekapcsolás​

Nyissa meg a Beállítások → Integráció lapot. A Webhookok a lap első része.

  1. Jelölje be az Egy másik rendszer értesítése a hívásokról lehetőséget. Minden alább bejelölt eseményre egy kérés megy ki.
  2. Adja meg a Cím mezőben azt a címet, amelyre az eseményeknek érkezniük kell, például https://crm.local/calls.
  3. Válassza ki a Módszer értékét: POST (az alapérték) vagy GET.
  4. Az Események alatt jelölje be, mit küldjön: Új hívás, Véget érő hívás, Állapotot váltó hívás.
  5. Ha szeretné, az Engedélyezés alatt állítson be egy fejlécet, amelyet a fogadó ellenőrizhet: egy Fejléc neve (javasolt: Authorization) és egy Fejléc értéke mezőt. Az értéket a számítógép kulcstartója őrzi, soha nem egy beállításfájl; mentés után a mezőben az Elmentve — írjon, hogy lecserélje felirat látható.
  6. Nyomja meg a Teszt esemény küldése gombot, hogy lássa, megérkezik-e. Ez egy eseményt küld egy soha meg nem történt hívásról, ugyanazokkal a fejlécekkel, mint egy valódi. Naplózza a nyers kérést, és a fogadót aszerint építse fel, amit az Ön verziója ténylegesen küld.

A program kéréseket küldő része az Integráció modul; a Modulok között kikapcsolható.

Az események​

Bejelölve mintEseményMikor küldi
Új híváscall-startedEgy bejövő hívás csörögni kezd, vagy egy kimenő hívás elindul.
Állapotot váltó híváscall-state-changedMegváltozik a hívás state értéke: fogadják, bármelyik fél tartásba teszi vagy folytatja, illetve csatlakozik egy konferenciához vagy kilép belőle. A némítás nem küldi el.
Véget érő híváscall-endedA hívás véget ért.

Minden esemény külön is bejelölhető. Egy felugró ügyféladatlaphoz csak az első kell, egy hívásnaplóhoz csak az utolsó. A call-started megy ki elsőként, és gyorsan kell feldolgozni.

Hogyan néz ki a kérés​

A https://crm.local/calls címmel és a POST módszerrel a telefon ezt küldi. A törzs JSON, a fejléc pedig az, amelyet az Engedélyezés alatt beállított:

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

A User-Agent a program verzióját és a telepítés módját tartalmazza.

Bejövő hívás, eseményről eseményre​

Egy hívás az 1020-as mellékről az 1002-es fiókra csörög, fogadják, és aki fogadta, négy másodperccel később bontja. Mindhárom esemény bejelölésével a fogadó három kérést kap, egymás után. Mindegyikben ugyanaz az id és a seance_id.

1. Csörög: 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"
}

Ez az a pillanat, amikor érdemes a hívót a number alapján kikeresni, és megjeleníteni az ügyfél adatlapját. A state értéke ringing-in, a duration_s értéke 0.

2. Fogadják: call-state-changed​

Körülbelül három másodperccel később:

{
"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"
}

A state most active, a callstate_ts pedig a változás pillanatára lépett előre, míg a callstart_ts ott maradt, ahol volt.

3. Véget ér: call-ended​

Négy másodperc beszélgetés után:

{
"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"
}

A state értéke ended, a duration_s a beszélgetés hossza, a reason pedig megmondja, ki fejezte be: itt local-hangup, mert a telefonnál ülő személy bontott.

Kimenő hívás, eseményről eseményre​

Ugyanezt a melléket hívják az 1002-es fiókról: a felhasználó tárcsázza az 1020-at, a telefon csörög, a túloldal fogadja, hét másodpercig beszél, majd bont. A fogadó négy kérést kap, eggyel többet, mint egy bejövő hívásnál, mert a kimenő hívásnak saját állapota van, amíg a túloldalon csörög.

1. Tárcsázás: 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"
}

A direction értéke out, a state értéke dialing, a dialed pedig a számot tartalmazza úgy, ahogyan tárcsázták. A telefon még nem ismeri a másik fél nevét, ezért a name üres.

2. Csörög a túloldalon: call-state-changed​

Fél másodperccel később:

{
"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"
}

A state értéke ringing-out.

3. A túloldal fogadja: call-state-changed​

Négy másodperccel ezután:

{
"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"
}

A state értéke active. A name most már ki van töltve, az uri pedig a fél címe úgy, ahogyan a válasz jelezte. A duration_s még mindig 0: ettől a pillanattól számol.

4. Véget ér: call-ended​

Hét másodperccel később a túloldal bont:

{
"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"
}

A duration_s értéke 7, a reason értéke remote-hangup, mert a túloldal fejezte be a hívást. Ha Ön bont, az érték local-hangup, mint a fenti bejövő hívásnál.

Az állapotok egymás mellett​

Bejövő hívásKimenő hívás
call-startedringing-indialing
call-state-changedactiveringing-out, majd active
call-endedendedended

A mezők​

Minden érték karakterlánc, a számokat és az időbélyegeket is beleértve: "duration_s": "42". Az ismeretlen időpont üres karakterlánc. A nevek egyetlen konvenciót követnek: az _id azonosító, a _ts Unix-idő ezredmásodpercben (UTC), az _s másodpercben megadott hossz — ugyanúgy, mint a REST API-ban, ahol az értékek JSON-számok.

MezőJelentés
eventcall-started, call-state-changed vagy call-ended.
idA hívás: ugyanaz az UUID, mint a GET /calls és a /calls/{id}/… esetében, és a hívás minden eseményében ugyanaz.
seance_idA beszélgetés, amelyhez a hívás tartozik; lásd alább.
directionin vagy out.
stateUgyanazok az értékek, mint a GET /calls esetében: dialing, ringing-out, ringing-in, active, hold (ez a telefon tette tartásba), onhold (a másik fél tette tartásba), conference vagy ended.
numberA másik fél száma. A CRM rekordjait ehhez a mezőhöz illessze.
nameA másik fél neve a Névjegyekből; lehet üres, és a hívás során később is kitöltődhet, mint a fenti kimenő hívásnál.
uriA másik fél SIP-címe.
dialedA tárcsázott számjegyek kimenő hívásnál; bejövő hívásnál üres.
account, account_idA vonal, amelyen a hívás zajlik: username@server, valamint az azonosító a GET /accounts válaszból.
event_tsMikor történt az esemény.
callstart_tsMikor szerzett először tudomást a telefon a hívásról.
callstate_tsMikor került a hívás az aktuális state állapotába.
duration_sA beszélgetési idő másodpercben, a fogadástól a bontásig. Fogadott hívásnál a call-ended eseményben van kitöltve; egyébként 0.
reasonHogyan ért véget a hívás: local-hangup, remote-hangup, busy, no-answer, cancelled…; addig none.
answered_byno, ha egy személy fogadta a hívást; egyébként az, ami fogadta.

Egy beszélgetés átadásokon keresztül​

A seance_id csoportosítja azokat a hívásokat, amelyek egy beszélgetést alkotnak. Egy elölről indított vagy fogadott hívás újat kezd. Az átadással létrejött hívás, egy másikat felváltó hívás, egy hívással kapcsolatos konzultáció és minden konferenciába kapcsolt hívás megtartja annak a hívásnak a seance_id értékét, amelyből származik.

A telefonok között az X-Seance-Id SIP-fejlécben utazik: ha egy hívást olyan kollégának adnak át, aki szintén AI Softphone-t használ, és az alközpont továbbítja a fejlécet, mindkét munkaállomás ugyanazt a seance_id értéket jelenti.

GET a POST helyett​

A GET azoknak a fogadóknak való, amelyek nem tudnak kéréstörzset fogadni, például egy régebbi CRM-nek vagy egy szkriptes átjárónak. Ilyenkor ugyanazok a mezők lekérdezési paraméterekként mennek ki.

GET esetén a cím sablon is lehet: minden [field] helyére az adott mező értéke kerül, százalékos kódolással. Például:

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

A helyőrzők a fenti mezőneveket használják. A korábbi nevekkel ([accountId], [at], [duration], [answeredBy], [seanceId]) mentett sablonok továbbra is működnek.

Hogyan kézbesülnek az események​

ViselkedésMit jelent ez Önnek
Az események várólistára kerülnek, nem magából a hívásból mennek kiEgy lassú fogadó soha nem késlelteti a csengést, a hívásokat vagy az átadásokat.
A megtelt várólista eldobja az eseményeketHa a fogadó nem válaszol többé, események vesznek el, de a telefon tovább működik. Figyelje a webhooks_dropped_total értékét.
Az elutasított és az elérhetetlen kézbesítéseket a program számoljaHa a webhooks_failed_total nő, miközben a webhooks_delivered_total áll, a hiba a fogadónál van.
Az események sorrendben érkeznekHívás indulása, aztán az állapotváltozások, aztán a hívás vége. A tárolt események sorba rendezéséhez a callstate_ts értéket használja, ne az érkezésük idejét.
Legalább egyszerUgyanaz az esemény kétszer is megérkezhet. Az id, az event és a callstate_ts együtt azonosít egy eseményt: a kezelője hagyja ki azt, amelyet már látott.

Az események fogadása​

A fogadó egyetlen szabálya: azonnal válaszoljon 200-zal, és utána végezze el a munkát. Egy lassú fogadó nem lassítja a telefont, de megtölti a várólistát, a megtelt várólista pedig eldobja az eseményeket.

Például Node.js-ben, Expresszel:

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);

Egy hívás kimenetelének — fogadott, nem fogadott, elutasított — naplózásához vegye ki az azonos seance_id és number értékű bejegyzést a REST API GET /history?limit=20 válaszából. Amikor a szolgáltatása egy szünet után újraindul, olvassa be a GET /history?limit=200 választ, és tárolja el, amiről lemaradt: a webhookok a valós időhöz, az előzmények a hézagok kitöltéséhez.

Ha a CRM elkészülte előtt szeretné látni a kéréseket, irányítsa a Cím mezőt egy online kérésvizsgálóra, és nyomja meg a Teszt esemény küldése gombot.

Ha semmi sem érkezik meg​

TünetMit ellenőrizzen
Egyáltalán nem érkeznek webhookokNyomja meg a Teszt esemény küldése gombot. Ha megérkezik, a szükséges események nincsenek bejelölve; ha nem, a cím hibás, vagy nem érhető el a munkaállomásról.
A webhooks_failed_total folyamatosan nőA fogadó elutasítja a kéréseket, vagy nem érhető el. Ellenőrizze a naplóját, és azt, hogy válaszol-e egy egyszerű kérésre a munkaállomásról.
A webhooks_dropped_total nagyobb nullánálA fogadó túl sokáig volt túl lassú, és a várólista megtelt. Először válaszoljon 200-zal, aztán dolgozza fel.
Ugyanaz az esemény kétszerA legalább egyszeri kézbesítésnél ez várható. Az azonos id, event és callstate_ts értékű eseményeket kezelje egyként.