@jambonz/schema 0.1.1

package/components/actionHookDelayAction.schema.json

@@ -0,0 +1,37 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/components/actionHookDelayAction",
+  "title": "ActionHookDelayAction",
+  "description": "Configuration for what to do when an actionHook (webhook) takes a long time to respond. Allows playing interim content (e.g. 'please wait' messages, hold music) while waiting for the webhook response, with configurable retry and give-up behavior.",
+  "type": "object",
+  "properties": {
+    "enabled": {
+      "type": "boolean",
+      "description": "Whether to enable delay handling for actionHooks."
+    },
+    "noResponseTimeout": {
+      "type": "number",
+      "description": "Time in seconds to wait before executing the delay actions. If the webhook responds before this timeout, the delay actions are skipped.",
+      "examples": [3, 5]
+    },
+    "noResponseGiveUpTimeout": {
+      "type": "number",
+      "description": "Total time in seconds to wait for a webhook response before giving up and executing the giveUpActions.",
+      "examples": [30, 60]
+    },
+    "retries": {
+      "type": "number",
+      "description": "Number of times to retry the delay actions while still waiting for the webhook response."
+    },
+    "actions": {
+      "type": "array",
+      "description": "An array of jambonz verbs to execute while waiting for the webhook response. Typically 'say' or 'play' verbs with messages like 'please hold'.",
+      "items": { "type": "object" }
+    },
+    "giveUpActions": {
+      "type": "array",
+      "description": "An array of jambonz verbs to execute if the webhook never responds within the giveUpTimeout. Typically an error message and/or hangup.",
+      "items": { "type": "object" }
+    }
+  }
+}

package/components/amd.schema.json

@@ -0,0 +1,68 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/components/amd",
+  "title": "Answering Machine Detection",
+  "description": "Configuration for answering machine detection (AMD). Detects whether an outbound or inbound call was answered by a human or a machine. Used as a nested property on the 'config' or 'dial' verb. IMPORTANT: AMD runs asynchronously in the background. When using AMD with the 'config' verb, you MUST follow it with a 'pause' verb (e.g. pause({ length: 25 })) to keep the call alive while AMD detection runs. Without a pause, the call will end immediately after config completes.",
+  "type": "object",
+  "properties": {
+    "actionHook": {
+      "$ref": "actionHook",
+      "description": "Webhook to receive AMD events (amd_human_detected, amd_machine_detected, amd_no_speech_detected, amd_decision_timeout, amd_machine_stopped_speaking, amd_tone_detected, amd_error, amd_stopped)."
+    },
+    "thresholdWordCount": {
+      "type": "number",
+      "description": "Number of spoken words in a greeting that triggers an amd_machine_detected result.",
+      "default": 9
+    },
+    "digitCount": {
+      "type": "number",
+      "description": "Number of digits in a greeting to trigger detection. 0 disables digit-based detection.",
+      "default": 0
+    },
+    "timers": {
+      "type": "object",
+      "description": "Timer settings controlling AMD detection windows.",
+      "properties": {
+        "noSpeechTimeoutMs": {
+          "type": "number",
+          "description": "Milliseconds to wait for any speech before returning amd_no_speech_detected.",
+          "default": 5000
+        },
+        "decisionTimeoutMs": {
+          "type": "number",
+          "description": "Milliseconds before returning amd_decision_timeout if no determination is made.",
+          "default": 15000
+        },
+        "toneTimeoutMs": {
+          "type": "number",
+          "description": "Milliseconds to wait for beep/tone detection.",
+          "default": 20000
+        },
+        "greetingCompletionTimeoutMs": {
+          "type": "number",
+          "description": "Milliseconds of silence after speech before determining the machine greeting is complete. Automatically reduced to 1000ms if a beep is detected.",
+          "default": 2000
+        }
+      },
+      "additionalProperties": false
+    },
+    "recognizer": {
+      "$ref": "recognizer",
+      "description": "Override the STT recognizer used for AMD speech detection. When omitted, AMD uses the session default recognizer with enhancedModel enabled."
+    }
+  },
+  "required": ["actionHook"],
+  "examples": [
+    {
+      "actionHook": "/amd-events"
+    },
+    {
+      "actionHook": "/amd-events",
+      "thresholdWordCount": 6,
+      "timers": {
+        "noSpeechTimeoutMs": 3000,
+        "decisionTimeoutMs": 10000
+      }
+    }
+  ]
+}

