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

jambonz_sdk/schema/callbacks/gather.schema.json

@@ -0,0 +1,60 @@
+{
+  "$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
+}

jambonz_sdk/schema/callbacks/listen.schema.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/callbacks/listen",
+  "title": "Listen ActionHook Payload",
+  "description": "Payload sent to the listen verb's actionHook when the listen verb completes.",
+  "allOf": [
+    { "$ref": "base" }
+  ],
+  "type": "object",
+  "properties": {
+    "dial_call_duration": {
+      "type": "integer",
+      "description": "Duration of the listen session in seconds, present if recording was active."
+    },
+    "digits": {
+      "type": "string",
+      "description": "DTMF digit that ended the listen, present if finishOnKey was configured and pressed."
+    }
+  },
+  "additionalProperties": true
+}

jambonz_sdk/schema/callbacks/llm.schema.json

@@ -0,0 +1,30 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/callbacks/llm",
+  "title": "LLM ActionHook Payload",
+  "description": "Payload sent to the llm verb's actionHook when the LLM session ends. Applies to all LLM providers (OpenAI, Google, ElevenLabs, Ultravox, and generic voice agents).",
+  "allOf": [
+    { "$ref": "base" }
+  ],
+  "type": "object",
+  "properties": {
+    "completion_reason": {
+      "type": "string",
+      "enum": [
+        "normal conversation end",
+        "connection failure",
+        "disconnect from remote end",
+        "server failure",
+        "server error",
+        "client error calling function",
+        "client error calling mcp function"
+      ],
+      "description": "Reason the LLM session ended."
+    },
+    "error": {
+      "description": "Error details, present when completion_reason indicates a failure."
+    }
+  },
+  "required": ["completion_reason"],
+  "additionalProperties": true
+}

jambonz_sdk/schema/callbacks/message.schema.json

@@ -0,0 +1,35 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/callbacks/message",
+  "title": "Message ActionHook Payload",
+  "description": "Payload sent to the message verb's actionHook with the delivery status of an outbound SMS.",
+  "allOf": [
+    { "$ref": "base" }
+  ],
+  "type": "object",
+  "properties": {
+    "message_sid": {
+      "type": "string",
+      "description": "Unique identifier for the message."
+    },
+    "message_status": {
+      "type": "string",
+      "enum": ["success", "failure", "no carriers", "smpp configuration error", "system error"],
+      "description": "Delivery status of the message."
+    },
+    "carrier": {
+      "type": "string",
+      "description": "Name of the carrier used to send the message. Present on success or carrier-level failure."
+    },
+    "carrier_message_id": {
+      "type": "string",
+      "description": "Message ID returned by the carrier. Present on success or carrier-level failure."
+    },
+    "message_failure_reason": {
+      "type": "string",
+      "description": "Reason for failure. Present when message_status is 'failure' or 'system error'."
+    }
+  },
+  "required": ["message_sid", "message_status"],
+  "additionalProperties": true
+}

jambonz_sdk/schema/callbacks/pipeline-turn.schema.json

