02 Manage conversation

You can use the Recast.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 recastai

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

# ...is the same as...

request = recastai.Request('YOUR_TOKEN')

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()