PbxAdminApi

The PbxAdminApi protocol is available on AppWebsocket connections to innovaphone PBX objects, if the object is enabled for the PbxAdminApi. It allows the App to perform all kind of administration and configuration tasks.

General structure

{
    "api": "PbxAdminApi",
    "src": string,
    "mt": string,
}

api
To address this interface the value "PbxAdminApi" has to be used for the api property
src
The AppWebsocket src mechanism is supported on the interface. So a src property may be used
mt
The message type identifies the requested operation

In general operatinos are performed by sending a message with a message type <name> to the PBX. The result is returned with a message with message type <name>Result. If the operation turns on monitoring of some kind the updates are sent with messages with message type <name>Info.

Operations
Objects - recurring definitions

MonitorAdminObject

{
    "api": "PbxAdminApi",
    "mt": "MonitorAdminObject"
}

Start monitoring of the admin object. The admin object is used to store the pwd key pair used to encrypt all passwords inside PBX objects

{
    "api": "PbxAdminApi",
    "mt": "MonitorAdminObjectResult"
}

Message sent back to confirm start of the monitoring

{
    "api": "PbxAdminApi",
    "mt": "MonitorAdminObjectInfo"
    "pwd": string
    "key": string
}

Message sent back whenever the admin object changes

pwd
The password of the admin object, encrypted using 'key'
key
The key used to encrypt all passwords, encrypted with 'pwd'

MonitorConfig

{
    "api": "PbxAdminApi",
    "mt": "MonitorConfig",
    "stop": boolean
}

Start/stop monitoring of the local PBX config.

stop
If present and true, it stops a monitoring started before
{
    "api": "PbxAdminApi",
    "mt": "MonitorConfigResult"
}

Message sent back to confirm start of the monitoring

{
    "api": "PbxAdminApi",
    "mt": "MonitorConfigInfo"
    "domain": string
    "pbx": string
    "dns": string
    "ip4": string
}

Message whenever the local config changes

pbx
The PBX name
dns
The PBX DNS name as configured.
ip4
The local PBX ip4 address.

MonitorUnallowed

{
    "api": "PbxAdminApi",
    "mt": "MonitorUnallowed",
    "stop": boolean
}

Start/stop monitoring of the local PBX config.

stop
If present and true, it stops a monitoring started before
{
    "api": "PbxAdminApi",
    "mt": "MonitorUnallowedResult"
}

Message sent back to confirm start of the monitoring

{
    "api": "PbxAdminApi",
    "mt": "MonitorUnallowedAdd",
    "user": string,
    "srcs": [src]
}

Message whenever a new unallowed subscription is created

name
The SIP URI/H.323 Id of the user to which the subscription is sent
srcs
An array of objects, which describe the source of the subscription. These objects have a property "name" for the name of the source and an optional boolean property "grp". If grp is present and true the "name" identifies a group, otherwise it is the SIP URI/H.323 Id of a user.
{
    "api": "PbxAdminApi",
    "mt": "MonitorUnallowedDel",
    "user": string,
    "srcs": [src]
}

Message whenever a new unallowed subscription is removed

UpdateObject

{
    "api": "PbxAdminApi",
    "mt": "UpdateObject",
    "guid": string,
    "cn": string,
    "dn": string,
    "h323": string,
    "e164": string,
    "pwd": string,
    "loc": string,
    "node": string,
    "ext": string,
    "config": string,
    "apps": string,
    "filter": string,
    "cd-filter": string,
    "push": string,
    "messages": string,
    "hide": boolean,
    "critical": boolean,
    "cfnr": unsigned,
    "colr": bool,
    "uclic": bool,
    "voicemail": bool,
    "fax": bool,
    "mobility": bool,
    "mypbx": bool,
    "video": bool,
    "app-sharing": bool,
    "reporting": bool,
    "devices": [device],
    "grp": [group],
    "presence": [presence],
    "cds": [diversion],
    "wakeups": [wakeup],
    "gws": [gw],
    "pseudo": pseudo,
    "phone": phone,
    "copyPwd": string
}

Update or create a PBX object. Any property present in the message updates the respective information of the PBX object. Properties not present are left unchanged.

If bool properties are sent as integers (e.g -1), the parameter is deleted, which means the value inherited from a config template is used

