jambonz-python-sdk 0.2.0__py3-none-any.whl

jambonz_sdk/schema/verbs/gather.schema.json

@@ -0,0 +1,190 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/verbs/gather",
+  "minVersion": "0.9.6",
+  "title": "Gather",
+  "description": "Collects user input via speech (STT) and/or DTMF digits. Optionally plays a prompt (using nested 'say' or 'play') while listening. When input is received, the result is sent to the actionHook which should return the next set of verbs. This is the primary verb for building interactive voice menus and conversational flows.",
+  "type": "object",
+  "properties": {
+    "verb": {
+      "const": "gather",
+      "description": "The verb name."
+    },
+    "id": {
+      "type": "string",
+      "description": "An optional unique identifier for this verb instance."
+    },
+    "actionHook": {
+      "$ref": "../components/actionHook",
+      "description": "Invoked when the gather completes. The payload includes 'reason' ('speechDetected', 'dtmfDetected', or 'timeout'), 'speech' (object with alternatives[].transcript and alternatives[].confidence when reason is speechDetected), and 'digits' (string when reason is dtmfDetected). In webhook mode this is a URL that receives an HTTP POST. In WebSocket mode this is an event name — use session.on('/hookName', (evt) => {...}) and respond with session.reply()."
+    },
+    "input": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "enum": [
+          "speech",
+          "digits"
+        ]
+      },
+      "description": "The types of input to accept. Can include 'speech' (STT), 'digits' (DTMF), or both.",
+      "default": [
+        "digits"
+      ],
+      "examples": [
+        [
+          "speech",
+          "digits"
+        ],
+        [
+          "speech"
+        ],
+        [
+          "digits"
+        ]
+      ]
+    },
+    "finishOnKey": {
+      "type": "string",
+      "description": "A DTMF key that signals the end of digit input. The key itself is not included in the collected digits.",
+      "examples": [
+        "#",
+        "*"
+      ]
+    },
+    "numDigits": {
+      "type": "number",
+      "description": "Exact number of DTMF digits to collect. Gather completes automatically when this many digits are received."
+    },
+    "minDigits": {
+      "type": "number",
+      "description": "Minimum number of DTMF digits required."
+    },
+    "maxDigits": {
+      "type": "number",
+      "description": "Maximum number of DTMF digits to collect."
+    },
+    "interDigitTimeout": {
+      "type": "number",
+      "description": "Time in seconds to wait between DTMF digits before considering input complete.",
+      "examples": [
+        5
+      ]
+    },
+    "speechTimeout": {
+      "type": "number",
+      "description": "Time in seconds of silence after speech before considering the utterance complete.",
+      "examples": [
+        2,
+        3
+      ]
+    },
+    "timeout": {
+      "type": "number",
+      "description": "Overall timeout in seconds. If no input is received within this time, the gather completes with no input and the actionHook is invoked.",
+      "examples": [
+        10,
+        30
+      ]
+    },
+    "partialResultHook": {
+      "$ref": "../components/actionHook",
+      "description": "A webhook to invoke with interim (partial) speech recognition results. Useful for providing real-time feedback or early processing."
+    },
+    "listenDuringPrompt": {
+      "type": "boolean",
+      "description": "If true, listen for input while the prompt is playing. If false, only start listening after the prompt finishes.",
+      "default": true
+    },
+    "dtmfBargein": {
+      "type": "boolean",
+      "description": "If true, DTMF input interrupts (barges in on) any playing prompt."
+    },
+    "bargein": {
+      "type": "boolean",
+      "description": "If true, speech input interrupts (barges in on) any playing prompt."
+    },
+    "minBargeinWordCount": {
+      "type": "number",
+      "description": "Minimum number of words that must be recognized before barge-in is triggered. Prevents brief noises from interrupting prompts.",
+      "examples": [
+        1,
+        2
+      ]
+    },
+    "recognizer": {
+      "$ref": "../components/recognizer",
+      "description": "Override the session-level STT configuration for this gather."
+    },
+    "say": {
+      "type": "object",
+      "description": "A nested say prompt played to the caller while listening for input. Accepts the same properties as the say verb (text, synthesizer, etc.) but no fields are required.",
+      "additionalProperties": true
+    },
+    "play": {
+      "type": "object",
+      "description": "A nested play prompt played to the caller while listening for input. Accepts the same properties as the play verb (url, etc.) but no fields are required.",
+      "additionalProperties": true
+    },
+    "fillerNoise": {
+      "$ref": "../components/fillerNoise",
+      "description": "Filler noise configuration while waiting for the actionHook to respond."
+    },
+    "actionHookDelayAction": {
+      "$ref": "../components/actionHookDelayAction",
+      "description": "Configuration for interim actions while the actionHook is processing."
+    }
+  },
+  "examples": [
+    {
+      "verb": "gather",
+      "input": [
+        "speech",
+        "digits"
+      ],
+      "actionHook": "/gather-result",
+      "timeout": 15,
+      "say": {
+        "text": "Please say or enter your account number."
+      }
+    },
+    {
+      "verb": "gather",
+      "input": [
+        "digits"
+      ],
+      "actionHook": "/menu-selection",
+      "numDigits": 1,
+      "say": {
+        "text": "Press 1 for sales, 2 for support, or 3 for billing."
+      }
+    },
+    {
+      "verb": "gather",
+      "input": [
+        "speech"
+      ],
+      "actionHook": "/process-speech",
+      "timeout": 20,
+      "bargein": true,
+      "recognizer": {
+        "vendor": "deepgram",
+        "language": "en-US",
+        "hints": [
+          "account",
+          "balance",
+          "transfer",
+          "payment"
+        ]
+      },
+      "say": {
+        "text": "How can I help you today?"
+      },
+      "fillerNoise": {
+        "enable": true,
+        "url": "https://example.com/sounds/typing.wav",
+        "startDelaySecs": 2
+      }
+    }
+  ]
+}

