com.innovaphone.client (App API)

This API is used for communicating with the client. It provides the following functionality for apps:

Restictions

The API is exclusively provided by the myApps client. The corresponding provider name is "@client".

API model

Service info

The API doesn't define any service info.

Provider model

user
An object containing the details about the user that is logged-in.
home
An object containing the app links that are attached to home for each app.
deviceApps
An array that contains the apps that can be used as a phone app by the user.
profileApp
The name of the app that shall be used to configure the user profile.
lang
The two-letter code of the user's language.
scheme
The current color scheme ("light" or "dark").
standby
true if the client is running on a standby PBX. Apps can use this information if they implement a special behaviour in that case.
launcher
true if myApps is running inside the myApps launcher for Windows, iOS or Android.
adminSettings
An object that contains administrative settings that are used by the launcher, by the myApps client or by apps. Each setting is represented by a named object that contains a "value" and "force" field. If "force" is true, the user should not be allowed to change that setting.

Example

{
  "@client": {
    "title": "innovaphone myApps",
    "url": "http:\/\/pbx.example.com\/PBX0\/APPCLIENT\/13XXXX\/appclient.htm",
    "info": { },
    "model": {
      "user": {
        "domain": "example.com",
        "sip": "bob",
        "guid": "5db8519be826c148a8877f10f8bc2d73",
        "dn": "Bob Hansen",
        "num": "201",
        "email": "bob@example.com"
      },
      "home": {
        "phone": [ ],
        "contacts": [
          "id=3#s=john.doe&d=John%20Doe",
          "id=4#s=joe.bloggs&d=Joe%20Bloggs"
        ]
      },
      "deviceApps": [
        {
          "name": "phone",
          "title": "Phone",
          "deviceapp": "phone"
        }
      ],
      "profileApp": "profile",
      "launcher": true,
      "adminSettings": {
        "autostart": {
            "value": false,
            "force": true
        },
        "taskbar": {
            "value": true,
            "force": true
        },
        "offline": {
            "value": 300000,
            "force": true
        },
        "video": {
            "value": true,
            "force": true
        },
        "hotkeyDial": {
            "value": "F8",
            "force": true
        },
        "hotkeyAccept": {
            "value": "CTRL + ALT + F9",
            "force": true
        },
        "hotkeyReject": {
            "value": "WIN + F10",
            "force": true
        },
        "logFlags": {
            "value": "00000000d6800001",
            "force": true
        },
        "docking": {
            "value": 0,
            "force": true
        },
        "notifications": {
            "value": false,
            "force": true
        }
      }
    }
  }
}

API messages

All messages are JSON objects that have a mandatory attribute "mt" that specifies the message type. The provider will echo the "src" attribute from requests in the corresponding responses.

Requests

UpdateProfile
Tells the client that the profile picture of the user has changed and shall be reloaded.
Example: { mt: "UpdateProfile" }
SetAttachedToHome
Attaches or detaches an app link to the home screen. Apps can only attach links to itself.
reference
The app parameters and client parameters of the app link without leading "?".
attached
true if the app link shall be attached.
false if the app link shall be deatached.
Example: { mt: "SetAttachedToHome", reference: "id=13#s=doe&d=John%20Doe", attached: true }
ShowStatusInfo
Opens an HTML page in the client as a status information. It is only shown, while the originating app is in the background. When the originating app is closed, the client closes all related status informations.
url
The URL of the HTML page that shall be shown.
id
An id that must be unique for the app that created the notification.
Example: { mt: "ShowStatusInfo", url: "https://apps.example.com/phone/activecall.htm?app=phone&call=4", id: "4" }
CloseStatusInfo
Closes a status information that has been opened using ShowStatusInfo.
id
The id that has been used to create the notification.
If no id is given, the client will close all status informations of the app.
Example: { mt: "CloseStatusInfo", id: "4" }
SubscribePresence
Starts a presence subscription to a given SIP URI or phone number.
mt
"SubscribePresence"
sip
The SIP URI of the remote endpoint (optional, sip or num must be specified)
num
The phone number of the remote endpoint (optional, sip or num must be specified)
Example: { mt: "SubscribePresence", sip: "atlantis" }
Example: { mt: "SubscribePresence", num: "201" }
UnsubscribePresence
Closes a presence subscription that was started using SubscribePresence.
If no sip or num is given, all presence subscriptions of the consumer are closed.
mt
"UnsubscribePresence"
sip
The SIP URI of the remote endpoint (optional)
num
The phone number of the remote endpoint (optional)
Example: { mt: "UnsubscribePresence", sip: "atlantis" }
Example: { mt: "UnsubscribePresence", num: "201" }
SubscribeDialog
Starts a dialog subscription to a given SIP URI or phone number.
mt
"SubscribeDialog"
sip
The SIP URI of the monitored endpoint (optional, sip or num must be specified)
num
The phone number of the monitored endpoint (optional, sip or num must be specified)
Example: { mt: "SubscribeDialog", sip: "atlantis" }
Example: { mt: "SubscribeDialog", num: "201" }
UnsubscribeDialog
Closes a dialog subscription that was started using SubscribeDialog.
If no sip or num is given, all dialog subscriptions of the consumer are closed.
mt
"UnsubscribeDialog"
sip
The SIP URI of the monitored endpoint (optional)
num
The phone number of the monitored endpoint (optional)
Example: { mt: "UnsubscribeDialog", sip: "atlantis" }
Example: { mt: "UnsubscribeDialog", num: "201" }

