Message History File Format

The LlmClient control uses a JSON-formatted message history file to support exporting and importing conversation state between application sessions. This format is used by the ExportHistory and ImportHistory methods and is intended to provide a simple, human-readable representation of the conversation history associated with a client session.

A message history file contains both the messages sent by the client application and the responses generated by the model. Together, these entries represent the conversational context for the session. The file does not contain information about the client session, aside from the provider type and model name. It does not contain user names, authorization tokens or any information related to the service account.

The history file may contain sensitive or private information, including user prompts, model responses or application-specific data. Applications should take reasonable precautions to protect these files, particularly if they are stored, transmitted or made available for users to download.

The following example shows a simplified message history file containing a single message turn:

{
  "version": 1,
  "provider": 1,
  "created": 1715000000,
  "messages": [
    {
      "message": {
        "role": 1,
        "reasoning": 0,
        "flags": 0,
        "id": 1,
        "timestamp": 1715000001,
        "maxTokens": 0,
        "inputTokens": 12,
        "content": "Hello"
      },
      "response": {
        "role": 2,
        "flags": 0,
        "messageId": 1,
        "status": 1,
        "elapsed": 812,
        "timestamp": 1715000002,
        "outputTokens": 24,
        "model": "gpt-5.4-nano",
        "content": "Hi there."
      }
    }
  ],
  "messageCount": 1,
  "model": "gpt-5.4-nano"
}

File Structure

A message history file consists of a root JSON object which contains session metadata and an array of message turns.

version

The format version number used by the exported history file.

provider

The numeric provider identifier associated with the session.

created

A Unix timestamp value which indicates when the history file was created.

messages

An array containing the exported message turns.

messageCount

The number of message turns stored in the history file.

model

The default model name associated with the exported session.

Message Turns

Each entry in the messages array represents a complete message turn consisting of two objects:

A message object which contains the client input

A response object which contains the model output

Applications should not depend on undocumented fields or the exact formatting of exported history files. Future versions of the control may add additional fields or metadata while maintaining compatibility with previous versions where possible.

Remarks

The message history format is intended primarily for exporting, importing and persisting conversation state between application sessions. Although the file format is human-readable JSON text, applications should avoid modifying exported history files unless they fully understand the relationship between the stored values.

Changing values such as the provider identifier, model name, message role or status values may produce undefined or unexpected results when the history is imported. Applications should not modify role identifiers or assume that numeric values used internally by the API will remain unchanged in future versions.

Modifying the message or response content may also invalidate related metadata such as token usage values. For example, changing the content field may result in incorrect inputTokens or outputTokens values being associated with the imported conversation history.

File Structure

Message Turns

Remarks

See Also