Chat Data Model
This page defines the data structures used in the Chat API for messages, conversations, and response types.
ChatbotMessage
The top-level message object in a conversation.
| Field | Type | Description |
|---|
message_id | string | Unique identifier for the message |
conversation_id | string | ID of the conversation this message belongs to |
message_type | MessageType | Type of message content |
content | object | Message content (varies by message type) |
sender | string | Sender identifier (user or ai) |
timestamp | string | ISO 8601 timestamp |
snippets | list of Snippet | Structured content blocks |
sources | list of Source | Source attributions |
MessageType
| Value | Description |
|---|
TEXT | Plain text or markdown message |
BUTTONS | Message with clickable buttons |
FORM | Message with form fields |
FEEDBACK | Feedback request (rating/thumbs) |
URL | URL/link message |
Complete list of MessageType values.
TextMessage
A plain text or markdown-formatted message.
| Field | Type | Description |
|---|
text | string | The message content (supports markdown) |
A message presenting clickable options to the user.
| Field | Type | Description |
|---|
text | string | Prompt text above the buttons |
buttons | list of Button | List of button options |
| Field | Type | Description |
|---|
label | string | Display text for the button |
value | string | Value sent when the button is clicked |
A message presenting form fields for structured input.
| Field | Type | Description |
|---|
text | string | Prompt text above the form |
fields | list of FormField | List of form fields |
| Field | Type | Description |
|---|
name | string | Field identifier |
label | string | Display label |
type | FormFieldType | Field type (text, number, select, etc.) |
required | boolean | Whether the field is required |
options | list of strings | Options for select/dropdown fields |
default_value | string | Default value |
| Value | Description |
|---|
TEXT | Single-line text input |
TEXTAREA | Multi-line text input |
NUMBER | Numeric input |
SELECT | Dropdown selection |
CHECKBOX | Boolean checkbox |
DATE | Date picker |
Complete list of FormFieldType values.
FeedbackMessage
A message requesting user feedback on the AI response.
| Field | Type | Description |
|---|
text | string | Prompt text for the feedback request |
feedback_type | string | Type of feedback (thumbs, rating, text) |
Snippet Types
Snippets are structured data blocks within messages. The platform supports the following snippet types:
| Snippet Type | Description |
|---|
TextSnippet | Formatted text block |
CodeSnippet | Code with syntax highlighting |
TableSnippet | Tabular data |
ImageSnippet | Inline image |
FileSnippet | Downloadable file attachment |
LinkSnippet | Hyperlink with preview |
ListSnippet | Ordered or unordered list |
ChartSnippet | Data visualization |
SourceSnippet | Knowledge source citation |
ActionResultSnippet | Output from a workflow action |
ErrorSnippet | Error message with details |
ProgressSnippet | Progress indicator |
SuggestionSnippet | Suggested follow-up questions |
JSONSnippet | Formatted JSON data |
MarkdownSnippet | Rich markdown content |
Complete list of snippet types.
Source
A source attribution linking a response to its knowledge origin.
| Field | Type | Description |
|---|
title | string | Title of the source document |
url | string | URL to the source document |
snippet | string | Relevant excerpt from the source |
source_type | string | Type of source (e.g., confluence, gdrive) |
ConversationChatMessageHistory
The full message history for a conversation.
| Field | Type | Description |
|---|
messages | list of ChatbotMessage | All messages in the conversation |
metadata | ConversationMetadata | Conversation metadata |
| Field | Type | Description |
|---|
conversation_id | string | Unique conversation identifier |
persona_id | string | AI Employee ID |
created_at | string | ISO 8601 creation timestamp |
updated_at | string | ISO 8601 last update timestamp |