jambonz_sdk/schema/verbs/google_s2s.schema.json

@@ -0,0 +1,42 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/verbs/google_s2s",
+  "minVersion": "10.1.0",
+  "title": "Google S2S",
+  "description": "Shortcut for 'llm' with vendor automatically set to 'google'. Connects the caller to a Google model for real-time speech-to-speech voice conversation.",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "../components/llm-base"
+    }
+  ],
+  "properties": {
+    "verb": {
+      "const": "google_s2s",
+      "description": "The verb name."
+    },
+    "vendor": {
+      "type": "string",
+      "const": "google",
+      "description": "The LLM vendor (always 'google' for this shortcut)."
+    }
+  },
+  "required": [
+    "llmOptions"
+  ],
+  "examples": [
+    {
+      "verb": "google_s2s",
+      "model": "gemini-2.0-flash",
+      "llmOptions": {
+        "messages": [
+          {
+            "role": "system",
+            "content": "You are a helpful voice assistant."
+          }
+        ]
+      },
+      "actionHook": "/s2s-complete"
+    }
+  ]
+}

jambonz_sdk/schema/verbs/hangup.schema.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/verbs/hangup",
+  "minVersion": "0.9.6",
+  "title": "Hangup",
+  "description": "Terminates the call. Optionally includes custom SIP headers on the BYE request.",
+  "type": "object",
+  "properties": {
+    "verb": {
+      "const": "hangup",
+      "description": "The verb name."
+    },
+    "id": {
+      "type": "string",
+      "description": "An optional unique identifier for this verb instance."
+    },
+    "headers": {
+      "type": "object",
+      "description": "Custom SIP headers to include on the BYE request.",
+      "additionalProperties": {
+        "oneOf": [{ "type": "string" }, { "type": "number" }]
+      }
+    }
+  },
+  "examples": [
+    {
+      "verb": "hangup"
+    },
+    {
+      "verb": "hangup",
+      "headers": {
+        "X-Reason": "call-complete"
+      }
+    }
+  ]
+}

jambonz_sdk/schema/verbs/leave.schema.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/verbs/leave",
+  "minVersion": "0.9.6",
+  "title": "Leave",
+  "description": "Removes the caller from a conference or queue that they are currently in. Execution continues with the next verb in the application.",
+  "type": "object",
+  "properties": {
+    "verb": {
+      "const": "leave"
+    },
+    "id": {
+      "type": "string",
+      "description": "An optional unique identifier for this verb instance."
+    }
+  },
+  "examples": [
+    {
+      "verb": "leave"
+    }
+  ]
+}

jambonz_sdk/schema/verbs/listen.schema.json

