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

jambonz_sdk/schema/jambonz-app.schema.json

@@ -0,0 +1,113 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/jambonz-app",
+  "title": "jambonz Application",
+  "description": "A jambonz application is an array of verbs that are executed sequentially to control a phone call. Each verb performs an action: speaking text, playing audio, collecting input, dialing a number, connecting to an AI model, etc. When a webhook (actionHook) is invoked, it must return a new verb array to continue call processing.\n\nThe execution model is simple: verbs execute one after another, top to bottom. When a verb with an actionHook completes (e.g. gather collects input), the actionHook is called and its response replaces the remaining verb stack. If the verb array is exhausted without a hangup, the call is terminated.\n\nThere are two transport modes for delivering verb arrays to jambonz:\n- **Webhook**: Your HTTP server receives POST/GET requests with call data and returns JSON verb arrays in the response body.\n- **WebSocket**: Your server maintains a persistent websocket connection with jambonz and sends/receives verb arrays as JSON messages. Required for real-time features like LLM conversations.\n\nThe verb schemas and JSON structure are identical regardless of transport mode.",
+  "type": "array",
+  "items": {
+    "$ref": "#/$defs/Verb"
+  },
+  "minItems": 1,
+  "$defs": {
+    "Verb": {
+      "oneOf": [
+        { "$ref": "verbs/answer" },
+        { "$ref": "verbs/alert" },
+        { "$ref": "verbs/config" },
+        { "$ref": "verbs/say" },
+        { "$ref": "verbs/play" },
+        { "$ref": "verbs/gather" },
+        { "$ref": "verbs/dial" },
+        { "$ref": "verbs/listen" },
+        { "$ref": "verbs/stream" },
+        { "$ref": "verbs/llm" },
+        { "$ref": "verbs/s2s" },
+        { "$ref": "verbs/openai_s2s" },
+        { "$ref": "verbs/google_s2s" },
+        { "$ref": "verbs/elevenlabs_s2s" },
+        { "$ref": "verbs/deepgram_s2s" },
+        { "$ref": "verbs/ultravox_s2s" },
+        { "$ref": "verbs/dialogflow" },
+        { "$ref": "verbs/pipeline" },
+        { "$ref": "verbs/conference" },
+        { "$ref": "verbs/transcribe" },
+        { "$ref": "verbs/enqueue" },
+        { "$ref": "verbs/dequeue" },
+        { "$ref": "verbs/dtmf" },
+        { "$ref": "verbs/dub" },
+        { "$ref": "verbs/hangup" },
+        { "$ref": "verbs/leave" },
+        { "$ref": "verbs/message" },
+        { "$ref": "verbs/pause" },
+        { "$ref": "verbs/redirect" },
+        { "$ref": "verbs/tag" },
+        { "$ref": "verbs/sip:decline" },
+        { "$ref": "verbs/sip:request" },
+        { "$ref": "verbs/sip:refer" },
+        { "$ref": "verbs/rest:dial" }
+      ],
+      "discriminator": {
+        "propertyName": "verb"
+      }
+    }
+  },
+  "examples": [
+    [
+      {
+        "verb": "config",
+        "synthesizer": { "vendor": "elevenlabs", "voice": "EXAVITQu4vr4xnSDxMaL", "language": "en-US" },
+        "recognizer": { "vendor": "deepgram", "language": "en-US" }
+      },
+      {
+        "verb": "say",
+        "text": "Hello! Welcome to Acme Corp. How can I help you today?"
+      },
+      {
+        "verb": "gather",
+        "input": ["speech"],
+        "actionHook": "/process-input",
+        "timeout": 15,
+        "say": { "text": "I'm listening." }
+      }
+    ],
+    [
+      {
+        "verb": "say",
+        "text": "Please hold while I connect you to an agent."
+      },
+      {
+        "verb": "dial",
+        "target": [{ "type": "phone", "number": "+15085551212" }],
+        "answerOnBridge": true,
+        "timeout": 30,
+        "actionHook": "/dial-complete"
+      },
+      {
+        "verb": "say",
+        "text": "Sorry, the agent is not available. Please try again later."
+      },
+      {
+        "verb": "hangup"
+      }
+    ],
+    [
+      {
+        "verb": "config",
+        "synthesizer": { "vendor": "cartesia", "voice": "sonic-english" },
+        "recognizer": { "vendor": "deepgram", "language": "en-US" }
+      },
+      {
+        "verb": "openai_s2s",
+        "model": "gpt-4o",
+        "llmOptions": {
+          "messages": [
+            { "role": "system", "content": "You are a helpful customer service agent for Acme Corp. Be concise and friendly." }
+          ],
+          "temperature": 0.7
+        },
+        "actionHook": "/llm-complete",
+        "toolHook": "/llm-tool"
+      }
+    ]
+  ]
+}

