{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://jambonz.org/schema/callbacks/gather",
  "title": "Gather ActionHook Payload",
  "description": "Payload sent to the actionHook when a gather verb completes, either due to speech detected, DTMF detected, or timeout.",
  "allOf": [
    { "$ref": "base" }
  ],
  "type": "object",
  "properties": {
    "reason": {
      "type": "string",
      "enum": ["speechDetected", "dtmfDetected", "timeout", "error", "stt-low-confidence"],
      "description": "The reason the gather completed."
    },
    "speech": {
      "type": "object",
      "description": "Speech recognition results, present when reason is speechDetected.",
      "properties": {
        "language_code": { "type": "string", "description": "Language code used for recognition (e.g. 'en-US')." },
        "channel_tag": { "type": "integer", "description": "Audio channel number." },
        "is_final": { "type": "boolean", "description": "Whether this is a final (not interim) recognition result." },
        "alternatives": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "transcript": { "type": "string", "description": "The recognized transcript." },
              "confidence": { "type": "number", "description": "Confidence score between 0 and 1." }
            }
          },
          "description": "Array of recognition alternatives, ordered by confidence."
        },
        "vendor": {
          "type": "object",
          "description": "Vendor-specific STT data. Structure varies by provider.",
          "properties": {
            "name": { "type": "string", "description": "STT vendor name (e.g. 'deepgram', 'google', 'aws')." },
            "evt": {
              "description": "Raw vendor-specific event payload. A single object for simple utterances, or an array of objects when jambonz assembles the final transcript from multiple STT segments. Contains provider-specific fields like word-level timestamps, model info, etc.",
              "oneOf": [
                { "type": "object", "additionalProperties": true },
                { "type": "array", "items": { "type": "object", "additionalProperties": true } }
              ]
            }
          }
        }
      }
    },
    "digits": {
      "type": "string",
      "description": "DTMF digits collected, present when reason is dtmfDetected."
    },
    "details": {
      "type": "object",
      "description": "Error information if reason is error."
    }
  },
  "additionalProperties": true
}