Conversation Message

Message schemas define the structure of individual messages exchanged in conversations between users and AI agents. Supports multiple message types (chat, email) with distinct schemas for user-originated and agent-originated messages.

Source: src/core/conversation/conversation-message.schema.ts

---

UserChatMessage

Represents a message sent by a user/customer in a chat conversation.

Schema: UserChatMessageSchema

Attributes

Attribute	Type	Required	Default	Description
conversation_config_id	string	Yes	—	ID of the conversation this message belongs to
message	string	Yes	—	Text content of the message
message_type	literal	Yes	'user'	Fixed to 'user' for user messages
timestamp	number	No	Date.now()	Unix timestamp when sent
llm_conversation_id	string | null	No	—	LLM provider conversation thread ID
user_message_id	string | null	No	—	Unique identifier for this user message
last_assistant_message_id	string	No	—	ID of the previous assistant message

---

AssistantChatMessage

Represents a message generated by the AI agent in a chat conversation.

Schema: AssistantChatMessageSchema

Attributes

Attribute	Type	Required	Default	Description
conversation_config_id	string	Yes	—	ID of the conversation this message belongs to
message	string	Yes	—	Text content of the message
assistant_message_id	string	Yes	—	Unique identifier for this assistant message
message_type	literal	Yes	'assistant'	Fixed to 'assistant' for agent messages
timestamp	number	No	Date.now()	Unix timestamp when sent
llm_conversation_id	string | null	No	—	LLM provider conversation thread ID
last_user_message_id	string	No	—	ID of the user message being responded to

---

UserEmailMessage

Represents an email message sent by a user/customer.

Schema: UserEmailMessageSchema

Attributes

Attribute	Type	Required	Default	Description
conversation_config_id	string	Yes	—	ID of the conversation this message belongs to
message	string	Yes	—	Email body content
subject	string	Yes	—	Email subject line
isEmail	literal	Yes	true	Flag indicating this is an email message
message_type	literal	Yes	'user'	Fixed to 'user' for user messages
timestamp	number	No	Date.now()	Unix timestamp when sent
llm_conversation_id	string | null	No	—	LLM provider conversation thread ID
provider_message_id	string | null	No	—	Provider-specific email message ID

---

AssistantEmailMessage

Represents an email message generated by the AI agent.

Schema: AssistantEmailMessageSchema

Attributes

Attribute	Type	Required	Default	Description
conversation_config_id	string	Yes	—	ID of the conversation this message belongs to
message	string	Yes	—	Email body content
subject	string	Yes	—	Email subject line
isEmail	literal	Yes	true	Flag indicating this is an email message
message_type	literal	Yes	'assistant'	Fixed to 'assistant' for agent messages
timestamp	number	No	Date.now()	Unix timestamp when sent
llm_conversation_id	string | null	No	—	LLM provider conversation thread ID

---

Example

User Chat Message

{
  "conversation_config_id": "conv_abc123",
  "message": "Hi, I need help with my order",
  "message_type": "user",
  "timestamp": 1709856000000,
  "user_message_id": "msg_user_001",
  "last_assistant_message_id": null
}

Assistant Chat Message

{
  "conversation_config_id": "conv_abc123",
  "message": "Hello! I'd be happy to help you with your order. Could you please provide your order number?",
  "message_type": "assistant",
  "timestamp": 1709856001000,
  "assistant_message_id": "msg_asst_001",
  "last_user_message_id": "msg_user_001",
  "llm_conversation_id": "thread_xyz789"
}

User Email Message

{
  "conversation_config_id": "conv_def456",
  "message": "I would like to inquire about your enterprise pricing plans.",
  "subject": "Enterprise Pricing Inquiry",
  "isEmail": true,
  "message_type": "user",
  "timestamp": 1709856000000,
  "provider_message_id": "gmail_msg_abc123"
}

Assistant Email Message

{
  "conversation_config_id": "conv_def456",
  "message": "Thank you for your interest in our enterprise plans. I've attached our pricing guide for your review.",
  "subject": "Re: Enterprise Pricing Inquiry",
  "isEmail": true,
  "message_type": "assistant",
  "timestamp": 1709856300000
}

---

Message Threading

Chat messages support bidirectional threading:

1. User messages reference the previous assistant message via last_assistant_message_id
2. Assistant messages reference the user message being responded to via last_user_message_id
3. LLM context is maintained across messages via llm_conversation_id

This enables:

• Tracking conversation turns
• Maintaining context for AI responses
• Measuring response latency
• Building conversation flow visualizations

---

Related

• Conversation Configuration - Parent conversation records
• Translation - Translation message schemas