jambonz_sdk/schema/verbs/alert.schema.json

@@ -0,0 +1,34 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/verbs/alert",
+  "minVersion": "0.9.6",
+  "title": "Alert",
+  "description": "Sends a 180 Ringing provisional response with an Alert-Info header. Used to trigger a specific ring tone or alert behavior on the caller's device before the call is answered.",
+  "type": "object",
+  "properties": {
+    "verb": {
+      "const": "alert"
+    },
+    "id": {
+      "type": "string",
+      "description": "An optional unique identifier for this verb instance."
+    },
+    "message": {
+      "type": "string",
+      "description": "The value to include in the Alert-Info header.",
+      "examples": [
+        "info=alert-internal",
+        "http://example.com/ringtone.wav"
+      ]
+    }
+  },
+  "required": [
+    "message"
+  ],
+  "examples": [
+    {
+      "verb": "alert",
+      "message": "info=alert-internal"
+    }
+  ]
+}

jambonz_sdk/schema/verbs/answer.schema.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/verbs/answer",
+  "minVersion": "0.9.6",
+  "title": "Answer",
+  "description": "Answers an incoming call (sends a 200 OK to the SIP INVITE). Most verbs implicitly answer the call, so this verb is only needed when you want to explicitly control when the call is answered — for example, to play early media before answering.",
+  "type": "object",
+  "properties": {
+    "verb": {
+      "const": "answer"
+    },
+    "id": {
+      "type": "string",
+      "description": "An optional unique identifier for this verb instance."
+    }
+  },
+  "examples": [
+    {
+      "verb": "answer"
+    }
+  ]
+}

jambonz_sdk/schema/verbs/conference.schema.json

