Node.js

Using node.js is a powerful way to interact with the PBX. This page describes how to write a simple script that will interact with the PBX.

Authentication

When using the Basic authentication scheme, you should not use the admininstrator account. Instead create another administrator account and choose a long and random password. It generally makes sense to use an encrypted connection to the PBX to make sure that someone with access to the connection data cannot read the credentials. You need to enable API access for the account to use Basic authentication (starting with version 69).

Instead it would be possible to set up a session and use it with the PBX. However the security gain is limited because instead of the random password the connection will transport the session cookie.

In your code instead of putting in your credentials into your code repository you could use e.g. use a seperate file to store them.

const server = 'https://your.pbx.com'
const username = 'apiaccess'
const password = 'TuAdSfgSd1d'

const authorization = { "Authorization": "Basic " + Buffer.from(`${username}:${password}`).toString('base64') }

Fetching from the REST API

In order to fetch data from the PBX, there are several possibilities, including axios. If you just want to use https you can use the following function to retrieve an object from the PBX:

// Fetch a /rest resource from the PBX:                                                                                                                                                                
const fs = require('fs')
const https = require('https')

const fetchPbx = path => {
    return new Promise((resolve, reject) => {
        const request = https.get(server + path, {headers: authorization}, response => {
            if (response.statusCode >= 400) {
                reject(`Request to ${path} failed with HTTP ${response.statusCode}`)
            }
            else {
                let body = ''
                response.on('data', chunk => body += chunk.toString())
                response.on('end', () => {
                    let object
                    try {
                        object = JSON.parse(body)
                    }
                    catch (e) {
                        reject(`Request to ${path} did not return a JSON object`)
                        return
                    }
                    resolve(object)
                })
            }
        })
        request.on('error', reject)
        request.end()
    })
}

Whitelisting on the SBC

If the address from where your requests are coming from are fixed, you should white list those addresses on the SBC to avoid accidential blocking of the address. Also, you can associate that address with the administrator account that you are using for authentication, which serves as additional safeguard against leaking out of the authentication information.

Example: Fetching tenant information

The following example shows how to fetch the list of current tenants on the PBX.

// Check what domains are available:
const getDomains = async () => {
    let all = []
    try {
        const total = await fetchPbx('/rest/system/domaininfo?size=all')
        if (typeof total != 'number') return total; // Old API
    
        for (let i = 0; i < total; i += 25) {
            const page = await fetchPbx('/rest/system/domaininfo?size=25&page=' + ((i / 25) + 1))
            for (let j = 0; j < page.length; j++) all.push(page[j]);
        }
    }
    catch (e) {
        console.log('Could not load tenant list')
    }
    return all
}