@signalwire/sdk 2.0.1 → 2.0.2

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 (610) hide show
  1. package/dist/AgentBase.d.ts +1045 -0
  2. package/dist/AgentBase.js +2375 -0
  3. package/dist/AgentBase.js.map +1 -0
  4. package/dist/AgentServer.d.ts +146 -0
  5. package/dist/AgentServer.js +388 -0
  6. package/dist/AgentServer.js.map +1 -0
  7. package/dist/AuthHandler.d.ts +127 -0
  8. package/dist/AuthHandler.js +212 -0
  9. package/dist/AuthHandler.js.map +1 -0
  10. package/dist/ConfigLoader.d.ts +170 -0
  11. package/dist/ConfigLoader.js +393 -0
  12. package/dist/ConfigLoader.js.map +1 -0
  13. package/dist/ContextBuilder.d.ts +652 -0
  14. package/dist/ContextBuilder.js +1115 -0
  15. package/dist/ContextBuilder.js.map +1 -0
  16. package/dist/DataMap.d.ts +271 -0
  17. package/dist/DataMap.js +430 -0
  18. package/dist/DataMap.js.map +1 -0
  19. package/dist/FunctionResult.d.ts +481 -0
  20. package/dist/FunctionResult.js +775 -0
  21. package/dist/FunctionResult.js.map +1 -0
  22. package/dist/Logger.d.ts +113 -0
  23. package/dist/Logger.js +320 -0
  24. package/dist/Logger.js.map +1 -0
  25. package/dist/PomBuilder.d.ts +208 -0
  26. package/dist/PomBuilder.js +409 -0
  27. package/dist/PomBuilder.js.map +1 -0
  28. package/dist/PromptManager.d.ts +85 -0
  29. package/dist/PromptManager.js +108 -0
  30. package/dist/PromptManager.js.map +1 -0
  31. package/dist/SWMLHandler.d.ts +159 -0
  32. package/dist/SWMLHandler.js +229 -0
  33. package/dist/SWMLHandler.js.map +1 -0
  34. package/dist/SWMLService.d.ts +326 -0
  35. package/dist/SWMLService.js +610 -0
  36. package/dist/SWMLService.js.map +1 -0
  37. package/dist/SchemaUtils.d.ts +108 -0
  38. package/dist/SchemaUtils.js +317 -0
  39. package/dist/SchemaUtils.js.map +1 -0
  40. package/dist/SecurityUtils.d.ts +60 -0
  41. package/{src/SecurityUtils.ts → dist/SecurityUtils.js} +82 -83
  42. package/dist/SecurityUtils.js.map +1 -0
  43. package/dist/ServerlessAdapter.d.ts +119 -0
  44. package/dist/ServerlessAdapter.js +188 -0
  45. package/dist/ServerlessAdapter.js.map +1 -0
  46. package/dist/SessionManager.d.ts +142 -0
  47. package/dist/SessionManager.js +260 -0
  48. package/dist/SessionManager.js.map +1 -0
  49. package/dist/SslConfig.d.ts +77 -0
  50. package/dist/SslConfig.js +100 -0
  51. package/dist/SslConfig.js.map +1 -0
  52. package/dist/SwaigFunction.d.ts +159 -0
  53. package/dist/SwaigFunction.js +209 -0
  54. package/dist/SwaigFunction.js.map +1 -0
  55. package/dist/SwmlBuilder.d.ts +165 -0
  56. package/dist/SwmlBuilder.js +247 -0
  57. package/dist/SwmlBuilder.js.map +1 -0
  58. package/dist/SwmlVerbMethods.generated.d.ts +254 -0
  59. package/dist/SwmlVerbMethods.generated.js +9 -0
  60. package/dist/SwmlVerbMethods.generated.js.map +1 -0
  61. package/dist/TypeInference.d.ts +71 -0
  62. package/dist/TypeInference.js +164 -0
  63. package/dist/TypeInference.js.map +1 -0
  64. package/dist/WebService.d.ts +148 -0
  65. package/dist/WebService.js +532 -0
  66. package/dist/WebService.js.map +1 -0
  67. package/dist/cli/agent-loader.d.ts +22 -0
  68. package/dist/cli/agent-loader.js +144 -0
  69. package/dist/cli/agent-loader.js.map +1 -0
  70. package/dist/cli/mock-data.d.ts +37 -0
  71. package/dist/cli/mock-data.js +80 -0
  72. package/dist/cli/mock-data.js.map +1 -0
  73. package/dist/cli/swaig-test.d.ts +32 -0
  74. package/dist/cli/swaig-test.js +418 -0
  75. package/dist/cli/swaig-test.js.map +1 -0
  76. package/dist/generateVerbTypes.d.ts +11 -0
  77. package/dist/generateVerbTypes.js +265 -0
  78. package/dist/generateVerbTypes.js.map +1 -0
  79. package/{src/index.ts → dist/index.d.ts} +13 -100
  80. package/dist/index.js +152 -0
  81. package/dist/index.js.map +1 -0
  82. package/dist/livewire/index.d.ts +653 -0
  83. package/dist/livewire/index.js +992 -0
  84. package/dist/livewire/index.js.map +1 -0
  85. package/dist/prefabs/ConciergeAgent.d.ts +89 -0
  86. package/dist/prefabs/ConciergeAgent.js +245 -0
  87. package/dist/prefabs/ConciergeAgent.js.map +1 -0
  88. package/dist/prefabs/FAQBotAgent.d.ts +113 -0
  89. package/dist/prefabs/FAQBotAgent.js +329 -0
  90. package/dist/prefabs/FAQBotAgent.js.map +1 -0
  91. package/dist/prefabs/InfoGathererAgent.d.ts +126 -0
  92. package/dist/prefabs/InfoGathererAgent.js +287 -0
  93. package/dist/prefabs/InfoGathererAgent.js.map +1 -0
  94. package/dist/prefabs/ReceptionistAgent.d.ts +104 -0
  95. package/dist/prefabs/ReceptionistAgent.js +303 -0
  96. package/dist/prefabs/ReceptionistAgent.js.map +1 -0
  97. package/dist/prefabs/SurveyAgent.d.ts +148 -0
  98. package/dist/prefabs/SurveyAgent.js +540 -0
  99. package/dist/prefabs/SurveyAgent.js.map +1 -0
  100. package/{src/prefabs/index.ts → dist/prefabs/index.d.ts} +1 -15
  101. package/dist/prefabs/index.js +14 -0
  102. package/dist/prefabs/index.js.map +1 -0
  103. package/dist/relay/Action.d.ts +258 -0
  104. package/dist/relay/Action.js +402 -0
  105. package/dist/relay/Action.js.map +1 -0
  106. package/dist/relay/Call.d.ts +697 -0
  107. package/dist/relay/Call.js +1062 -0
  108. package/dist/relay/Call.js.map +1 -0
  109. package/dist/relay/Deferred.d.ts +44 -0
  110. package/dist/relay/Deferred.js +69 -0
  111. package/dist/relay/Deferred.js.map +1 -0
  112. package/dist/relay/Message.d.ts +103 -0
  113. package/dist/relay/Message.js +169 -0
  114. package/dist/relay/Message.js.map +1 -0
  115. package/dist/relay/RelayClient.d.ts +302 -0
  116. package/dist/relay/RelayClient.js +1019 -0
  117. package/dist/relay/RelayClient.js.map +1 -0
  118. package/dist/relay/RelayError.d.ts +15 -0
  119. package/dist/relay/RelayError.js +20 -0
  120. package/dist/relay/RelayError.js.map +1 -0
  121. package/dist/relay/RelayEvent.d.ts +254 -0
  122. package/dist/relay/RelayEvent.js +509 -0
  123. package/dist/relay/RelayEvent.js.map +1 -0
  124. package/dist/relay/constants.d.ts +90 -0
  125. package/{src/relay/constants.ts → dist/relay/constants.js} +11 -29
  126. package/dist/relay/constants.js.map +1 -0
  127. package/dist/relay/index.d.ts +16 -0
  128. package/dist/relay/index.js +18 -0
  129. package/dist/relay/index.js.map +1 -0
  130. package/dist/relay/types.d.ts +142 -0
  131. package/dist/relay/types.js +5 -0
  132. package/dist/relay/types.js.map +1 -0
  133. package/dist/rest/HttpClient.d.ts +80 -0
  134. package/dist/rest/HttpClient.js +148 -0
  135. package/dist/rest/HttpClient.js.map +1 -0
  136. package/dist/rest/RestError.d.ts +30 -0
  137. package/dist/rest/RestError.js +39 -0
  138. package/dist/rest/RestError.js.map +1 -0
  139. package/dist/rest/base/BaseResource.d.ts +24 -0
  140. package/dist/rest/base/BaseResource.js +29 -0
  141. package/dist/rest/base/BaseResource.js.map +1 -0
  142. package/dist/rest/base/CrudResource.d.ts +68 -0
  143. package/dist/rest/base/CrudResource.js +82 -0
  144. package/dist/rest/base/CrudResource.js.map +1 -0
  145. package/dist/rest/base/CrudWithAddresses.d.ts +22 -0
  146. package/dist/rest/base/CrudWithAddresses.js +25 -0
  147. package/dist/rest/base/CrudWithAddresses.js.map +1 -0
  148. package/dist/rest/index.d.ts +131 -0
  149. package/{src/rest/index.ts → dist/rest/index.js} +101 -136
  150. package/dist/rest/index.js.map +1 -0
  151. package/dist/rest/namespaces/addresses.d.ts +46 -0
  152. package/dist/rest/namespaces/addresses.js +55 -0
  153. package/dist/rest/namespaces/addresses.js.map +1 -0
  154. package/dist/rest/namespaces/calling.d.ts +382 -0
  155. package/dist/rest/namespaces/calling.js +478 -0
  156. package/dist/rest/namespaces/calling.js.map +1 -0
  157. package/dist/rest/namespaces/chat.d.ts +22 -0
  158. package/dist/rest/namespaces/chat.js +26 -0
  159. package/dist/rest/namespaces/chat.js.map +1 -0
  160. package/dist/rest/namespaces/compat.d.ts +585 -0
  161. package/dist/rest/namespaces/compat.js +735 -0
  162. package/dist/rest/namespaces/compat.js.map +1 -0
  163. package/dist/rest/namespaces/datasphere.d.ts +66 -0
  164. package/dist/rest/namespaces/datasphere.js +77 -0
  165. package/dist/rest/namespaces/datasphere.js.map +1 -0
  166. package/dist/rest/namespaces/fabric.d.ts +282 -0
  167. package/dist/rest/namespaces/fabric.js +373 -0
  168. package/dist/rest/namespaces/fabric.js.map +1 -0
  169. package/dist/rest/namespaces/imported-numbers.d.ts +22 -0
  170. package/dist/rest/namespaces/imported-numbers.js +26 -0
  171. package/dist/rest/namespaces/imported-numbers.js.map +1 -0
  172. package/dist/rest/namespaces/logs.d.ts +105 -0
  173. package/dist/rest/namespaces/logs.js +133 -0
  174. package/dist/rest/namespaces/logs.js.map +1 -0
  175. package/dist/rest/namespaces/lookup.d.ts +29 -0
  176. package/dist/rest/namespaces/lookup.js +32 -0
  177. package/dist/rest/namespaces/lookup.js.map +1 -0
  178. package/dist/rest/namespaces/mfa.d.ts +46 -0
  179. package/dist/rest/namespaces/mfa.js +54 -0
  180. package/dist/rest/namespaces/mfa.js.map +1 -0
  181. package/dist/rest/namespaces/number-groups.d.ts +49 -0
  182. package/dist/rest/namespaces/number-groups.js +58 -0
  183. package/dist/rest/namespaces/number-groups.js.map +1 -0
  184. package/dist/rest/namespaces/phone-numbers.d.ts +60 -0
  185. package/dist/rest/namespaces/phone-numbers.js +67 -0
  186. package/dist/rest/namespaces/phone-numbers.js.map +1 -0
  187. package/dist/rest/namespaces/project.d.ts +46 -0
  188. package/dist/rest/namespaces/project.js +56 -0
  189. package/dist/rest/namespaces/project.js.map +1 -0
  190. package/dist/rest/namespaces/pubsub.d.ts +22 -0
  191. package/dist/rest/namespaces/pubsub.js +26 -0
  192. package/dist/rest/namespaces/pubsub.js.map +1 -0
  193. package/dist/rest/namespaces/queues.d.ts +42 -0
  194. package/dist/rest/namespaces/queues.js +49 -0
  195. package/dist/rest/namespaces/queues.js.map +1 -0
  196. package/dist/rest/namespaces/recordings.d.ts +38 -0
  197. package/dist/rest/namespaces/recordings.js +45 -0
  198. package/dist/rest/namespaces/recordings.js.map +1 -0
  199. package/dist/rest/namespaces/registry.d.ts +141 -0
  200. package/dist/rest/namespaces/registry.js +178 -0
  201. package/dist/rest/namespaces/registry.js.map +1 -0
  202. package/dist/rest/namespaces/short-codes.d.ts +39 -0
  203. package/dist/rest/namespaces/short-codes.js +46 -0
  204. package/dist/rest/namespaces/short-codes.js.map +1 -0
  205. package/dist/rest/namespaces/sip-profile.d.ts +28 -0
  206. package/dist/rest/namespaces/sip-profile.js +34 -0
  207. package/dist/rest/namespaces/sip-profile.js.map +1 -0
  208. package/dist/rest/namespaces/verified-callers.d.ts +33 -0
  209. package/dist/rest/namespaces/verified-callers.js +39 -0
  210. package/dist/rest/namespaces/verified-callers.js.map +1 -0
  211. package/dist/rest/namespaces/video.d.ts +235 -0
  212. package/dist/rest/namespaces/video.js +297 -0
  213. package/dist/rest/namespaces/video.js.map +1 -0
  214. package/{src/rest/pagination.ts → dist/rest/pagination.d.ts} +2 -61
  215. package/dist/rest/pagination.js +78 -0
  216. package/dist/rest/pagination.js.map +1 -0
  217. package/dist/rest/types.d.ts +54 -0
  218. package/dist/rest/types.js +5 -0
  219. package/dist/rest/types.js.map +1 -0
  220. package/dist/skills/SkillBase.d.ts +404 -0
  221. package/dist/skills/SkillBase.js +471 -0
  222. package/dist/skills/SkillBase.js.map +1 -0
  223. package/dist/skills/SkillManager.d.ts +195 -0
  224. package/dist/skills/SkillManager.js +378 -0
  225. package/dist/skills/SkillManager.js.map +1 -0
  226. package/dist/skills/SkillRegistry.d.ts +176 -0
  227. package/dist/skills/SkillRegistry.js +310 -0
  228. package/dist/skills/SkillRegistry.js.map +1 -0
  229. package/dist/skills/builtin/api_ninjas_trivia.d.ts +47 -0
  230. package/dist/skills/builtin/api_ninjas_trivia.js +211 -0
  231. package/dist/skills/builtin/api_ninjas_trivia.js.map +1 -0
  232. package/dist/skills/builtin/ask_claude.d.ts +37 -0
  233. package/dist/skills/builtin/ask_claude.js +162 -0
  234. package/dist/skills/builtin/ask_claude.js.map +1 -0
  235. package/dist/skills/builtin/claude_skills.d.ts +75 -0
  236. package/dist/skills/builtin/claude_skills.js +753 -0
  237. package/dist/skills/builtin/claude_skills.js.map +1 -0
  238. package/dist/skills/builtin/custom_skills.d.ts +79 -0
  239. package/dist/skills/builtin/custom_skills.js +227 -0
  240. package/dist/skills/builtin/custom_skills.js.map +1 -0
  241. package/dist/skills/builtin/datasphere.d.ts +73 -0
  242. package/dist/skills/builtin/datasphere.js +350 -0
  243. package/dist/skills/builtin/datasphere.js.map +1 -0
  244. package/dist/skills/builtin/datasphere_serverless.d.ts +89 -0
  245. package/dist/skills/builtin/datasphere_serverless.js +291 -0
  246. package/dist/skills/builtin/datasphere_serverless.js.map +1 -0
  247. package/dist/skills/builtin/datetime.d.ts +40 -0
  248. package/dist/skills/builtin/datetime.js +118 -0
  249. package/dist/skills/builtin/datetime.js.map +1 -0
  250. package/dist/skills/builtin/google_maps.d.ts +48 -0
  251. package/dist/skills/builtin/google_maps.js +470 -0
  252. package/dist/skills/builtin/google_maps.js.map +1 -0
  253. package/dist/skills/builtin/index.d.ts +31 -0
  254. package/{src/skills/builtin/index.ts → dist/skills/builtin/index.js} +30 -36
  255. package/dist/skills/builtin/index.js.map +1 -0
  256. package/dist/skills/builtin/info_gatherer.d.ts +115 -0
  257. package/dist/skills/builtin/info_gatherer.js +328 -0
  258. package/dist/skills/builtin/info_gatherer.js.map +1 -0
  259. package/dist/skills/builtin/joke.d.ts +41 -0
  260. package/dist/skills/builtin/joke.js +156 -0
  261. package/dist/skills/builtin/joke.js.map +1 -0
  262. package/dist/skills/builtin/math.d.ts +39 -0
  263. package/dist/skills/builtin/math.js +119 -0
  264. package/dist/skills/builtin/math.js.map +1 -0
  265. package/dist/skills/builtin/mcp_gateway.d.ts +82 -0
  266. package/dist/skills/builtin/mcp_gateway.js +574 -0
  267. package/dist/skills/builtin/mcp_gateway.js.map +1 -0
  268. package/dist/skills/builtin/native_vector_search.d.ts +128 -0
  269. package/dist/skills/builtin/native_vector_search.js +752 -0
  270. package/dist/skills/builtin/native_vector_search.js.map +1 -0
  271. package/dist/skills/builtin/play_background_file.d.ts +59 -0
  272. package/dist/skills/builtin/play_background_file.js +274 -0
  273. package/dist/skills/builtin/play_background_file.js.map +1 -0
  274. package/dist/skills/builtin/spider.d.ts +91 -0
  275. package/dist/skills/builtin/spider.js +758 -0
  276. package/dist/skills/builtin/spider.js.map +1 -0
  277. package/dist/skills/builtin/swml_transfer.d.ts +66 -0
  278. package/dist/skills/builtin/swml_transfer.js +475 -0
  279. package/dist/skills/builtin/swml_transfer.js.map +1 -0
  280. package/dist/skills/builtin/weather_api.d.ts +59 -0
  281. package/dist/skills/builtin/weather_api.js +196 -0
  282. package/dist/skills/builtin/weather_api.js.map +1 -0
  283. package/dist/skills/builtin/web_search.d.ts +160 -0
  284. package/dist/skills/builtin/web_search.js +894 -0
  285. package/dist/skills/builtin/web_search.js.map +1 -0
  286. package/dist/skills/builtin/wikipedia_search.d.ts +77 -0
  287. package/dist/skills/builtin/wikipedia_search.js +241 -0
  288. package/dist/skills/builtin/wikipedia_search.js.map +1 -0
  289. package/{src/skills/index.ts → dist/skills/index.d.ts} +0 -1
  290. package/dist/skills/index.js +10 -0
  291. package/dist/skills/index.js.map +1 -0
  292. package/dist/types.d.ts +118 -0
  293. package/dist/types.js +5 -0
  294. package/dist/types.js.map +1 -0
  295. package/package.json +7 -1
  296. package/.github/workflows/publish.yml +0 -27
  297. package/.github/workflows/test.yml +0 -17
  298. package/CLAUDE.md +0 -112
  299. package/docs/MIGRATION-2.0.md +0 -81
  300. package/docs/agent-guide.md +0 -869
  301. package/docs/agent_guide.md +0 -1026
  302. package/docs/api-reference.md +0 -2420
  303. package/docs/api_reference.md +0 -1301
  304. package/docs/architecture.md +0 -843
  305. package/docs/cli-guide.md +0 -579
  306. package/docs/cli_guide.md +0 -448
  307. package/docs/cloud_functions_guide.md +0 -474
  308. package/docs/configuration.md +0 -422
  309. package/docs/contexts-guide.md +0 -787
  310. package/docs/contexts_guide.md +0 -511
  311. package/docs/datamap-guide.md +0 -1141
  312. package/docs/datamap_guide.md +0 -595
  313. package/docs/llm_parameters.md +0 -239
  314. package/docs/mcp_gateway_reference.md +0 -648
  315. package/docs/mcp_integration.md +0 -108
  316. package/docs/prefabs-guide.md +0 -800
  317. package/docs/sdk_features.md +0 -477
  318. package/docs/security.md +0 -436
  319. package/docs/serverless-guide.md +0 -513
  320. package/docs/skills-guide.md +0 -857
  321. package/docs/skills-system.md +0 -301
  322. package/docs/skills_parameter_schema.md +0 -392
  323. package/docs/skills_system.md +0 -467
  324. package/docs/swaig-reference.md +0 -1627
  325. package/docs/swaig_reference.md +0 -910
  326. package/docs/swml_service_guide.md +0 -600
  327. package/docs/third_party_skills.md +0 -533
  328. package/docs/web_service.md +0 -677
  329. package/examples/README.md +0 -131
  330. package/examples/advanced-datamap.ts +0 -100
  331. package/examples/advanced-dynamic-config.ts +0 -70
  332. package/examples/auto-vivified.ts +0 -94
  333. package/examples/call-flow.ts +0 -63
  334. package/examples/comprehensive-dynamic.ts +0 -125
  335. package/examples/contexts-steps.ts +0 -65
  336. package/examples/custom-path.ts +0 -45
  337. package/examples/datamap-tools.ts +0 -55
  338. package/examples/datasphere-multi-instance.ts +0 -63
  339. package/examples/datasphere-serverless-env.ts +0 -68
  340. package/examples/datasphere-webhook-env.ts +0 -66
  341. package/examples/datasphere.ts +0 -37
  342. package/examples/declarative.ts +0 -100
  343. package/examples/dynamic-config.ts +0 -54
  344. package/examples/dynamic-info-gatherer.ts +0 -69
  345. package/examples/dynamic-swml-service.ts +0 -67
  346. package/examples/gather-info.ts +0 -71
  347. package/examples/gather-per-question-functions-demo.ts +0 -140
  348. package/examples/joke-agent.ts +0 -34
  349. package/examples/kubernetes-agent.ts +0 -45
  350. package/examples/llm-params.ts +0 -69
  351. package/examples/mcp-agent.ts +0 -84
  352. package/examples/mcp-gateway.ts +0 -35
  353. package/examples/multi-agent.ts +0 -73
  354. package/examples/multi-endpoint.ts +0 -79
  355. package/examples/pom-prompt.ts +0 -71
  356. package/examples/prefab-concierge.ts +0 -47
  357. package/examples/prefab-faq.ts +0 -54
  358. package/examples/prefab-info-gatherer.ts +0 -33
  359. package/examples/prefab-receptionist.ts +0 -36
  360. package/examples/prefab-survey.ts +0 -68
  361. package/examples/record-call.ts +0 -67
  362. package/examples/relay-demo.ts +0 -33
  363. package/examples/room-and-sip.ts +0 -94
  364. package/examples/serverless-lambda.ts +0 -35
  365. package/examples/session-state.ts +0 -83
  366. package/examples/simple-agent.ts +0 -36
  367. package/examples/simple-static.ts +0 -29
  368. package/examples/skills-demo.ts +0 -38
  369. package/examples/step-function-inheritance-demo.ts +0 -124
  370. package/examples/swaig-features.ts +0 -187
  371. package/examples/swml-service-routing.ts +0 -66
  372. package/examples/swml-service.ts +0 -38
  373. package/examples/tap.ts +0 -68
  374. package/examples/verb-methods.ts +0 -45
  375. package/examples/web-search-multi-instance.ts +0 -72
  376. package/examples/web-search.ts +0 -38
  377. package/examples/wikipedia.ts +0 -36
  378. package/livewire/README.md +0 -140
  379. package/livewire/docs/migration-guide.md +0 -228
  380. package/livewire/examples/livewire-basic-agent.ts +0 -74
  381. package/livewire/examples/livewire-handoff.ts +0 -197
  382. package/livewire/examples/livewire-multi-tool.ts +0 -117
  383. package/relay/README.md +0 -70
  384. package/relay/RELAY_IMPLEMENTATION_GUIDE.md +0 -1257
  385. package/relay/docs/call-methods.md +0 -474
  386. package/relay/docs/client-reference.md +0 -142
  387. package/relay/docs/events.md +0 -134
  388. package/relay/docs/getting-started.md +0 -134
  389. package/relay/docs/guide.md +0 -306
  390. package/relay/docs/messaging.md +0 -182
  391. package/relay/examples/relay-inbound.ts +0 -66
  392. package/relay/examples/relay-messaging.ts +0 -71
  393. package/relay/examples/relay-outbound.ts +0 -76
  394. package/rest/README.md +0 -95
  395. package/rest/docs/calling.md +0 -273
  396. package/rest/docs/client-reference.md +0 -107
  397. package/rest/docs/compat.md +0 -204
  398. package/rest/docs/fabric.md +0 -183
  399. package/rest/docs/getting-started.md +0 -110
  400. package/rest/docs/guide.md +0 -351
  401. package/rest/docs/namespaces.md +0 -285
  402. package/rest/examples/rest-10dlc-registration.ts +0 -161
  403. package/rest/examples/rest-calling-ivr-and-ai.ts +0 -102
  404. package/rest/examples/rest-calling-play-and-record.ts +0 -91
  405. package/rest/examples/rest-client.ts +0 -65
  406. package/rest/examples/rest-compat-laml.ts +0 -210
  407. package/rest/examples/rest-datasphere-search.ts +0 -82
  408. package/rest/examples/rest-fabric-conferences-and-routing.ts +0 -144
  409. package/rest/examples/rest-fabric-subscribers-and-sip.ts +0 -108
  410. package/rest/examples/rest-fabric-swml-and-callflows.ts +0 -99
  411. package/rest/examples/rest-manage-resources.ts +0 -65
  412. package/rest/examples/rest-phone-number-management.ts +0 -197
  413. package/rest/examples/rest-queues-mfa-and-recordings.ts +0 -143
  414. package/rest/examples/rest-video-rooms.ts +0 -186
  415. package/src/AgentBase.ts +0 -2598
  416. package/src/AgentServer.ts +0 -442
  417. package/src/AuthHandler.ts +0 -256
  418. package/src/ConfigLoader.ts +0 -447
  419. package/src/ContextBuilder.ts +0 -1181
  420. package/src/DataMap.ts +0 -477
  421. package/src/FunctionResult.ts +0 -903
  422. package/src/Logger.ts +0 -337
  423. package/src/PomBuilder.ts +0 -467
  424. package/src/PromptManager.ts +0 -133
  425. package/src/SWMLHandler.ts +0 -298
  426. package/src/SWMLService.ts +0 -749
  427. package/src/SchemaUtils.ts +0 -361
  428. package/src/ServerlessAdapter.ts +0 -240
  429. package/src/SessionManager.ts +0 -311
  430. package/src/SslConfig.ts +0 -118
  431. package/src/SwaigFunction.ts +0 -276
  432. package/src/SwmlBuilder.ts +0 -283
  433. package/src/SwmlVerbMethods.generated.ts +0 -234
  434. package/src/TypeInference.ts +0 -199
  435. package/src/WebService.ts +0 -641
  436. package/src/cli/agent-loader.ts +0 -166
  437. package/src/cli/mock-data.ts +0 -111
  438. package/src/cli/swaig-test.ts +0 -452
  439. package/src/generateVerbTypes.ts +0 -322
  440. package/src/livewire/index.ts +0 -1252
  441. package/src/prefabs/ConciergeAgent.ts +0 -309
  442. package/src/prefabs/FAQBotAgent.ts +0 -415
  443. package/src/prefabs/InfoGathererAgent.ts +0 -379
  444. package/src/prefabs/ReceptionistAgent.ts +0 -395
  445. package/src/prefabs/SurveyAgent.ts +0 -671
  446. package/src/relay/Action.ts +0 -482
  447. package/src/relay/Call.ts +0 -1270
  448. package/src/relay/Deferred.ts +0 -94
  449. package/src/relay/Message.ts +0 -199
  450. package/src/relay/RelayClient.ts +0 -1185
  451. package/src/relay/RelayError.ts +0 -20
  452. package/src/relay/RelayEvent.ts +0 -944
  453. package/src/relay/index.ts +0 -123
  454. package/src/relay/types.ts +0 -149
  455. package/src/rest/HttpClient.ts +0 -164
  456. package/src/rest/RestError.ts +0 -45
  457. package/src/rest/base/BaseResource.ts +0 -32
  458. package/src/rest/base/CrudResource.ts +0 -98
  459. package/src/rest/base/CrudWithAddresses.ts +0 -37
  460. package/src/rest/namespaces/addresses.ts +0 -64
  461. package/src/rest/namespaces/calling.ts +0 -534
  462. package/src/rest/namespaces/chat.ts +0 -31
  463. package/src/rest/namespaces/compat.ts +0 -812
  464. package/src/rest/namespaces/datasphere.ts +0 -88
  465. package/src/rest/namespaces/fabric.ts +0 -417
  466. package/src/rest/namespaces/imported-numbers.ts +0 -31
  467. package/src/rest/namespaces/logs.ts +0 -151
  468. package/src/rest/namespaces/lookup.ts +0 -38
  469. package/src/rest/namespaces/mfa.ts +0 -61
  470. package/src/rest/namespaces/number-groups.ts +0 -68
  471. package/src/rest/namespaces/phone-numbers.ts +0 -76
  472. package/src/rest/namespaces/project.ts +0 -65
  473. package/src/rest/namespaces/pubsub.ts +0 -31
  474. package/src/rest/namespaces/queues.ts +0 -58
  475. package/src/rest/namespaces/recordings.ts +0 -53
  476. package/src/rest/namespaces/registry.ts +0 -200
  477. package/src/rest/namespaces/short-codes.ts +0 -54
  478. package/src/rest/namespaces/sip-profile.ts +0 -40
  479. package/src/rest/namespaces/verified-callers.ts +0 -46
  480. package/src/rest/namespaces/video.ts +0 -332
  481. package/src/rest/types.ts +0 -61
  482. package/src/skills/SkillBase.ts +0 -582
  483. package/src/skills/SkillManager.ts +0 -419
  484. package/src/skills/SkillRegistry.ts +0 -367
  485. package/src/skills/builtin/api_ninjas_trivia.ts +0 -285
  486. package/src/skills/builtin/ask_claude.ts +0 -246
  487. package/src/skills/builtin/claude_skills.ts +0 -983
  488. package/src/skills/builtin/custom_skills.ts +0 -327
  489. package/src/skills/builtin/datasphere.ts +0 -447
  490. package/src/skills/builtin/datasphere_serverless.ts +0 -347
  491. package/src/skills/builtin/datetime.ts +0 -137
  492. package/src/skills/builtin/google_maps.ts +0 -656
  493. package/src/skills/builtin/info_gatherer.ts +0 -415
  494. package/src/skills/builtin/joke.ts +0 -196
  495. package/src/skills/builtin/math.ts +0 -149
  496. package/src/skills/builtin/mcp_gateway.ts +0 -685
  497. package/src/skills/builtin/native_vector_search.ts +0 -910
  498. package/src/skills/builtin/play_background_file.ts +0 -367
  499. package/src/skills/builtin/spider.ts +0 -874
  500. package/src/skills/builtin/swml_transfer.ts +0 -645
  501. package/src/skills/builtin/weather_api.ts +0 -255
  502. package/src/skills/builtin/web_search.ts +0 -1083
  503. package/src/skills/builtin/wikipedia_search.ts +0 -304
  504. package/src/types.ts +0 -132
  505. package/tests/AgentBase.test.ts +0 -1093
  506. package/tests/AgentServer.test.ts +0 -126
  507. package/tests/AuthHandler.test.ts +0 -133
  508. package/tests/ConfigLoader.test.ts +0 -151
  509. package/tests/ContextBuilder.test.ts +0 -108
  510. package/tests/DataMap.test.ts +0 -367
  511. package/tests/EphemeralSkillCopy.test.ts +0 -107
  512. package/tests/FunctionResult.test.ts +0 -298
  513. package/tests/GracefulShutdown.test.ts +0 -46
  514. package/tests/Logger.test.ts +0 -420
  515. package/tests/PomBuilder.test.ts +0 -228
  516. package/tests/ProxyDetection.test.ts +0 -228
  517. package/tests/SWMLService.test.ts +0 -320
  518. package/tests/SWMLVerbHandler.test.ts +0 -523
  519. package/tests/SchemaUtils.test.ts +0 -106
  520. package/tests/SchemaUtils.verb.test.ts +0 -206
  521. package/tests/SecurityUtils.test.ts +0 -192
  522. package/tests/ServerlessAdapter.test.ts +0 -222
  523. package/tests/SessionManager.test.ts +0 -257
  524. package/tests/SkillBaseFeatures.test.ts +0 -130
  525. package/tests/SkillMultiInstance.test.ts +0 -102
  526. package/tests/SkillParameterSchemas.test.ts +0 -134
  527. package/tests/SkillRegistrySchema.test.ts +0 -84
  528. package/tests/SslConfig.test.ts +0 -97
  529. package/tests/SwmlBuilder.test.ts +0 -400
  530. package/tests/TypeInference.test.ts +0 -165
  531. package/tests/VerbHandlerRegistry.test.ts +0 -128
  532. package/tests/cli/mock-data.test.ts +0 -113
  533. package/tests/cli/swaig-test.test.ts +0 -108
  534. package/tests/examples.test.ts +0 -194
  535. package/tests/fixtures/scrape-parity/README.md +0 -53
  536. package/tests/fixtures/scrape-parity/expected/01_simple_article.json +0 -5
  537. package/tests/fixtures/scrape-parity/expected/02_class_based_noise.json +0 -5
  538. package/tests/fixtures/scrape-parity/expected/03_nested_containers.json +0 -5
  539. package/tests/fixtures/scrape-parity/expected/04_bare_body.json +0 -5
  540. package/tests/fixtures/scrape-parity/expected/05_malformed.json +0 -5
  541. package/tests/fixtures/scrape-parity/expected/06_multi_class.json +0 -5
  542. package/tests/fixtures/scrape-parity/expected/07_anchor_pattern.json +0 -5
  543. package/tests/fixtures/scrape-parity/expected/08_inline_script.json +0 -5
  544. package/tests/fixtures/scrape-parity/expected/09_whitespace_nbsp.json +0 -5
  545. package/tests/fixtures/scrape-parity/expected/10_entity_unicode.json +0 -5
  546. package/tests/fixtures/scrape-parity/expected/11_cdata_comments.json +0 -5
  547. package/tests/fixtures/scrape-parity/expected/12_deep_nested_removals.json +0 -5
  548. package/tests/fixtures/scrape-parity/html/01_simple_article.html +0 -18
  549. package/tests/fixtures/scrape-parity/html/02_class_based_noise.html +0 -18
  550. package/tests/fixtures/scrape-parity/html/03_nested_containers.html +0 -13
  551. package/tests/fixtures/scrape-parity/html/04_bare_body.html +0 -9
  552. package/tests/fixtures/scrape-parity/html/05_malformed.html +0 -11
  553. package/tests/fixtures/scrape-parity/html/06_multi_class.html +0 -18
  554. package/tests/fixtures/scrape-parity/html/07_anchor_pattern.html +0 -12
  555. package/tests/fixtures/scrape-parity/html/08_inline_script.html +0 -17
  556. package/tests/fixtures/scrape-parity/html/09_whitespace_nbsp.html +0 -21
  557. package/tests/fixtures/scrape-parity/html/10_entity_unicode.html +0 -10
  558. package/tests/fixtures/scrape-parity/html/11_cdata_comments.html +0 -13
  559. package/tests/fixtures/scrape-parity/html/12_deep_nested_removals.html +0 -24
  560. package/tests/fixtures/scrape-parity/python_extract.py +0 -109
  561. package/tests/livewire/livewire.test.ts +0 -780
  562. package/tests/mcp.test.ts +0 -221
  563. package/tests/prefabs/prefabs.test.ts +0 -1093
  564. package/tests/relay/Action.test.ts +0 -392
  565. package/tests/relay/Call.test.ts +0 -535
  566. package/tests/relay/Deferred.test.ts +0 -71
  567. package/tests/relay/Message.test.ts +0 -164
  568. package/tests/relay/RelayClient.test.ts +0 -779
  569. package/tests/relay/RelayEvent.test.ts +0 -463
  570. package/tests/relay/helpers.ts +0 -79
  571. package/tests/rest/HttpClient.test.ts +0 -274
  572. package/tests/rest/RestError.test.ts +0 -53
  573. package/tests/rest/calling.test.ts +0 -156
  574. package/tests/rest/client.test.ts +0 -197
  575. package/tests/rest/compat.test.ts +0 -335
  576. package/tests/rest/datasphere.test.ts +0 -71
  577. package/tests/rest/fabric.test.ts +0 -186
  578. package/tests/rest/helpers.ts +0 -95
  579. package/tests/rest/logs.test.ts +0 -68
  580. package/tests/rest/pagination.test.ts +0 -133
  581. package/tests/rest/registry.test.ts +0 -94
  582. package/tests/rest/relay-rest.test.ts +0 -290
  583. package/tests/rest/video.test.ts +0 -173
  584. package/tests/setup.ts +0 -6
  585. package/tests/skills/SkillBase.test.ts +0 -108
  586. package/tests/skills/SkillManager.test.ts +0 -268
  587. package/tests/skills/SkillRegistry.test.ts +0 -176
  588. package/tests/skills/builtin.test.ts +0 -1472
  589. package/tests/skills/claude-skills.test.ts +0 -54
  590. package/tests/skills/custom-skills.test.ts +0 -53
  591. package/tests/skills/datasphere-serverless.test.ts +0 -70
  592. package/tests/skills/datasphere.test.ts +0 -107
  593. package/tests/skills/datetime.test.ts +0 -101
  594. package/tests/skills/google-maps.test.ts +0 -78
  595. package/tests/skills/info-gatherer.test.ts +0 -411
  596. package/tests/skills/joke.test.ts +0 -81
  597. package/tests/skills/math.test.ts +0 -68
  598. package/tests/skills/mcp-gateway.test.ts +0 -101
  599. package/tests/skills/play-background.test.ts +0 -54
  600. package/tests/skills/spider.test.ts +0 -108
  601. package/tests/skills/swml-transfer.test.ts +0 -178
  602. package/tests/skills/trivia.test.ts +0 -54
  603. package/tests/skills/vector-search.test.ts +0 -135
  604. package/tests/skills/weather-api.test.ts +0 -77
  605. package/tests/skills/web-search-parity.test.ts +0 -59
  606. package/tests/skills/web-search.test.ts +0 -103
  607. package/tests/skills/wikipedia.test.ts +0 -63
  608. package/tsconfig.json +0 -18
  609. package/vitest.config.ts +0 -9
  610. /package/{src → dist}/schema.json +0 -0
