Manage your conversation

You can use SAP Conversational AI's 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, you can use this SDK to make it interact with the world.

Jump at the end of this page if you're looking for more details on the Conversation returned by a call to the dialog method.

Usage

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

var sapcai = require('sapcai').default

var client = new sapcai('YOUR_TOKEN')
var build = client.build

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

var build = new sapcai.build('YOUR_TOKEN')

Dialog

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

build.dialog({'type': 'text', content: 'YOUR TEXT'}, { conversationId: 'CONVERSATION_ID' })
  .then(res => {
    console.log(res.messages)
    // Do your code
  })
  .catch(err => console.error('Something went wrong', err))

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 parameter

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

build.dialog({'type': 'text', content: 'YOUR TEXT'}, { conversationId: 'CONVERSATION_ID' }, { my_key: 'my_value' })
  .then(res => {
    console.log(res.messages)
    // Do your code
  })
  .catch(err => console.error('Something went wrong', err))

You can also specify a proxy:

build.dialog({'type': 'text', content: 'YOUR TEXT'}, { conversationId: 'CONVERSATION_ID', proxy: 'my_proxy' })
  .then(res => {
    console.log(res.messages)
    // Do your code
  })
  .catch(err => console.error('Something went wrong', err))

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:

build.dialog({'type': 'text', content: 'YOUR TEXT'}, { conversationId: 'CONVERSATION_ID' })
  .then(res => {
    console.log(res.messages)
    var conversation = res.conversation
    var memory = conversation.memory
    // Do your code
  })
  .catch(err => console.error('Something went wrong', err))

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

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.

getConversation

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:

build.getConversation('user', 'bot', 'version_id', 'conversationId')
  .then(res => {
    console.log(res)
    // Do your code
  })
  .catch(err => console.error('Something went wrong', err))

updateConversation

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	Object: the conversation attributes

The opts object can contain the following keys:

• memory
• skill_occurences
• language

This method returns a Conversation object.

Usage:

build.updateConversation('user', 'bot', 'version_id', 'version_id', 'conversationId', { language: 'en' })
  .then(res => {
    console.log(res)
    // Do your code
  })
  .catch(err => console.error('Something went wrong', err))

deleteConversation

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:

build.deleteConversation('user', 'bot', 'version_id', 'conversationId')
  .then(res => {
    console.log(res)
    // Do your code
  })
  .catch(err => console.error('Something went wrong', err))