guid
The guid of the object as hexstring. Must be present when updating the object. If the object is to be created, should be omitted completely. There are special values for the guid:
*
This means the cn is used to identify an object, which shall be updated.
?
This means the cn is used to identify an object, which shall be updated, however, if no object is found, a new one will be created.
empty
A missing or empty guid parameter should be used to create an object. In this case guid of the created object will be returned in the UpdateObjectResult.
cn
The 'cn' or 'Long Name'.
dn
The display name.
h323
The H.323 id or SIP URI user part.
e164
The number.
pwd
The cleartext object password.
loc
The PBX to which this object is assigned
node
The numbering node
ext
The external number
config
Name of the config template used by the object.
apps
Comma separated list of all Apps, which can be accessed by this user.
filter
Name of the filter, which shall be applied to calls made by this user
cd-filter
Name of the filter, which shall be applied by call diversions made by this user
push
Name of the Push object, to be used for calls to this object.
messages
Name of the Messages object, to be used to store chat messages of this user.
hide
The object is marked as "Hide from LDAP".
critical
The object is marked as "Critical".
cfnr
No response timeout.
colr
If true no connected number is sent for calls to this object.
uclic
A UC license shall be acquired for this object.
voicemail
A Voicemail license shall be acquired for this object.
fax
A Fax license shall be acquired for this object.
mobility
A Mobility license shall be acquired for this object.
mypbx
A myPBX license shall be acquired for this object.
video
A Video license shall be acquired for this object.
app-sharing
A App Sharing license shall be acquired for this object.
reporting
A Reporting license shall be acquired for this object.
devices
Array of device configurations
grp
Array of group configurations
presence
Array of presence information items
cds
Array of call diversion configurations
wakeups
Array of wakeups
pseudo
Pseudo object configuration
phone
Phone configuration
copyPwd
If set, the password for this object is set the same as the password identified by this property as h323. This can not be used for objects of type "user" (no pseudo configuration) or executive.
{
    "api": "PbxAdminApi",
    "mt": "UpdateObjectResult",
    "guid": "1234567890abcdef1234567890abcdef"
}

Sent, when the object is updated, which means it is written to the database and the update is in effect in the PBX. The guid is delivered only if no guid was submitted with the UpdateObject request and a new object is created.

GetObject

{
    "api": "PbxAdminApi",
    "mt": "GetObject",
    "guid": string,
    "cn": string,
	"h323": string
}

Request the configuration data for an object

guid
Hex string of the guid of the object
cn
If no guid is present, the cn (Long Name) can be used to identify the object
h323
If no guid and no cn is present, the h323-id (Name) can be used to identify the object
{
    "api": "PbxAdminApi",
    "mt": "GetObjectResult",
    "guid": string,
    "cn": string,
    "dn": string,
    "h323": string,
    "e164": string,
    "pwd": string,
    "loc": string,
    "node": string,
    "ext": string,
    "h323-email": boolean,
    "emails": [email],
    "config": string,
    "apps": string,
    "filter": string,
    "cd-filter": string,
    "push": string,
    "messages": string,
    "hide": boolean,
    "critical": boolean,
    "no-dev": boolean,
    "cfnr": unsigned,
    "colr": bool,
    "uclic": bool,
    "voicemail": bool,
    "fax": bool,
    "mobility": bool,
    "mypbx": bool,
    "video": bool,
    "app-sharing": bool,
    "reporting": bool,
    "devices": [device],
    "grp": [group],
    "presence": [presence],
    "cds": [diversion],
    "wakeups": [wakeup],
    "gws": [gw],
    "pseudo": pseudo,
    "phone": phone,
    "copyPwd": string
}
guid
The guid of the object as hexstring.
cn
The 'cn' or 'Long Name'.
dn
The display name.
h323
The H.323 id or SIP URI user part.
e164
The number.
pwd
The password encrypted by key of the admin object
loc
The PBX to which this object is assigned
node
The numbering node
ext
The external number
h323-email
True, if the SIP URI of the user can also be used as an email address.
emails
Array of additional email addresses.
config
Name of the config template used by the object.
apps
Comma separated list of all Apps, which can be accessed by this user.
filter
Name of the filter, which shall be applied to calls made by this user
cd-filter
Name of the filter, which shall be applied by call diversions made by this user
push
Name of the Push object, to be used for calls to this object.
messages
Name of the Messages object, to be used to store chat messages of this user.
hide
The object is marked as "Hide from LDAP".
critical
The object is marked as "Critical".
cfnr
No response timeout.
colr
If true no connected number is sent for calls to this object.
uclic
A UC license shall be acquired for this object.
voicemail
A Voicemail license shall be acquired for this object.
fax
A Fax license shall be acquired for this object.
mobility
A Mobility license shall be acquired for this object.
mypbx
A myPBX license shall be acquired for this object.
video
A Video license shall be acquired for this object.
app-sharing
A App Sharing license shall be acquired for this object.
reporting
A Reporting license shall be acquired for this object.
devices
Array of device configurations
cds
Array of call diversion configurations
pseudo
Pseudo object configuration