package/components/auth.schema.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/components/auth",
+  "title": "Auth",
+  "description": "Basic authentication credentials, used for authenticating with external services such as websocket endpoints or SIP registrars.",
+  "type": "object",
+  "properties": {
+    "username": {
+      "type": "string",
+      "description": "The username for authentication."
+    },
+    "password": {
+      "type": "string",
+      "description": "The password for authentication."
+    }
+  },
+  "required": ["username", "password"]
+}

package/components/bidirectionalAudio.schema.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/components/bidirectionalAudio",
+  "title": "BidirectionalAudio",
+  "description": "Configuration for bidirectional audio streaming over a websocket connection. When enabled, the remote websocket endpoint can send audio back to jambonz to be played to the caller.",
+  "type": "object",
+  "properties": {
+    "enabled": {
+      "type": "boolean",
+      "description": "Whether to enable bidirectional audio on the websocket connection."
+    },
+    "streaming": {
+      "type": "boolean",
+      "description": "If true, audio is streamed continuously rather than sent as complete messages."
+    },
+    "sampleRate": {
+      "type": "number",
+      "description": "The sample rate in Hz for bidirectional audio.",
+      "examples": [8000, 16000, 24000]
+    }
+  }
+}

package/components/fillerNoise.schema.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/components/fillerNoise",
+  "title": "FillerNoise",
+  "description": "Configuration for playing background filler noise (e.g. keyboard typing, hold music) while the application is processing and the caller would otherwise hear silence. Commonly used during LLM response generation to indicate the system is working.",
+  "type": "object",
+  "properties": {
+    "enable": {
+      "type": "boolean",
+      "description": "Whether to enable filler noise."
+    },
+    "url": {
+      "type": "string",
+      "format": "uri",
+      "description": "URL of the audio file to play as filler noise. Should be a short, loopable audio clip.",
+      "examples": ["https://example.com/sounds/typing.wav"]
+    },
+    "startDelaySecs": {
+      "type": "number",
+      "description": "Number of seconds to wait before starting filler noise. Prevents filler noise from playing during brief processing pauses.",
+      "examples": [1, 2]
+    }
+  },
+  "required": ["enable"]
+}

package/components/llm-base.schema.json

@@ -0,0 +1,94 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/components/llm-base",
+  "title": "LLM Base Properties",
+  "description": "Shared properties for llm, s2s, and vendor-specific s2s verb schemas.",
+  "type": "object",
+  "properties": {
+    "id": {
+      "type": "string",
+      "description": "An optional unique identifier for this verb instance."
+    },
+    "vendor": {
+      "type": "string",
+      "description": "The LLM vendor to use.",
+      "examples": ["openai", "anthropic", "google", "groq", "deepseek", "deepgram", "ultravox", "custom"]
+    },
+    "model": {
+      "type": "string",
+      "description": "The specific model to use from the vendor.",
+      "examples": ["gpt-4o", "claude-sonnet-4-20250514", "gemini-2.0-flash"]
+    },
+    "auth": {
+      "type": "object",
+      "description": "Authentication credentials for the LLM vendor API.",
+      "properties": {
+        "apiKey": {
+          "type": "string",
+          "description": "The API key for the LLM vendor."
+        }
+      },
+      "additionalProperties": true
+    },
+    "connectOptions": {
+      "type": "object",
+      "description": "Additional connection options for the LLM vendor, such as custom base URLs or API versions.",
+      "additionalProperties": true
+    },
+    "llmOptions": {
+      "type": "object",
+      "description": "Configuration passed to the LLM including the system prompt, temperature, tools/functions, and other model parameters. The structure varies by vendor but typically includes 'messages' (conversation history), 'temperature', 'tools' (function definitions), and 'maxTokens'.",
+      "additionalProperties": true,
+      "examples": [
+        {
+          "messages": [
+            { "role": "system", "content": "You are a helpful customer service agent for Acme Corp." }
+          ],
+          "temperature": 0.7
+        }
+      ]
+    },
+    "mcpServers": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "url": {
+            "type": "string",
+            "format": "uri",
+            "description": "The URL of the MCP server."
+          },
+          "auth": {
+            "type": "object",
+            "description": "Authentication for the MCP server.",
+            "additionalProperties": true
+          },
+          "roots": {
+            "type": "array",
+            "items": { "type": "object" },
+            "description": "MCP root definitions."
+          }
+        },
+        "required": ["url"]
+      },
+      "description": "Model Context Protocol servers to connect to. MCP servers provide tools that the LLM can invoke during the conversation."
+    },
+    "actionHook": {
+      "$ref": "actionHook",
+      "description": "A webhook invoked when the LLM conversation ends. Receives conversation details and should return the next verbs to execute."
+    },
+    "eventHook": {
+      "$ref": "actionHook",
+      "description": "A webhook invoked for real-time events during the LLM conversation (e.g. tool calls, transcription events)."
+    },
+    "toolHook": {
+      "$ref": "actionHook",
+      "description": "A webhook invoked when the LLM calls a tool/function. Receives the tool name and arguments, and should return the tool result."
+    },
+    "events": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "List of event types to receive via the eventHook."
+    }
+  }
+}