@@ -0,0 +1,109 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/callbacks/pipeline-turn",
+  "title": "Pipeline EventHook Events",
+  "description": "Events sent to the pipeline verb's eventHook during a conversation. These are sent as 'pipeline:event' messages over the WebSocket connection.",
+  "type": "object",
+  "oneOf": [
+    {
+      "properties": {
+        "type": {
+          "const": "turn_end",
+          "description": "Sent at the end of each conversational turn."
+        },
+        "transcript": {
+          "type": "string",
+          "description": "The user's final speech-to-text transcript for this turn."
+        },
+        "response": {
+          "type": "string",
+          "description": "The assistant's text response for this turn. May be trimmed to what was actually spoken if the turn was interrupted and alignment tracking is enabled."
+        },
+        "interrupted": {
+          "type": "boolean",
+          "description": "True if the user interrupted the assistant before it finished speaking.",
+          "default": false
+        },
+        "latency": {
+          "type": "object",
+          "description": "Latency metrics for this turn, all in milliseconds. Fields are absent when not applicable.",
+          "properties": {
+            "transcriber_latency": {
+              "type": "integer",
+              "description": "STT processing latency: time from user stops talking until final transcript received, in milliseconds."
+            },
+            "turn_detection_latency": {
+              "type": "integer",
+              "description": "Additional wait after final transcript for end-of-turn detection, in milliseconds. Absent when EOT fires before or with the transcript."
+            },
+            "model_latency": {
+              "type": "integer",
+              "description": "LLM latency: time spent waiting for the first LLM token after the system is ready to prompt, in milliseconds. Absent on a preflight hit."
+            },
+            "voice_latency": {
+              "type": "integer",
+              "description": "TTS engine latency: time from first text sent to the TTS engine until first audio received back, in milliseconds."
+            },
+            "preflight": {
+              "type": "object",
+              "description": "Early generation (preflight) metrics. Only present when earlyGeneration is enabled.",
+              "properties": {
+                "result": {
+                  "type": "string",
+                  "enum": ["hit", "miss", "pending"],
+                  "description": "Whether the speculative preflight transcript matched the final transcript ('hit'), did not match ('miss'), or was still in progress ('pending')."
+                },
+                "tokens": {
+                  "type": "integer",
+                  "description": "Number of preflight tokens that were buffered. Only present on a 'hit'."
+                }
+              },
+              "additionalProperties": false
+            }
+          },
+          "additionalProperties": false
+        }
+      },
+      "required": ["type", "transcript", "response", "interrupted", "latency"],
+      "additionalProperties": false
+    },
+    {
+      "properties": {
+        "type": {
+          "const": "user_transcript",
+          "description": "Sent when the user's final transcript is available and the system is proceeding to prompt the LLM. This indicates the end of the user's speech input for the current turn."
+        },
+        "transcript": {
+          "type": "string",
+          "description": "The user's final speech-to-text transcript."
+        }
+      },
+      "required": ["type", "transcript"],
+      "additionalProperties": false
+    },
+    {
+      "properties": {
+        "type": {
+          "const": "agent_response",
+          "description": "Sent when the LLM has finished generating its response for the current turn. Contains the complete response text."
+        },
+        "response": {
+          "type": "string",
+          "description": "The assistant's complete text response."
+        }
+      },
+      "required": ["type", "response"],
+      "additionalProperties": false
+    },
+    {
+      "properties": {
+        "type": {
+          "const": "user_interruption",
+          "description": "Sent when the user barges in (interrupts) while the assistant is speaking. This event has no additional data."
+        }
+      },
+      "required": ["type"],
+      "additionalProperties": false
+    }
+  ]
+}

jambonz_sdk/schema/callbacks/play.schema.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/callbacks/play",
+  "title": "Play ActionHook Payload",
+  "description": "Payload sent to the play verb's actionHook when playback completes or fails.",
+  "allOf": [
+    { "$ref": "base" }
+  ],
+  "type": "object",
+  "properties": {
+    "reason": {
+      "type": "string",
+      "enum": ["playCompleted", "playFailed"],
+      "description": "Outcome of playback. 'playCompleted' on success, 'playFailed' on file-not-found or other error."
+    },
+    "playback_seconds": {
+      "type": "integer",
+      "description": "Total playback duration in seconds. Present when reason is 'playCompleted'."
+    },
+    "playback_milliseconds": {
+      "type": "integer",
+      "description": "Total playback duration in milliseconds. Present when reason is 'playCompleted'."
+    },
+    "playback_last_offset_pos": {
+      "type": "string",
+      "description": "Last offset position in the audio stream. Present when reason is 'playCompleted'."
+    },
+    "status": {
+      "type": "string",
+      "enum": ["fail"],
+      "description": "Set to 'fail' when playback failed (e.g. file not found)."
+    }
+  },
+  "required": ["reason"],
+  "additionalProperties": true
+}