@@ -1,1257 +0,0 @@
1
- # SignalWire RELAY Client Implementation Guide
2
-
3
- This document is for AI coding agents implementing a RELAY client in any language. It describes the wire protocol, correlation mechanisms, and critical pitfalls that are not obvious from the spec alone.
4
-
5
- ## Protocol Overview
6
-
7
- RELAY uses JSON-RPC 2.0 over WebSocket. The server is at `wss://<host>` (no path). All communication is async — you send requests, get responses matched by `id`, and receive server-pushed events via `signalwire.event`.
8
-
9
- ## Authentication
10
-
11
- ```json
12
- {
13
- "jsonrpc": "2.0",
14
- "id": "<uuid>",
15
- "method": "signalwire.connect",
16
- "params": {
17
- "version": {"major": 2, "minor": 0, "revision": 0},
18
- "agent": "your-sdk-name/1.0",
19
- "event_acks": true,
20
- "authentication": {"project": "<project_id>", "token": "<token>"},
21
- "contexts": ["office", "support"]
22
- }
23
- }
24
- ```
25
-
26
- The response contains a `protocol` string — save it and send it back on reconnect to resume the session.
27
-
28
- ## Four Correlation Mechanisms
29
-
30
- Every method uses one or more of these to bind requests to responses and events. Getting these wrong is the #1 source of bugs.
31
-
32
- ### 1. JSON-RPC `id` (ALL methods)
33
-
34
- Every request has a UUID `id`. The server responds with the same `id`. This is how you match RPC responses to pending requests.
35
-
36
- ```
37
- Client → {"jsonrpc":"2.0", "id":"abc-123", "method":"calling.answer", "params":{...}}
38
- Server → {"jsonrpc":"2.0", "id":"abc-123", "result":{"code":"200", "message":"Answered"}}
39
- ```
40
-
41
- Implementation: maintain a `pending: Map<string, Future>` keyed by request `id`.
42
-
43
- ### 2. `call_id` routing (all call-level methods)
44
-
45
- Every call method sends `node_id` + `call_id` in params. Events come back with `call_id` in their params. Route events to the correct Call object by `call_id`.
46
-
47
- ```
48
- Client → {"method":"calling.play", "params":{"node_id":"n1", "call_id":"c1", "control_id":"ctl1", ...}}
49
- Server event → {"method":"signalwire.event", "params":{"event_type":"calling.call.play", "params":{"call_id":"c1", "control_id":"ctl1", "state":"finished"}}}
50
- ```
51
-
52
- Implementation: maintain a `calls: Map<string, Call>` keyed by `call_id`.
53
-
54
- ### 3. `control_id` action tracking (12 methods)
55
-
56
- Methods that start long-running operations (play, record, detect, etc.) take a client-generated `control_id`. The server echoes it back in events. Multiple actions can run concurrently on the same call — `control_id` disambiguates.
57
-
58
- Implementation: each Call maintains `actions: Map<string, Action>` keyed by `control_id`.
59
-
60
- ### 4. `tag` correlation (dial only)
61
-
62
- **CRITICAL**: `calling.dial` is the only method where the RPC response does NOT contain a `call_id`. The response is just `{"code":"200", "message":"Dialing"}`. The real `call_id` and `node_id` arrive asynchronously via events matched by `tag`.
63
-
64
- Implementation: maintain `pending_dials: Map<string, Future<Call>>` keyed by `tag`.
65
-
66
- ## Method Categories
67
-
68
- ### Simple fire-and-response (no async tracking)
69
-
70
- These methods send an RPC, get a response with `code`/`message`, and are done. No control_id, no ongoing events to track.
71
-
72
- | Method | RPC | Response |
73
- |--------|-----|----------|
74
- | `answer` | `calling.answer` | `{"code":"200", "message":"Answered"}` |
75
- | `end` | `calling.end` | `{"code":"200", "message":"Disconnecting call"}` |
76
- | `pass` | `calling.pass` | `{"code":"200", "message":"Passing call"}` |
77
- | `connect` | `calling.connect` | `{"code":"200", "message":"connecting"}` |
78
- | `disconnect` | `calling.disconnect` | `{"code":"200", "message":"Disconnecting"}` |
79
- | `hold` | `calling.hold` | `{"code":"200", "message":"Call on hold"}` |
80
- | `unhold` | `calling.unhold` | `{"code":"200", "message":"Call off hold"}` |
81
- | `denoise` | `calling.denoise` | `{"code":"200", "message":"Denoiser on"}` |
82
- | `denoise.stop` | `calling.denoise.stop` | `{"code":"200", "message":"Denoiser off"}` |
83
- | `transfer` | `calling.transfer` | `{"code":"200", "message":"Transferring"}` |
84
- | `join_conference` | `calling.join_conference` | `{"code":"200", "message":"Joining conference"}` |
85
- | `leave_conference` | `calling.leave_conference` | `{"code":"200", "message":"Leaving conference"}` |
86
- | `echo` | `calling.echo` | `{"code":"200", "message":"Echo started"}` |
87
- | `bind_digit` | `calling.bind_digit` | `{"code":"200", "message":"Digit binding created"}` |
88
- | `clear_digit_bindings` | `calling.clear_digit_bindings` | `{"code":"200", "message":"Digit bindings cleared"}` |
89
- | `live_transcribe` | `calling.live_transcribe` | `{"code":"200", "message":"Live transcription started"}` |
90
- | `live_translate` | `calling.live_translate` | `{"code":"200", "message":"Live translation started"}` |
91
- | `join_room` | `calling.join_room` | `{"code":"200", "message":"Joining room"}` |
92
- | `leave_room` | `calling.leave_room` | `{"code":"200", "message":"Leaving room"}` |
93
- | `amazon_bedrock` | `calling.amazon_bedrock` | `{"code":"200", "message":"AI started"}` |
94
- | `ai_message` | `calling.ai_message` | `{"code":"200", "message":"Message sent"}` |
95
- | `ai_hold` | `calling.ai_hold` | `{"code":"200", "message":"AI on hold"}` |
96
- | `ai_unhold` | `calling.ai_unhold` | `{"code":"200", "message":"AI resumed"}` |
97
- | `user_event` | `calling.user_event` | `{"code":"200", "message":"Event sent"}` |
98
- | `queue.enter` | `calling.queue.enter` | `{"code":"200", "message":"Entering Queue"}` |
99
- | `queue.leave` | `calling.queue.leave` | `{"code":"200", "message":"Leaving Queue"}` |
100
- | `refer` | `calling.refer` | `{"code":"200", "message":"Starting SIP REFER"}` |
101
- | `send_digits` | `calling.send_digits` | `{"code":"200", "message":"Sending Digits"}` |
102
-
103
- Note: `connect`, `refer`, `send_digits` etc. DO produce async events (`calling.call.connect`, `calling.call.refer`, `calling.call.send_digits`) but these route normally by `call_id`. You don't need special tracking — just the standard event dispatch.
104
-
105
- ### control_id action methods (require action tracking)
106
-
107
- These methods start a long-running operation. The client generates a `control_id` UUID, sends it in the request, and the server echoes it back in all related events. You MUST track these as Action objects to support `stop()`, `pause()`, `resume()`, `wait()`.
108
-
109
- **Blocking vs fire-and-forget**: The `await call.play(...)` call only waits for the server to accept the command (the JSON-RPC response). The actual operation runs asynchronously on the server. The user chooses how to handle completion:
110
-
111
- 1. **Wait inline** (blocking): `await action.wait()` — blocks until the terminal event arrives
112
- 2. **Fire and forget** (background): don't call `action.wait()`, continue immediately. Check `action.is_done` or `action.result` later if needed
113
- 3. **Callback** (background + notification): pass `on_completed=callback` to the method. The callback fires when the action reaches a terminal state. Accepts both sync and async functions. Errors in callbacks are caught and logged.
114
-
115
- The `on_completed` callback MUST also fire when the call is gone (404/410) — the action is resolved immediately with an empty event so the callback still runs. Implementations MUST support all three patterns on every action-based method.
116
-
117
- | Method | RPC | Event Type | Terminal States |
118
- |--------|-----|------------|-----------------|
119
- | `play` | `calling.play` | `calling.call.play` | `finished`, `error` |
120
- | `record` | `calling.record` | `calling.call.record` | `finished`, `no_input` |
121
- | `detect` | `calling.detect` | `calling.call.detect` | `finished`, `error` |
122
- | `collect` | `calling.collect` | `calling.call.collect` | `finished`, `error`, `no_input`, `no_match` |
123
- | `play_and_collect` | `calling.play_and_collect` | `calling.call.collect` | `finished`, `error`, `no_input`, `no_match` |
124
- | `pay` | `calling.pay` | `calling.call.pay` | `finished`, `error` |
125
- | `send_fax` | `calling.send_fax` | `calling.call.fax` | `finished`, `error` |
126
- | `receive_fax` | `calling.receive_fax` | `calling.call.fax` | `finished`, `error` |
127
- | `tap` | `calling.tap` | `calling.call.tap` | `finished` |
128
- | `stream` | `calling.stream` | `calling.call.stream` | `finished` |
129
- | `transcribe` | `calling.transcribe` | `calling.call.transcribe` | `finished` |
130
- | `ai` | `calling.ai` | N/A (ends on call end or stop) | `finished`, `error` |
131
-
132
- Action sub-commands (these reference an existing `control_id`):
133
- - `play.stop`, `play.pause`, `play.resume`, `play.volume`
134
- - `record.stop`, `record.pause`, `record.resume`
135
- - `detect.stop`
136
- - `collect.stop`, `collect.start_input_timers`
137
- - `play_and_collect.stop`, `play_and_collect.volume`
138
- - `pay.stop`
139
- - `send_fax.stop`, `receive_fax.stop`
140
- - `tap.stop`
141
- - `stream.stop`
142
- - `transcribe.stop`
143
- - `ai.stop`
144
-
145
- #### play_and_collect gotcha
146
-
147
- `play_and_collect` shares one `control_id` across both the play and collect phases. Events arrive as BOTH `calling.call.play` (for play state) and `calling.call.collect` (for collect result). Your CollectAction must filter by event_type — only resolve on `calling.call.collect` events, NOT on `calling.call.play` events with `state: finished` (that just means playback ended, not that input was collected).
148
-
149
- #### detect gotcha
150
-
151
- `detect` delivers results continuously via `calling.call.detect` events with a `detect` object. A detect action should resolve on the FIRST meaningful result (e.g., `HUMAN`, `MACHINE`, `CED`, digit) OR on terminal states `finished`/`error`. Don't wait only for `finished` — the useful data comes in intermediate events.
152
-
153
- ### tag-based methods (dial)
154
-
155
- **This is where most implementations break.**
156
-
157
- #### calling.dial — the async dance
158
-
159
- ```
160
- Client → {"method":"calling.dial", "params":{"tag":"my-tag-123", "devices":[[...]]}}
161
- Server → {"result":{"code":"200", "message":"Dialing"}} ← NO call_id here!
162
- ```
163
-
164
- After the RPC response, the server sends a sequence of events:
165
-
166
- 1. **`calling.call.state`** events for each call leg (one per device being dialed):
167
- ```json
168
- {"event_type":"calling.call.state", "params":{
169
- "call_id":"leg-uuid-1", "node_id":"node-uuid", "tag":"my-tag-123",
170
- "call_state":"created", "device":{...}
171
- }}
172
- ```
173
- Then `ringing`, then `answered` or `ended` for each leg.
174
-
175
- 2. **`calling.call.dial`** event when the dial operation completes:
176
- ```json
177
- {"event_type":"calling.call.dial", "params":{
178
- "node_id":"node-uuid",
179
- "tag":"my-tag-123",
180
- "dial_state":"answered",
181
- "call":{
182
- "call_id":"winner-uuid",
183
- "node_id":"node-uuid",
184
- "tag":"my-tag-123",
185
- "device":{...},
186
- "dial_winner": true
187
- }
188
- }}
189
- ```
190
-
191
- **CRITICAL DETAILS:**
192
- - The `calling.call.dial` event has NO top-level `call_id` in params. The call info is nested inside `params.call.call_id`.
193
- - `dial_state` values: `dialing` (progress), `answered` (success), `failed` (all legs failed).
194
- - With parallel dialing, multiple call legs are created. Each gets `calling.call.state` events. Only the winner appears in the `calling.call.dial` event with `dial_state: "answered"`. Losers get `calling.call.state` with `call_state: "ended"`.
195
-
196
- #### Correct dial() implementation
197
-
198
- ```python
199
- async def dial(devices, tag=None, timeout=120):
200
- tag = tag or generate_uuid()
201
-
202
- # 1. Register pending dial BEFORE sending RPC
203
- future = create_future()
204
- pending_dials[tag] = future
205
-
206
- # 2. Send the RPC — response is just {"code":"200","message":"Dialing"}
207
- await execute("calling.dial", {"tag": tag, "devices": devices})
208
-
209
- # 3. Wait for calling.call.dial event to resolve the future
210
- try:
211
- call = await wait_for(future, timeout=timeout)
212
- return call
213
- finally:
214
- pending_dials.pop(tag)
215
- ```
216
-
217
- #### Event routing during dial
218
-
219
- Your event handler needs three special cases:
220
-
221
- ```python
222
- def handle_event(payload):
223
- event_type = payload["event_type"]
224
- event_params = payload["params"]
225
- call_id = event_params.get("call_id", "")
226
-
227
- # 1. Inbound call
228
- if event_type == "calling.call.receive":
229
- handle_inbound(payload)
230
- return
231
-
232
- # 2. Dial completion — call_id is NESTED at params.call.call_id
233
- if event_type == "calling.call.dial":
234
- tag = event_params.get("tag", "")
235
- dial_state = event_params.get("dial_state", "")
236
- call_info = event_params.get("call", {})
237
- future = pending_dials.get(tag)
238
- if future:
239
- if dial_state == "answered":
240
- call = find_or_create_call(call_info)
241
- future.resolve(call)
242
- elif dial_state == "failed":
243
- future.reject(Error("Dial failed"))
244
- return
245
-
246
- # 3. State events during dial — call not registered yet
247
- if event_type == "calling.call.state":
248
- tag = event_params.get("tag", "")
249
- if tag in pending_dials and call_id not in calls:
250
- # Create the Call object so events route correctly
251
- register_dial_leg(tag, event_params)
252
- # Fall through to normal routing
253
-
254
- # 4. Normal routing by call_id
255
- call = calls.get(call_id)
256
- if call:
257
- call.dispatch_event(payload)
258
- if call.state == "ended":
259
- calls.pop(call_id)
260
- ```
261
-
262
- ### calling.begin (DEPRECATED)
263
-
264
- Unlike `calling.dial`, the deprecated `calling.begin` DOES return `call_id` and `node_id` in the response:
265
- ```json
266
- {"code":"200", "message":"Call started", "call_id":"<UUID>", "node_id":"<UUID>"}
267
- ```
268
- Do NOT assume `calling.dial` works the same way. It doesn't.
269
-
270
- ## Event ACK
271
-
272
- The server expects an acknowledgment for every `signalwire.event`:
273
- ```json
274
- {"jsonrpc":"2.0", "id":"<event_msg_id>", "result":{}}
275
- ```
276
- Send this immediately when you receive the event, before processing it.
277
-
278
- ## Server Pings
279
-
280
- The server sends `signalwire.ping` periodically. Respond with:
281
- ```json
282
- {"jsonrpc":"2.0", "id":"<ping_msg_id>", "result":{}}
283
- ```
284
-
285
- ## Error Code Handling
286
-
287
- The calling API always returns results with `code` and `message`. The code is a STRING, not an integer.
288
-
289
- - Any `2xx` code = success
290
- - `404` = call does not exist
291
- - `410` = call existed but is gone
292
- - `409` = conflict (call already connected, controlled by another client)
293
-
294
- ### Call-gone handling (404/410)
295
-
296
- When a caller hangs up, the server destroys the call. If your client tries to send a command (play, record, etc.) after the caller hung up but before you received the `calling.call.state ended` event, you get a 404 or 410 error. **This is normal telephony flow, not an exceptional condition.**
297
-
298
- Handle it gracefully: log it and return an empty result instead of raising an exception. This avoids noisy errors in production when callers hang up mid-IVR.
299
-
300
- ```python
301
- async def execute_on_call(method, params):
302
- try:
303
- return await execute(f"calling.{method}", params)
304
- except RelayError as e:
305
- if e.code in (404, 410):
306
- log.info(f"Call gone during {method}")
307
- return {}
308
- raise
309
- ```
310
-
311
- Also: if an action (play, record, etc.) gets a call-gone response, resolve the action's Future immediately so `action.wait()` doesn't hang forever.
312
-
313
- ## Event Structure Reference
314
-
315
- All events arrive as:
316
- ```json
317
- {
318
- "jsonrpc": "2.0",
319
- "method": "signalwire.event",
320
- "id": "<msg_id>",
321
- "params": {
322
- "event_type": "calling.call.play",
323
- "timestamp": 123457.1234,
324
- "params": {
325
- "call_id": "...",
326
- "control_id": "...",
327
- "state": "finished"
328
- }
329
- }
330
- }
331
- ```
332
-
333
- Note the nested `params.params` structure. The outer `params` has `event_type`, the inner `params` has event-specific data like `call_id`, `control_id`, `state`.
334
-
335
- ### Events with non-standard structure
336
-
337
- | Event | Gotcha |
338
- |-------|--------|
339
- | `calling.call.dial` | No top-level `call_id`. Has `tag`, `dial_state`, and `call` object containing `call_id`. |
340
- | `calling.conference` | Uses `conference_id` instead of `call_id` for conference-level events. Participant events DO have `call_id`. |
341
- | `calling.call.detect` | Results are in `detect.params.event`, not in a `state` field. Terminal state is `finished`. |
342
- | `calling.call.collect` | Result object has `type` (digit/speech/error/no_input/no_match) and `params`. |
343
- | `calling.call.record` | `url`, `duration`, `size` may be at top level OR nested inside `record` object. Check both. |
344
-
345
- ## Authorization State (Fast Reconnection)
346
-
347
- The server sends `signalwire.authorization.state` events containing an encrypted `authorization_state` string. Store this and send it back on reconnect for fast re-auth without a full authentication round-trip.
348
-
349
- ```json
350
- // Server sends:
351
- {"method":"signalwire.event", "params":{
352
- "event_type":"signalwire.authorization.state",
353
- "params":{"authorization_state":"<encryptedBase64>:<tagBase64>"}
354
- }}
355
- ```
356
-
357
- On reconnect, include `authorization_state` in the `signalwire.connect` params alongside `protocol`. If the authorization state is invalid or expired, the server ignores it and falls back to normal `authentication`.
358
-
359
- ## Server-Initiated Disconnect
360
-
361
- The server sends `signalwire.disconnect` to gracefully shut down connections (e.g. during deployments). The client MUST:
362
-
363
- 1. Respond with an empty result `{"jsonrpc":"2.0","id":"...","result":{}}`
364
- 2. Check the `restart` flag:
365
- - `restart: false` (or absent) → reconnect normally, reuse `protocol` and `authorization_state`
366
- - `restart: true` → clear `protocol` and `authorization_state`, reconnect with fresh auth
367
-
368
- ```json
369
- {"method":"signalwire.disconnect", "params":{"restart": true}}
370
- ```
371
-
372
- Do NOT set a "closing" flag — the client should reconnect after the server closes the socket.
373
-
374
- ## Dynamic Context Subscription
375
-
376
- Contexts can be sent in `signalwire.connect` for initial subscription, but you can also add/remove contexts dynamically after connecting:
377
-
378
- ### signalwire.receive
379
-
380
- Subscribe to additional contexts for inbound events:
381
- ```json
382
- {"method":"signalwire.receive", "params":{"contexts":["sales","support"]}}
383
- // Response: {"code":"200","message":"Receiving events"}
384
- // Error: {"code":"402","message":"Payment required"}
385
- ```
386
-
387
- ### signalwire.unreceive
388
-
389
- Unsubscribe from contexts:
390
- ```json
391
- {"method":"signalwire.unreceive", "params":{"contexts":["sales"]}}
392
- // Response: {"code":"200","message":"Unreceiving events"}
393
- ```
394
-
395
- These are sent on the assigned protocol (the one returned from `signalwire.connect`), not the signalwire protocol.
396
-
397
- ## Reconnection
398
-
399
- On WebSocket disconnect:
400
- 1. Reject all pending request Futures
401
- 2. Reject all pending dial Futures
402
- 3. Wait with exponential backoff (1s → 2s → 4s → ... → 30s max)
403
- 4. Reconnect and re-authenticate with `signalwire.connect`, sending:
404
- - The previous `protocol` string (to resume the session)
405
- - The `authorization_state` (for fast re-auth)
406
- - Unless a `signalwire.disconnect` with `restart: true` was received — then connect fresh
407
- 5. Flush any queued requests
408
-
409
- Call objects survive reconnect — the server tracks them by `call_id` across connections.
410
-
411
- ## Architecture Checklist
412
-
413
- - [ ] `pending` map: request `id` → Future (for RPC response matching)
414
- - [ ] `calls` map: `call_id` → Call (for event routing)
415
- - [ ] Each Call has `actions` map: `control_id` → Action (for action event routing)
416
- - [ ] `pending_dials` map: `tag` → Future<Call> (for dial event matching)
417
- - [ ] `authorization_state` stored from events and sent on reconnect
418
- - [ ] Event ACK sent for every `signalwire.event`
419
- - [ ] Pong sent for every `signalwire.ping`
420
- - [ ] `signalwire.disconnect` handled: respond, check `restart` flag, reconnect
421
- - [ ] `signalwire.receive`/`signalwire.unreceive` for dynamic context management
422
- - [ ] 404/410 errors handled gracefully (call-gone, not exceptional)
423
- - [ ] `calling.call.dial` events routed by `tag`, not `call_id`
424
- - [ ] `calling.call.state` events during dial create Call objects before dial completes
425
- - [ ] `play_and_collect` CollectAction filters by event_type, ignores play events
426
- - [ ] Auto-reconnect with exponential backoff
427
- - [ ] All pending futures cleaned up on disconnect
428
- - [ ] Actions support three completion patterns: `await action.wait()` (blocking), fire-and-forget (don't await), `on_completed` callback
429
- - [ ] `on_completed` callback supports both sync and async functions, errors caught and logged
430
- - [ ] `on_completed` fires on call-gone (404/410) with resolved empty event
431
- - [ ] `messages` map: `message_id` → Message (for messaging.state routing)
432
- - [ ] `on_message` handler for inbound SMS/MMS (like `on_call` for calls)
433
- - [ ] `send_message()` returns Message, tracks by `message_id`, supports `on_completed`
434
-
435
- ## Complete Method Parameter Reference
436
-
437
- Every calling method is sent as a JSON-RPC request. Unless otherwise noted, all methods require `node_id` (UUID) and `call_id` (UUID) in params. The `project_id` and `protocol` fields are added by the client automatically.
438
-
439
- ### Media Objects (reused across methods)
440
-
441
- Used in `play`, `play_and_collect`, and `connect` (ringback):
442
-
443
- ```
444
- audio: { type: "audio", params: { url: "https://..." } }
445
- tts: { type: "tts", params: { text: "...", language?: "en-US", gender?: "male"|"female", voice?: "..." } }
446
- silence: { type: "silence", params: { duration: <seconds> } }
447
- ringtone: { type: "ringtone", params: { name: "<country-code>", duration?: <seconds> } }
448
- ```
449
-
450
- Ringtone country codes: `at au bg br be ch cl cn cz de dk ee es fi fr gr hu il in it lt jp mx my nl no nz ph pl pt ru se sg th uk us tw ve za`
451
-
452
- ### Device Objects (reused across dial/connect)
453
-
454
- ```
455
- phone: { type: "phone", params: { from_number: "+1...", to_number: "+1...", timeout?: 30, max_duration?: <sec>, call_state_url?: "https://...", call_state_events?: ["created","ringing","answered","ended"], confirm?: "<swml>" } }
456
- sip: { type: "sip", params: { from: "sip:...", to: "sip:...", from_name?: "...", timeout?: 30, max_duration?: <sec>, headers?: [{name,value}], codecs?: ["PCMU","PCMA","OPUS","G729","G722","VP8","H264"], webrtc_media?: false, call_state_url?: "...", call_state_events?: [...], confirm?: "..." } }
457
- webrtc: { type: "webrtc", params: { from: "+1...", to: "resource-name", timeout?: 30, codecs?: ["PCMU","PCMA","OPUS","VP8","H264"], call_state_url?: "...", call_state_events?: [...], confirm?: "..." } }
458
- agora: { type: "agora", params: { from: "+1...", to?: "...", appid: "...", channel: "...", call_state_url?: "...", call_state_events?: [...], confirm?: "..." } }
459
- call: { type: "call", params: { node_id: "...", call_id: "..." } } // connect only
460
- queue: { type: "queue", params: { node_id: "...", queue_name: "...", queue_id?: "..." } } // connect only
461
- stream: { type: "stream", params: { url: "wss://...", name?: "...", codec?: "PCMU", status_url?: "...", status_url_method?: "POST", realtime?: false, authorization_bearer_token?: "...", custom_parameters?: {} } } // connect only
462
- ```
463
-
464
- ### Collect Object (reused in collect and play_and_collect)
465
-
466
- ```
467
- {
468
- initial_timeout?: 4.0, // seconds, used when start_input_timers is true
469
- digits?: {
470
- max: <int>, // required
471
- terminators?: "#*",
472
- digit_timeout?: 5.0
473
- },
474
- speech?: {
475
- end_silence_timeout?: 1.0,
476
- speech_timeout?: 60.0,
477
- language?: "en-US",
478
- hints?: ["word1", "word2"],
479
- engine?: "Deepgram"|"Google"
480
- }
481
- }
482
- ```
483
-
484
- ---
485
-
486
- ### calling.dial
487
-
488
- Dial outbound call(s). First device to answer wins.
489
-
490
- | Param | Type | Required | Notes |
491
- |-------|------|----------|-------|
492
- | `tag` | string | YES | Identifier for matching async events |
493
- | `devices` | array[array[Device]] | YES | Outer=sequential, inner=parallel |
494
- | `region` | string | no | Region to originate from |
495
- | `max_price_per_minute` | number | no | Price cap |
496
-
497
- Does NOT take `node_id`/`call_id`. Response has NO `call_id` — see tag correlation section above.
498
-
499
- ### calling.begin (DEPRECATED)
500
-
501
- | Param | Type | Required | Notes |
502
- |-------|------|----------|-------|
503
- | `tag` | string | no | |
504
- | `region` | string | no | |
505
- | `device` | Device | YES | Single device (not array) |
506
-
507
- Response DOES return `call_id` and `node_id`. Do NOT assume dial works the same.
508
-
509
- ### calling.answer
510
-
511
- | Param | Type | Required | Notes |
512
- |-------|------|----------|-------|
513
- | `node_id` | UUID | YES | |
514
- | `call_id` | UUID | YES | |
515
- | `codecs` | string[] | no | e.g. ["PCMU","PCMA","OPUS","G729","G722","VP8","H264"] |
516
-
517
- ### calling.end
518
-
519
- | Param | Type | Required | Notes |
520
- |-------|------|----------|-------|
521
- | `node_id` | UUID | YES | |
522
- | `call_id` | UUID | YES | |
523
- | `reason` | string | no | hangup\|cancel\|busy\|noAnswer\|decline\|error (default: hangup) |
524
-
525
- ### calling.pass
526
-
527
- | Param | Type | Required | Notes |
528
- |-------|------|----------|-------|
529
- | `node_id` | UUID | YES | |
530
- | `call_id` | UUID | YES | |
531
-
532
- Pass on inbound call offer. SignalWire offers it to another RELAY consumer.
533
-
534
- ### calling.connect
535
-
536
- Connect another device to this active call.
537
-
538
- | Param | Type | Required | Notes |
539
- |-------|------|----------|-------|
540
- | `node_id` | UUID | YES | |
541
- | `call_id` | UUID | YES | |
542
- | `devices` | array[array[Device]] | YES | Sequential/parallel device arrays |
543
- | `ringback` | Media[] | no | What caller hears while connecting |
544
- | `tag` | string | no | Tag for created calls' events |
545
- | `max_duration` | number | no | Max connected duration in minutes |
546
- | `max_price_per_minute` | number | no | |
547
- | `status_url` | URL | no | |
548
-
549
- ### calling.disconnect
550
-
551
- | Param | Type | Required | Notes |
552
- |-------|------|----------|-------|
553
- | `node_id` | UUID | YES | |
554
- | `call_id` | UUID | YES | |
555
-
556
- Disconnects all connected calls without hanging up on them.
557
-
558
- ### calling.play
559
-
560
- | Param | Type | Required | Notes |
561
- |-------|------|----------|-------|
562
- | `node_id` | UUID | YES | |
563
- | `call_id` | UUID | YES | |
564
- | `control_id` | string | YES | Client-generated UUID |
565
- | `play` | Media[] | YES | Array of media objects |
566
- | `volume` | float | no | -40 to +40 dB |
567
- | `direction` | string | no | listen\|speak\|both (default: listen) |
568
- | `loop` | int | no | 0=infinite, default 1 |
569
- | `status_url` | URL | no | |
570
-
571
- ### calling.play.pause / calling.play.resume / calling.play.stop
572
-
573
- | Param | Type | Required |
574
- |-------|------|----------|
575
- | `node_id` | UUID | YES |
576
- | `call_id` | UUID | YES |
577
- | `control_id` | string | YES |
578
-
579
- ### calling.play.volume
580
-
581
- | Param | Type | Required | Notes |
582
- |-------|------|----------|-------|
583
- | `node_id` | UUID | YES | |
584
- | `call_id` | UUID | YES | |
585
- | `control_id` | string | YES | |
586
- | `volume` | float | YES | -40 to +40 dB |
587
-
588
- ### calling.record
589
-
590
- | Param | Type | Required | Notes |
591
- |-------|------|----------|-------|
592
- | `node_id` | UUID | YES | |
593
- | `call_id` | UUID | YES | |
594
- | `control_id` | string | YES | |
595
- | `record` | object | YES | See below |
596
- | `status_url` | URL | no | |
597
-
598
- Record object (`record.audio`):
599
- | Param | Type | Default | Notes |
600
- |-------|------|---------|-------|
601
- | `beep` | bool | false | |
602
- | `format` | string | "mp3" | mp3\|wav |
603
- | `stereo` | bool | false | |
604
- | `direction` | string | "speak" | listen\|speak\|both |
605
- | `initial_timeout` | float | 5.0 | seconds, 0=disable |
606
- | `end_silence_timeout` | float | 1.0 | seconds, 0=disable |
607
- | `terminators` | string | "#*" | DTMF digits |
608
- | `input_sensitivity` | int | 44 | 0-100 |
609
-
610
- ### calling.record.pause
611
-
612
- | Param | Type | Required | Notes |
613
- |-------|------|----------|-------|
614
- | `node_id` | UUID | YES | |
615
- | `call_id` | UUID | YES | |
616
- | `control_id` | string | YES | |
617
- | `behavior` | string | no | skip\|silence (default: skip) |
618
-
619
- ### calling.record.resume / calling.record.stop
620
-
621
- | Param | Type | Required |
622
- |-------|------|----------|
623
- | `node_id` | UUID | YES |
624
- | `call_id` | UUID | YES |
625
- | `control_id` | string | YES |
626
-
627
- ### calling.collect
628
-
629
- | Param | Type | Required | Notes |
630
- |-------|------|----------|-------|
631
- | `node_id` | UUID | YES | |
632
- | `call_id` | UUID | YES | |
633
- | `control_id` | string | YES | |
634
- | `initial_timeout` | float | no | seconds, default 4.0 |
635
- | `digits` | object | conditional | Required if no speech |
636
- | `speech` | object | conditional | Required if no digits |
637
- | `partial_results` | bool | no | default false |
638
- | `continuous` | bool | no | default false |
639
- | `send_start_of_input` | bool | no | default false |
640
- | `start_input_timers` | bool | no | default false |
641
- | `status_url` | URL | no | |
642
-
643
- See Collect Object section above for digits/speech schemas.
644
-
645
- ### calling.collect.stop
646
-
647
- | Param | Type | Required |
648
- |-------|------|----------|
649
- | `node_id` | UUID | YES |
650
- | `call_id` | UUID | YES |
651
- | `control_id` | string | YES |
652
-
653
- ### calling.collect.start_input_timers
654
-
655
- | Param | Type | Required |
656
- |-------|------|----------|
657
- | `node_id` | UUID | YES |
658
- | `call_id` | UUID | YES |
659
- | `control_id` | string | YES |
660
-
661
- Starts the `initial_timeout` timer on an active collect.
662
-
663
- ### calling.play_and_collect
664
-
665
- | Param | Type | Required | Notes |
666
- |-------|------|----------|-------|
667
- | `node_id` | UUID | YES | |
668
- | `call_id` | UUID | YES | |
669
- | `control_id` | string | YES | |
670
- | `play` | Media[] | YES | Array of media objects |
671
- | `collect` | object | YES | See Collect Object section |
672
- | `volume` | float | no | -40 to +40 dB |
673
- | `status_url` | URL | no | |
674
-
675
- ### calling.play_and_collect.stop
676
-
677
- | Param | Type | Required |
678
- |-------|------|----------|
679
- | `node_id` | UUID | YES |
680
- | `call_id` | UUID | YES |
681
- | `control_id` | string | YES |
682
-
683
- ### calling.play_and_collect.volume
684
-
685
- | Param | Type | Required | Notes |
686
- |-------|------|----------|-------|
687
- | `node_id` | UUID | YES | |
688
- | `call_id` | UUID | YES | |
689
- | `control_id` | string | YES | |
690
- | `volume` | float | YES | -40 to +40 dB |
691
-
692
- ### calling.detect
693
-
694
- | Param | Type | Required | Notes |
695
- |-------|------|----------|-------|
696
- | `node_id` | UUID | YES | |
697
- | `call_id` | UUID | YES | |
698
- | `control_id` | string | YES | |
699
- | `detect` | object | YES | See below |
700
- | `timeout` | float | no | seconds, default 30.0 |
701
- | `status_url` | URL | no | |
702
-
703
- Detect object — type "machine":
704
- | Param | Type | Default |
705
- |-------|------|---------|
706
- | `initial_timeout` | float | 4.5 |
707
- | `end_silence_timeout` | float | 1.0 |
708
- | `machine_ready_timeout` | float | =end_silence_timeout |
709
- | `machine_voice_threshold` | float | 1.25 |
710
- | `machine_words_threshold` | int | 6 |
711
- | `detect_interruptions` | bool | false |
712
- | `detect_message_end` | bool | true |
713
-
714
- Detect object — type "fax":
715
- | Param | Type | Default |
716
- |-------|------|---------|
717
- | `tone` | string | "CED" | CED\|CNG |
718
-
719
- Detect object — type "digit":
720
- | Param | Type | Default |
721
- |-------|------|---------|
722
- | `digits` | string | "0123456789#*" |
723
-
724
- ### calling.detect.stop
725
-
726
- | Param | Type | Required |
727
- |-------|------|----------|
728
- | `node_id` | UUID | YES |
729
- | `call_id` | UUID | YES |
730
- | `control_id` | string | YES |
731
-
732
- ### calling.send_digits
733
-
734
- | Param | Type | Required | Notes |
735
- |-------|------|----------|-------|
736
- | `node_id` | UUID | YES | |
737
- | `call_id` | UUID | YES | |
738
- | `control_id` | string | YES | |
739
- | `digits` | string | YES | 0-9, #, *, A-D, w (0.5s wait), W (1s wait) |
740
-
741
- ### calling.tap
742
-
743
- | Param | Type | Required | Notes |
744
- |-------|------|----------|-------|
745
- | `node_id` | UUID | YES | |
746
- | `call_id` | UUID | YES | |
747
- | `control_id` | string | YES | |
748
- | `tap` | object | YES | `{type:"audio", params:{direction:"listen"\|"speak"\|"both"}}` |
749
- | `device` | object | YES | See below |
750
- | `status_url` | URL | no | |
751
-
752
- Tap device — type "rtp":
753
- | Param | Type | Required |
754
- |-------|------|----------|
755
- | `addr` | string (IPv4) | YES |
756
- | `port` | int | YES |
757
- | `codec` | string | no |
758
- | `ptime` | int | no |
759
-
760
- Tap device — type "ws":
761
- | Param | Type | Required |
762
- |-------|------|----------|
763
- | `uri` | string | YES |
764
- | `codec` | string | no |
765
- | `rate` | int | no |
766
-
767
- ### calling.tap.stop
768
-
769
- | Param | Type | Required |
770
- |-------|------|----------|
771
- | `node_id` | UUID | YES |
772
- | `call_id` | UUID | YES |
773
- | `control_id` | string | YES |
774
-
775
- ### calling.stream
776
-
777
- | Param | Type | Required | Notes |
778
- |-------|------|----------|-------|
779
- | `node_id` | UUID | YES | |
780
- | `call_id` | UUID | YES | |
781
- | `control_id` | string | YES | |
782
- | `url` | string | YES | wss:// WebSocket URI |
783
- | `name` | string | no | Friendly name |
784
- | `codec` | string | no | Default: call's native codec |
785
- | `track` | string | no | inbound_track\|outbound_track\|both_tracks (default: inbound_track) |
786
- | `status_url` | URL | no | |
787
- | `status_url_method` | string | no | GET\|POST (default: POST) |
788
- | `authorization_bearer_token` | string | no | |
789
- | `custom_parameters` | object | no | |
790
-
791
- ### calling.stream.stop
792
-
793
- | Param | Type | Required |
794
- |-------|------|----------|
795
- | `node_id` | UUID | YES |
796
- | `call_id` | UUID | YES |
797
- | `control_id` | string | YES |
798
-
799
- ### calling.transcribe
800
-
801
- | Param | Type | Required | Notes |
802
- |-------|------|----------|-------|
803
- | `node_id` | UUID | YES | |
804
- | `call_id` | UUID | YES | |
805
- | `control_id` | string | YES | |
806
- | `status_url` | URL | no | |
807
-
808
- Only one active transcription per call (409 if already active).
809
-
810
- ### calling.transcribe.stop
811
-
812
- | Param | Type | Required |
813
- |-------|------|----------|
814
- | `node_id` | UUID | YES |
815
- | `call_id` | UUID | YES |
816
- | `control_id` | string | YES |
817
-
818
- ### calling.send_fax
819
-
820
- | Param | Type | Required | Notes |
821
- |-------|------|----------|-------|
822
- | `node_id` | UUID | YES | |
823
- | `call_id` | UUID | YES | |
824
- | `control_id` | string | YES | |
825
- | `document` | URL | YES | URL to PDF |
826
- | `identity` | string | no | Display identity on receiver |
827
- | `header_info` | string | no | Custom header (default: "SignalWire", ""=disable) |
828
- | `status_url` | URL | no | |
829
-
830
- ### calling.send_fax.stop / calling.receive_fax.stop
831
-
832
- | Param | Type | Required |
833
- |-------|------|----------|
834
- | `node_id` | UUID | YES |
835
- | `call_id` | UUID | YES |
836
- | `control_id` | string | YES |
837
-
838
- ### calling.receive_fax
839
-
840
- | Param | Type | Required | Notes |
841
- |-------|------|----------|-------|
842
- | `node_id` | UUID | YES | |
843
- | `call_id` | UUID | YES | |
844
- | `control_id` | string | YES | |
845
- | `status_url` | URL | no | |
846
-
847
- ### calling.refer
848
-
849
- SIP REFER transfer.
850
-
851
- | Param | Type | Required | Notes |
852
- |-------|------|----------|-------|
853
- | `node_id` | UUID | YES | |
854
- | `call_id` | UUID | YES | |
855
- | `device` | object | YES | `{type:"sip", params:{to:"sip:...", username?:"...", password?:"..."}}` |
856
- | `status_url` | URL | no | |
857
-
858
- ### calling.transfer
859
-
860
- Transfer call control to another app.
861
-
862
- | Param | Type | Required | Notes |
863
- |-------|------|----------|-------|
864
- | `node_id` | UUID | YES | |
865
- | `call_id` | UUID | YES | |
866
- | `dest` | string | YES | https:// URL, SWML script, or `context:<app>` |
867
-
868
- ### calling.join_conference
869
-
870
- | Param | Type | Required | Notes |
871
- |-------|------|----------|-------|
872
- | `node_id` | UUID | YES | |
873
- | `call_id` | UUID | YES | |
874
- | `name` | string | YES | Conference name |
875
- | `muted` | bool | no | default false |
876
- | `beep` | string | no | true\|false\|onEnter\|onExit (default: "true") |
877
- | `start_on_enter` | bool | no | default true |
878
- | `end_on_exit` | bool | no | default false |
879
- | `wait_url` | URL | no | CXML/mp3/wav hold music |
880
- | `max_participants` | int | no | 1-250, default 250 |
881
- | `record` | string | no | do-not-record\|record-from-start |
882
- | `region` | string | no | global\|us\|eu |
883
- | `trim` | string | no | trim-silence\|do-not-trim |
884
- | `coach` | string | no | Call ID to coach |
885
- | `status_callback` | URL | no | |
886
- | `status_callback_event` | string | no | Space-separated: start end join leave mute hold modify speaker announcement |
887
- | `status_callback_event_type` | string | no | relay\|cxml (default: relay) |
888
- | `status_callback_method` | string | no | GET\|POST |
889
- | `recording_status_callback` | URL | no | |
890
- | `recording_status_callback_event` | string | no | in-progress\|completed\|absent |
891
- | `recording_status_callback_event_type` | string | no | relay\|cxml |
892
- | `recording_status_callback_method` | string | no | GET\|POST |
893
- | `stream` | object | no | `{url:"wss://...", name?:"...", codec?:"...", ...}` |
894
-
895
- ### calling.leave_conference
896
-
897
- | Param | Type | Required | Notes |
898
- |-------|------|----------|-------|
899
- | `node_id` | UUID | YES | |
900
- | `call_id` | UUID | YES | |
901
- | `conference_id` | UUID | YES | From conference events |
902
-
903
- ### calling.hold / calling.unhold
904
-
905
- | Param | Type | Required |
906
- |-------|------|----------|
907
- | `node_id` | UUID | YES |
908
- | `call_id` | UUID | YES |
909
-
910
- Note: marked NOT IMPLEMENTED in spec.
911
-
912
- ### calling.denoise / calling.denoise.stop
913
-
914
- | Param | Type | Required |
915
- |-------|------|----------|
916
- | `node_id` | UUID | YES |
917
- | `call_id` | UUID | YES |
918
-
919
- ### calling.echo
920
-
921
- | Param | Type | Required | Notes |
922
- |-------|------|----------|-------|
923
- | `node_id` | UUID | YES | |
924
- | `call_id` | UUID | YES | |
925
- | `timeout` | int | no | seconds, 0=until call ends |
926
- | `status_url` | URL | no | |
927
-
928
- ### calling.bind_digit
929
-
930
- | Param | Type | Required | Notes |
931
- |-------|------|----------|-------|
932
- | `node_id` | UUID | YES | |
933
- | `call_id` | UUID | YES | |
934
- | `digits` | string | YES | DTMF sequence to bind |
935
- | `bind_method` | string | YES | Method to invoke |
936
- | `params` | object | no | Params for bound method |
937
- | `realm` | string | no | Namespace for selective clearing |
938
- | `max_triggers` | int | no | 0=unlimited |
939
-
940
- ### calling.clear_digit_bindings
941
-
942
- | Param | Type | Required | Notes |
943
- |-------|------|----------|-------|
944
- | `node_id` | UUID | YES | |
945
- | `call_id` | UUID | YES | |
946
- | `realm` | string | no | Only clear this realm |
947
-
948
- ### calling.queue.enter
949
-
950
- | Param | Type | Required | Notes |
951
- |-------|------|----------|-------|
952
- | `node_id` | UUID | YES | |
953
- | `call_id` | UUID | YES | |
954
- | `control_id` | string | YES | |
955
- | `queue_name` | string | YES | |
956
- | `status_url` | URL | no | |
957
-
958
- ### calling.queue.leave
959
-
960
- | Param | Type | Required | Notes |
961
- |-------|------|----------|-------|
962
- | `node_id` | UUID | YES | |
963
- | `call_id` | UUID | YES | |
964
- | `control_id` | string | YES | |
965
- | `queue_name` | string | YES | |
966
- | `queue_id` | string | no | |
967
- | `status_url` | URL | no | |
968
-
969
- ### calling.ai
970
-
971
- Start an AI agent on the call.
972
-
973
- | Param | Type | Required | Notes |
974
- |-------|------|----------|-------|
975
- | `node_id` | UUID | YES | |
976
- | `call_id` | UUID | YES | |
977
- | `control_id` | string | YES | |
978
- | `agent` | UUID | no | Pre-configured agent |
979
- | `prompt` | object | no | `{text, top_p?, temperature?, confidence?, barge_confidence?, presence_penalty?, frequency_penalty?, model?}` |
980
- | `post_prompt` | object | no | Same structure as prompt |
981
- | `post_prompt_url` | URL | no | |
982
- | `post_prompt_auth_user` | string | no | |
983
- | `post_prompt_auth_password` | string | no | |
984
- | `global_data` | object | no | Data for SWAIG functions |
985
- | `pronounce` | object | no | Pronunciation rules |
986
- | `hints` | object | no | Context hints |
987
- | `languages` | object | no | Language configs |
988
- | `SWAIG` | object | no | `{defaults?, functions?, includes?, native_functions?}` |
989
- | `params` | object | no | ASR, TTS, turn detection, barge-in, LLM config, video, etc. |
990
-
991
- ### calling.ai.stop
992
-
993
- | Param | Type | Required |
994
- |-------|------|----------|
995
- | `node_id` | UUID | YES |
996
- | `call_id` | UUID | YES |
997
- | `control_id` | string | YES |
998
-
999
- ### calling.amazon_bedrock
1000
-
1001
- | Param | Type | Required | Notes |
1002
- |-------|------|----------|-------|
1003
- | `node_id` | UUID | YES | |
1004
- | `call_id` | UUID | YES | |
1005
- | `prompt` | string | no | System prompt |
1006
- | `SWAIG` | object | no | Function config |
1007
- | `params` | object | no | AI params |
1008
- | `global_data` | object | no | |
1009
- | `post_prompt` | object | no | |
1010
- | `post_prompt_url` | URL | no | |
1011
-
1012
- ### calling.ai_message
1013
-
1014
- | Param | Type | Required | Notes |
1015
- |-------|------|----------|-------|
1016
- | `node_id` | UUID | YES | |
1017
- | `call_id` | UUID | YES | |
1018
- | `message_text` | string | no | Text to inject |
1019
- | `role` | string | no | Message role |
1020
- | `reset` | object | no | `{full_reset?, user_prompt?, system_prompt?}` |
1021
- | `global_data` | object | no | Updated global data |
1022
-
1023
- ### calling.ai_hold
1024
-
1025
- | Param | Type | Required | Notes |
1026
- |-------|------|----------|-------|
1027
- | `node_id` | UUID | YES | |
1028
- | `call_id` | UUID | YES | |
1029
- | `timeout` | string/number | no | |
1030
- | `prompt` | string | no | Hold prompt/music |
1031
-
1032
- ### calling.ai_unhold
1033
-
1034
- | Param | Type | Required | Notes |
1035
- |-------|------|----------|-------|
1036
- | `node_id` | UUID | YES | |
1037
- | `call_id` | UUID | YES | |
1038
- | `prompt` | string | no | Resume prompt |
1039
-
1040
- ### calling.user_event
1041
-
1042
- | Param | Type | Required | Notes |
1043
- |-------|------|----------|-------|
1044
- | `node_id` | UUID | YES | |
1045
- | `call_id` | UUID | YES | |
1046
- | `event` | string | no | Event name |
1047
-
1048
- ### calling.live_transcribe
1049
-
1050
- | Param | Type | Required | Notes |
1051
- |-------|------|----------|-------|
1052
- | `node_id` | UUID | YES | |
1053
- | `call_id` | UUID | YES | |
1054
- | `action` | object | YES | One key: `start{}`, `stop{}`, or `summarize{}` |
1055
-
1056
- ### calling.live_translate
1057
-
1058
- | Param | Type | Required | Notes |
1059
- |-------|------|----------|-------|
1060
- | `node_id` | UUID | YES | |
1061
- | `call_id` | UUID | YES | |
1062
- | `action` | object | YES | One key: `start{}`, `stop{}`, `summarize{}`, or `inject{}` |
1063
- | `status_url` | URL | no | |
1064
-
1065
- ### calling.join_room
1066
-
1067
- | Param | Type | Required | Notes |
1068
- |-------|------|----------|-------|
1069
- | `node_id` | UUID | YES | |
1070
- | `call_id` | UUID | YES | |
1071
- | `name` | string | YES | Room name |
1072
- | `status_url` | URL | no | |
1073
-
1074
- ### calling.leave_room
1075
-
1076
- | Param | Type | Required |
1077
- |-------|------|----------|
1078
- | `node_id` | UUID | YES |
1079
- | `call_id` | UUID | YES |
1080
-
1081
- ### calling.pay
1082
-
1083
- | Param | Type | Required | Notes |
1084
- |-------|------|----------|-------|
1085
- | `node_id` | UUID | YES | |
1086
- | `call_id` | UUID | YES | |
1087
- | `control_id` | string | YES | |
1088
- | `payment_connector_url` | URL | YES | |
1089
- | `input` | string | no | dtmf (only option) |
1090
- | `status_url` | URL | no | |
1091
- | `payment_method` | string | no | credit-card (only option) |
1092
- | `timeout` | int | no | seconds, default 5 |
1093
- | `max_attempts` | int | no | default 1 |
1094
- | `security_code` | bool | no | default true |
1095
- | `postal_code` | bool/string | no | true/false/known-postcode |
1096
- | `min_postal_code_length` | int | no | default 0 |
1097
- | `token_type` | string | no | one-time\|reusable (default: reusable) |
1098
- | `charge_amount` | string | no | Decimal, no currency prefix |
1099
- | `currency` | string | no | default "usd" |
1100
- | `language` | string | no | default "en-US" |
1101
- | `voice` | string | no | TTS voice, default "woman" |
1102
- | `description` | string | no | |
1103
- | `valid_card_types` | string | no | Space-separated: visa mastercard amex maestro discover jcb diners-club |
1104
- | `parameters` | array | no | `[{name, value}]` |
1105
- | `prompts` | array | no | See spec for prompt structure |
1106
-
1107
- ### calling.pay.stop
1108
-
1109
- | Param | Type | Required |
1110
- |-------|------|----------|
1111
- | `node_id` | UUID | YES |
1112
- | `call_id` | UUID | YES |
1113
- | `control_id` | string | YES |
1114
-
1115
- ---
1116
-
1117
- ## Messaging Namespace
1118
-
1119
- The messaging namespace is separate from calling. It handles SMS/MMS and uses different methods and event types. Messages are identified by `message_id` (not `call_id`), and there is no `node_id` or `control_id`.
1120
-
1121
- ### Correlation
1122
-
1123
- Messages use a simpler model than calls:
1124
- 1. **JSON-RPC `id`** — matches the RPC response (same as calling)
1125
- 2. **`message_id`** — returned in the `messaging.send` response and echoed in all `messaging.state` events. Route state events to the correct Message object by `message_id`.
1126
-
1127
- Implementation: maintain a `messages: Map<string, Message>` keyed by `message_id`.
1128
-
1129
- ### messaging.send
1130
-
1131
- Send an outbound SMS/MMS.
1132
-
1133
- | Param | Type | Required | Notes |
1134
- |-------|------|----------|-------|
1135
- | `context` | string | YES | Context for receiving state events |
1136
- | `to_number` | string | YES | E.164 format |
1137
- | `from_number` | string | YES | E.164 format |
1138
- | `body` | string | conditional | Required if no media |
1139
- | `media` | string[] | conditional | Required if no body — array of URLs |
1140
- | `tags` | string[] | no | Tags for searching in UI |
1141
- | `region` | string | no | Origination region |
1142
-
1143
- ```
1144
- Client → {"method":"messaging.send", "params":{
1145
- "context": "my_context",
1146
- "from_number": "+15551111111",
1147
- "to_number": "+15552222222",
1148
- "body": "Hello World",
1149
- "media": ["https://example.com/image.jpg"],
1150
- "tags": ["vip"]
1151
- }}
1152
- Server → {"result":{"code":"200", "message":"Message accepted", "message_id":"<UUID>"}}
1153
- ```
1154
-
1155
- **IMPORTANT**: The response includes `message_id`. Store this to route subsequent `messaging.state` events.
1156
-
1157
- ### Messaging Events
1158
-
1159
- Events arrive via the same `signalwire.event` mechanism as calling events, but with `messaging.*` event types.
1160
-
1161
- #### messaging.receive
1162
-
1163
- Inbound message received.
1164
-
1165
- | Field | Type | Description |
1166
- |-------|------|-------------|
1167
- | `message_id` | UUID | Message identifier |
1168
- | `context` | string | Context |
1169
- | `direction` | string | Always `"inbound"` |
1170
- | `from_number` | string | Sender (E.164) |
1171
- | `to_number` | string | Recipient (E.164) |
1172
- | `body` | string | Message body |
1173
- | `media` | string[] | Media URLs |
1174
- | `segments` | int | Number of segments |
1175
- | `message_state` | string | Always `"received"` |
1176
- | `tags` | string[] | Tags |
1177
-
1178
- ```json
1179
- {"method":"signalwire.event", "params":{
1180
- "event_type":"messaging.receive",
1181
- "params":{
1182
- "message_id":"<UUID>",
1183
- "context":"my_context",
1184
- "direction":"inbound",
1185
- "from_number":"+15553333333",
1186
- "to_number":"+15551111111",
1187
- "body":"Hello",
1188
- "media":[],
1189
- "segments":1,
1190
- "message_state":"received"
1191
- }
1192
- }}
1193
- ```
1194
-
1195
- #### messaging.state
1196
-
1197
- Outbound message state change.
1198
-
1199
- | Field | Type | Description |
1200
- |-------|------|-------------|
1201
- | `message_id` | UUID | Message identifier |
1202
- | `context` | string | Context |
1203
- | `direction` | string | Always `"outbound"` |
1204
- | `from_number` | string | Sender (E.164) |
1205
- | `to_number` | string | Recipient (E.164) |
1206
- | `body` | string | Message body |
1207
- | `media` | string[] | Media URLs |
1208
- | `segments` | int | Number of segments |
1209
- | `message_state` | string | See states below |
1210
- | `reason` | string | Present on `undelivered` and `failed` |
1211
- | `tags` | string[] | Tags |
1212
-
1213
- Message states: `queued` → `initiated` → `sent` → `delivered` (terminal)
1214
-
1215
- Failed paths: `queued` → `initiated` → `failed` or `undelivered` (terminal)
1216
-
1217
- Terminal states: `delivered`, `undelivered`, `failed`
1218
-
1219
- ### Message Object Design
1220
-
1221
- The Message object is simpler than Call — it's a data holder with state tracking:
1222
-
1223
- ```python
1224
- class Message:
1225
- message_id: str
1226
- context: str
1227
- direction: str # "inbound" or "outbound"
1228
- from_number: str
1229
- to_number: str
1230
- body: str
1231
- media: list[str]
1232
- segments: int
1233
- state: str # current message_state
1234
- reason: str # failure reason (on failed/undelivered)
1235
- tags: list[str]
1236
-
1237
- # Completion
1238
- is_done: bool # True when terminal state reached
1239
- result: RelayEvent # Terminal event (or None)
1240
-
1241
- async def wait(timeout=None) -> RelayEvent
1242
- def on(handler) # Register state change listener
1243
- ```
1244
-
1245
- The `on_completed` callback pattern from calling actions applies here too — pass it to `send_message()` and it fires when a terminal state is reached.
1246
-
1247
- ### Messaging Checklist
1248
-
1249
- - [ ] `messages` map: `message_id` → Message (for state event routing)
1250
- - [ ] `on_message` handler for inbound messages (like `on_call` for calls)
1251
- - [ ] `send_message()` returns a Message object with the `message_id` from the response
1252
- - [ ] `messaging.receive` events create a Message and invoke the `on_message` handler
1253
- - [ ] `messaging.state` events route to tracked Message by `message_id`
1254
- - [ ] Message tracks state progression and resolves on terminal state (delivered/undelivered/failed)
1255
- - [ ] Terminal messages are cleaned up from the tracking map
1256
- - [ ] `on_completed` callback supported on `send_message()`
1257
- - [ ] At least one of `body` or `media` is required for `send_message()`