package/components/recognizer-assemblyAiOptions.schema.json

@@ -0,0 +1,66 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/components/recognizer-assemblyAiOptions",
+  "title": "AssemblyAI Recognizer Options",
+  "description": "AssemblyAI-specific STT options. Only applies when recognizer vendor is 'assemblyai'.",
+  "type": "object",
+  "properties": {
+    "apiKey": {
+      "type": "string",
+      "description": "AssemblyAI API key. Overrides credentials configured in jambonz."
+    },
+    "serviceVersion": {
+      "type": "string",
+      "enum": ["v2", "v3"],
+      "description": "AssemblyAI streaming API version."
+    },
+    "speechModel": {
+      "type": "string",
+      "description": "AssemblyAI speech model to use for recognition."
+    },
+    "formatTurns": {
+      "type": "boolean",
+      "description": "Enable turn-level formatting."
+    },
+    "endOfTurnConfidenceThreshold": {
+      "type": "number",
+      "description": "Confidence threshold for end-of-turn detection."
+    },
+    "minEndOfTurnSilenceWhenConfident": {
+      "type": "number",
+      "description": "Minimum silence duration (seconds) to trigger end-of-turn when confidence is met."
+    },
+    "maxTurnSilence": {
+      "type": "number",
+      "description": "Maximum silence duration (seconds) before forcing end-of-turn."
+    },
+    "minTurnSilence": {
+      "type": "number",
+      "description": "Minimum silence duration (seconds) before allowing end-of-turn."
+    },
+    "keyterms": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "List of key terms to boost in recognition."
+    },
+    "prompt": {
+      "type": "string",
+      "description": "Prompt to guide the recognition model."
+    },
+    "languageDetection": {
+      "type": "boolean",
+      "description": "Enable automatic language detection."
+    },
+    "vadThreshold": {
+      "type": "number",
+      "description": "Voice activity detection threshold."
+    },
+    "inactivityTimeout": {
+      "type": "number",
+      "description": "Timeout (seconds) for inactivity before closing the stream."
+    }
+  },
+  "additionalProperties": false
+}

package/components/recognizer-awsOptions.schema.json

