Conversation Logs Retrieval

This guide explains the workflow and endpoints required to retrieve and filter detailed conversation logs from the UNITH platform.

The log retrieval workflow consists of three main steps: Authentication, Getting Conversations, and Fetching Session Logs.

Step 1: Authentication

1.1 Obtain Bearer Token

To access the logs, you must first obtain a Bearer token using your account credentials.

Endpoint: POST https://platform-api.unith.ai/auth/token

Request Body

{
  "email": "your-email@example.com",
  "secretKey": "your-secret-key"
}

CURL Example

curl -X POST "https://platform-api.unith.ai/auth/token" \
-H "Content-Type: application/json" \
-d '{
"email": "your-email@example.com",
"secretKey": "your-secret-key"
}'

The response will contain a JSON Web Token (JWT) under data.bearer. Save this token to use in the subsequent API calls as an Authorization header.

Response

{
"data": {
"bearer": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
}

1.2 Retrieve Organization ID (Org ID)

Use the token obtained in the previous step to fetch your user profile, which contains your Organization details.

Endpoint: GET https://platform-api.unith.ai/user/me****

curl -X 'GET' \
  '[https://platform-api.unith.ai/user/me](https://platform-api.unith.ai/user/me)' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer yourBearerToken'

Response:

{
  "id": "yourUserId",
  "organisation": {
    "id": "thisIsYourOrgId",  
    "publicId": "thisIsYourPublicOrgId",  // <-- Use this ID in all subsequent steps
    ...
  },
  ...
}

Step 2: Get Conversations (Filtering by Metadata)

Retrieve a list of conversation sessions for your organization within a specified date range.

Endpoint: GET https://api.data.unith.ai/conversations

Query Parameters

Headers

• Authorization: Bearer <token from Step 1>

Filter by Username

The username field is now available as a separate column in conversation logs, making it easier to track and analyze user-specific conversations.

Previous Behavior:

• Username was included as a suffix in session_id: "sessionId_username"
• Required parsing the session ID to extract username

Current Behavior:

• Username is now available as a dedicated field

To enable username tracking, define the data-username attribute when embedding the Digital Human:

HTML Embed Configuration

<unith-widget
  head_id="UNITH-1595"
  org_id="U-760"
  api_key="YOUR_API_KEY"
  username="alice"
>
</unith-widget>

Response Example

Below is an example of a retrieved conversation, showing the username included in the session_id.

"conversations": [
  {
    "session_id": "20ab19bf-942b-4fc8-bf36-1bc4d7d53103_alice",
    "start_time": "2025-09-09T06:45:07.211821",
    "end_time": "2025-09-09T06:46:40.504327",
    "head_id": "UNITH-1595",
    "head_name": null,
    "org_id": "U-760",
    "message_count": 18
  }
]

CURL Example (With Date Range)

curl -X GET "https://7bdt5ca661.execute-api.eu-west-
1.amazonaws.com/conversations?org_id=your-public-org-id&start_date=2023-06-
01T00:00:00Z&end_date=2025-06-01T00:00:00Z&head_id=" \
-H "Authorization: Bearer YOUR_TOKEN_HERE"

Custom Tracking with data_tag

The new data_tag field enables flexible custom tracking for any use case. This field accepts any string value of your choice, allowing you to segment and analyze conversations based on your specific requirements.

Common Use Cases:

• Multi-Domain Tracking: Track the same Digital Human across different websites
• Customer Segmentation: Tag conversations by user type (e.g., "segment:enterprise", "segment:trial")
• Campaign Tracking: Associate conversations with marketing campaigns (e.g., "campaign:summer2025")
• A/B Testing: Track different variants (e.g., "variant:control", "variant:test")

<unith-widget
  head_id="yourHeadId"
  org_id="yourOrgId"
  api_key="yourApiKey"
  username="alice"
  data_tag="domain:example.com"
>
</unith-widget>

Multiple Values Example:

You can use any delimiter format that suits your needs:

<!-- Colon delimiter -->
<unith-widget data_tag="source:google:campaign:spring2026"></unith-widget>

Enhanced Session Metadata

The UNITH platform now includes enhanced metadata fields in conversation logs, providing deeper insights into user sessions and enabling more flexible analytics.

Session Data Fields

Direct Fields (sent at root level):

Metadata Fields (extracted from request_metadata):

Step 3: Get Session Logs

Retrieve the detailed message logs (the full transcript) for a specific conversation session.

Endpoint: GET https://api.data.unith.ai/sessions/{public_org_id}/{session_id}

Path Parameters

• public_org_id: Your organization ID.
• session_id: The full session ID (including the username suffix, if used) obtained from Step 2.

Headers

• Authorization: Bearer <token from Step 1>

CURL Example

curl -X GET "https://api.data.unith.ai/sessions/your-public-org-id/session-id-here" \
-H "Authorization: Bearer YOUR_TOKEN_HERE"

Complete Workflow Example

This section provides a complete, sequential command line example for retrieving logs.

# Step 1: Get authentication token (stores token in environment variable $TOKEN)
TOKEN=$(curl -s -X POST "[https://platform-api.unith.ai/auth/token](https://platform-api.unith.ai/auth/token)" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "your-email@example.com",
    "secretKey": "your-secret-key"
  }' | jq -r '.data.bearer')
  
# Step 2: Get conversations
curl -X GET "https://api.data.unith.ai/conversations?org_id=your-public-org-id&start_date=2023-06-
01T00:00:00Z&end_date=2025-06-01T00:00:00Z" \
-H "Authorization: Bearer $TOKEN"

# Step 3: Get specific session logs (replace session-id with actual ID from
Step 2)
curl -X GET "https://api.data.unith.ai/sessions/your-public-org-id/session-id-here" \
-H "Authorization: Bearer $TOKEN"

Important Notes

• Token Expiration: Bearer tokens have an expiration time of 7 days. If you receive authentication errors, you must generate a new token via the authentication endpoint.
• Organization ID: Always ensure you use the correct organization ID associated with your account.
• Date Format: All date parameters (start_date, end_date) must strictly use the ISO 8601 format (e.g., YYYY-MM-DDTHH:mm:ssZ).
• Session IDs: Session IDs are UUIDs retrieved from the conversations endpoint, and will include the optional _{{username}} suffix if configured in the embed code.