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

jambonz_sdk/schema/verbs/dial.schema.json

@@ -0,0 +1,200 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/verbs/dial",
+  "minVersion": "0.9.6",
+  "title": "Dial",
+  "description": "Initiates an outbound call to one or more targets and bridges the caller to the first target that answers. Targets can be phone numbers (PSTN), SIP endpoints, registered users, or Microsoft Teams users. Supports simultaneous ringing, call screening, recording, and DTMF capture during the bridged call.",
+  "type": "object",
+  "properties": {
+    "verb": {
+      "const": "dial",
+      "description": "The verb name."
+    },
+    "id": {
+      "type": "string",
+      "description": "An optional unique identifier for this verb instance."
+    },
+    "target": {
+      "type": "array",
+      "items": {
+        "$ref": "../components/target"
+      },
+      "description": "One or more call targets to dial. If multiple targets are specified, they are rung simultaneously and the first to answer is connected. The rest are canceled.",
+      "minItems": 1
+    },
+    "actionHook": {
+      "$ref": "../components/actionHook",
+      "description": "A webhook invoked when the dialed call ends. Receives call disposition details (duration, who hung up, etc.) and should return the next verbs to execute."
+    },
+    "onHoldHook": {
+      "$ref": "../components/actionHook",
+      "description": "A webhook invoked when the call is placed on hold. Should return verbs to execute (e.g. play hold music) while the caller is holding."
+    },
+    "answerOnBridge": {
+      "type": "boolean",
+      "description": "If true, delay answering the inbound call until the outbound leg is answered. This allows the caller to hear ringing until the target picks up, and avoids billing the caller for unanswered outbound attempts."
+    },
+    "callerId": {
+      "type": "string",
+      "description": "The caller ID (phone number) to present on the outbound call. Overrides the default caller ID.",
+      "examples": [
+        "+15085551212"
+      ]
+    },
+    "callerName": {
+      "type": "string",
+      "description": "The caller display name to present on the outbound call."
+    },
+    "confirmHook": {
+      "$ref": "../components/actionHook",
+      "description": "A webhook invoked when a target answers, before the call is bridged. Used for call screening — the webhook can return verbs (e.g. a 'say' prompt and 'gather') to confirm the callee wants to accept the call."
+    },
+    "referHook": {
+      "$ref": "../components/actionHook",
+      "description": "A webhook invoked when a SIP REFER is received on the bridged call. Allows handling call transfers initiated by the far end."
+    },
+    "dialMusic": {
+      "type": "string",
+      "format": "uri",
+      "description": "URL of an audio file to play to the caller while the outbound call is ringing. Replaces the default ringback tone."
+    },
+    "dtmfCapture": {
+      "oneOf": [
+        {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Array of DTMF patterns to capture on both call legs."
+        },
+        {
+          "type": "object",
+          "description": "Per-leg DTMF capture configuration with childCall and/or parentCall arrays.",
+          "additionalProperties": true
+        }
+      ],
+      "description": "Configuration for capturing DTMF digits during the bridged call. Can be a simple array of patterns (applied to both legs) or an object with childCall/parentCall arrays."
+    },
+    "dtmfHook": {
+      "$ref": "../components/actionHook",
+      "description": "A webhook invoked when a captured DTMF pattern is detected during the bridged call."
+    },
+    "headers": {
+      "type": "object",
+      "description": "Custom SIP headers to include on the outbound INVITE.",
+      "additionalProperties": {
+        "oneOf": [{ "type": "string" }, { "type": "number" }]
+      }
+    },
+    "anchorMedia": {
+      "type": "boolean",
+      "description": "If true, keep media anchored through the jambonz media server even if a direct media path is possible. Required for features like recording, listen, and DTMF capture during bridged calls."
+    },
+    "exitMediaPath": {
+      "type": "boolean",
+      "description": "If true, remove jambonz from the media path after the call is bridged. Reduces latency but disables mid-call features like recording and DTMF capture."
+    },
+    "boostAudioSignal": {
+      "oneOf": [
+        {
+          "type": "number"
+        },
+        {
+          "type": "string"
+        }
+      ],
+      "description": "Boost (or attenuate) the audio signal in dB. Positive values increase volume, negative values decrease it.",
+      "examples": [
+        6,
+        -3
+      ]
+    },
+    "listen": {
+      "type": "object",
+      "description": "Nested listen configuration for streaming audio of the bridged call.",
+      "additionalProperties": true
+    },
+    "stream": {
+      "type": "object",
+      "description": "Nested stream configuration for streaming audio of the bridged call. Alias for 'listen'.",
+      "additionalProperties": true
+    },
+    "transcribe": {
+      "type": "object",
+      "description": "Nested transcribe configuration for real-time transcription of the bridged call.",
+      "additionalProperties": true
+    },
+    "timeLimit": {
+      "type": "number",
+      "description": "Maximum duration in seconds for the bridged call. The call is automatically hung up when this limit is reached.",
+      "examples": [
+        3600
+      ]
+    },
+    "timeout": {
+      "type": "number",
+      "description": "Time in seconds to wait for the target to answer before giving up.",
+      "examples": [
+        30,
+        60
+      ]
+    },
+    "proxy": {
+      "type": "string",
+      "description": "A SIP proxy to route the outbound call through.",
+      "examples": [
+        "sip:proxy.example.com"
+      ]
+    },
+    "amd": {
+      "$ref": "../components/amd",
+      "description": "Answering machine detection configuration. When enabled, jambonz attempts to determine whether the call was answered by a human or a machine."
+    },
+    "dub": {
+      "type": "array",
+      "items": {
+        "$ref": "dub"
+      },
+      "description": "Nested dub verbs — audio dubbing configuration for mixing additional audio tracks into the bridged call."
+    },
+    "tag": {
+      "type": "object",
+      "description": "Arbitrary metadata to attach to this call leg. Included in subsequent webhook invocations and CDRs.",
+      "additionalProperties": true
+    },
+    "forwardPAI": {
+      "type": "boolean",
+      "description": "If true, forward the P-Asserted-Identity header from the inbound call to the outbound call."
+    }
+  },
+  "required": [
+    "target"
+  ],
+  "examples": [
+    {
+      "verb": "dial",
+      "target": [
+        {
+          "type": "phone",
+          "number": "+15085551212"
+        }
+      ],
+      "answerOnBridge": true,
+      "timeout": 30,
+      "actionHook": "/dial-complete"
+    },
+    {
+      "verb": "dial",
+      "target": [
+        {
+          "type": "sip",
+          "sipUri": "sip:alice@example.com"
+        },
+        {
+          "type": "sip",
+          "sipUri": "sip:bob@example.com"
+        }
+      ],
+      "confirmHook": "/screen-call",
+      "timeLimit": 3600
+    }
+  ]
+}

