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.