@@ -0,0 +1,52 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/components/recognizer-awsOptions",
+  "title": "AWS Recognizer Options",
+  "description": "AWS Transcribe specific options. Only applies when recognizer vendor is 'aws'.",
+  "type": "object",
+  "properties": {
+    "accessKey": {
+      "type": "string",
+      "description": "AWS access key ID. Overrides credentials configured in jambonz."
+    },
+    "secretKey": {
+      "type": "string",
+      "description": "AWS secret access key."
+    },
+    "securityToken": {
+      "type": "string",
+      "description": "AWS temporary security token (for STS/assumed roles)."
+    },
+    "region": {
+      "type": "string",
+      "description": "AWS region for the Transcribe service."
+    },
+    "vocabularyName": {
+      "type": "string",
+      "description": "Name of a custom vocabulary to use."
+    },
+    "vocabularyFilterName": {
+      "type": "string",
+      "description": "Name of a vocabulary filter to apply."
+    },
+    "vocabularyFilterMethod": {
+      "type": "string",
+      "enum": ["remove", "mask", "tag"],
+      "description": "How filtered vocabulary words should be handled."
+    },
+    "languageModelName": {
+      "type": "string",
+      "description": "Name of a custom language model."
+    },
+    "piiEntityTypes": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "PII entity types to identify (e.g. 'BANK_ACCOUNT_NUMBER', 'CREDIT_DEBIT_NUMBER')."
+    },
+    "piiIdentifyEntities": {
+      "type": "boolean",
+      "description": "Enable PII entity identification."
+    }
+  },
+  "additionalProperties": false
+}

package/components/recognizer-azureOptions.schema.json

@@ -0,0 +1,32 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/components/recognizer-azureOptions",
+  "title": "Azure Recognizer Options",
+  "description": "Azure Speech Services specific options. Only applies when recognizer vendor is 'microsoft'.",
+  "type": "object",
+  "properties": {
+    "speechSegmentationSilenceTimeoutMs": {
+      "type": "number",
+      "description": "Silence timeout in milliseconds for speech segmentation."
+    },
+    "postProcessing": {
+      "type": "string",
+      "description": "Post-processing mode for transcription results."
+    },
+    "audioLogging": {
+      "type": "boolean",
+      "description": "Enable audio logging for diagnostics."
+    },
+    "languageIdMode": {
+      "type": "string",
+      "enum": ["AtStart", "Continuous"],
+      "description": "Language identification mode when using multiple languages."
+    },
+    "speechRecognitionMode": {
+      "type": "string",
+      "enum": ["CONVERSATION", "DICTATION", "INTERACTIVE"],
+      "description": "Speech recognition mode optimized for the interaction type."
+    }
+  },
+  "additionalProperties": false
+}

package/components/recognizer-cobaltOptions.schema.json

@@ -0,0 +1,34 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/components/recognizer-cobaltOptions",
+  "title": "Cobalt Recognizer Options",
+  "description": "Cobalt-specific STT options. Only applies when recognizer vendor is 'cobalt'.",
+  "type": "object",
+  "properties": {
+    "serverUri": {
+      "type": "string",
+      "description": "Cobalt server URI."
+    },
+    "enableConfusionNetwork": {
+      "type": "boolean",
+      "description": "Enable confusion network output."
+    },
+    "metadata": {
+      "type": "string",
+      "description": "Metadata string to pass to the server."
+    },
+    "compiledContextData": {
+      "type": "string",
+      "description": "Compiled context data for biasing recognition."
+    },
+    "wordTimeOffsets": {
+      "type": "boolean",
+      "description": "Include word-level timestamps."
+    },
+    "contextToken": {
+      "type": "string",
+      "description": "Context token for server-side context."
+    }
+  },
+  "additionalProperties": false
+}

package/components/recognizer-customOptions.schema.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/components/recognizer-customOptions",
+  "title": "Custom Recognizer Options",
+  "description": "Options for custom STT vendors. Only applies when recognizer vendor is 'custom'.",
+  "type": "object",
+  "properties": {
+    "authToken": {
+      "type": "string",
+      "description": "Authentication token for the custom STT service."
+    },
+    "uri": {
+      "type": "string",
+      "description": "WebSocket URI of the custom STT service."
+    },
+    "sampleRate": {
+      "type": "number",
+      "description": "Audio sample rate in Hz."
+    },
+    "options": {
+      "type": "object",
+      "description": "Additional vendor-specific options passed through to the custom service.",
+      "additionalProperties": true
+    }
+  },
+  "additionalProperties": false
+}

package/components/recognizer-deepgramOptions.schema.json

