@signalwire/sdk 3.5.0 → 3.7.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -135,7 +135,7 @@ SignalWire requests the SWML with a `POST` whose body describes the call. The ag
135
135
  - **Tool dispatch**: running the handler for a SWAIG request, after checking its per-call token.
136
136
  - **Proxy detection**: finding the external URL for the webhook URLs in the SWML.
137
137
  - **Per-request configuration**: making a per-request copy of the agent for a dynamic config callback.
138
- - **Lifecycle hooks**: `onSummary`, `onFunctionCall`, `onSwmlRequest`, `onDebugEvent`, `onCallEnd` and `onError`.
138
+ - **Lifecycle hooks**: `onSummary`, `onFunctionCall`, `onSwmlRequest`, `onDebugEvent`, `onCallStart`, `onCallEnd` and `onError`.
139
139
 
140
140
  `SWMLService` supplies the `SwmlBuilder`, the tool registry, basic-auth resolution, routing callbacks and `handleRequest()`, the framework-free request handler that the agent's SWML routes call.
141
141
 
@@ -777,6 +777,7 @@ A subclass can override these methods:
777
777
  These methods register handlers instead of being overridden:
778
778
 
779
779
  - `onError(handler)`: called when a tool handler throws, after the tool's own `onError`. A `FunctionResult` it returns is sent as the response.
780
+ - `onCallStart(handler)`: registers the reserved `startup_hook` tool, so the handler runs before the AI's first turn; the actions and response text of the `FunctionResult` it returns reach the call.
780
781
  - `onCallEnd(handler)`: registers the reserved `hangup_hook` tool and turns on `swaig_post_conversation`, so the handler gets the call log when the call ends.
781
782
 
782
783
  ### Dynamic Configuration Callback
@@ -5,13 +5,14 @@ This page is the reference for the `DataMap` class in the SignalWire AI Agents T
5
5
  <!-- snippet-setup -->
6
6
  ```ts
7
7
  export {}; // treat each runnable example as a module
8
- // Shared context the examples assume: `DataMap`/`FunctionResult` (imported once and
9
- // reused), `agent` (an AgentBase), and `tool` (the DataMap built in the current example).
10
- // Declared as ambient globals so each fragment resolves without repeating the boilerplate.
11
- // A block that constructs or imports its own `const tool`/`DataMap` shadows these.
8
+ // Shared context the examples assume: `DataMap`/`FunctionResult`/`SemanticGate` (imported
9
+ // once and reused), `agent` (an AgentBase), and `tool` (the DataMap built in the current
10
+ // example). Declared as ambient globals so each fragment resolves without repeating the
11
+ // boilerplate. A block that constructs or imports its own `const tool`/`DataMap` shadows these.
12
12
  declare global {
13
13
  const DataMap: typeof import('@signalwire/sdk').DataMap;
14
14
  const FunctionResult: typeof import('@signalwire/sdk').FunctionResult;
15
+ const SemanticGate: typeof import('@signalwire/sdk').SemanticGate;
15
16
  const agent: import('@signalwire/sdk').AgentBase;
16
17
  const tool: import('@signalwire/sdk').DataMap;
17
18
  }
@@ -43,6 +44,9 @@ The page has these sections:
43
44
  - [fallbackOutput](#fallbackoutput)
44
45
  - [errorKeys](#errorkeys)
45
46
  - [globalErrorKeys](#globalerrorkeys)
47
+ - [Semantic Gates](#semantic-gates)
48
+ - [gate](#gate)
49
+ - [gateFillers](#gatefillers)
46
50
  - [Iteration](#iteration)
47
51
  - [foreach](#foreach)
48
52
  - [Environment Variables](#environment-variables)
@@ -629,6 +633,49 @@ With a ZIP code, the platform requests the first webhook. With only a city, it s
629
633
 
630
634
  ---
631
635
 
636
+ ## Semantic Gates
637
+
638
+ A semantic gate is a yes/no question a decision model answers about the call right before the platform runs the function. When a gate fails, the data_map doesn't run at all: no expression or webhook is tried, and the model gets the gate's `on_fail` output. The [API reference](api-reference.md#semantic-gates) describes gates and their limits. They need a platform release that supports them; one that doesn't runs the function ungated.
639
+
640
+ ### gate
641
+
642
+ This method adds a gate. Call it once per gate, up to 8.
643
+
644
+ <!-- snippet: no-compile API signature / illustrative fragment, not runnable -->
645
+ ```typescript
646
+ gate(gate: SemanticGate | Record<string, unknown>): this
647
+ ```
648
+
649
+ `toSwaigFunction()` checks the gates by the platform's rules, after environment variables are expanded, and throws for one the platform would refuse. This tool places an order only once the caller has confirmed it:
650
+
651
+ <!-- snippet: no-run illustrative fragment: references the assumed `DataMap` and `SemanticGate` from the page prelude (declared type-only in the shared snippet-setup), not a standalone program -->
652
+ ```typescript
653
+ const placeOrder = new DataMap('place_order')
654
+ .purpose('Place the order the caller confirmed')
655
+ .webhook('POST', 'https://orders.example.com/orders')
656
+ .params({ item: '${args.item}' })
657
+ .output(new FunctionResult('The order is placed.'))
658
+ .gate(
659
+ new SemanticGate(
660
+ 'Has the caller confirmed the order in `conversation`?',
661
+ 0.9,
662
+ 'place_order was not run.',
663
+ ),
664
+ )
665
+ .gateFillers({ default: ['Let me check that.'] });
666
+ ```
667
+
668
+ ### gateFillers
669
+
670
+ This method sets what the AI says while the gates are checked, shaped like a function's fillers: phrases keyed by language code, `auto` or `default`. It's only for a function with gates.
671
+
672
+ <!-- snippet: no-compile API signature / illustrative fragment, not runnable -->
673
+ ```typescript
674
+ gateFillers(fillers: FillerPhrases): this
675
+ ```
676
+
677
+ ---
678
+
632
679
  ## Iteration
633
680
 
634
681
  ### foreach
@@ -43,6 +43,7 @@ The reference groups the methods by what they do:
43
43
  - [say](#say)
44
44
  - [playBackgroundFile](#playbackgroundfile)
45
45
  - [stopBackgroundFile](#stopbackgroundfile)
46
+ - [changeVoice](#changevoice)
46
47
  - [Speech](#speech)
47
48
  - [addDynamicHints](#adddynamichints)
48
49
  - [clearDynamicHints](#cleardynamichints)
@@ -51,6 +52,7 @@ The reference groups the methods by what they do:
51
52
  - [Data Management](#data-management)
52
53
  - [updateGlobalData](#updateglobaldata)
53
54
  - [removeGlobalData](#removeglobaldata)
55
+ - [setSemanticState](#setsemanticstate)
54
56
  - [setMetadata](#setmetadata)
55
57
  - [removeMetadata](#removemetadata)
56
58
  - [SWML Actions](#swml-actions)
@@ -702,6 +704,29 @@ const result = new FunctionResult('The music is stopped.')
702
704
  .stopBackgroundFile();
703
705
  ```
