Webhookovi
Webhook je zahtjev koji telefon šalje na adresu po vašem izboru svaki put kad se s pozivom nešto dogodi. Zahvaljujući njemu CRM može otvoriti karticu kupca prije drugog zvona, zabilježiti poziv kad završi ili upaliti lampicu na zidnoj ploči. Webhook ne treba pravila vatrozida za dolazni promet: telefon se spaja s vama. Budući da se zahtjevi šalju s radne stanice, adresa mora biti dostupna samo s tog računala — interna http://crm.local/calls radi jednako dobro kao javna HTTPS adresa.
Nakon instalacije webhookovi su isključeni dok ih ne uključite. Rade uz lokalni REST API: događaj kaže da se nešto promijenilo, a API daje trenutne pojedinosti.
Uključivanje
Otvorite Postavke → Integracija. Webhookovi su prvi odjeljak kartice.
- Označite Obavještavanje drugog sustava o pozivima. Za svaki dolje označeni događaj šalje se jedan zahtjev.
- Upišite Adresa koja treba primati događaje, primjerice
https://crm.local/calls. - Odaberite Metoda: POST (zadano) ili GET.
- Pod Događaji označite što slati: Novi poziv, Poziv koji završava, Poziv koji mijenja stanje.
- Po želji pod Autorizacija postavite zaglavlje koje vaš primatelj može provjeriti: Naziv zaglavlja (predlaže se
Authorization) i Vrijednost zaglavlja. Vrijednost se čuva u spremniku ključeva računala, nikada u datoteci postavki; nakon spremanja polje prikazuje Spremljeno — pišite da to zamijenite. - Pritisnite Pošalji probni događaj da vidite stiže li. Šalje jedan događaj za poziv koji se nikada nije dogodio, s istim zaglavljima kao pravi. Zabilježite sirovi zahtjev i gradite primatelja prema onome što vaša inačica stvarno šalje.
Dio programa koji šalje zahtjeve je modul Integracija; može se isključiti u Modulima.
Događaji
| Označeno kao | Događaj | Šalje se kad |
|---|---|---|
| Novi poziv | call-started | Dolazni poziv počne zvoniti ili se uputi odlazni poziv. |
| Poziv koji mijenja stanje | call-state-changed | Promijeni se state poziva: netko se javi, poziv se stavi na čekanje ili nastavi s bilo koje strane, ili se pridruži konferenciji ili je napusti. Utišavanje ga ne šalje. |
| Poziv koji završava | call-ended | Poziv je završio. |
Svaki se događaj može označiti zasebno. Skočna kartica kupca treba samo prvi, zapisnik poziva samo zadnji. call-started se šalje prvi i treba ga brzo obraditi.
Kako izgleda zahtjev
S adresom https://crm.local/calls i metodom POST telefon šalje ovo. Tijelo je JSON, a zaglavlje je ono koje ste postavili pod Autorizacija:
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 inačicu programa i način na koji je instaliran.
Dolazni poziv, događaj po događaj
Poziv s internog broja 1020 na račun 1002 zvoni, netko se javi, a osoba koja se javila spušta slušalicu četiri sekunde kasnije. Uz sva tri označena događaja primatelj dobiva tri zahtjeva, 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 pozivatelja potražite po number i prikažete karticu kupca. state je ringing-in, a duration_s je 0.
2. Netko se javi: call-state-changed
Otprilike 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 pomaknuo na trenutak promjene, dok callstart_ts ostaje gdje je bio.
3. Završava: call-ended
Nakon č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 tko ga je završio: ovdje local-hangup, jer je slušalicu spustila osoba na ovom telefonu.
Odlazni poziv, događaj po događaj
Isti interni broj zove se s računa 1002: osoba bira 1020, telefon zvoni, druga strana se javlja, razgovara sedam sekundi i spušta slušalicu. Primatelj dobiva četiri zahtjeva, jedan više nego za dolazni poziv, jer odlazni poziv ima vlastito 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 nakon 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 ispunjen, a uri je adresa druge strane kako ju je javio odgovor. duration_s je i dalje 0: broji od ovog trenutka.
4. Završava: call-ended
Sedam sekundi kasnije druga strana spušta slušalicu:
{
"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. Kad spustite slušalicu sami, to je local-hangup, kao kod dolaznog poziva gore.
Stanja jedno uz drugo
| Dolazni poziv | Odlazni poziv | |
|---|---|---|
call-started | ringing-in | dialing |
call-state-changed | active | ringing-out, zatim active |
call-ended | ended | ended |
Polja
Svaka vrijednost je niz znakova, uključujući brojeve i vremenske oznake: "duration_s": "42". Nepoznat trenutak je prazan niz. Nazivi slijede jednu konvenciju: _id je identifikator, _ts je Unix vrijeme u milisekundama (UTC), _s je trajanje u sekundama — isto kao u REST API-ju, gdje su vrijednosti JSON brojevi.
| Polje | Značenje |
|---|---|
event | call-started, call-state-changed ili call-ended. |
id | Poziv: isti UUID kao u GET /calls i /calls/{id}/…, isti u svakom događaju poziva. |
seance_id | Razgovor kojem poziv pripada; pogledajte u nastavku. |
direction | in ili out. |
state | Iste vrijednosti 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. |
number | Broj druge strane. Zapise u CRM-u uparujte po ovom polju. |
name | Ime druge strane iz Kontakata; može biti prazno i može se ispuniti kasnije u pozivu, kao kod odlaznog poziva gore. |
uri | SIP adresa druge strane. |
dialed | Birane znamenke, za odlazni poziv; prazno za dolazni. |
account, account_id | Linija na kojoj je poziv: username@server i identifikator iz GET /accounts. |
event_ts | Kada se događaj dogodio. |
callstart_ts | Kada je telefon prvi put saznao za poziv. |
callstate_ts | Kada je poziv ušao u trenutni state. |
duration_s | Vrijeme razgovora u sekundama, od javljanja do spuštanja. Postavlja se u call-ended za prihvaćeni poziv; inače 0. |
reason | Kako je poziv završio: local-hangup, remote-hangup, busy, no-answer, cancelled…; do tada none. |
answered_by | no ako se na poziv javio čovjek; inače ono što se javilo. |
Jedan razgovor kroz prosljeđivanja
seance_id grupira pozive koji čine jedan razgovor. Poziv upućen ili primljen iznova započinje novi. Poziv nastao prosljeđivanjem, poziv koji zamjenjuje drugi, konzultacija o pozivu i svaki poziv pridružen konferenciji zadržavaju seance_id poziva iz kojeg su nastali.
Između telefona prenosi ga SIP zaglavlje X-Seance-Id: kad se poziv proslijedi kolegi koji također koristi AI Softphone, a centrala zaglavlje prenese dalje, obje radne stanice javljaju isti seance_id.
GET umjesto POST
GET je za primatelje koji ne mogu primiti tijelo zahtjeva, poput starijeg CRM-a ili skriptnog mosta. Ista se polja tada šalju kao parametri upita.
Uz GET adresa može biti predložak: svako [polje] zamjenjuje se vrijednošću tog polja, postotno kodiranom. Primjerice:
https://crm.local/pop?phone=[number]&call=[id]
Rezervirana mjesta koriste gornje nazive polja. Predlošci spremljeni s ranijim nazivima ([accountId], [at], [duration], [answeredBy], [seanceId]) i dalje rade.
Kako se događaji isporučuju
| Ponašanje | Što to znači za vas |
|---|---|
| Događaji idu u red, ne šalju se iz samog poziva | Spor primatelj nikada ne odgađa zvonjenje, pozive ni prosljeđivanja. |
| Pun red odbacuje događaje | Ako vaš primatelj prestane odgovarati, događaji se gube, ali telefon nastavlja raditi. Pratite webhooks_dropped_total. |
| Odbijene i nedostupne isporuke se broje | Rast webhooks_failed_total dok webhooks_delivered_total stoji upućuje na primatelja. |
| Događaji stižu redom | Početak poziva, zatim promjene stanja, zatim kraj poziva. Za redanje spremljenih događaja koristite callstate_ts, a ne vrijeme dolaska. |
| Barem jednom | Isti događaj može stići dvaput. id, event i callstate_ts zajedno identificiraju događaj: neka vaš rukovatelj preskoči onaj koji je već vidio. |
Primanje događaja
Jedino pravilo za primatelja: odmah odgovorite 200, a posao obavite poslije. Spor primatelj ne usporava telefon, ali puni red, a pun red odbacuje događaje.
Primjerice, u Node.js s 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 zabilježite ishod poziva — prihvaćen, propušten, odbijen — uzmite stavku s istim seance_id i number iz GET /history?limit=20 u REST API-ju. Kad se vaša usluga nakon stanke ponovno pokrene, pročitajte GET /history?limit=200 i spremite ono što ste propustili: webhookovi za stvarno vrijeme, povijest za popunjavanje praznina.
Da vidite zahtjeve prije nego što CRM bude spreman, usmjerite Adresa na mrežni preglednik zahtjeva i pritisnite Pošalji probni događaj.
Kad ništa ne stiže
| Simptom | Što provjeriti |
|---|---|
| Nema nijednog webhooka | Pritisnite Pošalji probni događaj. Ako stigne, potrebni događaji nisu označeni; ako ne, adresa je pogrešna ili nedostupna s radne stanice. |
webhooks_failed_total stalno raste | Primatelj odbija zahtjeve ili je nedostupan. Provjerite njegov zapisnik i odgovara li na jednostavan zahtjev s radne stanice. |
webhooks_dropped_total je veći od nule | Primatelj je predugo bio prespor i red se napunio. Najprije odgovorite 200, zatim obrađujte. |
| Isti događaj dvaput | Očekivano kod isporuke barem jednom. Događaje s istim id, event i callstate_ts smatrajte jednim. |