Conversation History API

Fetch the Entire History of a Conversation in a Single Request

The Conversation History API offers a streamlined method for retrieving the full history of a conversation through a single GET request. Unlike analytics, which provides data on a per-transaction basis, allowing you to collate records using a unique callId, the Conversation History API returns all transactions from a conversation in one comprehensive record. Moreover, while analytics captures storage variables and state information, Conversation History focuses solely on conversation-related details such as utterances, prompts, intents, and slot values.

Identifying Conversations

Each conversation on the Parloa platform is assigned a unique identifier, known as conversationId. This ID is generated upon the detection of a WELCOME event, signaling the start of a new conversation. All subsequent interactions within this conversation are grouped under the same conversationId until the conversation ends. Additionally, the conversationId is linked to a specific caller's sessionId, ensuring a unique conversationId is created for each distinct interaction with the same caller.

Accessing the Conversation History

To access the Conversation History via a REST request, you will need the following information:

• Endpoint: Visit the API specification for detailed information.

• ConversationId: This can be found in the debugger context. For example:

  
• Customer-Specific Access Token: Please contact your Partner Manager or Customer Success Manager to access this service.

Tokens are valid for 1 year from creation by default.

To avoid any service interruptions, monitor the token expiration date and contact support for renewal when necessary.

Making a Request

Retrieve the conversation history by executing the following curl command in your terminal:

curl --location 'https://app.parloa.com/api/v1/conversation-history/<CONVERSATIONID>' \
--header 'Authorization: Bearer <TENANT-SPECIFIC-TOKEN>'

Response Structure

The API returns the conversation history in a structured format, detailing each transaction within the conversation, including the exchanges between human and bot, recognized intents, and any storage variables gathered during the conversation. The response is structured as follows:

{
  "conversationId": "<conversation-id>",
  "releaseId": "<release-id>",
  "requesterId": "<requester-id>",
  "userContextId": "<user-context-id>",
  "conversationStart": "<timestamp>",
  "conversationFlow": [
    {
      // Transaction details
    },
    // Additional transactions
  ]
}

The following describes each field:

• conversationId: The unique identifier for the conversation.

• releaseId: The identifier for the Parloa release/deployment during which the conversation occurred.

• requesterId: The identifier for the requester.

• userContextId: Identifies the user's lifetime context, allowing linkage of multiple calls from the same user for a cohesive interaction history.

• conversationStart: The timestamp marking the start of the conversation.

• conversationFlow: An array containing the details of each transaction within the conversation.

The following is an example response:

{
      "conversationId": "b6b45d30-9b33-422d-b2af-c9d335423cfe",
      "releaseId": "5ea1ab5f3ae50a67bd80c77f",
      "requesterId": "ec0c0d8c-6d2c-4a34-b4c0-2b98bcd7d1f4",
      "userContextId": "5ea1ab5f3ae50a67bd80c780",
      "conversationStart": "2020-04-23T14:51:11.378Z",
      "conversationEnd": "2020-04-23T14:51:11.378Z",
      "conversationFlow": [
        {
          "timestamp": "2020-04-23T14:51:11.378Z",
          "human": {
            "intent": "LaunchRequest",
            "message": "LaunchRequest",
            "entities": {}
          },
          "bot": {
            "message": "Welcome, do you want to book a room?"
          }
        },
        {
          "timestamp": "2020-04-23T14:51:11.378Z",
          "human": {
            "intent": "Affirmative",
            "message": "Yes",
            "entities": {}
          },
          "bot": {
            "message": "Great. For how long?"
          }
        },
        {
          "timestamp": "2020-04-23T14:51:11.378Z",
          "human": {
            "intent": "TellDuration",
            "message": "For fifteen minutes",
            "entities": {
              "duration": "15"
            }
          },
          "bot": {
            "message": "Ok. I have booked room 3b for fifteen minutes"
          }
        }
      ]
    }