Conversations API

Create and manage chat sessions with your AI personas.

Chat Sessions

Persistent conversations with full message history.

AI Responses

Automatic AI-generated responses using persona configuration.

Attachments

Send PDFs and documents for context-aware responses.

The Chat Session Object

A chat session represents a conversation between a user and an AI persona, containing all messages and metadata.

Chat Session Structure

JSON

{
  "id": "session_abc123xyz",
  "title": "Customer Support Chat",
  "personaId": "clx1abc123xyz789",
  "userId": "user_def456",
  "platform": "WEB",
  "status": "ACTIVE",
  "organizationId": "cmdhtumx9000nus412v5qezme",
  "createdAt": "2025-01-15T10:30:00.000Z",
  "updatedAt": "2025-01-15T10:45:00.000Z",
  "persona": {
    "id": "clx1abc123xyz789",
    "name": "Customer Support Agent",
    "avatarUrl": "https://..."
  },
  "messages": [
    {
      "id": "msg_001",
      "role": "USER",
      "content": "Hello! I need help with my account.",
      "createdAt": "2025-01-15T10:30:00.000Z"
    },
    {
      "id": "msg_002",
      "role": "ASSISTANT",
      "content": "Hello! I'd be happy to help you with your account...",
      "createdAt": "2025-01-15T10:30:03.000Z"
    }
  ],
  "_count": {
    "messages": 12
  }
}

Field Descriptions

Field	Type	Description
id	string	Unique session identifier
personaId	string	ID of the persona in this conversation
title	string	Optional title for the session
platform	enum	WEB, API, MOBILE, WIDGET
status	enum	ACTIVE, ARCHIVED

The Message Object

Messages represent individual exchanges in a chat session.

Message Structure

JSON

{
  "id": "msg_abc123",
  "chatSessionId": "session_abc123xyz",
  "role": "USER",
  "content": "Hello! I need help with my order.",
  "metadata": {},
  "createdAt": "2025-01-15T10:30:00.000Z",
  "updatedAt": "2025-01-15T10:30:00.000Z"
}

Message Roles

USER

Messages from the user

ASSISTANT

AI-generated responses

SYSTEM

System messages (internal)

Create a Chat Session

Start a new conversation with a persona.

POST

trpc.chat.createSession

Create a new chat session for a persona.

Bash

curl -X POST "https://aipersona.dsethiopia.org/api/trpc/chat.createSession" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -H "X-Organization-ID: your-org-id" \
  -d '{
    "json": {
      "personaId": "clx1abc123xyz789",
      "title": "Customer Support Chat",
      "platform": "API"
    }
  }'

Input Parameters

Parameter	Type	Required	Description
personaId	string	Yes	ID of the persona to chat with
title	string	No	Optional title for the session
platform	string	No	WEB, API, MOBILE, WIDGET (default: WEB)

Send a Message

Send a message to a chat session and receive an AI-generated response.

POST

trpc.chat.sendMessage

Send a user message and receive the AI response.

Bash

curl -X POST "https://aipersona.dsethiopia.org/api/trpc/chat.sendMessage" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -H "X-Organization-ID: your-org-id" \
  -d '{
    "json": {
      "chatSessionId": "session_abc123xyz",
      "content": "Hello! I need help with my account login.",
      "role": "USER"
    }
  }'

Response

JSON

{
  "result": {
    "data": {
      "id": "msg_xyz789",
      "chatSessionId": "session_abc123xyz",
      "role": "ASSISTANT",
      "content": "Hello! I'd be happy to help you with your account login. Could you please tell me what specific issue you're experiencing? For example:\n\n1. Are you getting an error message?\n2. Did you forget your password?\n3. Is your account locked?",
      "metadata": {},
      "createdAt": "2025-01-15T10:30:05.000Z"
    }
  }
}

Tip

The AI response is generated based on the persona's configuration, system prompt, and the full conversation history in the session.

Message Attachments

Send PDF and document attachments with messages for context-aware responses.

Sending Message with PDF Attachment

JavaScript

// Read the file and convert to base64
const fs = require('fs');
const fileBuffer = fs.readFileSync('document.pdf');
const base64Content = fileBuffer.toString('base64');

const response = await fetch('https://aipersona.dsethiopia.org/api/trpc/chat.sendMessage', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': process.env.AIPERSONA_API_KEY,
    'X-Organization-ID': process.env.AIPERSONA_ORG_ID,
  },
  body: JSON.stringify({
    json: {
      chatSessionId: 'session_abc123xyz',
      content: 'Please summarize the key points from this document',
      role: 'USER',
      attachments: [{
        filename: 'document.pdf',
        mimeType: 'application/pdf',
        data: base64Content
      }]
    }
  })
});

