@jambonz/schema 0.4.29 → 0.4.31

package/commands/dialogflow-update.schema.json

@@ -0,0 +1,60 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/commands/dialogflow:update",
+  "title": "Dialogflow Update Command",
+  "description": "Command sent from the application to feature-server over the session websocket, sending input into a running Dialogflow CES session (a `dialogflow` verb with `model: \"ces\"`) without restarting the verb. The same object can be sent over REST as the `dialogflow_update` key of the call-update body. `variables` and `dtmf` are sent at once. An `event` or `text` starts an agent turn; CES silently drops one that arrives while the agent is still replying, so jambonz holds it and sends it when the agent's current turn ends, one per turn, in order. A command sent when no CES dialogflow verb is running is refused and logged by feature-server.",
+  "type": "object",
+  "required": ["type", "command", "data"],
+  "properties": {
+    "type": { "const": "command" },
+    "command": { "const": "dialogflow:update" },
+    "data": {
+      "type": "object",
+      "description": "The input to send. At least one of `event`, `text`, `dtmf` or `variables` is required, and at most one of `event`, `text` and `dtmf`.",
+      "properties": {
+        "event": {
+          "type": "string",
+          "minLength": 1,
+          "description": "A CES event name. The CES agent's instructions must say what to do when it receives this event."
+        },
+        "text": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Text sent as if the caller had said it."
+        },
+        "dtmf": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Keypad digits."
+        },
+        "variables": {
+          "type": "object",
+          "description": "CES session variables. Only variables the CES app declares, and whose instructions reference them as {name}, are used by the agent.",
+          "additionalProperties": true
+        }
+      },
+      "additionalProperties": false,
+      "minProperties": 1,
+      "not": {
+        "anyOf": [
+          { "required": ["event", "text"] },
+          { "required": ["event", "dtmf"] },
+          { "required": ["text", "dtmf"] }
+        ]
+      }
+    }
+  },
+  "additionalProperties": false,
+  "examples": [
+    {
+      "type": "command",
+      "command": "dialogflow:update",
+      "data": { "event": "payment_approved" }
+    },
+    {
+      "type": "command",
+      "command": "dialogflow:update",
+      "data": { "variables": { "account_tier": "gold" } }
+    }
+  ]
+}

package/components/recognizer-paxaOptions.schema.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/components/recognizer-paxaOptions",
+  "title": "Paxa Recognizer Options",
+  "description": "Paxa Labs realtime STT options. Only applies when recognizer vendor is 'paxa'. Paxa detects the end of each turn and produces one final transcript per turn. The recognizer language is sent as a hint (it never filters out other languages); set it to 'any' for automatic detection.",
+  "type": "object",
+  "properties": {
+    "style": {
+      "type": "string",
+      "enum": ["verbatim", "clean"],
+      "description": "verbatim (default) keeps fillers and false starts; clean drops them."
+    },
+    "convention": {
+      "type": "string",
+      "enum": ["spoken", "written"],
+      "description": "spoken (default) writes numbers as said; written uses digits and units."
+    },
+    "timestamps": {
+      "type": "boolean",
+      "description": "Request word-level timestamps."
+    }
+  },
+  "additionalProperties": false
+}

package/components/recognizer.schema.json

