ExoVoIPManuale sviluppatori

Server voce

Le chiamate dei clienti passano dal server principale o da uno o più server voce aggiuntivi, gestiti dalla piattaforma. Questa sezione è riservata alla piattaforma (superadmin o chiavi globali con scope system:* e tenants:*).

Aggiungere un server voce

  1. POST /v1/voice-nodes con name (e, se disponibile, sipHost: il nome a dominio del server). La risposta contiene enrollment.code (codice di attivazione monouso, valido 24 ore) e enrollment.installCommand: sono mostrati una sola volta.
  2. Sul nuovo server (Ubuntu 22.04 o 24.04) si esegue il comando di installazione. Al termine il server si registra da solo e passa allo stato online.
curl -fsSL https://centralino.exovoip.it/api/v1/nodes/install.sh | sudo bash -s -- --token EXO-XXXX-XXXX-XXXX-XXXX --domain tel2.exovoip.it

Con --domain il server ottiene un certificato e abilita cifratura (SIP TLS) e telefono nel browser (WebRTC). Senza dominio funziona in UDP/TCP e health.warnings riporta che WebRTC e TLS non sono disponibili.

Stato

GET /v1/voice-nodes restituisce per ogni server state (pending, online, degraded, offline, disabled), indirizzo (sipHost, publicIp), connessioni sicure (tlsEnabled, webrtcEnabled), versioni, numero di aziende ospitate e l'ultimo stato inviato (health: centralino, chiamate attive, servizi, certificato, risorse, avvisi). Un server che non comunica da oltre 3 minuti è offline.

Lo stesso riepilogo è in GET /v1/live/health (campo platform.voiceNodes).

Assegnare le aziende

PUT /v1/tenants/:id/voice-node con voiceNodeId (null = server principale) e, facoltativo, sipHost (indirizzo personalizzato per i telefoni dell'azienda). La risposta indica effectiveSipHost, l'indirizzo che i telefoni useranno, e webrtcAvailable.

Le credenziali dei telefoni (GET /v1/extensions/:id/sip-credentials) seguono automaticamente l'assegnazione: indirizzo personalizzato → dominio del server voce → IP del server voce → indirizzo del server principale. Quando il telefono nel browser non è disponibile wssUrl è vuoto.

Reinstallare, disattivare, eliminare

  • POST /v1/voice-nodes/:id/enrollment-code: nuovo codice per reinstallare o sostituire il server; il server attuale resta collegato finché il codice non viene usato.
  • POST /v1/voice-nodes/:id/revoke: disattiva subito il server e ne revoca le credenziali.
  • DELETE /v1/voice-nodes/:id: solo se non ospita aziende (altrimenti 409 CONFLICT).

Endpoint

DescrizioneRichiestaScopeMetodo SDK
Server voce collegati e statoGET /v1/voice-nodessystem:readvoiceNodes.list() · py: voice_nodes.list()
Aggiunge un server voce (codice di attivazione mostrato una volta)POST /v1/voice-nodessystem:writevoiceNodes.create() · py: voice_nodes.create()
Dettaglio server voceGET /v1/voice-nodes/:idsystem:readvoiceNodes.get() · py: voice_nodes.get()
Modifica nome, host SIP, notePATCH /v1/voice-nodes/:idsystem:writevoiceNodes.update() · py: voice_nodes.update()
Elimina server voce (solo senza aziende assegnate)DELETE /v1/voice-nodes/:idsystem:writevoiceNodes.delete() · py: voice_nodes.delete()
Nuovo codice di attivazione (installazione o reinstallazione)POST /v1/voice-nodes/:id/enrollment-codesystem:writevoiceNodes.enrollmentCode() · py: voice_nodes.enrollment_code()
Disattiva il server voce e ne revoca le credenzialiPOST /v1/voice-nodes/:id/revokesystem:writevoiceNodes.revoke() · py: voice_nodes.revoke()