GetNormalizedNumber


    {
    "api": "PbxAdminApi",
    "mt": "GetNormalizedNumber",
    "guid": string,
    "cn": string,
    "h323": string,
    "from-guid": string,
    "from-cn": string,
    "from-h323": string
    }

Get the normalized phone number. guid, cn or h323 must be sent to specify the user. If from-guid, from-cn or from-h323 are also sent, then the relative number will be returned.


    {
    "api": "PbxAdminApi",
    "mt": "GetNormalizedNumberResult",
    "number": string
    }
number
The prefix node followed by the extension

GetPbxConfig

{
    "api": "PbxAdminApi",
    "mt": "GetPbxConfig",
}

Request some of the local PBX config info

{
    "api": "PbxAdminApi",
    "mt": "GetPbxConfigResult",
    "loc": string
}
loc
The name of the local PBX

GetPbxLicenses

{
    "api": "PbxAdminApi",
    "mt": "GetPbxLicenses",
}

Request all local PBX license info

{
    "api": "PbxAdminApi",
    "mt": "GetPbxLicensesResult",
    "lic": [
        {
            "count": "0",
            "local": "3",
            "name": "Port",
            "slaves": "0",
            "used": "3",
            "version": "13"
        },
        {
            "count": "0",
            "local": "0",
            "name": "Standby",
            "slaves": "0",
            "used": "0",
            "version": "13"
        }
    ]
}
lic
The array with license objects. The license information supplied here corresponds to the list of local licenses in the general PBX configuration overview.

GetPhoneConfig

{
    "api": "PbxAdminApi",
    "mt": "GetPhoneConfig",
    "guid": string,
    "cn": string
}

Request the phone config from an object identified by guid, or if not present by cn

{
    "api": "PbxAdminApi",
    "mt": "GetPhoneConfigResult",
    "phone": phone
}

Returns the phone config

GetRegs

{
    "api": "PbxAdminApi",
    "mt": "GetRegs",
    "guid": string,
    "cn": string
}

Request the current registrations to an object identified by guid, or if not present by cn

{
    "api": "PbxAdminApi",
    "mt": "GetRegsResult",
    "regs": [reg],
    "cn": string
}

Returns an array of objects decribing the registrations

DeleteObject

{
    "api": "PbxAdminApi",
    "mt": "DeleteObject",
    "guid": string
}

Request to delete an object identified by guid.

{
    "api": "PbxAdminApi",
    "mt": "DeleteObjectResult"
}

Returned when the delete request was accepted.

GetAppObjects

{
    "api": "PbxAdminApi",
    "mt": "GetAppObjects",
    "uri": string,
    "pseudo": string
}

Request a list of objects, providing an App, based on URL and type. Only some basic information is returned in the list to keep data volume low even with many objects.

uri
If present only the App objects with a matching URL are returned. To determine if the URL matches a headmatch is performed
pseudo
If present only App objects of this pseudo type are returned.
{
    "api": "PbxAdminApi",
    "mt": "GetAppObjectsResult",
    "objects": [app]
}

Returns array of app objects

GetConfigObjects

{
    "api": "PbxAdminApi",
    "mt": "GetConfigObjects"
}

Request a list of all config templates available in the PBX. Only some basic information is returned in the list to keep data volume low even with many templates.

{
    "api": "PbxAdminApi",
    "mt": "GetConfigObjectsResult",
    "objects": [template]
}

Returns an array of template objects

GetPseudoObjects

{
    "api": "PbxAdminApi",
    "mt": "GetPseudoObjects",
    "pseudo": string
}