@@ -0,0 +1,127 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/verbs/listen",
+  "minVersion": "0.9.6",
+  "title": "Listen",
+  "description": "Streams real-time call audio to an external websocket endpoint. The remote endpoint receives raw audio and can optionally send audio back (bidirectional). Used for custom speech processing, real-time analysis, AI agent integration, and recording to external systems.",
+  "type": "object",
+  "properties": {
+    "verb": {
+      "const": "listen",
+      "description": "The verb name."
+    },
+    "id": {
+      "type": "string",
+      "description": "An optional unique identifier for this verb instance."
+    },
+    "url": {
+      "type": "string",
+      "format": "uri",
+      "description": "The websocket URL to stream audio to.",
+      "examples": [
+        "wss://myapp.example.com/audio-stream"
+      ]
+    },
+    "actionHook": {
+      "$ref": "../components/actionHook",
+      "description": "A webhook invoked when the listen session ends. Should return the next verbs to execute."
+    },
+    "wsAuth": {
+      "$ref": "../components/auth",
+      "description": "Authentication credentials for the websocket connection."
+    },
+    "mixType": {
+      "type": "string",
+      "description": "How to mix the audio channels when streaming. 'mono' sends a single mixed channel, 'stereo' sends caller and callee as separate left/right channels, 'mixed' sends both as a single mixed stream.",
+      "enum": [
+        "mono",
+        "stereo",
+        "mixed"
+      ],
+      "default": "mono"
+    },
+    "metadata": {
+      "type": "object",
+      "description": "Arbitrary metadata to send to the websocket endpoint in the initial connection message.",
+      "additionalProperties": true
+    },
+    "sampleRate": {
+      "type": "number",
+      "description": "The audio sample rate in Hz.",
+      "examples": [
+        8000,
+        16000,
+        24000
+      ],
+      "default": 8000
+    },
+    "finishOnKey": {
+      "type": "string",
+      "description": "A DTMF key that ends the listen session when pressed.",
+      "examples": [
+        "#"
+      ]
+    },
+    "maxLength": {
+      "type": "number",
+      "description": "Maximum duration in seconds for the listen session."
+    },
+    "passDtmf": {
+      "type": "boolean",
+      "description": "If true, forward DTMF events to the websocket endpoint."
+    },
+    "playBeep": {
+      "type": "boolean",
+      "description": "If true, play a beep tone before streaming begins."
+    },
+    "disableBidirectionalAudio": {
+      "type": "boolean",
+      "description": "If true, disable receiving audio from the websocket endpoint. Audio flows only from the call to the websocket, not back."
+    },
+    "bidirectionalAudio": {
+      "$ref": "../components/bidirectionalAudio",
+      "description": "Fine-grained configuration for bidirectional audio."
+    },
+    "timeout": {
+      "type": "number",
+      "description": "Time in seconds to wait for audio activity before ending the listen session."
+    },
+    "transcribe": {
+      "$ref": "transcribe",
+      "description": "Nested transcribe verb — enables simultaneous real-time transcription of the audio being streamed."
+    },
+    "earlyMedia": {
+      "type": "boolean",
+      "description": "If true, begin streaming audio before the call is formally answered."
+    },
+    "channel": {
+      "type": "number",
+      "description": "Specific audio channel to stream. Used when streaming a single channel of a multi-channel call."
+    }
+  },
+  "required": [
+    "url"
+  ],
+  "examples": [
+    {
+      "verb": "listen",
+      "url": "wss://myapp.example.com/audio-stream",
+      "actionHook": "/listen-complete",
+      "sampleRate": 16000,
+      "mixType": "stereo"
+    },
+    {
+      "verb": "listen",
+      "url": "wss://myapp.example.com/ai-agent",
+      "bidirectionalAudio": {
+        "enabled": true,
+        "streaming": true,
+        "sampleRate": 24000
+      },
+      "metadata": {
+        "callType": "support",
+        "language": "en-US"
+      }
+    }
+  ]
+}

jambonz_sdk/schema/verbs/llm.schema.json

@@ -0,0 +1,44 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/verbs/llm",
+  "minVersion": "0.9.6",
+  "title": "LLM",
+  "description": "Connects the caller to a large language model for a real-time voice conversation. Handles the complete STT → LLM → TTS pipeline, including turn detection, interruption handling, and tool/function calling. The caller speaks naturally and the LLM responds via synthesized speech. This is the primary verb for building AI voice agents on jambonz.",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "../components/llm-base"
+    }
+  ],
+  "properties": {
+    "verb": {
+      "const": "llm",
+      "description": "The verb name."
+    }
+  },
+  "required": [
+    "vendor",
+    "llmOptions"
+  ],
+  "examples": [
+    {
+      "verb": "llm",
+      "vendor": "openai",
+      "model": "gpt-4o",
+      "auth": {
+        "apiKey": "sk-..."
+      },
+      "llmOptions": {
+        "messages": [
+          {
+            "role": "system",
+            "content": "You are a helpful customer service agent. Be concise and friendly."
+          }
+        ],
+        "temperature": 0.7
+      },
+      "actionHook": "/llm-complete",
+      "toolHook": "/llm-tool-call"
+    }
+  ]
+}

