Manage conversation

You can use the SAP Conversational AI API to bring your bot to life !

Once you have created your bot on the platform and built your conversation flow in the Build tab of your bot's page, you can use this SDK to make it interact with the world.

You can jump at the end of this page if you're looking for more detail on the Conversation returned by a call to the converseText method.

Usage

Start by instantiating either a Client or a Request object, as shown below:

<?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

Converse

You can then interact with it using the converseText method, as follows:

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

// get the next reply your bot can respond
$reply = $response->reply()

// Do your code

Conversation Token

Each time you want to start a new conversation, just call converseText without the optional conversationToken parameter. In the response, you'll receive a new conversationToken, corresponding to a fresh new conversation.

Note that you can also pass your own conversationToken. It can be useful if you use a channel that already provides you unique conversation ids. Check this section to see how to get the conversation ids from channels.

<?php
$my_conversation_token = null;

$response = $request->converseText('I live in Paris.');

$my_conversation_token = $response->conversation_token;

// Do your code

Then, you can pass it to the following converseText calls to continue the previously started conversation and benefit from the information already extracted.

<?php
$response = $request->converseText('I live in Paris.', [ 'conversation_token' => $my_conversation_token ]);

// get the location variable set at the previous call of converseText
$location = $response->getMemory('location')

// Do your code

Optional parameter

You can specify a proxy to your request

<?php
$response = $request->converseText('YOUR_TEXT', ['conversation_token' => 'my_conversation_token', 'proxy' => 'my_proxy' ]);

// Do your code

If you want to start a conversation and fill your bot memory, you can pass an optional parameter memory, as follows

<?php
$memory = (object)[
  'ingredient' => (object)[
    'value' => 'asparagus',
    'type' => 'vegetable',
    'season' => 'spring',
  ]
];

$response = $request->converseText('YOUR_TEXT', ['conversation_token' => 'my_conversation_token' ], $memory);

// Do your code

Action

In the response you get from calling converseText, you can access action objects as follows:

<?php
$response = $request->converseText('I live in Paris.');

// get the action from the response
$action = $response->action;

// or the next actions
$next_actions = $response->next_actions;

if ($action && $action->done) {
  // ...make a call to a weather API
}

An action is a wrapper around the intent detected, and contains, along with a slug and a reply, a boolean called done that you can use to check if the current action is complete or not (if there's a missing notion for example).

Memory management

Each conversation has an attribute - called 'memory' - used to store the notions extracted from the input it receives. For example, if your user starts the conversation by telling his name, and you need it later in the conversation, you don't need to ask him again, it will be stored in the 'memory' object.

The Conversation class provides a lot more attributes and methods, such as methods to manage the memory inside your conversations, as documented at the end of this page.

Connect

You can use the Connect API of this SDK to connect your bot to channels like Messenger, Kik or Slack.

You can find more information here.

Conversation

An instance of Conversation is generated after a call to the converseText method.

Attributes

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

Attributes	Type
raw	String: the raw unparsed json response
uuid	String: the universal unique id of the api call
source	String: the user input
replies	Array[String]: all the replies
action	Object: the action of the conversation
nextActions	Array[Object]: the next actions of the conversation
memory	Object: the memory of the conversation
entities	Array[Entity]: the array of entities
intents	Array[Object]: all the matched intents
conversation_token	String: the conversation token
sentiment	String: the sentiment of the processed input
language	String: the language of the input
processing_language	String: the language used to process the language
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 reply

Method	Params	Return
reply()		String: the first reply

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

$reply = $response->reply();

var_dump($reply);

// Do your code

Get the first next action

Method	Params	Return
nextAction()		Action: the first next action

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

$action = $response->nextAction();

var_dump($action);

// Do your code

Join all replies

Method	Params	Return
joinedReplies()	sep: String	String: the replies concatenated

If there is no sep parameter provided, the replies will be joined with a space.

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

$replyJoinedBySpace = $response->joinedReplies();
$replyJoinedByNewLine = $response->joinedReplies("\n");

Get the memory

Method	Params	Return
getMemory()	key: String	Array[Entity]

If there is no key parameter provided, the entire memory is returned

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

$city = $response->getMemory('city');

if ($city->raw == 'Paris') {
  // Do your code
}

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

Memory Management

The methods below allow you to manage the memory of the current conversation. You can set a specific value in the memory of your bot, or reset the conversation or the memory.

Please note that those functions are asynchronous, and that they modify the content of the current conversation.

Set the memory

Method	Params	Return
setMemory()	Object	Array[Entity]: the new memory

setMemory({ key: {value} })

This method allows you to modify the memory of a conversation. Please note that you can only set the value that has an existing key in the conversation on the platform.

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

$memory = (object)[
  'ingredient' => (object)[
    'value' => 'asparagus',
    'type' => 'vegetable',
    'season' => 'spring',
  ]
];

$response->setMemory($memory);

Reset the memory

Method	Params	Return
resetMemory()	String	Array[Entity]: the new memory

resetMemory(key)

This method allows you to reset a specific field in the memory of a conversation. If no key is given, the entire memory will be reset.

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

// Example to reset the city object in memory
$response->resetMemory('city');

// Example to reset the whole memory
$response->resetMemory();

Reset the conversation

Method	Params	Return
resetConversation()		Array[Entity]: the API response

This method allows you to reset the entire conversation, from its memory to its action already done.

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

// Reset the conversation
$response->resetConversation();