@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.
Files changed (659) hide show
  1. package/CHANGELOG.md +821 -0
  2. package/LICENSE +21 -0
  3. package/README.md +163 -68
  4. package/dist/AGENTS.md +13 -0
  5. package/dist/AgentBase.d.ts +510 -126
  6. package/dist/AgentBase.js +1581 -455
  7. package/dist/AgentBase.js.map +1 -1
  8. package/dist/AgentServer.d.ts +21 -0
  9. package/dist/AgentServer.js +154 -47
  10. package/dist/AgentServer.js.map +1 -1
  11. package/dist/AuthHandler.d.ts +14 -2
  12. package/dist/AuthHandler.js +7 -2
  13. package/dist/AuthHandler.js.map +1 -1
  14. package/dist/ConfigLoader.d.ts +5 -13
  15. package/dist/ConfigLoader.js +15 -29
  16. package/dist/ConfigLoader.js.map +1 -1
  17. package/dist/ContextBuilder.d.ts +202 -9
  18. package/dist/ContextBuilder.js +219 -36
  19. package/dist/ContextBuilder.js.map +1 -1
  20. package/dist/DataMap.d.ts +186 -45
  21. package/dist/DataMap.js +210 -52
  22. package/dist/DataMap.js.map +1 -1
  23. package/dist/FunctionResult.d.ts +309 -83
  24. package/dist/FunctionResult.js +483 -116
  25. package/dist/FunctionResult.js.map +1 -1
  26. package/dist/Logger.d.ts +30 -5
  27. package/dist/Logger.js +77 -19
  28. package/dist/Logger.js.map +1 -1
  29. package/dist/POM/PromptObjectModel.d.ts +12 -1
  30. package/dist/POM/PromptObjectModel.js +25 -9
  31. package/dist/POM/PromptObjectModel.js.map +1 -1
  32. package/dist/ParameterSchema.d.ts +306 -0
  33. package/dist/ParameterSchema.js +251 -0
  34. package/dist/ParameterSchema.js.map +1 -0
  35. package/dist/PlatformContracts.d.ts +21 -0
  36. package/dist/PlatformContracts.generated.d.ts +109 -0
  37. package/dist/PlatformContracts.generated.js +8 -0
  38. package/dist/PlatformContracts.generated.js.map +1 -0
  39. package/dist/PlatformContracts.js +2 -0
  40. package/dist/PlatformContracts.js.map +1 -0
  41. package/dist/PomBuilder.d.ts +18 -0
  42. package/dist/PomBuilder.js +53 -3
  43. package/dist/PomBuilder.js.map +1 -1
  44. package/dist/PostPrompt.d.ts +110 -0
  45. package/dist/PostPrompt.js +204 -0
  46. package/dist/PostPrompt.js.map +1 -0
  47. package/dist/PromptManager.d.ts +22 -1
  48. package/dist/PromptManager.js +28 -1
  49. package/dist/PromptManager.js.map +1 -1
  50. package/dist/PublicFetch.d.ts +132 -0
  51. package/dist/PublicFetch.js +311 -0
  52. package/dist/PublicFetch.js.map +1 -0
  53. package/dist/RobotsTxt.d.ts +41 -0
  54. package/dist/RobotsTxt.js +152 -0
  55. package/dist/RobotsTxt.js.map +1 -0
  56. package/dist/SWMLHandler.js.map +1 -1
  57. package/dist/SWMLService.d.ts +169 -59
  58. package/dist/SWMLService.js +456 -129
  59. package/dist/SWMLService.js.map +1 -1
  60. package/dist/SchemaUtils.d.ts +115 -2
  61. package/dist/SchemaUtils.js +444 -12
  62. package/dist/SchemaUtils.js.map +1 -1
  63. package/dist/SecurityUtils.d.ts +49 -9
  64. package/dist/SecurityUtils.js +153 -51
  65. package/dist/SecurityUtils.js.map +1 -1
  66. package/dist/SemanticGate.d.ts +183 -0
  67. package/dist/SemanticGate.js +533 -0
  68. package/dist/SemanticGate.js.map +1 -0
  69. package/dist/ServerlessAdapter.d.ts +156 -7
  70. package/dist/ServerlessAdapter.js +399 -42
  71. package/dist/ServerlessAdapter.js.map +1 -1
  72. package/dist/SessionManager.d.ts +11 -2
  73. package/dist/SessionManager.js +50 -18
  74. package/dist/SessionManager.js.map +1 -1
  75. package/dist/SslConfig.d.ts +2 -1
  76. package/dist/SslConfig.js +4 -1
  77. package/dist/SslConfig.js.map +1 -1
  78. package/dist/SwaigActions.generated.d.ts +23 -0
  79. package/dist/SwaigActions.generated.js +8 -0
  80. package/dist/SwaigActions.generated.js.map +1 -0
  81. package/dist/SwaigContracts.d.ts +15 -0
  82. package/dist/SwaigContracts.generated.d.ts +264 -0
  83. package/dist/SwaigContracts.generated.js +12 -0
  84. package/dist/SwaigContracts.generated.js.map +1 -0
  85. package/dist/SwaigContracts.js +2 -0
  86. package/dist/SwaigContracts.js.map +1 -0
  87. package/dist/SwaigFunction.d.ts +139 -7
  88. package/dist/SwaigFunction.js +170 -22
  89. package/dist/SwaigFunction.js.map +1 -1
  90. package/dist/SwmlBuilder.d.ts +68 -19
  91. package/dist/SwmlBuilder.js +74 -38
  92. package/dist/SwmlBuilder.js.map +1 -1
  93. package/dist/SwmlVerbMethods.generated.d.ts +41 -4
  94. package/dist/SwmlVerbMethods.generated.js +1 -1
  95. package/dist/TypeInference.d.ts +39 -3
  96. package/dist/TypeInference.js +256 -16
  97. package/dist/TypeInference.js.map +1 -1
  98. package/dist/WebService.d.ts +79 -11
  99. package/dist/WebService.js +320 -109
  100. package/dist/WebService.js.map +1 -1
  101. package/dist/WebhookMiddleware.d.ts +119 -0
  102. package/dist/WebhookMiddleware.js +271 -0
  103. package/dist/WebhookMiddleware.js.map +1 -0
  104. package/dist/WebhookValidator.d.ts +92 -0
  105. package/dist/WebhookValidator.js +409 -0
  106. package/dist/WebhookValidator.js.map +1 -0
  107. package/dist/agents/BedrockAgent.d.ts +162 -0
  108. package/dist/agents/BedrockAgent.js +323 -0
  109. package/dist/agents/BedrockAgent.js.map +1 -0
  110. package/dist/ai-chat/AIChatClient.d.ts +316 -0
  111. package/dist/ai-chat/AIChatClient.js +535 -0
  112. package/dist/ai-chat/AIChatClient.js.map +1 -0
  113. package/dist/ai-chat/ChatGateway.d.ts +408 -0
  114. package/dist/ai-chat/ChatGateway.js +747 -0
  115. package/dist/ai-chat/ChatGateway.js.map +1 -0
  116. package/dist/ai-chat/HandoffRouter.d.ts +282 -0
  117. package/dist/ai-chat/HandoffRouter.js +518 -0
  118. package/dist/ai-chat/HandoffRouter.js.map +1 -0
  119. package/dist/ai-chat/index.d.ts +12 -0
  120. package/dist/ai-chat/index.js +10 -0
  121. package/dist/ai-chat/index.js.map +1 -0
  122. package/dist/capabilities.d.ts +64 -0
  123. package/dist/capabilities.js +95 -0
  124. package/dist/capabilities.js.map +1 -0
  125. package/dist/cli/agent-loader.d.ts +32 -6
  126. package/dist/cli/agent-loader.js +92 -33
  127. package/dist/cli/agent-loader.js.map +1 -1
  128. package/dist/cli/datamap-exec.d.ts +175 -0
  129. package/dist/cli/datamap-exec.js +1284 -0
  130. package/dist/cli/datamap-exec.js.map +1 -0
  131. package/dist/cli/function-args.d.ts +40 -0
  132. package/dist/cli/function-args.js +146 -0
  133. package/dist/cli/function-args.js.map +1 -0
  134. package/dist/cli/simulation.d.ts +99 -0
  135. package/dist/cli/simulation.js +490 -0
  136. package/dist/cli/simulation.js.map +1 -0
  137. package/dist/cli/swaig-test.d.ts +12 -25
  138. package/dist/cli/swaig-test.js +935 -371
  139. package/dist/cli/swaig-test.js.map +1 -1
  140. package/dist/cli/tsdocs/agentsNote.d.ts +30 -0
  141. package/dist/cli/tsdocs/agentsNote.js +92 -0
  142. package/dist/cli/tsdocs/agentsNote.js.map +1 -0
  143. package/dist/cli/tsdocs/api-index.json +1 -0
  144. package/dist/cli/tsdocs/api.d.ts +91 -0
  145. package/dist/cli/tsdocs/api.js +372 -0
  146. package/dist/cli/tsdocs/api.js.map +1 -0
  147. package/dist/cli/tsdocs/apiTypes.d.ts +64 -0
  148. package/dist/cli/tsdocs/apiTypes.js +7 -0
  149. package/dist/cli/tsdocs/apiTypes.js.map +1 -0
  150. package/dist/cli/tsdocs/bin.d.ts +6 -0
  151. package/dist/cli/tsdocs/bin.js +23 -0
  152. package/dist/cli/tsdocs/bin.js.map +1 -0
  153. package/dist/cli/tsdocs/files.d.ts +108 -0
  154. package/dist/cli/tsdocs/files.js +287 -0
  155. package/dist/cli/tsdocs/files.js.map +1 -0
  156. package/dist/cli/tsdocs/index.d.ts +28 -0
  157. package/dist/cli/tsdocs/index.js +307 -0
  158. package/dist/cli/tsdocs/index.js.map +1 -0
  159. package/dist/cli/tsdocs/live.d.ts +41 -0
  160. package/dist/cli/tsdocs/live.js +202 -0
  161. package/dist/cli/tsdocs/live.js.map +1 -0
  162. package/dist/cli/tsdocs/locate.d.ts +51 -0
  163. package/dist/cli/tsdocs/locate.js +75 -0
  164. package/dist/cli/tsdocs/locate.js.map +1 -0
  165. package/dist/cli/tsdocs/render.d.ts +75 -0
  166. package/dist/cli/tsdocs/render.js +323 -0
  167. package/dist/cli/tsdocs/render.js.map +1 -0
  168. package/dist/cli/tsdocs/topics.d.ts +43 -0
  169. package/dist/cli/tsdocs/topics.js +920 -0
  170. package/dist/cli/tsdocs/topics.js.map +1 -0
  171. package/dist/index.d.ts +49 -68
  172. package/dist/index.js +45 -73
  173. package/dist/index.js.map +1 -1
  174. package/dist/livewire/index.d.ts +229 -155
  175. package/dist/livewire/index.js +298 -195
  176. package/dist/livewire/index.js.map +1 -1
  177. package/dist/llms.txt +65 -0
  178. package/dist/prefabs/CallSessionStore.d.ts +52 -0
  179. package/dist/prefabs/CallSessionStore.js +72 -0
  180. package/dist/prefabs/CallSessionStore.js.map +1 -0
  181. package/dist/prefabs/ConciergeAgent.d.ts +13 -1
  182. package/dist/prefabs/ConciergeAgent.js +36 -31
  183. package/dist/prefabs/ConciergeAgent.js.map +1 -1
  184. package/dist/prefabs/FAQBotAgent.d.ts +9 -1
  185. package/dist/prefabs/FAQBotAgent.js +113 -47
  186. package/dist/prefabs/FAQBotAgent.js.map +1 -1
  187. package/dist/prefabs/InfoGathererAgent.d.ts +22 -3
  188. package/dist/prefabs/InfoGathererAgent.js +67 -58
  189. package/dist/prefabs/InfoGathererAgent.js.map +1 -1
  190. package/dist/prefabs/ReceptionistAgent.d.ts +16 -5
  191. package/dist/prefabs/ReceptionistAgent.js +39 -31
  192. package/dist/prefabs/ReceptionistAgent.js.map +1 -1
  193. package/dist/prefabs/SurveyAgent.d.ts +22 -4
  194. package/dist/prefabs/SurveyAgent.js +84 -68
  195. package/dist/prefabs/SurveyAgent.js.map +1 -1
  196. package/dist/relay/Action.d.ts +44 -21
  197. package/dist/relay/Action.js +75 -17
  198. package/dist/relay/Action.js.map +1 -1
  199. package/dist/relay/Call.d.ts +312 -47
  200. package/dist/relay/Call.js +369 -18
  201. package/dist/relay/Call.js.map +1 -1
  202. package/dist/relay/Deferred.js.map +1 -1
  203. package/dist/relay/Message.d.ts +26 -5
  204. package/dist/relay/Message.js +36 -6
  205. package/dist/relay/Message.js.map +1 -1
  206. package/dist/relay/RelayClient.d.ts +44 -17
  207. package/dist/relay/RelayClient.js +175 -65
  208. package/dist/relay/RelayClient.js.map +1 -1
  209. package/dist/relay/RelayError.d.ts +14 -0
  210. package/dist/relay/RelayError.js +15 -0
  211. package/dist/relay/RelayError.js.map +1 -1
  212. package/dist/relay/RelayEvent.d.ts +96 -65
  213. package/dist/relay/RelayEvent.js +85 -56
  214. package/dist/relay/RelayEvent.js.map +1 -1
  215. package/dist/relay/closedSets.d.ts +111 -0
  216. package/dist/relay/closedSets.js +83 -0
  217. package/dist/relay/closedSets.js.map +1 -0
  218. package/dist/relay/index.d.ts +3 -1
  219. package/dist/relay/index.js +1 -0
  220. package/dist/relay/index.js.map +1 -1
  221. package/dist/relay/normalize.js.map +1 -1
  222. package/dist/relay/protocol.types.generated.d.ts +1195 -0
  223. package/dist/relay/protocol.types.generated.js +8 -0
  224. package/dist/relay/protocol.types.generated.js.map +1 -0
  225. package/dist/relay/types.d.ts +73 -42
  226. package/dist/rest/HttpClient.d.ts +36 -8
  227. package/dist/rest/HttpClient.js +233 -40
  228. package/dist/rest/HttpClient.js.map +1 -1
  229. package/dist/rest/RequestOptions.d.ts +110 -0
  230. package/dist/rest/RequestOptions.js +113 -0
  231. package/dist/rest/RequestOptions.js.map +1 -0
  232. package/dist/rest/RestError.d.ts +52 -6
  233. package/dist/rest/RestError.js +89 -5
  234. package/dist/rest/RestError.js.map +1 -1
  235. package/dist/rest/base/CrudResource.d.ts +16 -26
  236. package/dist/rest/base/CrudResource.js +19 -33
  237. package/dist/rest/base/CrudResource.js.map +1 -1
  238. package/dist/rest/base/CrudWithAddresses.d.ts +3 -2
  239. package/dist/rest/base/CrudWithAddresses.js +2 -2
  240. package/dist/rest/base/CrudWithAddresses.js.map +1 -1
  241. package/dist/rest/base/FabricResource.d.ts +15 -0
  242. package/dist/rest/base/FabricResource.js +16 -0
  243. package/dist/rest/base/FabricResource.js.map +1 -0
  244. package/dist/rest/base/ReadResource.d.ts +62 -0
  245. package/dist/rest/base/ReadResource.js +69 -0
  246. package/dist/rest/base/ReadResource.js.map +1 -0
  247. package/dist/rest/callHandler.d.ts +5 -2
  248. package/dist/rest/callHandler.js +4 -1
  249. package/dist/rest/callHandler.js.map +1 -1
  250. package/dist/rest/index.d.ts +18 -77
  251. package/dist/rest/index.js +47 -120
  252. package/dist/rest/index.js.map +1 -1
  253. package/dist/rest/namespaces/_client_tree_generated.d.ts +103 -0
  254. package/dist/rest/namespaces/_client_tree_generated.js +171 -0
  255. package/dist/rest/namespaces/_client_tree_generated.js.map +1 -0
  256. package/dist/rest/namespaces/addresses.d.ts +3 -42
  257. package/dist/rest/namespaces/addresses.js +3 -50
  258. package/dist/rest/namespaces/addresses.js.map +1 -1
  259. package/dist/rest/namespaces/calling.d.ts +6 -378
  260. package/dist/rest/namespaces/calling.js +6 -473
  261. package/dist/rest/namespaces/calling.js.map +1 -1
  262. package/dist/rest/namespaces/calling.resources.generated.d.ts +165 -0
  263. package/dist/rest/namespaces/calling.resources.generated.js +477 -0
  264. package/dist/rest/namespaces/calling.resources.generated.js.map +1 -0
  265. package/dist/rest/namespaces/calling.types.generated.d.ts +2917 -0
  266. package/dist/rest/namespaces/calling.types.generated.js +8 -0
  267. package/dist/rest/namespaces/calling.types.generated.js.map +1 -0
  268. package/dist/rest/namespaces/chat.d.ts +4 -18
  269. package/dist/rest/namespaces/chat.js +4 -21
  270. package/dist/rest/namespaces/chat.js.map +1 -1
  271. package/dist/rest/namespaces/chat.resources.generated.d.ts +12 -0
  272. package/dist/rest/namespaces/chat.resources.generated.js +29 -0
  273. package/dist/rest/namespaces/chat.resources.generated.js.map +1 -0
  274. package/dist/rest/namespaces/chat.types.generated.d.ts +56 -0
  275. package/dist/rest/namespaces/chat.types.generated.js +8 -0
  276. package/dist/rest/namespaces/chat.types.generated.js.map +1 -0
  277. package/dist/rest/namespaces/datasphere.d.ts +6 -62
  278. package/dist/rest/namespaces/datasphere.js +6 -72
  279. package/dist/rest/namespaces/datasphere.js.map +1 -1
  280. package/dist/rest/namespaces/datasphere.resources.generated.d.ts +25 -0
  281. package/dist/rest/namespaces/datasphere.resources.generated.js +50 -0
  282. package/dist/rest/namespaces/datasphere.resources.generated.js.map +1 -0
  283. package/dist/rest/namespaces/datasphere.types.generated.d.ts +180 -0
  284. package/dist/rest/namespaces/datasphere.types.generated.js +8 -0
  285. package/dist/rest/namespaces/datasphere.types.generated.js.map +1 -0
  286. package/dist/rest/namespaces/fabric.d.ts +11 -327
  287. package/dist/rest/namespaces/fabric.js +14 -439
  288. package/dist/rest/namespaces/fabric.js.map +1 -1
  289. package/dist/rest/namespaces/fabric.resources.generated.d.ts +195 -0
  290. package/dist/rest/namespaces/fabric.resources.generated.js +399 -0
  291. package/dist/rest/namespaces/fabric.resources.generated.js.map +1 -0
  292. package/dist/rest/namespaces/fabric.types.generated.d.ts +4557 -0
  293. package/dist/rest/namespaces/fabric.types.generated.js +8 -0
  294. package/dist/rest/namespaces/fabric.types.generated.js.map +1 -0
  295. package/dist/rest/namespaces/fax.resources.generated.d.ts +6 -0
  296. package/dist/rest/namespaces/fax.resources.generated.js +14 -0
  297. package/dist/rest/namespaces/fax.resources.generated.js.map +1 -0
  298. package/dist/rest/namespaces/fax.types.generated.d.ts +131 -0
  299. package/dist/rest/namespaces/fax.types.generated.js +8 -0
  300. package/dist/rest/namespaces/fax.types.generated.js.map +1 -0
  301. package/dist/rest/namespaces/imported-numbers.d.ts +3 -18
  302. package/dist/rest/namespaces/imported-numbers.js +3 -21
  303. package/dist/rest/namespaces/imported-numbers.js.map +1 -1
  304. package/dist/rest/namespaces/logs.d.ts +10 -101
  305. package/dist/rest/namespaces/logs.js +10 -128
  306. package/dist/rest/namespaces/logs.js.map +1 -1
  307. package/dist/rest/namespaces/logs.resources.generated.d.ts +9 -0
  308. package/dist/rest/namespaces/logs.resources.generated.js +17 -0
  309. package/dist/rest/namespaces/logs.resources.generated.js.map +1 -0
  310. package/dist/rest/namespaces/logs.types.generated.d.ts +131 -0
  311. package/dist/rest/namespaces/logs.types.generated.js +8 -0
  312. package/dist/rest/namespaces/logs.types.generated.js.map +1 -0
  313. package/dist/rest/namespaces/lookup.d.ts +3 -25
  314. package/dist/rest/namespaces/lookup.js +3 -27
  315. package/dist/rest/namespaces/lookup.js.map +1 -1
  316. package/dist/rest/namespaces/message.resources.generated.d.ts +6 -0
  317. package/dist/rest/namespaces/message.resources.generated.js +14 -0
  318. package/dist/rest/namespaces/message.resources.generated.js.map +1 -0
  319. package/dist/rest/namespaces/message.types.generated.d.ts +122 -0
  320. package/dist/rest/namespaces/message.types.generated.js +8 -0
  321. package/dist/rest/namespaces/message.types.generated.js.map +1 -0
  322. package/dist/rest/namespaces/messages.resources.generated.d.ts +18 -0
  323. package/dist/rest/namespaces/messages.resources.generated.js +44 -0
  324. package/dist/rest/namespaces/messages.resources.generated.js.map +1 -0
  325. package/dist/rest/namespaces/messages.types.generated.d.ts +99 -0
  326. package/dist/rest/namespaces/messages.types.generated.js +8 -0
  327. package/dist/rest/namespaces/messages.types.generated.js.map +1 -0
  328. package/dist/rest/namespaces/mfa.d.ts +3 -42
  329. package/dist/rest/namespaces/mfa.js +3 -49
  330. package/dist/rest/namespaces/mfa.js.map +1 -1
  331. package/dist/rest/namespaces/number-groups.d.ts +3 -45
  332. package/dist/rest/namespaces/number-groups.js +3 -53
  333. package/dist/rest/namespaces/number-groups.js.map +1 -1
  334. package/dist/rest/namespaces/phone-numbers.d.ts +8 -196
  335. package/dist/rest/namespaces/phone-numbers.js +8 -230
  336. package/dist/rest/namespaces/phone-numbers.js.map +1 -1
  337. package/dist/rest/namespaces/project.d.ts +6 -42
  338. package/dist/rest/namespaces/project.js +6 -51
  339. package/dist/rest/namespaces/project.js.map +1 -1
  340. package/dist/rest/namespaces/project.resources.generated.d.ts +17 -0
  341. package/dist/rest/namespaces/project.resources.generated.js +44 -0
  342. package/dist/rest/namespaces/project.resources.generated.js.map +1 -0
  343. package/dist/rest/namespaces/project.types.generated.d.ts +58 -0
  344. package/dist/rest/namespaces/project.types.generated.js +8 -0
  345. package/dist/rest/namespaces/project.types.generated.js.map +1 -0
  346. package/dist/rest/namespaces/projects.resources.generated.d.ts +12 -0
  347. package/dist/rest/namespaces/projects.resources.generated.js +25 -0
  348. package/dist/rest/namespaces/projects.resources.generated.js.map +1 -0
  349. package/dist/rest/namespaces/projects.types.generated.d.ts +77 -0
  350. package/dist/rest/namespaces/projects.types.generated.js +8 -0
  351. package/dist/rest/namespaces/projects.types.generated.js.map +1 -0
  352. package/dist/rest/namespaces/pubsub.d.ts +4 -18
  353. package/dist/rest/namespaces/pubsub.js +4 -21
  354. package/dist/rest/namespaces/pubsub.js.map +1 -1
  355. package/dist/rest/namespaces/pubsub.resources.generated.d.ts +12 -0
  356. package/dist/rest/namespaces/pubsub.resources.generated.js +29 -0
  357. package/dist/rest/namespaces/pubsub.resources.generated.js.map +1 -0
  358. package/dist/rest/namespaces/pubsub.types.generated.d.ts +60 -0
  359. package/dist/rest/namespaces/pubsub.types.generated.js +8 -0
  360. package/dist/rest/namespaces/pubsub.types.generated.js.map +1 -0
  361. package/dist/rest/namespaces/queues.d.ts +3 -38
  362. package/dist/rest/namespaces/queues.js +3 -44
  363. package/dist/rest/namespaces/queues.js.map +1 -1
  364. package/dist/rest/namespaces/recordings.d.ts +3 -34
  365. package/dist/rest/namespaces/recordings.js +3 -40
  366. package/dist/rest/namespaces/recordings.js.map +1 -1
  367. package/dist/rest/namespaces/registry.d.ts +6 -137
  368. package/dist/rest/namespaces/registry.js +6 -173
  369. package/dist/rest/namespaces/registry.js.map +1 -1
  370. package/dist/rest/namespaces/relay-rest.resources.generated.d.ts +168 -0
  371. package/dist/rest/namespaces/relay-rest.resources.generated.js +430 -0
  372. package/dist/rest/namespaces/relay-rest.resources.generated.js.map +1 -0
  373. package/dist/rest/namespaces/relay-rest.types.generated.d.ts +1906 -0
  374. package/dist/rest/namespaces/relay-rest.types.generated.js +8 -0
  375. package/dist/rest/namespaces/relay-rest.types.generated.js.map +1 -0
  376. package/dist/rest/namespaces/short-codes.d.ts +3 -35
  377. package/dist/rest/namespaces/short-codes.js +3 -41
  378. package/dist/rest/namespaces/short-codes.js.map +1 -1
  379. package/dist/rest/namespaces/sip-profile.d.ts +3 -24
  380. package/dist/rest/namespaces/sip-profile.js +3 -29
  381. package/dist/rest/namespaces/sip-profile.js.map +1 -1
  382. package/dist/rest/namespaces/verified-callers.d.ts +3 -29
  383. package/dist/rest/namespaces/verified-callers.js +3 -34
  384. package/dist/rest/namespaces/verified-callers.js.map +1 -1
  385. package/dist/rest/namespaces/video.d.ts +10 -227
  386. package/dist/rest/namespaces/video.js +10 -288
  387. package/dist/rest/namespaces/video.js.map +1 -1
  388. package/dist/rest/namespaces/video.resources.generated.d.ts +81 -0
  389. package/dist/rest/namespaces/video.resources.generated.js +171 -0
  390. package/dist/rest/namespaces/video.resources.generated.js.map +1 -0
  391. package/dist/rest/namespaces/video.types.generated.d.ts +771 -0
  392. package/dist/rest/namespaces/video.types.generated.js +8 -0
  393. package/dist/rest/namespaces/video.types.generated.js.map +1 -0
  394. package/dist/rest/namespaces/voice.resources.generated.d.ts +9 -0
  395. package/dist/rest/namespaces/voice.resources.generated.js +17 -0
  396. package/dist/rest/namespaces/voice.resources.generated.js.map +1 -0
  397. package/dist/rest/namespaces/voice.types.generated.d.ts +214 -0
  398. package/dist/rest/namespaces/voice.types.generated.js +8 -0
  399. package/dist/rest/namespaces/voice.types.generated.js.map +1 -0
  400. package/dist/rest/pagination.d.ts +5 -1
  401. package/dist/rest/pagination.js +40 -20
  402. package/dist/rest/pagination.js.map +1 -1
  403. package/dist/rest/types.d.ts +21 -3
  404. package/dist/schema.json +299 -98
  405. package/dist/skills/SkillBase.d.ts +111 -21
  406. package/dist/skills/SkillBase.js +100 -17
  407. package/dist/skills/SkillBase.js.map +1 -1
  408. package/dist/skills/SkillManager.d.ts +66 -13
  409. package/dist/skills/SkillManager.js +101 -20
  410. package/dist/skills/SkillManager.js.map +1 -1
  411. package/dist/skills/SkillName.d.ts +44 -0
  412. package/dist/skills/SkillName.js +2 -0
  413. package/dist/skills/SkillName.js.map +1 -0
  414. package/dist/skills/SkillRegistry.d.ts +22 -11
  415. package/dist/skills/SkillRegistry.js +47 -17
  416. package/dist/skills/SkillRegistry.js.map +1 -1
  417. package/dist/skills/builtin/api_ninjas_trivia.d.ts +3 -1
  418. package/dist/skills/builtin/api_ninjas_trivia.js +18 -6
  419. package/dist/skills/builtin/api_ninjas_trivia.js.map +1 -1
  420. package/dist/skills/builtin/ask_claude.d.ts +14 -4
  421. package/dist/skills/builtin/ask_claude.js +36 -14
  422. package/dist/skills/builtin/ask_claude.js.map +1 -1
  423. package/dist/skills/builtin/claude_skills.d.ts +3 -1
  424. package/dist/skills/builtin/claude_skills.js +19 -15
  425. package/dist/skills/builtin/claude_skills.js.map +1 -1
  426. package/dist/skills/builtin/custom_skills.d.ts +10 -3
  427. package/dist/skills/builtin/custom_skills.js +26 -9
  428. package/dist/skills/builtin/custom_skills.js.map +1 -1
  429. package/dist/skills/builtin/datasphere.d.ts +5 -3
  430. package/dist/skills/builtin/datasphere.js +21 -22
  431. package/dist/skills/builtin/datasphere.js.map +1 -1
  432. package/dist/skills/builtin/datasphere_serverless.d.ts +12 -1
  433. package/dist/skills/builtin/datasphere_serverless.js +17 -6
  434. package/dist/skills/builtin/datasphere_serverless.js.map +1 -1
  435. package/dist/skills/builtin/datetime.d.ts +3 -1
  436. package/dist/skills/builtin/datetime.js +11 -7
  437. package/dist/skills/builtin/datetime.js.map +1 -1
  438. package/dist/skills/builtin/google_maps.d.ts +29 -14
  439. package/dist/skills/builtin/google_maps.js +89 -269
  440. package/dist/skills/builtin/google_maps.js.map +1 -1
  441. package/dist/skills/builtin/index.d.ts +8 -6
  442. package/dist/skills/builtin/index.js +8 -6
  443. package/dist/skills/builtin/index.js.map +1 -1
  444. package/dist/skills/builtin/info_gatherer.d.ts +4 -2
  445. package/dist/skills/builtin/info_gatherer.js +20 -12
  446. package/dist/skills/builtin/info_gatherer.js.map +1 -1
  447. package/dist/skills/builtin/joke.d.ts +16 -6
  448. package/dist/skills/builtin/joke.js +54 -37
  449. package/dist/skills/builtin/joke.js.map +1 -1
  450. package/dist/skills/builtin/math.d.ts +3 -1
  451. package/dist/skills/builtin/math.js +14 -9
  452. package/dist/skills/builtin/math.js.map +1 -1
  453. package/dist/skills/builtin/mcp_gateway.d.ts +34 -5
  454. package/dist/skills/builtin/mcp_gateway.js +77 -46
  455. package/dist/skills/builtin/mcp_gateway.js.map +1 -1
  456. package/dist/skills/builtin/native_vector_search.d.ts +19 -5
  457. package/dist/skills/builtin/native_vector_search.js +179 -61
  458. package/dist/skills/builtin/native_vector_search.js.map +1 -1
  459. package/dist/skills/builtin/play_background_file.d.ts +21 -15
  460. package/dist/skills/builtin/play_background_file.js +43 -122
  461. package/dist/skills/builtin/play_background_file.js.map +1 -1
  462. package/dist/skills/builtin/spider.d.ts +42 -4
  463. package/dist/skills/builtin/spider.js +277 -104
  464. package/dist/skills/builtin/spider.js.map +1 -1
  465. package/dist/skills/builtin/swml_transfer.d.ts +14 -3
  466. package/dist/skills/builtin/swml_transfer.js +45 -24
  467. package/dist/skills/builtin/swml_transfer.js.map +1 -1
  468. package/dist/skills/builtin/weather_api.d.ts +24 -13
  469. package/dist/skills/builtin/weather_api.js +38 -30
  470. package/dist/skills/builtin/weather_api.js.map +1 -1
  471. package/dist/skills/builtin/web_search.d.ts +48 -10
  472. package/dist/skills/builtin/web_search.js +294 -100
  473. package/dist/skills/builtin/web_search.js.map +1 -1
  474. package/dist/skills/builtin/wikipedia_search.d.ts +4 -2
  475. package/dist/skills/builtin/wikipedia_search.js +14 -13
  476. package/dist/skills/builtin/wikipedia_search.js.map +1 -1
  477. package/dist/skills/index.d.ts +3 -2
  478. package/dist/skills/index.js +1 -1
  479. package/dist/skills/index.js.map +1 -1
  480. package/dist/swml_verbs_generated.d.ts +2824 -0
  481. package/dist/swml_verbs_generated.js +12 -0
  482. package/dist/swml_verbs_generated.js.map +1 -0
  483. package/dist/types.d.ts +59 -6
  484. package/dist/web.d.ts +27 -0
  485. package/dist/web.js +20 -0
  486. package/dist/web.js.map +1 -0
  487. package/docs/agent-guide.md +1034 -0
  488. package/docs/ai_chat.md +560 -0
  489. package/docs/api-reference.md +3641 -0
  490. package/docs/architecture.md +846 -0
  491. package/docs/bedrock_agent.md +411 -0
  492. package/docs/cli-guide.md +403 -0
  493. package/docs/cloud_functions_guide.md +399 -0
  494. package/docs/configuration.md +548 -0
  495. package/docs/contexts-guide.md +884 -0
  496. package/docs/datamap-guide.md +1207 -0
  497. package/docs/developer_pain_points.md +548 -0
  498. package/docs/llm_parameters.md +298 -0
  499. package/docs/mcp_gateway_reference.md +354 -0
  500. package/docs/mcp_integration.md +162 -0
  501. package/docs/pgi_agent_guide.md +1820 -0
  502. package/docs/prefabs-guide.md +815 -0
  503. package/docs/programmatically_governed_inference.md +301 -0
  504. package/docs/sdk_features.md +501 -0
  505. package/docs/security.md +559 -0
  506. package/docs/serverless-guide.md +520 -0
  507. package/docs/skills-guide.md +1223 -0
  508. package/docs/skills-system.md +405 -0
  509. package/docs/skills_parameter_schema.md +417 -0
  510. package/docs/swaig-reference.md +1986 -0
  511. package/docs/swml_service_guide.md +573 -0
  512. package/docs/third_party_skills.md +410 -0
  513. package/docs/web_service.md +666 -0
  514. package/examples/README.md +202 -0
  515. package/examples/advanced-datamap.ts +108 -0
  516. package/examples/advanced-dynamic-config.ts +70 -0
  517. package/examples/auto-vivified.ts +95 -0
  518. package/examples/call-flow.ts +65 -0
  519. package/examples/comprehensive-dynamic.ts +125 -0
  520. package/examples/contexts-steps.ts +65 -0
  521. package/examples/custom-path.ts +45 -0
  522. package/examples/datamap-tools.ts +51 -0
  523. package/examples/datasphere-multi-instance.ts +66 -0
  524. package/examples/datasphere-serverless-env.ts +87 -0
  525. package/examples/datasphere-webhook-env.ts +65 -0
  526. package/examples/datasphere.ts +56 -0
  527. package/examples/declarative.ts +100 -0
  528. package/examples/dynamic-config.ts +54 -0
  529. package/examples/dynamic-info-gatherer.ts +69 -0
  530. package/examples/dynamic-swml-service.ts +67 -0
  531. package/examples/gather-info.ts +95 -0
  532. package/examples/gather-per-question-functions-demo.ts +139 -0
  533. package/examples/joke-agent.ts +34 -0
  534. package/examples/kubernetes-agent.ts +45 -0
  535. package/examples/llm-params.ts +75 -0
  536. package/examples/mcp-agent.ts +89 -0
  537. package/examples/mcp-gateway.ts +81 -0
  538. package/examples/multi-agent.ts +80 -0
  539. package/examples/multi-endpoint.ts +79 -0
  540. package/examples/pgi/case-domain.ts +114 -0
  541. package/examples/pgi/serve.ts +16 -0
  542. package/examples/pgi/support-agent.ts +265 -0
  543. package/examples/pom-prompt.ts +70 -0
  544. package/examples/prefab-concierge.ts +42 -0
  545. package/examples/prefab-faq.ts +58 -0
  546. package/examples/prefab-info-gatherer.ts +33 -0
  547. package/examples/prefab-receptionist.ts +36 -0
  548. package/examples/prefab-survey.ts +69 -0
  549. package/examples/quickstart-agent.ts +29 -0
  550. package/examples/quickstart-relay.ts +25 -0
  551. package/examples/quickstart-rest.ts +25 -0
  552. package/examples/record-call.ts +65 -0
  553. package/examples/relay-demo.ts +33 -0
  554. package/examples/room-and-sip.ts +93 -0
  555. package/examples/serverless-lambda.ts +43 -0
  556. package/examples/session-state.ts +83 -0
  557. package/examples/simple-agent.ts +36 -0
  558. package/examples/simple-static.ts +29 -0
  559. package/examples/skills-demo.ts +41 -0
  560. package/examples/step-function-inheritance-demo.ts +124 -0
  561. package/examples/swaig-features.ts +193 -0
  562. package/examples/swml-service-routing.ts +66 -0
  563. package/examples/swml-service.ts +38 -0
  564. package/examples/swmlservice_ai_sidecar.ts +104 -0
  565. package/examples/swmlservice_swaig_standalone.ts +79 -0
  566. package/examples/tap.ts +67 -0
  567. package/examples/typed-tools.ts +68 -0
  568. package/examples/verb-methods.ts +45 -0
  569. package/examples/web-search-multi-instance.ts +75 -0
  570. package/examples/web-search.ts +38 -0
  571. package/examples/wikipedia.ts +36 -0
  572. package/livewire/README.md +164 -0
  573. package/livewire/docs/migration-guide.md +251 -0
  574. package/livewire/examples/livewire-basic-agent.ts +74 -0
  575. package/livewire/examples/livewire-handoff.ts +196 -0
  576. package/livewire/examples/livewire-multi-tool.ts +121 -0
  577. package/package.json +85 -13
  578. package/relay/README.md +101 -0
  579. package/relay/docs/call-methods.md +622 -0
  580. package/relay/docs/client-reference.md +281 -0
  581. package/relay/docs/events.md +193 -0
  582. package/relay/docs/getting-started.md +221 -0
  583. package/relay/docs/guide.md +386 -0
  584. package/relay/docs/messaging.md +246 -0
  585. package/relay/examples/relay-inbound.ts +66 -0
  586. package/relay/examples/relay-messaging.ts +74 -0
  587. package/relay/examples/relay-outbound.ts +76 -0
  588. package/rest/README.md +141 -0
  589. package/rest/docs/calling.md +313 -0
  590. package/rest/docs/client-reference.md +149 -0
  591. package/rest/docs/fabric.md +192 -0
  592. package/rest/docs/getting-started.md +138 -0
  593. package/rest/docs/guide.md +421 -0
  594. package/rest/docs/namespaces.md +367 -0
  595. package/rest/docs/phone-binding.md +116 -0
  596. package/rest/examples/rest-10dlc-registration.ts +177 -0
  597. package/rest/examples/rest-bind-phone-to-swml-webhook.ts +66 -0
  598. package/rest/examples/rest-calling-ivr-and-ai.ts +136 -0
  599. package/rest/examples/rest-calling-play-and-record.ts +98 -0
  600. package/rest/examples/rest-client.ts +59 -0
  601. package/rest/examples/rest-datasphere-search.ts +81 -0
  602. package/rest/examples/rest-fabric-conferences-and-routing.ts +147 -0
  603. package/rest/examples/rest-fabric-subscribers-and-sip.ts +106 -0
  604. package/rest/examples/rest-fabric-swml-and-callflows.ts +101 -0
  605. package/rest/examples/rest-manage-resources.ts +64 -0
  606. package/rest/examples/rest-phone-number-management.ts +200 -0
  607. package/rest/examples/rest-queues-mfa-and-recordings.ts +143 -0
  608. package/rest/examples/rest-video-rooms.ts +186 -0
  609. package/tutorial/fred/fred.ts +218 -0
  610. package/tutorial/fred/tutorial/01-introduction.md +141 -0
  611. package/tutorial/fred/tutorial/02-setup.md +304 -0
  612. package/tutorial/fred/tutorial/03-basic-agent.md +284 -0
  613. package/tutorial/fred/tutorial/04-wikipedia-skill.md +298 -0
  614. package/tutorial/fred/tutorial/05-custom-functions.md +347 -0
  615. package/tutorial/fred/tutorial/06-running-testing.md +642 -0
  616. package/tutorial/fred/tutorial/README.md +56 -0
  617. package/tutorial/fred/tutorial/appendix-complete-code.md +632 -0
  618. package/tutorial/fred/tutorial/appendix-docker-deployment.md +504 -0
  619. package/tutorial/full-guardrails-agent/handlers.ts +436 -0
  620. package/tutorial/full-guardrails-agent/penny.ts +305 -0
  621. package/tutorial/full-guardrails-agent/reservations.ts +1109 -0
  622. package/tutorial/full-guardrails-agent/tutorial/01-why-guardrails.md +149 -0
  623. package/tutorial/full-guardrails-agent/tutorial/02-design-first.md +139 -0
  624. package/tutorial/full-guardrails-agent/tutorial/03-rules-first.md +422 -0
  625. package/tutorial/full-guardrails-agent/tutorial/04-the-shell.md +238 -0
  626. package/tutorial/full-guardrails-agent/tutorial/05-steps-and-scoping.md +247 -0
  627. package/tutorial/full-guardrails-agent/tutorial/06-tools-that-decide.md +467 -0
  628. package/tutorial/full-guardrails-agent/tutorial/07-gather-and-projection.md +160 -0
  629. package/tutorial/full-guardrails-agent/tutorial/08-the-verification-gate.md +333 -0
  630. package/tutorial/full-guardrails-agent/tutorial/09-people-and-endings.md +313 -0
  631. package/tutorial/full-guardrails-agent/tutorial/10-testing-and-running.md +387 -0
  632. package/tutorial/full-guardrails-agent/tutorial/README.md +106 -0
  633. package/tutorial/full-guardrails-agent/tutorial/appendix-complete-code.md +2207 -0
  634. package/tutorial/full-guardrails-agent/tutorial/appendix-deployment.md +191 -0
  635. package/tutorial/full-guardrails-agent/tutorial/appendix-technique-map.md +117 -0
  636. package/tutorial/full-guardrails-agent/workflow.ts +219 -0
  637. package/tutorial/multi_agents/README.md +175 -0
  638. package/tutorial/multi_agents/advanced_agent.ts +395 -0
  639. package/tutorial/multi_agents/extending_agents.ts +641 -0
  640. package/tutorial/multi_agents/knowledge.ts +59 -0
  641. package/tutorial/multi_agents/lesson1_first_agent.md +368 -0
  642. package/tutorial/multi_agents/lesson2_knowledge_bases.md +404 -0
  643. package/tutorial/multi_agents/lesson3_multi_agent_systems.md +621 -0
  644. package/tutorial/multi_agents/lesson4_advanced_features.md +805 -0
  645. package/tutorial/multi_agents/lesson5_extending_agents.md +856 -0
  646. package/tutorial/multi_agents/pc_builder.ts +529 -0
  647. package/tutorial/multi_agents/sales_agent.ts +88 -0
  648. package/tutorial/multi_agents/sales_agent_with_search.ts +116 -0
  649. package/tutorial/multi_agents/sales_knowledge.md +139 -0
  650. package/tutorial/multi_agents/support_knowledge.md +256 -0
  651. package/dist/cli/mock-data.d.ts +0 -37
  652. package/dist/cli/mock-data.js +0 -80
  653. package/dist/cli/mock-data.js.map +0 -1
  654. package/dist/generateVerbTypes.d.ts +0 -11
  655. package/dist/generateVerbTypes.js +0 -265
  656. package/dist/generateVerbTypes.js.map +0 -1
  657. package/dist/rest/namespaces/compat.d.ts +0 -585
  658. package/dist/rest/namespaces/compat.js +0 -735
  659. 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
+ ```