Messages Reference

Messages are the individual exchanges within a dialogue. Each message belongs to a parent Dialogue and is accessed through it.

Creating Messages

Messages are always created through a Dialogue instance and persisted immediately — there is no batching.

Single Message

const message = await dialogue.saveMessage({
  role: 'assistant',
  content: 'How can I help you today?',
  metadata: { model: 'gpt-4', tokens: 15 },
  tags: ['generated']
});

console.log(message.id);      // auto-generated or custom
console.log(message.content);  // "How can I help you today?"

Multiple Messages

const messages = await dialogue.saveMessages([
  { role: 'user', content: 'What is the weather?' },
  { role: 'assistant', content: 'It is sunny and 72°F.' }
]);

Message Input

Field	Type	Required	Description
role	string	Yes	"user", "assistant", or "system"
content	string | object | object[]	Yes	Message content
id	string	No	Custom message ID (auto-generated if omitted)
tags	string[]	No	Message tags
metadata	Record<string, string | number | boolean>	No	Custom metadata (can't be changed after creation)

Message Class

A Message instance is returned by dialogue.saveMessage(), dialogue.saveMessages(), and dialogue.loadMessages(). Messages are also available via dialogue.messages.

Properties

Property	Type	Mutable	Description
id	string	No	Unique identifier
role	string	No	"user", "assistant", or "system"
content	string | object | object[]	No	Message content
name	string?	No	Optional speaker display name
metadata	Record<string, string | number | boolean>?	No	Custom metadata (set at creation)
created	string	No	Creation timestamp (ISO 8601)
isDirty	boolean	No	true if tags have unsaved changes
tags	string[]	Yes	Message tags

saveTags

Set tags and persist immediately.

await message.saveTags(['reviewed', 'approved']);

Parameters: tags: string[]

Returns: Promise<void>

save

Persist any batched changes (currently just tags).

message.tags = ['reviewed'];
await message.save();

Returns: Promise<void>

remove

Delete this message from the API and remove it from the parent dialogue's message list.

await message.remove();

Returns: Promise<void>

Loading Messages

Messages are loaded through the parent dialogue. The initial getDialogue() call returns up to 10 messages. Use loadMessages() for more.

const dialogue = await db.getDialogue('dialogue-id');

// Initial messages (up to 10)
console.log(dialogue.messages.length);

// Load more with pagination
const messages = await dialogue.loadMessages({ limit: 50 });

// Continue loading
if (dialogue.hasMoreMessages) {
  await dialogue.loadMessages({ limit: 50, next: true });
}

Deleting Messages

Two ways to delete a message:

// Via the dialogue
await dialogue.deleteMessage('message-id');

// Via the message instance
const message = dialogue.messages[0];
await message.remove();

Message Content Types

The content field supports multiple types:

// String content (most common)
await dialogue.saveMessage({
  role: 'user',
  content: 'Hello!'
});

// Object content (structured data)
await dialogue.saveMessage({
  role: 'assistant',
  content: { type: 'tool_result', data: { temperature: 72 } }
});

// Array content (multi-part messages)
await dialogue.saveMessage({
  role: 'assistant',
  content: [
    { type: 'text', text: 'Here is the image:' },
    { type: 'image_url', url: 'https://...' }
  ]
});

TypeScript Types

import type {
  IMessage,
  CreateMessageInput,
  MessageContent,
  ListMessageFilters
} from 'dialogue-db';

IMessage

interface IMessage {
  id: string;
  dialogueId: string;
  role: string;
  content: string | object | object[];
  created: string;
  modified: string;
  metadata: Record<string, string | number | boolean>;
  tags: string[];
  name?: string;
}

CreateMessageInput

type CreateMessageInput = {
  role: string;
  content: string | object | object[];
  id?: string;
  tags?: string[];
  metadata?: Record<string, string | number | boolean>;
};

MessageContent

type MessageContent = string | object | object[];