@@ -8,7 +8,7 @@
     "vendor": {
       "type": "string",
       "description": "The STT vendor to use. Must match a vendor configured in the jambonz platform.",
-      "examples": ["google", "aws", "microsoft", "deepgram", "ibm", "nvidia", "soniox", "xai", "modulate", "zoom", "gradium", "giggy", "mistral", "assemblyai", "speechmatics", "openai", "houndify", "gladia", "elevenlabs", "custom"]
+      "examples": ["google", "aws", "microsoft", "deepgram", "ibm", "nvidia", "soniox", "xai", "modulate", "zoom", "gradium", "giggy", "mistral", "paxa", "assemblyai", "speechmatics", "openai", "houndify", "gladia", "elevenlabs", "custom"]
     },
     "label": {
       "type": "string",
@@ -204,6 +204,7 @@
     "gradiumOptions": { "$ref": "recognizer-gradiumOptions" },
     "giggyOptions": { "$ref": "recognizer-giggyOptions" },
     "mistralOptions": { "$ref": "recognizer-mistralOptions" },
+    "paxaOptions": { "$ref": "recognizer-paxaOptions" },
     "assemblyAiOptions": { "$ref": "recognizer-assemblyAiOptions" },
     "speechmaticsOptions": { "$ref": "recognizer-speechmaticsOptions" },
     "openaiOptions": { "$ref": "recognizer-openaiOptions" },

package/components/synthesizer.schema.json

@@ -8,7 +8,7 @@
     "vendor": {
       "type": "string",
       "description": "The TTS vendor to use. Must match a vendor configured in the jambonz platform.",
-      "examples": ["google", "aws", "microsoft", "elevenlabs", "cartesia", "fishaudio", "gradium", "kugelaudio", "mistral", "nineninesix", "speechify", "deepgram", "deepgramflux", "ibm", "nvidia", "wellsaid", "whisper", "custom"]
+      "examples": ["google", "aws", "microsoft", "elevenlabs", "cartesia", "fishaudio", "gradium", "kugelaudio", "mistral", "nineninesix", "paxa", "speechify", "deepgram", "deepgramflux", "ibm", "nvidia", "wellsaid", "whisper", "custom"]
     },
     "label": {
       "type": "string",

package/docs/guides/session-commands.md

@@ -255,6 +255,16 @@ session.updateAgent({
 });
 ```
 
+## Dialogflow Update
+
+The `dialogflow:update` command sends input into a running Dialogflow CES session (a `dialogflow` verb with `model: "ces"`) without restarting the verb. Over REST, send the same object as the `dialogflow_update` key of the call-update body. The object holds at most one of `event`, `text` or `dtmf`, plus optional `variables`; at least one field is required.
+
+```json
+{"type": "command", "command": "dialogflow:update", "data": {"event": "payment_approved"}}
+```
+
+An `event` or `text` is held until the agent's current turn ends, since CES drops input that arrives mid-reply. See `docs/verbs/dialogflow.md` for the worked example, including the line the CES agent's instructions need, and for the `input-sent` and `input-dropped` events.
+
 ## LLM Tool Output
 
 When using the `agent` verb with a `toolHook`, tool call requests arrive as events. Return results with:

package/docs/verbs/dialogflow.md

@@ -0,0 +1,69 @@
+## Overview
+
+The dialogflow verb connects the caller to a Google Dialogflow agent (ES, CX, or CES). See the verb schema for all properties.
+
+## Sending input into a CES conversation mid-call
+
+With `model: "ces"`, an application can send input into the running conversation without restarting the verb. Updates can be sent via:
+- **WebSocket**: a `dialogflow:update` command: `{"type":"command","command":"dialogflow:update","data":{...}}`
+- **REST API**: the `dialogflow_update` key of the call-update body, with the same object
+
+The object holds at most one of `event` (a CES event name), `text` (sent as if the caller said it) or `dtmf` (keypad digits), plus an optional `variables` object. At least one field is required.
+
+- `variables` and `dtmf` are sent at once.
+- An `event` or `text` starts an agent turn. CES silently drops one that arrives while the agent is still replying, so jambonz holds it and sends it when the agent's current turn ends: one per turn, in order.
+- Only CES is supported. A command sent when no CES dialogflow verb is running is refused and logged by feature-server.
+
+This replaces redirecting to a new `dialogflow` verb with a `welcomeEvent` to tell the agent something mid-call, which restarts the verb.
+
+### Example: take a card payment, then tell the agent
+
+The caller is talking to a CES agent. The application takes the card payment on another system and tells the agent when it is approved:
+
+```typescript
+// WebSocket application (@jambonz/sdk)
+session.updateDialogflow({ event: 'payment_approved' });
+
+// or from any system that knows the call sid, over REST
+await client.calls.updateDialogflow(callSid, { event: 'payment_approved' });
+```
+
+The raw command is:
+
+```json
+{"type": "command", "command": "dialogflow:update", "data": {"event": "payment_approved"}}
+```
+
+The CES agent only acts on an event its instructions mention. Add a line like this to the agent's instructions in the CES app:
+
+```
+When you receive the event payment_approved, thank the caller, confirm that their payment went through, and ask if there is anything else you can help with.
+```
+
+Without it, the event arrives but the agent has no idea what to do with it.
+
+### Variables
+
+`variables` sets CES session variables. A variable must be declared in the CES app and referenced in the agent's instructions as `{name}`, otherwise the agent does not use it.
+
+```json
+{"type": "command", "command": "dialogflow:update", "data": {"variables": {"account_tier": "gold"}}}
+```
+
+### input-sent and input-dropped events
+
+Two eventHook events report what happened to a held `event` or `text` input. They are delivered only if listed in the verb's `events` array (or `events: ["all"]`).
+
+| Event | Meaning | Data |
+|-------|---------|------|
+| `input-sent` | A held input went out | `{kind, event, waited_ms}` |
+| `input-dropped` | An input was not delivered, e.g. the session ended first | `{kind, event, reason}` |
+
+```json
+{
+  "verb": "dialogflow",
+  "model": "ces",
+  "eventHook": "/df-event",
+  "events": ["input-sent", "input-dropped"]
+}
+```

package/lib/validator.js

@@ -116,6 +116,7 @@ function validateVerb(name, data, logger) {
  * Commands are the inverse of callbacks: callbacks flow server → app; commands
  * flow app → server. Currently defined commands:
  *   - llm:tool-output — response to an agent:tool-call event.
+ *   - dialogflow:update — send input into a running Dialogflow CES session.
  *
  * @param {string} name - Command name (e.g. 'llm:tool-output').
  * @param {object} message - The full command message including `type` and `command`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jambonz/schema",
-  "version": "0.4.29",
+  "version": "0.4.31",
   "description": "JSON Schema definitions and validation for jambonz verb applications",
   "main": "index.js",
   "scripts": {

package/verbs/dialogflow.schema.json

@@ -81,7 +81,7 @@
       "items": {
         "type": "string"
       },
-      "description": "List of event types to receive via the eventHook."
+      "description": "List of event types to receive via the eventHook. For CES, the events `input-sent` (an input held by a `dialogflow:update` command was sent; data `{kind, event, waited_ms}`) and `input-dropped` (an input was not delivered, e.g. the session ended first; data `{kind, event, reason}`) are delivered only if listed here (or `all`)."
     },
     "welcomeEvent": {
       "type": "string",