jambonz_sdk/schema/callbacks/session-new.schema.json

@@ -0,0 +1,143 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/callbacks/session-new",
+  "title": "Session:new Payload",
+  "description": "Payload delivered when a new call arrives. For webhook apps this is the initial POST body; for WebSocket apps it is the `data` property of the first `session:new` message. In the @jambonz/sdk WebSocket transport, this data is available as `session.data`.",
+  "allOf": [
+    { "$ref": "base" }
+  ],
+  "type": "object",
+  "properties": {
+    "caller_name": {
+      "type": "string",
+      "description": "Caller display name from the SIP From header."
+    },
+    "caller_id": {
+      "type": "string",
+      "description": "Caller ID value (phone number or SIP user)."
+    },
+    "service_provider_sid": {
+      "type": "string",
+      "description": "Service provider identifier, if applicable."
+    },
+    "parent_call_sid": {
+      "type": "string",
+      "description": "Call SID of the parent call, present when this session was created via the REST API dial (adulting) or when an outbound call leg is promoted to its own session."
+    },
+    "fs_sip_address": {
+      "type": "string",
+      "description": "Internal SIP address of the FreeSWITCH media server handling this call."
+    },
+    "fs_public_ip": {
+      "type": "string",
+      "description": "Public IP address of the FreeSWITCH media server, if available."
+    },
+    "sip": {
+      "type": "object",
+      "description": "The raw SIP INVITE message (drachtio SipRequest object, serialized). Only present for WebSocket and HTTP POST transports (not for HTTP GET). See https://drachtio.org/api#sip-request for the full drachtio SipRequest API.",
+      "properties": {
+        "headers": {
+          "type": "object",
+          "description": "SIP headers from the INVITE as key-value pairs. Custom headers (X-* headers) from the originating carrier or SIP client are included here. Standard SIP headers like From, To, Contact, Call-ID, Via, etc. are also present.",
+          "additionalProperties": { "type": "string" },
+          "examples": [
+            {
+              "X-Authenticated-User": "retell@sip.example.com",
+              "X-Override-Number": "+15551234567",
+              "From": "<sip:+15083084809@10.0.0.1>;tag=abc123",
+              "To": "<sip:+15083728299@jambonz.cloud>",
+              "Call-ID": "abc123@10.0.0.1"
+            }
+          ]
+        },
+        "body": {
+          "type": "string",
+          "description": "SIP message body (typically SDP for INVITE)."
+        },
+        "method": {
+          "type": "string",
+          "description": "SIP method (always 'INVITE' for session:new)."
+        },
+        "uri": {
+          "type": "string",
+          "description": "Request-URI from the SIP INVITE."
+        },
+        "calledNumber": {
+          "type": "string",
+          "description": "Phone number extracted from the Request-URI."
+        },
+        "callingNumber": {
+          "type": "string",
+          "description": "Calling phone number extracted from P-Asserted-Identity or From header."
+        },
+        "type": {
+          "type": "string",
+          "enum": ["request"],
+          "description": "Always 'request' for an incoming INVITE."
+        },
+        "source": {
+          "type": "string",
+          "enum": ["network", "application"],
+          "description": "Origin of the SIP message."
+        },
+        "source_address": {
+          "type": "string",
+          "description": "IP address of the sender."
+        },
+        "source_port": {
+          "type": ["string", "integer"],
+          "description": "Port of the sender."
+        },
+        "protocol": {
+          "type": "string",
+          "description": "Transport protocol (e.g. 'udp', 'tcp', 'tls', 'wss')."
+        },
+        "payload": {
+          "type": "array",
+          "description": "Message body organized into parts; useful for multipart content."
+        }
+      }
+    },
+    "env_vars": {
+      "type": "object",
+      "description": "Application environment variables configured in the jambonz portal. These are the key-value pairs defined in the application's environment variable schema. In the @jambonz/sdk, access via `session.data.env_vars`.",
+      "additionalProperties": true,
+      "examples": [
+        {
+          "RETELL_TRUNK_NAME": "retell-hosted",
+          "PSTN_TRUNK_NAME": "my-carrier",
+          "DEFAULT_COUNTRY": "US"
+        }
+      ]
+    },
+    "defaults": {
+      "type": "object",
+      "description": "Default speech settings for the account (synthesizer and recognizer defaults).",
+      "properties": {
+        "synthesizer": {
+          "type": "object",
+          "description": "Default TTS settings.",
+          "properties": {
+            "vendor": { "type": "string" },
+            "language": { "type": "string" },
+            "voice": { "type": "string" }
+          }
+        },
+        "recognizer": {
+          "type": "object",
+          "description": "Default STT settings.",
+          "properties": {
+            "vendor": { "type": "string" },
+            "language": { "type": "string" }
+          }
+        }
+      }
+    },
+    "customerData": {
+      "type": "object",
+      "description": "Custom data attached to the call via the REST API when creating an outbound call. Preserved as-is (not snake-cased).",
+      "additionalProperties": true
+    }
+  },
+  "additionalProperties": true
+}

