ExoVoIPManuale sviluppatori

Tempo reale

Stato del centralino in tempo reale: chiamate in corso, interni e telefoni collegati, linee, code, parcheggio e stato del servizio. Disponibile con richieste REST (fotografia dello stato) ed eventi SSE o WebSocket (aggiornamenti). Scope live:read.

Fotografia dello stato

curl -s https://centralino.exovoip.it/api/v1/live/snapshot -H "X-API-Key: $EXOPBX_API_KEY"
curl -s https://centralino.exovoip.it/api/v1/live/extensions -H "X-API-Key: $EXOPBX_API_KEY"
EndpointContenuto
GET /v1/live/snapshotTutto in una chiamata: chiamate, interni, linee, code, parcheggio, salute
GET /v1/live/channelsChiamate in corso
GET /v1/live/extensionsInterni: stato, registrazione, disponibilità, "non disturbare", dispositivi
GET /v1/live/devicesUn elemento per telefono registrato (IP, user agent, latenza, raggiungibilità)
GET /v1/live/trunksLinee: registrazione, raggiungibilità, chiamate attive
GET /v1/live/queuesCode: chiamanti in attesa, attesa massima, operatori
GET /v1/live/healthStato del servizio: operational, degraded, outage

Disponibilità di un interno (availability): available, ringing, busy, on_hold, dnd, unreachable (registrato ma non risponde), offline (nessun telefono registrato).

Eventi (SSE)

GET /v1/live/events mantiene aperta la connessione e invia un evento per ogni cambiamento. Alla connessione arriva uno snapshot completo, poi solo le variazioni; ogni 15 secondi un heartbeat. Con ?types= si ricevono solo i tipi indicati (snapshot e heartbeat arrivano sempre).

# -N disattiva il buffer: gli eventi arrivano appena accadono
curl -N "https://centralino.exovoip.it/api/v1/live/events?types=channel.update,channel.hangup,calendar.override" \
  -H "X-API-Key: $EXOPBX_API_KEY"

Gli SDK si riconnettono automaticamente con attese crescenti e, dopo ogni riconnessione, ricevono un nuovo snapshot: usalo come stato di riferimento invece di accumulare le variazioni. Una chiave non valida o senza permessi interrompe il flusso senza nuovi tentativi.

Eventi (WebSocket)

GET /v1/live/ws invia gli stessi eventi, uno per messaggio JSON. L'SSE resta il canale consigliato; il WebSocket è utile negli ambienti che lo preferiscono.

# WebSocket: stessi eventi dell'SSE, un evento JSON per messaggio
websocat -H "X-API-Key: $EXOPBX_API_KEY" "wss://centralino.exovoip.it/api/v1/live/ws?types=extension.state"

Nel browser i WebSocket e EventSource non possono inviare header: funzionano con la sessione del pannello. Le chiavi API vanno usate solo lato server.

Tipi di evento

TipoQuando
snapshotConnessione o riallineamento
channel.updateNuova chiamata, cambio di stato, risposta, attesa, registrazione, collegamento
channel.hangupFine di una chiamata (causa, durata)
extension.stateQualsiasi cambio di stato di un interno
extension.registrationPrimo telefono registrato / ultimo scollegato
extension.contactTelefono aggiunto, rimosso, raggiungibile o non raggiungibile
trunk.stateRegistrazione, raggiungibilità o chiamate attive di una linea
queue.caller.join / queue.caller.leaveChiamante entra / esce dalla coda (risposto, abbandonato, uscito)
queue.memberStato o pausa di un operatore
parking.updateChiamata parcheggiata, ripresa, scaduta o abbandonata
calendar.overrideForzatura degli orari (pannello, API, telefono, scadenza)
system.statusCambio dello stato del servizio
heartbeatOgni 15 secondi

Solo per la piattaforma: system.asterisk, system.service, system.reload.

Esempio di evento:

{
  "type": "calendar.override",
  "tenantId": 3,
  "calendarId": 4,
  "name": "Ufficio",
  "forceState": "closed",
  "forceUntil": "2026-11-04T12:00:00.000Z",
  "previousForceState": "auto",
  "state": "closed"
}

Lo schema completo di ogni evento (campi e valori) è nel riferimento Swagger, alla voce GET /v1/live/events.

Vista globale

Per una chiave globale senza X-Tenant-Id (o ?tenantId=) gli eventi e le fotografie riguardano tutte le aziende; ogni oggetto riporta il tenantId.

Endpoint

DescrizioneRichiestaScopeMetodo SDK
Fotografia completa in tempo reale (chiamate, interni, linee, code, parcheggio, stato servizio)GET /v1/live/snapshotlive:readlive.snapshot()
Chiamate in corsoGET /v1/live/channelslive:readlive.channels()
Stato interni (registrazione, disponibilità, dispositivi)GET /v1/live/extensionslive:readlive.extensions()
Dispositivi registrati (IP, porta, trasporto, latenza, raggiungibilità)GET /v1/live/deviceslive:readlive.devices()
Stato linee (registrazione, raggiungibilità, chiamate attive)GET /v1/live/trunkslive:readlive.trunks()
Code: chiamanti in attesa e stato operatoriGET /v1/live/queueslive:readlive.queues()
Stato del servizio (dettaglio tecnico solo piattaforma)GET /v1/live/healthlive:readlive.health()
Eventi in tempo reale (SSE), filtrabili con ?types=GET /v1/live/eventslive:readlive.stream()
Eventi in tempo reale (WebSocket), filtrabili con ?types=GET /v1/live/wslive:readlive.websocket() (TS)