jambonz_sdk/schema/verbs/dialogflow.schema.json

@@ -0,0 +1,148 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/verbs/dialogflow",
+  "minVersion": "0.9.6",
+  "title": "Dialogflow",
+  "description": "Connects the caller to a Google Dialogflow agent for a voice conversation. Supports Dialogflow ES, CX, and CES models. The caller speaks and Dialogflow handles intent detection and response generation.",
+  "type": "object",
+  "properties": {
+    "verb": {
+      "const": "dialogflow",
+      "description": "The verb name."
+    },
+    "id": {
+      "type": "string",
+      "description": "An optional unique identifier for this verb instance."
+    },
+    "credentials": {
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": true
+        },
+        {
+          "type": "string"
+        }
+      ],
+      "description": "Google service account credentials as a JSON object or stringified JSON."
+    },
+    "project": {
+      "type": "string",
+      "description": "The Google Cloud project ID."
+    },
+    "agent": {
+      "type": "string",
+      "description": "The Dialogflow agent ID. Required for CX agents."
+    },
+    "environment": {
+      "type": "string",
+      "description": "The Dialogflow environment to use."
+    },
+    "region": {
+      "type": "string",
+      "description": "The Google Cloud region for the Dialogflow API endpoint."
+    },
+    "model": {
+      "type": "string",
+      "enum": [
+        "es",
+        "cx",
+        "ces"
+      ],
+      "description": "The Dialogflow model type: 'es' for Dialogflow ES, 'cx' for Dialogflow CX, 'ces' for Dialogflow CES."
+    },
+    "lang": {
+      "type": "string",
+      "description": "The language code for the conversation (e.g. 'en-US')."
+    },
+    "actionHook": {
+      "$ref": "../components/actionHook",
+      "description": "A webhook invoked when the Dialogflow session ends."
+    },
+    "eventHook": {
+      "$ref": "../components/actionHook",
+      "description": "A webhook invoked for Dialogflow events during the conversation."
+    },
+    "events": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "List of event types to receive via the eventHook."
+    },
+    "welcomeEvent": {
+      "type": "string",
+      "description": "A Dialogflow event to trigger at the start of the conversation (e.g. 'welcome')."
+    },
+    "welcomeEventParams": {
+      "type": "object",
+      "description": "Parameters to pass with the welcome event.",
+      "additionalProperties": true
+    },
+    "noInputTimeout": {
+      "type": "number",
+      "description": "Seconds to wait for caller input before triggering the no-input event."
+    },
+    "noInputEvent": {
+      "type": "string",
+      "description": "Dialogflow event to trigger when no input is received within the timeout."
+    },
+    "passDtmfAsTextInput": {
+      "type": "boolean",
+      "description": "If true, pass DTMF digits to Dialogflow as text input."
+    },
+    "thinkingMusic": {
+      "type": "string",
+      "description": "URL of an audio file to play while waiting for Dialogflow to respond."
+    },
+    "tts": {
+      "$ref": "../components/synthesizer",
+      "description": "TTS configuration for Dialogflow responses."
+    },
+    "bargein": {
+      "type": "boolean",
+      "description": "If true, allow the caller to interrupt Dialogflow responses with speech."
+    },
+    "queryInput": {
+      "type": "object",
+      "description": "Initial query input to send to Dialogflow.",
+      "properties": {
+        "text": {
+          "type": "string",
+          "description": "Text input."
+        },
+        "intent": {
+          "type": "string",
+          "description": "Intent to trigger."
+        },
+        "event": {
+          "type": "string",
+          "description": "Event to trigger."
+        },
+        "dtmf": {
+          "type": "string",
+          "description": "DTMF input."
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "required": [
+    "project",
+    "credentials",
+    "lang"
+  ],
+  "examples": [
+    {
+      "verb": "dialogflow",
+      "project": "my-gcp-project",
+      "credentials": "{\"type\": \"service_account\", \"project_id\": \"my-gcp-project\"}",
+      "lang": "en-US",
+      "model": "cx",
+      "agent": "my-agent-id",
+      "welcomeEvent": "welcome",
+      "actionHook": "/dialogflow-action",
+      "eventHook": "/dialogflow-event"
+    }
+  ]
+}

jambonz_sdk/schema/verbs/dtmf.schema.json

@@ -0,0 +1,49 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/verbs/dtmf",
+  "minVersion": "0.9.6",
+  "title": "DTMF",
+  "description": "Sends DTMF tones on the call. Used to interact with IVR systems on the far end, or to signal systems that respond to DTMF.",
+  "type": "object",
+  "properties": {
+    "verb": {
+      "const": "dtmf"
+    },
+    "id": {
+      "type": "string",
+      "description": "An optional unique identifier for this verb instance."
+    },
+    "dtmf": {
+      "type": "string",
+      "description": "The DTMF digits to send. Valid characters are 0-9, *, #, and A-D. Use 'w' for a 500ms pause between digits.",
+      "examples": [
+        "1234#",
+        "1w2w3",
+        "5551212"
+      ]
+    },
+    "duration": {
+      "type": "number",
+      "description": "Duration in milliseconds for each DTMF tone.",
+      "default": 500,
+      "examples": [
+        250,
+        500
+      ]
+    }
+  },
+  "required": [
+    "dtmf"
+  ],
+  "examples": [
+    {
+      "verb": "dtmf",
+      "dtmf": "1234#"
+    },
+    {
+      "verb": "dtmf",
+      "dtmf": "1w2w3w4",
+      "duration": 250
+    }
+  ]
+}

jambonz_sdk/schema/verbs/dub.schema.json

@@ -0,0 +1,103 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/verbs/dub",
+  "minVersion": "0.9.6",
+  "title": "Dub",
+  "description": "Manages audio dubbing tracks on a call. Allows adding, removing, and controlling auxiliary audio tracks that are mixed into the call audio. Used for background music, coaching whispers, or injecting audio from external sources.",
+  "type": "object",
+  "properties": {
+    "verb": {
+      "const": "dub"
+    },
+    "id": {
+      "type": "string",
+      "description": "An optional unique identifier for this verb instance."
+    },
+    "action": {
+      "type": "string",
+      "description": "The dubbing action to perform.",
+      "enum": [
+        "addTrack",
+        "removeTrack",
+        "silenceTrack",
+        "playOnTrack",
+        "sayOnTrack"
+      ]
+    },
+    "track": {
+      "type": "string",
+      "description": "The name of the audio track. Used to reference the track in subsequent dub actions.",
+      "examples": [
+        "background-music",
+        "coach-whisper"
+      ]
+    },
+    "play": {
+      "type": "string",
+      "format": "uri",
+      "description": "URL of an audio file to play on the track. Used with 'playOnTrack' action."
+    },
+    "say": {
+      "oneOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "object",
+          "additionalProperties": true
+        }
+      ],
+      "description": "Text to synthesize and play on the track. Used with 'sayOnTrack' action. Can be a string or a say configuration object."
+    },
+    "loop": {
+      "type": "boolean",
+      "description": "If true, loop the audio on the track continuously."
+    },
+    "gain": {
+      "oneOf": [
+        {
+          "type": "number"
+        },
+        {
+          "type": "string"
+        }
+      ],
+      "description": "Audio gain for the track in dB. Use negative values to reduce volume.",
+      "examples": [
+        -10,
+        0,
+        6
+      ]
+    }
+  },
+  "required": [
+    "action",
+    "track"
+  ],
+  "examples": [
+    {
+      "verb": "dub",
+      "action": "addTrack",
+      "track": "bgm"
+    },
+    {
+      "verb": "dub",
+      "action": "playOnTrack",
+      "track": "bgm",
+      "play": "https://example.com/music.mp3",
+      "loop": true,
+      "gain": -15
+    },
+    {
+      "verb": "dub",
+      "action": "sayOnTrack",
+      "track": "coach",
+      "say": "Ask about their budget"
+    },
+    {
+      "verb": "dub",
+      "action": "removeTrack",
+      "track": "bgm"
+    }
+  ]
+}

