{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/bots/refs/heads/main/json-schema/bots-conversation-turn-schema.json",
  "title": "ConversationTurn",
  "description": "A single turn in a bot conversation, capturing the user utterance, the bot response, and the NLU interpretation that linked them.",
  "type": "object",
  "properties": {
    "turn_id": {
      "type": "string",
      "description": "Unique identifier for this conversation turn.",
      "example": "turn_01HX5J9Z6E7K"
    },
    "conversation_id": {
      "type": "string",
      "description": "Identifier of the parent conversation or session.",
      "example": "conv_8f1c2d"
    },
    "channel": {
      "type": "string",
      "description": "Channel on which the turn occurred.",
      "enum": ["slack", "discord", "telegram", "whatsapp", "ms-teams", "web-chat", "facebook-messenger", "instagram", "sms", "voice", "google-chat", "line", "alexa", "google-assistant"],
      "example": "slack"
    },
    "timestamp": {
      "type": "string",
      "format": "date-time",
      "description": "ISO 8601 timestamp of the turn.",
      "example": "2026-05-19T14:22:11Z"
    },
    "user": {
      "type": "object",
      "description": "Identity of the end user in this turn.",
      "properties": {
        "id": { "type": "string", "example": "U02ABCDEF" },
        "display_name": { "type": "string", "example": "Jordan Park" }
      }
    },
    "user_utterance": {
      "type": "string",
      "description": "Raw text (or transcribed speech) sent by the user in this turn.",
      "example": "I need to reset my password"
    },
    "intent": {
      "type": "object",
      "description": "Intent detected by the NLU engine for this turn.",
      "properties": {
        "name": { "type": "string", "example": "account.reset_password" },
        "confidence": { "type": "number", "minimum": 0, "maximum": 1, "example": 0.91 }
      }
    },
    "entities": {
      "type": "array",
      "description": "Entities extracted from the user utterance.",
      "items": {
        "type": "object",
        "properties": {
          "type": { "type": "string", "example": "email" },
          "value": { "type": "string", "example": "jordan@example.com" }
        }
      }
    },
    "bot_response": {
      "type": "object",
      "description": "Bot response emitted in this turn.",
      "properties": {
        "text": { "type": "string", "example": "I can help with that. What email is on the account?" },
        "rich_content_type": {
          "type": "string",
          "enum": ["text", "card", "carousel", "quick_replies", "form", "voice"],
          "example": "text"
        }
      }
    },
    "handoff_triggered": {
      "type": "boolean",
      "description": "Whether this turn escalated the conversation to a human agent.",
      "example": false
    }
  },
  "required": ["turn_id", "conversation_id", "channel", "user_utterance"]
}