jambonz_sdk/schema/callbacks/session-reconnect.schema.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/callbacks/session-reconnect",
+  "title": "Session:reconnect Payload",
+  "description": "Payload delivered when a WebSocket client reconnects after a disconnection. The payload is identical to the original session:new payload — it is cached from the initial session setup and replayed on reconnect. This allows the application to restore state without needing to re-fetch call details.",
+  "allOf": [
+    { "$ref": "session-new" }
+  ]
+}

jambonz_sdk/schema/callbacks/session-redirect.schema.json

@@ -0,0 +1,38 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/callbacks/session-redirect",
+  "title": "Session:redirect Payload",
+  "description": "Payload delivered when a redirect verb transfers the call to a new application or WebSocket endpoint. Contains only the current call state information — unlike session:new, it does not include defaults, env_vars, sip, or service_provider_sid.",
+  "allOf": [
+    { "$ref": "base" }
+  ],
+  "type": "object",
+  "properties": {
+    "caller_name": {
+      "type": "string",
+      "description": "Caller display name from the SIP From header."
+    },
+    "caller_id": {
+      "type": "string",
+      "description": "Caller ID value (phone number or SIP user)."
+    },
+    "parent_call_sid": {
+      "type": "string",
+      "description": "Call SID of the parent call, if applicable."
+    },
+    "fs_sip_address": {
+      "type": "string",
+      "description": "Internal SIP address of the FreeSWITCH media server handling this call."
+    },
+    "fs_public_ip": {
+      "type": "string",
+      "description": "Public IP address of the FreeSWITCH media server, if available."
+    },
+    "customerData": {
+      "type": "object",
+      "description": "Custom data attached to the call via the REST API. Preserved as-is (not snake-cased).",
+      "additionalProperties": true
+    }
+  },
+  "additionalProperties": true
+}

jambonz_sdk/schema/callbacks/sip-refer-event.schema.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/callbacks/sip-refer-event",
+  "title": "SIP Refer EventHook Payload",
+  "description": "Payload sent to the sip-refer eventHook when a SIP NOTIFY is received with transfer status updates.",
+  "type": "object",
+  "properties": {
+    "event": {
+      "type": "string",
+      "const": "transfer-status",
+      "description": "Event type — always 'transfer-status' for REFER notifications."
+    },
+    "call_status": {
+      "type": "integer",
+      "description": "SIP status code from the NOTIFY sipfrag body (e.g. 100 for trying, 180 for ringing, 200 for success)."
+    }
+  },
+  "required": ["event", "call_status"],
+  "additionalProperties": true
+}

