{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://raw.githubusercontent.com/api-evangelist/cm-com/main/json-schema/cm-com-conversation-schema.json", "title": "Conversation", "description": "Complete conversation with analytics", "x-generated": "2026-10-13", "x-method": "derived", "x-generator": "derive-json-schema.py", "x-source": "openapi/cm-com-halo-analytics-v1-openapi.yml#/components/schemas/Conversation", "type": "object", "required": [ "started", "ended", "total_user_items", "num_matched_user_items", "recognition_rate", "messages" ], "properties": { "ended": { "type": "string", "format": "date-time" }, "feedback": { "$ref": "#/$defs/ConversationFeedback" }, "feedback_comment": { "type": [ "string", "null" ] }, "manual_resolution": { "oneOf": [ { "type": "null" }, { "$ref": "#/$defs/ManualResolution" } ] }, "messages": { "type": "array", "items": { "$ref": "#/$defs/Message" } }, "most_common_channel": { "type": [ "string", "null" ] }, "most_common_language": { "type": [ "string", "null" ] }, "most_common_origin": { "type": [ "string", "null" ] }, "most_common_product": { "type": [ "string", "null" ] }, "num_matched_user_items": { "type": "integer", "format": "int32" }, "profile_id": { "type": [ "integer", "null" ], "format": "int32" }, "profile_name": { "type": [ "string", "null" ] }, "recognition_rate": { "type": "number", "format": "double" }, "resolution": { "$ref": "#/$defs/ConversationResolution" }, "resolution_reasoning": { "type": [ "string", "null" ] }, "started": { "type": "string", "format": "date-time" }, "subtopic": { "oneOf": [ { "type": "null" }, { "$ref": "#/$defs/Subtopic" } ] }, "summary": { "type": [ "string", "null" ] }, "topic": { "oneOf": [ { "type": "null" }, { "$ref": "#/$defs/Topic" } ] }, "total_user_items": { "type": "integer", "format": "int32" }, "version": { "type": "integer", "format": "int32" }, "visited_agent_ids": { "type": "array", "items": { "type": [ "integer", "null" ], "format": "int64" } }, "visited_agents": { "type": "array", "items": { "$ref": "#/$defs/VisitedAgent" } }, "visited_tool_ids": { "type": "array", "items": { "type": [ "integer", "null" ], "format": "int64" } }, "visited_tools": { "type": "array", "items": { "$ref": "#/$defs/VisitedTool" } } }, "$defs": { "Actor": { "oneOf": [ { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "msc_user" ] } } }, { "type": "object", "required": [ "type" ], "properties": { "name": { "type": [ "string", "null" ] }, "type": { "type": "string", "enum": [ "msc_agent" ] } } }, { "type": "object", "required": [ "id", "name", "type" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "teams" ] } } } ], "description": "Identifies the specific participant who authored a `User` or `Assistant`\nconversation item, for conversations with more than one distinct actor\non that role (e.g. MSC's end-user/agent distinction, or a Teams channel\nthread). Absent when the item's role alone identifies the author.\n\nSerializes as a tagged object (`{\"type\": \"msc_user\"}`, `{\"type\": \"teams\", ...}`,\netc). Deserialization additionally accepts the bare strings `\"End_User\"` /\n`\"Customer_Service_Agent\"` for `MscUser` / `MscAgent { name: None }` — MSC's\nlegacy `/instruction` and `/suggestion` endpoints have sent exactly those two\nstring values on the wire for years, so reading that shape can't be dropped.\nNothing produces it anymore; it's accepted, not emitted." }, "AgentHandoverDetails": { "type": "object", "description": "Agent handover details", "required": [ "stop_status" ], "properties": { "from_agent_name": { "type": [ "string", "null" ] }, "from_agent_version_id": { "type": [ "integer", "null" ], "format": "int32" }, "reasoning": { "type": [ "string", "null" ] }, "stop_status": { "$ref": "#/$defs/AgentInteractionState" }, "to_agent_name": { "type": [ "string", "null" ] }, "to_agent_version_id": { "type": [ "integer", "null" ], "format": "int32" } } }, "AgentInteractionState": { "type": "string", "description": "Agent interaction state", "enum": [ "active", "completed", "breakout", "handover" ] }, "AgentResult": { "type": "object", "description": "Agent execution result", "properties": { "agent_id": { "type": [ "integer", "null" ], "format": "int64" }, "agent_name": { "type": [ "string", "null" ] }, "agent_version_id": { "type": [ "integer", "null" ], "format": "int64" }, "handover_reasoning": { "type": [ "string", "null" ] }, "tool_results": { "type": "array", "items": { "$ref": "#/$defs/ToolResult" } }, "tool_uses": { "type": "array", "items": { "$ref": "#/$defs/ToolUse" } } } }, "AgenticParkPayload": { "type": "object", "description": "Park payload for agentic activity", "properties": { "agent_response": { "type": [ "string", "null" ], "description": "Agent's response to show the user" }, "conversation_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Conversation ID for continuing multi-turn conversations" }, "dialog_options": { "type": [ "array", "null" ], "items": { "$ref": "#/$defs/ConversationOption" }, "description": "Selectable buttons to show alongside the response" }, "image_carousel": { "oneOf": [ { "type": "null" }, { "$ref": "#/$defs/CarouselResponse", "description": "Image carousel to show alongside the response" } ] } } }, "AgenticUnparkPayload": { "type": "object", "description": "Unpark payload for agentic activity - user continues conversation via orchestrator", "required": [ "query" ], "properties": { "query": { "$ref": "#/$defs/UserResponse", "description": "User's query to continue the conversation" } } }, "AiCloudItemMeta": { "type": "object", "description": "AI Cloud-specific metadata for a conversation message", "required": [ "customer_key", "project_key", "culture" ], "properties": { "article_ids": { "type": [ "array", "null" ], "items": { "type": "string" } }, "context_variables": {}, "conversation_variables": {}, "culture": { "type": "string" }, "customer_key": { "type": "string" }, "entity_matches": {}, "intent_info": {}, "is_fallback": { "type": [ "boolean", "null" ] }, "main_interaction_type": { "oneOf": [ { "type": "null" }, { "$ref": "#/$defs/MainInteractionType" } ] }, "pages": { "oneOf": [ { "type": "null" }, { "$ref": "#/$defs/Pages" } ] }, "project_key": { "type": "string" }, "recognition_quality": { "type": [ "number", "null" ], "format": "double" }, "recognition_type": { "oneOf": [ { "type": "null" }, { "$ref": "#/$defs/RecognitionType" } ] }, "stop_words": {}, "translation": { "oneOf": [ { "type": "null" }, { "$ref": "#/$defs/TranslationDetails" } ] } } }, "AiCloudMessage": { "allOf": [ { "type": "object", "description": "Base fields shared by all message types", "properties": { "actor": { "oneOf": [ { "type": "null" }, { "$ref": "#/$defs/Actor", "description": "The participant who authored this item, when the role alone is ambiguous." } ] }, "content": { "type": [ "array", "null" ], "items": { "$ref": "#/$defs/MessageContentPart" } }, "interaction_id": { "type": [ "string", "null" ], "format": "uuid" }, "is_message_before_halo": { "type": "boolean" }, "timestamp": { "type": [ "string", "null" ], "format": "date-time", "description": "Time at which the conversation item was first produced. Legacy items\nwithout valid initialization metadata fall back to their logging time." } } }, { "type": "object", "properties": { "aicloud_meta": { "oneOf": [ { "type": "null" }, { "$ref": "#/$defs/AiCloudItemMeta" } ] }, "tool_results": { "type": "array", "items": { "$ref": "#/$defs/ToolResult" } }, "tool_uses": { "type": "array", "items": { "$ref": "#/$defs/ToolUse" } } } } ], "description": "AI Cloud message" }, "AssistantMessage": { "allOf": [ { "type": "object", "description": "Base fields shared by all message types", "properties": { "actor": { "oneOf": [ { "type": "null" }, { "$ref": "#/$defs/Actor", "description": "The participant who authored this item, when the role alone is ambiguous." } ] }, "content": { "type": [ "array", "null" ], "items": { "$ref": "#/$defs/MessageContentPart" } }, "interaction_id": { "type": [ "string", "null" ], "format": "uuid" }, "is_message_before_halo": { "type": "boolean" }, "timestamp": { "type": [ "string", "null" ], "format": "date-time", "description": "Time at which the conversation item was first produced. Legacy items\nwithout valid initialization metadata fall back to their logging time." } } }, { "type": "object", "properties": { "aicloud_meta": { "oneOf": [ { "type": "null" }, { "$ref": "#/$defs/AiCloudItemMeta" } ] }, "source": { "type": [ "string", "null" ] } } } ], "description": "Generic assistant message" }, "CarouselItem": { "type": "object", "required": [ "image_src", "image_alt" ], "properties": { "buttons": { "type": [ "array", "null" ], "items": { "$ref": "#/$defs/CarouselItemButton" } }, "description": { "type": [ "string", "null" ] }, "image_alt": { "type": "string" }, "image_src": { "type": "string" }, "title": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] } } }, "CarouselItemButton": { "type": "object", "required": [ "text", "value" ], "properties": { "text": { "type": "string" }, "value": { "type": "string" } } }, "CarouselResponse": { "type": "object", "properties": { "carousel": { "type": [ "array", "null" ], "items": { "$ref": "#/$defs/CarouselItem" } } } }, "ContentPart": { "oneOf": [ { "type": "object", "required": [ "text", "type" ], "properties": { "text": { "type": "string" }, "type": { "type": "string", "enum": [ "text" ] } } }, { "type": "object", "required": [ "text", "type" ], "properties": { "redacted": { "type": "boolean" }, "signature": { "type": [ "string", "null" ] }, "text": { "type": "string" }, "type": { "type": "string", "enum": [ "thinking" ] } } }, { "type": "object", "required": [ "json_value", "type" ], "properties": { "json_value": { "$ref": "#/$defs/Value" }, "type": { "type": "string", "enum": [ "json" ] } } }, { "allOf": [ { "$ref": "#/$defs/MediaContentPart" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "media" ] } } } ] }, { "type": "object", "description": "OpenAI Responses API `phase: \"commentary\"` text: an intermediate\npreamble emitted before a tool call, distinct from the turn's final\nanswer. Plain assistant-authored text, not hidden reasoning like\n`Thinking`.", "required": [ "text", "type" ], "properties": { "text": { "type": "string" }, "type": { "type": "string", "enum": [ "commentary" ] } } } ] }, "ContextValue": { "oneOf": [ { "type": "object", "required": [ "Plain" ], "properties": { "Plain": { "type": "string" } } }, { "type": "object", "description": "A sensitive string (masked in debug output).\n\n- `is_external: true` — the value came from an external source (e.g. user/API input)\n No decryption is needed.\n- `is_external: false` — the value is internally managed (e.g. a database default)\n and is stored encrypted. It must be decrypted before use.", "required": [ "Secret" ], "properties": { "Secret": { "type": "object", "description": "A sensitive string (masked in debug output).\n\n- `is_external: true` — the value came from an external source (e.g. user/API input)\n No decryption is needed.\n- `is_external: false` — the value is internally managed (e.g. a database default)\n and is stored encrypted. It must be decrypted before use.", "required": [ "value", "is_external" ], "properties": { "is_external": { "type": "boolean" }, "value": { "type": "string" } } } } } ], "description": "Value of context\n- Plain: A non-sensitive string (media and structured data stored as JSON strings)\n- Secret: A sensitive string (not printed in debug)" }, "Contexts": { "type": "object", "description": "Type alias for a mapping from strings to context values", "additionalProperties": { "$ref": "#/$defs/ContextValue" }, "propertyNames": { "type": "string" } }, "ConversationFeedback": { "type": "string", "description": "Enum for conversation feedback rating in API responses", "enum": [ "FEEDBACK_VERY_SATISFIED", "FEEDBACK_SATISFIED", "FEEDBACK_NEUTRAL", "FEEDBACK_UNSATISFIED", "FEEDBACK_VERY_UNSATISFIED", "FEEDBACK_NOT_GIVEN" ] }, "ConversationOption": { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string" } } }, "ConversationOptionsContentPart": { "type": "object", "description": "Conversation options (buttons) content part", "required": [ "conversation_options" ], "properties": { "conversation_options": { "type": "array", "items": { "$ref": "#/$defs/ConversationOption" } } } }, "ConversationResolution": { "type": "string", "description": "Enum for conversation resolution status in API responses", "enum": [ "RESOLUTION_SUCCESSFUL", "RESOLUTION_HANDOVER", "RESOLUTION_UNSUCCESSFUL", "RESOLUTION_UNDETERMINED", "RESOLUTION_PENDING" ] }, "CustomGuardrailResult": { "type": "object", "required": [ "input", "prompt", "result" ], "properties": { "input": { "type": "string" }, "prompt": { "type": "string" }, "request_type": { "type": "string" }, "result": { "$ref": "#/$defs/CustomGuardrailResultType" }, "rewritten_input": { "type": [ "string", "null" ] }, "usage": { "oneOf": [ { "type": "null" }, { "$ref": "#/$defs/UsageDetails" } ] } } }, "CustomGuardrailResultType": { "type": "string", "description": "Custom guardrail result type", "enum": [ "continue", "stop", "rewrite" ] }, "CustomerServiceAgentInstructionMessage": { "allOf": [ { "type": "object", "description": "Base fields shared by all message types", "properties": { "actor": { "oneOf": [ { "type": "null" }, { "$ref": "#/$defs/Actor", "description": "The participant who authored this item, when the role alone is ambiguous." } ] }, "content": { "type": [ "array", "null" ], "items": { "$ref": "#/$defs/MessageContentPart" } }, "interaction_id": { "type": [ "string", "null" ], "format": "uuid" }, "is_message_before_halo": { "type": "boolean" }, "timestamp": { "type": [ "string", "null" ], "format": "date-time", "description": "Time at which the conversation item was first produced. Legacy items\nwithout valid initialization metadata fall back to their logging time." } } }, { "type": "object", "required": [ "is_classified_as_instruction" ], "properties": { "custom_guardrail_results": { "type": [ "array", "null" ], "items": { "$ref": "#/$defs/CustomGuardrailResult" } }, "is_classified_as_instruction": { "type": "boolean" }, "is_recognized": { "type": [ "boolean", "null" ] } } } ], "description": "Customer service agent instruction message" }, "CustomerServiceAgentMessage": { "allOf": [ { "type": "object", "description": "Base fields shared by all message types", "properties": { "actor": { "oneOf": [ { "type": "null" }, { "$ref": "#/$defs/Actor", "description": "The participant who authored this item, when the role alone is ambiguous." } ] }, "content": { "type": [ "array", "null" ], "items": { "$ref": "#/$defs/MessageContentPart" } }, "interaction_id": { "type": [ "string", "null" ], "format": "uuid" }, "is_message_before_halo": { "type": "boolean" }, "timestamp": { "type": [ "string", "null" ], "format": "date-time", "description": "Time at which the conversation item was first produced. Legacy items\nwithout valid initialization metadata fall back to their logging time." } } } ], "description": "Customer service agent message" }, "DematerializedMediaContentPart": { "type": "object", "required": [ "mime_type", "data_uri", "data_hash" ], "properties": { "data_hash": { "type": "string" }, "data_uri": { "$ref": "#/$defs/MediaDataUri" }, "metadata": { "$ref": "#/$defs/Value" }, "mime_type": { "type": "string" }, "name": { "type": [ "string", "null" ] } } }, "ErrorResponse": { "type": "object", "required": [ "type", "title" ], "properties": { "detail": { "type": [ "object", "null" ] }, "instance": { "type": [ "string", "null" ] }, "title": { "type": "string" }, "type": { "type": "string" } } }, "ExternalHandoverMessage": { "allOf": [ { "type": "object", "description": "Base fields shared by all message types", "properties": { "actor": { "oneOf": [ { "type": "null" }, { "$ref": "#/$defs/Actor", "description": "The participant who authored this item, when the role alone is ambiguous." } ] }, "content": { "type": [ "array", "null" ], "items": { "$ref": "#/$defs/MessageContentPart" } }, "interaction_id": { "type": [ "string", "null" ], "format": "uuid" }, "is_message_before_halo": { "type": "boolean" }, "timestamp": { "type": [ "string", "null" ], "format": "date-time", "description": "Time at which the conversation item was first produced. Legacy items\nwithout valid initialization metadata fall back to their logging time." } } }, { "type": "object", "properties": { "handover_details": { "oneOf": [ { "type": "null" }, { "$ref": "#/$defs/HandoverDetails" } ] } } } ], "description": "External handover message" }, "Feedback": { "type": "object", "required": [ "feedback_id", "profile_id", "account_id", "conversation_id", "interaction_id", "original_answer", "feedback", "distance", "feedback_reason" ], "properties": { "account_id": { "type": "string", "format": "uuid" }, "conversation_id": { "type": "string", "format": "uuid" }, "distance": { "type": "number", "format": "double" }, "feedback": { "type": "string" }, "feedback_id": { "$ref": "#/$defs/i64" }, "feedback_reason": { "$ref": "#/$defs/FeedbackReason" }, "interaction_id": { "type": "string", "format": "uuid" }, "original_answer": { "type": "string" }, "profile_id": { "$ref": "#/$defs/i64" } } }, "FeedbackReason": { "type": "string", "enum": [ "wrongly-formulated", "incorrect", "do-not-answer" ] }, "FunctionUseArgument": { "type": "object", "required": [ "parameter", "value" ], "properties": { "parameter": { "type": "string" }, "value": { "$ref": "#/$defs/Value" } } }, "HaloMessage": { "allOf": [ { "type": "object", "description": "Base fields shared by all message types", "properties": { "actor": { "oneOf": [ { "type": "null" }, { "$ref": "#/$defs/Actor", "description": "The participant who authored this item, when the role alone is ambiguous." } ] }, "content": { "type": [ "array", "null" ], "items": { "$ref": "#/$defs/MessageContentPart" } }, "interaction_id": { "type": [ "string", "null" ], "format": "uuid" }, "is_message_before_halo": { "type": "boolean" }, "timestamp": { "type": [ "string", "null" ], "format": "date-time", "description": "Time at which the conversation item was first produced. Legacy items\nwithout valid initialization metadata fall back to their logging time." } } }, { "type": "object", "required": [ "can_get_feedback", "answering_user_interaction", "used_language_detection", "is_welcome_tool_trigger", "is_fallback_tool_trigger", "is_breakout" ], "properties": { "agent_results": { "type": [ "array", "null" ], "items": { "$ref": "#/$defs/AgentResult" } }, "answer_after_answer_style": { "type": [ "string", "null" ] }, "answer_after_feedback": { "type": [ "string", "null" ] }, "answer_before_answer_style": { "type": [ "string", "null" ] }, "answer_before_feedback": { "type": [ "string", "null" ] }, "answering_user_interaction": { "type": "boolean" }, "can_get_feedback": { "type": "boolean" }, "contexts": { "oneOf": [ { "type": "null" }, { "$ref": "#/$defs/Contexts" } ] }, "detected_language": { "type": [ "string", "null" ] }, "feedback_reasoning": { "type": [ "string", "null" ] }, "input_language": { "type": [ "string", "null" ] }, "interaction_type": { "oneOf": [ { "type": "null" }, { "$ref": "#/$defs/ToolInteractionType" } ] }, "is_breakout": { "type": "boolean" }, "is_fallback_tool_trigger": { "type": "boolean" }, "is_welcome_tool_trigger": { "type": "boolean" }, "match": { "type": [ "boolean", "null" ] }, "reasoning": { "type": [ "string", "null" ] }, "tool_use_id": { "type": [ "string", "null" ] }, "used_feedback": { "type": [ "array", "null" ], "items": { "$ref": "#/$defs/Feedback" } }, "used_feedback_str": { "type": [ "string", "null" ] }, "used_language_detection": { "type": "boolean" }, "used_sources": { "type": [ "array", "null" ], "items": { "$ref": "#/$defs/Knowledge" } } } } ], "description": "HALO (AI assistant) message" }, "HandoverDetails": { "oneOf": [ { "allOf": [ { "$ref": "#/$defs/AgentHandoverDetails" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "agent" ] } } } ] }, { "allOf": [ { "$ref": "#/$defs/TextRouterHandoverDetails" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "text_router_v2" ] } } } ] }, { "allOf": [ { "$ref": "#/$defs/TextMscHandoverDetails" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "text_msc" ] } } } ] }, { "allOf": [ { "$ref": "#/$defs/TextMarketplaceHandoverDetails" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "text_marketplace" ] } } } ] }, { "allOf": [ { "$ref": "#/$defs/TextLoggingHandoverDetails" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "text_logging" ] } } } ] }, { "allOf": [ { "$ref": "#/$defs/VoiceMscHandoverDetails" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "voice_msc" ] } } } ] }, { "allOf": [ { "$ref": "#/$defs/VoiceForwardHandoverDetails" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "voice_forward" ] } } } ] }, { "allOf": [ { "$ref": "#/$defs/VoiceTransferHandoverDetails" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "voice_transfer" ] } } } ] }, { "allOf": [ { "$ref": "#/$defs/VoiceCustomHandoverDetails" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "voice_custom" ] } } } ] }, { "allOf": [ { "$ref": "#/$defs/VoiceLoggingHandoverDetails" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "voice_logging" ] } } } ] } ], "description": "Handover details variants" }, "ImageCarouselMessageContentPart": { "type": "object", "description": "Image carousel content part", "required": [ "image_carousel" ], "properties": { "image_carousel": { "$ref": "#/$defs/CarouselResponse" } } }, "JsonMessageContentPart": { "type": "object", "description": "JSON message content part", "required": [ "json" ], "properties": { "json": { "$ref": "#/$defs/Value" } } }, "Knowledge": { "type": "object", "required": [ "id", "source_id", "chunk_id", "content", "metadata", "distance" ], "properties": { "chunk_id": { "type": "string" }, "content": { "type": "string" }, "distance": { "type": "number", "format": "double" }, "id": { "$ref": "#/$defs/i64" }, "metadata": { "type": "object", "additionalProperties": {}, "propertyNames": { "type": "string" } }, "source": { "type": "string" }, "source_id": { "$ref": "#/$defs/i64" }, "source_reference": { "type": "string" } } }, "MainInteractionType": { "type": "string", "enum": [ "QA", "Dialog", "Event", "TransactionalDialog", "DataRetrieval", "FaqClick", "Feedback", "FaqSearch", "LinkClick", "GenerativeAI" ] }, "ManualResolution": { "type": "object", "description": "Manual resolution override for a conversation", "required": [ "id", "conversation_id", "new_label", "is_active", "created", "user_email" ], "properties": { "conversation_id": { "type": "string", "format": "uuid" }, "created": { "type": "string", "format": "date-time" }, "id": { "type": "integer", "format": "int32" }, "is_active": { "type": "boolean" }, "new_label": { "$ref": "#/$defs/ConversationResolution" }, "original_label": { "oneOf": [ { "type": "null" }, { "$ref": "#/$defs/ConversationResolution" } ] }, "profile_id": { "type": [ "integer", "null" ], "format": "int32" }, "reasoning": { "type": [ "string", "null" ] }, "user_email": { "type": "string" }, "user_name": { "type": [ "string", "null" ] } } }, "MaterializedMediaContentPart": { "type": "object", "required": [ "mime_type", "data", "data_uri", "data_hash", "metadata" ], "properties": { "data": { "type": "string" }, "data_hash": { "type": "string" }, "data_uri": { "$ref": "#/$defs/MediaDataUri" }, "metadata": { "$ref": "#/$defs/Value" }, "mime_type": { "type": "string" }, "name": { "type": [ "string", "null" ] } } }, "MediaContentPart": { "oneOf": [ { "type": "object", "description": "A new media content part which is not yet uploaded into HALO", "required": [ "Transient" ], "properties": { "Transient": { "$ref": "#/$defs/TransientMediaContentPart", "description": "A new media content part which is not yet uploaded into HALO" } } }, { "type": "object", "description": "A media content part with data, and can be dematerialized", "required": [ "Materialized" ], "properties": { "Materialized": { "$ref": "#/$defs/MaterializedMediaContentPart", "description": "A media content part with data, and can be dematerialized" } } }, { "type": "object", "description": "A media content part without data, but it can be downloaded", "required": [ "Dematerialized" ], "properties": { "Dematerialized": { "$ref": "#/$defs/DematerializedMediaContentPart", "description": "A media content part without data, but it can be downloaded" } } } ] }, "MediaDataUri": { "type": "string" }, "MediaMessageContentPart": { "type": "object", "description": "Media message content part", "required": [ "mime_type" ], "properties": { "data_uri": { "type": [ "string", "null" ] }, "mime_type": { "type": "string" }, "name": { "type": [ "string", "null" ] } } }, "Message": { "oneOf": [ { "allOf": [ { "$ref": "#/$defs/UserMessage" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "USER" ] } } } ] }, { "allOf": [ { "$ref": "#/$defs/HaloMessage" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "HALO" ] } } } ] }, { "allOf": [ { "$ref": "#/$defs/AssistantMessage" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "ASSISTANT" ] } } } ] }, { "allOf": [ { "$ref": "#/$defs/AiCloudMessage" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "AICLOUD" ] } } } ] }, { "allOf": [ { "$ref": "#/$defs/CustomerServiceAgentMessage" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "CUSTOMER_SERVICE_AGENT" ] } } } ] }, { "allOf": [ { "$ref": "#/$defs/CustomerServiceAgentInstructionMessage" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "CUSTOMER_SERVICE_AGENT_INSTRUCTION" ] } } } ] }, { "allOf": [ { "$ref": "#/$defs/ExternalHandoverMessage" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "EXTERNAL_HANDOVER" ] } } } ] } ], "description": "Message - discriminated union of all message types" }, "MessageContentPart": { "oneOf": [ { "allOf": [ { "$ref": "#/$defs/TextMessageContentPart" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "text" ] } } } ] }, { "allOf": [ { "$ref": "#/$defs/JsonMessageContentPart" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "json" ] } } } ] }, { "allOf": [ { "$ref": "#/$defs/MediaMessageContentPart" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "media" ] } } } ] }, { "allOf": [ { "$ref": "#/$defs/ConversationOptionsContentPart" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "buttons" ] } } } ] }, { "allOf": [ { "$ref": "#/$defs/ImageCarouselMessageContentPart" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "image_carousel" ] } } } ] }, { "allOf": [ { "$ref": "#/$defs/ShowFeedbackMessageContentPart" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "show_feedback" ] } } } ] } ], "description": "Message content part - discriminated union" }, "Pages": { "type": "object", "description": "Page context for the conversation item.", "properties": { "originatingPage": { "type": [ "string", "null" ] }, "previousPage": { "type": [ "string", "null" ] } } }, "ParkPayload": { "oneOf": [ { "allOf": [ { "$ref": "#/$defs/TimerParkPayload" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "timer" ] } } } ] }, { "allOf": [ { "$ref": "#/$defs/UserInteractionParkPayload" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "user_interaction" ] } } } ] }, { "allOf": [ { "$ref": "#/$defs/AgenticParkPayload" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "agentic" ] } } } ] }, { "allOf": [ { "$ref": "#/$defs/ToolCallParkPayload" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "tool" ] } } } ] } ], "description": "Enum type for parking" }, "ParkToken": { "type": "string" }, "Provider": { "type": "string", "enum": [ "anthropic", "openai", "gemini" ] }, "RecognitionType": { "type": "string", "enum": [ "Exception Event", "GenerativeAI", "Intent", "Entity Recognition", "No Recognition" ] }, "ShowFeedbackMessageContentPart": { "type": "object", "description": "Show feedback content part", "properties": { "text": { "type": "string" } } }, "Subtopic": { "type": "object", "description": "Subtopic (child topic in taxonomy)", "required": [ "id", "name", "definition" ], "properties": { "definition": { "type": "string" }, "id": { "type": "integer", "format": "int32" }, "name": { "type": "string" } } }, "TextLoggingHandoverDetails": { "type": "object", "description": "Text logging handover details" }, "TextMarketplaceHandoverDetails": { "type": "object", "description": "Text Marketplace handover details", "required": [ "adapter_id", "messaging_adapter_id" ], "properties": { "adapter_id": { "type": "string" }, "context": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "messaging_adapter_id": { "type": "string" }, "routing": { "type": [ "string", "null" ] } } }, "TextMessageContentPart": { "type": "object", "description": "Text message content part", "required": [ "text" ], "properties": { "text": { "type": "string" } } }, "TextMscHandoverDetails": { "type": "object", "description": "Text MSC handover details", "required": [ "adapter_id", "messaging_adapter_id", "name", "email" ], "properties": { "adapter_id": { "type": "string" }, "email": { "type": "string" }, "messaging_adapter_id": { "type": "string" }, "msc_profile": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "name": { "type": "string" }, "phone_number": { "type": [ "string", "null" ] }, "routing_keywords": { "type": [ "array", "null" ], "items": { "type": "string" } }, "web_store_referrer": { "type": [ "string", "null" ] } } }, "TextRouterHandoverDetails": { "type": "object", "description": "Text Router V2 handover details", "required": [ "target_state_name_id", "context" ], "properties": { "context": { "type": "object", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "target_state_name_id": { "type": "string", "format": "uuid" } } }, "TimerParkPayload": { "type": "object", "description": "Park payload for waiting", "required": [ "approximate_resumes_at" ], "properties": { "approximate_resumes_at": { "type": "string", "format": "date-time" } } }, "TimerUnparkPayload": { "type": "object", "description": "Unpark payload for timer (empty - no data needed when timer fires)" }, "ToolCallParkPayload": { "type": "object", "description": "Park payload for tool", "required": [ "nested_park_token", "nested_park_payload" ], "properties": { "nested_park_payload": { "$ref": "#/$defs/ParkPayload" }, "nested_park_token": { "$ref": "#/$defs/ParkToken" } } }, "ToolCallUnparkPayload": { "type": "object", "description": "Unpark payload for tool", "required": [ "nested_unpark_token", "nested_unpark_payload" ], "properties": { "nested_unpark_payload": { "$ref": "#/$defs/UnparkPayload" }, "nested_unpark_token": { "type": "string" } } }, "ToolInteractionType": { "type": "string", "enum": [ "user", "agentic" ] }, "ToolResult": { "type": "object", "description": "Tool execution result", "required": [ "tool_name", "tool_use_id", "started", "finished" ], "properties": { "execution_id": { "type": [ "string", "null" ] }, "finished": { "type": "string", "format": "date-time" }, "output": { "type": [ "array", "null" ], "items": { "$ref": "#/$defs/MessageContentPart" } }, "started": { "type": "string", "format": "date-time" }, "state": { "oneOf": [ { "type": "null" }, { "$ref": "#/$defs/ToolState" } ] }, "tool_id": { "type": [ "integer", "null" ], "format": "int64" }, "tool_name": { "type": "string" }, "tool_use_id": { "type": "string" }, "tool_version_id": { "type": [ "integer", "null" ], "format": "int64" }, "trace": { "type": [ "array", "null" ], "items": { "$ref": "#/$defs/Trace" } } } }, "ToolState": { "type": "string", "description": "Unified tool state that covers both Flow and MCP tool states", "enum": [ "running", "parked", "completed", "terminated" ] }, "ToolUse": { "oneOf": [ { "type": "object", "required": [ "id", "name", "arguments", "type" ], "properties": { "arguments": { "type": "array", "items": { "$ref": "#/$defs/FunctionUseArgument" } }, "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "function" ] } } }, { "type": "object", "required": [ "id", "name", "arguments", "tool_id", "type" ], "properties": { "arguments": { "type": "array", "items": { "$ref": "#/$defs/FunctionUseArgument" } }, "id": { "type": "string" }, "name": { "type": "string" }, "tool_id": { "$ref": "#/$defs/i32" }, "type": { "type": "string", "enum": [ "flow_tool" ] } } }, { "type": "object", "required": [ "id", "name", "arguments", "mcp_server_id", "type" ], "properties": { "arguments": { "type": "array", "items": { "$ref": "#/$defs/FunctionUseArgument" } }, "id": { "type": "string" }, "mcp_server_id": { "$ref": "#/$defs/i32" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "mcp_tool" ] } } }, { "type": "object", "required": [ "id", "name", "arguments", "type" ], "properties": { "arguments": { "type": "array", "items": { "$ref": "#/$defs/FunctionUseArgument" } }, "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "routing" ] } } }, { "type": "object", "required": [ "id", "name", "input", "type" ], "properties": { "id": { "type": "string" }, "input": { "$ref": "#/$defs/Value" }, "name": { "type": "string" }, "provider": { "oneOf": [ { "type": "null" }, { "$ref": "#/$defs/Provider" } ] }, "type": { "type": "string", "enum": [ "server_tool" ] } } } ] }, "ToolUseTraceOutput": { "oneOf": [ { "$ref": "#/$defs/Value" }, { "type": "object", "properties": { "payload": { "oneOf": [ { "type": "null" }, { "$ref": "#/$defs/ParkPayload" } ] } } }, { "$ref": "#/$defs/ErrorResponse" } ], "description": "Possible output types for a tool use trace step" }, "ToolUseTraceState": { "type": "string", "description": "State of a tool use trace step", "enum": [ "parked", "unparked", "completed", "terminated" ] }, "Topic": { "type": "object", "description": "Topic (parent topic in taxonomy)", "required": [ "id", "name", "definition" ], "properties": { "definition": { "type": "string" }, "id": { "type": "integer", "format": "int32" }, "name": { "type": "string" } } }, "Trace": { "type": "object", "description": "Trace for tool execution", "required": [ "id", "state", "started" ], "properties": { "attributes": { "type": [ "object", "null" ], "additionalProperties": { "$ref": "#/$defs/Value" }, "propertyNames": { "type": "string" } }, "finished": { "type": [ "string", "null" ], "format": "date-time" }, "id": { "type": "integer", "format": "int64" }, "node_type": { "type": [ "string", "null" ] }, "output": { "oneOf": [ { "type": "null" }, { "$ref": "#/$defs/ToolUseTraceOutput" } ] }, "started": { "type": "string", "format": "date-time" }, "state": { "$ref": "#/$defs/ToolUseTraceState" }, "trace": { "type": [ "array", "null" ], "items": { "$ref": "#/$defs/Trace" } }, "unpark_payload": { "oneOf": [ { "type": "null" }, { "$ref": "#/$defs/UnparkPayload" } ] }, "variables": { "type": [ "object", "null" ], "additionalProperties": { "$ref": "#/$defs/Value" }, "propertyNames": { "type": "string" } } } }, "TransientMediaContentPart": { "type": "object", "required": [ "mime_type", "data", "data_hash" ], "properties": { "data": { "type": "string" }, "data_hash": { "type": "string" }, "metadata": { "$ref": "#/$defs/Value" }, "mime_type": { "type": "string" }, "name": { "type": [ "string", "null" ] } } }, "TranslationDetails": { "type": "object", "required": [ "translation", "confidence", "detection_used" ], "properties": { "confidence": { "type": "number", "format": "double" }, "detection_used": { "type": "boolean" }, "original_input": { "type": [ "string", "null" ] }, "translation": { "$ref": "#/$defs/TranslationKind" }, "translation_language": { "type": [ "string", "null" ] } } }, "TranslationKind": { "type": "string", "enum": [ "No Translation", "Culture Selected", "Culture Detected" ] }, "UnparkPayload": { "oneOf": [ { "allOf": [ { "$ref": "#/$defs/TimerUnparkPayload" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "timer" ] } } } ] }, { "allOf": [ { "$ref": "#/$defs/UserInteractionUnparkPayload" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "user_interaction" ] } } } ] }, { "allOf": [ { "$ref": "#/$defs/AgenticUnparkPayload" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "agentic" ] } } } ] }, { "allOf": [ { "$ref": "#/$defs/ToolCallUnparkPayload" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "tool" ] } } } ] } ], "description": "Enum type for unparking" }, "UsageDetails": { "type": "object", "properties": { "cache_creation_input_tokens": { "type": "integer", "format": "int32", "default": 0, "minimum": 0 }, "cache_read_input_tokens": { "type": "integer", "format": "int32", "default": 0, "minimum": 0 }, "completion_tokens": { "type": "integer", "format": "int32", "default": 0, "minimum": 0 }, "prompt_tokens": { "type": "integer", "format": "int32", "default": 0, "minimum": 0 }, "total_tokens": { "type": "integer", "format": "int32", "default": 0, "minimum": 0 } } }, "UserInteractionDialogOption": { "type": "object", "description": "Represents a dialog option for user interaction", "required": [ "text" ], "properties": { "is_media": { "type": [ "boolean", "null" ] }, "language": { "type": [ "string", "null" ] }, "text": { "type": "string" } } }, "UserInteractionParkPayload": { "type": "object", "description": "Park payload for user interaction", "required": [ "answer" ], "properties": { "answer": { "type": "string" }, "dialog_options": { "type": [ "array", "null" ], "items": { "$ref": "#/$defs/UserInteractionDialogOption" } }, "retry_count": { "type": [ "integer", "null" ], "format": "int64", "description": "Number of times the user has been asked to retry due to invalid response" }, "translate_dialog_options": { "type": "boolean", "description": "Whether the orchestrator should translate `dialog_options[].text` to the\nconversation's resolved language. Carries the activity-level\n`dialog_options_translatable` decision; defaults to `true` (translate).\nPer-option opt-out is handled via `UserInteractionDialogOption.is_media`." } } }, "UserInteractionUnparkPayload": { "type": "object", "description": "Unpark payload for user interaction", "required": [ "user_response" ], "properties": { "user_response": { "$ref": "#/$defs/UserResponse" } } }, "UserMessage": { "allOf": [ { "type": "object", "description": "Base fields shared by all message types", "properties": { "actor": { "oneOf": [ { "type": "null" }, { "$ref": "#/$defs/Actor", "description": "The participant who authored this item, when the role alone is ambiguous." } ] }, "content": { "type": [ "array", "null" ], "items": { "$ref": "#/$defs/MessageContentPart" } }, "interaction_id": { "type": [ "string", "null" ], "format": "uuid" }, "is_message_before_halo": { "type": "boolean" }, "timestamp": { "type": [ "string", "null" ], "format": "date-time", "description": "Time at which the conversation item was first produced. Legacy items\nwithout valid initialization metadata fall back to their logging time." } } }, { "type": "object", "required": [ "is_safe", "do_not_answer" ], "properties": { "custom_guardrail_results": { "type": [ "array", "null" ], "items": { "$ref": "#/$defs/CustomGuardrailResult" } }, "do_not_answer": { "type": "boolean" }, "is_recognized": { "type": [ "boolean", "null" ] }, "is_safe": { "type": "boolean" } } } ], "description": "User message" }, "UserResponse": { "oneOf": [ { "type": "string" }, { "$ref": "#/$defs/MediaContentPart" }, { "type": "array", "items": { "$ref": "#/$defs/ContentPart" }, "description": "Mixed content (e.g. user replied with both text and an image).\nCarries the full ordered list of content parts so the agentic LLM\ncan reason over both the text query and the media together." } ], "description": "User response in an unpark payload`." }, "Value": {}, "VisitedAgent": { "type": "object", "description": "Agent info for visited agents", "required": [ "id", "name" ], "properties": { "id": { "type": "integer", "format": "int64" }, "name": { "type": "string" } } }, "VisitedTool": { "type": "object", "description": "Tool info for visited tools", "required": [ "id", "name" ], "properties": { "description": { "type": [ "string", "null" ] }, "id": { "type": "integer", "format": "int64" }, "name": { "type": "string" } } }, "VoiceCustomHandoverDetails": { "type": "object", "description": "Voice custom handover details", "required": [ "custom_type", "custom_config" ], "properties": { "custom_config": { "type": "object", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "custom_type": { "type": "string" } } }, "VoiceForwardHandoverDetails": { "type": "object", "description": "Voice forward handover details", "required": [ "callee_id" ], "properties": { "anonymous": { "type": [ "boolean", "null" ] }, "callee_id": { "type": "string" }, "caller_id": { "type": [ "string", "null" ] } } }, "VoiceLoggingHandoverDetails": { "type": "object", "description": "Voice logging handover details" }, "VoiceMscHandoverDetails": { "type": "object", "description": "Voice MSC handover details", "required": [ "environment", "web_store_referrer", "routing_keywords" ], "properties": { "environment": { "type": "string" }, "routing_keywords": { "type": "array", "items": { "type": "string" } }, "web_store_referrer": { "type": "string" } } }, "VoiceTransferHandoverDetails": { "type": "object", "description": "Voice transfer handover details", "required": [ "distribution_group", "distribution_group_algorithm" ], "properties": { "cm_context_variables": { "type": [ "object", "null" ], "additionalProperties": {}, "propertyNames": { "type": "string" } }, "distribution_group": { "type": "string" }, "distribution_group_algorithm": { "type": "integer", "format": "int32" } } }, "i32": { "type": "integer", "format": "int32" }, "i64": { "type": "integer", "format": "int64" } } }