Vai al contenuto principale

Webhook

Un webhook è una richiesta che il telefono invia a un indirizzo a sua scelta ogni volta che a una chiamata succede qualcosa. È così che un CRM può aprire la scheda del cliente prima del secondo squillo, registrare una chiamata quando finisce o accendere una spia su un pannello a parete. Un webhook non richiede regole del firewall in ingresso: è il telefono a chiamare lei. Poiché le richieste partono dalla postazione di lavoro, l'indirizzo deve solo essere raggiungibile da quel computer — un indirizzo interno http://crm.local/calls funziona come un indirizzo HTTPS pubblico.

I webhook sono spenti dopo l'installazione, finché non li attiva. Funzionano insieme all'API REST locale: un evento dice che qualcosa è cambiato, l'API dà i dettagli attuali.

Attivarli​

Apra Impostazioni → Integrazione. Webhook è la prima sezione della scheda.

  1. Spunti Raccontare a un altro sistema delle chiamate. Viene inviata una richiesta per ogni evento spuntato qui sotto.
  2. Inserisca l'Indirizzo che deve ricevere gli eventi, per esempio https://crm.local/calls.
  3. Scelga il Metodo: POST (il predefinito) o GET.
  4. In Eventi spunti che cosa inviare: Una nuova chiamata, Una chiamata che finisce, Una chiamata che cambia stato.
  5. Facoltativamente, in Autorizzazione, imposti un'intestazione che il suo ricevitore può verificare: un Nome dell'intestazione (viene suggerito Authorization) e un Valore dell'intestazione. Il valore è conservato nel portachiavi del computer, mai in un file di impostazioni; una volta salvato, il campo mostra Salvato — digiti per sostituirlo.
  6. Prema Invia un evento di prova per vedere che arrivi. Invia un evento di una chiamata mai avvenuta, con le stesse intestazioni di uno vero. Registri la richiesta grezza e costruisca il suo ricevitore su ciò che la sua versione invia davvero.

La parte del programma che invia le richieste è il modulo Integrazione; si può disattivare in Moduli.

Gli eventi​

Spuntato comeEventoInviato quando
Una nuova chiamatacall-startedUna chiamata in arrivo inizia a squillare o parte una chiamata in uscita.
Una chiamata che cambia statocall-state-changedCambia lo state della chiamata: riceve risposta, viene messa in attesa o ripresa da una delle due parti, oppure entra in una conferenza o ne esce. Silenziare non lo invia.
Una chiamata che finiscecall-endedLa chiamata è finita.

Ogni evento si può spuntare da solo. Una scheda che si apre alla chiamata ha bisogno solo del primo; un registro chiamate solo dell'ultimo. call-started viene inviato per primo e va gestito in fretta.

Com'è fatta la richiesta​

Con l'indirizzo https://crm.local/calls e il metodo POST, il telefono invia questo. Il corpo è JSON, e l'intestazione è quella impostata in Autorizzazione:

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

Lo User-Agent porta la versione del programma e il modo in cui è stato installato.

Una chiamata in arrivo, evento per evento​

Una chiamata dall'interno 1020 all'account 1002 squilla, riceve risposta, e chi ha risposto riaggancia quattro secondi dopo. Con tutti e tre gli eventi spuntati, il ricevitore riceve tre richieste, una dopo l'altra. Portano tutte lo stesso id e lo stesso seance_id.

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

È il momento di cercare chi chiama tramite number e mostrare la scheda del cliente. state è ringing-in e duration_s è 0.

2. Riceve risposta: call-state-changed​

Circa tre secondi dopo:

{
"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 è ora active, e callstate_ts è passato al momento del cambiamento mentre callstart_ts resta dov'era.

3. Finisce: call-ended​

Quattro secondi di conversazione dopo:

{
"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 è la durata della conversazione e reason dice chi l'ha chiusa: qui local-hangup, perché ha riagganciato la persona a questo telefono.

Una chiamata in uscita, evento per evento​

Lo stesso interno viene chiamato dall'account 1002: la persona compone 1020, il telefono squilla, l'altra parte risponde, parla per sette secondi e riaggancia. Il ricevitore riceve quattro richieste, una in più rispetto a una chiamata in arrivo, perché una chiamata in uscita ha uno stato proprio mentre squilla dall'altra parte.

1. Viene composta: 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 e dialed contiene il numero così come è stato composto. Il telefono non conosce ancora il nome dell'interlocutore, perciò name è vuoto.

2. Squilla dall'altra parte: call-state-changed​

Mezzo secondo dopo:

{
"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. L'altra parte risponde: call-state-changed​

Quattro secondi dopo:

{
"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. Il name ora è compilato, e l'uri è l'indirizzo dell'interlocutore come l'ha riportato la risposta. duration_s è ancora 0: conta da questo momento.

4. Finisce: call-ended​

Sette secondi dopo l'altra parte riaggancia:

{
"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, e reason è remote-hangup, perché ha chiuso la chiamata l'altra parte. Quando riaggancia lei, è local-hangup, come nella chiamata in arrivo sopra.

Gli stati, fianco a fianco​

Chiamata in arrivoChiamata in uscita
call-startedringing-indialing
call-state-changedactiveringing-out, poi active
call-endedendedended

I campi​

Ogni valore è una stringa, numeri e marcature temporali compresi: "duration_s": "42". Un momento non noto è una stringa vuota. I nomi seguono una convenzione: _id è un identificativo, _ts è tempo Unix in millisecondi (UTC), _s è una durata in secondi — come nell'API REST, dove i valori sono numeri JSON.

CampoSignificato
eventcall-started, call-state-changed o call-ended.
idLa chiamata: lo stesso UUID di GET /calls e /calls/{id}/…, e lo stesso in ogni evento della chiamata.
seance_idLa conversazione a cui appartiene la chiamata; veda sotto.
directionin o out.
stateGli stessi valori di GET /calls: dialing, ringing-out, ringing-in, active, hold (messa in attesa da questo telefono), onhold (messa in attesa dall'interlocutore), conference o ended.
numberIl numero dell'interlocutore. Faccia corrispondere i record del suo CRM su questo campo.
nameIl nome dell'interlocutore, dai Contatti; può essere vuoto, ed essere compilato più tardi nella chiamata, come nella chiamata in uscita sopra.
uriL'indirizzo SIP dell'interlocutore.
dialedLe cifre composte, per una chiamata in uscita; vuoto per una in arrivo.
account, account_idLa linea su cui passa la chiamata: username@server, e l'identificativo di GET /accounts.
event_tsQuando è avvenuto l'evento.
callstart_tsQuando il telefono ha saputo per la prima volta della chiamata.
callstate_tsQuando la chiamata è entrata nel suo state attuale.
duration_sTempo di conversazione in secondi, dalla risposta al riaggancio. Impostato su call-ended per una chiamata con risposta; 0 altrimenti.
reasonCome è finita la chiamata: local-hangup, remote-hangup, busy, no-answer, cancelled…; none fino ad allora.
answered_byno se ha risposto una persona; altrimenti che cosa ha risposto.

Una conversazione attraverso i trasferimenti​

seance_id raggruppa le chiamate che formano una conversazione. Una chiamata fatta o ricevuta da zero ne inizia una nuova. Una chiamata creata da un trasferimento, una chiamata che ne sostituisce un'altra, una consultazione su una chiamata e ogni chiamata unita in una conferenza mantengono il seance_id della chiamata da cui provengono.

Tra telefoni viaggia nell'intestazione SIP X-Seance-Id: quando una chiamata viene trasferita a un collega che usa anch'egli AI Softphone, e il centralino inoltra l'intestazione, entrambe le postazioni riportano lo stesso seance_id.

GET invece di POST​

GET è per i ricevitori che non possono accettare un corpo della richiesta, come un CRM più vecchio o uno script ponte. Gli stessi campi vengono allora inviati come parametri della query.

Con GET l'indirizzo può essere un modello: ogni [campo] viene sostituito dal valore di quel campo, codificato con il percento. Per esempio:

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

I segnaposto usano i nomi dei campi sopra. I modelli salvati con i nomi precedenti ([accountId], [at], [duration], [answeredBy], [seanceId]) continuano a funzionare.

Come vengono consegnati gli eventi​

ComportamentoChe cosa significa per lei
Gli eventi vengono messi in coda, non inviati dalla chiamata stessaUn ricevitore lento non ritarda mai squilli, chiamate o trasferimenti.
Una coda piena scarta eventiSe il suo ricevitore smette di rispondere, si perdono eventi ma il telefono continua a funzionare. Tenga d'occhio webhooks_dropped_total.
Le consegne rifiutate e non riuscite vengono contatewebhooks_failed_total che sale mentre webhooks_delivered_total resta fermo indica il ricevitore.
Gli eventi arrivano in ordineChiamata iniziata, poi i cambi di stato, poi chiamata finita. Per ordinare gli eventi salvati usi callstate_ts, non l'ora in cui sono arrivati.
Almeno una voltaLo stesso evento può arrivare due volte. id, event e callstate_ts insieme identificano un evento: faccia in modo che il suo gestore salti quello già visto.

Ricevere gli eventi​

L'unica regola per un ricevitore: rispondere 200 subito, e fare il lavoro dopo. Un ricevitore lento non rallenta il telefono, ma riempie la coda, e una coda piena scarta eventi.

Per esempio, in Node.js con 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);

Per registrare l'esito di una chiamata — con risposta, persa, rifiutata — prenda la voce con lo stesso seance_id e number da GET /history?limit=20 dell'API REST. Quando il suo servizio riparte dopo una pausa, legga GET /history?limit=200 e salvi ciò che ha perso: i webhook per il tempo reale, la cronologia per colmare i vuoti.

Per vedere le richieste prima che il CRM sia pronto, punti l'Indirizzo a un ispettore di richieste online e prema Invia un evento di prova.

Quando non arriva nulla​

SintomoChe cosa controllare
Nessun webhookPrema Invia un evento di prova. Se arriva, gli eventi che le servono non sono spuntati; se no, l'indirizzo è sbagliato o non raggiungibile dalla postazione.
webhooks_failed_total continua a salireIl ricevitore rifiuta le richieste o non è raggiungibile. Controlli il suo registro, e se risponde a una richiesta semplice dalla postazione.
webhooks_dropped_total è maggiore di zeroIl ricevitore è stato troppo lento troppo a lungo e la coda si è riempita. Risponda prima 200, poi elabori.
Lo stesso evento due voltePrevisto con la consegna almeno una volta. Tratti come uno solo gli eventi con lo stesso id, event e callstate_ts.