@@ -0,0 +1,107 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/verbs/conference",
+  "minVersion": "0.9.6",
+  "title": "Conference",
+  "description": "Places the caller into a multi-party conference room. Multiple callers in the same named conference can speak to each other. Supports features like muting, recording, waiting rooms, and participant limits.",
+  "type": "object",
+  "properties": {
+    "verb": {
+      "const": "conference"
+    },
+    "id": {
+      "type": "string",
+      "description": "An optional unique identifier for this verb instance."
+    },
+    "name": {
+      "type": "string",
+      "description": "The name of the conference room. All callers joining the same named conference are connected together.",
+      "examples": [
+        "team-standup",
+        "customer-call-12345"
+      ]
+    },
+    "beep": {
+      "type": "boolean",
+      "description": "If true, play a beep when participants join or leave."
+    },
+    "memberTag": {
+      "type": "string",
+      "description": "A tag to identify this participant. Can be used to target specific members for actions like muting or whispering."
+    },
+    "speakOnlyTo": {
+      "type": "string",
+      "description": "If set, this participant's audio is only heard by the member with the specified memberTag. Creates a private whisper channel."
+    },
+    "startConferenceOnEnter": {
+      "type": "boolean",
+      "description": "If true (default), the conference starts when this participant joins. If false, this participant waits silently until a participant with startConferenceOnEnter=true joins."
+    },
+    "endConferenceOnExit": {
+      "type": "boolean",
+      "description": "If true, the conference ends for all participants when this participant leaves."
+    },
+    "endConferenceDuration": {
+      "type": "number",
+      "description": "Maximum duration of the conference in seconds."
+    },
+    "maxParticipants": {
+      "type": "number",
+      "description": "Maximum number of participants allowed in the conference."
+    },
+    "joinMuted": {
+      "type": "boolean",
+      "description": "If true, this participant joins the conference muted."
+    },
+    "actionHook": {
+      "$ref": "../components/actionHook",
+      "description": "A webhook invoked when this participant leaves the conference."
+    },
+    "waitHook": {
+      "$ref": "../components/actionHook",
+      "description": "A webhook invoked while this participant is waiting for the conference to start. Should return verbs to play (e.g. hold music)."
+    },
+    "statusEvents": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "List of conference events to receive via the statusHook."
+    },
+    "statusHook": {
+      "$ref": "../components/actionHook",
+      "description": "A webhook to receive conference status events (joins, leaves, etc.)."
+    },
+    "enterHook": {
+      "$ref": "../components/actionHook",
+      "description": "A webhook invoked when this participant first enters the conference."
+    },
+    "record": {
+      "type": "object",
+      "description": "Recording configuration for the conference.",
+      "additionalProperties": true
+    },
+    "listen": {
+      "type": "object",
+      "description": "Audio streaming configuration for the conference.",
+      "additionalProperties": true
+    },
+    "distributeDtmf": {
+      "type": "boolean",
+      "description": "If true, DTMF events from this participant are distributed to all other participants."
+    }
+  },
+  "required": [
+    "name"
+  ],
+  "examples": [
+    {
+      "verb": "conference",
+      "name": "team-standup",
+      "beep": true,
+      "startConferenceOnEnter": true,
+      "endConferenceOnExit": false,
+      "statusHook": "/conference-events"
+    }
+  ]
+}

jambonz_sdk/schema/verbs/config.schema.json