jambonz_sdk/schema/verbs/elevenlabs_s2s.schema.json

@@ -0,0 +1,81 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/verbs/elevenlabs_s2s",
+  "minVersion": "10.1.0",
+  "title": "ElevenLabs S2S",
+  "description": "Shortcut for 'llm' with vendor automatically set to 'elevenlabs'. Connects the caller to an ElevenLabs Conversational AI agent for real-time speech-to-speech voice conversation. Unlike other s2s vendors, ElevenLabs requires a pre-configured agent_id rather than a model and messages.",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "../components/llm-base"
+    }
+  ],
+  "properties": {
+    "verb": {
+      "const": "elevenlabs_s2s",
+      "description": "The verb name."
+    },
+    "vendor": {
+      "type": "string",
+      "const": "elevenlabs",
+      "description": "The LLM vendor (always 'elevenlabs' for this shortcut)."
+    },
+    "auth": {
+      "type": "object",
+      "description": "Authentication credentials for ElevenLabs. Requires agent_id; api_key is optional (if not provided, an unsigned URL is used).",
+      "properties": {
+        "agent_id": {
+          "type": "string",
+          "description": "The ElevenLabs Conversational AI agent ID. Required."
+        },
+        "api_key": {
+          "type": "string",
+          "description": "The ElevenLabs API key. Optional; when provided, a signed URL is used for the WebSocket connection."
+        }
+      },
+      "required": [
+        "agent_id"
+      ]
+    },
+    "llmOptions": {
+      "type": "object",
+      "description": "Options for the ElevenLabs conversation session.",
+      "properties": {
+        "conversation_initiation_client_data": {
+          "type": "object",
+          "description": "Optional data sent to the agent when the conversation starts.",
+          "additionalProperties": true
+        },
+        "input_sample_rate": {
+          "type": "integer",
+          "description": "Audio input sample rate in Hz.",
+          "default": 16000
+        },
+        "output_sample_rate": {
+          "type": "integer",
+          "description": "Audio output sample rate in Hz.",
+          "default": 16000
+        }
+      },
+      "additionalProperties": true
+    }
+  },
+  "required": [
+    "auth"
+  ],
+  "examples": [
+    {
+      "verb": "elevenlabs_s2s",
+      "auth": {
+        "agent_id": "your-elevenlabs-agent-id",
+        "api_key": "your-elevenlabs-api-key"
+      },
+      "llmOptions": {},
+      "actionHook": "/s2s-complete",
+      "eventHook": "/event",
+      "events": [
+        "all"
+      ]
+    }
+  ]
+}

