Conversation Configuration

Conversation configurations manage interaction sessions between users and AI agents through various channels (phone, SMS, web chat, email). They track message history, status progression, call metadata, and relationship to deployment configurations.

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

---

ServiceConversationConfig

Complete conversation record extending base configuration with conversation-specific identifiers, provider metadata, call direction, recording URLs, and transfer details.

Schema: ServiceConversationConfigSchema

Attributes

Attribute	Type	Required	Default	Description
id	string	Yes	—	Unique identifier for this conversation record
organization_id	string	Yes	—	ID of the organization that owns this conversation
project_id	string	Yes	—	ID of the project this conversation is associated with
channel_id	string	Yes	—	ID of the deployment channel
deployment_config_id	string	Yes	—	ID of the deployment configuration
channel_identifier	string	Yes	—	Communication endpoint (phone number, widget ID, email)
conversation_type	enum	Yes	—	Type of conversation channel. One of OTT_CHAT, TELEPHONY_CALL, SMS, EMAIL, or WHATSAPP.
record_id	string | null	No	—	External record ID for partner systems
provider_message_id	string | null	No	—	Email provider message ID
direction	enum | null	No	—	Call direction. One of inbound or outbound.
instruction_config_id	string | null	No	—	Override instruction configuration ID
partner_user_id	string	No	—	External partner user identifier
model_id	string	No	—	AI model ID for this conversation
user_id	number	No	—	Internal platform user ID
customer_id	string | null	No	—	Customer or contact ID from CRM
status	enum | null	No	—	Current operational status. One of ACTIVE, COMPLETED, FAILED, ABANDONED, or TRANSFERRED.
is_campaign	boolean	No	false	Whether part of a marketing campaign
durationInSeconds	number	No	15	Duration in seconds
stt_model_id	string | null	No	—	Speech-to-Text model ID
tts_model_id	string | null	No	—	Text-to-Speech model ID
resource_url	string | null	No	—	Call recording URL
messages	array | null	No	—	Array of conversation messages
conversationSummary	ConversationSummary | null	No	—	AI-generated conversation summary
state_history	array | null	No	—	Audit trail of status changes
call_transfer	CallTransfer | null	No	—	Call transfer details
created_day	string	No	—	Creation day in YYYY-MM-DD format
created_at	number	No	Date.now	Unix timestamp when created
updated_at	number | null	No	—	Unix timestamp when last updated
deleted_at	number | null	No	—	Unix timestamp when soft-deleted

---

ConversationSummary

AI-generated summary capturing the essence of a conversation including key discussion points, follow-up actions, and sentiment analysis.

Schema: ConversationSummarySchema

Attributes

Attribute	Type	Required	Description
summary	string	Yes	Concise 1-3 sentence overview of the conversation
key_points	array<string>	Yes	Important discussion topics and decisions
action_items	array<string>	Yes	Follow-up tasks and commitments
sentiment	enum	Yes	Overall emotional tone. One of POSITIVE, NEGATIVE, NEUTRAL, or MIXED.

---

Message

Lightweight message representation used within conversation configurations.

Schema: MessageSchema

Attributes

Attribute	Type	Required	Default	Description
messageId	string	Yes	—	Unique identifier for this message
content	string	Yes	—	Text content of the message
message_type	enum	Yes	—	Type of sender. One of user or assistant.
timestamp	Date	Yes	—	When the message was sent
metadata	object	Yes	—	Additional message-specific metadata
id	string	No	—	Internal database ID
created_at	number	No	—	Unix timestamp when created

---

ConversationStateHistory

Audit trail recording each status transition throughout a conversation's lifecycle.

Schema: ConversationStateHistorySchema

Attributes

Attribute	Type	Required	Description
status	enum	Yes	Status at this point in the lifecycle. One of ACTIVE, COMPLETED, FAILED, ABANDONED, or TRANSFERRED.
timestamp	number	Yes	Unix timestamp when status was set
reason	string	No	Explanation for the status change
metadata	object	No	Additional context about the state change

---

CallTransfer

Captures metadata about call transfers to human agents including transfer type, timing, destination, and outcome.

Schema: CallTransferSchema

Attributes

Attribute	Type	Required	Description
transfer_target	string	Yes	Target phone number in E.164 format
transfer_status	enum	Yes	Current status. One of pending, completed, failed, or returned.
transfer_type	enum | null	No	Transfer type. One of blind or warm.
transfer_initiated_at	number	No	Unix timestamp when transfer was initiated
transfer_completed_at	number	No	Unix timestamp when transfer completed
transfer_reason	string	No	Reason for the transfer

---

DecommissionConfig

Request payload for decommissioning and shutting down active conversation services.

Schema: DecommissionConfigSchema

Attributes

Attribute	Type	Required	Description
decommission_service_id	string	Yes	Service ID of the conversation to decommission

---

Example

Service Conversation Config

{
  "id": "conv_abc123",
  "organization_id": "org_xyz",
  "project_id": "proj_123",
  "channel_id": "chan_456",
  "deployment_config_id": "deploy_789",
  "channel_identifier": "+12125551234",
  "conversation_type": "TELEPHONY_CALL",
  "direction": "inbound",
  "status": "COMPLETED",
  "is_campaign": false,
  "durationInSeconds": 245,
  "stt_model_id": "whisper-v3",
  "tts_model_id": "eleven-labs-v2",
  "resource_url": "https://storage.example.com/recordings/conv_abc123.mp3",
  "conversationSummary": {
    "summary": "Customer inquired about product pricing and placed an order.",
    "key_points": ["Discussed enterprise pricing", "Confirmed 50-user license"],
    "action_items": ["Send invoice by Friday", "Schedule onboarding call"],
    "sentiment": "POSITIVE"
  },
  "state_history": [
    { "status": "ACTIVE", "timestamp": 1709856000000 },
    { "status": "COMPLETED", "timestamp": 1709856245000, "reason": "Issue resolved" }
  ],
  "created_at": 1709856000000,
  "updated_at": 1709856245000
}

Call Transfer

{
  "transfer_type": "warm",
  "transfer_target": "+12125559876",
  "transfer_initiated_at": 1709856120000,
  "transfer_completed_at": 1709856135000,
  "transfer_status": "completed",
  "transfer_reason": "Customer requested billing department"
}

---

Related

• Conversation Message - Message schemas for chat and email
• Deployment Configuration - Deployment configurations that power conversations
• Interaction Channels - Channel configurations for conversations