Getting started

In a few minutes: an API key, your first request and your first extension.

1. Create an API key

In the control panel open Developers and click New key:

give it a recognizable name (e.g. "CRM integration");
choose only the permissions you need (read permissions are enough to start);
optional: restrict the IP addresses the key can be used from and set an expiry date.

The full key (exo_live_…) is shown only once: store it in a secrets manager or an environment variable, never in source code.

Test keys: exo_test_… keys work like exo_live_… keys and help you tell integrations under development apart in the usage log.

2. Install the SDK (optional)

Download the archive for your language from SDKs and install it, or use cURL or any HTTP client.

# 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_KEY

3. First request

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"])

If the response is 401, check that the key is complete and active; if it is 403 SCOPE_MISSING, the key lacks the permission required by the endpoint (listed in each guide and in the Swagger reference).

4. Create an extension

Requires the extensions:write scope.

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"]

The SIP password is returned only on creation and regeneration: configure it on the phone right away, or retrieve the full credentials with GET /v1/extensions/:id/sip-credentials.

5. Follow calls in real time

With the live:read scope:

# -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"])

Next steps

Authentication: scopes, roles, global keys.
Conventions: pagination, errors, limits, idempotency.
Webhooks: events sent to your systems.

Getting started

#1. Create an API key

#2. Install the SDK (optional)

#3. First request

#4. Create an extension

#5. Follow calls in real time

#Next steps

1. Create an API key

2. Install the SDK (optional)

3. First request

4. Create an extension

5. Follow calls in real time

Next steps