jambonz_sdk/schema/verbs/enqueue.schema.json

@@ -0,0 +1,53 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/verbs/enqueue",
+  "minVersion": "0.9.6",
+  "title": "Enqueue",
+  "description": "Places the caller into a named call queue. While in the queue, the caller hears content returned by the waitHook (typically hold music or position announcements). The caller remains in the queue until dequeued by another call or process.",
+  "type": "object",
+  "properties": {
+    "verb": {
+      "const": "enqueue"
+    },
+    "id": {
+      "type": "string",
+      "description": "An optional unique identifier for this verb instance."
+    },
+    "name": {
+      "type": "string",
+      "description": "The name of the queue to place the caller in. Queues are created implicitly when first referenced.",
+      "examples": [
+        "support",
+        "sales"
+      ]
+    },
+    "actionHook": {
+      "$ref": "../components/actionHook",
+      "description": "A webhook invoked when the caller leaves the queue (either dequeued or hung up). Should return the next verbs to execute."
+    },
+    "waitHook": {
+      "$ref": "../components/actionHook",
+      "description": "A webhook invoked immediately when the caller enters the queue and periodically while waiting. Should return verbs to play to the caller (e.g. hold music, queue position announcements)."
+    },
+    "priority": {
+      "type": "number",
+      "description": "The priority of this caller in the queue. Lower numbers are higher priority and are dequeued first.",
+      "examples": [
+        1,
+        5,
+        10
+      ]
+    }
+  },
+  "required": [
+    "name"
+  ],
+  "examples": [
+    {
+      "verb": "enqueue",
+      "name": "support",
+      "waitHook": "/queue-wait",
+      "actionHook": "/queue-exit"
+    }
+  ]
+}