02 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 converse_text method.

Usage

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

import sapcai

client = sapcai.Client('YOUR_TOKEN')
request = client.request

# ...is the same as...

request = sapcai.Request('YOUR_TOKEN')

Dialog

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

response = build.dialog({'type': 'text', 'content': 'YOUR_TEXT'}, "YOUR_CONVERSATION_ID")

# Do your code

Conversation Id

Each time you want to start a conversation, simply call dialog with a new conversation_id parameter and the conversation will be created automatically.

Optional parameters

The dialog method can take optional parameters, like memory, proxy and log_level. One or more options can be passed as parameters.

You can pass memory object to the method as follows:

response = build.dialog({'type': 'text', 'content': 'YOUR_TEXT'}, 'A_CONVERSATION_ID', memory = {'MEMORY_KEY': 'MEMORY_VALUE'})

# Do your code

You can also pass log_level option as follows:

response = buil.dialog({'type': 'text', 'content': 'YOUR_TEXT'}, 'A_CONVERSATION_ID', log_level = 'LOG_LEVEL')

# Do your code

You can add a proxy option as follows:

response = build.dialog({'type': 'text', 'content': 'YOUR_TEXT'}, 'A_CONVERSATION_ID', proxy = { 'https': 'http://10.100.10.100:8000' })

# Do your code

Memory management

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

You can access the current state of the memory as follows:

response = build.dialog({'type': 'text', 'content': 'YOUR_TEXT'}, 'A_CONVERSATION_ID')

conversation = response.conversation
memory = conversation.memory

# Do your code

Attributes

The response you receive after a call to the dialog method is an object composed of three parts:

• nlp, containing all the NLP information
• conversation, the text analysis of the input
• messages, containing the messages your bot can send at this stage of the conversation

Conversation attributes

The conversation object contains the following attributes:

Attributes	Type
id	String: the id of the conversation
language	String: the current language of the conversation
memory	Object: the current memory of the conversation
skill	String: the current active skill
skill_occurences	Number: the number of time the same skill was triggered

Message attributes

The message object contains the following attributes:

Attributes	Type
type	String: the type of the message
content	String

For more information about message types and formats, see Bot Connector doc.

NLP attributes

The NPL object contains the following attributes:

Attributes	Type
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	Object[Key: String (Entity Name), Value: Entity]: the array of entities
processing_language	String: the language used to process the input
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

Converse

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

response = request.converse_text('YOUR_TEXT')

reply = response.reply

print(reply)

# Do you code

Conversation Token

Each time you want to start a new conversation, just call converse_text without the optional conversation_token parameter. In the response, you'll receive a new conversation_token, 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.

my_conversation_token = None

response = request.converse_text('I live in Paris.')

# get the conversation_token
my_conversation_token = response.conversation_token

# Do your code

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

my_conversation_token = None

response = request.converse_text('What is the weather?', conversation_token=my_conversation_token)

# get the location variable set at the previous call of converse_text
location = response.get_memory('location')

# Do your code

Action

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

response = request.converse_text("What's the weather in Paris?")

# get the action from the response
action = response.action

# or the next actions
actions = response.next_actions

# if the action is done...
if action and 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 converse_text 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	Action: the action of the conversation
next_actions	Array[Action]: the next actions of the conversation
memory	Object: the memory of the conversation
entities	Array[Entity]: the array of entities
intents	Array[Intent]: 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 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 reply

Method	Params	Return
reply		String: the first reply

response = request.converse_text('YOUR_TEXT')

# get the reply from the response
reply = response.reply

print(reply)

Get the first next action

Method	Params	Return
next_action		String: the first next action

response = request.converse_text('YOUR_TEXT')

# get the action from the response
action = response.next_action

print(action)

Join all replies

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

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

response = request.converse_text('YOUR_TEXT')

reply_joined_by_space = response.joined_replies()
reply_joined_by_newline = response.joined_replies("\n")

Get the memory

Method	Params	Return
get_memory	key: String	Array[Entity]

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

response = request.converse_text('YOUR_TEXT')

city = response.get_memory('city')

if city.raw == 'Paris':
	# Do your code

Sentiment helpers

Method	Params	Return
is_vpositive		Bool: whether or not the sentiment is very positive
is_positive		Bool: whether or not the sentiment is positive
is_neutral		Bool: whether or not the sentiment is neutral
is_negative		Bool: whether or not the sentiment is negative
is_vnegative		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 modify the content of the current conversation.

Set the memory

Method	Params	Return
set_memory()	Dict	Array[Entity]: the new memory

set_memory({'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.

response = request.converse_text('YOUR_TEXT')

response.set_memory({'ingredient': {'value': 'aspargus', 'type': 'vegetable', 'season': 'spring'}})

Reset the memory

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

reset_memory(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.

response = request.converse_text('YOUR_TEXT')

# Example to reset the city object in memory
response.reset_memory('city')

# Example to reset the whole memory
response.reset_memory()

Reset the conversation

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

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

response = request.converse_text('YOUR_TEXT')

# Reset the conversation
response.reset_conversation()

Conversation management

The build client provides several methods to manage you conversations. This API requires the bot version that should be targeted. If versioning is not enabled in the bot, v1 should be passed. Otherwise, see our versioning documentation for more information.

get_conversation

Parameters	Type
user	String: your user slug or id
bot	String: your bot slug or id
version	String: you bot's version; v1 if versioning not enabled
conversationId	String: the conversation id

This method returns a Conversation object.

Usage:

response = request.get_conversation("USER_SLUG", "BOT_SLUG", "VERSION_SLUG", "A_CONVERSATION_ID")

# Do your code

update_conversation

Parameters	Type
user	String: your user slug or id
bot	String: your bot slug or id
version	String: you bot's version; v1 if versioning not enabled
conversationId	String: the conversation id
opts	Dict: the conversation attributes

The opts dict can contain the following keys:

• memory
• skill_occurences
• language

This method returns a Conversation object.

Usage:

response = request.update_conversation("USER_SLUG", "BOT_SLUG", "VERSION_SLUG", "A_CONVERSATION_ID", { "language": "en"})

# Do your code

delete_conversation

Parameters	Type
user	String: your user slug or id
bot	String: your bot slug or id
version	String: you bot's version; v1 if versioning not enabled
conversationId	String: the conversation id

This method returns true if the conversation is properly deleted.

Usage:

response = request.delete_conversation("USER_SLUG", "BOT_SLUG", "VERSION_SLUG", "A_CONVERSATION_ID")

# Do your code