jambonz_sdk/schema/callbacks/sip-refer.schema.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/callbacks/sip-refer",
+  "title": "SipRefer ActionHook Payload",
+  "description": "Payload sent to the sip-refer verb's actionHook when the REFER completes. Sent once the REFER response is received, or after a final NOTIFY arrives.",
+  "allOf": [
+    { "$ref": "base" }
+  ],
+  "type": "object",
+  "properties": {
+    "refer_status": {
+      "type": "integer",
+      "description": "SIP status code from the REFER response (e.g. 202 for accepted, 4xx/5xx for failure)."
+    },
+    "final_referred_call_status": {
+      "type": "integer",
+      "description": "Final SIP status of the referred call, extracted from a NOTIFY sipfrag. Present only when the REFER was accepted (202) and a final NOTIFY was received."
+    }
+  },
+  "required": ["refer_status"],
+  "additionalProperties": true
+}

jambonz_sdk/schema/callbacks/sip-request.schema.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/callbacks/sip-request",
+  "title": "SipRequest ActionHook Payload",
+  "description": "Payload sent to the sip-request verb's actionHook after a SIP request (e.g. INFO, NOTIFY) is sent and a response is received.",
+  "allOf": [
+    { "$ref": "base" }
+  ],
+  "type": "object",
+  "properties": {
+    "result": {
+      "type": "string",
+      "enum": ["success", "failed"],
+      "description": "Whether the SIP request succeeded or failed."
+    },
+    "sip_status": {
+      "type": "integer",
+      "description": "SIP response status code. Present when result is 'success'."
+    },
+    "err": {
+      "type": "string",
+      "description": "Error message. Present when result is 'failed'."
+    }
+  },
+  "required": ["result"],
+  "additionalProperties": true
+}

jambonz_sdk/schema/callbacks/transcribe-translation.schema.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/callbacks/transcribe-translation",
+  "title": "Transcribe TranslationHook Payload",
+  "description": "Payload sent to the translationHook when a translation result is received.",
+  "allOf": [
+    { "$ref": "base" }
+  ],
+  "type": "object",
+  "properties": {
+    "translation": {
+      "type": "object",
+      "description": "Translation result data.",
+      "properties": {
+        "channel": { "type": "integer", "description": "Audio channel number (1 or 2)." },
+        "language": { "type": "string", "description": "Target language code for the translation." },
+        "translation": { "type": "string", "description": "The translated text." }
+      },
+      "required": ["channel", "language", "translation"]
+    }
+  },
+  "required": ["translation"],
+  "additionalProperties": true
+}

jambonz_sdk/schema/callbacks/transcribe.schema.json

@@ -0,0 +1,46 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/callbacks/transcribe",
+  "title": "Transcribe TranscriptionHook Payload",
+  "description": "Payload sent to the transcriptionHook when a transcription result is received from the STT engine.",
+  "allOf": [
+    { "$ref": "base" }
+  ],
+  "type": "object",
+  "properties": {
+    "speech": {
+      "type": "object",
+      "description": "Speech recognition results, present when the STT engine returns alternatives.",
+      "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."
+        }
+      }
+    },
+    "speech_event": {
+      "type": "object",
+      "description": "Speech event data, present when the STT engine returns a typed event (e.g. end of utterance).",
+      "properties": {
+        "type": { "type": "string", "description": "Event type from the STT vendor." }
+      },
+      "additionalProperties": true
+    },
+    "stt_latency_ms": { "type": "string", "description": "STT latency in milliseconds." },
+    "stt_talkspurts": { "type": "string", "description": "JSON-encoded array of talkspurt timing data." },
+    "stt_start_time": { "type": "string", "description": "STT recognition start time." },
+    "stt_stop_time": { "type": "string", "description": "STT recognition stop time." },
+    "stt_usage": { "description": "STT usage data from the vendor." }
+  },
+  "additionalProperties": true
+}