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 tp 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 operatios are performed by sending a message with a message type <name> to the PBX. The result is retured 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

MonitorAdminObject - monitor the PBX Admin object
MonitorConfig - monitor the local PBX config changes
UpdateObject - Update/create a PBX object
GetObject - Read config of an object
GetPbxConfig - Read local PBX config
GetPhoneConfig - Read phone config stored at an object
GetRegs - Read current registrations
DeleteObject - Delete an object
GetAppObjects - Read App objects base on some filters
GetConfigObjects - Read config templates
GetPseudoObjects - Read pseudo objects of a given type
SearchUsers - Search users by cn
GetAppLogin - Get digest for App Service login
GetGroup - Read group members
GetRPs - Read configured RPs
GetNodes - Read all nodes and locations
GetConfigs - Read config templates
GetFilters - Read list of configured filters
GetGroups - Read availabe Groups
GetBooleans - Read available Booleans
GetPush - Read configured Push objects
GetMessages - Read configured Messages objects
GetStun - Read STUN config
GetAppLics - Read available App Lics

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.

UpdateObject

{
    "api": "PbxAdminApi",
    "mt": "UpdateObject",
    "guid": string,
    "cn": string,
    "dn": string,
    "h323": string,
    "e164": string,
    "pwd": string,
    "loc": string,
    "node": string,
    "config": string,
    "apps": string,
    "filter": string,
    "cd-filter": string,
    "push": string,
    "messages": string,
    "hide": 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],
    "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, it can be omitted. 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, or if no object is found a new object shall be created.

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

config

Name of the config template used by the object.

apps

Comman seperated 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".

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 informations

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

Sent, when the object is updated, which means it is written to the database and the update is in effect in the PBX

GetObject

{
    "api": "PbxAdminApi",
    "mt": "GetObject",
    "guid": string,
    "cn": 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 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,
    "config": string,
    "apps": string,
    "filter": string,
    "cd-filter": string,
    "push": string,
    "messages": string,
    "hide": 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],
    "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.

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
config: Name of the config template used by the object.
apps: Comman seperated 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".
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

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

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:

Start with SearchUsers for cn ""
Continue with SearchUsers with the cn of the last returned object until no more objects are returned.

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

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 booleans defined in the PBX

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

Returns an array of objects identifying the booleans

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

Objects

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" - fowarding 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 referes 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.

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,
    "dn": string,
    "guid": string,
    "pseudo": string,
    "active": bool,
    "dyn": string
}

cn: Long Name
dn: Display name
guid: guid
pseudp: Pseudo type
active: Active member
dyn: Dynamic member, "in" or "out"

{
    "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.