Analyse text

You can use the SAP Conversational AI API to analyse your text or your audio file, and extract useful information from it.

You can jump at the end of this page if you're looking for more details on the Response returned by the calls to analyseText and analyseFile methods.

Usage

Start by instantiating a SapcaiClient, as shown below:

import sapcai

class ViewController: UIViewController
{
    //Vars
    var bot : SapcaiClient?

    override func viewDidLoad()
    {
        super.viewDidLoad()
        // Do any additional setup after loading the view, typically from a nib.
        self.bot = SapcaiClient(token : "YOUR_TOKEN")
        self.bot = SapcaiClient(token : "YOUR_TOKEN", language: "YOUR_LANGUAGE")
    }
}

class Client

The Client can be instanciated with a token and a language (both optional).

let bot = SapcaiClient(token : "YOUR_TOKEN", language: "YOU_LANGUAGE")

Your tokens:

Copy paste your request access token from your bot's settings.

Your language

let bot = SapcaiClient(token : "YOUR_TOKEN", language: "en")

The language is a lowercase 639-1 isocode.

Text analysis

The analyseText method allows you to make a request to the SAP Conversational AI API. The analyseText method is to make a Text request and takes a text as a String as parameter and a language as a String or a Token as optional parameters. You also need to provide a successHandle and a failureHandle functions that will be called when either the request is done or the request fails. If you pass a token or a language in the options parameter, it will override your default client language or token.

Please note that the length of the text is limited to 512 chars by call.

/**
Make text request to SAP Conversational AI API
*/
func makeRequest()
{
    //Call makeRequest with string parameter to make a text request
    self.bot?.analyseText(<#T##request: String##String#>, successHandler: <#T##(Response) -> Void#>, failureHandle: <#T##(Error) -> Void#>)
}

If a language is provided: the language you've given is used for processing if your bot has expressions for it, else your bot's primary language is used.

If no language is provided: the language of the text is detected and is used for processing if your bot has expressions for it, else your bot's primary language is used for processing.

Audio analysis

In order to make a analyseFile Request you need to implement two methods you need to pass a file as a parameter. You also need to provide a successHandle and a failureHandle functions that will be called when either the request is done or the request fails. If you pass a token or a language in the options parameter, it will override your default client language or token.

Please note that the length of the audio is limited to 10 seconds by call.

file format: .wav

/**
Make File request to SAP Conversational AI API
*/
func makeFileRequest()
{
    if (!(self.requestTextField.text?.isEmpty)!)
    {
        let url = URL(string: self.requestTextField.text!)!
        //Call makeRequest with string parameter to make a text request
        self.bot?.analyseFile(<#T##audioFileURL: URL##URL#>, successHandler: <#T##(Response) -> Void#>, failureHandle: <#T##(Error) -> Void#>)
    }
}

Response

A Response is generated after a call to either analyseText or analyseFile Request methods.

Attributes	Type
raw	String: the raw unparsed json response
uuid	String: the uuid of the request
source	String: the user input
intents	Array[object]: all the matched intents
act	String: the act of the processed sentence
type	String: the type of the processed sentence
sentiment	String: the sentiment of the processed sentence
entities	Array[Entity]: the array of entities
language	String: the language of the input
version	String: the version of the json
timestamp	String: the timestamp at the end of the processing
status	String: the status of the response

Methods

Get the first detected intent

Method	Params	Return
intent()		Object: the first detected intent

/**
Method called when the request was successful

- parameter response: the response returned from the SAP Conversational AI API

- returns: void
*/
func sapcaiRequestDone(_ response : Response)
{
    let intent = response.intent()
    print(intent.slug)
}

Act helpers

Method	Params	Return
isAssert()		Bool: whether or not the act is an assertion
isCommand()		Bool: whether or not the act is a command
isWhQuery()		Bool: whether or not the act is a question
isYnQuery()		Bool: whether or not the act is a query

Type helpers

Method	Params	Return
isAbbreviation()		Bool: whether or not the sentence is asking for an abbreviation
isEntity()		Bool: whether or not the sentence is asking for an entity
isDescription()		Bool: whether or not the sentence is asking for a description
isHuman()		Bool: whether or not the sentence is asking for a human
isLocation()		Bool: whether or not the sentence is asking for a location
isNumber()		Bool: whether or not the sentence is asking for a number

Sentiment helpers

Method	Params	Return
isVPositive()		Bool: whether or not the sentiment is very positive
isPositive()		Bool: whether or not the sentiment is positive
isNeutral()		Bool: whether or not the sentiment is neutral
isNegative()		Bool: whether or not the sentiment is negative
isVNegative()		Bool: whether or not the sentiment is very negative

More

For more information, do not hesitate to dive deeper in the code, as it is commented.