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 refer to the Answer Server Reference.
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 refer to the Answer Server Reference.