@jambonz/schema 0.1.1

package/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
+    }
+  ]
+}

package/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
+}

package/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
+}

package/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" }
+  ]
+}

package/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
+}

package/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
+}

package/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
+}

package/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
+}

package/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
+}

package/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
+}

package/callbacks/tts-streaming-event.schema.json

@@ -0,0 +1,77 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/callbacks/tts-streaming-event",
+  "title": "TTS Streaming Event",
+  "description": "Events sent to the '/streaming-event' WebSocket endpoint during TTS streaming. These are sent as 'tts:streaming-event' messages. The tts_spoken event is only sent when trackTtsPlayout is enabled via the config verb.",
+  "type": "object",
+  "oneOf": [
+    {
+      "properties": {
+        "event_type": {
+          "const": "stream_open",
+          "description": "The TTS streaming connection has been established."
+        }
+      },
+      "required": ["event_type"],
+      "additionalProperties": false
+    },
+    {
+      "properties": {
+        "event_type": {
+          "const": "stream_closed",
+          "description": "The TTS streaming connection has been closed."
+        }
+      },
+      "required": ["event_type"],
+      "additionalProperties": false
+    },
+    {
+      "properties": {
+        "event_type": {
+          "const": "stream_paused",
+          "description": "TTS streaming has been paused."
+        }
+      },
+      "required": ["event_type"],
+      "additionalProperties": false
+    },
+    {
+      "properties": {
+        "event_type": {
+          "const": "stream_resumed",
+          "description": "TTS streaming has been resumed."
+        }
+      },
+      "required": ["event_type"],
+      "additionalProperties": false
+    },
+    {
+      "properties": {
+        "event_type": {
+          "const": "user_interruption",
+          "description": "The user interrupted (barged in) during TTS playout, causing the stream to be cleared."
+        }
+      },
+      "required": ["event_type"],
+      "additionalProperties": false
+    },
+    {
+      "properties": {
+        "event_type": {
+          "const": "tts_spoken",
+          "description": "Reports the actual text that was spoken via TTS. Sent on utterance completion or when the user barges in. Only sent when trackTtsPlayout is enabled via the config verb. Requires a TTS vendor that supports alignment data (e.g. ElevenLabs)."
+        },
+        "text": {
+          "type": "string",
+          "description": "The text that was actually spoken before completion or interruption."
+        },
+        "bargein": {
+          "type": "boolean",
+          "description": "True if the user barged in (interrupted) before the TTS finished speaking. False if the utterance completed normally."
+        }
+      },
+      "required": ["event_type", "text", "bargein"],
+      "additionalProperties": false
+    }
+  ]
+}

package/callbacks/verb-status.schema.json

@@ -0,0 +1,57 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/callbacks/verb-status",
+  "title": "Verb Status Event",
+  "description": "Real-time verb lifecycle events sent over WebSocket when notifyEvents is enabled on the session. These are informational — no response is expected.",
+  "type": "object",
+  "properties": {
+    "event": {
+      "type": "string",
+      "enum": [
+        "starting",
+        "finished",
+        "start-playback",
+        "stop-playback",
+        "kill-playback",
+        "dtmf-bargein-detected",
+        "speech-bargein-detected",
+        "synthesized-audio"
+      ],
+      "description": "The verb lifecycle event."
+    },
+    "verb": {
+      "type": "string",
+      "description": "The verb name (e.g. 'say', 'play', 'gather'). Present on synthesized-audio, start-playback, stop-playback, kill-playback, and dtmf/speech-bargein events."
+    },
+    "name": {
+      "type": "string",
+      "description": "The verb name. Present on 'starting' and 'finished' events (these use 'name' instead of 'verb')."
+    },
+    "id": {
+      "type": "string",
+      "description": "The verb instance id, if one was assigned by the application."
+    },
+    "vendor": {
+      "type": "string",
+      "description": "TTS vendor name. Present on synthesized-audio events."
+    },
+    "language": {
+      "type": "string",
+      "description": "TTS language code. Present on synthesized-audio events."
+    },
+    "characters": {
+      "type": "integer",
+      "description": "Number of characters synthesized. Present on synthesized-audio events when not served from cache."
+    },
+    "elapsed_time": {
+      "type": "number",
+      "description": "TTS round-trip time in milliseconds. Present on synthesized-audio events when not served from cache."
+    },
+    "served_from_cache": {
+      "type": "boolean",
+      "description": "Whether the TTS audio was served from cache. Present on synthesized-audio events."
+    }
+  },
+  "required": ["event"],
+  "additionalProperties": true
+}

package/components/actionHook.schema.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/components/actionHook",
+  "title": "ActionHook",
+  "description": "A webhook or websocket callback that jambonz invokes when a verb completes. Reports verb results (e.g. speech recognition from 'gather', dial outcome) and receives the next verbs to execute. In webhook mode: jambonz POSTs to this URL and the HTTP response body is the next verb array. In WebSocket mode: this value becomes an event name emitted on the session — bind session.on('/hookName', (evt) => {...}) and respond with session.reply() (NOT session.send()). The callback payload always includes 'reason' plus verb-specific fields (e.g. 'speech', 'digits' for gather). Can be a simple URL/path string or an object with additional options.",
+  "oneOf": [
+    {
+      "type": "string",
+      "format": "uri",
+      "description": "A URL to invoke. For webhook applications this is an HTTP(S) URL. For websocket applications this is typically a relative path or event name.",
+      "examples": ["https://myapp.example.com/gather-result", "/gather-result"]
+    },
+    {
+      "type": "object",
+      "description": "A hook specification with URL and additional options.",
+      "properties": {
+        "url": {
+          "type": "string",
+          "format": "uri",
+          "description": "The URL to invoke."
+        },
+        "method": {
+          "type": "string",
+          "description": "The HTTP method to use. Only applies to webhook applications.",
+          "enum": ["GET", "POST"],
+          "default": "POST"
+        },
+        "basicAuth": {
+          "$ref": "auth",
+          "description": "Basic authentication credentials to include in the request."
+        }
+      },
+      "required": ["url"]
+    }
+  ]
+}