com.innovaphone.client (Client 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": {
        "domain": string,
        "sip": string,
        "guid": string,
        "dn": string,
        "num": string,
        "email": string,
        "prefix": {
            "intl": string,
            "ntl": string,
            "subs": string,
            "area": string,
            "country": string
        }
    },
    "connInfo": {
        "up": boolean,
        "standby": boolean,
        "cur": string,
        "pri": string,
        "sec": string,
        "phys": string
    },
    "home": [ string ],
    "deviceApps": [
        {
            "name": string,
            "title": string,
            "deviceapp": string
        } 
    ],
    "profileApp": string,
    "tutorialApp": string,
    "standby": boolean,
    "lang": string,
    "scheme": string,
    "launcher": boolean,
    "launcherUpdateBuild": string,
    "appStoreUrl": string,
    "adminSettings": object
}

user
An object containing the details about the user that is logged-in.
connInfo
An object containing information about the connection and alternative PBXes.
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.
tutorialApp
The name of the tutorials app.
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.
lang
The two-letter code of the user's language.
scheme
The current color scheme ("light" or "dark").
launcher
true if myApps is running inside the myApps launcher for Windows, iOS or Android.
launcherUpdateBuild
The buildnumber that shall be used for automatic update of the launcher.
appStoreUrl
The URL of the app store that shall be used for automatic update of the launcher.
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.

API messages

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

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

Requests Responses

UpdateProfile

Tells the client that the profile picture of the user has changed and shall be reloaded. 

{
    "mt": "UpdateProfile"
}

ShowApp

Opens an app link within myapps. 

{
    "mt": "ShowApp",
    "app": string
}

app
The app link to show, possibly including parameters, e.g. "someapp?id=3".

SetAttachedToHome

Attaches or detaches an app link to the home screen. 

{
    "mt": "SetAttachedToHome",
    "reference": string,
    "attached": boolean
}

{
    "mt": "SetAttachedToHome",
    "link": string,
    "attached": boolean
}

reference
Used for links to the app itself.
Contains only the parameter part of the app link, e.g. "?id=13#s=doe&d=John%20Doe".
The provider will prepend it with the ID of the app sending the request.
link
Used for links to another app.
Contains a full app link, e.g. "someapp?id=13#s=doe&d=John%20Doe".
attached
true if the app link shall be attached.
false if the app link shall be deatached.

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. 

{
    "mt": "ShowStatusInfo",
    "url": string,
    "id": string
}

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.

CloseStatusInfo

Closes a status information that has been opened using ShowStatusInfo. 

{
    "mt": "CloseStatusInfo",
    "id": string
}

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.

SubscribePresence

Starts a presence subscription to a given SIP URI or phone number. The provider will send PresenceUpdated messages until the consume stops the subscription using UnsubscribePresence. 

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

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)

Examples:
{ mt: "SubscribePresence", sip: "atlantis" }

{ 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": string,
    "num": string
}

mt
"UnsubscribePresence"
sip
The SIP URI of the remote endpoint (optional)
num
The phone number of the remote endpoint (optional)

Examples:
{ mt: "UnsubscribePresence", sip: "atlantis" }

{ mt: "UnsubscribePresence", num: "201" }

{ mt: "UnsubscribePresence" }

SubscribeDialog

Starts a dialog subscription to a given SIP URI or phone number. The provider will send DialogInfo messages until the consume stops the subscription using UnsubscribeDialog. 

{
    "mt": "SubscribeDialog",
    "sip": string,
    "num": string
}

mt
"SubscribeDialog"
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)

Examples:
{ mt: "SubscribeDialog", sip: "atlantis" }

{ 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": string,
    "num": string
}

mt
"UnsubscribeDialog"
sip
The SIP URI of the remote endpoint (optional)
num
The phone number of the remote endpoint (optional)

Examples:
{ mt: "UnsubscribeDialog", sip: "atlantis" }

{ mt: "UnsubscribeDialog", num: "201" }

{ mt: "UnsubscribeDialog" }

PresenceUpdated

An update for a presence subscription that was started using SubscribePresence. 

{
    "mt": "PresenceUpdated",
    "sip": string,
    "num": string,
    "up": boolean,
    "ep": {
        "sip": string,
        "num": string,
        "dn": string
    },
    "presence" : [
        {
            "contact": string,
            "activity", string,
            "displayNote": string,
            "note": string,
            "status": string,
            "params": object
        }
    ]
}

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

An update for a dialog subscription that was started using SubscribeDialog. 

{
    "mt": "DialogInfo",
    "sip": string,
    "callId": string,
    "confId": string,
    "remote": {
        "sip": string,
        "dn": string,
        "num": string,
    },
    "state": {
        "name": string,
        "outgoing": boolean,
        "hold": boolean
    }
}

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

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 and retrieval of a profile picture. The presence will be shown on the app tile on the home screen.

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