Supported Attachment Types

PDF

application/pdf

DOCX

Word documents

DOC

Legacy Word

TXT

Plain text

Markdown

Note

Attachments are processed using the document processor service. The extracted text is added to the message context for the AI to reference.

PDF Upload in Chat

Personas with useAgent: true and pdf_processor in their enabledTools can receive PDF file uploads directly during chat. The uploaded PDF is processed, its text extracted, and the content is made available to the AI as session-scoped context.

Requirements for PDF Upload

Setting	Required Value
useAgent	true
enabledTools	Must include pdf_processor

Note

PDFs uploaded during chat are classified as chat_upload documents and are scoped to the current session only. They do not appear in the persona's permanent knowledge base.

Session-Scoped Context

AIPersona uses session-scoped context to keep conversations focused and relevant.

How Context Scoping Works

Chat uploads are session-scoped: Documents uploaded via chat_upload are only available within the session they were uploaded to. Other sessions cannot access them.
Chat history is session-isolated: When performing RAG retrieval, chat history from other sessions is excluded. Only the current session's conversation is used for context.
Knowledge base is shared: Documents uploaded to the persona's permanent knowledge base (via the edit page or API) are available across all sessions for that persona.

Chat Formatting

Assistant messages are rendered with full markdown support, including code blocks with syntax highlighting, tables, lists, and inline formatting. The chat input uses an auto-resizing textarea that grows with the content.

List Chat Sessions

Retrieve all chat sessions for a user or filter by persona.

GET

trpc.chat.sessions

List chat sessions with optional persona filter.

Bash

curl -X GET "https://aipersona.dsethiopia.org/api/trpc/chat.sessions?input=%7B%7D" \
  -H "X-API-Key: your-api-key" \
  -H "X-Organization-ID: your-org-id"

Response

JSON

{
  "result": {
    "data": [
      {
        "id": "session_abc123xyz",
        "title": "Customer Support Chat",
        "platform": "WEB",
        "status": "ACTIVE",
        "createdAt": "2025-01-15T10:30:00.000Z",
        "persona": {
          "id": "clx1abc123xyz789",
          "name": "Customer Support Agent",
          "avatarUrl": "https://..."
        },
        "_count": {
          "messages": 12
        }
      },
      {
        "id": "session_def456abc",
        "title": "Product Inquiry",
        "platform": "API",
        "status": "ACTIVE",
        "createdAt": "2025-01-14T15:00:00.000Z",
        "persona": {
          "id": "clx1abc123xyz789",
          "name": "Customer Support Agent"
        },
        "_count": {
          "messages": 8
        }
      }
    ]
  }
}

Get Session Messages

Retrieve messages for a specific chat session.

GET

trpc.chat.getMessages

Get messages for a chat session.

Bash

curl -X GET "https://aipersona.dsethiopia.org/api/trpc/chat.getMessages?input=%7B%22id%22%3A%22session_abc123xyz%22%7D" \
  -H "X-API-Key: your-api-key" \
  -H "X-Organization-ID: your-org-id"

Response

JSON

{
  "result": {
    "data": {
      "id": "session_abc123xyz",
      "title": "Customer Support Chat",
      "personaId": "clx1abc123xyz789",
      "platform": "WEB",
      "status": "ACTIVE",
      "createdAt": "2025-01-15T10:30:00.000Z",
      "persona": {
        "id": "clx1abc123xyz789",
        "name": "Customer Support Agent",
        "avatarUrl": "https://..."
      },
      "messages": [
        {
          "id": "msg_001",
          "role": "USER",
          "content": "Hello! I need help with my account.",
          "createdAt": "2025-01-15T10:30:00.000Z"
        },
        {
          "id": "msg_002",
          "role": "ASSISTANT",
          "content": "Hello! I'd be happy to help you with your account...",
          "createdAt": "2025-01-15T10:30:03.000Z"
        }
      ]
    }
  }
}

Session Management

Update and manage chat sessions.

POST

trpc.chat.updateSession

Bash

curl -X POST "https://aipersona.dsethiopia.org/api/trpc/chat.updateSession" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -H "X-Organization-ID: your-org-id" \
  -d '{
    "json": {
      "id": "session_abc123xyz",
      "title": "Updated Chat Title"
    }
  }'