@signalwire/sdk 2.0.5 → 3.5.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 (656) hide show
  1. package/CHANGELOG.md +785 -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 +481 -126
  6. package/dist/AgentBase.js +1502 -438
  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 +158 -45
  21. package/dist/DataMap.js +167 -52
  22. package/dist/DataMap.js.map +1 -1
  23. package/dist/FunctionResult.d.ts +277 -83
  24. package/dist/FunctionResult.js +444 -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 +158 -58
  58. package/dist/SWMLService.js +435 -127
  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/ServerlessAdapter.d.ts +156 -7
  67. package/dist/ServerlessAdapter.js +399 -42
  68. package/dist/ServerlessAdapter.js.map +1 -1
  69. package/dist/SessionManager.d.ts +11 -2
  70. package/dist/SessionManager.js +50 -18
  71. package/dist/SessionManager.js.map +1 -1
  72. package/dist/SslConfig.d.ts +2 -1
  73. package/dist/SslConfig.js +4 -1
  74. package/dist/SslConfig.js.map +1 -1
  75. package/dist/SwaigActions.generated.d.ts +23 -0
  76. package/dist/SwaigActions.generated.js +8 -0
  77. package/dist/SwaigActions.generated.js.map +1 -0
  78. package/dist/SwaigContracts.d.ts +15 -0
  79. package/dist/SwaigContracts.generated.d.ts +264 -0
  80. package/dist/SwaigContracts.generated.js +12 -0
  81. package/dist/SwaigContracts.generated.js.map +1 -0
  82. package/dist/SwaigContracts.js +2 -0
  83. package/dist/SwaigContracts.js.map +1 -0
  84. package/dist/SwaigFunction.d.ts +110 -4
  85. package/dist/SwaigFunction.js +151 -19
  86. package/dist/SwaigFunction.js.map +1 -1
  87. package/dist/SwmlBuilder.d.ts +68 -19
  88. package/dist/SwmlBuilder.js +74 -38
  89. package/dist/SwmlBuilder.js.map +1 -1
  90. package/dist/SwmlVerbMethods.generated.d.ts +41 -4
  91. package/dist/SwmlVerbMethods.generated.js +1 -1
  92. package/dist/TypeInference.d.ts +39 -3
  93. package/dist/TypeInference.js +256 -16
  94. package/dist/TypeInference.js.map +1 -1
  95. package/dist/WebService.d.ts +79 -11
  96. package/dist/WebService.js +320 -109
  97. package/dist/WebService.js.map +1 -1
  98. package/dist/WebhookMiddleware.d.ts +119 -0
  99. package/dist/WebhookMiddleware.js +271 -0
  100. package/dist/WebhookMiddleware.js.map +1 -0
  101. package/dist/WebhookValidator.d.ts +92 -0
  102. package/dist/WebhookValidator.js +409 -0
  103. package/dist/WebhookValidator.js.map +1 -0
  104. package/dist/agents/BedrockAgent.d.ts +162 -0
  105. package/dist/agents/BedrockAgent.js +323 -0
  106. package/dist/agents/BedrockAgent.js.map +1 -0
  107. package/dist/ai-chat/AIChatClient.d.ts +316 -0
  108. package/dist/ai-chat/AIChatClient.js +535 -0
  109. package/dist/ai-chat/AIChatClient.js.map +1 -0
  110. package/dist/ai-chat/ChatGateway.d.ts +408 -0
  111. package/dist/ai-chat/ChatGateway.js +747 -0
  112. package/dist/ai-chat/ChatGateway.js.map +1 -0
  113. package/dist/ai-chat/HandoffRouter.d.ts +282 -0
  114. package/dist/ai-chat/HandoffRouter.js +518 -0
  115. package/dist/ai-chat/HandoffRouter.js.map +1 -0
  116. package/dist/ai-chat/index.d.ts +12 -0
  117. package/dist/ai-chat/index.js +10 -0
  118. package/dist/ai-chat/index.js.map +1 -0
  119. package/dist/capabilities.d.ts +64 -0
  120. package/dist/capabilities.js +95 -0
  121. package/dist/capabilities.js.map +1 -0
  122. package/dist/cli/agent-loader.d.ts +32 -6
  123. package/dist/cli/agent-loader.js +92 -33
  124. package/dist/cli/agent-loader.js.map +1 -1
  125. package/dist/cli/datamap-exec.d.ts +175 -0
  126. package/dist/cli/datamap-exec.js +1284 -0
  127. package/dist/cli/datamap-exec.js.map +1 -0
  128. package/dist/cli/function-args.d.ts +40 -0
  129. package/dist/cli/function-args.js +146 -0
  130. package/dist/cli/function-args.js.map +1 -0
  131. package/dist/cli/simulation.d.ts +99 -0
  132. package/dist/cli/simulation.js +490 -0
  133. package/dist/cli/simulation.js.map +1 -0
  134. package/dist/cli/swaig-test.d.ts +12 -25
  135. package/dist/cli/swaig-test.js +935 -371
  136. package/dist/cli/swaig-test.js.map +1 -1
  137. package/dist/cli/tsdocs/agentsNote.d.ts +30 -0
  138. package/dist/cli/tsdocs/agentsNote.js +92 -0
  139. package/dist/cli/tsdocs/agentsNote.js.map +1 -0
  140. package/dist/cli/tsdocs/api-index.json +1 -0
  141. package/dist/cli/tsdocs/api.d.ts +91 -0
  142. package/dist/cli/tsdocs/api.js +372 -0
  143. package/dist/cli/tsdocs/api.js.map +1 -0
  144. package/dist/cli/tsdocs/apiTypes.d.ts +64 -0
  145. package/dist/cli/tsdocs/apiTypes.js +7 -0
  146. package/dist/cli/tsdocs/apiTypes.js.map +1 -0
  147. package/dist/cli/tsdocs/bin.d.ts +6 -0
  148. package/dist/cli/tsdocs/bin.js +23 -0
  149. package/dist/cli/tsdocs/bin.js.map +1 -0
  150. package/dist/cli/tsdocs/files.d.ts +108 -0
  151. package/dist/cli/tsdocs/files.js +287 -0
  152. package/dist/cli/tsdocs/files.js.map +1 -0
  153. package/dist/cli/tsdocs/index.d.ts +28 -0
  154. package/dist/cli/tsdocs/index.js +307 -0
  155. package/dist/cli/tsdocs/index.js.map +1 -0
  156. package/dist/cli/tsdocs/live.d.ts +41 -0
  157. package/dist/cli/tsdocs/live.js +202 -0
  158. package/dist/cli/tsdocs/live.js.map +1 -0
  159. package/dist/cli/tsdocs/locate.d.ts +51 -0
  160. package/dist/cli/tsdocs/locate.js +75 -0
  161. package/dist/cli/tsdocs/locate.js.map +1 -0
  162. package/dist/cli/tsdocs/render.d.ts +75 -0
  163. package/dist/cli/tsdocs/render.js +323 -0
  164. package/dist/cli/tsdocs/render.js.map +1 -0
  165. package/dist/cli/tsdocs/topics.d.ts +43 -0
  166. package/dist/cli/tsdocs/topics.js +916 -0
  167. package/dist/cli/tsdocs/topics.js.map +1 -0
  168. package/dist/index.d.ts +47 -68
  169. package/dist/index.js +44 -73
  170. package/dist/index.js.map +1 -1
  171. package/dist/livewire/index.d.ts +229 -155
  172. package/dist/livewire/index.js +298 -195
  173. package/dist/livewire/index.js.map +1 -1
  174. package/dist/llms.txt +65 -0
  175. package/dist/prefabs/CallSessionStore.d.ts +52 -0
  176. package/dist/prefabs/CallSessionStore.js +72 -0
  177. package/dist/prefabs/CallSessionStore.js.map +1 -0
  178. package/dist/prefabs/ConciergeAgent.d.ts +13 -1
  179. package/dist/prefabs/ConciergeAgent.js +36 -31
  180. package/dist/prefabs/ConciergeAgent.js.map +1 -1
  181. package/dist/prefabs/FAQBotAgent.d.ts +9 -1
  182. package/dist/prefabs/FAQBotAgent.js +113 -47
  183. package/dist/prefabs/FAQBotAgent.js.map +1 -1
  184. package/dist/prefabs/InfoGathererAgent.d.ts +22 -3
  185. package/dist/prefabs/InfoGathererAgent.js +67 -58
  186. package/dist/prefabs/InfoGathererAgent.js.map +1 -1
  187. package/dist/prefabs/ReceptionistAgent.d.ts +16 -5
  188. package/dist/prefabs/ReceptionistAgent.js +39 -31
  189. package/dist/prefabs/ReceptionistAgent.js.map +1 -1
  190. package/dist/prefabs/SurveyAgent.d.ts +22 -4
  191. package/dist/prefabs/SurveyAgent.js +84 -68
  192. package/dist/prefabs/SurveyAgent.js.map +1 -1
  193. package/dist/relay/Action.d.ts +44 -21
  194. package/dist/relay/Action.js +75 -17
  195. package/dist/relay/Action.js.map +1 -1
  196. package/dist/relay/Call.d.ts +312 -47
  197. package/dist/relay/Call.js +369 -18
  198. package/dist/relay/Call.js.map +1 -1
  199. package/dist/relay/Deferred.js.map +1 -1
  200. package/dist/relay/Message.d.ts +26 -5
  201. package/dist/relay/Message.js +36 -6
  202. package/dist/relay/Message.js.map +1 -1
  203. package/dist/relay/RelayClient.d.ts +44 -17
  204. package/dist/relay/RelayClient.js +175 -65
  205. package/dist/relay/RelayClient.js.map +1 -1
  206. package/dist/relay/RelayError.d.ts +14 -0
  207. package/dist/relay/RelayError.js +15 -0
  208. package/dist/relay/RelayError.js.map +1 -1
  209. package/dist/relay/RelayEvent.d.ts +96 -65
  210. package/dist/relay/RelayEvent.js +85 -56
  211. package/dist/relay/RelayEvent.js.map +1 -1
  212. package/dist/relay/closedSets.d.ts +111 -0
  213. package/dist/relay/closedSets.js +83 -0
  214. package/dist/relay/closedSets.js.map +1 -0
  215. package/dist/relay/index.d.ts +3 -1
  216. package/dist/relay/index.js +1 -0
  217. package/dist/relay/index.js.map +1 -1
  218. package/dist/relay/normalize.js.map +1 -1
  219. package/dist/relay/protocol.types.generated.d.ts +1195 -0
  220. package/dist/relay/protocol.types.generated.js +8 -0
  221. package/dist/relay/protocol.types.generated.js.map +1 -0
  222. package/dist/relay/types.d.ts +73 -42
  223. package/dist/rest/HttpClient.d.ts +36 -8
  224. package/dist/rest/HttpClient.js +233 -40
  225. package/dist/rest/HttpClient.js.map +1 -1
  226. package/dist/rest/RequestOptions.d.ts +110 -0
  227. package/dist/rest/RequestOptions.js +113 -0
  228. package/dist/rest/RequestOptions.js.map +1 -0
  229. package/dist/rest/RestError.d.ts +52 -6
  230. package/dist/rest/RestError.js +89 -5
  231. package/dist/rest/RestError.js.map +1 -1
  232. package/dist/rest/base/CrudResource.d.ts +16 -26
  233. package/dist/rest/base/CrudResource.js +19 -33
  234. package/dist/rest/base/CrudResource.js.map +1 -1
  235. package/dist/rest/base/CrudWithAddresses.d.ts +3 -2
  236. package/dist/rest/base/CrudWithAddresses.js +2 -2
  237. package/dist/rest/base/CrudWithAddresses.js.map +1 -1
  238. package/dist/rest/base/FabricResource.d.ts +15 -0
  239. package/dist/rest/base/FabricResource.js +16 -0
  240. package/dist/rest/base/FabricResource.js.map +1 -0
  241. package/dist/rest/base/ReadResource.d.ts +62 -0
  242. package/dist/rest/base/ReadResource.js +69 -0
  243. package/dist/rest/base/ReadResource.js.map +1 -0
  244. package/dist/rest/callHandler.d.ts +5 -2
  245. package/dist/rest/callHandler.js +4 -1
  246. package/dist/rest/callHandler.js.map +1 -1
  247. package/dist/rest/index.d.ts +18 -77
  248. package/dist/rest/index.js +47 -120
  249. package/dist/rest/index.js.map +1 -1
  250. package/dist/rest/namespaces/_client_tree_generated.d.ts +103 -0
  251. package/dist/rest/namespaces/_client_tree_generated.js +171 -0
  252. package/dist/rest/namespaces/_client_tree_generated.js.map +1 -0
  253. package/dist/rest/namespaces/addresses.d.ts +3 -42
  254. package/dist/rest/namespaces/addresses.js +3 -50
  255. package/dist/rest/namespaces/addresses.js.map +1 -1
  256. package/dist/rest/namespaces/calling.d.ts +6 -378
  257. package/dist/rest/namespaces/calling.js +6 -473
  258. package/dist/rest/namespaces/calling.js.map +1 -1
  259. package/dist/rest/namespaces/calling.resources.generated.d.ts +165 -0
  260. package/dist/rest/namespaces/calling.resources.generated.js +477 -0
  261. package/dist/rest/namespaces/calling.resources.generated.js.map +1 -0
  262. package/dist/rest/namespaces/calling.types.generated.d.ts +2917 -0
  263. package/dist/rest/namespaces/calling.types.generated.js +8 -0
  264. package/dist/rest/namespaces/calling.types.generated.js.map +1 -0
  265. package/dist/rest/namespaces/chat.d.ts +4 -18
  266. package/dist/rest/namespaces/chat.js +4 -21
  267. package/dist/rest/namespaces/chat.js.map +1 -1
  268. package/dist/rest/namespaces/chat.resources.generated.d.ts +12 -0
  269. package/dist/rest/namespaces/chat.resources.generated.js +29 -0
  270. package/dist/rest/namespaces/chat.resources.generated.js.map +1 -0
  271. package/dist/rest/namespaces/chat.types.generated.d.ts +56 -0
  272. package/dist/rest/namespaces/chat.types.generated.js +8 -0
  273. package/dist/rest/namespaces/chat.types.generated.js.map +1 -0
  274. package/dist/rest/namespaces/datasphere.d.ts +6 -62
  275. package/dist/rest/namespaces/datasphere.js +6 -72
  276. package/dist/rest/namespaces/datasphere.js.map +1 -1
  277. package/dist/rest/namespaces/datasphere.resources.generated.d.ts +25 -0
  278. package/dist/rest/namespaces/datasphere.resources.generated.js +50 -0
  279. package/dist/rest/namespaces/datasphere.resources.generated.js.map +1 -0
  280. package/dist/rest/namespaces/datasphere.types.generated.d.ts +180 -0
  281. package/dist/rest/namespaces/datasphere.types.generated.js +8 -0
  282. package/dist/rest/namespaces/datasphere.types.generated.js.map +1 -0
  283. package/dist/rest/namespaces/fabric.d.ts +11 -327
  284. package/dist/rest/namespaces/fabric.js +14 -439
  285. package/dist/rest/namespaces/fabric.js.map +1 -1
  286. package/dist/rest/namespaces/fabric.resources.generated.d.ts +195 -0
  287. package/dist/rest/namespaces/fabric.resources.generated.js +399 -0
  288. package/dist/rest/namespaces/fabric.resources.generated.js.map +1 -0
  289. package/dist/rest/namespaces/fabric.types.generated.d.ts +4557 -0
  290. package/dist/rest/namespaces/fabric.types.generated.js +8 -0
  291. package/dist/rest/namespaces/fabric.types.generated.js.map +1 -0
  292. package/dist/rest/namespaces/fax.resources.generated.d.ts +6 -0
  293. package/dist/rest/namespaces/fax.resources.generated.js +14 -0
  294. package/dist/rest/namespaces/fax.resources.generated.js.map +1 -0
  295. package/dist/rest/namespaces/fax.types.generated.d.ts +131 -0
  296. package/dist/rest/namespaces/fax.types.generated.js +8 -0
  297. package/dist/rest/namespaces/fax.types.generated.js.map +1 -0
  298. package/dist/rest/namespaces/imported-numbers.d.ts +3 -18
  299. package/dist/rest/namespaces/imported-numbers.js +3 -21
  300. package/dist/rest/namespaces/imported-numbers.js.map +1 -1
  301. package/dist/rest/namespaces/logs.d.ts +10 -101
  302. package/dist/rest/namespaces/logs.js +10 -128
  303. package/dist/rest/namespaces/logs.js.map +1 -1
  304. package/dist/rest/namespaces/logs.resources.generated.d.ts +9 -0
  305. package/dist/rest/namespaces/logs.resources.generated.js +17 -0
  306. package/dist/rest/namespaces/logs.resources.generated.js.map +1 -0
  307. package/dist/rest/namespaces/logs.types.generated.d.ts +131 -0
  308. package/dist/rest/namespaces/logs.types.generated.js +8 -0
  309. package/dist/rest/namespaces/logs.types.generated.js.map +1 -0
  310. package/dist/rest/namespaces/lookup.d.ts +3 -25
  311. package/dist/rest/namespaces/lookup.js +3 -27
  312. package/dist/rest/namespaces/lookup.js.map +1 -1
  313. package/dist/rest/namespaces/message.resources.generated.d.ts +6 -0
  314. package/dist/rest/namespaces/message.resources.generated.js +14 -0
  315. package/dist/rest/namespaces/message.resources.generated.js.map +1 -0
  316. package/dist/rest/namespaces/message.types.generated.d.ts +122 -0
  317. package/dist/rest/namespaces/message.types.generated.js +8 -0
  318. package/dist/rest/namespaces/message.types.generated.js.map +1 -0
  319. package/dist/rest/namespaces/messages.resources.generated.d.ts +18 -0
  320. package/dist/rest/namespaces/messages.resources.generated.js +44 -0
  321. package/dist/rest/namespaces/messages.resources.generated.js.map +1 -0
  322. package/dist/rest/namespaces/messages.types.generated.d.ts +99 -0
  323. package/dist/rest/namespaces/messages.types.generated.js +8 -0
  324. package/dist/rest/namespaces/messages.types.generated.js.map +1 -0
  325. package/dist/rest/namespaces/mfa.d.ts +3 -42
  326. package/dist/rest/namespaces/mfa.js +3 -49
  327. package/dist/rest/namespaces/mfa.js.map +1 -1
  328. package/dist/rest/namespaces/number-groups.d.ts +3 -45
  329. package/dist/rest/namespaces/number-groups.js +3 -53
  330. package/dist/rest/namespaces/number-groups.js.map +1 -1
  331. package/dist/rest/namespaces/phone-numbers.d.ts +8 -196
  332. package/dist/rest/namespaces/phone-numbers.js +8 -230
  333. package/dist/rest/namespaces/phone-numbers.js.map +1 -1
  334. package/dist/rest/namespaces/project.d.ts +6 -42
  335. package/dist/rest/namespaces/project.js +6 -51
  336. package/dist/rest/namespaces/project.js.map +1 -1
  337. package/dist/rest/namespaces/project.resources.generated.d.ts +17 -0
  338. package/dist/rest/namespaces/project.resources.generated.js +44 -0
  339. package/dist/rest/namespaces/project.resources.generated.js.map +1 -0
  340. package/dist/rest/namespaces/project.types.generated.d.ts +58 -0
  341. package/dist/rest/namespaces/project.types.generated.js +8 -0
  342. package/dist/rest/namespaces/project.types.generated.js.map +1 -0
  343. package/dist/rest/namespaces/projects.resources.generated.d.ts +12 -0
  344. package/dist/rest/namespaces/projects.resources.generated.js +25 -0
  345. package/dist/rest/namespaces/projects.resources.generated.js.map +1 -0
  346. package/dist/rest/namespaces/projects.types.generated.d.ts +77 -0
  347. package/dist/rest/namespaces/projects.types.generated.js +8 -0
  348. package/dist/rest/namespaces/projects.types.generated.js.map +1 -0
  349. package/dist/rest/namespaces/pubsub.d.ts +4 -18
  350. package/dist/rest/namespaces/pubsub.js +4 -21
  351. package/dist/rest/namespaces/pubsub.js.map +1 -1
  352. package/dist/rest/namespaces/pubsub.resources.generated.d.ts +12 -0
  353. package/dist/rest/namespaces/pubsub.resources.generated.js +29 -0
  354. package/dist/rest/namespaces/pubsub.resources.generated.js.map +1 -0
  355. package/dist/rest/namespaces/pubsub.types.generated.d.ts +60 -0
  356. package/dist/rest/namespaces/pubsub.types.generated.js +8 -0
  357. package/dist/rest/namespaces/pubsub.types.generated.js.map +1 -0
  358. package/dist/rest/namespaces/queues.d.ts +3 -38
  359. package/dist/rest/namespaces/queues.js +3 -44
  360. package/dist/rest/namespaces/queues.js.map +1 -1
  361. package/dist/rest/namespaces/recordings.d.ts +3 -34
  362. package/dist/rest/namespaces/recordings.js +3 -40
  363. package/dist/rest/namespaces/recordings.js.map +1 -1
  364. package/dist/rest/namespaces/registry.d.ts +6 -137
  365. package/dist/rest/namespaces/registry.js +6 -173
  366. package/dist/rest/namespaces/registry.js.map +1 -1
  367. package/dist/rest/namespaces/relay-rest.resources.generated.d.ts +168 -0
  368. package/dist/rest/namespaces/relay-rest.resources.generated.js +430 -0
  369. package/dist/rest/namespaces/relay-rest.resources.generated.js.map +1 -0
  370. package/dist/rest/namespaces/relay-rest.types.generated.d.ts +1906 -0
  371. package/dist/rest/namespaces/relay-rest.types.generated.js +8 -0
  372. package/dist/rest/namespaces/relay-rest.types.generated.js.map +1 -0
  373. package/dist/rest/namespaces/short-codes.d.ts +3 -35
  374. package/dist/rest/namespaces/short-codes.js +3 -41
  375. package/dist/rest/namespaces/short-codes.js.map +1 -1
  376. package/dist/rest/namespaces/sip-profile.d.ts +3 -24
  377. package/dist/rest/namespaces/sip-profile.js +3 -29
  378. package/dist/rest/namespaces/sip-profile.js.map +1 -1
  379. package/dist/rest/namespaces/verified-callers.d.ts +3 -29
  380. package/dist/rest/namespaces/verified-callers.js +3 -34
  381. package/dist/rest/namespaces/verified-callers.js.map +1 -1
  382. package/dist/rest/namespaces/video.d.ts +10 -227
  383. package/dist/rest/namespaces/video.js +10 -288
  384. package/dist/rest/namespaces/video.js.map +1 -1
  385. package/dist/rest/namespaces/video.resources.generated.d.ts +81 -0
  386. package/dist/rest/namespaces/video.resources.generated.js +171 -0
  387. package/dist/rest/namespaces/video.resources.generated.js.map +1 -0
  388. package/dist/rest/namespaces/video.types.generated.d.ts +771 -0
  389. package/dist/rest/namespaces/video.types.generated.js +8 -0
  390. package/dist/rest/namespaces/video.types.generated.js.map +1 -0
  391. package/dist/rest/namespaces/voice.resources.generated.d.ts +9 -0
  392. package/dist/rest/namespaces/voice.resources.generated.js +17 -0
  393. package/dist/rest/namespaces/voice.resources.generated.js.map +1 -0
  394. package/dist/rest/namespaces/voice.types.generated.d.ts +214 -0
  395. package/dist/rest/namespaces/voice.types.generated.js +8 -0
  396. package/dist/rest/namespaces/voice.types.generated.js.map +1 -0
  397. package/dist/rest/pagination.d.ts +5 -1
  398. package/dist/rest/pagination.js +40 -20
  399. package/dist/rest/pagination.js.map +1 -1
  400. package/dist/rest/types.d.ts +21 -3
  401. package/dist/schema.json +299 -98
  402. package/dist/skills/SkillBase.d.ts +97 -20
  403. package/dist/skills/SkillBase.js +100 -17
  404. package/dist/skills/SkillBase.js.map +1 -1
  405. package/dist/skills/SkillManager.d.ts +66 -13
  406. package/dist/skills/SkillManager.js +101 -20
  407. package/dist/skills/SkillManager.js.map +1 -1
  408. package/dist/skills/SkillName.d.ts +44 -0
  409. package/dist/skills/SkillName.js +2 -0
  410. package/dist/skills/SkillName.js.map +1 -0
  411. package/dist/skills/SkillRegistry.d.ts +22 -11
  412. package/dist/skills/SkillRegistry.js +47 -17
  413. package/dist/skills/SkillRegistry.js.map +1 -1
  414. package/dist/skills/builtin/api_ninjas_trivia.d.ts +3 -1
  415. package/dist/skills/builtin/api_ninjas_trivia.js +18 -6
  416. package/dist/skills/builtin/api_ninjas_trivia.js.map +1 -1
  417. package/dist/skills/builtin/ask_claude.d.ts +14 -4
  418. package/dist/skills/builtin/ask_claude.js +36 -14
  419. package/dist/skills/builtin/ask_claude.js.map +1 -1
  420. package/dist/skills/builtin/claude_skills.d.ts +3 -1
  421. package/dist/skills/builtin/claude_skills.js +19 -15
  422. package/dist/skills/builtin/claude_skills.js.map +1 -1
  423. package/dist/skills/builtin/custom_skills.d.ts +10 -3
  424. package/dist/skills/builtin/custom_skills.js +26 -9
  425. package/dist/skills/builtin/custom_skills.js.map +1 -1
  426. package/dist/skills/builtin/datasphere.d.ts +5 -3
  427. package/dist/skills/builtin/datasphere.js +21 -22
  428. package/dist/skills/builtin/datasphere.js.map +1 -1
  429. package/dist/skills/builtin/datasphere_serverless.d.ts +12 -1
  430. package/dist/skills/builtin/datasphere_serverless.js +17 -6
  431. package/dist/skills/builtin/datasphere_serverless.js.map +1 -1
  432. package/dist/skills/builtin/datetime.d.ts +3 -1
  433. package/dist/skills/builtin/datetime.js +11 -7
  434. package/dist/skills/builtin/datetime.js.map +1 -1
  435. package/dist/skills/builtin/google_maps.d.ts +29 -14
  436. package/dist/skills/builtin/google_maps.js +89 -269
  437. package/dist/skills/builtin/google_maps.js.map +1 -1
  438. package/dist/skills/builtin/index.d.ts +8 -6
  439. package/dist/skills/builtin/index.js +8 -6
  440. package/dist/skills/builtin/index.js.map +1 -1
  441. package/dist/skills/builtin/info_gatherer.d.ts +4 -2
  442. package/dist/skills/builtin/info_gatherer.js +20 -12
  443. package/dist/skills/builtin/info_gatherer.js.map +1 -1
  444. package/dist/skills/builtin/joke.d.ts +16 -6
  445. package/dist/skills/builtin/joke.js +54 -37
  446. package/dist/skills/builtin/joke.js.map +1 -1
  447. package/dist/skills/builtin/math.d.ts +3 -1
  448. package/dist/skills/builtin/math.js +14 -9
  449. package/dist/skills/builtin/math.js.map +1 -1
  450. package/dist/skills/builtin/mcp_gateway.d.ts +34 -5
  451. package/dist/skills/builtin/mcp_gateway.js +77 -46
  452. package/dist/skills/builtin/mcp_gateway.js.map +1 -1
  453. package/dist/skills/builtin/native_vector_search.d.ts +19 -5
  454. package/dist/skills/builtin/native_vector_search.js +179 -61
  455. package/dist/skills/builtin/native_vector_search.js.map +1 -1
  456. package/dist/skills/builtin/play_background_file.d.ts +21 -15
  457. package/dist/skills/builtin/play_background_file.js +43 -122
  458. package/dist/skills/builtin/play_background_file.js.map +1 -1
  459. package/dist/skills/builtin/spider.d.ts +42 -4
  460. package/dist/skills/builtin/spider.js +277 -104
  461. package/dist/skills/builtin/spider.js.map +1 -1
  462. package/dist/skills/builtin/swml_transfer.d.ts +14 -3
  463. package/dist/skills/builtin/swml_transfer.js +45 -24
  464. package/dist/skills/builtin/swml_transfer.js.map +1 -1
  465. package/dist/skills/builtin/weather_api.d.ts +24 -13
  466. package/dist/skills/builtin/weather_api.js +38 -30
  467. package/dist/skills/builtin/weather_api.js.map +1 -1
  468. package/dist/skills/builtin/web_search.d.ts +48 -10
  469. package/dist/skills/builtin/web_search.js +294 -100
  470. package/dist/skills/builtin/web_search.js.map +1 -1
  471. package/dist/skills/builtin/wikipedia_search.d.ts +4 -2
  472. package/dist/skills/builtin/wikipedia_search.js +14 -13
  473. package/dist/skills/builtin/wikipedia_search.js.map +1 -1
  474. package/dist/skills/index.d.ts +3 -2
  475. package/dist/skills/index.js +1 -1
  476. package/dist/skills/index.js.map +1 -1
  477. package/dist/swml_verbs_generated.d.ts +2824 -0
  478. package/dist/swml_verbs_generated.js +12 -0
  479. package/dist/swml_verbs_generated.js.map +1 -0
  480. package/dist/types.d.ts +59 -6
  481. package/dist/web.d.ts +27 -0
  482. package/dist/web.js +20 -0
  483. package/dist/web.js.map +1 -0
  484. package/docs/agent-guide.md +1034 -0
  485. package/docs/ai_chat.md +560 -0
  486. package/docs/api-reference.md +3534 -0
  487. package/docs/architecture.md +846 -0
  488. package/docs/bedrock_agent.md +411 -0
  489. package/docs/cli-guide.md +403 -0
  490. package/docs/cloud_functions_guide.md +399 -0
  491. package/docs/configuration.md +548 -0
  492. package/docs/contexts-guide.md +884 -0
  493. package/docs/datamap-guide.md +1160 -0
  494. package/docs/developer_pain_points.md +548 -0
  495. package/docs/llm_parameters.md +298 -0
  496. package/docs/mcp_gateway_reference.md +354 -0
  497. package/docs/mcp_integration.md +162 -0
  498. package/docs/pgi_agent_guide.md +1820 -0
  499. package/docs/prefabs-guide.md +815 -0
  500. package/docs/programmatically_governed_inference.md +301 -0
  501. package/docs/sdk_features.md +501 -0
  502. package/docs/security.md +559 -0
  503. package/docs/serverless-guide.md +520 -0
  504. package/docs/skills-guide.md +1223 -0
  505. package/docs/skills-system.md +405 -0
  506. package/docs/skills_parameter_schema.md +417 -0
  507. package/docs/swaig-reference.md +1938 -0
  508. package/docs/swml_service_guide.md +573 -0
  509. package/docs/third_party_skills.md +410 -0
  510. package/docs/web_service.md +666 -0
  511. package/examples/README.md +202 -0
  512. package/examples/advanced-datamap.ts +108 -0
  513. package/examples/advanced-dynamic-config.ts +70 -0
  514. package/examples/auto-vivified.ts +95 -0
  515. package/examples/call-flow.ts +65 -0
  516. package/examples/comprehensive-dynamic.ts +125 -0
  517. package/examples/contexts-steps.ts +65 -0
  518. package/examples/custom-path.ts +45 -0
  519. package/examples/datamap-tools.ts +51 -0
  520. package/examples/datasphere-multi-instance.ts +66 -0
  521. package/examples/datasphere-serverless-env.ts +87 -0
  522. package/examples/datasphere-webhook-env.ts +65 -0
  523. package/examples/datasphere.ts +56 -0
  524. package/examples/declarative.ts +100 -0
  525. package/examples/dynamic-config.ts +54 -0
  526. package/examples/dynamic-info-gatherer.ts +69 -0
  527. package/examples/dynamic-swml-service.ts +67 -0
  528. package/examples/gather-info.ts +95 -0
  529. package/examples/gather-per-question-functions-demo.ts +139 -0
  530. package/examples/joke-agent.ts +34 -0
  531. package/examples/kubernetes-agent.ts +45 -0
  532. package/examples/llm-params.ts +75 -0
  533. package/examples/mcp-agent.ts +89 -0
  534. package/examples/mcp-gateway.ts +81 -0
  535. package/examples/multi-agent.ts +80 -0
  536. package/examples/multi-endpoint.ts +79 -0
  537. package/examples/pgi/case-domain.ts +114 -0
  538. package/examples/pgi/serve.ts +16 -0
  539. package/examples/pgi/support-agent.ts +265 -0
  540. package/examples/pom-prompt.ts +70 -0
  541. package/examples/prefab-concierge.ts +42 -0
  542. package/examples/prefab-faq.ts +58 -0
  543. package/examples/prefab-info-gatherer.ts +33 -0
  544. package/examples/prefab-receptionist.ts +36 -0
  545. package/examples/prefab-survey.ts +69 -0
  546. package/examples/quickstart-agent.ts +29 -0
  547. package/examples/quickstart-relay.ts +25 -0
  548. package/examples/quickstart-rest.ts +25 -0
  549. package/examples/record-call.ts +65 -0
  550. package/examples/relay-demo.ts +33 -0
  551. package/examples/room-and-sip.ts +93 -0
  552. package/examples/serverless-lambda.ts +43 -0
  553. package/examples/session-state.ts +83 -0
  554. package/examples/simple-agent.ts +36 -0
  555. package/examples/simple-static.ts +29 -0
  556. package/examples/skills-demo.ts +41 -0
  557. package/examples/step-function-inheritance-demo.ts +124 -0
  558. package/examples/swaig-features.ts +193 -0
  559. package/examples/swml-service-routing.ts +66 -0
  560. package/examples/swml-service.ts +38 -0
  561. package/examples/swmlservice_ai_sidecar.ts +104 -0
  562. package/examples/swmlservice_swaig_standalone.ts +79 -0
  563. package/examples/tap.ts +67 -0
  564. package/examples/typed-tools.ts +68 -0
  565. package/examples/verb-methods.ts +45 -0
  566. package/examples/web-search-multi-instance.ts +75 -0
  567. package/examples/web-search.ts +38 -0
  568. package/examples/wikipedia.ts +36 -0
  569. package/livewire/README.md +164 -0
  570. package/livewire/docs/migration-guide.md +251 -0
  571. package/livewire/examples/livewire-basic-agent.ts +74 -0
  572. package/livewire/examples/livewire-handoff.ts +196 -0
  573. package/livewire/examples/livewire-multi-tool.ts +121 -0
  574. package/package.json +85 -13
  575. package/relay/README.md +101 -0
  576. package/relay/docs/call-methods.md +622 -0
  577. package/relay/docs/client-reference.md +281 -0
  578. package/relay/docs/events.md +193 -0
  579. package/relay/docs/getting-started.md +221 -0
  580. package/relay/docs/guide.md +386 -0
  581. package/relay/docs/messaging.md +246 -0
  582. package/relay/examples/relay-inbound.ts +66 -0
  583. package/relay/examples/relay-messaging.ts +74 -0
  584. package/relay/examples/relay-outbound.ts +76 -0
  585. package/rest/README.md +141 -0
  586. package/rest/docs/calling.md +313 -0
  587. package/rest/docs/client-reference.md +149 -0
  588. package/rest/docs/fabric.md +192 -0
  589. package/rest/docs/getting-started.md +138 -0
  590. package/rest/docs/guide.md +421 -0
  591. package/rest/docs/namespaces.md +367 -0
  592. package/rest/docs/phone-binding.md +116 -0
  593. package/rest/examples/rest-10dlc-registration.ts +177 -0
  594. package/rest/examples/rest-bind-phone-to-swml-webhook.ts +66 -0
  595. package/rest/examples/rest-calling-ivr-and-ai.ts +136 -0
  596. package/rest/examples/rest-calling-play-and-record.ts +98 -0
  597. package/rest/examples/rest-client.ts +59 -0
  598. package/rest/examples/rest-datasphere-search.ts +81 -0
  599. package/rest/examples/rest-fabric-conferences-and-routing.ts +147 -0
  600. package/rest/examples/rest-fabric-subscribers-and-sip.ts +106 -0
  601. package/rest/examples/rest-fabric-swml-and-callflows.ts +101 -0
  602. package/rest/examples/rest-manage-resources.ts +64 -0
  603. package/rest/examples/rest-phone-number-management.ts +200 -0
  604. package/rest/examples/rest-queues-mfa-and-recordings.ts +143 -0
  605. package/rest/examples/rest-video-rooms.ts +186 -0
  606. package/tutorial/fred/fred.ts +218 -0
  607. package/tutorial/fred/tutorial/01-introduction.md +141 -0
  608. package/tutorial/fred/tutorial/02-setup.md +304 -0
  609. package/tutorial/fred/tutorial/03-basic-agent.md +284 -0
  610. package/tutorial/fred/tutorial/04-wikipedia-skill.md +298 -0
  611. package/tutorial/fred/tutorial/05-custom-functions.md +347 -0
  612. package/tutorial/fred/tutorial/06-running-testing.md +642 -0
  613. package/tutorial/fred/tutorial/README.md +56 -0
  614. package/tutorial/fred/tutorial/appendix-complete-code.md +632 -0
  615. package/tutorial/fred/tutorial/appendix-docker-deployment.md +504 -0
  616. package/tutorial/full-guardrails-agent/handlers.ts +436 -0
  617. package/tutorial/full-guardrails-agent/penny.ts +305 -0
  618. package/tutorial/full-guardrails-agent/reservations.ts +1109 -0
  619. package/tutorial/full-guardrails-agent/tutorial/01-why-guardrails.md +149 -0
  620. package/tutorial/full-guardrails-agent/tutorial/02-design-first.md +139 -0
  621. package/tutorial/full-guardrails-agent/tutorial/03-rules-first.md +422 -0
  622. package/tutorial/full-guardrails-agent/tutorial/04-the-shell.md +238 -0
  623. package/tutorial/full-guardrails-agent/tutorial/05-steps-and-scoping.md +247 -0
  624. package/tutorial/full-guardrails-agent/tutorial/06-tools-that-decide.md +467 -0
  625. package/tutorial/full-guardrails-agent/tutorial/07-gather-and-projection.md +160 -0
  626. package/tutorial/full-guardrails-agent/tutorial/08-the-verification-gate.md +333 -0
  627. package/tutorial/full-guardrails-agent/tutorial/09-people-and-endings.md +313 -0
  628. package/tutorial/full-guardrails-agent/tutorial/10-testing-and-running.md +387 -0
  629. package/tutorial/full-guardrails-agent/tutorial/README.md +106 -0
  630. package/tutorial/full-guardrails-agent/tutorial/appendix-complete-code.md +2207 -0
  631. package/tutorial/full-guardrails-agent/tutorial/appendix-deployment.md +191 -0
  632. package/tutorial/full-guardrails-agent/tutorial/appendix-technique-map.md +117 -0
  633. package/tutorial/full-guardrails-agent/workflow.ts +219 -0
  634. package/tutorial/multi_agents/README.md +175 -0
  635. package/tutorial/multi_agents/advanced_agent.ts +395 -0
  636. package/tutorial/multi_agents/extending_agents.ts +641 -0
  637. package/tutorial/multi_agents/knowledge.ts +59 -0
  638. package/tutorial/multi_agents/lesson1_first_agent.md +368 -0
  639. package/tutorial/multi_agents/lesson2_knowledge_bases.md +404 -0
  640. package/tutorial/multi_agents/lesson3_multi_agent_systems.md +621 -0
  641. package/tutorial/multi_agents/lesson4_advanced_features.md +805 -0
  642. package/tutorial/multi_agents/lesson5_extending_agents.md +856 -0
  643. package/tutorial/multi_agents/pc_builder.ts +529 -0
  644. package/tutorial/multi_agents/sales_agent.ts +88 -0
  645. package/tutorial/multi_agents/sales_agent_with_search.ts +116 -0
  646. package/tutorial/multi_agents/sales_knowledge.md +139 -0
  647. package/tutorial/multi_agents/support_knowledge.md +256 -0
  648. package/dist/cli/mock-data.d.ts +0 -37
  649. package/dist/cli/mock-data.js +0 -80
  650. package/dist/cli/mock-data.js.map +0 -1
  651. package/dist/generateVerbTypes.d.ts +0 -11
  652. package/dist/generateVerbTypes.js +0 -265
  653. package/dist/generateVerbTypes.js.map +0 -1
  654. package/dist/rest/namespaces/compat.d.ts +0 -585
  655. package/dist/rest/namespaces/compat.js +0 -735
  656. package/dist/rest/namespaces/compat.js.map +0 -1
