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.

List Chat Sessions

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

GET

trpc.chat.listSessions

List chat sessions with optional persona filter.

Bash

curl -X GET "https://aipersona.dsethiopia.org/api/trpc/chat.listSessions?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 Details

Retrieve a specific chat session with all its messages.

GET

trpc.chat.getSession

Get full session details including message history.

Bash

curl -X GET "https://aipersona.dsethiopia.org/api/trpc/chat.getSession?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"
    }
  }'