Chat

Once a session is open, use the Chat namespace to exchange messages with the AI and retrieve conversation history. Every message is sent in the context of a session so the AI remembers the full conversation. If a document has been attached to the session, the AI can answer questions about its content.

client.sdk.chatsendMessagesessions.getMessages

What this page covers

Sending a user message and receiving the AI reply

How the AI uses session context and attached documents

Handling the synchronous 2-8 second response time

Retrieving the full paginated history of a session

Both methods at a glance

chat-overview.ts

import 'dotenv/config';
import Pdffillr from '@pdffillr/sdk';

const client = new Pdffillr({
  apiKey: process.env['PDFFILLR_API_KEY'],
});

// 1. Assume a session was created earlier - see the Sessions page.
const sessionId = 'clx9f2k3n0000abc123xyz';

// 2. sendMessage() - send a user message and get the AI reply.
const reply = await client.sdk.chat.sendMessage({
  session_id: sessionId,
  message: 'Summarise the key obligations in section 3.',
});
console.log('AI reply:', reply.ai_reply.content);

// 3. getMessages() - retrieve the full conversation history.
const { messages } = await client.sdk.chat.sessions.getMessages(sessionId);
messages.forEach((m) => console.log(`[${m.role}] ${m.content}`));

1. Send a Message

Sends a user message to the AI within an active session and returns the AI's response. The AI has full context of all prior messages in the session. If a document has been attached via documents.attachToSession(), the AI can answer questions about that document's content.

Synchronous - expect 2-8 seconds

This call waits for the LLM to respond before returning. Average response time is 2-8 seconds depending on message complexity. Design your UI to show a loading state while waiting.

client.sdk.chat.sendMessage(body, options?)POST /v1/sdk/chat/send-message

ReturnsPromise<ChatSendResponse>

Required argsbody: ChatSendMessageParams

Body parameters - ChatSendMessageParams

Parameter	Type	Required	Description
session_id	string	Yes	The ID of the active session to send the message to.
message	string	Yes	The user message text to send to the AI.

Response - ChatSendResponse

Field	Type	Description
user_message.role	"user"	Always "user" for the message you sent.
user_message.content	string	The message text you sent.
user_message.created_at	string	ISO 8601 timestamp the message was recorded.
ai_reply.role	"assistant"	Always "assistant" for the AI response.
ai_reply.content	string	The AI's reply text.
ai_reply.created_at	string	ISO 8601 timestamp the reply was generated.

Example

chat-send.ts

import Pdffillr from '@pdffillr/sdk';

const client = new Pdffillr({
  apiKey: process.env['PDFFILLR_API_KEY'],
});

// Send a message to the AI and receive its reply.
const reply = await client.sdk.chat.sendMessage({
  message: 'What is the deadline field on page 2 of the form?',
  session_id: 'clx9f2k3n0000abc123xyz',
});

console.log('[user]     ', reply.user_message.content);
console.log('[assistant]', reply.ai_reply.content);

Session must be active

Sending a message to an ended session will return an error. Always check the session status or handle the error if the session may have been ended elsewhere.

2. Get Session Messages

Returns the complete history for the specific session identified by sessionID - including attached documents, all chat messages exchanged, and any other activity recorded against it. Results arrive in chronological order (oldest first) and are paginated. Use page and size to walk through long sessions - default page size is 50, maximum is 100.

client.sdk.chat.sessions.getMessages(sessionID, query?, options?)GET /v1/sdk/chat/sessions/{sessionId}/messages

ReturnsPromise<MessagePage>

Required argssessionID: string

Query parameters

Parameter	Type	Default	Description
page	number	1	Page number to retrieve. 1-indexed.
size	number	50	Messages per page. Maximum is 100.

Example

chat-get-messages.ts

import Pdffillr from '@pdffillr/sdk';

const client = new Pdffillr({
  apiKey: process.env['PDFFILLR_API_KEY'],
});

// Retrieve the full history for a specific session -
// includes attached docs, chat messages, and other session activity.
const result = await client.sdk.chat.sessions.getMessages('sess_abc123');

result.messages.forEach((m) => {
  console.log(`[${m.role}] ${m.content}`);
});

// Paginate through a long session history.
const page2 = await client.sdk.chat.sessions.getMessages('sess_abc123', {
  page: 2,
  size: 50,   // max: 100
});

Works on ended sessions too

getMessages() works on both active and ended sessions. Use it after sessions.end() to retrieve the complete history - attached documents, messages, and all other recorded activity.