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 SapcaiClient, as shown below:

import sapcai

class ViewController: UIViewController
{
    //Vars
    var bot : SapcaiClient?

    override func viewDidLoad()
    {
        super.viewDidLoad()
        // Do any additional setup after loading the view, typically from a nib.
        self.bot = SapcaiClient(token : "YOUR_TOKEN")
        self.bot = SapcaiClient(token : "YOUR_TOKEN", language: "YOUR_LANGUAGE")
    }
}

Converse

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

/**
Make text request to SAP Conversational AI API
*/
@IBAction func makeRequest()
{
    if (!(self.requestTextField.text?.isEmpty)!)
    {
        //Call makeRequest with string parameter to make a text request
        self.bot?.converseText(<#T##request: String##String#>, successHandler: <#T##(Response) -> Void#>, failureHandle: <#T##(Error) -> Void#>)
    }
}

You can also send a .wav file for your bot to understand, as shown below:

/**
Make File request to SAP Conversational AI API
*/
func makeFileRequest()
{
    if (!(self.requestTextField.text?.isEmpty)!)
    {
        let url = URL(string: self.requestTextField.text!)!
        //Call makeRequest with string parameter to make a text request
        self.bot?.converseFile(<#T##audioFileURL: URL##URL#>, successHandler: <#T##(Response) -> Void#>, failureHandle: <#T##(Error) -> Void#>)
    }
}

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.

Action

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

    /**
     Method called when the converse request was successful
     
     - parameter response: the response returned from the SAP Conversational AI API
     
     - returns: void
     */
    func sapcaiRequestDone(_ response : ConverseResponse)
    {
        let action = response.action
    }

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.

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
conversationToken	String: the conversation token
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

Methods

Get the first reply

Method	Params	Return
reply()		String: the first reply

    /**
     Method called when the converse request was successful
     
     - parameter response: the response returned from the SAP Conversational AI API
     
     - returns: void
     */
    func sapcaiRequestDone(_ response : ConverseResponse)
    {
        print(response.reply())
    }

Get the first next action

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

    /**
     Method called when the converse request was successful
     
     - parameter response: the response returned from the SAP Conversational AI API
     
     - returns: void
     */
    func sapcaiRequestDone(_ response : ConverseResponse)
    {
        let nextAction = response.nextAction()
        print(nextAction.slug)
    }

Get the memory

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

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

    /**
     Method called when the converse request was successful
     
     - parameter response: the response returned from the SAP Conversational AI API
     
     - returns: void
     */
    func sapcaiRequestDone(_ response : ConverseResponse)
    {
        print(response.get('location'))
    }

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.

    /**
     Method called when the converse request was successful
     
     - parameter response: the response returned from the SAP Conversational AI API
     
     - returns: void
     */
    func sapcaiRequestDone(_ response : ConverseResponse)
    {
        response.setMemory([
            ingredient: [
                value: 'asparagus',
                type: 'vegetable',
                season: 'spring',
            ]
        ])
    }

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.

    /**
     Method called when the converse request was successful
     
     - parameter response: the response returned from the SAP Conversational AI API
     
     - returns: void
     */
    func sapcaiRequestDone(_ response : ConverseResponse)
    {
        print(response.resetMemory('location'))
        print(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.

    /**
     Method called when the converse request was successful
     
     - parameter response: the response returned from the SAP Conversational AI API
     
     - returns: void
     */
    func sapcaiRequestDone(_ response : ConverseResponse)
    {
        print(response.resetConversation())
    }