@jambonz/schema 0.1.1

package/callbacks/amd.schema.json

@@ -0,0 +1,50 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/callbacks/amd",
+  "title": "AMD ActionHook Payload",
+  "description": "Payload sent to the AMD actionHook when an answering machine detection event occurs. Multiple events may fire during a single call (e.g. amd_machine_detected followed by amd_machine_stopped_speaking or amd_tone_detected).",
+  "allOf": [{ "$ref": "base" }],
+  "type": "object",
+  "properties": {
+    "type": {
+      "type": "string",
+      "description": "The AMD event type. IMPORTANT: This field is 'type', NOT 'amd_type'.",
+      "enum": [
+        "amd_human_detected",
+        "amd_machine_detected",
+        "amd_no_speech_detected",
+        "amd_decision_timeout",
+        "amd_machine_stopped_speaking",
+        "amd_tone_detected",
+        "amd_tone_timeout",
+        "amd_error",
+        "amd_stopped"
+      ]
+    },
+    "reason": {
+      "type": "string",
+      "description": "Reason for the detection result (e.g. 'short greeting', 'long greeting', 'hint', 'digit count'). Present on amd_human_detected and amd_machine_detected events."
+    },
+    "greeting": {
+      "type": "string",
+      "description": "The transcribed greeting text. Present on amd_human_detected and amd_machine_detected events."
+    },
+    "hint": {
+      "type": "string",
+      "description": "The voicemail hint that matched, if detection was triggered by hint matching."
+    },
+    "language": {
+      "type": "string",
+      "description": "Language code from the transcription (e.g. 'en-US'). Present on amd_human_detected and amd_machine_detected events."
+    },
+    "frequency": {
+      "type": "number",
+      "description": "Frequency of the detected beep in Hz. Present on amd_tone_detected events."
+    },
+    "variance": {
+      "type": "number",
+      "description": "Frequency variance of the detected beep. Present on amd_tone_detected events."
+    }
+  },
+  "required": ["type"]
+}

package/callbacks/base.schema.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/callbacks/base",
+  "title": "ActionHook Base Payload",
+  "description": "Common fields present in every actionHook callback payload. All verb-specific callback schemas extend this base.",
+  "type": "object",
+  "properties": {
+    "call_sid": { "type": "string", "description": "Unique identifier for this call." },
+    "account_sid": { "type": "string", "description": "Account identifier." },
+    "application_sid": { "type": "string", "description": "Application identifier." },
+    "direction": { "type": "string", "enum": ["inbound", "outbound"], "description": "Call direction." },
+    "from": { "type": "string", "description": "Caller phone number or SIP URI." },
+    "to": { "type": "string", "description": "Called phone number or SIP URI." },
+    "call_id": { "type": "string", "description": "SIP Call-ID." },
+    "sbc_callid": { "type": "string", "description": "SBC-level Call-ID." },
+    "call_status": {
+      "type": "string",
+      "enum": ["trying", "ringing", "early-media", "in-progress", "completed", "failed", "busy", "no-answer", "queued"],
+      "description": "Current call state."
+    },
+    "sip_status": { "type": "integer", "description": "SIP response code (e.g. 200, 486)." },
+    "sip_reason": { "type": "string", "description": "SIP reason phrase (e.g. 'OK', 'Busy Here')." },
+    "trace_id": { "type": "string", "description": "Distributed tracing identifier for correlating logs across jambonz components." },
+    "originating_sip_ip": { "type": "string", "description": "IP address of the originating SIP trunk." },
+    "originating_sip_trunk_name": { "type": "string", "description": "Name of the originating SIP trunk as configured in jambonz." },
+    "api_base_url": { "type": "string", "description": "jambonz REST API base URL. Use this for mid-call control via the REST API." }
+  },
+  "additionalProperties": true
+}

