Messages

Message types and utility functions for AI conversations

Overview

The message types in ff-ai extend the Vercel AI SDK’s ModelMessage with additional metadata for persistence and identification.

ConversationMessage

The ConversationMessage namespace provides types and utilities for working with conversation messages.

Type Definition

import type * as Ai from 'ai';
import type * as v from 'valibot';

export namespace ConversationMessage {
  export type Id = string & v.Brand<'ff-ai/ConversationMessageId'>;

  export type Type = Ai.ModelMessage & {
    id: Id;
    createdAt: Date;
  };
}

Message Structure

A ConversationMessage includes:

id · ConversationMessage.Id · required

UUID v7 identifier for the message. Generated automatically using the uuid package.

createdAt · Date · required

Timestamp when the message was created. Used for ordering messages chronologically.

role · 'user' | 'assistant' | 'tool' | 'system' · required

The role of the message sender (inherited from AI SDK)

content · string | ContentPart[] · required

The message content. Can be a simple string or an array of content parts (text, images, tool calls, etc.)

Creating Messages

Messages are typically created automatically when using createTurnHandler. The turn handler’s saveUserMessage and onStep methods handle message creation internally.

If you need to manually create a message (e.g., for custom storage implementations), construct it with the required fields:

import type { ConversationMessage } from 'ff-ai';
import { v7 as createUuid } from 'uuid';

const message: ConversationMessage = {
  id: createUuid() as any, // UUID v7
  createdAt: new Date(),
  role: 'user',
  content: 'Hello, world!'
};

Most users should rely on createTurnHandler to manage message creation automatically rather than creating messages manually.

Converting Messages

convertToUIMessage

Convert a ConversationMessage to the AI SDK’s UIMessage format for rendering in user interfaces:

import { convertToUIMessage } from 'ff-ai';

const conversationMessage = {
  id: '01940b3e-...',
  createdAt: new Date(),
  role: 'assistant',
  content: 'Hello! How can I help you?'
};

const uiMessage = convertToUIMessage(conversationMessage);

// Result:
// {
//   id: '01940b3e-...',
//   role: 'assistant',
//   parts: [
//     { type: 'text', text: 'Hello! How can I help you?' }
//   ]
// }

Signature:

function convertToUIMessage(
  message: ConversationMessage.Type
): Ai.UIMessage

Behavior:

• Extracts text parts from the message content
• Maps tool role to assistant (UI convention)
• Preserves message ID for React keys
• Returns an array of UIMessagePart objects

Message Roles

Messages can have different roles based on their source:

user

Messages sent by the end user. These are the primary input to the AI model.

{
  role: 'user',
  content: 'What is the weather today?'
}

assistant

Messages generated by the AI model. Can include text responses or tool calls.

{
  role: 'assistant',
  content: 'The weather today is sunny with a high of 75°F.'
}

tool

Results from tool executions. These provide context back to the model.

{
  role: 'tool',
  content: [
    {
      type: 'tool-result',
      toolCallId: 'call_123',
      toolName: 'getWeather',
      result: { temp: 75, condition: 'sunny' }
    }
  ]
}

system

System instructions that guide the model’s behavior. Not stored in conversation history by default.

{
  role: 'system',
  content: 'You are a helpful weather assistant.'
}

Content Types

Messages can contain different types of content:

Text Content

Simple string content:

const message = {
  role: 'user',
  content: 'Hello!'
};

Structured Content

Array of content parts for complex messages:

const message = {
  role: 'user',
  content: [
    {
      type: 'text',
      text: 'What is in this image?'
    },
    {
      type: 'image',
      image: 'data:image/png;base64,...'
    }
  ]
};

Tool Calls

Assistant messages requesting tool execution:

const message = {
  role: 'assistant',
  content: [
    {
      type: 'tool-call',
      toolCallId: 'call_123',
      toolName: 'getWeather',
      args: { location: 'San Francisco' }
    }
  ]
};

Working with Messages

Complete Example

import { ConversationMessage, convertToUIMessage } from 'ff-ai';
import { Effect } from 'effect';

const program = Effect.gen(function* () {
  // Create a user message
  const userMessage = ConversationMessage.fromModelMessage({
    role: 'user',
    content: 'Tell me a joke'
  });

  console.log('Message ID:', userMessage.id);
  console.log('Created at:', userMessage.createdAt);

  // Create an assistant response
  const assistantMessage = ConversationMessage.fromModelMessage({
    role: 'assistant',
    content: 'Why did the chicken cross the road? To get to the other side!'
  });

  // Convert for UI rendering
  const uiMessages = [
    convertToUIMessage(userMessage),
    convertToUIMessage(assistantMessage)
  ];

  return uiMessages;
});

Multi-part Messages

import { ConversationMessage } from 'ff-ai';

const message = ConversationMessage.fromModelMessage({
  role: 'user',
  content: [
    { type: 'text', text: 'Analyze this data:' },
    { type: 'text', text: 'Sales: $1M, Growth: 15%' }
  ]
});

console.log('Content parts:', message.content.length);

Tool Result Messages

import { ConversationMessage } from 'ff-ai';

const toolResult = ConversationMessage.fromModelMessage({
  role: 'tool',
  content: [
    {
      type: 'tool-result',
      toolCallId: 'call_abc123',
      toolName: 'getWeather',
      result: {
        location: 'San Francisco',
        temperature: 68,
        condition: 'Partly Cloudy'
      }
    }
  ]
});

Message IDs

Message IDs use UUID v7, which provides:

• Time-ordered: IDs are sortable by creation time
• Unique: Globally unique across distributed systems
• Performance: Efficient for database indexing

import { v7 as createUuid } from 'uuid';

const id = createUuid();
// '01940b3e-5c5a-7b9c-9c3e-f1a2b3c4d5e6'

The first part of the UUID encodes the timestamp, making it naturally ordered.

Type Safety

The ConversationMessage.Id type is branded using Valibot:

const idSchema = v.pipe(
  v.string(),
  v.uuid(),
  v.brand('ff-ai/ConversationMessageId'),
);

This prevents accidental mixing of message IDs with other string types:

function processMessage(id: ConversationMessage.Id) {
  // TypeScript ensures `id` is a valid message ID
}

// Error: Type 'string' is not assignable to type 'ConversationMessage.Id'
processMessage('not-a-valid-id');

// OK: Created through proper channels
const msg = ConversationMessage.fromModelMessage({ role: 'user', content: 'Hi' });
processMessage(msg.id);

Best Practices

Always use fromModelMessage

Don’t manually construct ConversationMessage objects. Use fromModelMessage to ensure IDs and timestamps are properly generated:

// Good
const message = ConversationMessage.fromModelMessage({
  role: 'user',
  content: 'Hello'
});

// Bad - missing id and createdAt
const message = {
  role: 'user',
  content: 'Hello'
};

Use convertToUIMessage for rendering

When displaying messages in a UI, always convert them first:

const uiMessages = messages.map(convertToUIMessage);
return <MessageList messages={uiMessages} />;

Preserve message history

Store complete messages including metadata. Don’t discard id and createdAt as they’re needed for message ordering and deduplication.

Handle multi-part content

Always check if content is a string or array:

if (typeof message.content === 'string') {
  // Handle simple text
} else {
  // Handle content parts
  for (const part of message.content) {
    if (part.type === 'text') {
      // Handle text part
    }
  }
}

Next Steps

Turn Handler

Automatically manage message creation and persistence

Conversation Store

Store and retrieve conversation messages

Examples

See complete examples with messages