Conversations

Reference for querying conversation sessions and message history programmatically

This documentation describes the chat record query API for retrieving session records and conversation message history within a project. Use it to list sessions, inspect a single session, and retrieve messages for analytics, audit workflows, or downstream integrations.

Base URL

https://transfer.navtalk.ai/api/chat

Authentication

All requests require an apikey query parameter.

Never expose your API key in client-side code or public repositories. API keys should be stored securely on your server and rotated regularly.

Endpoints Overview

Endpoint	Method	Description
/api/chat/sessions	GET	List chat sessions for a project with optional filters
/api/chat/sessions/{sessionId}	GET	Get details for a single chat session
/api/chat/messages	GET	List messages for a specific chat session

List Chat Sessions

Retrieve a paginated list of chat sessions for a project.

GET /api/chat/sessions?apikey=YOUR_API_KEY&startTime=2025-11-12 00:00:00&endTime=2025-11-21 23:59:59&status=1&limit=20

Query Parameters

Name	Type	Required	Description
apikey	string	Yes	Project API key used for authentication
startTime	string	No	Start time in UTC, format yyyy-MM-dd HH:mm:ss
endTime	string	No	End time in UTC, format yyyy-MM-dd HH:mm:ss
status	integer	No	Session status: 0=active, 1=completed, 2=failed
limit	integer	No	Maximum records to return. Default 20, maximum 100
cursor	string	No	Pagination cursor for the next page

Response Example

{
  "code": 200,
  "message": "SUCCESS",
  "data": {
    "data": [
      {
        "id": "709b712f-dede-11f0-92bc-000e1eed4a72",
        "status": 1,
        "startTime": "2025-11-12 18:20:38",
        "endTime": "2025-11-12 18:20:50",
        "videoUrl": null
      },
      {
        "id": "709c1924-dede-11f0-92bc-000e1eed4a72",
        "status": 1,
        "startTime": "2025-11-12 23:17:42",
        "endTime": "2025-11-12 23:17:48",
        "videoUrl": null
      },
      {
        "id": "709c19a1-dede-11f0-92bc-000e1eed4a72",
        "status": 1,
        "startTime": "2025-11-14 07:44:42",
        "endTime": "2025-11-14 07:45:07",
        "videoUrl": null
      }
    ],
    "nextCursor": "MjAyNS0xMS0xNFQwNzo0NDo0Mnw3MDljMTlhMS1kZWRlLTExZjAtOTJiYy0wMDBlMWVlZDRhNzI="
  }
}

Results are ordered by startTime ascending, then by id ascending. videoUrl is null when no video was generated for the session.

Get Single Chat Session

Retrieve detailed information for a specific session.

GET /api/chat/sessions/709b712f-dede-11f0-92bc-000e1eed4a72?apikey=YOUR_API_KEY

Path Parameters

Name	Type	Required	Description
sessionId	string	Yes	Session identifier in UUID format

Query Parameters

Name	Type	Required	Description
apikey	string	Yes	Project API key used for authentication

Response Example

{
  "code": 200,
  "message": "SUCCESS",
  "data": {
    "id": "709b712f-dede-11f0-92bc-000e1eed4a72",
    "status": 1,
    "startTime": "2025-11-12 18:20:38",
    "endTime": "2025-11-12 18:20:50",
    "videoUrl": null
  }
}

This endpoint returns the session object directly in data, not in a nested data.data array.

List Chat Messages

Retrieve messages for a specific chat session with optional filtering and pagination.

GET /api/chat/messages?apikey=YOUR_API_KEY&sessionId=709b712f-dede-11f0-92bc-000e1eed4a72&startTime=2025-11-12 18:20:00&endTime=2025-11-12 18:21:00&role=0&limit=50

Query Parameters

Name	Type	Required	Description
apikey	string	Yes	Project API key used for authentication
sessionId	string	Yes	Session identifier in UUID format
startTime	string	No	Start time in UTC, format yyyy-MM-dd HH:mm:ss
endTime	string	No	End time in UTC, format yyyy-MM-dd HH:mm:ss
role	integer	No	Message role filter: 0=user, 1=AI/assistant
limit	integer	No	Maximum records to return. Default 50, maximum 200
cursor	string	No	Pagination cursor for the next page

Response Example

{
  "code": 200,
  "message": "SUCCESS",
  "data": {
    "data": [
      {
        "id": "70c27233-dede-11f0-92bc-000e1eed4a72",
        "role": 0,
        "messageType": 0,
        "content": "zaiganma",
        "createdAt": "2025-11-12 18:20:43"
      },
      {
        "id": "70c27301-dede-11f0-92bc-000e1eed4a72",
        "role": 1,
        "messageType": 0,
        "content": "It sounds like you're trying to convey something-could you clarify or share a bit more about what you need help with? I'm here to help.",
        "createdAt": "2025-11-12 18:20:45"
      },
      {
        "id": "70c273da-dede-11f0-92bc-000e1eed4a72",
        "role": 0,
        "messageType": 0,
        "content": "Thank You For Watching",
        "createdAt": "2025-11-12 18:20:45"
      }
    ],
    "nextCursor": "MjAyNS0xMS0xMlQxODoyMDo0NXw3MGMyNzNkYS1kZWRlLTExZjAtOTJiYy0wMDBlMWVlZDRhNzI="
  }
}

Message Fields

Field	Type	Description
id	string	Message UUID
role	integer	0=user, 1=AI/assistant
messageType	integer	Message type. Current value is 0 for text
content	string	Plain-text message content
createdAt	string	Message time in yyyy-MM-dd HH:mm:ss format

Messages are ordered by createdAt ascending, then by id ascending.

Usage Guide

1. Get an API key

   Obtain an active API key from your project settings before making requests.

2. List sessions

   Call GET /api/chat/sessions to retrieve sessions for your project. Use startTime, endTime, and status to narrow the result set.

3. Inspect a session

   Use the returned session id as sessionId in GET /api/chat/sessions/{sessionId} when you need session-level details.

4. Fetch messages

   Call GET /api/chat/messages with sessionId to retrieve the conversation history. Use role if you only need user or assistant messages.

5. Paginate with nextCursor

   For both list endpoints, omit cursor on the first request. On subsequent requests, pass the previous nextCursor until it is empty or null.

6. Handle UTC timestamps

   All input time filters should use UTC and the format yyyy-MM-dd HH:mm:ss.

Error Handling

Code	Meaning
400	Invalid API key or missing required parameters
403	API key expired or project not active
404	Session not found or does not belong to the project
500	Internal server error

Security Notes

• Never expose your API key in browser-side code.
• API keys are project-scoped and can expire.
• Send all requests over HTTPS.
• Rotate keys regularly.
• Monitor usage for abnormal traffic patterns.