Requests a list of pseudo objects of a given type. Care must be taken not to use this operation too much, because a scan of all configured pseudo objects is done to find the requested objects. Only some basic information is returned in the list to keep data volume low even with many templates.

{
    "api": "PbxAdminApi",
    "mt": "GetPseudoObjectsResult",
    "objects": [object-id]
}

Returns an array of objects ids for the requested pseudo objects

SearchUsers

{
    "api": "PbxAdminApi",
    "mt": "SearchUsers",
    "cn": string,
    "includeMatch": boolen
}

Searches for users, based on the cn (Long Name) provided. Returns a list of up to 20 users starting from the position in the list of users identified by cn. Only objects of the type user or executive are returned.

This message can be used to enumerate all user and executive objects in the PBX:

If you don't want to enumerate all objects but find also the object that exactly matches the specified cn, set the parameter includeMath to true. In all other cases the parameter can be omitted.

{
    "api": "PbxAdminApi",
    "mt": "SearchUsersResult",
    "user": [user-id]
}

Returns an array obj user ids.

GetAppLogin

{
    "api": "PbxAdminApi",
    "mt": "GetAppLogin",
    "app": string,
    "challenge": string
}

Request the digest, which can be used to login to an App service. The main purpose is to verify that the shared secret of an App object is correct. It can be tested, by sending the returned parameter with AppCheckLogin to the App service. In this case an arbitrary challenge may be used.

{
    "api": "PbxAdminApi",
    "mt": "GetAppLoginResult",
    "app": string,
    "digest": string
}

Return the digest for the login.

GetGroup

{
    "api": "PbxAdminApi",
    "mt": "GetGroup",
    "grp": string
}

Request a list of members of a group identified by grp. The list is limited to 64 users

{
    "api": "PbxAdminApi",
    "mt": "GetGroupResult",
    "member": [member]
}

Returns an array of member objects

GetRPs

{
    "api": "PbxAdminApi",
    "mt": "GetRPs"
}

Request a list of Reverse Proxies configured in the local PBX

{
    "api": "PbxAdminApi",
    "mt": "GetRPsResult",
    "addr": string,
    "hw": string,
    "dns": string,
    "rp": [rp]
}

Returns a list of rp objects together with some more information interesting in this context

addr
The default IP4 address of the local PBX
hw
The hardware id (MAC) of the local PBX
dns
The configured DNS name of the local PBX
rp
Array of rp objects

GetNodes

{
    "api": "PbxAdminApi",
    "mt": "GetNodes"
}

Request a list of all nodes and locations

{
    "api": "PbxAdminApi",
    "mt": "GetNodesResult",
    "nodes":[node]
}

Returns an array of objects describing the nodes

GetLocation

{
    "api": "PbxAdminApi",
    "mt": "GetLocation",
    "loc": string
}

Request infos for a specific location/PBX. The delivered infos can be used to compose an URI to be used to create a WebSocket connection for the specified PBX. In case no registration at the PBX object for a slave PBX is available, the DNS name and the IP-Address info of the current PBX is delivered.

The URI is composed by the following scheme: [ws/wss]://[dns/addr] [:port]/[module]/APPS/websocket

E.g. wss://slave.example.com/PBX0/APPS/websocket

loc
The PBX name/name (h323) of the PBX object the infos are requested from
{
    "api": "PbxAdminApi",
    "mt": "GetLocationResult",
    "loc": string,
    "http": unsigned,
    "https": unsigned,
    "module": string,
    "dns": string,
    "addr": string
}
loc
The PBX name/name (h323) of the PBX object the infos are requested from
http
The port number for the HTTP/WS connections
https
The port number for the HTTPS/WSS connections
module
Usually PBX0 for a non dynamic PBX
dns
The DNS name of the PBX
addr
The IP-Address of the PBX

GetConfigs

{
    "api": "PbxAdminApi",
    "mt": "GetConfigs"
}

Request a list of configured config templates.

{
    "api": "PbxAdminApi",
    "mt": "GetConfigsResult",
    "configs":[string]
}

Returns an array of names of config templates

GetFilters

{
    "api": "PbxAdminApi",
    "mt": "GetFilters"
}

Request a list of call filters defined in the local PBX

