Pređi na glavni sadržaj

Veb-kuke

Veb-kuka je zahtev koji telefon šalje na adresu po vašem izboru svaki put kada se sa pozivom nešto desi. Zahvaljujući njoj CRM može da otvori karticu kupca pre drugog zvona, zabeleži poziv kada se završi ili upali lampicu na zidnoj tabli. Veb-kuka ne zahteva pravila zaštitnog zida za dolazni saobraćaj: telefon se povezuje sa vama. Pošto se zahtevi šalju sa radne stanice, adresa mora biti dostupna samo sa tog računara — interna http://crm.local/calls radi jednako dobro kao javna HTTPS adresa.

Nakon instalacije veb-kuke su isključene dok ih ne uključite. Rade uz lokalni REST API: događaj kaže da se nešto promenilo, a API daje trenutne pojedinosti.

Uključivanje​

Otvorite Podešavanja → Povezivanje. Veb-kuke su prvi odeljak kartice.

  1. Označite Javi drugom sistemu o pozivima. Za svaki događaj koji označite ispod šalje se jedan zahtev.
  2. Upišite Adresa koja treba da prima događaje, na primer https://crm.local/calls.
  3. Izaberite Metod: POST (podrazumevano) ili GET.
  4. Pod Događaji označite šta da se šalje: Novi poziv, Kraj poziva, Promena stanja poziva.
  5. Po želji pod Prijava podesite zaglavlje koje vaš primalac može da proveri: Naziv zaglavlja (predlaže se Authorization) i Vrednost zaglavlja. Vrednost se čuva u skladištu ključeva računara, nikada u datoteci podešavanja; nakon čuvanja polje prikazuje Sačuvano — kucajte da zamenite.
  6. Pritisnite Pošalji probni događaj da vidite da li stiže. Šalje jedan događaj za poziv koji se nikada nije desio, sa istim zaglavljima kao pravi. Zabeležite sirovi zahtev i pravite primaoca prema onome što vaša verzija stvarno šalje.

Deo programa koji šalje zahteve je modul Povezivanje; može da se isključi u Modulima.

Događaji​

Označeno kaoDogađajŠalje se kada
Novi pozivcall-startedDolazni poziv počne da zvoni ili se uputi odlazni poziv.
Promena stanja pozivacall-state-changedPromeni se state poziva: neko se javi, poziv se stavi na čekanje ili nastavi sa bilo koje strane, ili se pridruži konferenciji ili je napusti. Isključivanje mikrofona ga ne šalje.
Kraj pozivacall-endedPoziv se završio.

Svaki događaj može da se označi zasebno. Iskačuća kartica kupca treba samo prvi, dnevnik poziva samo poslednji. call-started se šalje prvi i treba ga brzo obraditi.

Kako izgleda zahtev​

Sa adresom https://crm.local/calls i metodom POST telefon šalje ovo. Telo je JSON, a zaglavlje je ono koje ste podesili pod Prijava:

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 nosi verziju programa i način na koji je instaliran.

Dolazni poziv, događaj po događaj​

Poziv sa internog broja 1020 na nalog 1002 zvoni, neko se javi, a osoba koja se javila prekida poziv četiri sekunde kasnije. Uz sva tri označena događaja primalac dobija tri zahteva, jedan za drugim. Svi nose isti id i seance_id.

1. Zvoni: 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"
}

Ovo je trenutak da pozivaoca potražite po number i prikažete karticu kupca. state je ringing-in, a duration_s je 0.

2. Neko se javi: call-state-changed​

Oko tri sekunde kasnije:

{
"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 je sada active, a callstate_ts se pomerio na trenutak promene, dok callstart_ts ostaje gde je bio.

3. Završava se: call-ended​

Posle četiri sekunde razgovora:

{
"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 je ended, duration_s je trajanje razgovora, a reason kaže ko ga je završio: ovde local-hangup, jer je poziv prekinula osoba na ovom telefonu.

Odlazni poziv, događaj po događaj​

Isti interni broj se zove sa naloga 1002: osoba bira 1020, telefon zvoni, druga strana se javlja, razgovara sedam sekundi i prekida. Primalac dobija četiri zahteva, jedan više nego za dolazni poziv, jer odlazni poziv ima sopstveno stanje dok zvoni na drugoj strani.

1. Bira se: 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 je out, state je dialing, a dialed sadrži broj kako je biran. Telefon još ne zna ime druge strane, pa je name prazan.

2. Zvoni na drugoj strani: call-state-changed​

Pola sekunde kasnije:

{
"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 je ringing-out.

3. Druga strana se javlja: call-state-changed​

Četiri sekunde posle toga:

{
"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 je active. name je sada popunjen, a uri je adresa druge strane kako ju je javio odgovor. duration_s je i dalje 0: broji od ovog trenutka.

4. Završava se: call-ended​

Sedam sekundi kasnije druga strana prekida poziv:

{
"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 je 7, a reason je remote-hangup, jer je poziv završila druga strana. Kada prekinete sami, to je local-hangup, kao kod dolaznog poziva gore.

Stanja jedno pored drugog​

Dolazni pozivOdlazni poziv
call-startedringing-indialing
call-state-changedactiveringing-out, zatim active
call-endedendedended

Polja​

Svaka vrednost je niska, uključujući brojeve i vremenske oznake: "duration_s": "42". Nepoznat trenutak je prazna niska. Nazivi prate jednu konvenciju: _id je identifikator, _ts je Unix vreme u milisekundama (UTC), _s je trajanje u sekundama — isto kao u REST API-ju, gde su vrednosti JSON brojevi.

PoljeZnačenje
eventcall-started, call-state-changed ili call-ended.
idPoziv: isti UUID kao u GET /calls i /calls/{id}/…, isti u svakom događaju poziva.
seance_idRazgovor kom poziv pripada; pogledajte u nastavku.
directionin ili out.
stateIste vrednosti kao u GET /calls: dialing, ringing-out, ringing-in, active, hold (na čekanje stavio ovaj telefon), onhold (na čekanje stavila druga strana), conference ili ended.
numberBroj druge strane. Zapise u CRM-u uparujte po ovom polju.
nameIme druge strane iz Kontakata; može biti prazno i može da se popuni kasnije u pozivu, kao kod odlaznog poziva gore.
uriSIP adresa druge strane.
dialedBirane cifre, za odlazni poziv; prazno za dolazni.
account, account_idLinija na kojoj je poziv: username@server i identifikator iz GET /accounts.
event_tsKada se događaj desio.
callstart_tsKada je telefon prvi put saznao za poziv.
callstate_tsKada je poziv ušao u trenutni state.
duration_sVreme razgovora u sekundama, od javljanja do prekida. Postavlja se u call-ended za poziv na koji se neko javio; inače 0.
reasonKako se poziv završio: local-hangup, remote-hangup, busy, no-answer, cancelled…; do tada none.
answered_byno ako se na poziv javio čovek; inače ono što se javilo.

Jedan razgovor kroz prosleđivanja​

seance_id grupiše pozive koji čine jedan razgovor. Poziv upućen ili primljen iznova započinje novi. Poziv nastao prosleđivanjem, poziv koji zamenjuje drugi, konsultacija o pozivu i svaki poziv pridružen konferenciji zadržavaju seance_id poziva iz kog su nastali.

Između telefona prenosi ga SIP zaglavlje X-Seance-Id: kada se poziv prosledi kolegi koji takođe koristi AI Softphone, a centrala zaglavlje prenese dalje, obe radne stanice javljaju isti seance_id.

GET umesto POST​

GET je za primaoce koji ne mogu da prime telo zahteva, kao što su stariji CRM ili skriptni most. Ista polja se tada šalju kao parametri upita.

Uz GET adresa može biti šablon: svako [polje] zamenjuje se vrednošću tog polja, procentno kodiranom. Na primer:

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

Čuvari mesta koriste gornje nazive polja. Šabloni sačuvani sa ranijim nazivima ([accountId], [at], [duration], [answeredBy], [seanceId]) i dalje rade.

Kako se događaji isporučuju​

PonašanjeŠta to znači za vas
Događaji idu u red, ne šalju se iz samog pozivaSpor primalac nikada ne odlaže zvonjenje, pozive ni prosleđivanja.
Pun red odbacuje događajeAko vaš primalac prestane da odgovara, događaji se gube, ali telefon nastavlja da radi. Pratite webhooks_dropped_total.
Odbijene i nedostupne isporuke se brojeRast webhooks_failed_total dok webhooks_delivered_total stoji upućuje na primaoca.
Događaji stižu redomPočetak poziva, zatim promene stanja, zatim kraj poziva. Za ređanje sačuvanih događaja koristite callstate_ts, a ne vreme dolaska.
Najmanje jednomIsti događaj može da stigne dvaput. id, event i callstate_ts zajedno identifikuju događaj: neka vaš rukovalac preskoči onaj koji je već video.

Primanje događaja​

Jedino pravilo za primaoca: odmah odgovorite 200, a posao obavite posle. Spor primalac ne usporava telefon, ali puni red, a pun red odbacuje događaje.

Na primer, u Node.js sa Expressom:

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

Da zabeležite ishod poziva — prihvaćen, propušten, odbijen — uzmite stavku sa istim seance_id i number iz GET /history?limit=20 u REST API-ju. Kada se vaša usluga posle pauze ponovo pokrene, pročitajte GET /history?limit=200 i sačuvajte ono što ste propustili: veb-kuke za realno vreme, istorija za popunjavanje praznina.

Da vidite zahteve pre nego što CRM bude spreman, usmerite Adresa na mrežni pregledač zahteva i pritisnite Pošalji probni događaj.

Kada ništa ne stiže​

SimptomŠta proveriti
Nema nijedne veb-kukePritisnite Pošalji probni događaj. Ako stigne, potrebni događaji nisu označeni; ako ne, adresa je pogrešna ili nedostupna sa radne stanice.
webhooks_failed_total stalno rastePrimalac odbija zahteve ili je nedostupan. Proverite njegov dnevnik i da li odgovara na jednostavan zahtev sa radne stanice.
webhooks_dropped_total je veći od nulePrimalac je predugo bio prespor i red se napunio. Prvo odgovorite 200, zatim obrađujte.
Isti događaj dvaputOčekivano kod isporuke najmanje jednom. Događaje sa istim id, event i callstate_ts smatrajte jednim.