@@ -0,0 +1,147 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/components/recognizer-deepgramOptions",
+  "title": "Deepgram Recognizer Options",
+  "description": "Deepgram-specific STT options. Only applies when recognizer vendor is 'deepgram'.",
+  "type": "object",
+  "properties": {
+    "deepgramSttUri": {
+      "type": "string",
+      "description": "Custom Deepgram STT endpoint URI."
+    },
+    "deepgramSttUseTls": {
+      "type": "boolean",
+      "description": "Whether to use TLS when connecting to the Deepgram STT endpoint."
+    },
+    "apiKey": {
+      "type": "string",
+      "description": "Deepgram API key. Overrides the key configured in jambonz."
+    },
+    "tier": {
+      "type": "string",
+      "description": "Deepgram model tier."
+    },
+    "model": {
+      "type": "string",
+      "description": "Deepgram model name (e.g. 'nova-2', 'nova-2-general')."
+    },
+    "customModel": {
+      "type": "string",
+      "description": "ID of a custom-trained Deepgram model."
+    },
+    "version": {
+      "type": "string",
+      "description": "Model version."
+    },
+    "punctuate": {
+      "type": "boolean",
+      "description": "Enable automatic punctuation."
+    },
+    "smartFormatting": {
+      "type": "boolean",
+      "description": "Enable Deepgram smart formatting (dates, numbers, etc.)."
+    },
+    "noDelay": {
+      "type": "boolean",
+      "description": "Disable Deepgram's internal buffering for lower latency."
+    },
+    "profanityFilter": {
+      "type": "boolean",
+      "description": "Filter profanity from transcripts."
+    },
+    "redact": {
+      "type": "string",
+      "enum": ["pci", "numbers", "true", "ssn"],
+      "description": "Redact sensitive information from transcripts."
+    },
+    "diarize": {
+      "type": "boolean",
+      "description": "Enable speaker diarization."
+    },
+    "diarizeVersion": {
+      "type": "string",
+      "description": "Diarization model version."
+    },
+    "ner": {
+      "type": "boolean",
+      "description": "Enable named entity recognition."
+    },
+    "multichannel": {
+      "type": "boolean",
+      "description": "Enable multichannel processing."
+    },
+    "alternatives": {
+      "type": "number",
+      "description": "Number of alternative transcripts to return."
+    },
+    "numerals": {
+      "type": "boolean",
+      "description": "Convert spoken numbers to digits."
+    },
+    "search": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Terms to search for in the transcript."
+    },
+    "replace": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Terms to replace in the transcript."
+    },
+    "keywords": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Keywords to boost recognition for."
+    },
+    "keyterms": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Key terms to boost recognition for."
+    },
+    "endpointing": {
+      "type": ["boolean", "number"],
+      "description": "Endpointing sensitivity. Boolean to enable/disable, or number of milliseconds."
+    },
+    "utteranceEndMs": {
+      "type": "number",
+      "description": "Milliseconds of silence to detect end of utterance."
+    },
+    "shortUtterance": {
+      "type": "boolean",
+      "description": "Optimize for short utterances."
+    },
+    "vadTurnoff": {
+      "type": "number",
+      "description": "Milliseconds of silence before VAD turns off."
+    },
+    "tag": {
+      "type": "string",
+      "description": "Tag to associate with the request for tracking."
+    },
+    "fillerWords": {
+      "type": "boolean",
+      "description": "Include filler words (um, uh) in transcript."
+    },
+    "eotThreshold": {
+      "type": "number",
+      "description": "End-of-turn confidence threshold (0-1)."
+    },
+    "eotTimeoutMs": {
+      "type": "number",
+      "description": "End-of-turn timeout in milliseconds."
+    },
+    "mipOptOut": {
+      "type": "boolean",
+      "description": "Opt out of Deepgram's model improvement program."
+    },
+    "entityPrompt": {
+      "type": "string",
+      "description": "Prompt to guide entity detection."
+    },
+    "eagerEotThreshold": {
+      "type": "number",
+      "description": "Eager end-of-turn threshold for faster response."
+    }
+  },
+  "additionalProperties": false
+}