Sessions API

Retrieve and browse your chatbot's sessions programmatically through the Developer API.

---

Base URL

https://api.peki.ai/api

Authentication

All endpoints require HMAC-SHA256 authentication. See the Messages API guide for full details on signature generation.

Required Headers

Header	Required	Description
Content-Type	✅	Must be application/json
X-API-Key	✅	Your API key (starts with pk_)
X-Signature	✅	HMAC-SHA256 signature
X-Timestamp	✅	Unix timestamp in seconds

---

List Sessions

Get all chat sessions for your chatbot with pagination. Optionally filter by user.

GET /Dev/{chatbotId}/sessions

Path Parameters

Parameter	Type	Required	Description
chatbotId	string	✅	The unique identifier for your chatbot

Query Parameters

Parameter	Type	Required	Default	Description
userId	string	❌	-	Filter sessions by user ID
page	int	❌	1	Page number (1-based)
pageSize	int	❌	20	Number of items per page

Response

{
  "data": [
    {
      "id": "6612a1b2c3d4e5f6a7b8c9d1",
      "chatbotId": "your_chatbot_id",
      "chatUserId": "6612a1b2c3d4e5f6a7b8c9d0",
      "threadId": "thread_abc123",
      "status": "Active",
      "subject": "Product inquiry",
      "summary": "User asked about pricing plans and feature comparison.",
      "behaviour": "Calm",
      "result": "Resolved",
      "score": 8.5,
      "category": "Sales",
      "sentiment": "Positive",
      "language": "en",
      "tags": ["pricing", "features", "comparison"],
      "chatUserName": "John Doe",
      "source": "Dev",
      "tokenCount": 1250,
      "createdAt": "2025-04-08T12:00:00Z",
      "updatedAt": "2025-04-08T12:05:00Z"
    }
  ],
  "error": null,
  "totalItems": 120,
  "pageSize": 20,
  "currentPage": 1,
  "totalPages": 6
}

Response Fields

Field	Type	Description
id	string	Unique identifier for the session
chatbotId	string	The chatbot this session belongs to
chatUserId	string	The user who initiated the session
threadId	string	Thread identifier for the AI conversation
status	string	Session status: Active, Closed
subject	string	Auto-detected topic of the conversation
summary	string	Auto-generated summary of the session
behaviour	string	Detected user behavior (e.g., Calm, Urgent, Confused)
result	string	Outcome of the session (e.g., Resolved, Pending)
score	number	AI-assigned quality score for the session
category	string	Auto-detected category (e.g., Sales, Support, General)
sentiment	string	Detected sentiment (Positive, Neutral, Negative)
language	string	Detected language code (e.g., en, tr)
tags	string[]	Auto-generated tags for the conversation
chatUserName	string	Display name of the user
source	string	Platform where the session originated
tokenCount	int	Total tokens consumed in the session
createdAt	datetime	When the session was created
updatedAt	datetime	When the session was last updated

---

Get Session

Get a single session by its ID.

GET /Dev/{chatbotId}/sessions/{sessionId}

Path Parameters

Parameter	Type	Required	Description
chatbotId	string	✅	The unique identifier for your chatbot
sessionId	string	✅	The unique identifier for the session

Response

{
  "data": {
    "id": "6612a1b2c3d4e5f6a7b8c9d1",
    "chatbotId": "your_chatbot_id",
    "chatUserId": "6612a1b2c3d4e5f6a7b8c9d0",
    "threadId": "thread_abc123",
    "status": "Closed",
    "subject": "Product inquiry",
    "summary": "User asked about pricing plans and feature comparison.",
    "sentiment": "Positive",
    "score": 8.5,
    "language": "en",
    "tokenCount": 1250,
    "createdAt": "2025-04-08T12:00:00Z",
    "updatedAt": "2025-04-08T12:05:00Z"
  },
  "error": null
}

Error Response

{
  "data": null,
  "error": "Session not found."
}

---

Filtering by User

To get all sessions for a specific user, pass the userId query parameter:

GET /Dev/{chatbotId}/sessions?userId=6612a1b2c3d4e5f6a7b8c9d0

This is useful for building user-specific conversation history views.

---

Pagination

All list endpoints return paginated results with the following metadata:

Field	Type	Description
totalItems	int	Total number of records
pageSize	int	Number of items per page
currentPage	int	Current page number
totalPages	int	Total number of pages

Use the page and pageSize query parameters to navigate through results. Results are ordered by creation date (newest first).

---

Code Examples

JavaScript

const crypto = require("crypto");

const apiKey = "pk_your_api_key";
const apiSecret = "sk_your_api_secret";
const chatbotId = "your_chatbot_id";

// List all sessions
const timestamp = Math.floor(Date.now() / 1000);
const path = `/api/Dev/${chatbotId}/sessions?page=1&pageSize=20`;
const payload = `GET\n${path}\n\n${timestamp}`;
const signature = crypto
  .createHmac("sha256", apiSecret)
  .update(payload)
  .digest("base64");

const response = await fetch(`https://api.peki.ai${path}`, {
  method: "GET",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": apiKey,
    "X-Signature": signature,
    "X-Timestamp": timestamp.toString(),
  },
});

const result = await response.json();
console.log("Sessions:", result.data);
console.log("Total:", result.totalItems);

Python

import hmac, hashlib, base64, time, requests

api_key = 'pk_your_api_key'
api_secret = 'sk_your_api_secret'
chatbot_id = 'your_chatbot_id'

# List sessions for a specific user
user_id = 'USER_ID_HERE'
timestamp = str(int(time.time()))
path = f'/api/Dev/{chatbot_id}/sessions?userId={user_id}&page=1&pageSize=20'
payload = f'GET\n{path}\n\n{timestamp}'

signature = base64.b64encode(
    hmac.new(api_secret.encode(), payload.encode(), hashlib.sha256).digest()
).decode()

headers = {
    'Content-Type': 'application/json',
    'X-API-Key': api_key,
    'X-Signature': signature,
    'X-Timestamp': timestamp
}

response = requests.get(f'https://api.peki.ai{path}', headers=headers)
result = response.json()
print('Sessions:', result['data'])

cURL

API_KEY="pk_your_api_key"
API_SECRET="sk_your_api_secret"
CHATBOT_ID="your_chatbot_id"

TIMESTAMP=$(date +%s)
REQ_PATH="/api/Dev/$CHATBOT_ID/sessions?page=1&pageSize=20"
PAYLOAD="GET\n$REQ_PATH\n\n$TIMESTAMP"
SIGNATURE=$(echo -ne "$PAYLOAD" | openssl dgst -sha256 -hmac "$API_SECRET" -binary | base64)

curl -s "https://api.peki.ai$REQ_PATH" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" \
  -H "X-Signature: $SIGNATURE" \
  -H "X-Timestamp: $TIMESTAMP"

---

Error Codes

Status Code	Description
401	Invalid API key or signature
403	API key doesn't have access to the specified chatbot
404	Session not found
500	Internal server error