Skip to main content

AI chat sessions

Use OvokClient to create a chat session, send messages, and read session history. The SDK manages the HTTP request and response types; your application owns the chat interface, message lifecycle, and any real-time delivery channel used by the product.

Create a session​

createChatSession() accepts an assistant configuration, a participant reference, an optional title, and initial messages. The assistant's system field describes its behavior; context and history can provide additional context settings for the server.

const session = await client.createChatSession({
  title: 'Health assistant',
  assistant: {
    system: 'Answer questions using the available patient context.',
    participant: `Practitioner/${assistantId}`,
    history: 10,
    context: [],
  },
  participant: `Patient/${patientId}`,
  messages: [
    {
      sender: `Patient/${patientId}`,
      content: 'I would like to review my latest measurements.',
      mode: 'user',
    },
  ],
});

showChatSession(session);

assistantId, patientId, and showChatSession() are application values. Use participant references and assistant instructions that match the platform workflow configured for the project.

Send and read messages​

Use the session identifier expected by the API for subsequent operations. sendChatMessage() sends one message, while listChatMessages() reads a page of messages. getChatSession() can load the session and a requested number of messages; listChatSessions() lists sessions matching its query.

const message = await client.sendChatMessage(sessionId, {
  sender: `Patient/${patientId}`,
  content: 'What was my most recent blood pressure reading?',
  mode: 'user',
});

const history = await client.listChatMessages(sessionId, {
  _sort: 'sent',
  _count: 50,
});

renderMessages(history.messages);

The example's sessionId, patientId, and renderMessages() come from the application. The query supports _sort, _count, and _offset; use the pagination fields and server contract that apply to your project.

Handle the application lifecycle​

The client methods do not create chat UI or hold an open message stream for your components. Keep session and message state in the application, display request failures, and reconnect using the delivery mechanism configured for the project. Avoid treating a submitted message as an assistant response; read or receive the resulting assistant message through the supported workflow.