Conversation Messages

Messages are the fundamental building blocks of conversations in ChatBotKit, representing each individual communication within a dialogue. Every message has a type (user, bot, context, or activity) and contains text content along with optional metadata, entities, and other attributes.

Understanding message management is essential for building sophisticated chat applications that require precise control over conversation content. You can create messages manually, retrieve specific messages, update message content, or remove messages from conversations.

Creating Messages

Creating a message manually allows you to add content to a conversation without triggering the AI response system. This is useful for importing existing conversations, adding system messages, or building conversation histories programmatically.

To create a message in a conversation:

Replace {conversationId} with the actual conversation ID. The type and text fields are required.

Message Types

Messages can have different types indicating their role in the conversation:

• user: Messages from the end user
• bot: Responses from the AI assistant
• context: System or contextual messages providing information
• activity: Activity or status messages (function calls, actions)

Choose the appropriate type based on the message's purpose. For most manual message creation, you'll use "user" or "bot" types.

Message Fields

When creating a message, you can specify:

• name: Optional name or label for the message
• description: Optional description providing additional context
• type: Required message type (user, bot, context, activity)
• text: Required message content
• meta: Optional custom metadata

Response

After creating a message, the API returns the unique identifier for the created message. This ID can be used to reference the message later.

Use Cases for Manual Message Creation

Manual message creation is commonly used for:

• Importing Conversations: Migrating existing chat histories into ChatBotKit
• Building Context: Adding contextual messages that set up the conversation
• Testing: Creating test conversation scenarios for development
• Conversation Assembly: Constructing conversations programmatically for demonstrations or templates
• System Messages: Adding administrative or system-level messages to conversations

Important Notes:

• Creating a message manually does not trigger an AI response
• Messages must belong to an existing conversation
• The message type affects how it's displayed and processed
• Message creation counts toward your usage limits

Listing Conversation Messages

Retrieving the list of messages in a conversation provides access to the complete dialogue history, allowing you to display conversations, analyze interactions, or export conversation data. The list endpoint supports pagination and ordering to efficiently handle conversations of any length.

To list all messages in a conversation:

Replace {conversationId} with the actual conversation ID. This returns all messages in chronological order (oldest first) by default.

Pagination and Ordering

For conversations with many messages, use pagination to retrieve messages in manageable chunks:

Available parameters include:

• cursor: Pagination cursor from the previous response for fetching the next page
• take: Number of messages to retrieve per request
• order: Sort order - "asc" (chronological, oldest first) or "desc" (reverse chronological, newest first)

The default order is "asc" (chronological), which is most natural for displaying conversations. Use "desc" to retrieve the most recent messages first.

Response Structure

The response includes an items array with message objects:

Each message includes:

• id: Unique message identifier
• type: Message type (user, bot, context, activity)
• text: Message content
• meta: Custom metadata attached to the message
• createdAt: When the message was created
• updatedAt: When the message was last modified

Filtering by Metadata

Messages with custom metadata can be filtered using meta query parameters, allowing you to retrieve specific subsets of messages based on your custom fields and values.

Message Ordering Considerations

The default ascending order (chronological) is optimal for:

• Displaying complete conversations from beginning to end
• Exporting conversation transcripts
• Analyzing conversation flow and progression
• Maintaining natural reading order

Descending order (reverse chronological) is useful for:

• Loading the most recent messages first in a chat UI
• Checking the latest activity in a conversation
• Implementing "load more" functionality that fetches older messages

Performance Considerations

For conversations with very large messages or extensive history:

• Use pagination with appropriate take values (50-100 messages per request)
• Consider caching message lists on your application side
• Use cursor-based pagination for consistent results during active conversations
• Filter by metadata when you only need specific message types

Use Cases

Common scenarios for listing messages include:

• Chat UI Display: Loading and displaying conversation history in your application
• Conversation Export: Retrieving full conversation transcripts for archival or analysis
• Context Analysis: Examining message flow to understand conversation patterns
• Debugging: Reviewing actual message content during development or troubleshooting
• Reporting: Analyzing conversation content for business insights

Best Practices:

• Use ascending order for displaying conversations naturally
• Implement pagination for conversations with many messages
• Cache message lists when appropriate to reduce API calls
• Handle empty conversation cases gracefully
• Consider message type when rendering in your UI
• Store cursor values for efficient pagination

