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

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.

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