# com.innovaphone.client (Client API)

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

- Presence and dialog subscriptions.
- Manage app links on the home screen.
- Notifying the client, if profile pictures need to be reloaded.
- Displaying status info for active phone calls.
- Information about the user and the myApps client.

## 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,
                "subscriber": 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

- UpdateProfile - Tells the client that the profile picture of the user has changed and shall be reloaded.
- ShowApp - Opens an app link within myapps.
- SetAttachedToHome - Attaches or detaches an app link to the home screen.
- ShowStatusInfo - Opens a status bar provided by the app that is shown while other apps are in the foreground.
- CloseStatusInfo - Closes a status bar.
- SubscribePresence - Starts a presence subscription.
- UnsubscribePresence - Closes a presence subscription.
- SubscribeDialog - Starts a dialog subscription.
- UnsubscribeDialog - Closes a dialog subscription.
- GetAppIcon - Gets the app icon URI for an app.

Responses

- PresenceUpdated - An update for a presence subscription.
- DialogInfo - An update for a dialog subscription.
- GetAppIconResult - The response to the GetAppIcon request.

### 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`