api-ai-cordova

Plugin makes it easy to integrate your Cordova application with api.ai natural language processing service. This plugin supports Android and iOS mobile operation systems.

Project on Github https://github.com/api-ai/api-ai-cordova
Page in NPM https://www.npmjs.com/package/cordova-plugin-apiai
Github issues https://github.com/api-ai/api-ai-cordova/issues
Demo application sources https://github.com/api-ai/api-ai-cordova-sample

• Installation
• Usage
• API
  • Request Options
• Supported Languages
• Promise-Based Wrapper

Installation

• Make sure that Cordova CLI is installed
• Install api.ai plugin with Cordova CLI:

cordova plugin add cordova-plugin-apiai

Usage

Add to your index.js file (typically in js folder) in function onDeviceReady following code

ApiAIPlugin.init(
        {
            clientAccessToken: "YOUR_CLIENT_ACCESS_TOKEN", // insert your client access key here
            lang: "en" // set lang tag from list of supported languages
        }, 
        function(result) { /* success processing */ },
        function(error) { /* error processing */ }
    );

Add to your page with mic button function to make voice requests:

function sendVoice() {
    try {     
      ApiAIPlugin.requestVoice(
        {}, // empty for simple requests, some optional parameters can be here
        function (response) {
            // place your result processing here
            alert(JSON.stringify(response));
        },
        function (error) {
            // place your error processing here
            alert(error);
        });                
    } catch (e) {
        alert(e);
    }
}

If you want to create voice level visualization use function levelMeterCallback to set callback for processing soundLevel:

ApiAIPlugin.levelMeterCallback(function(level) {
   console.log(level);
   // add visualization code here
});

If you want to handle start and stop listening events, add appropriate handlers:

ApiAIPlugin.setListeningStartCallback(function () {
    console.log("listening started");
});

ApiAIPlugin.setListeningFinishCallback(function () {
    console.log("listening stopped");
});

Please note, that handlers must be added before ApiAIPlugin.requestVoice call, like here:

function sendVoice() {
    try {    

      // !!!
      ApiAIPlugin.levelMeterCallback(function(level) {
         console.log(level);
      }); 

      ApiAIPlugin.requestVoice(...

Then add call sendVoice function from your button's onclick:

<div onclick="sendVoice();">Mic</div>

If you want make text requests add the following code:

function sendText(query_text) {
    try {
        ApiAIPlugin.requestText(
            {
                query: query_text
            },
            function (response) {
                // place your result processing here
                alert(JSON.stringify(response));
            },
            function (error) {
                // place your error processing here
                alert(error);
            });
    } catch (e) {
        alert(e);
    }
}

Also you can use function to cancel current api.ai request:

ApiAIPlugin.cancelAllRequests();

API

// Initialize plugin
//  options - JSON object - `{
//                              clientAccessToken: "your_access_token",
//                              lang: "one_of_supported_languages"
//                           }`
//  success - Function (optional) - callback for initialization success: function () {}
//  error - Function (optional) - callback for initialization error: function (error) {}
ApiAIPlugin.init(options, success, error)

// Start listening, then make voice request to api.ai service
//  options - JSON object - voice request options (reserved for future use)
//  success - Function (optional) - callback for request success `function (response) {}` where response is Object 
//  error - Function (optional) - callback for request error `function (error) {}` where error is String
ApiAIPlugin.requestVoice(options, success, error)

// Make text request to api.ai service
//  options - JSON object - `{ query: "queryText" }`
//  success - Function (optional) - callback for request success `function (response) {}` where response is Object 
//  error - Function (optional) - callback for request error `function (error) {}` where error is String
ApiAIPlugin.requestText(options, success, error)

// Set callback for sound level. Need to call only once after initialization
//  callback - Function - function must be `function(level) { }`, level is float value from 0 to 1
ApiAIPlugin.levelMeterCallback(callback)

// Cancel all pending requests
ApiAIPlugin.cancelAllRequests()

// Stop current listening process and send request to server
ApiAIPlugin.stopListening()

// Set callback for listening started event
//  callback - Function - must be simple function without arguments: function () {} 
ApiAIPlugin.setListeningStartCallback(callback)

// Set callback for listening finished callback
//  callback - Function - must be simple function without arguments: function () {}
ApiAIPlugin.setListeningFinishCallback(callback)

// Set callback for getting partial recognition results (Available only on Android platform!)
// callback - Function - must be `function(str) { }` with string argument
// You can get the json array of strings with partial recognition results
ApiAIPlugin.setPartialResultsCallback(callback)

Request Options

The options parameter may contains following fields:

• query - text query, only appliable to requestText function

• contexts - list of strings or objects, input context for the request (See Contexts Quick Start for more information about Contexts) strings:

  contexts: [ "weather", "home" ]

  objects:

  contexts: [ { name: "weather", parameters: { location: "London" } }, { name: "home"} ]

• resetContexts - boolean flag, set it to true to reset current active contexts

  resetContexts: true

• entities - array of entities that replace developer defined entities for this request only. The entity(ies) need to exist in the developer console. Each entity is the pair of name and entries array. Entries array contains one or more items with value and synonyms fields.

  entities: [
    {
      name: "dwarfs",
      entries: [
        {
          value: "Ori",
          synonyms: [
            "Ori",
            "Nori"
          ]
        },
        {
          value: "bifur",
          synonyms: [
            "Bofur",
            "Bombur"
          ]
        }
      ]
    }
  ]

• context also may have lifespan property - integer number defining number of requests the context will influence

  {
      name: "weather",
      lifespan: 2,
      parameters: {
          location: "London"
      }
  }

For many samples see tests

Supported Languages

• en
• es
• ru
• de
• pt
• pt-BR
• es
• fr
• it
• ja
• ko
• zh-CN
• zh-HK
• zh-TW

Promise-Based Wrapper

The promise-based wrapper was added for ease of use and better interoperability with other JavaScript code. Wrapper implemented using the Q library. You can use the wrapper through ApiAIPromises module. For example:

ApiAIPromises.requestText(
{
    query: "Hello"
})
.then(function (response) {
    // some response processing
    console.log(response.result.action);
})
.fail(function (error) {
    // some error processing
    console.log(error);
});

More samples you can find in the tests module.