@@ -0,0 +1,221 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/verbs/config",
+  "minVersion": "0.9.6",
+  "title": "Config",
+  "description": "Sets session-level defaults for the call. Configures default TTS, STT, VAD, recording, streaming, and other session-wide settings. These defaults apply to all subsequent verbs unless overridden at the verb level. Typically the first verb in an application. Can be used multiple times during a call to change settings.",
+  "type": "object",
+  "properties": {
+    "verb": {
+      "const": "config",
+      "description": "The verb name."
+    },
+    "id": {
+      "type": "string",
+      "description": "An optional unique identifier for this verb instance."
+    },
+    "synthesizer": {
+      "$ref": "../components/synthesizer",
+      "description": "Default TTS configuration for the session."
+    },
+    "recognizer": {
+      "$ref": "../components/recognizer",
+      "description": "Default STT configuration for the session."
+    },
+    "bargeIn": {
+      "type": "object",
+      "description": "Default barge-in configuration. When enabled, callers can interrupt playing prompts with speech or DTMF.",
+      "properties": {
+        "enable": {
+          "type": "boolean"
+        },
+        "sticky": {
+          "type": "boolean",
+          "description": "If true, barge-in settings persist across verbs rather than resetting after each verb."
+        },
+        "actionHook": {
+          "$ref": "../components/actionHook"
+        },
+        "input": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "enum": [
+              "speech",
+              "digits"
+            ]
+          }
+        },
+        "minBargeinWordCount": {
+          "type": "number"
+        }
+      }
+    },
+    "ttsStream": {
+      "type": "object",
+      "description": "Default TTS streaming configuration for the session.",
+      "properties": {
+        "enable": {
+          "type": "boolean"
+        },
+        "synthesizer": {
+          "$ref": "../components/synthesizer"
+        }
+      }
+    },
+    "record": {
+      "type": "object",
+      "description": "Session-level call recording configuration.",
+      "additionalProperties": true
+    },
+    "listen": {
+      "type": "object",
+      "description": "Session-level audio streaming configuration defaults. Properties match the listen verb but no fields are required here.",
+      "additionalProperties": true
+    },
+    "stream": {
+      "type": "object",
+      "description": "Session-level audio streaming configuration defaults. Alias for 'listen'.",
+      "additionalProperties": true
+    },
+    "transcribe": {
+      "type": "object",
+      "description": "Session-level transcription configuration defaults.",
+      "additionalProperties": true
+    },
+    "amd": {
+      "$ref": "../components/amd",
+      "description": "Session-level answering machine detection configuration."
+    },
+    "fillerNoise": {
+      "$ref": "../components/fillerNoise",
+      "description": "Default filler noise configuration for the session."
+    },
+    "vad": {
+      "$ref": "../components/vad",
+      "description": "Default voice activity detection configuration for the session."
+    },
+    "notifyEvents": {
+      "type": "boolean",
+      "description": "If true, send call events (e.g. DTMF, call status changes) to the application via the status webhook."
+    },
+    "notifySttLatency": {
+      "type": "boolean",
+      "description": "If true, include STT latency measurements in webhook payloads."
+    },
+    "reset": {
+      "oneOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      ],
+      "description": "Reset specific session-level settings to their defaults. Pass a setting name or array of setting names to reset."
+    },
+    "onHoldMusic": {
+      "type": "string",
+      "format": "uri",
+      "description": "URL of an audio file to play when the call is placed on hold."
+    },
+    "actionHookDelayAction": {
+      "$ref": "../components/actionHookDelayAction",
+      "description": "Default configuration for handling slow webhook responses."
+    },
+    "sipRequestWithinDialogHook": {
+      "$ref": "../components/actionHook",
+      "description": "A webhook to invoke when a SIP request (e.g. INFO, NOTIFY) is received within the dialog."
+    },
+    "boostAudioSignal": {
+      "oneOf": [
+        {
+          "type": "number"
+        },
+        {
+          "type": "string"
+        }
+      ],
+      "description": "Boost (or attenuate) the audio signal in dB for the session."
+    },
+    "referHook": {
+      "$ref": "../components/actionHook",
+      "description": "A webhook to invoke when a SIP REFER request is received."
+    },
+    "earlyMedia": {
+      "type": "boolean",
+      "description": "If true, allow early media (audio before call answer) for the session."
+    },
+    "autoStreamTts": {
+      "type": "boolean",
+      "description": "If true, automatically use streaming TTS for all 'say' verbs in the session."
+    },
+    "disableTtsCache": {
+      "type": "boolean",
+      "description": "If true, disable TTS caching for the session."
+    },
+    "trackTtsPlayout": {
+      "type": "boolean",
+      "description": "If true, report the actual text spoken via TTS. Requires a TTS vendor that supports alignment data (e.g. ElevenLabs). On each utterance completion or interruption, a tts_spoken event is sent to the '/streaming-event' endpoint with fields: 'text' (string — the text actually spoken) and 'bargein' (boolean — true if the user interrupted before TTS finished). See the tts-streaming-event callback schema for full details."
+    },
+    "noiseIsolation": {
+      "type": "object",
+      "description": "Noise isolation configuration to reduce background noise on call audio. Defaults to filtering inbound (caller) audio; can also filter outbound audio via the direction option.",
+      "properties": {
+        "enable": {
+          "type": "boolean"
+        },
+        "vendor": {
+          "type": "string"
+        },
+        "level": {
+          "type": "number"
+        },
+        "model": {
+          "type": "string"
+        }
+      }
+    },
+    "turnTaking": {
+      "type": "object",
+      "description": "Turn-taking detection configuration for conversational AI applications.",
+      "properties": {
+        "enable": {
+          "type": "boolean"
+        },
+        "vendor": {
+          "type": "string"
+        },
+        "threshold": {
+          "type": "number"
+        },
+        "model": {
+          "type": "string"
+        }
+      }
+    }
+  },
+  "required": [],
+  "examples": [
+    {
+      "verb": "config",
+      "synthesizer": {
+        "vendor": "elevenlabs",
+        "voice": "Rachel",
+        "language": "en-US"
+      },
+      "recognizer": {
+        "vendor": "deepgram",
+        "language": "en-US"
+      },
+      "fillerNoise": {
+        "enable": true,
+        "url": "https://example.com/sounds/typing.wav",
+        "startDelaySecs": 2
+      }
+    }
+  ]
+}