Fetching a Specific Message

Retrieving a single message by its ID provides access to the complete message details, including its content, type, metadata, and timestamps. This is useful when you need to reference a specific message, display message details, or verify message content.

To fetch a specific message:

Replace {conversationId} with the conversation ID and {messageId} with the specific message ID you want to retrieve.

Response Details

The response includes the complete message object:

Use Cases

Fetching individual messages is commonly used for:

• Message References: Displaying quoted or referenced messages in a UI
• Deep Linking: Allowing users to link directly to specific messages
• Verification: Confirming message content after creation or update
• Auditing: Retrieving specific messages for compliance or review
• Context Retrieval: Getting specific message details for processing or analysis

Performance Note: For retrieving multiple messages, use the list endpoint with appropriate filters rather than fetching messages individually, as this is more efficient and reduces API calls.

Updating a Message

Modifying an existing message allows you to correct content, update metadata, or change message attributes after creation. This is useful for editing mistakes, refining message content, or updating associated metadata without deleting and recreating messages.

To update a message:

Replace {conversationId} and {messageId} with the appropriate IDs. You only need to include fields you want to change; all other fields remain unchanged.

Entity Handling During Updates

When you update message text with entity annotations, the system will:

1. Detect PII in the new text content
2. Apply entity annotations to mark sensitive information
3. Redact PII based on your privacy settings
4. Return the updated entity positions

Example with entity annotations:

Metadata Management

When updating metadata, the system intelligently merges the new meta object with existing metadata. This means you can:

• Add new fields without removing existing ones
• Update specific fields while preserving others
• Build up metadata incrementally over time

Response

The API returns:

• id: The ID of the updated message (confirms which message was updated)
• entities: Array of entity positions in the updated text

This allows you to track entity locations after the update, which is important for maintaining PII protection and data privacy compliance.

Use Cases for Message Updates

Common scenarios for updating messages include:

• Content Correction: Fixing typos or errors in message text
• Metadata Enhancement: Adding tags, flags, or other metadata after message creation
• PII Updates: Re-applying entity annotations if privacy requirements change
• Type Changes: Adjusting message type if initially classified incorrectly
• Content Refinement: Improving message content based on user feedback

Important Considerations

• Updating a message does not trigger new AI responses or reprocessing of the conversation
• The updatedAt timestamp will reflect when the message was modified
• Message history and conversation context remain intact
• Entity detection and PII handling apply to the updated content
• You can only update messages in conversations you own

Best Practice: When implementing message editing in your application, consider maintaining an edit history in the metadata for audit trail purposes. This can help with debugging, compliance, and understanding how messages evolved over time.

Deleting a Message

Removing a message from a conversation permanently deletes its content and metadata. This operation is useful for content moderation, privacy compliance, removing errors, or managing conversation content according to your application's requirements.

To delete a message:

Replace {conversationId} and {messageId} with the appropriate IDs. The request body should be an empty JSON object.

What Gets Deleted

When you delete a message, the following is permanently removed:

• The message record itself
• Message text content
• All message metadata
• Entity annotations
• Any custom fields associated with the message

Response

The API returns the ID of the deleted message:

This confirms which message was deleted and can be used for logging, auditing, or updating your application's UI.

Impact on Conversations

Deleting a message affects the conversation in several ways:

Conversation Context:

• The deleted message is removed from the conversation history
• Subsequent AI responses will not have access to the deleted message content
• The conversation flow may be affected if the message provided important context

Message Order:

• Remaining messages maintain their original order and timestamps
• No message IDs or positions are reassigned
• Gaps in the conversation timeline indicate deleted messages

Conversation Relationships:

• The conversation itself is not affected
• Other messages in the conversation remain unchanged
• The conversation's updated timestamp may be modified

Use Cases

Common scenarios for deleting messages include:

• Content Moderation: Removing inappropriate or policy-violating content
• Privacy Compliance: Deleting messages containing sensitive information upon user request
• Error Correction: Removing messages that were created incorrectly or by mistake
• Conversation Cleanup: Pruning unnecessary or test messages from conversations
• PII Removal: Deleting messages that inadvertently contain personal information

Important Considerations

Irreversible Operation: This deletion is permanent and cannot be undone. Ensure you have proper authorization and confirmation flows in your application before allowing message deletion.

