Skip to content

appContext.callApi()#

Syntax#

appContext.callApi(params);

Parameters#

params is a mandatory Object parameter with the following properties:

Key Description Type Default Required
resource Kazoo SDK method name. String true
apiRoot Override the API URL set in config.js for this request only. String monster.config.api.default false
authToken Override the authentication token (JWT) generated during the authentication process for this request only. String monster.util.getAuthToken() false
bypassProgressIndicator Whether or not to hide the request progress indicator while this request is in progress. Boolean false false
data A plain JavaScript object that contains the list of parameters to be sent on the request. Object(#data) true
success A function to be called if the request succeeds (200 OK). The function gets passed two arguments: the response payload formatted according to the data type; a string describing the status. Function false
error A function to be called if the request fails (except for 402 Payment Required, see onChargesCancelled). The function receives three arguments: the error parsed as JSON; the raw error from the ajax error handler; a function to throw a generic Monster UI request error. Function false
onChargesCancelled A function called when the error is specifically a 402 Payment Required. It is executed if the user declines the charges associated with the request. Function false

data#

Here is a list of some common data properties. However, this object may contain other properties besides the ones listed here, depending on the requested resource.

Key Description Type Default Required
accountId Kazoo account ID. String false
data Payload to be sent in as request body. Object false
filters A map of filters to append to the API URL, where the key is the URL parameter name and the value is the parameter's value. Object false
generateError Whether or not to display the generic Monster UI error dialog when the request fails. Boolean true false
headers An object of additional header key/value pairs to send along with the request (e.g. { 'Accept': 'application/octet-stream' }). Object false

Description#

Every Monster app has a helper function callApi(_params_) that can be used to call any API endpoint supported by the Kazoo SDK.

It is automatically configured with our Kazoo SDK and takes the same parameter structure as the monster.request(_params_) function, as well as some additional arguments, to easily interact with the Kazoo API within the application context. The main difference, however, is that the resource value must be a valid Kazoo SDK's method name, which means that you don't have to declare any resource in the app's requests object, compared to the monster.request(_params_) function.

Examples#

Request all the devices for the current account, without displaying Monster UI progress indicator#

var self = this;

// ...

self.callApi(params: {
  resource: 'device.list',
  data: {
    accountId: self.accountId
  },
  bypassProgressIndicator: true,
  success: function(data, status) {
    var devices = data.data;

    // Do something with the device list
  },
  error: function(parsedError, error, globalHandler) {
    // Handle failure
  }
});

Request the callflows that belong to the current user, and have not been last modified by Smart PBX nor Call Center apps#

var self = this;

// ...

self.callApi(params: {
  resource: 'callflow.list',
  data: {
    accountId: self.accountId,
    filters: {
      filter_owner_id: monster.apps.auth.currentUser.id,
      'filter_not_ui_metadata.origin': [
        'voip',
        'callqueues'
      ]
    }
  },
  success: function(data, status) {
    var callflows = data.data;

    // Do something with the callflow list
  }
});

Request to create a voicemail box, but handle the charge declination case#

var self = this,
  newVMBox;

// ...

self.callApi(params: {
  resource: 'voicemail.create',
  data: {
    accountId: self.accountId,
    data: newVMBox
  },
  success: function(data) {
    var savedVMBox = data.data;

    // Do something with the newly created vmbox...
  },
  onChargesCancelled: function() {
    console.log('Charges not accepted by the user!');
  }
});

Request to create a user, but do not display the default error alert in case of HTTP 400 status code#

var self = this,
  newUser;

// ...

self.callApi(params: {
  resource: 'user.create',
  data: {
    accountId: self.accountId,
    data: newUser
  },
  success: function(data) {
    var savedUser = data.data;

    // Do something with the newly created user...
  },
  error: function(parsedError, error, globalHandler) {
    if (error.status === 400) { // You could check also: parsedError.error === '400'
      // Handle error due to invalid data...
    } else {
      // Display default alert
      globalHandler(parsedError, { generateError: true });
    }
  }
});