package/callbacks/call-status.schema.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/callbacks/call-status",
+  "title": "Call Status Webhook Payload",
+  "description": "Payload sent to the call status webhook URL whenever the call state changes (e.g. trying, in-progress, completed). The status webhook is configured at the application level in jambonz. Multiple status events are sent over the life of a call. The final event (completed or failed) includes additional fields like duration and termination cause.",
+  "allOf": [
+    { "$ref": "base" }
+  ],
+  "type": "object",
+  "properties": {
+    "call_termination_by": {
+      "type": "string",
+      "enum": ["caller", "jambonz"],
+      "description": "Who terminated the call. 'caller' if the remote party hung up, 'jambonz' if the call was ended by the application (e.g. hangup verb, REST API). Present only on the final status event (completed/failed)."
+    },
+    "duration": {
+      "type": "integer",
+      "description": "Call duration in seconds. Present only on the final status event (completed/failed)."
+    }
+  },
+  "additionalProperties": true
+}

package/callbacks/conference-status.schema.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/callbacks/conference-status",
+  "title": "Conference StatusHook Payload",
+  "description": "Payload sent to the conference statusHook when a conference event occurs.",
+  "allOf": [
+    { "$ref": "base" }
+  ],
+  "type": "object",
+  "properties": {
+    "event": {
+      "type": "string",
+      "enum": ["start", "end", "join", "leave", "start-talking", "stop-talking"],
+      "description": "The conference event that occurred."
+    },
+    "conference_sid": { "type": "string", "description": "Conference identifier (format: conf:<account_sid>:<conference_name>)." },
+    "friendly_name": { "type": "string", "description": "The conference name as specified in the conference verb." },
+    "duration": { "type": "number", "description": "Time in seconds since the conference started." },
+    "members": { "type": "integer", "description": "Current number of participants in the conference." },
+    "time": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the event occurred." }
+  },
+  "required": ["event", "conference_sid"],
+  "additionalProperties": true
+}

package/callbacks/conference-wait.schema.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/callbacks/conference-wait",
+  "title": "Conference WaitHook Payload",
+  "description": "Payload sent to the conference waitHook while a participant is waiting for the conference to start. The response should contain an array of say, play, and/or pause verbs to play while waiting.",
+  "allOf": [
+    { "$ref": "base" }
+  ],
+  "type": "object",
+  "additionalProperties": true
+}

package/callbacks/conference.schema.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/callbacks/conference",
+  "title": "Conference ActionHook Payload",
+  "description": "Payload sent to the conference verb's actionHook when the participant leaves or the conference ends. Contains only the base call info.",
+  "allOf": [
+    { "$ref": "base" }
+  ],
+  "type": "object",
+  "additionalProperties": true
+}

package/callbacks/dequeue.schema.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/callbacks/dequeue",
+  "title": "Dequeue ActionHook Payload",
+  "description": "Payload sent to the dequeue verb's actionHook when the dequeue operation completes.",
+  "allOf": [
+    { "$ref": "base" }
+  ],
+  "type": "object",
+  "properties": {
+    "dequeue_result": {
+      "type": "string",
+      "enum": ["complete", "timeout", "hangup"],
+      "description": "Outcome of the dequeue. 'complete' — successfully dequeued and bridged; 'timeout' — no queued caller found; 'hangup' — call hung up during bridge."
+    }
+  },
+  "required": ["dequeue_result"],
+  "additionalProperties": true
+}

package/callbacks/dial-dtmf.schema.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/callbacks/dial-dtmf",
+  "title": "Dial DtmfHook Payload",
+  "description": "Payload sent to the dial dtmfHook when DTMF digits matching the configured pattern are detected during a dial.",
+  "allOf": [
+    { "$ref": "base" }
+  ],
+  "type": "object",
+  "properties": {
+    "dtmf": {
+      "type": "string",
+      "description": "The DTMF digit sequence that matched the configured dtmfCapture pattern."
+    }
+  },
+  "required": ["dtmf"],
+  "additionalProperties": true
+}