Context Impact: Deleting messages can affect conversation coherence. If you remove a question message, the corresponding answer message may lose context. Consider whether you need to delete related messages as well.

Bulk Deletion: To delete multiple messages, you must call the delete endpoint for each message individually. Implement appropriate rate limiting and error handling when performing bulk deletions.

Alternative Approach: Instead of deleting messages, consider using metadata flags to mark messages as "hidden" or "archived" in your application. This preserves conversation integrity while allowing you to filter messages in your UI.

Security Note: You can only delete messages from conversations that belong to your account. The API verifies ownership before performing the deletion.

Synthesizing Message Audio

The message synthesis endpoint converts message text content into natural- sounding speech audio, enabling voice-based interfaces and accessibility features for your conversational applications. This powerful text-to-speech capability leverages OpenAI's advanced TTS (Text-to-Speech) models to generate high-quality audio that can be played back in real-time or downloaded for offline use.

Audio synthesis is particularly valuable for building voice-enabled chatbots, accessibility features for visually impaired users, phone-based AI assistants, and multi-modal conversational experiences. The synthesized audio maintains consistent quality and pronunciation, with intelligent caching ensuring efficient processing of frequently requested messages.

The endpoint supports flexible output formats, allowing you to receive either a direct audio stream (for immediate playback) or a JSON response containing a temporary download URL (for deferred playback or client-side handling). Audio files are automatically cached for 24 hours, significantly reducing costs and latency for repeated synthesis requests of the same content.

Synthesizing Message Text

To convert a message to speech audio:

Replace {conversationId} and {messageId} with the actual conversation and message identifiers. The endpoint synthesizes the complete message text by default.

Response Formats

The endpoint supports two response formats controlled by the Accept header:

JSON Response (Default):

Returns a JSON object with a temporary download URL:

This format is ideal when you need to pass the audio URL to a client application or defer audio playback. The URL includes authentication and remains valid for the duration of the cache period.

Direct Audio Stream:

Returns the audio file directly as an MP3 stream, allowing immediate playback or download. This format is useful for server-side processing or when you want to proxy audio directly to end users without exposing underlying URLs.

Partial Text Synthesis

You can synthesize only a portion of the message text by providing a text fragment:

The endpoint searches for the provided text within the message content and synthesizes only that segment. This is useful for creating audio clips of specific quotes or sections from longer messages, or for progressive audio generation as messages are being composed.

Caching and Performance

The synthesis system implements intelligent caching based on message content:

• Audio is cached for 24 hours after first generation
• Identical text produces identical cached audio (content-addressed)
• Cached audio significantly reduces latency and costs
• Cache keys include the exact text content being synthesized

When you request synthesis of previously synthesized content, the system returns the cached audio instantly without regenerating it. This makes repeated playback of the same messages extremely efficient and cost- effective.

Voice and Model Configuration

The current implementation uses OpenAI's tts-1 model with the alloy voice, providing a natural, balanced voice suitable for most applications. The audio is generated in MP3 format at standard quality, balancing file size and audio fidelity for web and mobile applications.

Usage and Costs

Audio synthesis consumes token credits based on the length of text being synthesized. The system calculates usage using OpenAI's pricing model ($15 per 1M characters), approximately equivalent to GPT-4 token costs. Each synthesis operation records usage metadata including:

• Token count (calculated from character length)
• Model used (GPT-4 equivalent for billing)
• Conversation and message references
• Synthesis reason and timestamp

Usage is tracked even for cached responses to maintain accurate billing and usage analytics.

Use Cases for Message Synthesis

Audio synthesis enables various accessibility and engagement features:

• Voice Assistants: Converting bot responses to speech for voice-based interactions
• Accessibility: Providing audio alternatives for visually impaired users
• Phone Bots: Generating audio responses for telephony integrations
• Multi-modal UX: Enhancing chat interfaces with optional audio playback
• Content Creation: Converting chat content to podcast or video narration
• Language Learning: Providing pronunciation examples in educational applications

Important Notes:

• Synthesis requires valid conversation and message ownership
• Only the message owner can synthesize audio
• Audio URLs expire and should not be permanently stored
• Synthesis counts toward your token usage limits
• Cached audio improves performance and reduces costs
• MP3 is the only currently supported audio format