{
    "api": "PbxAdminApi",
    "mt": "GetFiltersResult",
    "filter": [string]
}

Returns an array of filter names

GetGroups

{
    "api": "PbxAdminApi",
    "mt": "GetGroups"
}

Request a list of groups defined in the PBX

{
    "api": "PbxAdminApi",
    "mt": "GetGroupsResult",
    "groups":[string]
}

Returns an array of group names

GetBooleans

{
    "api": "PbxAdminApi",
    "mt": "GetBooleans"
}

Request a list of boolean objects defined in the PBX

{
    "api": "PbxAdminApi",
    "mt": "GetBooleansResult",
    "booleans":[boolean]
}

Returns an array of objects identifying the boolean objects

GetPush

{
    "api": "PbxAdminApi",
    "mt": "GetPush"
}

Request a list of push objects defined in the PBX

{
    "api": "PbxAdminApi",
    "mt": "GetPushResult",
    "push":[push]
}

Returns an array of objects identifying the push objects

GetMessages

{
    "api": "PbxAdminApi",
    "mt": "GetMessages"
}

Request a list of messages objects defined in the PBX

{
    "api": "PbxAdminApi",
    "mt": "GetMessagesResult",
    "messages":[messages]
}

Returns an array of objects identifying the messages objects

GetStun

{
    "api": "PbxAdminApi",
    "mt": "GetStun"
}

Request the local configured STUN parameters, published by this PBX

{
    "api": "PbxAdminApi",
    "mt": "GetStunResult",
    "stun": string,
    "turn": string,
    "turnUsr": string,
    "turnPwd": string,
    "stunSlow": boolean
}

Returns the STUN parameter

stun
The STUN server(s)
turn
The TURN server(s)
turnUsr, turnPwd
The TURN credentials
stunSlow
Activate workaround for slow STUN servers

GetAppLics

{
    "api": "PbxAdminApi",
    "mt": "GetAppLics"
}

Request the available App Licenses

{
    "api": "PbxAdminApi",
    "mt": "GetAppLicsResult",
    "lic": [app-lic]
}

Returns the available App licenses

CheckAppLic

{
    "api": "PbxAdminApi",
    "mt": "CheckAppLic",
    "guid": string,
    "cn": string,
    "h323": string,
    "lic": string
}

Check if a user is licensed for a given App

guid,cd,h323
One of these properties must be present to identify the user
lic
The license in the format as displayed on the PBX General page. Example: App(innovaphone-switchboard).
{
    "api": "PbxAdminApi",
    "mt": "CheckAppLicResult",
    "ok": bool
}

Returns the available App licenses

Objects

