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

SubscribePresence - start monitoring the presence of a PBX object
UnsubscribePresence - stop monitoring the presence of a PBX object
SetPresence - sets the presence of a PBX object
SubscribeProfile - start monitoring the profiles / favourites of a PBX object
UnsubscribeProfile - stop monitoring the profiles / favourites of a PBX object
AddProfile - add a profile to a PBX object
DelProfile - delete a profile from a PBX object
UpdateProfile - change the name of a profile
AddProfileContact - add a favourite to a profile of a PBX object
DelProfileContact - delete a favourite from a profile of a PBX object
UpdateProfileContact - change a favourite in the profile of a PBX object
GetNodeInfo - Retrieves information about a PBX node
AddAlienCall - add an alien call this maybe a call the user has on another PBX
DelAlienCall - delete an alien call
AddDiversion - add a diversion (cfu, cfb, cfnr) but no admin diversion
DelDiversion - delete a diversion (cfu, cfb, cfnr) but no admin diversion
GetDiversion - get a diversion (cfu, cfb, cfnr) of a PBX object but no admin diversion
AppNotify - send an app notification to a user

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