PbxApi

The PbxApi protocol is available on AppWebsocket connections to innovaphone PBX objects, if the object is enabled for the PbxApi. It allows access to the presence, favourties and node information.

General structure

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

api
To address this interface the value "PbxApi" 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. Some operations turn on monitoring and cause additional update messages sent by the PBX.

Operations
Objects - recurring definitions

SubscribePresence

{
    "api": "PbxApi",
    "mt": "SubscribePresence",
    "sip": string,
    "num": string
}

Start monitoring of the presence of the object defined by sip or num.

{
    "api": "PbxApi",
    "mt": "SubscribePresenceResult"
}

Message sent back to confirm start of the monitoring

{
    "api": "PbxApi",
    "mt": "PresenceState"
    "up": boolean
    "sip": string,
    "num": string,
    "dn": string,
    "email": string
}

Message sent back whenever the state of the presence monitoring has changed. It also includes the full endpoint info that was retrieved with the subscription.

up
True if the presence monitor is connected. False if it is disconnected.
sip
The SIP URI of the monitored user.
num
The phone number of the monitored user.
dn
The display name of the monitored user.
email
The email address of the monitored user.

{
    "api": "PbxApi",
    "mt": "PresenceUpdate",
    "presence": [presence]
}

Sent after the presence monitor is up and whenever the presence of the monitored user changes afterwards. The presence array

presence
An array containing presence items. The first item is the newest item and should be used for displaying the current presence.

UnsubscribePresence

{
    "api": "PbxApi",
    "mt": "UnsubscribePresence",
    "sip": string,
    "num": string
}

Stop monitoring of the presence of the object defined by sip or num.

{
    "api": "PbxApi",
    "mt": "UnsubscribePresenceResult"
}

Message sent back to confirm that the monitoring has been stopped.

SetPresence

{
    "api": "PbxApi",
    "mt": "SetPresence",
    "sip": string,
    "guid": string,
    "contact": string,
    "activity": string,
    "note": string
}

Sets the presence for a given contact of a user, defined by the SIP URI or GUID.

{
    "api": "PbxApi",
    "mt": "SetPresenceResult",
    "error": unsigned,
    "errorText": string
}

Message sent back to confirm that setting the presence has been completed or failed.

SubscribeProfile

{
    "api": "PbxApi",
    "mt": "SubscribeProfile"
}

Starts monitoring the first profile of the user that established the AppWebsocket connection.

{
    "api": "PbxApi",
    "mt": "SubscribeProfileResult",
    "profile": profile
}

Confirmation that the monitor has been set up. Also this message contains the initial value of the first profile.

{
    "api": "PbxApi",
    "mt": "ProfileContactAdded",
    "profile": {
        "id": unsigned,
        "contact": contact
    }
}

This message is sent when a new favourite has been added to the first profile.

{
    "api": "PbxApi",
    "mt": "ProfileContactDeleted",
    "profile": {
        "id": unsigned,
        "contact": {
            "id": unsigned
        }
    }
}

This message is sent when a favourite has been deleted from the first profile.

UnsubscribeProfile

{
    "api": "PbxApi",
    "mt": "UnsubscribeProfile"
}

Stops monitoring the users profile.

{
    "api": "PbxApi",
    "mt": "UnsubscribeProfileResult"
}

Confirmation that the monitor has been deleted.

AddProfile

{
    "api": "PbxApi",
    "mt": "AddProfile",
    "name": string,
}

Adds a new profile with a given name.

DelProfile

{
    "api": "PbxApi",
    "mt": "DelProfile",
    "id": unsigned,
}

Deletes a profile with a given id.

UpdateProfile

{
    "api": "PbxApi",
    "mt": "UpdateProfile",
    "id": unsigned,
    "name": string,
}

Changes the name of a profile identified by id.

AddProfileContact

{
    "api": "PbxApi",
    "mt": "AddProfileContact",
    "id": unsigned,
    "name": string,
    "contact": {
        "dn": string,
        "sip": string,
        "num": string
    }
}

Adds a new favourite to the given profile. If the profile does not exist, it is created.

DelProfileContact

{
    "api": "PbxApi",
    "mt": "DelProfileContact",
    "id": unsigned,
    "contact": {
        "id": unsigned
    }
}

Deletes a favourite from the given profile.

UpdateProfileContact

{
    "api": "PbxApi",
    "mt": "UpdateProfileContact",
    "id": unsigned,
    "contact": contact
}

Updates an existing favourite.

GetNodeInfo

{
    "api": "PbxApi",
    "mt": "GetNodeInfo"
}