704
706
 
707
+ ### changeVoice
708
+
709
+ Change the AI's voice for the rest of the call (`change_voice`). The voice takes the `engine.voice:model` form a language's voice takes, and may be on another engine. It replaces the current language's voice from the next batch of speech on, never mid-utterance, and stays for that language for the rest of the call. A voice that won't open falls back to the fallback voice.
710
+
711
+ <!-- snippet: no-compile API signature reference, not runnable code -->
712
+ ```typescript
713
+ changeVoice(voice: string): this
714
+ ```
715
+
716
+ | Parameter | Type | Description |
717
+ |-----------|----------|--------------------------------------------------------|
718
+ | `voice` | `string` | The voice as `engine.voice:model`, such as `elevenlabs.rachel`. |
719
+
720
+ **Returns:** `this` for chaining.
721
+
722
+ **Throws:** `Error` when `voice` is empty or only whitespace. The platform would ignore it.
723
+
724
+ **Example:**
725
+
726
+ ```typescript
727
+ const result = new FunctionResult('The voice is changed.').changeVoice('elevenlabs.rachel');
728
+ ```
729
+
705
730
  ## Speech
706
731
 
707
732
  ### addDynamicHints
@@ -822,6 +847,29 @@ const result = new FunctionResult('The customer record is loaded.')
822
847
  .updateGlobalData({ customer_id: 'C-123', tier: 'premium' });
823
848
  ```
824
849
 
850
+ ### setSemanticState
851
+
852
+ Set the state the call's semantic gates judge, besides the dialogue: `global_data.semantic_state` (sent as `set_global_data`). It replaces the state as a whole: to change one field, send the whole state with that field changed, and send `{}` to reset it. Keep it to what the application has established, such as an order the caller confirmed, rather than what the caller claims. It's the only global data copied into the decision model's state; a gate question can still bring in other global data with a `${global_data.x}` template. See [Semantic gates](api-reference.md#semantic-gates).
853
+
854
+ <!-- snippet: no-compile API signature reference, not runnable code -->
855
+ ```typescript
856
+ setSemanticState(state: Record<string, unknown>): this
857
+ ```
858
+
859
+ | Parameter | Type | Description |
860
+ |-----------|---------------------------|---------------------|
861
+ | `state` | `Record<string, unknown>` | The semantic state. |
862
+
863
+ **Returns:** `this` for chaining.
864
+
865
+ **Example:**
866
+
867
+ ```typescript
868
+ const result = new FunctionResult('The order is confirmed.').setSemanticState({
869
+ order: { item: 'large pepperoni', confirmed: true },
870
+ });
871
+ ```
872
+
825
873
  ### removeGlobalData
826
874
 
827
875
  Remove one or more keys from the global data (`unset_global_data`).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@signalwire/sdk",
3
- "version": "3.5.0",
3
+ "version": "3.7.1",
4
4
  "description": "SignalWire AI Agents SDK for TypeScript/Node.js",
5
5
  "keywords": [
6
6
  "signalwire",