email
{
    "email": string
}
email
A string containing an email address.
device
{
    "hw": string,
    "text": string,
    "app": string,
    "admin": bool,
    "no-filter": bool,
    "tls": bool,
    "no-mob": bool,
    "trusted": bool
}
hw
The hardware id/mac address
text
Text displayed in the UI to identify the device
app
The phone App associated with the device
admin
Only registration with the PBX admin password allowed, no user password
no-filter
Registration allowed for endpoints not matching the registration address filter
tls
Only registration with verified TLS certificate, or from trusted RP allowed
no-mob
Deactivate call thru mobility object, if registration to this device exists
trusted
Registration from trusted reverse proxy allowed
group
{
    "name": string,
    "mode": string,
    "dyn": string
}
name
Name of the group
mode
A value of "active" indicates that this member is active. Other values are reserved
dyn
If present, this is a dynamic group membership. A value of "in" means the user is currently member, a value of "out" the user is currently not member
presence
{
    "c": string,
    "a": string,
    "n": string
}
c
Contact URI. There are predefined values like "tel:" or "im:", which identify the source of the presence info
a
Standard activity strings like "away" or "busy".
n
Presence note as entered by the user.
diversion
{
    "type": string,
    "bool": string,
    "bool-not": string,
    "ep": [ { "e164": string, "h323": string } ],
    "src" [ { "type": string, "ep": [ { "ext": string, "fwd": string, "e164": string, "h323": string } ] } ]
}
type
The type of the call diversion definition. Can be "cfu", "cfb" or "cfnr".
bool
Optional boolean object, the call diversion should depend on
bool-not
If present and not "false", indicates the diversion should only be executed, if the boolean object is not active
ep
Destination of the diversion. Only the first member of the array is used.
e164
Number
h323
H.323 Id/SIP URI
src
Otional filter for source of the call. Only the first member of the array is used.
type
Values are "do" - execute if source of call matches, or "dont" - execute if source of the call does not match
ep
Sources of the call identified by name (h323) or number (e164). It can be defined that only external calls should match by adding a ext property, or the type of the source can be defined as "fwd" - forwarding endpoint, "clid" - calling party, "both" - forwarding or calling party
wakeup
{
    "h": unsigned,
    "m": unsigned,
    "s": unsigned,
    "name": string,
    "num": string,
    "retry": unsigned,
    "mult": bool,
    "to": unsigned,
    "fallback": string,
    "bool": string,
    "bool-not": bool
}
h
The hour of the day, to which the wakeup call is executed. This refers to the local time of the PBX.
m
The minute to which the wakeup call is executed. If no hour is configured, the wakeup call is executed each hour.
s
The second to which the wakeup call is executed. If no hour and no minute is configured, the wakeup call is executed each minute. The clock resolution for wakeup calls is 10s, so the wakeup call is executed within a 10s interval after the configured time.
name
Name which is called for the announcement source (if no Name or Number' is configured the default MOH is used as source)
num
Number which is called for the announcement source (if no Name or Number is configured the default MOH is used as source)
retry
Number of Retries, if Source or Destination do not connect
mult
If this value is set, the wakeup call is executed periodically until it is removed. If not set, the wakeup call is removed after execution.
to
Timeout to limit the time the wakeup call is alerting at the user. After the timeout the call is disconnected.
fallback
Number to be called when the wakeup failed. The wakeup failed if the call was never alerting at the user after the configured retries, or if the Timeout expired, so the call was alerting the configured time, but was not answered.
bool
An optional Boolean object. If configured the call is sent to the given time only if the state of the boolean object is true.
bool-not
When this value is set the call is sent if the state of the boolean object is false.
gw
{
    "name": string,
    "idle": string,
    "ipei": string,
    "ac": string
}
pseudo
{
    "type": string,
    ...
}
type
The type of the pseudo object.
phone

The XML phone config translated to JSON.

reg
{
    "hw": string,
    "addr": string
}
hw
The hw id of the device used for the registration
addr
Address
app
{
    "title": string,
    "app": string,
    "url": string,
    "connected": bool,
    "guid": string,
    "sip": string,
    "pseudo": string
}
title
Configured display name of the App
app
App SIP URI
url
URL to the App Service
connected
Indicates that the App object has established a AppWebsocket connection to the App Service
sip
SIP URI of the App object if available
pseudo
Pseudo type of the App object if available
template
{
    "cn": string,
    "config": [string]
}
cn
Config template name
config
Up to four references to other config templates
object-id
{
    "cn": string,
    "guid": string
}
cn
Long Name
guid
guid
user-id
{
    "cn": string,
    "dn": string,
    "guid": string,
    "h323":string
}
cn
Long Name
dn
Display name
guid
guid
h323
H.323 Id/SIP URI
member
{
    "cn": string,
    "h323": string,
    "e164": string,
    "dn": string,
    "guid": string,
    "pseudo": string,
    "active": bool,
    "dyn": string
}
cn
Long Name
h323
Name
e164
Number
dn
Display name
guid
guid
pseudp
Pseudo type
active
Active member
dyn
Dynamic member, "in" or "out"
rp
{
    "addr": string,
    "cert": string,
    "cert2": string
}
addr
Address of the RP
cert
Mac address of the RP, which can also be used as certificate name
cert2
Alternate certificate name
boolean
{
    "guid": string,
    "name": string,
    "on": bool,
    "reason": string
}
guid
guid
name
Name
on
Indicates if the boolean is currently on
reason
undefined/manual/automatic
push
{
    "name": string
}
name
The name of the push object
messages
{
    "name": string
}
name
The name of the messages object
app-lic
{
    "name": string,
    "version": string,
    "count": string,
    "used": string,
    "local": string,
    "slaves": string,
    "key": string
}
name
The name of the license
node
{
    "name": string,
    "node": string,
    "loc": string
}
name
The name (SIP) of the node
node
The parent node of this node
loc
Present if the node is also a PBX. Indicates the parent PBX.