Responses

PresenceUpdated
An update for a presence subscription that was started using SubscribePresence.
mt
"PresenceUpdated"
sip
The SIP URI of the remote endpoint, as specified by the consumer
num
The phone number of the remote endpoint, as specified by the consumer
up
The connection state of the presence subscription (true or false)
ep
Information about the remote endpoint that was received over the presence subscription.
sip
SIP URI
num
Phone number
dn
Display name
presence
An array containing the list of presences for the different contacts.
contact
Presence contact ("tel:", "im:", "calendar:")
activity
Presence activity ("", "away", "busy", "dnd")
displayNote
An additional text entered by the user that describes the presence in detail. Calendar presences are localized by the provider. Additional parameters (hashtags) are removed.
note
Same as displayNote, but not localized and possibly containing hashtags. Should not be used for displaying.
status
The availability using that contact ("open", "closed")
params
An object containing the parsed parameters from the presence note.
Example: 
    {
        "mt": "PresenceUpdated",
        "sip": "atlantis",
        "up": true,
        "ep": {
            "sip": "atlantis",
            "dn": "Atlantis",
            "num": "201"
        },
        "presence": [
            {
                "contact": "calendar:",
                "status": "open",
                "activity": "",
                "note": "Frei bis 26.04.2018, 11:00 (Beschäftigt: Fixes) #free #until:1524733200000 #next-activity:busy #next:41:5:42:5",
                "displayNote": "Frei bis 26.4.2018 11:00 (Beschäftigt: Fixes)",
                "params": {
                    "free": "",
                    "until": 1524733200000,
                    "next-activity": "busy",
                    "next": "41:5:42:5"
                }
            },
            {
                "contact": "im:",
                "status": "closed",
                "activity": "",
                "displayNote": "",
                "params": {}
            }
        ]
    }
DialogInfo
A call update for a dialog subscription that was started using SubscribeDialog.
mt
"DialogInfo"
sip
The SIP URI of the monitored endpoint, as specified by the consumer
num
The phone number of the monitored endpoint, as specified by the consumer
callId
The unique ID of the call. It can be used for further actions using JSON signalling like pickup.
confId
The conference ID of the call.
remote
Information about the remote endpoint of the call.
sip
SIP URI
num
Phone number
dn
Display name
state
An object containing the state of the call.
name
The state itself. Possible values are "idle", "calling", "incomplete", "complete", "alerting", "connected", "disconnecting", "disconnected" and "parked".
outgoing
true for outgoing calls. false for incoming calls.
hold (optional)
true if the call is put on hold by the monitored endpoint.
held (optional)
true if the call is put on hold by the remote endpoint.
waiting (optional)
true if the call is waiting.
deleted (optional)
true if the call is finished. The consumer can remove the call from its local model.
Example: 
{
    "mt": "DialogInfo",
    "sip": "endeavour",
    "callId": "e44379a033ec5a01ebd500903328631a",
    "confId": "13d9c5a033ec5a01ead500903328631a",
    "remote": {
        "sip": "atlantis",
        "dn": "Atlantis",
        "num": "201"
    },
    "state": {
        "name": "connected",
        "outgoing": true,
        "hold": true
    }
}
Example: 
{
    "mt": "DialogInfo",
    "sip": "endeavour",
    "callId": "e44379a033ec5a01ebd500903328631a",
    "deleted": true
}

Concepts

App links

The URI format for app links consists of

app name
The name of app as defined in the app object in the PBX. The client will open this app, when the app link is clicked by the user.
app parameters (optional)
A search string (?) with the parameters that are passed to the app.
client parameters (optional)
A fragment identifier (#) with parameters for the client. Currently the following parameters are defined:
d
The display name that shall be shown on the app tile or in the tooltip of the app icon. If no display name is given, the client will show the name of the app.
s
A SIP URI for presence monitoring. The presence will be shown on the app tile on the home screen.

Example: contacts?id=13#s=doe&d=John%20Doe