Primi passi
In pochi minuti: chiave API, prima richiesta e primo interno creato.
1. Crea una chiave API
Nel pannello apri Sviluppatori e premi Nuova chiave:
- dai un nome riconoscibile (es. "Integrazione CRM");
- scegli solo i permessi che servono (per iniziare bastano quelli di lettura);
- facoltativo: limita gli indirizzi IP da cui la chiave può essere usata e imposta una scadenza.
La chiave completa (exo_live_…) viene mostrata una sola volta: salvala in un gestore di segreti o in una variabile d'ambiente, mai nel codice sorgente.
Chiavi di prova: le chiavi exo_test_… funzionano come quelle exo_live_… e servono a distinguere le integrazioni in sviluppo nel registro di utilizzo.
2. Installa l'SDK (facoltativo)
Scarica l'archivio del tuo linguaggio da SDK e installalo, oppure usa cURL o qualsiasi client HTTP.
# Nessuna installazione: cURL e la chiave API in una variabile d'ambiente
export EXOPBX_API_KEY="exo_live_..."// npm install ./exopbx-sdk-typescript (archivio typescript.zip)
import { ExoPBX } from '@exobyte/exopbx-sdk';
const pbx = new ExoPBX({ apiKey: process.env.EXOPBX_API_KEY });// composer config repositories.exopbx path ./exopbx-sdk-php && composer require exobyte/exopbx-sdk
require 'vendor/autoload.php';
use Exobyte\ExoPBX\Client;
$pbx = new Client(['apiKey' => getenv('EXOPBX_API_KEY')]);# pip install ./exopbx-sdk-python
import os
from exopbx import ExoPBX
pbx = ExoPBX(api_key=os.environ["EXOPBX_API_KEY"]) # oppure ExoPBX() legge EXOPBX_API_KEY3. Prima richiesta
curl -s https://centralino.exovoip.it/api/v1/tenants/current \
-H "X-API-Key: $EXOPBX_API_KEY"const { tenant } = await pbx.tenants.current();
console.log(tenant.name, tenant.status);$out = $pbx->tenants->current();
echo $out['tenant']['name'], PHP_EOL;tenant = pbx.tenants.current()["tenant"]
print(tenant["name"], tenant["status"])Se la risposta è 401, controlla che la chiave sia completa e attiva; se è 403 SCOPE_MISSING, la chiave non ha il permesso richiesto dall'endpoint (indicato in ogni guida e nel riferimento Swagger).
4. Crea un interno
Serve lo scope extensions:write.
curl -s -X POST https://centralino.exovoip.it/api/v1/extensions \
-H "X-API-Key: $EXOPBX_API_KEY" -H "Content-Type: application/json" \
-d '{"number":"105","name":"Giulia Verdi","email":"giulia.verdi@example.com",
"voicemail":{"enabled":true,"email":"giulia.verdi@example.com"}}'const { extension, sipPassword } = await pbx.extensions.create({
number: '105',
name: 'Giulia Verdi',
email: 'giulia.verdi@example.com',
voicemail: { enabled: true, email: 'giulia.verdi@example.com' },
});
// sipPassword: mostrata solo ora (rigenerabile con extensions.resetPassword)$out = $pbx->extensions->create([
'number' => '105',
'name' => 'Giulia Verdi',
'email' => 'giulia.verdi@example.com',
'voicemail' => ['enabled' => true, 'email' => 'giulia.verdi@example.com'],
]);
$sipPassword = $out['sipPassword'];out = pbx.extensions.create({
"number": "105",
"name": "Giulia Verdi",
"email": "giulia.verdi@example.com",
"voicemail": {"enabled": True, "email": "giulia.verdi@example.com"},
})
sip_password = out["sipPassword"]La password SIP è restituita solo alla creazione e alla rigenerazione: configurala subito sul telefono o recupera le credenziali complete con GET /v1/extensions/:id/sip-credentials.
5. Segui le chiamate in tempo reale
Con lo scope live:read:
# -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"const live = pbx.live.stream({ types: ['channel.update', 'channel.hangup', 'calendar.override'] });
live.on('snapshot', (s) => console.log('stato iniziale', s.channels.length));
live.on('channel.update', (e) => console.log(e.channel.callerNumber, e.channel.state));
live.on('calendar.override', (e) => console.log(e.name, e.forceState, e.state));
// oppure: for await (const event of live) { ... }
// live.close() per chiudere$pbx->live->stream(function (array $event): bool {
if ($event['type'] === 'channel.update') {
echo $event['channel']['callerNumber'] ?? '-', ' ', $event['channel']['state'], PHP_EOL;
}
return true; // false per fermarsi
}, ['channel.update', 'channel.hangup', 'calendar.override']);for event in pbx.live.stream(types=["channel.update", "channel.hangup", "calendar.override"]):
if event["type"] == "channel.update":
print(event["channel"]["callerNumber"], event["channel"]["state"])Passi successivi
- Autenticazione: scope, ruoli, chiavi globali.
- Convenzioni: paginazione, errori, limiti, idempotenza.
- Webhook: eventi inviati ai tuoi sistemi.