📘 How to Extract Conversation History Using the Kore.ai Public API with a Custom Python Script

Knowledge Articles
,
1

:open_file_folder: Overview

This article explains how to extract conversation history logs from your Kore.ai bot using the getMessagesV2 API and a ready-to-use Python script.

This script automatically handles:

  • :white_check_mark: Pagination using the skip parameter
  • :white_check_mark: Large datasets
  • :white_check_mark: API rate limits (HTTP 429 handling)
  • :white_check_mark: Flattening JSON response data
  • :white_check_mark: Exporting results to Excel

This solution is ideal for customers who need to:

  • Audit user–bot conversations
  • Perform troubleshooting
  • Generate compliance reports
  • Run analytics
  • Export raw data for external systems

:bullseye: What the Script Does

:one: Connects to the Conversation History API

Endpoint used:

/api/public/bot/{botId}/getMessagesV2

:two: Fetches All Messages for a Given Date Range

The script retrieves:

  • Incoming & outgoing messages
  • Message text
  • Session details
  • Channel information
  • User, message & session tags
  • Timestamps

:three: Automatically Handles Pagination

The script:

  • Starts with skip = 0
  • Fetches messages
  • Increases skip by the number of returned records
  • Continues until no more messages are available

:four: Handles API Rate Limits (429)

If the API returns:

429 – Too Many Requests

The script:

  • Waits 2, 4, 6, 8, 10 seconds
  • Retries automatically
  • Continues processing safely

:five: Exports Results to Excel

Creates:

conversation_history.xlsx

Formatted and ready for reporting or analysis.

:puzzle_piece: Prerequisites

Before running the script, ensure:

:check_mark: Python 3.8 or Later

Check version:

python --version

:check_mark: Required Python Libraries

Install dependencies:

pip install requests pandas openpyxl

:check_mark: Valid Kore.ai JWT Auth Token

You must generate a JWT token with permission to access:

  • Conversation History
  • Bot Messages
  • Analytics Logs

Replace in the script:

AUTH_TOKEN = "your_jwt_token_here"

:check_mark: Correct Kore.ai Bot API URL

Replace:

API_URL = "https://<your-host>/api/public/bot/<botId>/getMessagesV2"

Example host formats:

  • https://bots.kore.ai
  • https://de-bots.kore.ai
  • https://dev-bots.kore.ai

:check_mark: Valid Date Range

Set:

DATE_FROM = "YYYY-MM-DD"
DATE_TO = "YYYY-MM-DD"

:inbox_tray: How to Run the Script

  1. Save the file as:
fetch_conversation_history.py

  1. Open Terminal or Command Prompt

  2. Run:

python fetch_conversation_history.py

After execution, you will see:

conversation_history.xlsx

:bar_chart: Output Format

The Excel file includes the following columns:

Column Name Description
id Message ID
botId Bot Identifier
type incoming / outgoing
status Message status
createdOn Timestamp
channel Channel (web, rtm, etc.)
text User or bot message
sessionId Session Identifier
tags_message Message-level tags
tags_user User-level tags
tags_session Session-level tags
tags_altText Accessibility tags

:warning: Notes & Limitations

  • Data availability depends on your logging & retention configuration.
  • JWT token must be valid at runtime.
  • Large date ranges may take several minutes.
  • Some messages (media/system events) may not contain text.

:paperclip: Python Script – Conversation History Export Tool

You can copy and paste the following into a Python file:

import requests
import time
import pandas as pd

# ============= CONFIGURATION =============
API_URL = "https://<your-host>/api/public/bot/<botId>/getMessagesV2"
AUTH_TOKEN = "YOUR_JWT_TOKEN_HERE"
DATE_FROM = "2025-11-20"
DATE_TO = "2025-11-20"
OUTPUT_FILE = "conversation_history.xlsx"
# =========================================

def fetch_messages():
    all_records = []
    skip = 0

    while True:
        payload = {
            "dateFrom": DATE_FROM,
            "dateTo": DATE_TO,
            "skip": skip
        }

        headers = {
            "auth": AUTH_TOKEN,
            "Content-Type": "application/json"
        }

        print(f"Fetching messages with skip={skip} ...")

        # RATE LIMIT HANDLING
        for attempt in range(5):
            response = requests.post(API_URL, json=payload, headers=headers)
            if response.status_code == 429:
                wait_time = (attempt + 1) * 2
                print(f"Rate limited (429). Retrying in {wait_time} seconds...")
                time.sleep(wait_time)
                continue
            break

        if response.status_code != 200:
            print(f"API Error {response.status_code}: {response.text}")
            break

        data = response.json()
        messages = data.get("messages", [])

        print(f"Fetched {len(messages)} records")

        if len(messages) == 0:
            print("\nNo more messages available. Fetch complete.")
            break

        for msg in messages:
            record = {
                "id": msg.get("_id"),
                "botId": msg.get("botId"),
                "type": msg.get("type"),
                "status": msg.get("status"),
                "createdOn": msg.get("createdOn"),
                "channel": msg.get("chnl"),
                "text": extract_text(msg),
                "sessionId": msg.get("sessionId"),
                "tags_message": msg.get("tags", {}).get("messageTags"),
                "tags_user": msg.get("tags", {}).get("userTags"),
                "tags_session": msg.get("tags", {}).get("sessionTags"),
                "tags_altText": msg.get("tags", {}).get("altText")
            }

            all_records.append(record)

        skip += len(messages)

    return all_records


def extract_text(msg):
    comps = msg.get("components", [])
    if not comps:
        return ""

    try:
        return comps[0]["data"].get("text", "")
    except:
        return ""


def export_to_excel(records):
    df = pd.DataFrame(records)
    df.to_excel(OUTPUT_FILE, index=False)
    print(f"\n✅ Export complete! Saved to: {OUTPUT_FILE}")


# ============== MAIN EXECUTION ==============
if __name__ == "__main__":
    print("Starting Kore.ai Conversation History Fetch...\n")
    records = fetch_messages()
    print(f"\nTotal records fetched: {len(records)}")
    export_to_excel(records)

:tada: Summary

This script provides a simple, automated way to:

  • Extract full conversation history
  • Handle large data volumes
  • Manage API throttling
  • Export clean Excel reports

:warning: Disclaimer

This script is provided as a sample reference implementation for demonstration and learning purposes only.

It is not production-ready code, and Kore.ai does not imply or guarantee that this script is optimized, secure, or suitable for enterprise production environments without further validation and customization.

Before deploying in a production environment, customers should:

  • Perform proper security review and testing
  • Validate authentication and token handling mechanisms
  • Implement appropriate logging and monitoring
  • Add error handling enhancements as needed
  • Review compliance with internal IT and data governance policies

Customers are responsible for reviewing, modifying, and validating the script to meet their specific operational and security requirements.
ConversationHistoryV2API Script.txt (3.1 KB)

1 Like