Multiplatform Phone (MPP)

Remote SDK API Invocation

A single Remote SDK API call results in the follow the two messages between the controlling WebSockets server and the phone:

  • The controlling server sends a Request JSON payload through the WebSocket connection to the phone.
  • The phone processes the response, and sends a response JSON payload back to the controlling WebSockets server.

Note: The Remote SDK only allows a single API to be pending for a phone. Once you get a response to an API call from the phone, you may issue the next API call request.

Figure: Remote SDK Invocation


NOTE: The set of available calls and details about each call is available on Cisco DevNet for the Remote SDK under the API Reference section. You can also retrieve the full set of API's supported by the phone at runtime by calling the /api/GetMetadata method. The response is a Swagger/OpenAPI 3.0 definition of APIs and events supports by the phone's current software load.

Send a Remote SDK API Request

A Remote SDK API request is a JSON object that you can send from the controlling WebSockets server to the phone. A JSON object is also called a dictionary.
The Request-URI name-value pair is required. The associated value is a string that specifies the Request-URI path: the API call the controlling server is asking the phone to perform. /api/Config/v1/GetParams is an example of a Request-URI path that requests configuration and/or status values from a phone.

Note: The Request-URI is in the form of a path which contains the following information, separated by forward slashes (/):

  • /api This begins every Request-URI value.
  • <interface-name> The Remote SDK supports multiple interfaces, for example Call or Config which allow manipulate of different aspects of phone functionality per interface.
  • <interface-version> Since interfaces will be changed or enhanced in the future, the Request-URI specifies a specific version of the interface. A phone may simultaneously support multiple versions of an interface to provide backwards compatibility.
  • <method-name> This is specific API that will result in the phone returning data or performing some action.

Additional fields may be provided or even required depending on the specific API call.

JSON API Call Request Payload Example

Code Snippet
Copy {
     "Request-URI": "/api/Config/v1/GetParams",
     "params": ["Station_Name"]
 }

Receiving a Remote SDK API Response

A Remote SDK API response is sent from the controlled phone back to the controlling WebSockets server via the previously opened WebSocket.

  • type: The associated value, of type string, indicates what sort of message this JSON object represents. The associated value will be "result" for request responses.
    NOTE: Since events can be sent from the phone at any time, it is import it verify that the incoming JSON object is a response and not an event which happens to arrive between the request and the resulting response.
  • success: The associated value is of type boolean and represents call success (true) or failure (false).
  • status: The associated value is of type number, and is an HTTP style status code which gives additional detail about the success or failure of the request. A value of 200 represents a successful API call.
  • result: This object, or dictionary, represents the specific data being returned from a successful API call.

JSON API Call Successful Response Payload Example

Code Snippet
Copy {
    "type": "result",
    "result": {
    "paramvalues": {
       "Station_Name": "arupiSSomSok"
       },
    "respcode": 0
    },
"success": true,
"status": 200
}

JSON API Call Unsuccessful Response Payload Examples

Code Snippet
Copy{
    "type": "result",
    "message": "Insufficient Parameters. Required Parameter doesn't exist for parameter 'params'",
    "success": false,
    "status": 400
}

{
    "type": "result",
    "message": "API call failed. Check device logs.",
    "success": false,
    "status": 409
}
Next