jambonz_sdk/schema/verbs/message.schema.json

@@ -0,0 +1,82 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/verbs/message",
+  "minVersion": "0.9.6",
+  "title": "Message",
+  "description": "Sends an SMS or MMS message. Can be used during a voice call to send a text message to the caller or another party, or as a standalone action.",
+  "type": "object",
+  "properties": {
+    "verb": {
+      "const": "message"
+    },
+    "id": {
+      "type": "string",
+      "description": "An optional unique identifier for this verb instance."
+    },
+    "to": {
+      "type": "string",
+      "description": "The destination phone number in E.164 format.",
+      "examples": [
+        "+15085551212"
+      ]
+    },
+    "from": {
+      "type": "string",
+      "description": "The sender phone number in E.164 format. Must be a number provisioned on the jambonz platform.",
+      "examples": [
+        "+15085559876"
+      ]
+    },
+    "text": {
+      "type": "string",
+      "description": "The text content of the message."
+    },
+    "media": {
+      "oneOf": [
+        {
+          "type": "string",
+          "format": "uri"
+        },
+        {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "format": "uri"
+          }
+        }
+      ],
+      "description": "URL(s) of media to attach to the message (MMS). Can be images, audio, or video.",
+      "examples": [
+        "https://example.com/images/receipt.png"
+      ]
+    },
+    "carrier": {
+      "type": "string",
+      "description": "The messaging carrier to use. If not specified, the default carrier is used."
+    },
+    "account_sid": {
+      "type": "string",
+      "description": "The account SID to use for sending. Defaults to the current account."
+    },
+    "message_sid": {
+      "type": "string",
+      "description": "An optional message SID for tracking."
+    },
+    "actionHook": {
+      "$ref": "../components/actionHook",
+      "description": "A webhook invoked when the message send completes or fails."
+    }
+  },
+  "required": [
+    "to",
+    "from"
+  ],
+  "examples": [
+    {
+      "verb": "message",
+      "to": "+15085551212",
+      "from": "+15085559876",
+      "text": "Your order has been confirmed. Order #12345."
+    }
+  ]
+}

jambonz_sdk/schema/verbs/openai_s2s.schema.json

@@ -0,0 +1,42 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/verbs/openai_s2s",
+  "minVersion": "10.1.0",
+  "title": "OpenAI S2S",
+  "description": "Shortcut for 'llm' with vendor automatically set to 'openai'. Connects the caller to an OpenAI model for real-time speech-to-speech voice conversation.",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "../components/llm-base"
+    }
+  ],
+  "properties": {
+    "verb": {
+      "const": "openai_s2s",
+      "description": "The verb name."
+    },
+    "vendor": {
+      "type": "string",
+      "const": "openai",
+      "description": "The LLM vendor (always 'openai' for this shortcut)."
+    }
+  },
+  "required": [
+    "llmOptions"
+  ],
+  "examples": [
+    {
+      "verb": "openai_s2s",
+      "model": "gpt-4o-realtime",
+      "llmOptions": {
+        "messages": [
+          {
+            "role": "system",
+            "content": "You are a helpful voice assistant."
+          }
+        ]
+      },
+      "actionHook": "/s2s-complete"
+    }
+  ]
+}

jambonz_sdk/schema/verbs/pause.schema.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/verbs/pause",
+  "minVersion": "0.9.6",
+  "title": "Pause",
+  "description": "Pauses execution for a specified number of seconds. The caller hears silence during the pause. Useful for adding delays between verbs.",
+  "type": "object",
+  "properties": {
+    "verb": {
+      "const": "pause",
+      "description": "The verb name."
+    },
+    "id": {
+      "type": "string",
+      "description": "An optional unique identifier for this verb instance."
+    },
+    "length": {
+      "type": "number",
+      "description": "The duration of the pause in seconds.",
+      "examples": [
+        1,
+        2,
+        5
+      ]
+    }
+  },
+  "required": [
+    "length"
+  ],
+  "examples": [
+    {
+      "verb": "pause",
+      "length": 2
+    }
+  ]
+}