jambonz_sdk/schema/verbs/deepgram_s2s.schema.json

@@ -0,0 +1,81 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/verbs/deepgram_s2s",
+  "minVersion": "10.1.0",
+  "title": "Deepgram S2S",
+  "description": "Shortcut for 'llm' with vendor automatically set to 'deepgram'. Connects the caller to a Deepgram model for real-time speech-to-speech voice conversation.",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "../components/llm-base"
+    }
+  ],
+  "properties": {
+    "verb": {
+      "const": "deepgram_s2s",
+      "description": "The verb name."
+    },
+    "vendor": {
+      "type": "string",
+      "const": "deepgram",
+      "description": "The LLM vendor (always 'deepgram' for this shortcut)."
+    },
+    "llmOptions": {
+      "type": "object",
+      "description": "IMPORTANT: Deepgram does NOT use a 'messages' array. The llmOptions must contain a 'Settings' object with 'agent.think' (LLM provider, model, and prompt) and 'agent.speak' (TTS provider and voice model). The system prompt goes in Settings.agent.think.prompt, NOT in messages.",
+      "additionalProperties": true,
+      "examples": [
+        {
+          "Settings": {
+            "agent": {
+              "think": {
+                "provider": {
+                  "type": "open_ai",
+                  "model": "gpt-4o"
+                },
+                "prompt": "You are a helpful voice assistant."
+              },
+              "speak": {
+                "provider": {
+                  "type": "deepgram",
+                  "model": "aura-2-thalia-en"
+                }
+              }
+            }
+          }
+        }
+      ]
+    }
+  },
+  "required": [
+    "llmOptions"
+  ],
+  "examples": [
+    {
+      "verb": "deepgram_s2s",
+      "auth": {
+        "apiKey": "your-deepgram-api-key"
+      },
+      "llmOptions": {
+        "Settings": {
+          "agent": {
+            "think": {
+              "provider": {
+                "type": "open_ai",
+                "model": "gpt-4o"
+              },
+              "prompt": "You are a helpful voice assistant."
+            },
+            "speak": {
+              "provider": {
+                "type": "deepgram",
+                "model": "aura-2-thalia-en"
+              }
+            }
+          }
+        }
+      },
+      "actionHook": "/s2s-complete"
+    }
+  ]
+}

jambonz_sdk/schema/verbs/dequeue.schema.json

@@ -0,0 +1,51 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/verbs/dequeue",
+  "minVersion": "0.9.6",
+  "title": "Dequeue",
+  "description": "Removes a caller from a named queue and bridges them to the current call. Typically used by an agent or operator call flow to connect with the next waiting caller.",
+  "type": "object",
+  "properties": {
+    "verb": {
+      "const": "dequeue"
+    },
+    "id": {
+      "type": "string",
+      "description": "An optional unique identifier for this verb instance."
+    },
+    "name": {
+      "type": "string",
+      "description": "The name of the queue to dequeue from.",
+      "examples": [
+        "support",
+        "sales"
+      ]
+    },
+    "actionHook": {
+      "$ref": "../components/actionHook",
+      "description": "A webhook invoked when the dequeued call ends."
+    },
+    "timeout": {
+      "type": "number",
+      "description": "Time in seconds to wait for a caller to be available in the queue."
+    },
+    "beep": {
+      "type": "boolean",
+      "description": "If true, play a beep when the calls are connected."
+    },
+    "callSid": {
+      "type": "string",
+      "description": "Dequeue a specific call by its call SID, rather than the next caller in line."
+    }
+  },
+  "required": [
+    "name"
+  ],
+  "examples": [
+    {
+      "verb": "dequeue",
+      "name": "support",
+      "beep": true
+    }
+  ]
+}