@signalwire/sdk 2.0.5 → 3.6.0
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.
- package/CHANGELOG.md +821 -0
- package/LICENSE +21 -0
- package/README.md +163 -68
- package/dist/AGENTS.md +13 -0
- package/dist/AgentBase.d.ts +510 -126
- package/dist/AgentBase.js +1581 -455
- package/dist/AgentBase.js.map +1 -1
- package/dist/AgentServer.d.ts +21 -0
- package/dist/AgentServer.js +154 -47
- package/dist/AgentServer.js.map +1 -1
- package/dist/AuthHandler.d.ts +14 -2
- package/dist/AuthHandler.js +7 -2
- package/dist/AuthHandler.js.map +1 -1
- package/dist/ConfigLoader.d.ts +5 -13
- package/dist/ConfigLoader.js +15 -29
- package/dist/ConfigLoader.js.map +1 -1
- package/dist/ContextBuilder.d.ts +202 -9
- package/dist/ContextBuilder.js +219 -36
- package/dist/ContextBuilder.js.map +1 -1
- package/dist/DataMap.d.ts +186 -45
- package/dist/DataMap.js +210 -52
- package/dist/DataMap.js.map +1 -1
- package/dist/FunctionResult.d.ts +309 -83
- package/dist/FunctionResult.js +483 -116
- package/dist/FunctionResult.js.map +1 -1
- package/dist/Logger.d.ts +30 -5
- package/dist/Logger.js +77 -19
- package/dist/Logger.js.map +1 -1
- package/dist/POM/PromptObjectModel.d.ts +12 -1
- package/dist/POM/PromptObjectModel.js +25 -9
- package/dist/POM/PromptObjectModel.js.map +1 -1
- package/dist/ParameterSchema.d.ts +306 -0
- package/dist/ParameterSchema.js +251 -0
- package/dist/ParameterSchema.js.map +1 -0
- package/dist/PlatformContracts.d.ts +21 -0
- package/dist/PlatformContracts.generated.d.ts +109 -0
- package/dist/PlatformContracts.generated.js +8 -0
- package/dist/PlatformContracts.generated.js.map +1 -0
- package/dist/PlatformContracts.js +2 -0
- package/dist/PlatformContracts.js.map +1 -0
- package/dist/PomBuilder.d.ts +18 -0
- package/dist/PomBuilder.js +53 -3
- package/dist/PomBuilder.js.map +1 -1
- package/dist/PostPrompt.d.ts +110 -0
- package/dist/PostPrompt.js +204 -0
- package/dist/PostPrompt.js.map +1 -0
- package/dist/PromptManager.d.ts +22 -1
- package/dist/PromptManager.js +28 -1
- package/dist/PromptManager.js.map +1 -1
- package/dist/PublicFetch.d.ts +132 -0
- package/dist/PublicFetch.js +311 -0
- package/dist/PublicFetch.js.map +1 -0
- package/dist/RobotsTxt.d.ts +41 -0
- package/dist/RobotsTxt.js +152 -0
- package/dist/RobotsTxt.js.map +1 -0
- package/dist/SWMLHandler.js.map +1 -1
- package/dist/SWMLService.d.ts +169 -59
- package/dist/SWMLService.js +456 -129
- package/dist/SWMLService.js.map +1 -1
- package/dist/SchemaUtils.d.ts +115 -2
- package/dist/SchemaUtils.js +444 -12
- package/dist/SchemaUtils.js.map +1 -1
- package/dist/SecurityUtils.d.ts +49 -9
- package/dist/SecurityUtils.js +153 -51
- package/dist/SecurityUtils.js.map +1 -1
- package/dist/SemanticGate.d.ts +183 -0
- package/dist/SemanticGate.js +533 -0
- package/dist/SemanticGate.js.map +1 -0
- package/dist/ServerlessAdapter.d.ts +156 -7
- package/dist/ServerlessAdapter.js +399 -42
- package/dist/ServerlessAdapter.js.map +1 -1
- package/dist/SessionManager.d.ts +11 -2
- package/dist/SessionManager.js +50 -18
- package/dist/SessionManager.js.map +1 -1
- package/dist/SslConfig.d.ts +2 -1
- package/dist/SslConfig.js +4 -1
- package/dist/SslConfig.js.map +1 -1
- package/dist/SwaigActions.generated.d.ts +23 -0
- package/dist/SwaigActions.generated.js +8 -0
- package/dist/SwaigActions.generated.js.map +1 -0
- package/dist/SwaigContracts.d.ts +15 -0
- package/dist/SwaigContracts.generated.d.ts +264 -0
- package/dist/SwaigContracts.generated.js +12 -0
- package/dist/SwaigContracts.generated.js.map +1 -0
- package/dist/SwaigContracts.js +2 -0
- package/dist/SwaigContracts.js.map +1 -0
- package/dist/SwaigFunction.d.ts +139 -7
- package/dist/SwaigFunction.js +170 -22
- package/dist/SwaigFunction.js.map +1 -1
- package/dist/SwmlBuilder.d.ts +68 -19
- package/dist/SwmlBuilder.js +74 -38
- package/dist/SwmlBuilder.js.map +1 -1
- package/dist/SwmlVerbMethods.generated.d.ts +41 -4
- package/dist/SwmlVerbMethods.generated.js +1 -1
- package/dist/TypeInference.d.ts +39 -3
- package/dist/TypeInference.js +256 -16
- package/dist/TypeInference.js.map +1 -1
- package/dist/WebService.d.ts +79 -11
- package/dist/WebService.js +320 -109
- package/dist/WebService.js.map +1 -1
- package/dist/WebhookMiddleware.d.ts +119 -0
- package/dist/WebhookMiddleware.js +271 -0
- package/dist/WebhookMiddleware.js.map +1 -0
- package/dist/WebhookValidator.d.ts +92 -0
- package/dist/WebhookValidator.js +409 -0
- package/dist/WebhookValidator.js.map +1 -0
- package/dist/agents/BedrockAgent.d.ts +162 -0
- package/dist/agents/BedrockAgent.js +323 -0
- package/dist/agents/BedrockAgent.js.map +1 -0
- package/dist/ai-chat/AIChatClient.d.ts +316 -0
- package/dist/ai-chat/AIChatClient.js +535 -0
- package/dist/ai-chat/AIChatClient.js.map +1 -0
- package/dist/ai-chat/ChatGateway.d.ts +408 -0
- package/dist/ai-chat/ChatGateway.js +747 -0
- package/dist/ai-chat/ChatGateway.js.map +1 -0
- package/dist/ai-chat/HandoffRouter.d.ts +282 -0
- package/dist/ai-chat/HandoffRouter.js +518 -0
- package/dist/ai-chat/HandoffRouter.js.map +1 -0
- package/dist/ai-chat/index.d.ts +12 -0
- package/dist/ai-chat/index.js +10 -0
- package/dist/ai-chat/index.js.map +1 -0
- package/dist/capabilities.d.ts +64 -0
- package/dist/capabilities.js +95 -0
- package/dist/capabilities.js.map +1 -0
- package/dist/cli/agent-loader.d.ts +32 -6
- package/dist/cli/agent-loader.js +92 -33
- package/dist/cli/agent-loader.js.map +1 -1
- package/dist/cli/datamap-exec.d.ts +175 -0
- package/dist/cli/datamap-exec.js +1284 -0
- package/dist/cli/datamap-exec.js.map +1 -0
- package/dist/cli/function-args.d.ts +40 -0
- package/dist/cli/function-args.js +146 -0
- package/dist/cli/function-args.js.map +1 -0
- package/dist/cli/simulation.d.ts +99 -0
- package/dist/cli/simulation.js +490 -0
- package/dist/cli/simulation.js.map +1 -0
- package/dist/cli/swaig-test.d.ts +12 -25
- package/dist/cli/swaig-test.js +935 -371
- package/dist/cli/swaig-test.js.map +1 -1
- package/dist/cli/tsdocs/agentsNote.d.ts +30 -0
- package/dist/cli/tsdocs/agentsNote.js +92 -0
- package/dist/cli/tsdocs/agentsNote.js.map +1 -0
- package/dist/cli/tsdocs/api-index.json +1 -0
- package/dist/cli/tsdocs/api.d.ts +91 -0
- package/dist/cli/tsdocs/api.js +372 -0
- package/dist/cli/tsdocs/api.js.map +1 -0
- package/dist/cli/tsdocs/apiTypes.d.ts +64 -0
- package/dist/cli/tsdocs/apiTypes.js +7 -0
- package/dist/cli/tsdocs/apiTypes.js.map +1 -0
- package/dist/cli/tsdocs/bin.d.ts +6 -0
- package/dist/cli/tsdocs/bin.js +23 -0
- package/dist/cli/tsdocs/bin.js.map +1 -0
- package/dist/cli/tsdocs/files.d.ts +108 -0
- package/dist/cli/tsdocs/files.js +287 -0
- package/dist/cli/tsdocs/files.js.map +1 -0
- package/dist/cli/tsdocs/index.d.ts +28 -0
- package/dist/cli/tsdocs/index.js +307 -0
- package/dist/cli/tsdocs/index.js.map +1 -0
- package/dist/cli/tsdocs/live.d.ts +41 -0
- package/dist/cli/tsdocs/live.js +202 -0
- package/dist/cli/tsdocs/live.js.map +1 -0
- package/dist/cli/tsdocs/locate.d.ts +51 -0
- package/dist/cli/tsdocs/locate.js +75 -0
- package/dist/cli/tsdocs/locate.js.map +1 -0
- package/dist/cli/tsdocs/render.d.ts +75 -0
- package/dist/cli/tsdocs/render.js +323 -0
- package/dist/cli/tsdocs/render.js.map +1 -0
- package/dist/cli/tsdocs/topics.d.ts +43 -0
- package/dist/cli/tsdocs/topics.js +920 -0
- package/dist/cli/tsdocs/topics.js.map +1 -0
- package/dist/index.d.ts +49 -68
- package/dist/index.js +45 -73
- package/dist/index.js.map +1 -1
- package/dist/livewire/index.d.ts +229 -155
- package/dist/livewire/index.js +298 -195
- package/dist/livewire/index.js.map +1 -1
- package/dist/llms.txt +65 -0
- package/dist/prefabs/CallSessionStore.d.ts +52 -0
- package/dist/prefabs/CallSessionStore.js +72 -0
- package/dist/prefabs/CallSessionStore.js.map +1 -0
- package/dist/prefabs/ConciergeAgent.d.ts +13 -1
- package/dist/prefabs/ConciergeAgent.js +36 -31
- package/dist/prefabs/ConciergeAgent.js.map +1 -1
- package/dist/prefabs/FAQBotAgent.d.ts +9 -1
- package/dist/prefabs/FAQBotAgent.js +113 -47
- package/dist/prefabs/FAQBotAgent.js.map +1 -1
- package/dist/prefabs/InfoGathererAgent.d.ts +22 -3
- package/dist/prefabs/InfoGathererAgent.js +67 -58
- package/dist/prefabs/InfoGathererAgent.js.map +1 -1
- package/dist/prefabs/ReceptionistAgent.d.ts +16 -5
- package/dist/prefabs/ReceptionistAgent.js +39 -31
- package/dist/prefabs/ReceptionistAgent.js.map +1 -1
- package/dist/prefabs/SurveyAgent.d.ts +22 -4
- package/dist/prefabs/SurveyAgent.js +84 -68
- package/dist/prefabs/SurveyAgent.js.map +1 -1
- package/dist/relay/Action.d.ts +44 -21
- package/dist/relay/Action.js +75 -17
- package/dist/relay/Action.js.map +1 -1
- package/dist/relay/Call.d.ts +312 -47
- package/dist/relay/Call.js +369 -18
- package/dist/relay/Call.js.map +1 -1
- package/dist/relay/Deferred.js.map +1 -1
- package/dist/relay/Message.d.ts +26 -5
- package/dist/relay/Message.js +36 -6
- package/dist/relay/Message.js.map +1 -1
- package/dist/relay/RelayClient.d.ts +44 -17
- package/dist/relay/RelayClient.js +175 -65
- package/dist/relay/RelayClient.js.map +1 -1
- package/dist/relay/RelayError.d.ts +14 -0
- package/dist/relay/RelayError.js +15 -0
- package/dist/relay/RelayError.js.map +1 -1
- package/dist/relay/RelayEvent.d.ts +96 -65
- package/dist/relay/RelayEvent.js +85 -56
- package/dist/relay/RelayEvent.js.map +1 -1
- package/dist/relay/closedSets.d.ts +111 -0
- package/dist/relay/closedSets.js +83 -0
- package/dist/relay/closedSets.js.map +1 -0
- package/dist/relay/index.d.ts +3 -1
- package/dist/relay/index.js +1 -0
- package/dist/relay/index.js.map +1 -1
- package/dist/relay/normalize.js.map +1 -1
- package/dist/relay/protocol.types.generated.d.ts +1195 -0
- package/dist/relay/protocol.types.generated.js +8 -0
- package/dist/relay/protocol.types.generated.js.map +1 -0
- package/dist/relay/types.d.ts +73 -42
- package/dist/rest/HttpClient.d.ts +36 -8
- package/dist/rest/HttpClient.js +233 -40
- package/dist/rest/HttpClient.js.map +1 -1
- package/dist/rest/RequestOptions.d.ts +110 -0
- package/dist/rest/RequestOptions.js +113 -0
- package/dist/rest/RequestOptions.js.map +1 -0
- package/dist/rest/RestError.d.ts +52 -6
- package/dist/rest/RestError.js +89 -5
- package/dist/rest/RestError.js.map +1 -1
- package/dist/rest/base/CrudResource.d.ts +16 -26
- package/dist/rest/base/CrudResource.js +19 -33
- package/dist/rest/base/CrudResource.js.map +1 -1
- package/dist/rest/base/CrudWithAddresses.d.ts +3 -2
- package/dist/rest/base/CrudWithAddresses.js +2 -2
- package/dist/rest/base/CrudWithAddresses.js.map +1 -1
- package/dist/rest/base/FabricResource.d.ts +15 -0
- package/dist/rest/base/FabricResource.js +16 -0
- package/dist/rest/base/FabricResource.js.map +1 -0
- package/dist/rest/base/ReadResource.d.ts +62 -0
- package/dist/rest/base/ReadResource.js +69 -0
- package/dist/rest/base/ReadResource.js.map +1 -0
- package/dist/rest/callHandler.d.ts +5 -2
- package/dist/rest/callHandler.js +4 -1
- package/dist/rest/callHandler.js.map +1 -1
- package/dist/rest/index.d.ts +18 -77
- package/dist/rest/index.js +47 -120
- package/dist/rest/index.js.map +1 -1
- package/dist/rest/namespaces/_client_tree_generated.d.ts +103 -0
- package/dist/rest/namespaces/_client_tree_generated.js +171 -0
- package/dist/rest/namespaces/_client_tree_generated.js.map +1 -0
- package/dist/rest/namespaces/addresses.d.ts +3 -42
- package/dist/rest/namespaces/addresses.js +3 -50
- package/dist/rest/namespaces/addresses.js.map +1 -1
- package/dist/rest/namespaces/calling.d.ts +6 -378
- package/dist/rest/namespaces/calling.js +6 -473
- package/dist/rest/namespaces/calling.js.map +1 -1
- package/dist/rest/namespaces/calling.resources.generated.d.ts +165 -0
- package/dist/rest/namespaces/calling.resources.generated.js +477 -0
- package/dist/rest/namespaces/calling.resources.generated.js.map +1 -0
- package/dist/rest/namespaces/calling.types.generated.d.ts +2917 -0
- package/dist/rest/namespaces/calling.types.generated.js +8 -0
- package/dist/rest/namespaces/calling.types.generated.js.map +1 -0
- package/dist/rest/namespaces/chat.d.ts +4 -18
- package/dist/rest/namespaces/chat.js +4 -21
- package/dist/rest/namespaces/chat.js.map +1 -1
- package/dist/rest/namespaces/chat.resources.generated.d.ts +12 -0
- package/dist/rest/namespaces/chat.resources.generated.js +29 -0
- package/dist/rest/namespaces/chat.resources.generated.js.map +1 -0
- package/dist/rest/namespaces/chat.types.generated.d.ts +56 -0
- package/dist/rest/namespaces/chat.types.generated.js +8 -0
- package/dist/rest/namespaces/chat.types.generated.js.map +1 -0
- package/dist/rest/namespaces/datasphere.d.ts +6 -62
- package/dist/rest/namespaces/datasphere.js +6 -72
- package/dist/rest/namespaces/datasphere.js.map +1 -1
- package/dist/rest/namespaces/datasphere.resources.generated.d.ts +25 -0
- package/dist/rest/namespaces/datasphere.resources.generated.js +50 -0
- package/dist/rest/namespaces/datasphere.resources.generated.js.map +1 -0
- package/dist/rest/namespaces/datasphere.types.generated.d.ts +180 -0
- package/dist/rest/namespaces/datasphere.types.generated.js +8 -0
- package/dist/rest/namespaces/datasphere.types.generated.js.map +1 -0
- package/dist/rest/namespaces/fabric.d.ts +11 -327
- package/dist/rest/namespaces/fabric.js +14 -439
- package/dist/rest/namespaces/fabric.js.map +1 -1
- package/dist/rest/namespaces/fabric.resources.generated.d.ts +195 -0
- package/dist/rest/namespaces/fabric.resources.generated.js +399 -0
- package/dist/rest/namespaces/fabric.resources.generated.js.map +1 -0
- package/dist/rest/namespaces/fabric.types.generated.d.ts +4557 -0
- package/dist/rest/namespaces/fabric.types.generated.js +8 -0
- package/dist/rest/namespaces/fabric.types.generated.js.map +1 -0
- package/dist/rest/namespaces/fax.resources.generated.d.ts +6 -0
- package/dist/rest/namespaces/fax.resources.generated.js +14 -0
- package/dist/rest/namespaces/fax.resources.generated.js.map +1 -0
- package/dist/rest/namespaces/fax.types.generated.d.ts +131 -0
- package/dist/rest/namespaces/fax.types.generated.js +8 -0
- package/dist/rest/namespaces/fax.types.generated.js.map +1 -0
- package/dist/rest/namespaces/imported-numbers.d.ts +3 -18
- package/dist/rest/namespaces/imported-numbers.js +3 -21
- package/dist/rest/namespaces/imported-numbers.js.map +1 -1
- package/dist/rest/namespaces/logs.d.ts +10 -101
- package/dist/rest/namespaces/logs.js +10 -128
- package/dist/rest/namespaces/logs.js.map +1 -1
- package/dist/rest/namespaces/logs.resources.generated.d.ts +9 -0
- package/dist/rest/namespaces/logs.resources.generated.js +17 -0
- package/dist/rest/namespaces/logs.resources.generated.js.map +1 -0
- package/dist/rest/namespaces/logs.types.generated.d.ts +131 -0
- package/dist/rest/namespaces/logs.types.generated.js +8 -0
- package/dist/rest/namespaces/logs.types.generated.js.map +1 -0
- package/dist/rest/namespaces/lookup.d.ts +3 -25
- package/dist/rest/namespaces/lookup.js +3 -27
- package/dist/rest/namespaces/lookup.js.map +1 -1
- package/dist/rest/namespaces/message.resources.generated.d.ts +6 -0
- package/dist/rest/namespaces/message.resources.generated.js +14 -0
- package/dist/rest/namespaces/message.resources.generated.js.map +1 -0
- package/dist/rest/namespaces/message.types.generated.d.ts +122 -0
- package/dist/rest/namespaces/message.types.generated.js +8 -0
- package/dist/rest/namespaces/message.types.generated.js.map +1 -0
- package/dist/rest/namespaces/messages.resources.generated.d.ts +18 -0
- package/dist/rest/namespaces/messages.resources.generated.js +44 -0
- package/dist/rest/namespaces/messages.resources.generated.js.map +1 -0
- package/dist/rest/namespaces/messages.types.generated.d.ts +99 -0
- package/dist/rest/namespaces/messages.types.generated.js +8 -0
- package/dist/rest/namespaces/messages.types.generated.js.map +1 -0
- package/dist/rest/namespaces/mfa.d.ts +3 -42
- package/dist/rest/namespaces/mfa.js +3 -49
- package/dist/rest/namespaces/mfa.js.map +1 -1
- package/dist/rest/namespaces/number-groups.d.ts +3 -45
- package/dist/rest/namespaces/number-groups.js +3 -53
- package/dist/rest/namespaces/number-groups.js.map +1 -1
- package/dist/rest/namespaces/phone-numbers.d.ts +8 -196
- package/dist/rest/namespaces/phone-numbers.js +8 -230
- package/dist/rest/namespaces/phone-numbers.js.map +1 -1
- package/dist/rest/namespaces/project.d.ts +6 -42
- package/dist/rest/namespaces/project.js +6 -51
- package/dist/rest/namespaces/project.js.map +1 -1
- package/dist/rest/namespaces/project.resources.generated.d.ts +17 -0
- package/dist/rest/namespaces/project.resources.generated.js +44 -0
- package/dist/rest/namespaces/project.resources.generated.js.map +1 -0
- package/dist/rest/namespaces/project.types.generated.d.ts +58 -0
- package/dist/rest/namespaces/project.types.generated.js +8 -0
- package/dist/rest/namespaces/project.types.generated.js.map +1 -0
- package/dist/rest/namespaces/projects.resources.generated.d.ts +12 -0
- package/dist/rest/namespaces/projects.resources.generated.js +25 -0
- package/dist/rest/namespaces/projects.resources.generated.js.map +1 -0
- package/dist/rest/namespaces/projects.types.generated.d.ts +77 -0
- package/dist/rest/namespaces/projects.types.generated.js +8 -0
- package/dist/rest/namespaces/projects.types.generated.js.map +1 -0
- package/dist/rest/namespaces/pubsub.d.ts +4 -18
- package/dist/rest/namespaces/pubsub.js +4 -21
- package/dist/rest/namespaces/pubsub.js.map +1 -1
- package/dist/rest/namespaces/pubsub.resources.generated.d.ts +12 -0
- package/dist/rest/namespaces/pubsub.resources.generated.js +29 -0
- package/dist/rest/namespaces/pubsub.resources.generated.js.map +1 -0
- package/dist/rest/namespaces/pubsub.types.generated.d.ts +60 -0
- package/dist/rest/namespaces/pubsub.types.generated.js +8 -0
- package/dist/rest/namespaces/pubsub.types.generated.js.map +1 -0
- package/dist/rest/namespaces/queues.d.ts +3 -38
- package/dist/rest/namespaces/queues.js +3 -44
- package/dist/rest/namespaces/queues.js.map +1 -1
- package/dist/rest/namespaces/recordings.d.ts +3 -34
- package/dist/rest/namespaces/recordings.js +3 -40
- package/dist/rest/namespaces/recordings.js.map +1 -1
- package/dist/rest/namespaces/registry.d.ts +6 -137
- package/dist/rest/namespaces/registry.js +6 -173
- package/dist/rest/namespaces/registry.js.map +1 -1
- package/dist/rest/namespaces/relay-rest.resources.generated.d.ts +168 -0
- package/dist/rest/namespaces/relay-rest.resources.generated.js +430 -0
- package/dist/rest/namespaces/relay-rest.resources.generated.js.map +1 -0
- package/dist/rest/namespaces/relay-rest.types.generated.d.ts +1906 -0
- package/dist/rest/namespaces/relay-rest.types.generated.js +8 -0
- package/dist/rest/namespaces/relay-rest.types.generated.js.map +1 -0
- package/dist/rest/namespaces/short-codes.d.ts +3 -35
- package/dist/rest/namespaces/short-codes.js +3 -41
- package/dist/rest/namespaces/short-codes.js.map +1 -1
- package/dist/rest/namespaces/sip-profile.d.ts +3 -24
- package/dist/rest/namespaces/sip-profile.js +3 -29
- package/dist/rest/namespaces/sip-profile.js.map +1 -1
- package/dist/rest/namespaces/verified-callers.d.ts +3 -29
- package/dist/rest/namespaces/verified-callers.js +3 -34
- package/dist/rest/namespaces/verified-callers.js.map +1 -1
- package/dist/rest/namespaces/video.d.ts +10 -227
- package/dist/rest/namespaces/video.js +10 -288
- package/dist/rest/namespaces/video.js.map +1 -1
- package/dist/rest/namespaces/video.resources.generated.d.ts +81 -0
- package/dist/rest/namespaces/video.resources.generated.js +171 -0
- package/dist/rest/namespaces/video.resources.generated.js.map +1 -0
- package/dist/rest/namespaces/video.types.generated.d.ts +771 -0
- package/dist/rest/namespaces/video.types.generated.js +8 -0
- package/dist/rest/namespaces/video.types.generated.js.map +1 -0
- package/dist/rest/namespaces/voice.resources.generated.d.ts +9 -0
- package/dist/rest/namespaces/voice.resources.generated.js +17 -0
- package/dist/rest/namespaces/voice.resources.generated.js.map +1 -0
- package/dist/rest/namespaces/voice.types.generated.d.ts +214 -0
- package/dist/rest/namespaces/voice.types.generated.js +8 -0
- package/dist/rest/namespaces/voice.types.generated.js.map +1 -0
- package/dist/rest/pagination.d.ts +5 -1
- package/dist/rest/pagination.js +40 -20
- package/dist/rest/pagination.js.map +1 -1
- package/dist/rest/types.d.ts +21 -3
- package/dist/schema.json +299 -98
- package/dist/skills/SkillBase.d.ts +111 -21
- package/dist/skills/SkillBase.js +100 -17
- package/dist/skills/SkillBase.js.map +1 -1
- package/dist/skills/SkillManager.d.ts +66 -13
- package/dist/skills/SkillManager.js +101 -20
- package/dist/skills/SkillManager.js.map +1 -1
- package/dist/skills/SkillName.d.ts +44 -0
- package/dist/skills/SkillName.js +2 -0
- package/dist/skills/SkillName.js.map +1 -0
- package/dist/skills/SkillRegistry.d.ts +22 -11
- package/dist/skills/SkillRegistry.js +47 -17
- package/dist/skills/SkillRegistry.js.map +1 -1
- package/dist/skills/builtin/api_ninjas_trivia.d.ts +3 -1
- package/dist/skills/builtin/api_ninjas_trivia.js +18 -6
- package/dist/skills/builtin/api_ninjas_trivia.js.map +1 -1
- package/dist/skills/builtin/ask_claude.d.ts +14 -4
- package/dist/skills/builtin/ask_claude.js +36 -14
- package/dist/skills/builtin/ask_claude.js.map +1 -1
- package/dist/skills/builtin/claude_skills.d.ts +3 -1
- package/dist/skills/builtin/claude_skills.js +19 -15
- package/dist/skills/builtin/claude_skills.js.map +1 -1
- package/dist/skills/builtin/custom_skills.d.ts +10 -3
- package/dist/skills/builtin/custom_skills.js +26 -9
- package/dist/skills/builtin/custom_skills.js.map +1 -1
- package/dist/skills/builtin/datasphere.d.ts +5 -3
- package/dist/skills/builtin/datasphere.js +21 -22
- package/dist/skills/builtin/datasphere.js.map +1 -1
- package/dist/skills/builtin/datasphere_serverless.d.ts +12 -1
- package/dist/skills/builtin/datasphere_serverless.js +17 -6
- package/dist/skills/builtin/datasphere_serverless.js.map +1 -1
- package/dist/skills/builtin/datetime.d.ts +3 -1
- package/dist/skills/builtin/datetime.js +11 -7
- package/dist/skills/builtin/datetime.js.map +1 -1
- package/dist/skills/builtin/google_maps.d.ts +29 -14
- package/dist/skills/builtin/google_maps.js +89 -269
- package/dist/skills/builtin/google_maps.js.map +1 -1
- package/dist/skills/builtin/index.d.ts +8 -6
- package/dist/skills/builtin/index.js +8 -6
- package/dist/skills/builtin/index.js.map +1 -1
- package/dist/skills/builtin/info_gatherer.d.ts +4 -2
- package/dist/skills/builtin/info_gatherer.js +20 -12
- package/dist/skills/builtin/info_gatherer.js.map +1 -1
- package/dist/skills/builtin/joke.d.ts +16 -6
- package/dist/skills/builtin/joke.js +54 -37
- package/dist/skills/builtin/joke.js.map +1 -1
- package/dist/skills/builtin/math.d.ts +3 -1
- package/dist/skills/builtin/math.js +14 -9
- package/dist/skills/builtin/math.js.map +1 -1
- package/dist/skills/builtin/mcp_gateway.d.ts +34 -5
- package/dist/skills/builtin/mcp_gateway.js +77 -46
- package/dist/skills/builtin/mcp_gateway.js.map +1 -1
- package/dist/skills/builtin/native_vector_search.d.ts +19 -5
- package/dist/skills/builtin/native_vector_search.js +179 -61
- package/dist/skills/builtin/native_vector_search.js.map +1 -1
- package/dist/skills/builtin/play_background_file.d.ts +21 -15
- package/dist/skills/builtin/play_background_file.js +43 -122
- package/dist/skills/builtin/play_background_file.js.map +1 -1
- package/dist/skills/builtin/spider.d.ts +42 -4
- package/dist/skills/builtin/spider.js +277 -104
- package/dist/skills/builtin/spider.js.map +1 -1
- package/dist/skills/builtin/swml_transfer.d.ts +14 -3
- package/dist/skills/builtin/swml_transfer.js +45 -24
- package/dist/skills/builtin/swml_transfer.js.map +1 -1
- package/dist/skills/builtin/weather_api.d.ts +24 -13
- package/dist/skills/builtin/weather_api.js +38 -30
- package/dist/skills/builtin/weather_api.js.map +1 -1
- package/dist/skills/builtin/web_search.d.ts +48 -10
- package/dist/skills/builtin/web_search.js +294 -100
- package/dist/skills/builtin/web_search.js.map +1 -1
- package/dist/skills/builtin/wikipedia_search.d.ts +4 -2
- package/dist/skills/builtin/wikipedia_search.js +14 -13
- package/dist/skills/builtin/wikipedia_search.js.map +1 -1
- package/dist/skills/index.d.ts +3 -2
- package/dist/skills/index.js +1 -1
- package/dist/skills/index.js.map +1 -1
- package/dist/swml_verbs_generated.d.ts +2824 -0
- package/dist/swml_verbs_generated.js +12 -0
- package/dist/swml_verbs_generated.js.map +1 -0
- package/dist/types.d.ts +59 -6
- package/dist/web.d.ts +27 -0
- package/dist/web.js +20 -0
- package/dist/web.js.map +1 -0
- package/docs/agent-guide.md +1034 -0
- package/docs/ai_chat.md +560 -0
- package/docs/api-reference.md +3641 -0
- package/docs/architecture.md +846 -0
- package/docs/bedrock_agent.md +411 -0
- package/docs/cli-guide.md +403 -0
- package/docs/cloud_functions_guide.md +399 -0
- package/docs/configuration.md +548 -0
- package/docs/contexts-guide.md +884 -0
- package/docs/datamap-guide.md +1207 -0
- package/docs/developer_pain_points.md +548 -0
- package/docs/llm_parameters.md +298 -0
- package/docs/mcp_gateway_reference.md +354 -0
- package/docs/mcp_integration.md +162 -0
- package/docs/pgi_agent_guide.md +1820 -0
- package/docs/prefabs-guide.md +815 -0
- package/docs/programmatically_governed_inference.md +301 -0
- package/docs/sdk_features.md +501 -0
- package/docs/security.md +559 -0
- package/docs/serverless-guide.md +520 -0
- package/docs/skills-guide.md +1223 -0
- package/docs/skills-system.md +405 -0
- package/docs/skills_parameter_schema.md +417 -0
- package/docs/swaig-reference.md +1986 -0
- package/docs/swml_service_guide.md +573 -0
- package/docs/third_party_skills.md +410 -0
- package/docs/web_service.md +666 -0
- package/examples/README.md +202 -0
- package/examples/advanced-datamap.ts +108 -0
- package/examples/advanced-dynamic-config.ts +70 -0
- package/examples/auto-vivified.ts +95 -0
- package/examples/call-flow.ts +65 -0
- package/examples/comprehensive-dynamic.ts +125 -0
- package/examples/contexts-steps.ts +65 -0
- package/examples/custom-path.ts +45 -0
- package/examples/datamap-tools.ts +51 -0
- package/examples/datasphere-multi-instance.ts +66 -0
- package/examples/datasphere-serverless-env.ts +87 -0
- package/examples/datasphere-webhook-env.ts +65 -0
- package/examples/datasphere.ts +56 -0
- package/examples/declarative.ts +100 -0
- package/examples/dynamic-config.ts +54 -0
- package/examples/dynamic-info-gatherer.ts +69 -0
- package/examples/dynamic-swml-service.ts +67 -0
- package/examples/gather-info.ts +95 -0
- package/examples/gather-per-question-functions-demo.ts +139 -0
- package/examples/joke-agent.ts +34 -0
- package/examples/kubernetes-agent.ts +45 -0
- package/examples/llm-params.ts +75 -0
- package/examples/mcp-agent.ts +89 -0
- package/examples/mcp-gateway.ts +81 -0
- package/examples/multi-agent.ts +80 -0
- package/examples/multi-endpoint.ts +79 -0
- package/examples/pgi/case-domain.ts +114 -0
- package/examples/pgi/serve.ts +16 -0
- package/examples/pgi/support-agent.ts +265 -0
- package/examples/pom-prompt.ts +70 -0
- package/examples/prefab-concierge.ts +42 -0
- package/examples/prefab-faq.ts +58 -0
- package/examples/prefab-info-gatherer.ts +33 -0
- package/examples/prefab-receptionist.ts +36 -0
- package/examples/prefab-survey.ts +69 -0
- package/examples/quickstart-agent.ts +29 -0
- package/examples/quickstart-relay.ts +25 -0
- package/examples/quickstart-rest.ts +25 -0
- package/examples/record-call.ts +65 -0
- package/examples/relay-demo.ts +33 -0
- package/examples/room-and-sip.ts +93 -0
- package/examples/serverless-lambda.ts +43 -0
- package/examples/session-state.ts +83 -0
- package/examples/simple-agent.ts +36 -0
- package/examples/simple-static.ts +29 -0
- package/examples/skills-demo.ts +41 -0
- package/examples/step-function-inheritance-demo.ts +124 -0
- package/examples/swaig-features.ts +193 -0
- package/examples/swml-service-routing.ts +66 -0
- package/examples/swml-service.ts +38 -0
- package/examples/swmlservice_ai_sidecar.ts +104 -0
- package/examples/swmlservice_swaig_standalone.ts +79 -0
- package/examples/tap.ts +67 -0
- package/examples/typed-tools.ts +68 -0
- package/examples/verb-methods.ts +45 -0
- package/examples/web-search-multi-instance.ts +75 -0
- package/examples/web-search.ts +38 -0
- package/examples/wikipedia.ts +36 -0
- package/livewire/README.md +164 -0
- package/livewire/docs/migration-guide.md +251 -0
- package/livewire/examples/livewire-basic-agent.ts +74 -0
- package/livewire/examples/livewire-handoff.ts +196 -0
- package/livewire/examples/livewire-multi-tool.ts +121 -0
- package/package.json +85 -13
- package/relay/README.md +101 -0
- package/relay/docs/call-methods.md +622 -0
- package/relay/docs/client-reference.md +281 -0
- package/relay/docs/events.md +193 -0
- package/relay/docs/getting-started.md +221 -0
- package/relay/docs/guide.md +386 -0
- package/relay/docs/messaging.md +246 -0
- package/relay/examples/relay-inbound.ts +66 -0
- package/relay/examples/relay-messaging.ts +74 -0
- package/relay/examples/relay-outbound.ts +76 -0
- package/rest/README.md +141 -0
- package/rest/docs/calling.md +313 -0
- package/rest/docs/client-reference.md +149 -0
- package/rest/docs/fabric.md +192 -0
- package/rest/docs/getting-started.md +138 -0
- package/rest/docs/guide.md +421 -0
- package/rest/docs/namespaces.md +367 -0
- package/rest/docs/phone-binding.md +116 -0
- package/rest/examples/rest-10dlc-registration.ts +177 -0
- package/rest/examples/rest-bind-phone-to-swml-webhook.ts +66 -0
- package/rest/examples/rest-calling-ivr-and-ai.ts +136 -0
- package/rest/examples/rest-calling-play-and-record.ts +98 -0
- package/rest/examples/rest-client.ts +59 -0
- package/rest/examples/rest-datasphere-search.ts +81 -0
- package/rest/examples/rest-fabric-conferences-and-routing.ts +147 -0
- package/rest/examples/rest-fabric-subscribers-and-sip.ts +106 -0
- package/rest/examples/rest-fabric-swml-and-callflows.ts +101 -0
- package/rest/examples/rest-manage-resources.ts +64 -0
- package/rest/examples/rest-phone-number-management.ts +200 -0
- package/rest/examples/rest-queues-mfa-and-recordings.ts +143 -0
- package/rest/examples/rest-video-rooms.ts +186 -0
- package/tutorial/fred/fred.ts +218 -0
- package/tutorial/fred/tutorial/01-introduction.md +141 -0
- package/tutorial/fred/tutorial/02-setup.md +304 -0
- package/tutorial/fred/tutorial/03-basic-agent.md +284 -0
- package/tutorial/fred/tutorial/04-wikipedia-skill.md +298 -0
- package/tutorial/fred/tutorial/05-custom-functions.md +347 -0
- package/tutorial/fred/tutorial/06-running-testing.md +642 -0
- package/tutorial/fred/tutorial/README.md +56 -0
- package/tutorial/fred/tutorial/appendix-complete-code.md +632 -0
- package/tutorial/fred/tutorial/appendix-docker-deployment.md +504 -0
- package/tutorial/full-guardrails-agent/handlers.ts +436 -0
- package/tutorial/full-guardrails-agent/penny.ts +305 -0
- package/tutorial/full-guardrails-agent/reservations.ts +1109 -0
- package/tutorial/full-guardrails-agent/tutorial/01-why-guardrails.md +149 -0
- package/tutorial/full-guardrails-agent/tutorial/02-design-first.md +139 -0
- package/tutorial/full-guardrails-agent/tutorial/03-rules-first.md +422 -0
- package/tutorial/full-guardrails-agent/tutorial/04-the-shell.md +238 -0
- package/tutorial/full-guardrails-agent/tutorial/05-steps-and-scoping.md +247 -0
- package/tutorial/full-guardrails-agent/tutorial/06-tools-that-decide.md +467 -0
- package/tutorial/full-guardrails-agent/tutorial/07-gather-and-projection.md +160 -0
- package/tutorial/full-guardrails-agent/tutorial/08-the-verification-gate.md +333 -0
- package/tutorial/full-guardrails-agent/tutorial/09-people-and-endings.md +313 -0
- package/tutorial/full-guardrails-agent/tutorial/10-testing-and-running.md +387 -0
- package/tutorial/full-guardrails-agent/tutorial/README.md +106 -0
- package/tutorial/full-guardrails-agent/tutorial/appendix-complete-code.md +2207 -0
- package/tutorial/full-guardrails-agent/tutorial/appendix-deployment.md +191 -0
- package/tutorial/full-guardrails-agent/tutorial/appendix-technique-map.md +117 -0
- package/tutorial/full-guardrails-agent/workflow.ts +219 -0
- package/tutorial/multi_agents/README.md +175 -0
- package/tutorial/multi_agents/advanced_agent.ts +395 -0
- package/tutorial/multi_agents/extending_agents.ts +641 -0
- package/tutorial/multi_agents/knowledge.ts +59 -0
- package/tutorial/multi_agents/lesson1_first_agent.md +368 -0
- package/tutorial/multi_agents/lesson2_knowledge_bases.md +404 -0
- package/tutorial/multi_agents/lesson3_multi_agent_systems.md +621 -0
- package/tutorial/multi_agents/lesson4_advanced_features.md +805 -0
- package/tutorial/multi_agents/lesson5_extending_agents.md +856 -0
- package/tutorial/multi_agents/pc_builder.ts +529 -0
- package/tutorial/multi_agents/sales_agent.ts +88 -0
- package/tutorial/multi_agents/sales_agent_with_search.ts +116 -0
- package/tutorial/multi_agents/sales_knowledge.md +139 -0
- package/tutorial/multi_agents/support_knowledge.md +256 -0
- package/dist/cli/mock-data.d.ts +0 -37
- package/dist/cli/mock-data.js +0 -80
- package/dist/cli/mock-data.js.map +0 -1
- package/dist/generateVerbTypes.d.ts +0 -11
- package/dist/generateVerbTypes.js +0 -265
- package/dist/generateVerbTypes.js.map +0 -1
- package/dist/rest/namespaces/compat.d.ts +0 -585
- package/dist/rest/namespaces/compat.js +0 -735
- package/dist/rest/namespaces/compat.js.map +0 -1
|
@@ -0,0 +1,1986 @@
|
|
|
1
|
+
# FunctionResult Reference
|
|
2
|
+
|
|
3
|
+
This page is the API reference for the `FunctionResult` class in the SignalWire AI Agents TypeScript SDK. `FunctionResult` is what a SWAIG tool handler returns.
|
|
4
|
+
|
|
5
|
+
The examples on this page assume this import and agent:
|
|
6
|
+
|
|
7
|
+
<!-- snippet-setup -->
|
|
8
|
+
```ts
|
|
9
|
+
import { AgentBase, FunctionResult } from '@signalwire/sdk';
|
|
10
|
+
|
|
11
|
+
const agent = new AgentBase({ name: 'support-agent' });
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
---
|
|
15
|
+
|
|
16
|
+
## Table of Contents
|
|
17
|
+
|
|
18
|
+
The reference groups the methods by what they do:
|
|
19
|
+
|
|
20
|
+
- [Overview](#overview)
|
|
21
|
+
- [Basic usage](#basic-usage)
|
|
22
|
+
- [Writing the response](#writing-the-response)
|
|
23
|
+
- [Returning a result from a handler](#returning-a-result-from-a-handler)
|
|
24
|
+
- [How serialization works](#how-serialization-works)
|
|
25
|
+
- [Properties](#properties)
|
|
26
|
+
- [Core Methods](#core-methods)
|
|
27
|
+
- [constructor](#constructor)
|
|
28
|
+
- [setResponse](#setresponse)
|
|
29
|
+
- [setToolResponse](#settoolresponse)
|
|
30
|
+
- [setPostProcess](#setpostprocess)
|
|
31
|
+
- [addAction](#addaction)
|
|
32
|
+
- [addActions](#addactions)
|
|
33
|
+
- [toDict](#todict)
|
|
34
|
+
- [toJSON](#tojson)
|
|
35
|
+
- [Call Control](#call-control)
|
|
36
|
+
- [connect](#connect)
|
|
37
|
+
- [swmlTransfer](#swmltransfer)
|
|
38
|
+
- [hangup](#hangup)
|
|
39
|
+
- [hold](#hold)
|
|
40
|
+
- [waitForUser](#waitforuser)
|
|
41
|
+
- [stop](#stop)
|
|
42
|
+
- [Audio](#audio)
|
|
43
|
+
- [say](#say)
|
|
44
|
+
- [playBackgroundFile](#playbackgroundfile)
|
|
45
|
+
- [stopBackgroundFile](#stopbackgroundfile)
|
|
46
|
+
- [changeVoice](#changevoice)
|
|
47
|
+
- [Speech](#speech)
|
|
48
|
+
- [addDynamicHints](#adddynamichints)
|
|
49
|
+
- [clearDynamicHints](#cleardynamichints)
|
|
50
|
+
- [setEndOfSpeechTimeout](#setendofspeechtimeout)
|
|
51
|
+
- [setSpeechEventTimeout](#setspeecheventtimeout)
|
|
52
|
+
- [Data Management](#data-management)
|
|
53
|
+
- [updateGlobalData](#updateglobaldata)
|
|
54
|
+
- [removeGlobalData](#removeglobaldata)
|
|
55
|
+
- [setSemanticState](#setsemanticstate)
|
|
56
|
+
- [setMetadata](#setmetadata)
|
|
57
|
+
- [removeMetadata](#removemetadata)
|
|
58
|
+
- [SWML Actions](#swml-actions)
|
|
59
|
+
- [executeSwml](#executeswml)
|
|
60
|
+
- [switchContext](#switchcontext)
|
|
61
|
+
- [swmlChangeStep](#swmlchangestep)
|
|
62
|
+
- [swmlChangeContext](#swmlchangecontext)
|
|
63
|
+
- [swmlUserEvent](#swmluserevent)
|
|
64
|
+
- [Function Control](#function-control)
|
|
65
|
+
- [toggleFunctions](#togglefunctions)
|
|
66
|
+
- [enableFunctionsOnTimeout](#enablefunctionsontimeout)
|
|
67
|
+
- [updateSettings](#updatesettings)
|
|
68
|
+
- [User Input and History](#user-input-and-history)
|
|
69
|
+
- [simulateUserInput](#simulateuserinput)
|
|
70
|
+
- [enableExtensiveData](#enableextensivedata)
|
|
71
|
+
- [replaceInHistory](#replaceinhistory)
|
|
72
|
+
- [Communication](#communication)
|
|
73
|
+
- [sendSms](#sendsms)
|
|
74
|
+
- [recordCall](#recordcall)
|
|
75
|
+
- [stopRecordCall](#stoprecordcall)
|
|
76
|
+
- [tap](#tap)
|
|
77
|
+
- [stopTap](#stoptap)
|
|
78
|
+
- [Rooms and Conferencing](#rooms-and-conferencing)
|
|
79
|
+
- [joinRoom](#joinroom)
|
|
80
|
+
- [sipRefer](#siprefer)
|
|
81
|
+
- [joinConference](#joinconference)
|
|
82
|
+
- [RPC](#rpc)
|
|
83
|
+
- [executeRpc](#executerpc)
|
|
84
|
+
- [rpcDial](#rpcdial)
|
|
85
|
+
- [rpcAiMessage](#rpcaimessage)
|
|
86
|
+
- [rpcAiGlobalData](#rpcaiglobaldata)
|
|
87
|
+
- [rpcAiUnhold](#rpcaiunhold)
|
|
88
|
+
- [Payments](#payments)
|
|
89
|
+
- [pay](#pay)
|
|
90
|
+
- [createPaymentPrompt (static)](#createpaymentprompt-static)
|
|
91
|
+
- [createPaymentAction (static)](#createpaymentaction-static)
|
|
92
|
+
- [createPaymentParameter (static)](#createpaymentparameter-static)
|
|
93
|
+
- [Full payment example](#full-payment-example)
|
|
94
|
+
- [Fluent Chaining](#fluent-chaining)
|
|
95
|
+
|
|
96
|
+
---
|
|
97
|
+
|
|
98
|
+
## Overview
|
|
99
|
+
|
|
100
|
+
`FunctionResult` is the return type for SWAIG tool handlers. It carries two things back to SignalWire:
|
|
101
|
+
|
|
102
|
+
1. **Response**: context for the model. The model reads it and decides what to say next. It isn't played to the caller.
|
|
103
|
+
2. **Actions**: an ordered list of structured commands (hangup, connect, send SMS and others) that the platform carries out.
|
|
104
|
+
|
|
105
|
+
A handler builds a `FunctionResult`, adds any actions, and returns it. The SDK serializes it with `toDict()` and sends it to SignalWire as the response to the `/swaig` request.
|
|
106
|
+
|
|
107
|
+
### Basic usage
|
|
108
|
+
|
|
109
|
+
This tool records a transfer reason and connects the caller to a support line:
|
|
110
|
+
|
|
111
|
+
```typescript
|
|
112
|
+
agent.defineTool({
|
|
113
|
+
name: 'transfer_to_support',
|
|
114
|
+
description: 'Transfer the caller to a human support agent',
|
|
115
|
+
parameters: {},
|
|
116
|
+
handler: () => {
|
|
117
|
+
return new FunctionResult('Tell the caller you are connecting them to support.', true)
|
|
118
|
+
.connect('+15551234567');
|
|
119
|
+
},
|
|
120
|
+
});
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
The second constructor argument turns on post-processing, so the model gets one more turn to tell the caller before the transfer runs.
|
|
124
|
+
|
|
125
|
+
### Writing the response
|
|
126
|
+
|
|
127
|
+
The response is context for the model, not a script. The model reads it, then decides what to say. It can hold facts, an instruction, or both.
|
|
128
|
+
|
|
129
|
+
The clearest form keeps facts and instruction apart. Pass them as the constructor's `toolResult` and `toolPrompt`, or with [setToolResponse](#settoolresponse), and the SDK sends `{ tool_result, tool_prompt }`:
|
|
130
|
+
|
|
131
|
+
```typescript
|
|
132
|
+
const structured = new FunctionResult(
|
|
133
|
+
undefined,
|
|
134
|
+
false,
|
|
135
|
+
'Order 1234 shipped Tuesday.',
|
|
136
|
+
'Tell the caller when their order shipped.',
|
|
137
|
+
);
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
A plain string works too, as facts or as an instruction:
|
|
141
|
+
|
|
142
|
+
```typescript
|
|
143
|
+
const facts = new FunctionResult('Order 1234 shipped Tuesday.');
|
|
144
|
+
const instruction = new FunctionResult('Tell the caller their order shipped Tuesday.');
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
Avoid a line written for the caller, such as `'Your order shipped Tuesday.'`. The model tends to repeat it, but it interprets the line rather than speaking it, so the wording can drift or merge with other context. To speak exact words, use [say](#say).
|
|
148
|
+
|
|
149
|
+
### Returning a result from a handler
|
|
150
|
+
|
|
151
|
+
A tool handler receives `(args, rawData, agent)`. `args` holds the parsed arguments, and `rawData` is the full SWAIG request body. `agent` is the agent the request was configured on: the per-request copy when a dynamic config callback or `addPerCallConfig()` is in use.
|
|
152
|
+
|
|
153
|
+
The SDK handles these return values:
|
|
154
|
+
|
|
155
|
+
- A `FunctionResult`, or a promise that resolves to one: serialized with `toDict()`.
|
|
156
|
+
- A plain object with a `response` key: sent as it is.
|
|
157
|
+
- A plain object without a `response` key: replaced by `{ response: "Function completed successfully" }`.
|
|
158
|
+
- Any other value, such as a string: converted to a string and sent as the response, with a logged warning.
|
|
159
|
+
|
|
160
|
+
If the handler throws, the SDK logs the error. It then returns the result of the tool's `onError` hook, or of the agent's `onError()` handler, when either returns a `FunctionResult`. Otherwise it returns the tool's `errorMessage`, or a default apology message.
|
|
161
|
+
|
|
162
|
+
Tools registered with `defineTool()` are secure by default. The SWML the agent renders gives each secure tool a per-call token (`__token`). The agent runs the handler only when a `/swaig` request carries a valid token for that function and call. Otherwise it returns a refusal response. Set `swaigSecret` or `SIGNALWIRE_SWAIG_SECRET` so tokens survive a restart and work across replicas. For details, see [Secure Tools (HMAC Tokens)](security.md#secure-tools-hmac-tokens).
|
|
163
|
+
|
|
164
|
+
### How serialization works
|
|
165
|
+
|
|
166
|
+
When the handler returns, the SDK calls `toDict()` to produce a plain object:
|
|
167
|
+
|
|
168
|
+
```typescript
|
|
169
|
+
const result = new FunctionResult('Order 1234 is cancelled.').hangup();
|
|
170
|
+
console.log(result.toDict());
|
|
171
|
+
// { response: 'Order 1234 is cancelled.', action: [ { hangup: true } ] }
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
If the response is empty and there are no actions, `toDict()` returns `{ response: "Action completed." }`, so the model always receives a response.
|
|
175
|
+
|
|
176
|
+
### Properties
|
|
177
|
+
|
|
178
|
+
The class has three public properties:
|
|
179
|
+
|
|
180
|
+
| Property | Type | Description |
|
|
181
|
+
|---------------|-----------------------------|--------------------------------------------------------------|
|
|
182
|
+
| `response` | `string` | The string response. Empty when the structured form is set. |
|
|
183
|
+
| `action` | `Record<string, unknown>[]` | Ordered list of action objects. |
|
|
184
|
+
| `postProcess` | `boolean` | When `true`, the model takes one more turn before the actions run. |
|
|
185
|
+
|
|
186
|
+
## Core Methods
|
|
187
|
+
|
|
188
|
+
### constructor
|
|
189
|
+
|
|
190
|
+
Create a new `FunctionResult`.
|
|
191
|
+
|
|
192
|
+
<!-- snippet: no-compile API signature reference, not runnable code -->
|
|
193
|
+
```typescript
|
|
194
|
+
constructor(
|
|
195
|
+
response?: string | { tool_result?: string; tool_prompt?: string },
|
|
196
|
+
postProcess?: boolean,
|
|
197
|
+
toolResult?: string,
|
|
198
|
+
toolPrompt?: string,
|
|
199
|
+
)
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
| Parameter | Type | Default | Description |
|
|
203
|
+
|---------------|-----------------------------------------------------|---------|--------------------------------------------------------------|
|
|
204
|
+
| `response` | `string \| { tool_result?: string; tool_prompt?: string }` | `''` | The response: a string, or the structured form. |
|
|
205
|
+
| `postProcess` | `boolean` | `false` | Whether the model takes one more turn before the actions run. |
|
|
206
|
+
| `toolResult` | `string` | none | Sets `tool_result`, as [setToolResponse](#settoolresponse) does. |
|
|
207
|
+
| `toolPrompt` | `string` | none | Sets `tool_prompt`, as [setToolResponse](#settoolresponse) does. |
|
|
208
|
+
|
|
209
|
+
When `toolResult` or `toolPrompt` is given, the structured form replaces a string `response`.
|
|
210
|
+
|
|
211
|
+
**Returns:** A new `FunctionResult` instance.
|
|
212
|
+
|
|
213
|
+
**Example:**
|
|
214
|
+
|
|
215
|
+
```typescript
|
|
216
|
+
// Empty result (serializes as "Action completed.")
|
|
217
|
+
const r1 = new FunctionResult();
|
|
218
|
+
|
|
219
|
+
// Facts as a string
|
|
220
|
+
const r2 = new FunctionResult('Order 1234 was placed.');
|
|
221
|
+
|
|
222
|
+
// Post-processing on, so the model speaks before the actions run
|
|
223
|
+
const r3 = new FunctionResult('Tell the caller the payment is being processed.', true);
|
|
224
|
+
|
|
225
|
+
// Structured form as the first argument
|
|
226
|
+
const r4 = new FunctionResult({
|
|
227
|
+
tool_result: 'Payment declined.',
|
|
228
|
+
tool_prompt: 'Ask the caller for another card.',
|
|
229
|
+
});
|
|
230
|
+
```
|
|
231
|
+
|
|
232
|
+
### setResponse
|
|
233
|
+
|
|
234
|
+
Set or replace the string response. It also clears a structured response set earlier.
|
|
235
|
+
|
|
236
|
+
<!-- snippet: no-compile API signature reference, not runnable code -->
|
|
237
|
+
```typescript
|
|
238
|
+
setResponse(response: string): this
|
|
239
|
+
```
|
|
240
|
+
|
|
241
|
+
| Parameter | Type | Description |
|
|
242
|
+
|------------|----------|----------------------------------------|
|
|
243
|
+
| `response` | `string` | The new response: facts or an instruction. |
|
|
244
|
+
|
|
245
|
+
**Returns:** `this` for chaining.
|
|
246
|
+
|
|
247
|
+
**Example:**
|
|
248
|
+
|
|
249
|
+
```typescript
|
|
250
|
+
const result = new FunctionResult()
|
|
251
|
+
.setResponse('The account balance is $42.50.');
|
|
252
|
+
```
|
|
253
|
+
|
|
254
|
+
### setToolResponse
|
|
255
|
+
|
|
256
|
+
Set the structured response, which keeps facts and instruction apart. The SDK sends `response` as `{ tool_result, tool_prompt }`, with only the fields you pass. It replaces any string response.
|
|
257
|
+
|
|
258
|
+
<!-- snippet: no-compile API signature reference, not runnable code -->
|
|
259
|
+
```typescript
|
|
260
|
+
setToolResponse(toolResult?: string, toolPrompt?: string): this
|
|
261
|
+
```
|
|
262
|
+
|
|
263
|
+
| Parameter | Type | Description |
|
|
264
|
+
|--------------|----------|----------------------------------------------------------------------|
|
|
265
|
+
| `toolResult` | `string` | What the tool did or found: facts for the model to reason from. |
|
|
266
|
+
| `toolPrompt` | `string` | What the model should do next: an instruction. |
|
|
267
|
+
|
|
268
|
+
**Returns:** `this` for chaining.
|
|
269
|
+
|
|
270
|
+
**Example:**
|
|
271
|
+
|
|
272
|
+
```typescript
|
|
273
|
+
const result = new FunctionResult()
|
|
274
|
+
.setToolResponse('3 seats left on the 7:40 flight.', 'Tell the caller how many seats are left.');
|
|
275
|
+
console.log(result.toDict());
|
|
276
|
+
// {
|
|
277
|
+
// response: {
|
|
278
|
+
// tool_result: '3 seats left on the 7:40 flight.',
|
|
279
|
+
// tool_prompt: 'Tell the caller how many seats are left.'
|
|
280
|
+
// }
|
|
281
|
+
// }
|
|
282
|
+
```
|
|
283
|
+
|
|
284
|
+
### setPostProcess
|
|
285
|
+
|
|
286
|
+
Enable or disable post-processing.
|
|
287
|
+
|
|
288
|
+
With post-processing on, the model takes one more turn before the actions run. Use it when the caller must hear something before an action takes effect, such as a hangup, hold or transfer. The SDK includes `post_process: true` in the result only when there are actions.
|
|
289
|
+
|
|
290
|
+
<!-- snippet: no-compile API signature reference, not runnable code -->
|
|
291
|
+
```typescript
|
|
292
|
+
setPostProcess(postProcess: boolean): this
|
|
293
|
+
```
|
|
294
|
+
|
|
295
|
+
| Parameter | Type | Description |
|
|
296
|
+
|---------------|-----------|------------------------------------------|
|
|
297
|
+
| `postProcess` | `boolean` | Whether to enable post-processing. |
|
|
298
|
+
|
|
299
|
+
**Returns:** `this` for chaining.
|
|
300
|
+
|
|
301
|
+
**Example:**
|
|
302
|
+
|
|
303
|
+
```typescript
|
|
304
|
+
const result = new FunctionResult('Tell the caller goodbye.')
|
|
305
|
+
.setPostProcess(true)
|
|
306
|
+
.hangup();
|
|
307
|
+
// The model gets one more turn to say goodbye, then the hangup runs.
|
|
308
|
+
```
|
|
309
|
+
|
|
310
|
+
### addAction
|
|
311
|
+
|
|
312
|
+
Append a single named action to the action list. Most helper methods use it. Use it directly for an action that has no helper.
|
|
313
|
+
|
|
314
|
+
<!-- snippet: no-compile API signature reference, not runnable code -->
|
|
315
|
+
```typescript
|
|
316
|
+
addAction(name: string, data: unknown): this
|
|
317
|
+
```
|
|
318
|
+
|
|
319
|
+
| Parameter | Type | Description |
|
|
320
|
+
|-----------|-----------|-----------------------------------------|
|
|
321
|
+
| `name` | `string` | The action name (for example `"say"`). |
|
|
322
|
+
| `data` | `unknown` | The action payload. |
|
|
323
|
+
|
|
324
|
+
**Returns:** `this` for chaining.
|
|
325
|
+
|
|
326
|
+
**Example:**
|
|
327
|
+
|
|
328
|
+
```typescript
|
|
329
|
+
const result = new FunctionResult('Order 1234 is confirmed.')
|
|
330
|
+
.addAction('say', 'Your order is confirmed.');
|
|
331
|
+
// action: [{ say: "Your order is confirmed." }], the same as .say(...)
|
|
332
|
+
```
|
|
333
|
+
|
|
334
|
+
### addActions
|
|
335
|
+
|
|
336
|
+
Append several action objects at once. Each object maps an action name to its payload.
|
|
337
|
+
|
|
338
|
+
<!-- snippet: no-compile API signature reference, not runnable code -->
|
|
339
|
+
```typescript
|
|
340
|
+
addActions(actions: Record<string, unknown>[]): this
|
|
341
|
+
```
|
|
342
|
+
|
|
343
|
+
| Parameter | Type | Description |
|
|
344
|
+
|-----------|-----------------------------|------------------------------------|
|
|
345
|
+
| `actions` | `Record<string, unknown>[]` | Array of action objects to append. |
|
|
346
|
+
|
|
347
|
+
**Returns:** `this` for chaining.
|
|
348
|
+
|
|
349
|
+
**Example:**
|
|
350
|
+
|
|
351
|
+
```typescript
|
|
352
|
+
const result = new FunctionResult('The survey is complete.')
|
|
353
|
+
.addActions([
|
|
354
|
+
{ say: 'Thank you for taking the survey.' },
|
|
355
|
+
{ hangup: true },
|
|
356
|
+
]);
|
|
357
|
+
```
|
|
358
|
+
|
|
359
|
+
### toDict
|
|
360
|
+
|
|
361
|
+
Serialize the result to a plain object in the SWAIG response format.
|
|
362
|
+
|
|
363
|
+
<!-- snippet: no-compile API signature reference, not runnable code -->
|
|
364
|
+
```typescript
|
|
365
|
+
toDict(): {
|
|
366
|
+
response?: string | { tool_result?: string; tool_prompt?: string };
|
|
367
|
+
action?: Record<string, unknown>[];
|
|
368
|
+
post_process?: boolean;
|
|
369
|
+
}
|
|
370
|
+
```
|
|
371
|
+
|
|
372
|
+
**Returns:** An object with `response`, `action` and `post_process` fields, each present only when it applies.
|
|
373
|
+
|
|
374
|
+
These rules decide which fields appear:
|
|
375
|
+
|
|
376
|
+
- A structured response with at least one field is sent as `response`. Otherwise a non-empty string response is.
|
|
377
|
+
- A non-empty action list is included as `action`.
|
|
378
|
+
- `post_process: true` is included only when `postProcess` is `true` and there are actions.
|
|
379
|
+
- When none of these fields is set, the result is `{ response: "Action completed." }`.
|
|
380
|
+
|
|
381
|
+
**Example:**
|
|
382
|
+
|
|
383
|
+
```typescript
|
|
384
|
+
const result = new FunctionResult('The caller is verified.').say('Thank you, you are verified.');
|
|
385
|
+
console.log(result.toDict());
|
|
386
|
+
// {
|
|
387
|
+
// response: 'The caller is verified.',
|
|
388
|
+
// action: [ { say: 'Thank you, you are verified.' } ]
|
|
389
|
+
// }
|
|
390
|
+
|
|
391
|
+
const empty = new FunctionResult();
|
|
392
|
+
console.log(empty.toDict());
|
|
393
|
+
// { response: 'Action completed.' }
|
|
394
|
+
```
|
|
395
|
+
|
|
396
|
+
### toJSON
|
|
397
|
+
|
|
398
|
+
Return the same object as `toDict()`, so `JSON.stringify(result)` produces the wire format.
|
|
399
|
+
|
|
400
|
+
<!-- snippet: no-compile API signature reference, not runnable code -->
|
|
401
|
+
```typescript
|
|
402
|
+
toJSON(): {
|
|
403
|
+
response?: string | { tool_result?: string; tool_prompt?: string };
|
|
404
|
+
action?: Record<string, unknown>[];
|
|
405
|
+
post_process?: boolean;
|
|
406
|
+
}
|
|
407
|
+
```
|
|
408
|
+
|
|
409
|
+
**Example:**
|
|
410
|
+
|
|
411
|
+
```typescript
|
|
412
|
+
console.log(JSON.stringify(new FunctionResult('Order 1234 is cancelled.').hangup()));
|
|
413
|
+
// {"response":"Order 1234 is cancelled.","action":[{"hangup":true}]}
|
|
414
|
+
```
|
|
415
|
+
|
|
416
|
+
## Call Control
|
|
417
|
+
|
|
418
|
+
### connect
|
|
419
|
+
|
|
420
|
+
Connect (transfer) the call to another destination. The SDK emits an inline SWML document with a `connect` verb, and a `transfer` key beside it set to `"true"` or `"false"`.
|
|
421
|
+
|
|
422
|
+
<!-- snippet: no-compile API signature reference, not runnable code -->
|
|
423
|
+
```typescript
|
|
424
|
+
connect(destination: string, final?: boolean, fromAddr?: string): this
|
|
425
|
+
```
|
|
426
|
+
|
|
427
|
+
| Parameter | Type | Default | Description |
|
|
428
|
+
|---------------|-----------|---------|----------------------------------------------------------|
|
|
429
|
+
| `destination` | `string` | none | Phone number or SIP address to connect to. |
|
|
430
|
+
| `final` | `boolean` | `true` | `true` for a permanent transfer: the call leaves the agent. `false` returns the call to the agent when the far end hangs up. |
|
|
431
|
+
| `fromAddr` | `string` | none | Caller ID for the outbound leg. Without it, the current call's from address is used. |
|
|
432
|
+
|
|
433
|
+
**Returns:** `this` for chaining.
|
|
434
|
+
|
|
435
|
+
**Example:**
|
|
436
|
+
|
|
437
|
+
```typescript
|
|
438
|
+
// Permanent transfer
|
|
439
|
+
const result = new FunctionResult('Tell the caller you are connecting them to support.', true)
|
|
440
|
+
.connect('+15551234567');
|
|
441
|
+
|
|
442
|
+
// Temporary transfer: the call returns to the agent afterwards
|
|
443
|
+
const result2 = new FunctionResult('Tell the caller you are bringing in a manager.', true)
|
|
444
|
+
.connect('+15559876543', false);
|
|
445
|
+
|
|
446
|
+
// Transfer with a custom caller ID
|
|
447
|
+
const result3 = new FunctionResult('Tell the caller you are transferring them.', true)
|
|
448
|
+
.connect('+15551234567', true, '+15550001111');
|
|
449
|
+
```
|
|
450
|
+
|
|
451
|
+
The emitted action for the first example has this shape:
|
|
452
|
+
|
|
453
|
+
```json
|
|
454
|
+
{
|
|
455
|
+
"SWML": {
|
|
456
|
+
"sections": { "main": [{ "connect": { "to": "+15551234567" } }] },
|
|
457
|
+
"version": "1.0.0"
|
|
458
|
+
},
|
|
459
|
+
"transfer": "true"
|
|
460
|
+
}
|
|
461
|
+
```
|
|
462
|
+
|
|
463
|
+
### swmlTransfer
|
|
464
|
+
|
|
465
|
+
Transfer the call with an inline SWML document. The document sets `ai_response` with the `set` verb, then runs the `transfer` verb. Like `connect`, the action carries `transfer: "true"` or `"false"` beside the document.
|
|
466
|
+
|
|
467
|
+
<!-- snippet: no-compile API signature reference, not runnable code -->
|
|
468
|
+
```typescript
|
|
469
|
+
swmlTransfer(dest: string, aiResponse: string, final?: boolean): this
|
|
470
|
+
```
|
|
471
|
+
|
|
472
|
+
| Parameter | Type | Default | Description |
|
|
473
|
+
|--------------|-----------|---------|----------------------------------------------------|
|
|
474
|
+
| `dest` | `string` | none | The transfer destination, such as a SWML URL or SIP address. |
|
|
475
|
+
| `aiResponse` | `string` | none | Stored as `ai_response`, for the agent to use when a non-final transfer returns the call. |
|
|
476
|
+
| `final` | `boolean` | `true` | `true` for a permanent transfer, `false` to return to the agent. |
|
|
477
|
+
|
|
478
|
+
**Returns:** `this` for chaining.
|
|
479
|
+
|
|
480
|
+
**Example:**
|
|
481
|
+
|
|
482
|
+
```typescript
|
|
483
|
+
const result = new FunctionResult('Tell the caller you are transferring them to billing.', true)
|
|
484
|
+
.swmlTransfer(
|
|
485
|
+
'https://example.com/billing-swml',
|
|
486
|
+
'The billing call is complete. Ask whether the caller needs anything else.',
|
|
487
|
+
false,
|
|
488
|
+
);
|
|
489
|
+
```
|
|
490
|
+
|
|
491
|
+
### hangup
|
|
492
|
+
|
|
493
|
+
Hang up the call. Adds a `{ hangup: true }` action.
|
|
494
|
+
|
|
495
|
+
<!-- snippet: no-compile API signature reference, not runnable code -->
|
|
496
|
+
```typescript
|
|
497
|
+
hangup(): this
|
|
498
|
+
```
|
|
499
|
+
|
|
500
|
+
**Returns:** `this` for chaining.
|
|
501
|
+
|
|
502
|
+
**Example:**
|
|
503
|
+
|
|
504
|
+
```typescript
|
|
505
|
+
const result = new FunctionResult('Thank the caller and say goodbye.')
|
|
506
|
+
.setPostProcess(true)
|
|
507
|
+
.hangup();
|
|
508
|
+
```
|
|
509
|
+
|
|
510
|
+
### hold
|
|
511
|
+
|
|
512
|
+
Put the call on hold. During a hold, speech detection is paused and the agent doesn't respond to the caller. The platform plays hold music while the call waits.
|
|
513
|
+
|
|
514
|
+
<!-- snippet: no-compile API signature reference, not runnable code -->
|
|
515
|
+
```typescript
|
|
516
|
+
hold(prompt?: string | number, timeout?: number, step?: string, timeoutStep?: string): this
|
|
517
|
+
```
|
|
518
|
+
|
|
519
|
+
| Parameter | Type | Default | Description |
|
|
520
|
+
|---------------|--------------------|---------|-------------------------------------------------------------|
|
|
521
|
+
| `prompt` | `string \| number` | none | Instruction for the model to act on before the hold. A number here is read as `timeout`. |
|
|
522
|
+
| `timeout` | `number` | `300` | Hold duration in seconds, clamped to 0 through 900. |
|
|
523
|
+
| `step` | `string` | none | Step to move to when the call is taken off hold. |
|
|
524
|
+
| `timeoutStep` | `string` | none | Step to move to when the hold times out. |
|
|
525
|
+
|
|
526
|
+
**Returns:** `this` for chaining.
|
|
527
|
+
|
|
528
|
+
The hold action carries no announcement of its own, so say anything the caller needs to hear before the hold takes effect. Passing `prompt` does that for you. It sets the structured response to `tool_result: "status: on hold"` with your prompt as `tool_prompt`, and turns on `postProcess`. The model then takes one more turn, and can tell the caller, before the hold runs.
|
|
529
|
+
|
|
530
|
+
A number as the first argument is the timeout, so `hold(120)` means a 120-second hold with no prompt:
|
|
531
|
+
|
|
532
|
+
```typescript
|
|
533
|
+
const shortHold = new FunctionResult('The caller is waiting for a supervisor.').hold(120);
|
|
534
|
+
// action: [{ hold: 120 }]
|
|
535
|
+
```
|
|
536
|
+
|
|
537
|
+
`step` and `timeoutStep` choose the step the call moves to when the hold ends. `step` applies when someone takes the call off hold, for example with [rpcAiUnhold](#rpcaiunhold). `timeoutStep` applies when the timeout passes with nobody releasing the call. Leave one out, and a hold that ends that way resumes in the current step.
|
|
538
|
+
|
|
539
|
+
Both transitions wait for the hold to end. [swmlChangeStep](#swmlchangestep) applies at once instead. Returning it with a hold moves the caller before the hold begins.
|
|
540
|
+
|
|
541
|
+
This example announces the hold and routes the call when the hold ends:
|
|
542
|
+
|
|
543
|
+
```typescript
|
|
544
|
+
const routed = new FunctionResult().hold(
|
|
545
|
+
'Tell the caller you are checking whether someone is available.',
|
|
546
|
+
60,
|
|
547
|
+
'human_available',
|
|
548
|
+
'take_message',
|
|
549
|
+
);
|
|
550
|
+
console.log(JSON.stringify(routed.toDict(), null, 2));
|
|
551
|
+
```
|
|
552
|
+
|
|
553
|
+
The result carries the prompt, the routing and `post_process`:
|
|
554
|
+
|
|
555
|
+
```json
|
|
556
|
+
{
|
|
557
|
+
"response": {
|
|
558
|
+
"tool_result": "status: on hold",
|
|
559
|
+
"tool_prompt": "Tell the caller you are checking whether someone is available."
|
|
560
|
+
},
|
|
561
|
+
"action": [
|
|
562
|
+
{
|
|
563
|
+
"hold": {
|
|
564
|
+
"timeout": 60,
|
|
565
|
+
"step": "human_available",
|
|
566
|
+
"timeout_step": "take_message"
|
|
567
|
+
}
|
|
568
|
+
}
|
|
569
|
+
],
|
|
570
|
+
"post_process": true
|
|
571
|
+
}
|
|
572
|
+
```
|
|
573
|
+
|
|
574
|
+
Without `step` and `timeoutStep`, the action is the bare timeout, such as `{ hold: 300 }`.
|
|
575
|
+
|
|
576
|
+
### waitForUser
|
|
577
|
+
|
|
578
|
+
Emit a `wait_for_user` action, which controls how the agent waits for the caller's input.
|
|
579
|
+
|
|
580
|
+
<!-- snippet: no-compile API signature reference, not runnable code -->
|
|
581
|
+
```typescript
|
|
582
|
+
waitForUser(opts?: {
|
|
583
|
+
enabled?: boolean;
|
|
584
|
+
timeout?: number;
|
|
585
|
+
answerFirst?: boolean;
|
|
586
|
+
}): this
|
|
587
|
+
```
|
|
588
|
+
|
|
589
|
+
| Parameter | Type | Default | Description |
|
|
590
|
+
|--------------------|-----------|---------|--------------------------------------------------|
|
|
591
|
+
| `opts.enabled` | `boolean` | none | Enable or disable waiting for user input. Emits the boolean. |
|
|
592
|
+
| `opts.timeout` | `number` | none | Seconds to wait for user input. Emits the number. |
|
|
593
|
+
| `opts.answerFirst` | `boolean` | none | When `true`, emits the string `"answer_first"`. |
|
|
594
|
+
|
|
595
|
+
**Priority:** `answerFirst` > `timeout` > `enabled`. With no options, the SDK emits `wait_for_user: true`.
|
|
596
|
+
|
|
597
|
+
**Returns:** `this` for chaining.
|
|
598
|
+
|
|
599
|
+
**Example:**
|
|
600
|
+
|
|
601
|
+
```typescript
|
|
602
|
+
// Wait for the caller
|
|
603
|
+
const r1 = new FunctionResult('Ask the caller to take their time.').waitForUser();
|
|
604
|
+
|
|
605
|
+
// Wait up to 10 seconds
|
|
606
|
+
const r2 = new FunctionResult('The caller is looking for their account number.')
|
|
607
|
+
.waitForUser({ timeout: 10 });
|
|
608
|
+
|
|
609
|
+
// answer_first mode
|
|
610
|
+
const r3 = new FunctionResult('The caller has not spoken yet.')
|
|
611
|
+
.waitForUser({ answerFirst: true });
|
|
612
|
+
|
|
613
|
+
// Stop waiting
|
|
614
|
+
const r4 = new FunctionResult('Continue with the next question.')
|
|
615
|
+
.waitForUser({ enabled: false });
|
|
616
|
+
```
|
|
617
|
+
|
|
618
|
+
### stop
|
|
619
|
+
|
|
620
|
+
Stop the AI conversation. Adds a `{ stop: true }` action.
|
|
621
|
+
|
|
622
|
+
<!-- snippet: no-compile API signature reference, not runnable code -->
|
|
623
|
+
```typescript
|
|
624
|
+
stop(): this
|
|
625
|
+
```
|
|
626
|
+
|
|
627
|
+
**Returns:** `this` for chaining.
|
|
628
|
+
|
|
629
|
+
**Example:**
|
|
630
|
+
|
|
631
|
+
```typescript
|
|
632
|
+
const result = new FunctionResult('The session is complete.').stop();
|
|
633
|
+
```
|
|
634
|
+
|
|
635
|
+
## Audio
|
|
636
|
+
|
|
637
|
+
### say
|
|
638
|
+
|
|
639
|
+
Speak text to the caller with text-to-speech. Unlike the response, which the model interprets, this text is spoken to the caller. Adds a `{ say: text }` action.
|
|
640
|
+
|
|
641
|
+
<!-- snippet: no-compile API signature reference, not runnable code -->
|
|
642
|
+
```typescript
|
|
643
|
+
say(text: string): this
|
|
644
|
+
```
|
|
645
|
+
|
|
646
|
+
| Parameter | Type | Description |
|
|
647
|
+
|-----------|----------|--------------------------|
|
|
648
|
+
| `text` | `string` | The text to speak. |
|
|
649
|
+
|
|
650
|
+
**Returns:** `this` for chaining.
|
|
651
|
+
|
|
652
|
+
**Example:**
|
|
653
|
+
|
|
654
|
+
```typescript
|
|
655
|
+
const result = new FunctionResult('Order 12345 was found.')
|
|
656
|
+
.say('Your order number is 12345.');
|
|
657
|
+
```
|
|
658
|
+
|
|
659
|
+
### playBackgroundFile
|
|
660
|
+
|
|
661
|
+
Play an audio file in the background during the call. The AI conversation continues while the file plays.
|
|
662
|
+
|
|
663
|
+
<!-- snippet: no-compile API signature reference, not runnable code -->
|
|
664
|
+
```typescript
|
|
665
|
+
playBackgroundFile(filename: string, wait?: boolean): this
|
|
666
|
+
```
|
|
667
|
+
|
|
668
|
+
| Parameter | Type | Default | Description |
|
|
669
|
+
|------------|-----------|---------|----------------------------------------------------|
|
|
670
|
+
| `filename` | `string` | none | URL or path of the audio file. |
|
|
671
|
+
| `wait` | `boolean` | `false` | When `true`, wait for the file to finish playing before continuing. |
|
|
672
|
+
|
|
673
|
+
With `wait` false, the action is `{ playback_bg: filename }`. With `wait` true, it's `{ playback_bg: { file: filename, wait: true } }`.
|
|
674
|
+
|
|
675
|
+
**Returns:** `this` for chaining.
|
|
676
|
+
|
|
677
|
+
**Example:**
|
|
678
|
+
|
|
679
|
+
```typescript
|
|
680
|
+
// Play background music
|
|
681
|
+
const result = new FunctionResult('Hold music is playing.')
|
|
682
|
+
.playBackgroundFile('https://example.com/hold-music.mp3');
|
|
683
|
+
|
|
684
|
+
// Play and wait for the file to finish
|
|
685
|
+
const result2 = new FunctionResult('The announcement is playing.')
|
|
686
|
+
.playBackgroundFile('https://example.com/announcement.wav', true);
|
|
687
|
+
```
|
|
688
|
+
|
|
689
|
+
### stopBackgroundFile
|
|
690
|
+
|
|
691
|
+
Stop the background audio file that is playing. Adds a `{ stop_playback_bg: true }` action.
|
|
692
|
+
|
|
693
|
+
<!-- snippet: no-compile API signature reference, not runnable code -->
|
|
694
|
+
```typescript
|
|
695
|
+
stopBackgroundFile(): this
|
|
696
|
+
```
|
|
697
|
+
|
|
698
|
+
**Returns:** `this` for chaining.
|
|
699
|
+
|
|
700
|
+
**Example:**
|
|
701
|
+
|
|
702
|
+
```typescript
|
|
703
|
+
const result = new FunctionResult('The music is stopped.')
|
|
704
|
+
.stopBackgroundFile();
|
|
705
|
+
```
|
|
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
|
+
|
|
730
|
+
## Speech
|
|
731
|
+
|
|
732
|
+
### addDynamicHints
|
|
733
|
+
|
|
734
|
+
Add speech recognition hints during the call, to improve recognition of specific words or phrases. A hint is a string, or a pattern object that replaces matching recognized text.
|
|
735
|
+
|
|
736
|
+
<!-- snippet: no-compile API signature reference, not runnable code -->
|
|
737
|
+
```typescript
|
|
738
|
+
addDynamicHints(
|
|
739
|
+
hints: (string | { pattern: string; replace: string; ignore_case?: boolean })[]
|
|
740
|
+
): this
|
|
741
|
+
```
|
|
742
|
+
|
|
743
|
+
| Parameter | Type | Description |
|
|
744
|
+
|-----------|-----------------------------------------------------------------------------------|------------------------------------------------|
|
|
745
|
+
| `hints` | `(string \| { pattern: string; replace: string; ignore_case?: boolean })[]` | Array of hint strings or pattern objects. |
|
|
746
|
+
|
|
747
|
+
**Returns:** `this` for chaining.
|
|
748
|
+
|
|
749
|
+
**Example:**
|
|
750
|
+
|
|
751
|
+
```typescript
|
|
752
|
+
// Word hints
|
|
753
|
+
const result = new FunctionResult('Hints are added.')
|
|
754
|
+
.addDynamicHints(['SignalWire', 'SWML', 'SWAIG']);
|
|
755
|
+
|
|
756
|
+
// Pattern-replacement hints
|
|
757
|
+
const result2 = new FunctionResult('Hints are added.')
|
|
758
|
+
.addDynamicHints([
|
|
759
|
+
{ pattern: 'signal wire', replace: 'SignalWire', ignore_case: true },
|
|
760
|
+
{ pattern: 'swiggy', replace: 'SWAIG' },
|
|
761
|
+
]);
|
|
762
|
+
```
|
|
763
|
+
|
|
764
|
+
### clearDynamicHints
|
|
765
|
+
|
|
766
|
+
Remove all hints added with `addDynamicHints()`. Adds a `{ clear_dynamic_hints: {} }` action.
|
|
767
|
+
|
|
768
|
+
<!-- snippet: no-compile API signature reference, not runnable code -->
|
|
769
|
+
```typescript
|
|
770
|
+
clearDynamicHints(): this
|
|
771
|
+
```
|
|
772
|
+
|
|
773
|
+
**Returns:** `this` for chaining.
|
|
774
|
+
|
|
775
|
+
**Example:**
|
|
776
|
+
|
|
777
|
+
```typescript
|
|
778
|
+
const result = new FunctionResult('Hints are cleared.')
|
|
779
|
+
.clearDynamicHints();
|
|
780
|
+
```
|
|
781
|
+
|
|
782
|
+
### setEndOfSpeechTimeout
|
|
783
|
+
|
|
784
|
+
Set how many milliseconds of silence after detected speech finalize speech recognition (`end_of_speech_timeout`). A shorter timeout ends the caller's turn sooner. A longer one allows for pauses.
|
|
785
|
+
|
|
786
|
+
<!-- snippet: no-compile API signature reference, not runnable code -->
|
|
787
|
+
```typescript
|
|
788
|
+
setEndOfSpeechTimeout(milliseconds: number): this
|
|
789
|
+
```
|
|
790
|
+
|
|
791
|
+
| Parameter | Type | Description |
|
|
792
|
+
|----------------|----------|-----------------------------------|
|
|
793
|
+
| `milliseconds` | `number` | Timeout in milliseconds. |
|
|
794
|
+
|
|
795
|
+
**Returns:** `this` for chaining.
|
|
796
|
+
|
|
797
|
+
**Example:**
|
|
798
|
+
|
|
799
|
+
```typescript
|
|
800
|
+
const result = new FunctionResult('The speech timeout is adjusted.')
|
|
801
|
+
.setEndOfSpeechTimeout(500); // 500 ms of silence ends the caller's turn
|
|
802
|
+
```
|
|
803
|
+
|
|
804
|
+
### setSpeechEventTimeout
|
|
805
|
+
|
|
806
|
+
Set how many milliseconds after the last speech detection event recognition is finalized (`speech_event_timeout`). It works better than the end-of-speech timeout in noisy environments.
|
|
807
|
+
|
|
808
|
+
<!-- snippet: no-compile API signature reference, not runnable code -->
|
|
809
|
+
```typescript
|
|
810
|
+
setSpeechEventTimeout(milliseconds: number): this
|
|
811
|
+
```
|
|
812
|
+
|
|
813
|
+
| Parameter | Type | Description |
|
|
814
|
+
|----------------|----------|-----------------------------------|
|
|
815
|
+
| `milliseconds` | `number` | Timeout in milliseconds. |
|
|
816
|
+
|
|
817
|
+
**Returns:** `this` for chaining.
|
|
818
|
+
|
|
819
|
+
**Example:**
|
|
820
|
+
|
|
821
|
+
```typescript
|
|
822
|
+
const result = new FunctionResult('The event timeout is set.')
|
|
823
|
+
.setSpeechEventTimeout(3000);
|
|
824
|
+
```
|
|
825
|
+
|
|
826
|
+
## Data Management
|
|
827
|
+
|
|
828
|
+
### updateGlobalData
|
|
829
|
+
|
|
830
|
+
Merge key-value pairs into the call's global data (`set_global_data`). Global data lasts for the AI session. Every function can read it, and prompts can expand it with `${global_data.key}`.
|
|
831
|
+
|
|
832
|
+
<!-- snippet: no-compile API signature reference, not runnable code -->
|
|
833
|
+
```typescript
|
|
834
|
+
updateGlobalData(data: Record<string, unknown>): this
|
|
835
|
+
```
|
|
836
|
+
|
|
837
|
+
| Parameter | Type | Description |
|
|
838
|
+
|-----------|----------------------------|------------------------------------|
|
|
839
|
+
| `data` | `Record<string, unknown>` | Key-value pairs to set or update. |
|
|
840
|
+
|
|
841
|
+
**Returns:** `this` for chaining.
|
|
842
|
+
|
|
843
|
+
**Example:**
|
|
844
|
+
|
|
845
|
+
```typescript
|
|
846
|
+
const result = new FunctionResult('The customer record is loaded.')
|
|
847
|
+
.updateGlobalData({ customer_id: 'C-123', tier: 'premium' });
|
|
848
|
+
```
|
|
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
|
+
|
|
873
|
+
### removeGlobalData
|
|
874
|
+
|
|
875
|
+
Remove one or more keys from the global data (`unset_global_data`).
|
|
876
|
+
|
|
877
|
+
<!-- snippet: no-compile API signature reference, not runnable code -->
|
|
878
|
+
```typescript
|
|
879
|
+
removeGlobalData(keys: string | string[]): this
|
|
880
|
+
```
|
|
881
|
+
|
|
882
|
+
| Parameter | Type | Description |
|
|
883
|
+
|-----------|----------------------|------------------------------------------|
|
|
884
|
+
| `keys` | `string \| string[]` | A single key or array of keys to remove. |
|
|
885
|
+
|
|
886
|
+
**Returns:** `this` for chaining.
|
|
887
|
+
|
|
888
|
+
**Example:**
|
|
889
|
+
|
|
890
|
+
```typescript
|
|
891
|
+
// Remove a single key
|
|
892
|
+
const r1 = new FunctionResult('The temporary token is removed.')
|
|
893
|
+
.removeGlobalData('temp_token');
|
|
894
|
+
|
|
895
|
+
// Remove several keys
|
|
896
|
+
const r2 = new FunctionResult('The session cache is cleared.')
|
|
897
|
+
.removeGlobalData(['temp_token', 'session_cache']);
|
|
898
|
+
```
|
|
899
|
+
|
|
900
|
+
### setMetadata
|
|
901
|
+
|
|
902
|
+
Set metadata (`set_meta_data`) scoped to the current function's `meta_data_token`. Functions that share a token share the metadata. Without a token, the scope is the function.
|
|
903
|
+
|
|
904
|
+
<!-- snippet: no-compile API signature reference, not runnable code -->
|
|
905
|
+
```typescript
|
|
906
|
+
setMetadata(data: Record<string, unknown>): this
|
|
907
|
+
```
|
|
908
|
+
|
|
909
|
+
| Parameter | Type | Description |
|
|
910
|
+
|-----------|----------------------------|-------------------------------|
|
|
911
|
+
| `data` | `Record<string, unknown>` | Metadata key-value pairs. |
|
|
912
|
+
|
|
913
|
+
**Returns:** `this` for chaining.
|
|
914
|
+
|
|
915
|
+
**Example:**
|
|
916
|
+
|
|
917
|
+
```typescript
|
|
918
|
+
const result = new FunctionResult('The lookup is saved.')
|
|
919
|
+
.setMetadata({ last_action: 'lookup', retry_count: 2 });
|
|
920
|
+
```
|
|
921
|
+
|
|
922
|
+
### removeMetadata
|
|
923
|
+
|
|
924
|
+
Remove metadata keys (`unset_meta_data`) from the current function's `meta_data_token` scope.
|
|
925
|
+
|
|
926
|
+
<!-- snippet: no-compile API signature reference, not runnable code -->
|
|
927
|
+
```typescript
|
|
928
|
+
removeMetadata(keys: string | string[]): this
|
|
929
|
+
```
|
|
930
|
+
|
|
931
|
+
| Parameter | Type | Description |
|
|
932
|
+
|-----------|----------------------|------------------------------------------|
|
|
933
|
+
| `keys` | `string \| string[]` | A single key or array of keys to remove. |
|
|
934
|
+
|
|
935
|
+
**Returns:** `this` for chaining.
|
|
936
|
+
|
|
937
|
+
**Example:**
|
|
938
|
+
|
|
939
|
+
```typescript
|
|
940
|
+
const result = new FunctionResult('The temporary metadata is removed.')
|
|
941
|
+
.removeMetadata(['temp_flag', 'debug_info']);
|
|
942
|
+
```
|
|
943
|
+
|
|
944
|
+
## SWML Actions
|
|
945
|
+
|
|
946
|
+
### executeSwml
|
|
947
|
+
|
|
948
|
+
Run arbitrary SWML content as an action.
|
|
949
|
+
|
|
950
|
+
<!-- snippet: no-compile API signature reference, not runnable code -->
|
|
951
|
+
```typescript
|
|
952
|
+
executeSwml(
|
|
953
|
+
swmlContent: string | Record<string, unknown> | { toDict(): Record<string, unknown> },
|
|
954
|
+
transfer?: boolean
|
|
955
|
+
): this
|
|
956
|
+
```
|
|
957
|
+
|
|
958
|
+
| Parameter | Type | Default | Description |
|
|
959
|
+
|---------------|-----------------------------------------|---------|---------------------------------------------------|
|
|
960
|
+
| `swmlContent` | `string \| Record<string, unknown> \| { toDict() }` | none | SWML as a JSON string, a plain object, or an object with a `toDict()` method. |
|
|
961
|
+
| `transfer` | `boolean` | `false` | When `true`, the call leaves the agent for this SWML. |
|
|
962
|
+
|
|
963
|
+
The SDK normalizes `swmlContent` as follows:
|
|
964
|
+
|
|
965
|
+
- A JSON string is parsed. A string that isn't valid JSON is sent as `{ raw_swml: <string> }`.
|
|
966
|
+
- An object with a `toDict()` method is converted through it.
|
|
967
|
+
- A plain object is copied, so the SDK never changes yours.
|
|
968
|
+
- Any other value, such as a number, an array or `null`, throws an `Error`.
|
|
969
|
+
|
|
970
|
+
The action is `{ SWML: <document> }`. With `transfer` set, the SDK adds `transfer: "true"` beside the `SWML` key, not inside the document. That is the same shape `connect()` and `swmlTransfer()` emit.
|
|
971
|
+
|
|
972
|
+
**Returns:** `this` for chaining.
|
|
973
|
+
|
|
974
|
+
**Example:**
|
|
975
|
+
|
|
976
|
+
```typescript
|
|
977
|
+
// Run SWML from an object
|
|
978
|
+
const result = new FunctionResult('A short announcement is playing.')
|
|
979
|
+
.executeSwml({
|
|
980
|
+
version: '1.0.0',
|
|
981
|
+
sections: {
|
|
982
|
+
main: [{ play: { url: 'https://example.com/audio.mp3' } }],
|
|
983
|
+
},
|
|
984
|
+
});
|
|
985
|
+
|
|
986
|
+
// Run SWML and leave the agent
|
|
987
|
+
const result2 = new FunctionResult('Tell the caller you are transferring them.', true)
|
|
988
|
+
.executeSwml({
|
|
989
|
+
version: '1.0.0',
|
|
990
|
+
sections: {
|
|
991
|
+
main: [{ connect: { to: '+15551234567' } }],
|
|
992
|
+
},
|
|
993
|
+
}, true);
|
|
994
|
+
```
|
|
995
|
+
|
|
996
|
+
The second example emits this action:
|
|
997
|
+
|
|
998
|
+
```json
|
|
999
|
+
{
|
|
1000
|
+
"SWML": {
|
|
1001
|
+
"version": "1.0.0",
|
|
1002
|
+
"sections": { "main": [{ "connect": { "to": "+15551234567" } }] }
|
|
1003
|
+
},
|
|
1004
|
+
"transfer": "true"
|
|
1005
|
+
}
|
|
1006
|
+
```
|
|
1007
|
+
|
|
1008
|
+
### switchContext
|
|
1009
|
+
|
|
1010
|
+
Replace the agent's prompt during the call (`context_switch`). It can set a new system prompt, add a user prompt, summarize the conversation so far, or reset the context completely.
|
|
1011
|
+
|
|
1012
|
+
<!-- snippet: no-compile API signature reference, not runnable code -->
|
|
1013
|
+
```typescript
|
|
1014
|
+
switchContext(opts?: {
|
|
1015
|
+
systemPrompt?: string;
|
|
1016
|
+
userPrompt?: string;
|
|
1017
|
+
consolidate?: boolean;
|
|
1018
|
+
fullReset?: boolean;
|
|
1019
|
+
}): this
|
|
1020
|
+
```
|
|
1021
|
+
|
|
1022
|
+
| Parameter | Type | Description |
|
|
1023
|
+
|---------------------|-----------|-------------------------------------------------------------------|
|
|
1024
|
+
| `opts.systemPrompt` | `string` | New system prompt. |
|
|
1025
|
+
| `opts.userPrompt` | `string` | Text added as if the user had said it, to give the new prompt context. |
|
|
1026
|
+
| `opts.consolidate` | `boolean` | When `true`, summarize the existing conversation. |
|
|
1027
|
+
| `opts.fullReset` | `boolean` | When `true`, reset the context completely. |
|
|
1028
|
+
|
|
1029
|
+
**Behavior:** With only `systemPrompt`, the action value is the prompt string. Otherwise it's an object with the fields that are set.
|
|
1030
|
+
|
|
1031
|
+
**Returns:** `this` for chaining.
|
|
1032
|
+
|
|
1033
|
+
**Example:**
|
|
1034
|
+
|
|
1035
|
+
```typescript
|
|
1036
|
+
// Change the system prompt only
|
|
1037
|
+
const r1 = new FunctionResult('The caller has a billing question.')
|
|
1038
|
+
.switchContext({ systemPrompt: 'You are a billing specialist.' });
|
|
1039
|
+
|
|
1040
|
+
// Change it and summarize the conversation so far
|
|
1041
|
+
const r2 = new FunctionResult('The call is escalated to a supervisor.')
|
|
1042
|
+
.switchContext({
|
|
1043
|
+
systemPrompt: 'You are a supervisor handling an escalated call.',
|
|
1044
|
+
consolidate: true,
|
|
1045
|
+
});
|
|
1046
|
+
|
|
1047
|
+
// Full reset
|
|
1048
|
+
const r3 = new FunctionResult('The caller wants to start over.')
|
|
1049
|
+
.switchContext({
|
|
1050
|
+
systemPrompt: 'You are a general assistant.',
|
|
1051
|
+
fullReset: true,
|
|
1052
|
+
});
|
|
1053
|
+
```
|
|
1054
|
+
|
|
1055
|
+
### swmlChangeStep
|
|
1056
|
+
|
|
1057
|
+
Move the conversation to another step in the current context (`change_step`). The step must exist in the current context of the agent's contexts, which you define with `defineContexts()`. The change applies at once, and a change from a tool isn't limited by the step's `setValidSteps()` list.
|
|
1058
|
+
|
|
1059
|
+
<!-- snippet: no-compile API signature reference, not runnable code -->
|
|
1060
|
+
```typescript
|
|
1061
|
+
swmlChangeStep(stepName: string): this
|
|
1062
|
+
```
|
|
1063
|
+
|
|
1064
|
+
| Parameter | Type | Description |
|
|
1065
|
+
|------------|----------|------------------------------------|
|
|
1066
|
+
| `stepName` | `string` | The name of the step to switch to. |
|
|
1067
|
+
|
|
1068
|
+
**Returns:** `this` for chaining.
|
|
1069
|
+
|
|
1070
|
+
The model reads the response before the new step's instructions, so put the reason for the move there. Pass values the step needs with `updateGlobalData()`, and expand them in the step's text.
|
|
1071
|
+
|
|
1072
|
+
**Example:**
|
|
1073
|
+
|
|
1074
|
+
```typescript
|
|
1075
|
+
const result = new FunctionResult('The premium plan is confirmed. Collect payment details next.')
|
|
1076
|
+
.updateGlobalData({ plan: 'premium' })
|
|
1077
|
+
.swmlChangeStep('collect_payment');
|
|
1078
|
+
```
|
|
1079
|
+
|
|
1080
|
+
### swmlChangeContext
|
|
1081
|
+
|
|
1082
|
+
Move the conversation to another context (`change_context`). The context must exist in the agent's contexts, which you define with `defineContexts()`. A change from a tool isn't limited by `setValidContexts()`.
|
|
1083
|
+
|
|
1084
|
+
<!-- snippet: no-compile API signature reference, not runnable code -->
|
|
1085
|
+
```typescript
|
|
1086
|
+
swmlChangeContext(contextName: string): this
|
|
1087
|
+
```
|
|
1088
|
+
|
|
1089
|
+
| Parameter | Type | Description |
|
|
1090
|
+
|---------------|----------|---------------------------------------|
|
|
1091
|
+
| `contextName` | `string` | The name of the context to switch to. |
|
|
1092
|
+
|
|
1093
|
+
**Returns:** `this` for chaining.
|
|
1094
|
+
|
|
1095
|
+
**Example:**
|
|
1096
|
+
|
|
1097
|
+
```typescript
|
|
1098
|
+
const result = new FunctionResult('The caller asked for support in Spanish.')
|
|
1099
|
+
.swmlChangeContext('spanish_support');
|
|
1100
|
+
```
|
|
1101
|
+
|
|
1102
|
+
### swmlUserEvent
|
|
1103
|
+
|
|
1104
|
+
Send an event to the client connected to the call, such as a browser using the SignalWire browser SDK. The SDK wraps `eventData` in an inline SWML `user_event` verb, and the client receives it as a `user_event` event.
|
|
1105
|
+
|
|
1106
|
+
<!-- snippet: no-compile API signature reference, not runnable code -->
|
|
1107
|
+
```typescript
|
|
1108
|
+
swmlUserEvent(eventData: Record<string, unknown>): this
|
|
1109
|
+
```
|
|
1110
|
+
|
|
1111
|
+
| Parameter | Type | Description |
|
|
1112
|
+
|-------------|----------------------------|----------------------|
|
|
1113
|
+
| `eventData` | `Record<string, unknown>` | The event payload. |
|
|
1114
|
+
|
|
1115
|
+
**Returns:** `this` for chaining.
|
|
1116
|
+
|
|
1117
|
+
**Example:**
|
|
1118
|
+
|
|
1119
|
+
```typescript
|
|
1120
|
+
const result = new FunctionResult('Order ORD-456 was placed.')
|
|
1121
|
+
.swmlUserEvent({
|
|
1122
|
+
type: 'order_placed',
|
|
1123
|
+
order_id: 'ORD-456',
|
|
1124
|
+
total: 29.99,
|
|
1125
|
+
});
|
|
1126
|
+
```
|
|
1127
|
+
|
|
1128
|
+
## Function Control
|
|
1129
|
+
|
|
1130
|
+
### toggleFunctions
|
|
1131
|
+
|
|
1132
|
+
Enable or disable SWAIG functions by name during the call (`toggle_functions`), to control which tools the model can call.
|
|
1133
|
+
|
|
1134
|
+
<!-- snippet: no-compile API signature reference, not runnable code -->
|
|
1135
|
+
```typescript
|
|
1136
|
+
toggleFunctions(toggles: { function: string; active: boolean }[]): this
|
|
1137
|
+
```
|
|
1138
|
+
|
|
1139
|
+
| Parameter | Type | Description |
|
|
1140
|
+
|--------------------|-----------|------------------------------------------|
|
|
1141
|
+
| `toggles[].function` | `string` | The name of the SWAIG function. |
|
|
1142
|
+
| `toggles[].active` | `boolean` | `true` to enable, `false` to disable. |
|
|
1143
|
+
|
|
1144
|
+
**Returns:** `this` for chaining.
|
|
1145
|
+
|
|
1146
|
+
**Example:**
|
|
1147
|
+
|
|
1148
|
+
```typescript
|
|
1149
|
+
// After verification, enable the account tools
|
|
1150
|
+
const result = new FunctionResult('The caller is verified.')
|
|
1151
|
+
.toggleFunctions([
|
|
1152
|
+
{ function: 'check_balance', active: true },
|
|
1153
|
+
{ function: 'make_payment', active: true },
|
|
1154
|
+
{ function: 'verify_identity', active: false },
|
|
1155
|
+
]);
|
|
1156
|
+
```
|
|
1157
|
+
|
|
1158
|
+
### enableFunctionsOnTimeout
|
|
1159
|
+
|
|
1160
|
+
Control whether the model can call functions on a speaker timeout, when the caller is silent (`functions_on_speaker_timeout`).
|
|
1161
|
+
|
|
1162
|
+
<!-- snippet: no-compile API signature reference, not runnable code -->
|
|
1163
|
+
```typescript
|
|
1164
|
+
enableFunctionsOnTimeout(enabled?: boolean): this
|
|
1165
|
+
```
|
|
1166
|
+
|
|
1167
|
+
| Parameter | Type | Default | Description |
|
|
1168
|
+
|-----------|-----------|---------|------------------------------------------------------|
|
|
1169
|
+
| `enabled` | `boolean` | `true` | Whether functions can be called on speaker timeout. |
|
|
1170
|
+
|
|
1171
|
+
**Returns:** `this` for chaining.
|
|
1172
|
+
|
|
1173
|
+
**Example:**
|
|
1174
|
+
|
|
1175
|
+
```typescript
|
|
1176
|
+
// Allow functions on speaker timeout
|
|
1177
|
+
const r1 = new FunctionResult('The caller may go quiet while searching.')
|
|
1178
|
+
.enableFunctionsOnTimeout();
|
|
1179
|
+
|
|
1180
|
+
// Disallow them
|
|
1181
|
+
const r2 = new FunctionResult('Wait for the caller to answer.')
|
|
1182
|
+
.enableFunctionsOnTimeout(false);
|
|
1183
|
+
```
|
|
1184
|
+
|
|
1185
|
+
### updateSettings
|
|
1186
|
+
|
|
1187
|
+
Update AI settings during the call (`settings`). The platform validates the keys. The Python SDK's reference lists `temperature`, `top-p`, `max-tokens`, `frequency-penalty`, `presence-penalty`, `confidence` and `barge-confidence`.
|
|
1188
|
+
|
|
1189
|
+
<!-- snippet: no-compile API signature reference, not runnable code -->
|
|
1190
|
+
```typescript
|
|
1191
|
+
updateSettings(settings: Record<string, unknown>): this
|
|
1192
|
+
```
|
|
1193
|
+
|
|
1194
|
+
| Parameter | Type | Description |
|
|
1195
|
+
|------------|----------------------------|--------------------------------------|
|
|
1196
|
+
| `settings` | `Record<string, unknown>` | Key-value pairs of settings. |
|
|
1197
|
+
|
|
1198
|
+
**Returns:** `this` for chaining.
|
|
1199
|
+
|
|
1200
|
+
**Example:**
|
|
1201
|
+
|
|
1202
|
+
```typescript
|
|
1203
|
+
const result = new FunctionResult('The settings are updated.')
|
|
1204
|
+
.updateSettings({ temperature: 0.3, 'top-p': 0.9 });
|
|
1205
|
+
```
|
|
1206
|
+
|
|
1207
|
+
## User Input and History
|
|
1208
|
+
|
|
1209
|
+
### simulateUserInput
|
|
1210
|
+
|
|
1211
|
+
Queue text as if the caller had said it (`user_input`). Use it to drive the conversation from code.
|
|
1212
|
+
|
|
1213
|
+
<!-- snippet: no-compile API signature reference, not runnable code -->
|
|
1214
|
+
```typescript
|
|
1215
|
+
simulateUserInput(text: string): this
|
|
1216
|
+
```
|
|
1217
|
+
|
|
1218
|
+
| Parameter | Type | Description |
|
|
1219
|
+
|-----------|----------|------------------------------------|
|
|
1220
|
+
| `text` | `string` | The simulated user input text. |
|
|
1221
|
+
|
|
1222
|
+
**Returns:** `this` for chaining.
|
|
1223
|
+
|
|
1224
|
+
**Example:**
|
|
1225
|
+
|
|
1226
|
+
```typescript
|
|
1227
|
+
const result = new FunctionResult('The caller accepted the default option.')
|
|
1228
|
+
.simulateUserInput('Yes, go ahead with the default.');
|
|
1229
|
+
```
|
|
1230
|
+
|
|
1231
|
+
### enableExtensiveData
|
|
1232
|
+
|
|
1233
|
+
Send the full data to the model for this turn only, and a smaller replacement in later turns (`extensive_data`).
|
|
1234
|
+
|
|
1235
|
+
<!-- snippet: no-compile API signature reference, not runnable code -->
|
|
1236
|
+
```typescript
|
|
1237
|
+
enableExtensiveData(enabled?: boolean): this
|
|
1238
|
+
```
|
|
1239
|
+
|
|
1240
|
+
| Parameter | Type | Default | Description |
|
|
1241
|
+
|-----------|-----------|---------|------------------------------------------|
|
|
1242
|
+
| `enabled` | `boolean` | `true` | Whether to send extensive data this turn. |
|
|
1243
|
+
|
|
1244
|
+
**Returns:** `this` for chaining.
|
|
1245
|
+
|
|
1246
|
+
**Example:**
|
|
1247
|
+
|
|
1248
|
+
```typescript
|
|
1249
|
+
const result = new FunctionResult('The full order history is attached.')
|
|
1250
|
+
.enableExtensiveData();
|
|
1251
|
+
```
|
|
1252
|
+
|
|
1253
|
+
### replaceInHistory
|
|
1254
|
+
|
|
1255
|
+
After the first send, remove or replace this tool call and its result in the conversation history (`replace_in_history`). Use it when a function call is an implementation detail that would confuse the model if it stayed in context.
|
|
1256
|
+
|
|
1257
|
+
<!-- snippet: no-compile API signature reference, not runnable code -->
|
|
1258
|
+
```typescript
|
|
1259
|
+
replaceInHistory(text?: string | boolean): this
|
|
1260
|
+
```
|
|
1261
|
+
|
|
1262
|
+
| Parameter | Type | Default | Description |
|
|
1263
|
+
|-----------|-----------------------|---------|-----------------------------------------------------------|
|
|
1264
|
+
| `text` | `string \| boolean` | `true` | A string replaces the pair with an assistant message holding that text. `true` removes the pair. |
|
|
1265
|
+
|
|
1266
|
+
**Returns:** `this` for chaining.
|
|
1267
|
+
|
|
1268
|
+
**Example:**
|
|
1269
|
+
|
|
1270
|
+
```typescript
|
|
1271
|
+
// Remove the tool call and result from the history
|
|
1272
|
+
const r1 = new FunctionResult('The answer is saved.')
|
|
1273
|
+
.replaceInHistory();
|
|
1274
|
+
|
|
1275
|
+
// Replace them with an assistant message
|
|
1276
|
+
const r2 = new FunctionResult('The identity check passed.')
|
|
1277
|
+
.replaceInHistory('Identity verification completed.');
|
|
1278
|
+
```
|
|
1279
|
+
|
|
1280
|
+
## Communication
|
|
1281
|
+
|
|
1282
|
+
### sendSms
|
|
1283
|
+
|
|
1284
|
+
Send an SMS or MMS message from within the call flow. The SDK emits an inline SWML `send_sms` verb. Provide `body`, `media`, or both.
|
|
1285
|
+
|
|
1286
|
+
<!-- snippet: no-compile API signature reference, not runnable code -->
|
|
1287
|
+
```typescript
|
|
1288
|
+
sendSms(opts: {
|
|
1289
|
+
toNumber: string;
|
|
1290
|
+
fromNumber: string;
|
|
1291
|
+
body?: string;
|
|
1292
|
+
media?: string[];
|
|
1293
|
+
tags?: string[];
|
|
1294
|
+
region?: string;
|
|
1295
|
+
}): this
|
|
1296
|
+
```
|
|
1297
|
+
|
|
1298
|
+
| Parameter | Type | Description |
|
|
1299
|
+
|------------------|------------|------------------------------------------------|
|
|
1300
|
+
| `opts.toNumber` | `string` | Recipient phone number, in E.164 format. |
|
|
1301
|
+
| `opts.fromNumber` | `string` | Sender phone number, in E.164 format. |
|
|
1302
|
+
| `opts.body` | `string` | Message text. |
|
|
1303
|
+
| `opts.media` | `string[]` | Media URLs for an MMS. |
|
|
1304
|
+
| `opts.tags` | `string[]` | Tags for the message. |
|
|
1305
|
+
| `opts.region` | `string` | Region to send the message from. |
|
|
1306
|
+
|
|
1307
|
+
**Throws:** `Error` if neither `body` nor `media` is provided.
|
|
1308
|
+
|
|
1309
|
+
**Returns:** `this` for chaining.
|
|
1310
|
+
|
|
1311
|
+
**Example:**
|
|
1312
|
+
|
|
1313
|
+
```typescript
|
|
1314
|
+
// Send a text message
|
|
1315
|
+
const result = new FunctionResult('The confirmation text is sent.')
|
|
1316
|
+
.sendSms({
|
|
1317
|
+
toNumber: '+15551234567',
|
|
1318
|
+
fromNumber: '+15559876543',
|
|
1319
|
+
body: 'Your appointment is confirmed for tomorrow at 2pm.',
|
|
1320
|
+
});
|
|
1321
|
+
|
|
1322
|
+
// Send an MMS with an image
|
|
1323
|
+
const result2 = new FunctionResult('The receipt is sent.')
|
|
1324
|
+
.sendSms({
|
|
1325
|
+
toNumber: '+15551234567',
|
|
1326
|
+
fromNumber: '+15559876543',
|
|
1327
|
+
body: 'Here is your receipt:',
|
|
1328
|
+
media: ['https://example.com/receipt.png'],
|
|
1329
|
+
});
|
|
1330
|
+
```
|
|
1331
|
+
|
|
1332
|
+
### recordCall
|
|
1333
|
+
|
|
1334
|
+
Start a background recording of the call. The SDK emits an inline SWML `record_call` verb, and the call continues while it records.
|
|
1335
|
+
|
|
1336
|
+
<!-- snippet: no-compile API signature reference, not runnable code -->
|
|
1337
|
+
```typescript
|
|
1338
|
+
recordCall(opts?: {
|
|
1339
|
+
controlId?: string;
|
|
1340
|
+
stereo?: boolean;
|
|
1341
|
+
format?: 'wav' | 'mp3' | 'mp4';
|
|
1342
|
+
direction?: 'speak' | 'listen' | 'both';
|
|
1343
|
+
terminators?: string;
|
|
1344
|
+
beep?: boolean;
|
|
1345
|
+
inputSensitivity?: number;
|
|
1346
|
+
initialTimeout?: number;
|
|
1347
|
+
endSilenceTimeout?: number;
|
|
1348
|
+
maxLength?: number;
|
|
1349
|
+
statusUrl?: string;
|
|
1350
|
+
}): this
|
|
1351
|
+
```
|
|
1352
|
+
|
|
1353
|
+
| Parameter | Type | Default | Description |
|
|
1354
|
+
|-------------------------|---------------------------------|----------|-------------------------------------------------|
|
|
1355
|
+
| `opts.controlId` | `string` | none | Identifier for this recording, for `stopRecordCall()`. |
|
|
1356
|
+
| `opts.stereo` | `boolean` | `false` | Record in stereo. |
|
|
1357
|
+
| `opts.format` | `'wav' \| 'mp3' \| 'mp4'` | `'wav'` | Recording file format. |
|
|
1358
|
+
| `opts.direction` | `'speak' \| 'listen' \| 'both'` | `'both'` | Audio to record: what the party says, hears, or both. |
|
|
1359
|
+
| `opts.terminators` | `string` | none | DTMF digits that stop the recording. |
|
|
1360
|
+
| `opts.beep` | `boolean` | `false` | Play a beep before recording. |
|
|
1361
|
+
| `opts.inputSensitivity` | `number` | `44.0` | Sensitivity of the voice activity detector to background noise, from 0 to 100. |
|
|
1362
|
+
| `opts.initialTimeout` | `number` | none | Seconds to wait for speech to start. |
|
|
1363
|
+
| `opts.endSilenceTimeout`| `number` | none | Seconds of silence before the recording ends. |
|
|
1364
|
+
| `opts.maxLength` | `number` | none | Maximum recording length in seconds. |
|
|
1365
|
+
| `opts.statusUrl` | `string` | none | URL that receives recording status events. |
|
|
1366
|
+
|
|
1367
|
+
The SDK always sends `stereo`, `format`, `direction`, `beep` and `input_sensitivity`, and sends the other options only when set.
|
|
1368
|
+
|
|
1369
|
+
**Returns:** `this` for chaining.
|
|
1370
|
+
|
|
1371
|
+
**Example:**
|
|
1372
|
+
|
|
1373
|
+
```typescript
|
|
1374
|
+
// Record with the defaults
|
|
1375
|
+
const result = new FunctionResult('The recording has started.')
|
|
1376
|
+
.recordCall();
|
|
1377
|
+
|
|
1378
|
+
// Stereo MP3 recording with a control ID
|
|
1379
|
+
const result2 = new FunctionResult('The recording has started.')
|
|
1380
|
+
.recordCall({
|
|
1381
|
+
controlId: 'main-recording',
|
|
1382
|
+
stereo: true,
|
|
1383
|
+
format: 'mp3',
|
|
1384
|
+
maxLength: 3600,
|
|
1385
|
+
statusUrl: 'https://example.com/recording-status',
|
|
1386
|
+
});
|
|
1387
|
+
```
|
|
1388
|
+
|
|
1389
|
+
### stopRecordCall
|
|
1390
|
+
|
|
1391
|
+
Stop a background recording (SWML `stop_record_call`).
|
|
1392
|
+
|
|
1393
|
+
<!-- snippet: no-compile API signature reference, not runnable code -->
|
|
1394
|
+
```typescript
|
|
1395
|
+
stopRecordCall(controlId?: string): this
|
|
1396
|
+
```
|
|
1397
|
+
|
|
1398
|
+
| Parameter | Type | Description |
|
|
1399
|
+
|-------------|----------|--------------------------------------------------|
|
|
1400
|
+
| `controlId` | `string` | Control ID of the recording to stop. Omit it to stop the most recent recording. |
|
|
1401
|
+
|
|
1402
|
+
**Returns:** `this` for chaining.
|
|
1403
|
+
|
|
1404
|
+
**Example:**
|
|
1405
|
+
|
|
1406
|
+
```typescript
|
|
1407
|
+
const result = new FunctionResult('The recording has stopped.')
|
|
1408
|
+
.stopRecordCall('main-recording');
|
|
1409
|
+
```
|
|
1410
|
+
|
|
1411
|
+
### tap
|
|
1412
|
+
|
|
1413
|
+
Start a background media tap, which streams the call's audio to a WebSocket or RTP destination, for example for real-time transcription or monitoring. The SDK emits an inline SWML `tap` verb.
|
|
1414
|
+
|
|
1415
|
+
<!-- snippet: no-compile API signature reference, not runnable code -->
|
|
1416
|
+
```typescript
|
|
1417
|
+
tap(opts: {
|
|
1418
|
+
uri: string;
|
|
1419
|
+
controlId?: string;
|
|
1420
|
+
direction?: 'speak' | 'listen' | 'both';
|
|
1421
|
+
codec?: 'PCMU' | 'PCMA';
|
|
1422
|
+
rtpPtime?: number;
|
|
1423
|
+
statusUrl?: string;
|
|
1424
|
+
}): this
|
|
1425
|
+
```
|
|
1426
|
+
|
|
1427
|
+
| Parameter | Type | Default | Description |
|
|
1428
|
+
|------------------|----------------------------------|----------|----------------------------------------------|
|
|
1429
|
+
| `opts.uri` | `string` | none | Destination of the stream: `ws://...`, `wss://...` or `rtp://IP:port`. |
|
|
1430
|
+
| `opts.controlId` | `string` | none | Identifier for this tap, for `stopTap()`. |
|
|
1431
|
+
| `opts.direction` | `'speak' \| 'listen' \| 'both'` | `'both'` | `speak` is what the party says, `listen` is what it hears, and `both` is both. |
|
|
1432
|
+
| `opts.codec` | `'PCMU' \| 'PCMA'` | `'PCMU'` | Audio codec for the stream. |
|
|
1433
|
+
| `opts.rtpPtime` | `number` | `20` | RTP packetization time in milliseconds, for an `rtp://` destination. |
|
|
1434
|
+
| `opts.statusUrl` | `string` | none | URL that receives tap status events. |
|
|
1435
|
+
|
|
1436
|
+
The SDK always sends `direction`, because the SWML `tap` verb defaults to `speak` when it's missing. It sends `codec` and `rtp_ptime` only when they differ from `PCMU` and 20.
|
|
1437
|
+
|
|
1438
|
+
**Throws:** `Error` when `direction` or `codec` isn't one of the listed values, or `rtpPtime` isn't positive.
|
|
1439
|
+
|
|
1440
|
+
**Returns:** `this` for chaining.
|
|
1441
|
+
|
|
1442
|
+
**Example:**
|
|
1443
|
+
|
|
1444
|
+
```typescript
|
|
1445
|
+
const result = new FunctionResult('The transcription stream has started.')
|
|
1446
|
+
.tap({
|
|
1447
|
+
uri: 'wss://transcription.example.com/stream',
|
|
1448
|
+
controlId: 'realtime-tap',
|
|
1449
|
+
direction: 'both',
|
|
1450
|
+
});
|
|
1451
|
+
```
|
|
1452
|
+
|
|
1453
|
+
### stopTap
|
|
1454
|
+
|
|
1455
|
+
Stop a media tap (SWML `stop_tap`).
|
|
1456
|
+
|
|
1457
|
+
<!-- snippet: no-compile API signature reference, not runnable code -->
|
|
1458
|
+
```typescript
|
|
1459
|
+
stopTap(controlId?: string): this
|
|
1460
|
+
```
|
|
1461
|
+
|
|
1462
|
+
| Parameter | Type | Description |
|
|
1463
|
+
|-------------|----------|---------------------------------------------|
|
|
1464
|
+
| `controlId` | `string` | Control ID of the tap to stop. Omit it to stop the most recent tap. |
|
|
1465
|
+
|
|
1466
|
+
**Returns:** `this` for chaining.
|
|
1467
|
+
|
|
1468
|
+
**Example:**
|
|
1469
|
+
|
|
1470
|
+
```typescript
|
|
1471
|
+
const result = new FunctionResult('The transcription stream has stopped.')
|
|
1472
|
+
.stopTap('realtime-tap');
|
|
1473
|
+
```
|
|
1474
|
+
|
|
1475
|
+
## Rooms and Conferencing
|
|
1476
|
+
|
|
1477
|
+
### joinRoom
|
|
1478
|
+
|
|
1479
|
+
Join a RELAY room by name (SWML `join_room`). The platform creates the room if it doesn't exist.
|
|
1480
|
+
|
|
1481
|
+
<!-- snippet: no-compile API signature reference, not runnable code -->
|
|
1482
|
+
```typescript
|
|
1483
|
+
joinRoom(name: string): this
|
|
1484
|
+
```
|
|
1485
|
+
|
|
1486
|
+
| Parameter | Type | Description |
|
|
1487
|
+
|-----------|----------|-----------------------|
|
|
1488
|
+
| `name` | `string` | The room name. Letters, digits, underscores and hyphens are allowed. |
|
|
1489
|
+
|
|
1490
|
+
**Returns:** `this` for chaining.
|
|
1491
|
+
|
|
1492
|
+
**Example:**
|
|
1493
|
+
|
|
1494
|
+
```typescript
|
|
1495
|
+
const result = new FunctionResult('The caller is joining the team meeting.')
|
|
1496
|
+
.joinRoom('team-standup');
|
|
1497
|
+
```
|
|
1498
|
+
|
|
1499
|
+
### sipRefer
|
|
1500
|
+
|
|
1501
|
+
Send a SIP REFER to transfer the call to another SIP endpoint (SWML `sip_refer`).
|
|
1502
|
+
|
|
1503
|
+
<!-- snippet: no-compile API signature reference, not runnable code -->
|
|
1504
|
+
```typescript
|
|
1505
|
+
sipRefer(toUri: string): this
|
|
1506
|
+
```
|
|
1507
|
+
|
|
1508
|
+
| Parameter | Type | Description |
|
|
1509
|
+
|-----------|----------|---------------------------------------|
|
|
1510
|
+
| `toUri` | `string` | The SIP URI to send the REFER to. |
|
|
1511
|
+
|
|
1512
|
+
**Returns:** `this` for chaining.
|
|
1513
|
+
|
|
1514
|
+
**Example:**
|
|
1515
|
+
|
|
1516
|
+
```typescript
|
|
1517
|
+
const result = new FunctionResult('Tell the caller you are transferring them.', true)
|
|
1518
|
+
.sipRefer('sip:agent@pbx.example.com');
|
|
1519
|
+
```
|
|
1520
|
+
|
|
1521
|
+
### joinConference
|
|
1522
|
+
|
|
1523
|
+
Join a conference by name (SWML `join_conference`), with optional settings.
|
|
1524
|
+
|
|
1525
|
+
<!-- snippet: no-compile API signature reference, not runnable code -->
|
|
1526
|
+
```typescript
|
|
1527
|
+
joinConference(name: string, opts?: {
|
|
1528
|
+
muted?: boolean;
|
|
1529
|
+
beep?: 'true' | 'false' | 'onEnter' | 'onExit';
|
|
1530
|
+
startOnEnter?: boolean;
|
|
1531
|
+
endOnExit?: boolean;
|
|
1532
|
+
waitUrl?: string;
|
|
1533
|
+
maxParticipants?: number | string;
|
|
1534
|
+
record?: 'do-not-record' | 'record-from-start';
|
|
1535
|
+
region?: string;
|
|
1536
|
+
trim?: 'trim-silence' | 'do-not-trim';
|
|
1537
|
+
coach?: string;
|
|
1538
|
+
statusCallbackEvent?: string;
|
|
1539
|
+
statusCallback?: string;
|
|
1540
|
+
statusCallbackMethod?: 'GET' | 'POST';
|
|
1541
|
+
recordingStatusCallback?: string;
|
|
1542
|
+
recordingStatusCallbackMethod?: 'GET' | 'POST';
|
|
1543
|
+
recordingStatusCallbackEvent?: string;
|
|
1544
|
+
result?: unknown;
|
|
1545
|
+
}): this
|
|
1546
|
+
```
|
|
1547
|
+
|
|
1548
|
+
| Parameter | Type | Default | Description |
|
|
1549
|
+
|----------------------------------------|---------------------------------------------|---------------------|------------------------------------------------------|
|
|
1550
|
+
| `name` | `string` | none | Conference name. Must not be blank. |
|
|
1551
|
+
| `opts.muted` | `boolean` | `false` | Join muted. |
|
|
1552
|
+
| `opts.beep` | `'true' \| 'false' \| 'onEnter' \| 'onExit'` | `'true'` | When to play the beep. |
|
|
1553
|
+
| `opts.startOnEnter` | `boolean` | `true` | Start the conference when this participant joins. |
|
|
1554
|
+
| `opts.endOnExit` | `boolean` | `false` | End the conference when this participant leaves. |
|
|
1555
|
+
| `opts.waitUrl` | `string` | none | URL of media to play while the conference is on hold. |
|
|
1556
|
+
| `opts.maxParticipants` | `number \| string` | none | Maximum number of participants, an integer of 2 or more, or a SWML variable reference such as `'${room_size}'`. A numeric string is sent as an integer. Sent whenever it's given. The platform refuses fewer than 2 and sets no upper limit; the schema's cap of 100000 isn't enforced. |
|
|
1557
|
+
| `opts.record` | `'do-not-record' \| 'record-from-start'` | `'do-not-record'` | Recording mode. |
|
|
1558
|
+
| `opts.region` | `string` | none | Region for the conference. |
|
|
1559
|
+
| `opts.trim` | `'trim-silence' \| 'do-not-trim'` | `'trim-silence'` | Silence trimming for recordings. |
|
|
1560
|
+
| `opts.coach` | `string` | none | Call SID of a call connected to the conference, to coach. |
|
|
1561
|
+
| `opts.statusCallbackEvent` | `string` | none | Space-separated events to send to the status callback. |
|
|
1562
|
+
| `opts.statusCallback` | `string` | none | URL for status callbacks. |
|
|
1563
|
+
| `opts.statusCallbackMethod` | `'GET' \| 'POST'` | `'POST'` | HTTP method for status callbacks. |
|
|
1564
|
+
| `opts.recordingStatusCallback` | `string` | none | URL for recording status callbacks. |
|
|
1565
|
+
| `opts.recordingStatusCallbackMethod` | `'GET' \| 'POST'` | `'POST'` | HTTP method for recording status callbacks. |
|
|
1566
|
+
| `opts.recordingStatusCallbackEvent` | `string` | `'completed'` | Events to send to the recording status callback. |
|
|
1567
|
+
| `opts.result` | `unknown` | none | Actions to switch on by result, as the verb's `result` object. |
|
|
1568
|
+
|
|
1569
|
+
**Behavior:** The SDK leaves out any option set to its default value, except `maxParticipants`, which is sent whenever it's given. When no option remains, the `join_conference` value is the name string. Otherwise it's an object with `name` and the other options.
|
|
1570
|
+
|
|
1571
|
+
**Throws:** `Error` when `name` is blank, or `maxParticipants` isn't an integer of at least 2 or a SWML variable reference.
|
|
1572
|
+
|
|
1573
|
+
**Returns:** `this` for chaining.
|
|
1574
|
+
|
|
1575
|
+
**Example:**
|
|
1576
|
+
|
|
1577
|
+
```typescript
|
|
1578
|
+
// Join with the defaults
|
|
1579
|
+
const result = new FunctionResult('The caller is joining the support conference.')
|
|
1580
|
+
.joinConference('support-queue');
|
|
1581
|
+
|
|
1582
|
+
// Join muted, recorded, and capped at 50 participants
|
|
1583
|
+
const result2 = new FunctionResult('The caller is joining as a listener.')
|
|
1584
|
+
.joinConference('all-hands', {
|
|
1585
|
+
muted: true,
|
|
1586
|
+
record: 'record-from-start',
|
|
1587
|
+
maxParticipants: 50,
|
|
1588
|
+
beep: 'onEnter',
|
|
1589
|
+
});
|
|
1590
|
+
```
|
|
1591
|
+
|
|
1592
|
+
## RPC
|
|
1593
|
+
|
|
1594
|
+
### executeRpc
|
|
1595
|
+
|
|
1596
|
+
Run a SignalWire RPC method from an inline SWML `execute_rpc` verb. It's the low-level method under `rpcDial()`, `rpcAiMessage()`, `rpcAiGlobalData()` and `rpcAiUnhold()`, which use the `dial`, `ai_message` and `ai_unhold` methods.
|
|
1597
|
+
|
|
1598
|
+
<!-- snippet: no-compile API signature reference, not runnable code -->
|
|
1599
|
+
```typescript
|
|
1600
|
+
executeRpc(opts: {
|
|
1601
|
+
method: string;
|
|
1602
|
+
params?: Record<string, unknown>;
|
|
1603
|
+
callId?: string;
|
|
1604
|
+
nodeId?: string;
|
|
1605
|
+
}): this
|
|
1606
|
+
```
|
|
1607
|
+
|
|
1608
|
+
| Parameter | Type | Description |
|
|
1609
|
+
|---------------|----------------------------|-------------------------------------|
|
|
1610
|
+
| `opts.method` | `string` | The RPC method name. |
|
|
1611
|
+
| `opts.params` | `Record<string, unknown>` | Parameters for the method. An empty object is left out. |
|
|
1612
|
+
| `opts.callId` | `string` | Target call ID. |
|
|
1613
|
+
| `opts.nodeId` | `string` | Target node ID. |
|
|
1614
|
+
|
|
1615
|
+
**Returns:** `this` for chaining.
|
|
1616
|
+
|
|
1617
|
+
**Example:**
|
|
1618
|
+
|
|
1619
|
+
```typescript
|
|
1620
|
+
const result = new FunctionResult('The other caller has been notified.')
|
|
1621
|
+
.executeRpc({
|
|
1622
|
+
method: 'ai_message',
|
|
1623
|
+
callId: 'call-abc-123',
|
|
1624
|
+
params: { role: 'system', message_text: 'The customer has been verified.' },
|
|
1625
|
+
});
|
|
1626
|
+
```
|
|
1627
|
+
|
|
1628
|
+
### rpcDial
|
|
1629
|
+
|
|
1630
|
+
Dial out with the `dial` RPC method. Use it, for example, to hold the caller and dial a person whose call runs the SWML at `destSwml`.
|
|
1631
|
+
|
|
1632
|
+
<!-- snippet: no-compile API signature reference, not runnable code -->
|
|
1633
|
+
```typescript
|
|
1634
|
+
rpcDial(
|
|
1635
|
+
toNumber: string,
|
|
1636
|
+
fromNumber: string,
|
|
1637
|
+
destSwml: string,
|
|
1638
|
+
deviceType?: string
|
|
1639
|
+
): this
|
|
1640
|
+
```
|
|
1641
|
+
|
|
1642
|
+
| Parameter | Type | Default | Description |
|
|
1643
|
+
|--------------|----------|-----------|------------------------------------------|
|
|
1644
|
+
| `toNumber` | `string` | none | Number to dial, in E.164 format. |
|
|
1645
|
+
| `fromNumber` | `string` | none | Caller ID, in E.164 format. |
|
|
1646
|
+
| `destSwml` | `string` | none | URL of the SWML that handles the dialed call. |
|
|
1647
|
+
| `deviceType` | `string` | `'phone'` | Device type for the outbound leg. |
|
|
1648
|
+
|
|
1649
|
+
**Returns:** `this` for chaining.
|
|
1650
|
+
|
|
1651
|
+
**Example:**
|
|
1652
|
+
|
|
1653
|
+
```typescript
|
|
1654
|
+
const result = new FunctionResult()
|
|
1655
|
+
.hold('Tell the caller you are checking whether a manager is available.', 120)
|
|
1656
|
+
.rpcDial('+15551234567', '+15559876543', 'https://example.com/manager-swml');
|
|
1657
|
+
```
|
|
1658
|
+
|
|
1659
|
+
### rpcAiMessage
|
|
1660
|
+
|
|
1661
|
+
Send a message, global data, or both to the AI agent on another call, with the `ai_message` RPC method.
|
|
1662
|
+
|
|
1663
|
+
<!-- snippet: no-compile API signature reference, not runnable code -->
|
|
1664
|
+
```typescript
|
|
1665
|
+
rpcAiMessage(
|
|
1666
|
+
callId: string,
|
|
1667
|
+
messageText?: string | null,
|
|
1668
|
+
role?: string,
|
|
1669
|
+
globalData?: Record<string, unknown>
|
|
1670
|
+
): this
|
|
1671
|
+
```
|
|
1672
|
+
|
|
1673
|
+
| Parameter | Type | Default | Description |
|
|
1674
|
+
|---------------|---------------------------|------------|-------------------------------------------------|
|
|
1675
|
+
| `callId` | `string` | none | The target call ID. |
|
|
1676
|
+
| `messageText` | `string \| null` | none | Message to add as a turn in the other conversation. |
|
|
1677
|
+
| `role` | `string` | `'system'` | Role for the message. Sent only with `messageText`. |
|
|
1678
|
+
| `globalData` | `Record<string, unknown>` | none | Object merged into the target call's global data. |
|
|
1679
|
+
|
|
1680
|
+
**Throws:** `Error` when neither `messageText` nor `globalData` is given.
|
|
1681
|
+
|
|
1682
|
+
**Returns:** `this` for chaining.
|
|
1683
|
+
|
|
1684
|
+
The two payloads behave differently. `messageText` arrives as a turn in the other conversation, alongside everything else arriving then. `globalData` is merged into the other call's global data without a turn, and a prompt there reads it with `${global_data.your_key}`. For content that a later step on the other call must say, prefer global data. [rpcAiGlobalData](#rpcaiglobaldata) sends global data only.
|
|
1685
|
+
|
|
1686
|
+
**Example:**
|
|
1687
|
+
|
|
1688
|
+
```typescript
|
|
1689
|
+
const result = new FunctionResult('The manager declined the call.')
|
|
1690
|
+
.rpcAiMessage('call-abc-123', 'No one is available. Take a message.')
|
|
1691
|
+
.rpcAiUnhold('call-abc-123');
|
|
1692
|
+
```
|
|
1693
|
+
|
|
1694
|
+
### rpcAiGlobalData
|
|
1695
|
+
|
|
1696
|
+
Merge data into another call's global data, with no conversation turn. It calls `rpcAiMessage(callId, undefined, 'system', data)`.
|
|
1697
|
+
|
|
1698
|
+
<!-- snippet: no-compile API signature reference, not runnable code -->
|
|
1699
|
+
```typescript
|
|
1700
|
+
rpcAiGlobalData(callId: string, data: Record<string, unknown>): this
|
|
1701
|
+
```
|
|
1702
|
+
|
|
1703
|
+
| Parameter | Type | Description |
|
|
1704
|
+
|-----------|---------------------------|----------------------------------------------|
|
|
1705
|
+
| `callId` | `string` | The target call ID. |
|
|
1706
|
+
| `data` | `Record<string, unknown>` | Object merged into that call's global data. |
|
|
1707
|
+
|
|
1708
|
+
**Returns:** `this` for chaining.
|
|
1709
|
+
|
|
1710
|
+
This example sends a message for the held caller's agent and then releases the hold:
|
|
1711
|
+
|
|
1712
|
+
```typescript
|
|
1713
|
+
const result = new FunctionResult('The manager declined the call.')
|
|
1714
|
+
.rpcAiGlobalData('call-abc-123', {
|
|
1715
|
+
decline_message: 'The manager is in a meeting until 3pm.',
|
|
1716
|
+
})
|
|
1717
|
+
.rpcAiUnhold('call-abc-123');
|
|
1718
|
+
```
|
|
1719
|
+
|
|
1720
|
+
A step on the other call can then use the value, with text such as `Tell the caller: ${global_data.decline_message}`.
|
|
1721
|
+
|
|
1722
|
+
### rpcAiUnhold
|
|
1723
|
+
|
|
1724
|
+
Take another call off hold, with the `ai_unhold` RPC method. When that call's hold has a `step`, the call moves to that step. For more information, see [hold](#hold).
|
|
1725
|
+
|
|
1726
|
+
<!-- snippet: no-compile API signature reference, not runnable code -->
|
|
1727
|
+
```typescript
|
|
1728
|
+
rpcAiUnhold(callId: string): this
|
|
1729
|
+
```
|
|
1730
|
+
|
|
1731
|
+
| Parameter | Type | Description |
|
|
1732
|
+
|-----------|----------|--------------------------------|
|
|
1733
|
+
| `callId` | `string` | The ID of the call to take off hold. |
|
|
1734
|
+
|
|
1735
|
+
**Returns:** `this` for chaining.
|
|
1736
|
+
|
|
1737
|
+
**Example:**
|
|
1738
|
+
|
|
1739
|
+
```typescript
|
|
1740
|
+
const result = new FunctionResult('The held caller is being reconnected.')
|
|
1741
|
+
.rpcAiUnhold('call-abc-123');
|
|
1742
|
+
```
|
|
1743
|
+
|
|
1744
|
+
## Payments
|
|
1745
|
+
|
|
1746
|
+
### pay
|
|
1747
|
+
|
|
1748
|
+
Start a payment collection flow on the call. The SDK emits an inline SWML document that sets `ai_response` with the `set` verb and then runs the `pay` verb. The payment connector at `paymentConnectorUrl` processes the payment.
|
|
1749
|
+
|
|
1750
|
+
<!-- snippet: no-compile API signature reference, not runnable code -->
|
|
1751
|
+
```typescript
|
|
1752
|
+
pay(opts: {
|
|
1753
|
+
paymentConnectorUrl: string;
|
|
1754
|
+
inputMethod?: string;
|
|
1755
|
+
statusUrl?: string;
|
|
1756
|
+
paymentMethod?: string;
|
|
1757
|
+
timeout?: number | string;
|
|
1758
|
+
maxAttempts?: number | string;
|
|
1759
|
+
securityCode?: boolean | string;
|
|
1760
|
+
postalCode?: boolean | string;
|
|
1761
|
+
minPostalCodeLength?: number | string;
|
|
1762
|
+
tokenType?: string;
|
|
1763
|
+
chargeAmount?: string;
|
|
1764
|
+
currency?: string;
|
|
1765
|
+
language?: string;
|
|
1766
|
+
voice?: string;
|
|
1767
|
+
description?: string;
|
|
1768
|
+
validCardTypes?: string;
|
|
1769
|
+
parameters?: PaymentParameter[];
|
|
1770
|
+
prompts?: PaymentPrompt[];
|
|
1771
|
+
aiResponse?: string;
|
|
1772
|
+
}): this
|
|
1773
|
+
```
|
|
1774
|
+
|
|
1775
|
+
| Parameter | Type | Default | Description |
|
|
1776
|
+
|----------------------------|----------------------|---------------------------------------|-----------------------------------------------------------------|
|
|
1777
|
+
| `opts.paymentConnectorUrl` | `string` | none | URL of the payment connector. |
|
|
1778
|
+
| `opts.inputMethod` | `string` | `'dtmf'` | How the caller enters details. The SWML `pay` verb accepts only `'dtmf'`. |
|
|
1779
|
+
| `opts.statusUrl` | `string` | none | URL that receives payment status events. |
|
|
1780
|
+
| `opts.paymentMethod` | `string` | `'credit-card'` | Payment method. The verb accepts only `'credit-card'`. |
|
|
1781
|
+
| `opts.timeout` | `number \| string` | `5` | Seconds to wait for the next digit. |
|
|
1782
|
+
| `opts.maxAttempts` | `number \| string` | `1` | Number of times the `pay` verb retries collecting the details. |
|
|
1783
|
+
| `opts.securityCode` | `boolean \| string` | `true` | Whether to ask for the security code. |
|
|
1784
|
+
| `opts.postalCode` | `boolean \| string` | `true` | Whether to ask for the postal code, or the postal code itself when it's known. |
|
|
1785
|
+
| `opts.minPostalCodeLength` | `number \| string` | `0` | Minimum postal code length. |
|
|
1786
|
+
| `opts.tokenType` | `string` | `'reusable'` | `'one-time'` or `'reusable'`. |
|
|
1787
|
+
| `opts.chargeAmount` | `string` | none | Amount to charge, as a decimal string (for example `'29.99'`). |
|
|
1788
|
+
| `opts.currency` | `string` | `'usd'` | ISO 4217 currency code. |
|
|
1789
|
+
| `opts.language` | `string` | `'en-US'` | Language of the payment prompts. |
|
|
1790
|
+
| `opts.voice` | `string` | `'woman'` | Text-to-speech voice for the payment prompts. |
|
|
1791
|
+
| `opts.description` | `string` | none | Description of the payment. |
|
|
1792
|
+
| `opts.validCardTypes` | `string` | `'visa mastercard amex'` | Space-separated list of accepted card types. |
|
|
1793
|
+
| `opts.parameters` | `PaymentParameter[]` | none | Name-value pairs for the payment connector. |
|
|
1794
|
+
| `opts.prompts` | `PaymentPrompt[]` | none | Custom prompts for payment steps. |
|
|
1795
|
+
| `opts.aiResponse` | `string` | Text that references `${pay_result}` | Set as `ai_response` before the `pay` verb runs. |
|
|
1796
|
+
|
|
1797
|
+
The SDK sends `timeout`, `max_attempts`, `min_postal_code_length`, `security_code` and `postal_code` as strings, as the platform reads them: its SWML validator requires strings for `security_code` and `postal_code`, and the pay request reads all five as strings. The bundled SWML schema types some of them as integers and booleans, but the platform's own checks win. The SDK checks each input first: `timeout`, `maxAttempts` and `minPostalCodeLength` must be integers or numeric strings, and `securityCode` a boolean or `'true'` or `'false'`. A SWML variable reference such as `'${pay_timeout}'` is sent as written. The default `aiResponse` is `The payment status is ${pay_result}, do not mention anything else about collecting payment if successful.`
|
|
1798
|
+
|
|
1799
|
+
**Throws:** `Error` when `timeout`, `maxAttempts` or `minPostalCodeLength` isn't an integer, or `securityCode` isn't a boolean, or a SWML variable reference.
|
|
1800
|
+
|
|
1801
|
+
**Returns:** `this` for chaining.
|
|
1802
|
+
|
|
1803
|
+
**Example:**
|
|
1804
|
+
|
|
1805
|
+
```typescript
|
|
1806
|
+
const result = new FunctionResult('Tell the caller you are starting the card payment.', true)
|
|
1807
|
+
.pay({
|
|
1808
|
+
paymentConnectorUrl: 'https://payments.example.com/connector',
|
|
1809
|
+
chargeAmount: '49.99',
|
|
1810
|
+
currency: 'usd',
|
|
1811
|
+
maxAttempts: 3,
|
|
1812
|
+
timeout: 10,
|
|
1813
|
+
});
|
|
1814
|
+
```
|
|
1815
|
+
|
|
1816
|
+
### createPaymentPrompt (static)
|
|
1817
|
+
|
|
1818
|
+
Create a `PaymentPrompt` object for the `prompts` option of `pay()`.
|
|
1819
|
+
|
|
1820
|
+
<!-- snippet: no-compile API signature reference, not runnable code -->
|
|
1821
|
+
```typescript
|
|
1822
|
+
static createPaymentPrompt(
|
|
1823
|
+
forSituation: string,
|
|
1824
|
+
actions: PaymentAction[],
|
|
1825
|
+
cardType?: string,
|
|
1826
|
+
errorType?: string
|
|
1827
|
+
): PaymentPrompt
|
|
1828
|
+
```
|
|
1829
|
+
|
|
1830
|
+
| Parameter | Type | Description |
|
|
1831
|
+
|----------------|-------------------|---------------------------------------------------|
|
|
1832
|
+
| `forSituation` | `string` | The payment step the prompt is for, such as `'payment-card-number'`, `'expiration-date'` or `'security-code'`. |
|
|
1833
|
+
| `actions` | `PaymentAction[]` | Actions to perform for this prompt. |
|
|
1834
|
+
| `cardType` | `string` | Space-separated card types the prompt applies to (for example `'visa'`). |
|
|
1835
|
+
| `errorType` | `string` | Space-separated error types the prompt applies to (for example `'invalid-card-number timeout'`). |
|
|
1836
|
+
|
|
1837
|
+
**Returns:** A `PaymentPrompt` object.
|
|
1838
|
+
|
|
1839
|
+
**Example:**
|
|
1840
|
+
|
|
1841
|
+
```typescript
|
|
1842
|
+
const prompt = FunctionResult.createPaymentPrompt(
|
|
1843
|
+
'payment-card-number',
|
|
1844
|
+
[FunctionResult.createPaymentAction('Say', 'Enter your card number.')],
|
|
1845
|
+
);
|
|
1846
|
+
```
|
|
1847
|
+
|
|
1848
|
+
### createPaymentAction (static)
|
|
1849
|
+
|
|
1850
|
+
Create a `PaymentAction` for a `PaymentPrompt`.
|
|
1851
|
+
|
|
1852
|
+
<!-- snippet: no-compile API signature reference, not runnable code -->
|
|
1853
|
+
```typescript
|
|
1854
|
+
static createPaymentAction(actionType: string, phrase: string): PaymentAction
|
|
1855
|
+
```
|
|
1856
|
+
|
|
1857
|
+
| Parameter | Type | Description |
|
|
1858
|
+
|--------------|----------|------------------------------------------|
|
|
1859
|
+
| `actionType` | `string` | `'Say'` to speak the phrase, or `'Play'` to play an audio file. The SWML `pay` verb accepts these two values. |
|
|
1860
|
+
| `phrase` | `string` | The text to say, or for `'Play'` the URL of the audio file. |
|
|
1861
|
+
|
|
1862
|
+
**Returns:** A `PaymentAction` object.
|
|
1863
|
+
|
|
1864
|
+
**Example:**
|
|
1865
|
+
|
|
1866
|
+
```typescript
|
|
1867
|
+
const action = FunctionResult.createPaymentAction(
|
|
1868
|
+
'Say',
|
|
1869
|
+
'Enter your credit card number, followed by the pound key.',
|
|
1870
|
+
);
|
|
1871
|
+
```
|
|
1872
|
+
|
|
1873
|
+
### createPaymentParameter (static)
|
|
1874
|
+
|
|
1875
|
+
Create a `PaymentParameter`, a name-value pair for the payment connector.
|
|
1876
|
+
|
|
1877
|
+
<!-- snippet: no-compile API signature reference, not runnable code -->
|
|
1878
|
+
```typescript
|
|
1879
|
+
static createPaymentParameter(name: string, value: string): PaymentParameter
|
|
1880
|
+
```
|
|
1881
|
+
|
|
1882
|
+
| Parameter | Type | Description |
|
|
1883
|
+
|-----------|----------|------------------------|
|
|
1884
|
+
| `name` | `string` | The parameter name. |
|
|
1885
|
+
| `value` | `string` | The parameter value. |
|
|
1886
|
+
|
|
1887
|
+
**Returns:** A `PaymentParameter` object.
|
|
1888
|
+
|
|
1889
|
+
**Example:**
|
|
1890
|
+
|
|
1891
|
+
```typescript
|
|
1892
|
+
const param = FunctionResult.createPaymentParameter('merchant_id', 'MERCH-001');
|
|
1893
|
+
```
|
|
1894
|
+
|
|
1895
|
+
### Full payment example
|
|
1896
|
+
|
|
1897
|
+
This example sets custom prompts for three payment steps and passes a merchant ID to the connector:
|
|
1898
|
+
|
|
1899
|
+
```typescript
|
|
1900
|
+
const prompts = [
|
|
1901
|
+
FunctionResult.createPaymentPrompt(
|
|
1902
|
+
'payment-card-number',
|
|
1903
|
+
[FunctionResult.createPaymentAction('Say', 'Enter your card number.')],
|
|
1904
|
+
),
|
|
1905
|
+
FunctionResult.createPaymentPrompt(
|
|
1906
|
+
'expiration-date',
|
|
1907
|
+
[FunctionResult.createPaymentAction('Say', 'Enter the expiration date.')],
|
|
1908
|
+
),
|
|
1909
|
+
FunctionResult.createPaymentPrompt(
|
|
1910
|
+
'security-code',
|
|
1911
|
+
[FunctionResult.createPaymentAction('Say', 'Enter the security code on the back of your card.')],
|
|
1912
|
+
),
|
|
1913
|
+
];
|
|
1914
|
+
|
|
1915
|
+
const params = [
|
|
1916
|
+
FunctionResult.createPaymentParameter('merchant_id', 'MERCH-001'),
|
|
1917
|
+
];
|
|
1918
|
+
|
|
1919
|
+
const result = new FunctionResult('Tell the caller you are starting the payment.', true)
|
|
1920
|
+
.pay({
|
|
1921
|
+
paymentConnectorUrl: 'https://payments.example.com/connector',
|
|
1922
|
+
chargeAmount: '99.95',
|
|
1923
|
+
currency: 'usd',
|
|
1924
|
+
maxAttempts: 3,
|
|
1925
|
+
timeout: 15,
|
|
1926
|
+
prompts,
|
|
1927
|
+
parameters: params,
|
|
1928
|
+
description: 'Annual subscription',
|
|
1929
|
+
});
|
|
1930
|
+
```
|
|
1931
|
+
|
|
1932
|
+
## Fluent Chaining
|
|
1933
|
+
|
|
1934
|
+
Every mutating method on `FunctionResult` returns `this`, so you can build a result with several actions in one expression. This tool completes an order, stores data, texts a confirmation and switches the available tools:
|
|
1935
|
+
|
|
1936
|
+
```typescript
|
|
1937
|
+
agent.defineTool({
|
|
1938
|
+
name: 'complete_order',
|
|
1939
|
+
description: 'Complete an order and send confirmation',
|
|
1940
|
+
parameters: {
|
|
1941
|
+
order_id: { type: 'string', description: 'The order ID' },
|
|
1942
|
+
},
|
|
1943
|
+
handler: (args) => {
|
|
1944
|
+
const orderId = args.order_id as string;
|
|
1945
|
+
|
|
1946
|
+
return new FunctionResult(`Order ${orderId} is complete.`)
|
|
1947
|
+
.setPostProcess(true)
|
|
1948
|
+
// Store data for other tools
|
|
1949
|
+
.updateGlobalData({ last_order: orderId, order_status: 'complete' })
|
|
1950
|
+
// Set metadata for this function
|
|
1951
|
+
.setMetadata({ order_id: orderId })
|
|
1952
|
+
// Send an SMS confirmation
|
|
1953
|
+
.sendSms({
|
|
1954
|
+
toNumber: '+15551234567',
|
|
1955
|
+
fromNumber: '+15559876543',
|
|
1956
|
+
body: `Your order ${orderId} has been confirmed.`,
|
|
1957
|
+
})
|
|
1958
|
+
// Speak a confirmation
|
|
1959
|
+
.say(`Your order ${orderId} is confirmed.`)
|
|
1960
|
+
// Send an event to the connected client
|
|
1961
|
+
.swmlUserEvent({ type: 'order_complete', order_id: orderId })
|
|
1962
|
+
// Disable the order tool, enable the feedback tool
|
|
1963
|
+
.toggleFunctions([
|
|
1964
|
+
{ function: 'complete_order', active: false },
|
|
1965
|
+
{ function: 'submit_feedback', active: true },
|
|
1966
|
+
]);
|
|
1967
|
+
},
|
|
1968
|
+
});
|
|
1969
|
+
```
|
|
1970
|
+
|
|
1971
|
+
For `order_id` `ORD-789`, the handler returns this result. The `action` array keeps the order of the calls:
|
|
1972
|
+
|
|
1973
|
+
```json
|
|
1974
|
+
{
|
|
1975
|
+
"response": "Order ORD-789 is complete.",
|
|
1976
|
+
"action": [
|
|
1977
|
+
{ "set_global_data": { "last_order": "ORD-789", "order_status": "complete" } },
|
|
1978
|
+
{ "set_meta_data": { "order_id": "ORD-789" } },
|
|
1979
|
+
{ "SWML": { "version": "1.0.0", "sections": { "main": [{ "send_sms": { "to_number": "+15551234567", "from_number": "+15559876543", "body": "Your order ORD-789 has been confirmed." } }] } } },
|
|
1980
|
+
{ "say": "Your order ORD-789 is confirmed." },
|
|
1981
|
+
{ "SWML": { "sections": { "main": [{ "user_event": { "event": { "type": "order_complete", "order_id": "ORD-789" } } }] }, "version": "1.0.0" } },
|
|
1982
|
+
{ "toggle_functions": [{ "function": "complete_order", "active": false }, { "function": "submit_feedback", "active": true }] }
|
|
1983
|
+
],
|
|
1984
|
+
"post_process": true
|
|
1985
|
+
}
|
|
1986
|
+
```
|