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 either a Client or a Request object, as shown below:

<?php
require_once __DIR__ . '/vendor/autoload.php';

use Sapcai\Client;

$client = new Client('YOUR_TOKEN');
$request = $client->request

// ...is the same as...

$request = Client::Request('YOUR_TOKEN');

Text analysis

Use the analyseText method of the client, and after a call to our API, we return a Response object containing the enriched entities extracted from your text, the intents detected and some additional information.

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

<?php
$response = $request->analyseText('YOUR_TEXT');

// get the intent detected
$intent = $response->intent();

// get all the location entities extracted from your text
$locations = $response->all('location');

// Do your code

Audio analysis

Use the analyseFile method of the client, and after a call to our API, we return you a Response object containing the enriched entities extracted from your speech, the intents detected and some other useful information.

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

<?php
// $your_file variable should be the return of the fopen function
$response = $request->analyseText($your_file);

// get the intent detected
$intent = $response->intent();

// get all the location entities extracted from your text
$locations = $response->get('location');

// Do your code

Response

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

Attributes

An instance of the Response class provides each of the following attributes:

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
processing_language	String: the language used to process 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

<?php
$response = $request->analyseText('YOUR_TEXT');

// get the intent detected
$intent = $response->intent();

if ($intent->slug == 'greetings' && $intent->confidence > 0.7) {
  // Do your code
}

Get one entity

Method	Params	Return
get(name)	name: String	Entity: the first Entity matched

<?php
$response = $request->analyseText('YOUR_TEXT');

$location = $response->get('location');

// Do your code

Get all entities matching name

Method	Params	Return
all(name)	name: String	Array[Entity]: all the Entities matched

<?php
$response = $request->analyseText('YOUR_TEXT');

// get all the location entities extracted from your text
$locations = $response->all('location');

// Do your code

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.