package/callbacks/dial-hold.schema.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/callbacks/dial-hold",
+  "title": "Dial OnHoldHook Payload",
+  "description": "Payload sent to the dial onHoldHook when the remote party places the call on hold. The response should contain say, play, and/or pause verbs to play as hold music. The hook is called repeatedly until the hold ends.",
+  "allOf": [
+    { "$ref": "base" }
+  ],
+  "type": "object",
+  "properties": {
+    "hold_detail": {
+      "type": "object",
+      "description": "Details of the hold event.",
+      "properties": {
+        "from": { "type": "string", "description": "SIP From header value." },
+        "to": { "type": "string", "description": "SIP To header value." }
+      }
+    }
+  },
+  "required": ["hold_detail"],
+  "additionalProperties": true
+}

package/callbacks/dial-refer.schema.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/callbacks/dial-refer",
+  "title": "Dial ReferHook Payload",
+  "description": "Payload sent to the dial referHook when a SIP REFER is received during an active dial. The response can contain new verbs to execute.",
+  "allOf": [
+    { "$ref": "base" }
+  ],
+  "type": "object",
+  "properties": {
+    "refer_details": {
+      "type": "object",
+      "description": "Details of the SIP REFER request. Any custom X-* headers on the REFER are also included as snake_cased properties (e.g. X-Override-Number becomes x_override_number).",
+      "properties": {
+        "sip_refer_to": { "type": "string", "description": "Full SIP Refer-To header value." },
+        "refer_to_user": { "type": "string", "description": "User part of the Refer-To URI (phone number or SIP user)." },
+        "sip_referred_by": { "type": "string", "description": "SIP Referred-By header value, if present." },
+        "referred_by_user": { "type": "string", "description": "User part of the Referred-By URI, if present." },
+        "sip_user_agent": { "type": "string", "description": "User-Agent header from the REFER request." },
+        "referring_call_sid": { "type": "string", "description": "Call SID of the leg that sent the REFER." },
+        "referred_call_sid": { "type": "string", "description": "Call SID of the leg being referred." }
+      },
+      "additionalProperties": true
+    }
+  },
+  "required": ["refer_details"],
+  "additionalProperties": true
+}

package/callbacks/dial.schema.json

@@ -0,0 +1,31 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/callbacks/dial",
+  "title": "Dial ActionHook Payload",
+  "description": "Payload sent to the actionHook when a dial verb completes, either because the dialed party hung up, the call was not answered, or an error occurred.",
+  "allOf": [
+    { "$ref": "base" }
+  ],
+  "type": "object",
+  "properties": {
+    "dial_call_status": {
+      "type": "string",
+      "enum": ["completed", "failed", "busy", "no-answer", "trying", "ringing", "early-media", "in-progress"],
+      "description": "Final status of the outbound (dialed) call leg."
+    },
+    "dial_sip_status": {
+      "type": "integer",
+      "description": "SIP response code from the dialed party (e.g. 200, 486, 487).",
+      "examples": [200, 486, 487]
+    },
+    "dial_call_sid": {
+      "type": "string",
+      "description": "Call SID of the outbound (dialed) call leg."
+    },
+    "dial_sbc_callid": {
+      "type": "string",
+      "description": "SBC-level Call-ID for the outbound (dialed) call leg."
+    }
+  },
+  "additionalProperties": true
+}

package/callbacks/enqueue-wait.schema.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/callbacks/enqueue-wait",
+  "title": "Enqueue WaitHook Payload",
+  "description": "Payload sent to the enqueue waitHook while a caller is waiting in the queue. The response should contain an array of say, play, pause, and/or leave verbs. Note: this payload is sparse — it contains queue-specific fields plus call_sid and call_id, but NOT the full base payload fields.",
+  "type": "object",
+  "properties": {
+    "queue_sid": { "type": "string", "description": "Queue identifier in the format 'queue:{account_sid}:{queue_name}'." },
+    "queue_time": { "type": "integer", "description": "Time in seconds the caller has been waiting in the queue." },
+    "queue_size": { "type": "integer", "description": "Total number of callers currently in the queue." },
+    "queue_position": { "type": "integer", "description": "Caller's current position in the queue (0-based)." },
+    "call_sid": { "type": "string", "description": "Unique identifier for this call." },
+    "call_id": { "type": "string", "description": "SIP Call-ID." }
+  },
+  "required": ["queue_sid", "queue_time"],
+  "additionalProperties": true
+}

