Services

The Services protocol is available on AppWebsocket connections to innovaphone PBX objects if the object is enabled for the Services API. It allows an application to find other app services that provide a specific service on incoming AppWebsocket connections. It is also possible to obtain a login for this app service. With this information an additional AppWebsocket connection to the service can be established.

For discovery and authentication against a service, the permission for the app providing the service must be configured on the own app object.

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

api

To address this interface the value "Services" has to 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

• SubscribeServices - Subscribe for information about available services
• UnsubscribeServices - Unsubscribe for information available services
• GetServiceLogin - Get a login for a specific service

• SubscribeServicesResult - Result of SubscribeServices
• UnsubscribeServicesResult - Result of UnsubscribeServices
• ServicesInfo - Information about the currently available services
• GetServiceLoginResult - Result of GetServiceLogin

{
    "api": "Services",
    "mt": "SubscribeServices",
}

With this message the application subscribes for service information. The PBX answers with SubscribeServicesResult and ServicesInfo. Each time the service information changes the PBX sends an updated version ServicesInfo until the application unsubscribes using UnsubscribeServices.

{
    "api": "Services",
    "mt": "SubscribeServicesResult",
}

Result of the SubscribeServices operation

{
    "api": "Services",
    "mt": "UnsubscribeServices",
}

Unsubscribes from the service info. The PBX answers with UnsubscribeServicesResult and stops sending ServicesInfo messages.

{
    "api": "Services",
    "mt": "UnsubscribeServicesResult",
}

Result of the UnsubscribeServices operation

{
    "api": "Services",
    "mt": "ServicesInfo",
    "services": AppServices,
}

This message contains information about the services available on this AppWebsocket connection. The first message is delivered immediately after SubscribeServicesResult is received. If there are any any changes to the available services, an additional message is delivered.

services

An array containing all available app services.

This message requests a login for the given app service. It contains the challenge received in the AppWebsocket message AppChallenge. See the AppWebsocket for details.

{
    "api": "Services",
    "mt": "GetServiceLogin",
    "app": SipUri,
    "challenge": string,
}

app

The SIP uri of the other app service.

challenge

The challenge that was received from the other app service.

The answer to the GetServiceLogin message. Contains all the parameters that shall be forwarded to the other app service in the AppLogin message. See the AppWebsocket for details about the individual parameters.

{
    "api": "Services",
    "mt": "GetServiceLoginResult",
    "domain": string,
    "sip": string,
    "guid": string,
    "dn": string,
    "pbxObj": string,
    "app", string,
    "info": object,
    "digest": string,
    "key": string,
    "salt": string
}

An array containing AppService objects.

[
        AppService,
        AppService,
        AppService
]

Information about an app service.

{
    "name": SipUri,
    "title": DisplayName,
    "url": WebsocketUrl,
    "info": AppServiceInfo
}

name

The SIP URI of the app service

title

The display name of the app service

url

The websocket URL of the app service

info

A ServiceInfo object.

An object containing the services that an app services provides on incoming AppWebsocket connections.

{
    ServiceId: ServiceModel,
    ServiceId: ServiceModel
}

ServiceId

The ID of the service, e.g. "com.innovaphone.devices".

ServiceModel

An object containing additional information, defined by the service.