Hold a Conversation

To start conversations, you must create a conversation session in Answer Server, which generates a session token. You use this session token to track a particular conversation in the Converse action.

Create a Conversation Session

To create a conversation session, you use a ManageResources action in a POST request method, with the details of the operation to perform provided in the Data parameter as a JSON object.

Action=ManageResources&SystemName=MyConversations
data={
   "operation":"add",
   "type":"conversation_session"
}

You can optionally pass session variables to the conversation session, so that the conversation does not have to ask for information that is already available in your system. For example, you might pass in the user name from the login that the user provided when they signed into your application. For example:

Action=ManageResources&SystemName=MyConversations
data={
   "operation":"add",
   "type":"conversation_session",
   "session_variables": [
      {"name": "USER_NAME", "value": "Jane"},
      {"name": "COUNTRY", "value": "USA"}
   ]			
}

You can retrieve the full schema for the JSON object to use by using the GetResources action. See Find the JSON Schema for Your Update.

NOTE: The ManageResources action fails if you attempt to use request JSON that contains properties that are not contained in the appropriate schema.

TIP: Typically, OpenText recommends that you send ManageResources as a POST request. For testing, you can use a GET request, in which case you must base64 encode the JSON data.

This action returns a session token, which you can use in the Converse action.

Retrieve Active Conversation Sessions

To retrieve the session IDs of your active conversation sessions, you use a GetResources action, with Type set to conversation_session. For example:

action=GetResources&SystemName=MyConversations&Type=conversation_session

Start and Continue a Conversation

To run conversations, you use the Converse action. You must set SystemName to the name of the conversation system, and SessionID to the session token that you receive from the ManageResources action when you create the session.

For example:

action=Converse&SystemName=MyConversations&SessionID=860028728520387723

This example starts the conversation without providing any user text. In this case, Answer Server runs the conversation task that you have configured as your initial task and returns the response from that task. See Initial Task.

To provide user text, you add the Text parameter:

action=Converse&SystemName=MyConversations&SessionID=860028728520387723&Text=I would like to buy some shares

Each action with the same session ID carries on the conversation, running the appropriate conversation tasks. You provide each new user text selection in the Text parameter, and the action returns the response from the conversation task.

When the Converse action calls out to the Ask action to ask a question, the Ask response can include additional information to allow the user to disambiguate between multiple possible answers. In this case, Answer Server returns the possible answers in the Converse action response, along with the disambiguation information. At this point, you can use the special string ANSWER_NUMBER_N to return a particular answer from the list, where N is the number of the answer (starting from 0).

You can retrieve the XML Schema Definitions (XSDs) for the Converse action by using the GetResources action with the Type parameter set to XSD. For more information, refer to the Answer Server Reference.

Close a Conversation Session

At the end of a conversation, you can delete the conversation session to free up the session license. To delete the conversation session, you use another ManageResources action, with the delete operation and the appropriate session ID. For example:

Action=ManageResources&SystemName=MyConversations
data={
   "operation":"delete",
   "type":"conversation_session",
   "ids":["860028728520387723"]
}

TIP: You can configure Answer Server to automatically close inactive conversation sessions, by setting the SessionExpirationInterval and SessionExpirationIdleTime configuration parameters in the system configuration section. For more information, see Configure the Conversation System, and Conversation System Configuration Parameters.

Retrieve a Conversation Transcript

You can retrieve a full transcript of a particular conversation session by using the GetResources action with Type set to Transcript, and IDs set to the ID of the conversation session that you want to retrieve. For example:

action=GetResources&Type=Transcript&SessionID=860028728520387723

TIP: You can also use the transcript in your conversation Lua scripts. See Lua Processing Scripts and Conversation System Configuration Parameters.