@@ -0,0 +1,560 @@
1
+ # AI Chat
2
+
3
+ The SignalWire AI Chat service runs an agent as a text conversation. The SDK has three classes for it, exported from `@signalwire/sdk`:
4
+
5
+ - `AIChatClient` calls the service from your server, with your project credentials.
6
+ - `ChatGateway` is a Hono router you mount in your app. A chat widget in a browser uses the service through it, without holding an API token.
7
+ - `HandoffRouter` is a second Hono router. It moves one conversation between a phone call and the chat, and lets a browser type into a live call.
8
+
9
+ ## Contents
10
+
11
+ The guide has these sections:
12
+
13
+ - [AIChatClient](#aichatclient)
14
+ - [Credentials and the service URL](#credentials-and-the-service-url)
15
+ - [Methods](#methods)
16
+ - [Errors](#errors)
17
+ - [Slow turns and the idle timeout](#slow-turns-and-the-idle-timeout)
18
+ - [Conversation IDs](#conversation-ids)
19
+ - [ChatGateway](#chatgateway)
20
+ - [Mount the gateway](#mount-the-gateway)
21
+ - [The wire protocol](#the-wire-protocol)
22
+ - [Page context in user_meta_data](#page-context-in-user_meta_data)
23
+ - [What the gateway protects, and what it doesn't](#what-the-gateway-protects-and-what-it-doesnt)
24
+ - [Size limits](#size-limits)
25
+ - [CORS](#cors)
26
+ - [Streaming](#streaming)
27
+ - [Rotate a key](#rotate-a-key)
28
+ - [Gateway reference](#gateway-reference)
29
+ - [HandoffRouter](#handoffrouter)
30
+ - [Register a call's nonce](#register-a-calls-nonce)
31
+ - [Routes](#routes)
32
+ - [The ordering guarantee](#the-ordering-guarantee)
33
+ - [What the nonce protects, and what it doesn't](#what-the-nonce-protects-and-what-it-doesnt)
34
+ - [HandoffRouter reference](#handoffrouter-reference)
35
+ - [Running more than one replica](#running-more-than-one-replica)
36
+ - [Related documentation](#related-documentation)
37
+
38
+ ## AIChatClient
39
+
40
+ `AIChatClient` sends JSON-RPC 2.0 requests to the AI Chat service. Each request is a `POST` with HTTP Basic auth: the project ID is the username and the API token is the password. The credentials travel only in the `Authorization` header, never in the request body.
41
+
42
+ This example creates a conversation from an agent's config URL, sends one message, and prints the reply:
43
+
44
+ <!-- snippet: no-run needs a real project, API token and space, and a reachable agent config URL -->
45
+ ```typescript
46
+ import { AIChatClient } from '@signalwire/sdk';
47
+
48
+ const client = new AIChatClient(); // reads SIGNALWIRE_PROJECT_ID, SIGNALWIRE_API_TOKEN, SIGNALWIRE_SPACE
49
+
50
+ const created = await client.createConversation('support.42', {
51
+ configUrl: 'https://agent.example.com/',
52
+ });
53
+ console.log(created.initialMessage);
54
+
55
+ const reply = await client.chat('support.42', 'Where is my order?');
56
+ console.log(reply.text);
57
+
58
+ await client.end('support.42');
59
+ ```
60
+
61
+ `configUrl` locates the agent config the conversation runs. The service fetches it like any other client, so an agent behind basic auth needs its credentials in the URL, as `agent.getFullUrl(true)` gives them.
62
+
63
+ ### Credentials and the service URL
64
+
65
+ The constructor takes an `AIChatClientOptions` object. Each credential falls back to an environment variable:
66
+
67
+ | Option | Environment variable | Description |
68
+ |---|---|---|
69
+ | `project` | `SIGNALWIRE_PROJECT_ID` | Project ID, the Basic auth username. Required: the constructor throws without it. |
70
+ | `token` | `SIGNALWIRE_API_TOKEN` | API token, the Basic auth password |
71
+ | `space` | `SIGNALWIRE_SPACE` | Space name (`example`) or space hostname (`example.signalwire.com`) |
72
+ | `url` | none | Full service URL, used as it is |
73
+ | `readIdleTimeoutSeconds` | none | Seconds without data before a request is abandoned. Default 60; `0` turns it off. |
74
+ | `fetchImpl` | none | A `fetch` replacement, for tests |
75
+
76
+ The client picks the service URL in this order:
77
+
78
+ 1. The `url` option.
79
+ 2. `RAILS_DEV_MODE`, when it holds a URL. A boolean value (`true`, `false`, `1`, `0`, `yes`, `no`, `on` or `off`) doesn't count as a URL and is skipped.
80
+ 3. `https://{space}.signalwire.com/api/ai/chat`, from `space` or `SIGNALWIRE_SPACE`. A value that contains a dot is used as the hostname: `example.signalwire.com` gives `https://example.signalwire.com/api/ai/chat`.
81
+
82
+ If none of the three resolves, the constructor throws. `RAILS_DEV_MODE` points the client at a development chat service, such as `http://localhost:8080/`.
83
+
84
+ ### Methods
85
+
86
+ Every method returns a promise. The typed methods decode the JSON-RPC result, and throw an `AIChatError` when the response carries an error:
87
+
88
+ | Method | Service method | Returns |
89
+ |---|---|---|
90
+ | `createConversation(id, { configUrl, userMessage?, timeout?, reinit?, userMetadata? })` | `create_conversation` | `{ id, status, initialMessage }` |
91
+ | `chat(id, message, { role?, configUrl?, timeout?, reinit?, userMetadata? })` | `chat` | `{ text, conversationId, userEvent }` |
92
+ | `end(id)` | `end_conversation` | `true` when the service reports `ended` |
93
+ | `delete(id)` | `delete` | `true` when the service reports `deleted` |
94
+ | `log(id)` | `chat_log` | `{ messages, callTimeline }` |
95
+ | `summarize(id, { summaryPrompt?, temperature?, topP?, frequencyPenalty?, presencePenalty?, maxTokens? })` | `summarize` | The summary text |
96
+ | `rawPost(method, params)` | any | The `Response`, with its body unread |
97
+ | `close()` | none | Nothing; the client holds no connection pool |
98
+
99
+ The options map to these request fields:
100
+
101
+ - `timeout` is sent as `conversation_timeout`, in seconds of inactivity.
102
+ - `userMetadata` is sent as `user_meta_data`.
103
+ - `userMessage` is sent as `user_message`, the opening user message.
104
+ - `role` defaults to `user`.
105
+
106
+ On `chat()`, `configUrl` lets the service create the conversation if it doesn't exist yet, and `timeout` and `reinit` apply to that creation.
107
+
108
+ `summarize()` throws a `SummaryError` when the service reports that it couldn't generate the summary. The service sends that failure inside a successful JSON-RPC result, so without the check it would look like an empty summary.
109
+
110
+ The client supports `await using`: `Symbol.asyncDispose` calls `close()`.
111
+
112
+ ### Errors
113
+
114
+ An error the service returns, a timeout and a response the client can't parse are each an `AIChatError`, with the JSON-RPC `code` (or `null`) and the service's message in `serverMessage`. A transport failure, such as a refused connection, is thrown as `fetch` threw it, usually a `TypeError`. These codes map to subclasses:
115
+
116
+ | Code | Error class |
117
+ |---|---|
118
+ | -32001 | `ConversationNotFoundError` |
119
+ | -32005, -32006 | `RateLimitError` |
120
+ | -32007 | `ChatInProgressError` |
121
+ | -32009 | `AuthenticationError` |
122
+ | none (summary failed) | `SummaryError` |
123
+
124
+ Other codes throw the base `AIChatError`. A body that isn't JSON throws `AIChatError` with the HTTP status as the code.
125
+
126
+ The client decides success from the JSON-RPC body, not the HTTP status. The service can send `200` before a slow turn finishes, so an error can arrive as `200` with an `error` object in the body.
127
+
128
+ ### Slow turns and the idle timeout
129
+
130
+ A `chat()` call waits for a full model turn, which takes seconds. The service sends whitespace ahead of a slow response so that proxies don't close the connection. Leading whitespace is valid JSON, so parsing isn't affected.
131
+
132
+ The client has no limit on the whole request. It has an idle timeout instead: `readIdleTimeoutSeconds` (default 60) bounds the wait for the response headers and each wait for the next body chunk. Every chunk restarts it, so a turn the service keeps alive runs as long as it needs. A connection that sends nothing for that long is aborted, and the call fails with an `AIChatError` whose code is `null`.
133
+
134
+ `rawPost()` returns the response with its body unread, and applies the idle timeout to each read. Use it to relay the body to another client without buffering it. You interpret the result yourself, including an error under HTTP 200. Read the body to the end or cancel it, so the connection is released. This Hono route relays a turn:
135
+
136
+ ```typescript
137
+ import { Hono } from 'hono';
138
+ import { AIChatClient } from '@signalwire/sdk';
139
+
140
+ const client = new AIChatClient();
141
+ const app = new Hono();
142
+
143
+ app.post('/relay', async (c) => {
144
+ const { id, message } = await c.req.json<{ id: string; message: string }>();
145
+ const upstream = await client.rawPost('chat', { id, message });
146
+ return new Response(upstream.body, {
147
+ status: upstream.status,
148
+ headers: { 'Content-Type': 'application/json' },
149
+ });
150
+ });
151
+ ```
152
+
153
+ A browser must not choose the conversation ID in a real relay, or it can continue anyone's conversation. `ChatGateway` solves that with signed handles.
154
+
155
+ ### Conversation IDs
156
+
157
+ `createConversation()` logs a `conversation_id_will_be_sanitized` warning when an ID contains a character other than letters, digits, `_`, `-`, `.` and `:`. The SDK's source records that the service removes such characters without reporting an error. The warning names the ID the service stores, because anything you file under the requested ID can't be found under the stored one.
158
+
159
+ Use `.` to compose IDs, such as `root.2` for the second leg of `root`. `_` and `-` appear in the IDs `ChatGateway` generates, and `:` separates fields inside a gateway handle.
160
+
161
+ ## ChatGateway
162
+
163
+ A chat widget runs in a page, and anything in the page is readable by every visitor. A SignalWire API token carries the whole project, and every chat turn is billed. `ChatGateway` holds the credential in your server and forwards requests on the widget's behalf:
164
+
165
+ ```text
166
+ browser --(publishable key)--> your app --(project:token)--> chat service
167
+ ```
168
+
169
+ The browser learns the gateway's URL and a publishable key. It doesn't learn the project, the space, the token, or which agent config runs. The gateway sends its own `config_url` on every call, so a key reaches only the agent it was issued for.
170
+
171
+ ### Mount the gateway
172
+
173
+ `router()` returns a Hono app that serves the gateway at its root. Mount it on your agent with `mount()`:
174
+
175
+ ```typescript
176
+ import { AgentBase, ChatGateway } from '@signalwire/sdk';
177
+
178
+ // SWML_PROXY_URL_BASE (https://support.example.com) is the agent's public URL.
179
+ const agent = new AgentBase({ name: 'support', route: '/' });
180
+
181
+ const gateway = new ChatGateway({
182
+ // The one agent this key reaches, with its basic-auth credentials in the
183
+ // URL, since the chat service fetches its SWML like any other client.
184
+ configUrl: agent.getFullUrl(true),
185
+ key: process.env['CHAT_WIDGET_KEY'], // what the widget carries
186
+ allowedOrigins: ['https://shop.example.com'], // localhost is always allowed
187
+ });
188
+
189
+ agent.mount(gateway.router(), { prefix: '/chat' });
190
+ await agent.serve();
191
+ ```
192
+
193
+ `mount()` takes the prefix from the host root, and keeps the mount when the agent rebuilds its app. A mounted app isn't behind the agent's basic auth, and the agent's CORS and CSRF middleware don't apply to it. The gateway answers its own preflights. Mount before calling `serve()`.
194
+
195
+ The gateway works on any Hono app too, with `app.route('/chat', gateway.router())`. Without a `client` option, the gateway builds an `AIChatClient` from the environment, so the constructor throws when `SIGNALWIRE_PROJECT_ID` or the service URL is missing. Pass `client` to supply your own; `close()` closes the client only when the gateway built it.
196
+
197
+ ### The wire protocol
198
+
199
+ The browser sends every request as `POST {prefix}` with a JSON body and the key in an `Authorization: Bearer` header. The body's `method` is `start`, `chat`, `log` or `end`, and defaults to `chat`. Any other method gets a `400`.
200
+
201
+ The first `chat` has no handle. The gateway creates a conversation ID, signs it into a handle, and returns the handle in the `X-Chat-Handle` response header:
202
+
203
+ ```http
204
+ POST /chat
205
+ Authorization: Bearer pk_live_example
206
+ Content-Type: application/json
207
+
208
+ {"message": "hi"}
209
+ ```
210
+
211
+ The response body is the chat service's JSON-RPC response, relayed as it arrives. This is a captured response, with the handle shortened:
212
+
213
+ ```http
214
+ HTTP/1.1 200 OK
215
+ X-Chat-Handle: Y2hhdC05aWxI...
216
+ Content-Type: application/json
217
+
218
+
219
+ {"jsonrpc":"2.0","result":{"response":"Your order ships tomorrow."},"id":"req-5"}
220
+ ```
221
+
222
+ The browser keeps the handle and sends it with every later request, as `{"handle": "...", "message": "..."}`. Two properties of the relayed body matter to a widget:
223
+
224
+ - A failed turn arrives as a JSON-RPC `error` object under HTTP 200, because the service commits the status before the turn finishes. Check the body for `error`.
225
+ - The body can start with whitespace; see [Streaming](#streaming).
226
+
227
+ The other methods return JSON the gateway builds:
228
+
229
+ | Method | Needs a handle | Service call | Response body |
230
+ |---|---|---|---|
231
+ | `start` | No (creates one) | `create_conversation`, no user message | `{ greeting, status, timeout }` |
232
+ | `chat` | No (creates one) | `chat` | The service's JSON-RPC response, relayed |
233
+ | `log` | Yes | `chat_log` | `{ messages, timeout, last_activity }` |
234
+ | `end` | Yes | `end_conversation` | `{ status: 'ended' }` |
235
+
236
+ `start` opens the conversation with no user message, so the agent speaks first. This is a captured `start` response from a gateway with `conversationTimeout: 1800`:
237
+
238
+ ```json
239
+ {"greeting":"Hi! How can I help?","status":"created","timeout":1800}
240
+ ```
241
+
242
+ `log` returns what a widget needs to redraw a conversation after a page reload. This is a captured response:
243
+
244
+ ```json
245
+ {
246
+ "messages": [
247
+ {"role": "assistant", "content": "Hi! How can I help?", "timestamp": 1786258737.147},
248
+ {"role": "user", "content": "where is my order?", "timestamp": 1786258812.004}
249
+ ],
250
+ "timeout": 1800,
251
+ "last_activity": 1786258813
252
+ }
253
+ ```
254
+
255
+ The response has three parts:
256
+
257
+ - `messages` holds user and assistant turns with text, and nothing else. The service's log also holds the system prompt, tool calls and tool results; the gateway drops them.
258
+ - `timeout` is the conversation's idle timeout: `conversationTimeout`, or the service default of 3600 seconds when it isn't set. The service's responses don't report the deadline, so the gateway does.
259
+ - `last_activity` is the time of the newest message of any role, so a widget can restart its idle clock where it was. It's `null` when no message has a time.
260
+
261
+ All times are epoch seconds. The service stores microseconds, and the gateway converts them.
262
+
263
+ ### Page context in user_meta_data
264
+
265
+ `start` and `chat` accept one field the gateway forwards instead of replacing: `user_meta_data`. It holds the page context a widget collects about itself, such as the page URL and title. This `start` request sends it:
266
+
267
+ ```http
268
+ POST /chat
269
+ Authorization: Bearer pk_live_example
270
+ Content-Type: application/json
271
+
272
+ {"method": "start", "user_meta_data": {"page": {"title": "Pricing", "url": "https://shop.example.com/pricing"}}}
273
+ ```
274
+
275
+ The gateway sends it to the service as `user_meta_data`. According to the Python SDK's gateway guide, the service passes it to the agent's config request under `params.user_meta_data`. The service reads it only when it creates the conversation. Metadata on later turns is accepted and not used, so the agent sees the page where the conversation started.
276
+
277
+ The browser writes this field, so treat it as the visitor's claim about themselves, never as authority. A page can put anything in it, including text aimed at your prompt. The gateway checks it before it counts a new conversation against the cap:
278
+
279
+ - A value that isn't a JSON object gets `400`.
280
+ - A value larger than `MAX_USER_METADATA_BYTES` (8192 bytes, serialized as compact JSON with non-ASCII characters counted as their `\u` escapes) gets `413`.
281
+ - An empty object is dropped.
282
+
283
+ The value stays under its own key, so it can't replace the conversation `id` or the `config_url` the gateway sets.
284
+
285
+ ### What the gateway protects, and what it doesn't
286
+
287
+ A publishable key is public: it's in the page. Plan for someone else holding it.
288
+
289
+ The key can't read other conversations. The browser never names a conversation: it presents a handle, which is the conversation ID and an expiry signed with HMAC-SHA256. The gateway checks the signature first and the expiry second, and refuses a bad handle with `403`. A handle can't be guessed or edited, and `log` returns only the dialogue of the handle's own conversation.
290
+
291
+ The key can start and continue conversations, and each turn costs money. The caps are the main control:
292
+
293
+ | Option | Default | Limits |
294
+ |---|---|---|
295
+ | `maxNewConversations` | 60 per `windowSeconds` (60) | How many conversations the gateway creates |
296
+ | `maxTurns` | 200 | `chat` turns in one conversation |
297
+
298
+ A cap that's hit returns `429`. `maxNewConversations` matters most: a leaked key used to open many one-turn conversations is billed for each opening turn, and a per-conversation limit wouldn't catch that.
299
+
300
+ The gateway protects these things:
301
+
302
+ - The API token, project and space stay on the server.
303
+ - A key reaches only its gateway's `configUrl`; the browser can't choose the agent.
304
+ - The key is compared in constant time, and a wrong or missing key gets `401`.
305
+ - A handle can't be forged or edited without the signing secret.
306
+ - The browser sees user and assistant text, not the system prompt or tool traffic.
307
+
308
+ These are the limits of that protection:
309
+
310
+ - **The key isn't user authentication.** Anyone with the page has it. The gateway doesn't know who the visitor is.
311
+ - **The origin allowlist is leak containment, not access control.** Browsers send the page's origin, so a key pasted into another site's page gets `403`. A request with no `Origin` header is allowed, because server-side callers send none. A script can also send any value it likes.
312
+ - **A handle is a bearer token until it expires.** Whoever holds it can continue, read (`log`) and end that conversation. `end` doesn't revoke it; it stays valid for `handleTtl` (24 hours by default).
313
+ - **The caps are counted in the process.** Behind several replicas, each keeps its own counts. The effective cap is the cap times the replica count, so put a shared limiter in front if that matters.
314
+ - **A refusal reason names its category.** A bad handle is reported as `invalid handle` or `expired handle`. A cap is reported as `too many new conversations` or `conversation turn limit reached`.
315
+
316
+ The gateway returns these statuses itself; everything else comes from the service:
317
+
318
+ | Status | Body `error` | Cause |
319
+ |---|---|---|
320
+ | 400 | `bad request`, `body must be an object`, `method not allowed`, `message is required`, `log requires a handle`, `end requires a handle`, `malformed handle`, `user_meta_data must be an object` | The request is malformed |
321
+ | 401 | `bad key` | The key is missing or wrong |
322
+ | 403 | `origin not allowed`, `invalid handle`, `expired handle` | The origin isn't allowed, or the handle doesn't verify |
323
+ | 413 | `request too large`, `message too large`, `user_meta_data too large` | The body, the message or `user_meta_data` is over its size limit |
324
+ | 429 | `too many new conversations`, `conversation turn limit reached` | A cap was hit |
325
+ | 502 | `chat service error` | The service call failed before any of the reply was sent |
326
+
327
+ A `start`, `log` or `end` whose service call returns a JSON-RPC error also gets `502`, because the gateway reads those results itself.
328
+
329
+ ### Size limits
330
+
331
+ Whoever holds the key chooses how large each request is, so the gateway limits every part of it and answers `413` past the limit:
332
+
333
+ | Limit | Constant | When it's checked |
334
+ |---|---|---|
335
+ | 64 KiB request body | `MAX_REQUEST_BODY_BYTES` | Before the body is parsed |
336
+ | 8 KiB chat message, UTF-8 | `MAX_MESSAGE_BYTES` | Before a conversation is created or a turn counted |
337
+ | 8 KiB `user_meta_data`, serialized | `MAX_USER_METADATA_BYTES` | Before a conversation is created |
338
+
339
+ The three constants are exported from `@signalwire/sdk`. The body limit leaves room for a full message and a full metadata bag, even when JSON escaping triples the size of non-ASCII text. A body whose `Content-Length` is over the limit is refused before any of it is read. A body sent without a `Content-Length` is counted as it arrives and dropped once it passes the limit. If your own middleware reads the body first, with `c.req.json()` or another `c.req` method, the routes read it from Hono's cache and apply the same limit to it. The error names the limit that was hit: `request too large`, `message too large` or `user_meta_data too large`.
340
+
341
+ `HandoffRouter` applies the same limits to its routes. `/handoff`, `/escalate` and `/say` refuse a body over 64 KiB, and `/say` refuses text over 8 KiB. Both checks come before the nonce is looked up, so the answer says nothing about whether a nonce is live.
342
+
343
+ ### CORS
344
+
345
+ The allowlist also sets the CORS headers. An allowed origin gets `Access-Control-Allow-Origin` with its own value, `Access-Control-Expose-Headers: X-Chat-Handle` and `Vary: Origin` on every response, refusals included. A preflight (`OPTIONS`) from an allowed origin gets `204` with `Access-Control-Allow-Headers: Authorization, Content-Type`, `Access-Control-Allow-Methods: POST, OPTIONS` and `Access-Control-Max-Age: 600`. Any other origin gets no CORS headers.
346
+
347
+ Origins are compared as whole strings, without a trailing slash, so `https://shop.example.com.evil.test` doesn't match `https://shop.example.com`. The hosts `localhost`, `127.0.0.1` and `::1`, and any host that ends in `.localhost`, are always allowed, on any port and scheme.
348
+
349
+ ### Streaming
350
+
351
+ The gateway relays a `chat` response body without buffering it. The service pads a slow turn with whitespace so that proxies don't close the connection. A relay that waited for the whole body would hold the padding back and bring the timeout into your own stack.
352
+
353
+ That's why a new handle comes back in a header. Headers go out before the body, so the widget has its handle without waiting for the turn. If you put another proxy in front of the gateway, make sure it doesn't buffer responses either. The client's idle timeout applies to each read of the relayed body.
354
+
355
+ ### Rotate a key
356
+
357
+ The key has no expiry, because it lives in a static page. To rotate it, construct the gateway with a new `key` and redeploy. To invalidate outstanding handles too, change `secret` at the same time.
358
+
359
+ ### Gateway reference
360
+
361
+ The constructor takes a `ChatGatewayOptions` object. Only `configUrl` is required:
362
+
363
+ | Option | Default | Description |
364
+ |---|---|---|
365
+ | `configUrl` | none | The agent config every call uses. The constructor throws when it's empty. |
366
+ | `key` | `SIGNALWIRE_CHAT_GATEWAY_KEY`, else a generated `pk_` key | The publishable key. A generated key is useful only to a process that also serves the page. |
367
+ | `allowedOrigins` | `[]` | Origins allowed besides localhost |
368
+ | `client` | Built from the environment | The `AIChatClient` to forward with |
369
+ | `secret` | `SIGNALWIRE_CHAT_GATEWAY_SECRET`, else 32 random bytes | The HMAC key for handles. A random secret invalidates handles on restart and across replicas. |
370
+ | `handleTtl` | 86400 | Seconds a handle stays valid |
371
+ | `conversationTimeout` | `null` (the service default, 3600) | Idle seconds before the service ends a conversation, sent on `start` and `chat` |
372
+ | `maxNewConversations` | 60 | New conversations per window |
373
+ | `maxTurns` | 200 | `chat` turns per conversation |
374
+ | `windowSeconds` | 60 | The window for `maxNewConversations` |
375
+
376
+ The gateway also has methods for use outside Hono, or for server-side handles:
377
+
378
+ | Member | Description |
379
+ |---|---|
380
+ | `router()` | The Hono app to mount |
381
+ | `prepare(body, { origin, key })` | Checks a request and returns `[method, params, mintedHandle]`, the service call to make |
382
+ | `mintHandle(conversationId?)` | Signs a handle, for a new random ID when none is given |
383
+ | `readHandle(handle)` | Returns the conversation ID, or throws a `GatewayRejection` |
384
+ | `checkKey(key)`, `checkOrigin(origin)` | The key and origin checks, which throw a `GatewayRejection` |
385
+ | `readUserMetadata(body)` | The `user_meta_data` check |
386
+ | `ChatGateway.visibleMessages(messages)` | The dialogue a browser may see |
387
+ | `ChatGateway.lastActivity(messages)` | Epoch seconds of the newest message, or `null` |
388
+ | `effectiveTimeout` | `conversationTimeout`, or 3600 when it isn't set |
389
+ | `close()` | Closes the client, if the gateway built it |
390
+
391
+ A `GatewayRejection` has `status` (400, 401, 403, 413 or 429) and `reason`, the text sent to the browser.
392
+
393
+ ## HandoffRouter
394
+
395
+ `HandoffRouter` serves three routes a browser client uses beside a `ChatGateway`. The SignalWire address widget calls them at `{gateway-url}/handoff`, `{gateway-url}/escalate` and `{gateway-url}/say`, and sends `handoff_nonce` and `chat_handle` as user variables when it places a call.
396
+
397
+ The router implements the wire contract: the routes, the nonce, the ordering guarantee and the per-call limit. Your application supplies the rest as callbacks, such as where a leg's transcript is written and how a call is ended.
398
+
399
+ ### Register a call's nonce
400
+
401
+ A browser can't be trusted to name a call. Sending text into a call needs its call ID, and a page that could supply one could send speech into someone else's call. Instead, the browser puts a random `handoff_nonce` in the user variables of the call it places. Your agent's per-call configuration registers that nonce against the call ID from the platform's request. Later, presenting the nonce shows that the browser placed that call.
402
+
403
+ This example mounts both routers at the same prefix and registers each call's nonce. It uses the REST client to end calls and to send text into them:
404
+
405
+ ```typescript
406
+ import { AgentBase, ChatGateway, HandoffRouter, restClient, userVariables } from '@signalwire/sdk';
407
+
408
+ // Your code: resolve true once the leg's transcript is stored.
409
+ declare function waitForRecord(conversationId: string, medium: string): Promise<boolean>;
410
+
411
+ const agent = new AgentBase({ name: 'support', route: '/' });
412
+ const gateway = new ChatGateway({
413
+ configUrl: agent.getFullUrl(true),
414
+ allowedOrigins: ['https://shop.example.com'],
415
+ });
416
+ const rest = restClient();
417
+
418
+ const handoff = new HandoffRouter({
419
+ gateway,
420
+ captureLeg: (conversationId, medium) => waitForRecord(conversationId, medium),
421
+ endCall: async (callId) => {
422
+ await rest.calling.end(callId);
423
+ },
424
+ sendMessage: async (callId, text) => {
425
+ await rest.calling.aiMessage(callId, { role: 'user', message_text: text });
426
+ return true;
427
+ },
428
+ });
429
+
430
+ agent.addPerCallConfig((_query, body) => {
431
+ const vars = userVariables(body);
432
+ const nonce = vars['handoff_nonce'];
433
+ const callId = body.call?.call_id;
434
+ if (typeof nonce !== 'string' || !callId) return;
435
+
436
+ // A call started from a chat continues that conversation as its next leg.
437
+ let conversationId = callId;
438
+ const chatHandle = vars['chat_handle'];
439
+ if (typeof chatHandle === 'string') {
440
+ try {
441
+ conversationId = handoff.nextConversationId(gateway.readHandle(chatHandle));
442
+ } catch {
443
+ // Not a handle this gateway issued: treat the call as a new conversation.
444
+ }
445
+ }
446
+ handoff.register(nonce, { conversationId, callId });
447
+ });
448
+
449
+ agent.mount(gateway.router(), { prefix: '/chat' });
450
+ agent.mount(handoff.router(), { prefix: '/chat' });
451
+ await agent.serve();
452
+ ```
453
+
454
+ Take `callId` from the request the platform sent, never from anything the browser supplied. The callback runs on every config request for the call, so registering a nonce again changes nothing: the first registration's call, time and message count stand, and a nonce that `/handoff` has used stays used until it would have expired. `restClient()` reads `SIGNALWIRE_PROJECT_ID`, `SIGNALWIRE_API_TOKEN` and `SIGNALWIRE_SPACE`. `calling.end()` sends the `calling.end` command, and `calling.aiMessage()` sends `calling.ai_message`.
455
+
456
+ ### Routes
457
+
458
+ Each route takes a JSON body. The browser derives all three paths from the gateway's URL, so mount the router at the gateway's prefix:
459
+
460
+ | Route | Body | Success | What it does |
461
+ |---|---|---|---|
462
+ | `POST /handoff` | `{ nonce }` | `200 { handle }` | Ends the call, waits for its record, and returns a handle for the next leg as a chat. Uses up the nonce. |
463
+ | `POST /escalate` | `{ handle }` | `200 { ok: true }` | Waits for the chat leg's record, before the browser places a call |
464
+ | `POST /say` | `{ nonce, text }` | `200 { ok: true }` | Sends the trimmed text to the nonce's call with `sendMessage` |
465
+
466
+ These routes return errors:
467
+
468
+ - `403 { error: 'origin not allowed' }` for an origin the gateway doesn't allow, on every route.
469
+ - `404 { error: 'not found' }` when a nonce or handle doesn't verify. An unknown, expired or used nonce gets the same answer, so the routes can't be used to learn whether a call is live.
470
+ - `404` from `/say` also when typing is off (no `sendMessage`), the text is empty, the call's limit is reached, or `sendMessage` threw or returned `false`.
471
+ - `400 { error: 'bad request' }` from `/escalate` when `handle` is missing.
472
+ - `413 { error: 'request too large' }` for a body over `MAX_REQUEST_BODY_BYTES` (64 KiB), on every route, and `413 { error: 'message too large' }` from `/say` for text over `MAX_MESSAGE_BYTES` (8 KiB of UTF-8). Both are checked before the nonce is looked up. `say()` called directly also returns `false` for text over the limit. For more information, see [Size limits](#size-limits).
473
+
474
+ These are captured responses from the three routes, with the handle shortened:
475
+
476
+ ```text
477
+ POST /chat/say {"nonce":"nonce-1","text":" hello "} 200 {"ok":true}
478
+ POST /chat/handoff {"nonce":"nonce-1"} 200 {"handle":"Y2hhdC1hYmMuMToxNzkw..."}
479
+ POST /chat/handoff {"nonce":"nonce-1"} 404 {"error":"not found"}
480
+ POST /chat/say {"nonce":"nonce-1","text":"hello"} 404 {"error":"not found"}
481
+ POST /chat/escalate {} 400 {"error":"bad request"}
482
+ ```
483
+
484
+ The last two lines show that a redeemed nonce no longer works for `/say` either.
485
+
486
+ Each route answers its own `OPTIONS` preflight. An origin the gateway allows gets `Access-Control-Allow-Origin` and `Vary: Origin` on every response; its preflight also gets `Access-Control-Allow-Headers: Content-Type`, `Access-Control-Allow-Methods: POST, OPTIONS` and `Access-Control-Max-Age: 600`.
487
+
488
+ The default `nextConversationId` names legs with a dot: `root` becomes `root.1`, and `root.1` becomes `root.2`. An ended conversation can't be reopened, so each leg needs a new ID.
489
+
490
+ ### The ordering guarantee
491
+
492
+ A medium doesn't start until the one it replaces has ended and its record is written. Without the wait, the new leg's config request can run before the record exists, and the new leg starts with no history.
493
+
494
+ `/handoff` calls `endCall(callId)`, then `captureLeg(conversationId, 'voice')`, and issues the handle after that. `/escalate` calls `captureLeg(conversationId, 'chat')` and answers after it. `captureLeg` should return `true` once the record is written.
495
+
496
+ The wait has limits:
497
+
498
+ - It lasts at most `captureTimeout` seconds (8 by default). After that, or if `captureLeg` throws, the router logs a warning and continues without the record.
499
+ - Without `captureLeg`, nothing waits, and the guarantee doesn't hold.
500
+ - A failing `endCall` is logged, and the handoff continues.
501
+
502
+ ### What the nonce protects, and what it doesn't
503
+
504
+ `/handoff` and `/say` check a nonce, and `/escalate` checks a handle; all three check the origin. None of them checks the publishable key.
505
+
506
+ The nonce protects these things:
507
+
508
+ - A browser can send text only into the call its nonce was registered for. `/say` finds the call by nonce and forwards only the text, never a call ID or `global_data` from the request.
509
+ - `/handoff` works once per nonce. The nonce is used up before the call is ended, even if a later step fails.
510
+ - Registering a nonce again doesn't reset its message count, revive it after `/handoff`, or move it to another call.
511
+ - A browser can switch to a chat leg only with a nonce from its own call.
512
+
513
+ These are the limits of that protection:
514
+
515
+ - **A nonce is a bearer secret.** Whoever holds it can type into the call and take over the conversation through `/handoff`. It's as strong as the random value the browser generates.
516
+ - **Typing lasts until the nonce is redeemed or expires.** `nonceTtl` (3600 seconds by default) counts from registration, not from the last message. After that, or after `/handoff`, `/say` returns `404` even when the call is still live.
517
+ - **Each typed message is a billed turn.** `maxMessagesPerCall` (200 by default) caps them per nonce. A message that isn't delivered doesn't count.
518
+ - **The nonce table is in the process.** A redemption must reach the replica that registered the nonce. Run one replica, route calls to the same replica, or pass a `registry` backed by shared storage.
519
+ - **A shared `registry` isn't atomic across replicas.** Within one process, registration, redemption and taking a typing slot each read the table and write it back without waiting in between, so overlapping requests can't redeem a nonce twice or pass the typing cap. When replicas share a `registry`, another replica can write between that read and write, so a nonce can be redeemed once by each replica and the typing cap can be passed. The `registry` is a plain `Map`, so the SDK can't make those steps atomic across replicas. Use one nonce table, or route each call's requests to one replica.
520
+ - **A handle is enough for `/escalate`.** It triggers your `captureLeg` for the chat leg, so make `captureLeg` safe to run more than once.
521
+
522
+ ### HandoffRouter reference
523
+
524
+ The constructor takes a `HandoffRouterOptions` object. Only `gateway` is required:
525
+
526
+ | Option | Default | Description |
527
+ |---|---|---|
528
+ | `gateway` | none | The `ChatGateway` that issues and reads handles and checks origins |
529
+ | `captureLeg` | none | `(conversationId, medium) => boolean \| Promise<boolean>`: ends a leg and writes its record; `medium` is `voice` or `chat` |
530
+ | `endCall` | none | `(callId) => void \| Promise<void>`: hangs the call up |
531
+ | `sendMessage` | none | `(callId, text) => boolean \| Promise<boolean>`: sends typed text into the call. Without it, `/say` returns 404. |
532
+ | `nextConversationId` | Appends `.N` | The ID of the next leg |
533
+ | `nonceTtl` | 3600 | Seconds a nonce stays usable, from registration |
534
+ | `maxMessagesPerCall` | 200 | Typed messages per nonce |
535
+ | `captureTimeout` | 8 | Seconds to wait for `captureLeg` |
536
+ | `registry` | A new `Map` | The nonce table, a `Map<string, NonceEntry>`. It may return copies of its entries: the router writes every change back with `set()`. |
537
+
538
+ The router's methods are `router()`, `register(nonce, { conversationId, callId })`, `redeem(nonce)`, `escalate(handle)` and `say(nonce, text)`. `redeem()` returns the new handle or `null`; `escalate()` and `say()` return `true` on success.
539
+
540
+ ## Running more than one replica
541
+
542
+ The three classes keep some state in the process. This table lists what each replica needs:
543
+
544
+ | State | Where it lives | Across replicas and restarts |
545
+ |---|---|---|
546
+ | Handle signing secret | `secret` or `SIGNALWIRE_CHAT_GATEWAY_SECRET` | Set the same value everywhere, or handles from one replica fail on another and after a restart |
547
+ | Publishable key | `key` or `SIGNALWIRE_CHAT_GATEWAY_KEY` | Set the same value everywhere; a generated key differs per process |
548
+ | Conversation and turn caps | Each gateway's memory | Counted per replica |
549
+ | Handoff nonces | `registry` | Pass a shared `registry`, or route a call's requests to one replica |
550
+
551
+ The agent's own tool tokens have the same requirement: set `swaigSecret` or `SIGNALWIRE_SWAIG_SECRET`. For more information, see the [security guide](security.md).
552
+
553
+ ## Related documentation
554
+
555
+ For more information, see these documents:
556
+
557
+ - [Agent guide](agent-guide.md): `mount()`, `addPerCallConfig()` and the agent routes
558
+ - [Configuration reference](configuration.md): the AI Chat environment variables
559
+ - [Security guide](security.md): basic auth, tool tokens and webhook signatures
560
+ - [REST client guide](../rest/docs/guide.md): the `calling` commands used to end calls and send text