Requests information about the node of the user that is authenticated on the underlying AppWebsocket connection.

{
    "api": "PbxApi",
    "mt": "GetNodeInfoResult",
    "name": string,
    "prefix_intl": string,
    "prefix_ntl": string,
    "prefix_subs": string,
    "country_code": string
}

Contains information about the node of the user that is authenticated on the underlying AppWebsocket connection.

name
Name of the node.
prefix_intl
Prefix for dialing international numbers.
prefix_ntl
Prefix for dialing national numbers.
prefix_subs
Subscriber number prefix.
country_code
Country code.

AddAlienCall

{
    "api": "PbxApi",
    "mt": "AddAlienCall",
}

Adds a call to the PBX, which will result in a busy state of the user and also shows up as on the phone presence

{
    "api": "PbxApi",
    "mt": "AddAlienCallResult",
    "id": unsigned
}

The id can be used to delete the call

DelAlienCall

{
    "api": "PbxApi",
    "mt": "DelAlienCall",
    "id": unsigned
}

Deletes a call added with AddAlienCall. The id identifies the call to be deleted

{
    "api": "PbxApi",
    "mt": "DelAlienCallResult",
}

AddDiversion


    {
    "api": "PbxApi",
    "mt": "AddDiversion",
    "sip": string,
    "guid": string,
    "ep-sip":string,
    "ep-num":string,
    "type":string,
    }

Adds a diversion (cfb, cfu, cfnr) to the PBX but no admin diversion

{
    "api": "PbxApi",
    "mt": "AddDiversionResult",
    "ok": boolean,
}

OK indicates that the diversion can be set.

DelDiversion


    {
    "api": "PbxApi",
    "mt": "DelDiversion",
    "sip": string,
    "guid": string,
    "type":string,
    }

Deletes a diversion (cfb, cfu, cfnr) of that type of the PBX but no admin diversion

{
    "api": "PbxApi",
    "mt": "DelDiversionResult",
    "ok": boolean,
}

OK indicates that the diversion can be deleted.

GetDiversion


    {
    "api": "PbxApi",
    "mt": "GetDiversion",
    "sip": string,
    "guid": string,
    "type":string,
    }

Get a diversion of the types (cfb, cfu, cfnr) from the PBX but no admin diversion

{
    "api": "PbxApi",
    "mt": "GetDiversionResult",
    "num": string,
    "sip":string,
}

Number and/or SIP are delivered if a diversion of that type persists.

AppNotify

{
    "api": "PbxApi",
    "mt": "AppNotify",
    "sip": string,
    "link": string,
    "title":string,
    "text":string,
}

Sends an app notification to a specified user. The notification will be displayed by all myApps sessions of the user that have app notifications enabled.

sip
The SIP URI of the user.
link
An app link that shall be opened if the user clicks the notification. This is the SIP URI of the corresponding app object with optional parameters.
Examples: someapp, someapp?discussion=3&action=show
Implementation hint: The app can process the the app link by listening to the start.onargschanged event. It fires if a user clicks a notification linking to the app. start.args contains the parameters given with the link.
title
The title of the notification.
text
The text body of the notification.
{
    "api": "PbxApi",
    "mt": "AppNotifyResult",
    "error": string,
}

The response to the AppNotify message.

error
An optional error string that is only present if the notification could not be sent.
"not found"
The user specified by "sip" was not found.

Objects

presence
{
    "contact": string,
    "status": string,
    "activity": string,
    "note": string
}
contact
A string defining the type of the presence. Typical values are:
tel:
The presence set by the user.
im:
Automatically created by the PBX. The status attribute contains the online state of the user.
calendar:
Automatically created by a calendar app like the innovaphone Calendar.
status
Tells if the user can be contacted using the given contact. Possible values are "open", "closed".
activity
The presence activity. Typical values are "" for available, "away", "busy" and "dnd" for do not disturb.
note
A free text entered by the user giving additional information about the presence.
profile
{
    "id": integer,
    "name": string,
    "contacts": [contact]
}
id
The nummerical id of the profile
name
The title of the profile
contact
{
    "id": integer,
    "name": string,
    "num": string,
    "dsp": string,
    "presence": boolean,
    "dialog": boolean,
    "ext": string
}
id
The nummerical id of the favourite
name
The SIP URI of the favourite
num
The phone number of the favourite
dsp
The display name of the favourite
presence
Tells if presence monitoring is available
dialog
Tells if dialog monitoring is available
ext
Obsolete. Tells the type of the favourite. Was used in myPBX to define the handling of the favourite.
undefined
Internal user.
tel
External phone number
sip
External SIP URI