package/callbacks/enqueue.schema.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/callbacks/enqueue",
+  "title": "Enqueue ActionHook Payload",
+  "description": "Payload sent to the enqueue actionHook when the enqueue verb completes — i.e. the call was bridged, abandoned, left the queue, or an error occurred.",
+  "allOf": [
+    { "$ref": "base" }
+  ],
+  "type": "object",
+  "properties": {
+    "queue_sid": {
+      "type": "string",
+      "description": "Queue identifier in the format 'queue:{account_sid}:{queue_name}'."
+    },
+    "queue_time": {
+      "type": "integer",
+      "description": "Time in seconds the caller spent waiting in the queue."
+    },
+    "queue_result": {
+      "type": "string",
+      "enum": ["bridged", "hangup", "leave", "error"],
+      "description": "Outcome of the enqueue. 'bridged' — call was dequeued and connected; 'hangup' — caller hung up while waiting; 'leave' — caller executed a leave verb from the waitHook; 'error' — an error occurred during bridging."
+    }
+  },
+  "required": ["queue_sid", "queue_time", "queue_result"],
+  "additionalProperties": true
+}

package/callbacks/gather-partial.schema.json

@@ -0,0 +1,54 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/callbacks/gather-partial",
+  "title": "Gather Partial Transcript Payload",
+  "description": "Payload sent to the partialResultHook during a gather verb with speech input. Delivers interim (partial) speech recognition results as they arrive, before the gather completes. This hook is informational — the response is ignored and does not replace the verb stack. Note: the base fields use slightly different names than the actionHook payload (e.g. local_sip_address instead of fs_sip_address).",
+  "type": "object",
+  "properties": {
+    "call_sid": { "type": "string", "description": "Unique identifier for this call." },
+    "account_sid": { "type": "string", "description": "Account identifier." },
+    "application_sid": { "type": "string", "description": "Application identifier." },
+    "direction": { "type": "string", "enum": ["inbound", "outbound"], "description": "Call direction." },
+    "from": { "type": "string", "description": "Caller phone number or SIP URI." },
+    "to": { "type": "string", "description": "Called phone number or SIP URI." },
+    "call_id": { "type": "string", "description": "SIP Call-ID." },
+    "sbc_callid": { "type": "string", "description": "SBC-level Call-ID." },
+    "call_status": { "type": "string", "description": "Current call state." },
+    "sip_status": { "type": "integer", "description": "SIP response code." },
+    "sip_reason": { "type": "string", "description": "SIP reason phrase." },
+    "trace_id": { "type": "string", "description": "Distributed tracing identifier." },
+    "b3": { "type": "string", "description": "B3 trace propagation header." },
+    "caller_name": { "type": "string", "description": "Caller display name from SIP, if available." },
+    "originating_sip_ip": { "type": "string", "description": "IP address of the originating SIP trunk." },
+    "originating_sip_trunk_name": { "type": "string", "description": "Name of the originating SIP trunk." },
+    "speech": {
+      "type": "object",
+      "description": "Interim speech recognition results.",
+      "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": "Always false for partial results." },
+        "alternatives": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "transcript": { "type": "string", "description": "The partial transcript recognized so far." },
+              "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": { "type": "object", "description": "Raw vendor-specific event payload.", "additionalProperties": true }
+          }
+        }
+      }
+    }
+  },
+  "additionalProperties": true
+}

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

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

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

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