@signalwire/sdk 2.0.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 (325) hide show
  1. package/.github/workflows/publish.yml +27 -0
  2. package/.github/workflows/test.yml +17 -0
  3. package/CLAUDE.md +112 -0
  4. package/README.md +254 -0
  5. package/docs/MIGRATION-2.0.md +81 -0
  6. package/docs/agent-guide.md +869 -0
  7. package/docs/agent_guide.md +1026 -0
  8. package/docs/api-reference.md +2420 -0
  9. package/docs/api_reference.md +1301 -0
  10. package/docs/architecture.md +843 -0
  11. package/docs/cli-guide.md +579 -0
  12. package/docs/cli_guide.md +448 -0
  13. package/docs/cloud_functions_guide.md +474 -0
  14. package/docs/configuration.md +422 -0
  15. package/docs/contexts-guide.md +787 -0
  16. package/docs/contexts_guide.md +511 -0
  17. package/docs/datamap-guide.md +1141 -0
  18. package/docs/datamap_guide.md +595 -0
  19. package/docs/llm_parameters.md +239 -0
  20. package/docs/mcp_gateway_reference.md +648 -0
  21. package/docs/mcp_integration.md +108 -0
  22. package/docs/prefabs-guide.md +800 -0
  23. package/docs/sdk_features.md +477 -0
  24. package/docs/security.md +436 -0
  25. package/docs/serverless-guide.md +513 -0
  26. package/docs/skills-guide.md +857 -0
  27. package/docs/skills-system.md +301 -0
  28. package/docs/skills_parameter_schema.md +392 -0
  29. package/docs/skills_system.md +467 -0
  30. package/docs/swaig-reference.md +1627 -0
  31. package/docs/swaig_reference.md +910 -0
  32. package/docs/swml_service_guide.md +600 -0
  33. package/docs/third_party_skills.md +533 -0
  34. package/docs/web_service.md +677 -0
  35. package/examples/README.md +131 -0
  36. package/examples/advanced-datamap.ts +100 -0
  37. package/examples/advanced-dynamic-config.ts +70 -0
  38. package/examples/auto-vivified.ts +94 -0
  39. package/examples/call-flow.ts +63 -0
  40. package/examples/comprehensive-dynamic.ts +125 -0
  41. package/examples/contexts-steps.ts +65 -0
  42. package/examples/custom-path.ts +45 -0
  43. package/examples/datamap-tools.ts +55 -0
  44. package/examples/datasphere-multi-instance.ts +63 -0
  45. package/examples/datasphere-serverless-env.ts +68 -0
  46. package/examples/datasphere-webhook-env.ts +66 -0
  47. package/examples/datasphere.ts +37 -0
  48. package/examples/declarative.ts +100 -0
  49. package/examples/dynamic-config.ts +54 -0
  50. package/examples/dynamic-info-gatherer.ts +69 -0
  51. package/examples/dynamic-swml-service.ts +67 -0
  52. package/examples/gather-info.ts +71 -0
  53. package/examples/gather-per-question-functions-demo.ts +140 -0
  54. package/examples/joke-agent.ts +34 -0
  55. package/examples/kubernetes-agent.ts +45 -0
  56. package/examples/llm-params.ts +69 -0
  57. package/examples/mcp-agent.ts +84 -0
  58. package/examples/mcp-gateway.ts +35 -0
  59. package/examples/multi-agent.ts +73 -0
  60. package/examples/multi-endpoint.ts +79 -0
  61. package/examples/pom-prompt.ts +71 -0
  62. package/examples/prefab-concierge.ts +47 -0
  63. package/examples/prefab-faq.ts +54 -0
  64. package/examples/prefab-info-gatherer.ts +33 -0
  65. package/examples/prefab-receptionist.ts +36 -0
  66. package/examples/prefab-survey.ts +68 -0
  67. package/examples/record-call.ts +67 -0
  68. package/examples/relay-demo.ts +33 -0
  69. package/examples/room-and-sip.ts +94 -0
  70. package/examples/serverless-lambda.ts +35 -0
  71. package/examples/session-state.ts +83 -0
  72. package/examples/simple-agent.ts +36 -0
  73. package/examples/simple-static.ts +29 -0
  74. package/examples/skills-demo.ts +38 -0
  75. package/examples/step-function-inheritance-demo.ts +124 -0
  76. package/examples/swaig-features.ts +187 -0
  77. package/examples/swml-service-routing.ts +66 -0
  78. package/examples/swml-service.ts +38 -0
  79. package/examples/tap.ts +68 -0
  80. package/examples/verb-methods.ts +45 -0
  81. package/examples/web-search-multi-instance.ts +72 -0
  82. package/examples/web-search.ts +38 -0
  83. package/examples/wikipedia.ts +36 -0
  84. package/livewire/README.md +140 -0
  85. package/livewire/docs/migration-guide.md +228 -0
  86. package/livewire/examples/livewire-basic-agent.ts +74 -0
  87. package/livewire/examples/livewire-handoff.ts +197 -0
  88. package/livewire/examples/livewire-multi-tool.ts +117 -0
  89. package/package.json +38 -0
  90. package/relay/README.md +70 -0
  91. package/relay/RELAY_IMPLEMENTATION_GUIDE.md +1257 -0
  92. package/relay/docs/call-methods.md +474 -0
  93. package/relay/docs/client-reference.md +142 -0
  94. package/relay/docs/events.md +134 -0
  95. package/relay/docs/getting-started.md +134 -0
  96. package/relay/docs/guide.md +306 -0
  97. package/relay/docs/messaging.md +182 -0
  98. package/relay/examples/relay-inbound.ts +66 -0
  99. package/relay/examples/relay-messaging.ts +71 -0
  100. package/relay/examples/relay-outbound.ts +76 -0
  101. package/rest/README.md +95 -0
  102. package/rest/docs/calling.md +273 -0
  103. package/rest/docs/client-reference.md +107 -0
  104. package/rest/docs/compat.md +204 -0
  105. package/rest/docs/fabric.md +183 -0
  106. package/rest/docs/getting-started.md +110 -0
  107. package/rest/docs/guide.md +351 -0
  108. package/rest/docs/namespaces.md +285 -0
  109. package/rest/examples/rest-10dlc-registration.ts +161 -0
  110. package/rest/examples/rest-calling-ivr-and-ai.ts +102 -0
  111. package/rest/examples/rest-calling-play-and-record.ts +91 -0
  112. package/rest/examples/rest-client.ts +65 -0
  113. package/rest/examples/rest-compat-laml.ts +210 -0
  114. package/rest/examples/rest-datasphere-search.ts +82 -0
  115. package/rest/examples/rest-fabric-conferences-and-routing.ts +144 -0
  116. package/rest/examples/rest-fabric-subscribers-and-sip.ts +108 -0
  117. package/rest/examples/rest-fabric-swml-and-callflows.ts +99 -0
  118. package/rest/examples/rest-manage-resources.ts +65 -0
  119. package/rest/examples/rest-phone-number-management.ts +197 -0
  120. package/rest/examples/rest-queues-mfa-and-recordings.ts +143 -0
  121. package/rest/examples/rest-video-rooms.ts +186 -0
  122. package/src/AgentBase.ts +2489 -0
  123. package/src/AgentServer.ts +415 -0
  124. package/src/AuthHandler.ts +256 -0
  125. package/src/ConfigLoader.ts +447 -0
  126. package/src/ContextBuilder.ts +1150 -0
  127. package/src/DataMap.ts +449 -0
  128. package/src/FunctionResult.ts +866 -0
  129. package/src/Logger.ts +337 -0
  130. package/src/PomBuilder.ts +439 -0
  131. package/src/PromptManager.ts +133 -0
  132. package/src/SWMLHandler.ts +298 -0
  133. package/src/SWMLService.ts +717 -0
  134. package/src/SchemaUtils.ts +361 -0
  135. package/src/SecurityUtils.ts +153 -0
  136. package/src/ServerlessAdapter.ts +221 -0
  137. package/src/SessionManager.ts +311 -0
  138. package/src/SslConfig.ts +118 -0
  139. package/src/SwaigFunction.ts +276 -0
  140. package/src/SwmlBuilder.ts +258 -0
  141. package/src/SwmlVerbMethods.generated.ts +234 -0
  142. package/src/TypeInference.ts +181 -0
  143. package/src/WebService.ts +619 -0
  144. package/src/cli/agent-loader.ts +166 -0
  145. package/src/cli/mock-data.ts +111 -0
  146. package/src/cli/swaig-test.ts +452 -0
  147. package/src/generateVerbTypes.ts +322 -0
  148. package/src/index.ts +167 -0
  149. package/src/livewire/index.ts +950 -0
  150. package/src/prefabs/ConciergeAgent.ts +287 -0
  151. package/src/prefabs/FAQBotAgent.ts +384 -0
  152. package/src/prefabs/InfoGathererAgent.ts +339 -0
  153. package/src/prefabs/ReceptionistAgent.ts +366 -0
  154. package/src/prefabs/SurveyAgent.ts +646 -0
  155. package/src/prefabs/index.ts +27 -0
  156. package/src/relay/Action.ts +314 -0
  157. package/src/relay/Call.ts +854 -0
  158. package/src/relay/Deferred.ts +71 -0
  159. package/src/relay/Message.ts +148 -0
  160. package/src/relay/RelayClient.ts +1036 -0
  161. package/src/relay/RelayError.ts +14 -0
  162. package/src/relay/RelayEvent.ts +892 -0
  163. package/src/relay/constants.ts +132 -0
  164. package/src/relay/index.ts +123 -0
  165. package/src/relay/types.ts +149 -0
  166. package/src/rest/HttpClient.ts +103 -0
  167. package/src/rest/RestError.ts +31 -0
  168. package/src/rest/base/BaseResource.ts +19 -0
  169. package/src/rest/base/CrudResource.ts +51 -0
  170. package/src/rest/base/CrudWithAddresses.ts +26 -0
  171. package/src/rest/index.ts +200 -0
  172. package/src/rest/namespaces/addresses.ts +32 -0
  173. package/src/rest/namespaces/calling.ts +187 -0
  174. package/src/rest/namespaces/chat.ts +20 -0
  175. package/src/rest/namespaces/compat.ts +352 -0
  176. package/src/rest/namespaces/datasphere.ts +45 -0
  177. package/src/rest/namespaces/fabric.ts +222 -0
  178. package/src/rest/namespaces/imported-numbers.ts +20 -0
  179. package/src/rest/namespaces/logs.ts +84 -0
  180. package/src/rest/namespaces/lookup.ts +21 -0
  181. package/src/rest/namespaces/mfa.ts +30 -0
  182. package/src/rest/namespaces/number-groups.ts +38 -0
  183. package/src/rest/namespaces/phone-numbers.ts +44 -0
  184. package/src/rest/namespaces/project.ts +36 -0
  185. package/src/rest/namespaces/pubsub.ts +20 -0
  186. package/src/rest/namespaces/queues.ts +33 -0
  187. package/src/rest/namespaces/recordings.ts +28 -0
  188. package/src/rest/namespaces/registry.ts +101 -0
  189. package/src/rest/namespaces/short-codes.ts +28 -0
  190. package/src/rest/namespaces/sip-profile.ts +25 -0
  191. package/src/rest/namespaces/verified-callers.ts +27 -0
  192. package/src/rest/namespaces/video.ts +165 -0
  193. package/src/rest/pagination.ts +84 -0
  194. package/src/rest/types.ts +61 -0
  195. package/src/schema.json +12250 -0
  196. package/src/skills/SkillBase.ts +547 -0
  197. package/src/skills/SkillManager.ts +415 -0
  198. package/src/skills/SkillRegistry.ts +367 -0
  199. package/src/skills/builtin/api_ninjas_trivia.ts +280 -0
  200. package/src/skills/builtin/ask_claude.ts +241 -0
  201. package/src/skills/builtin/claude_skills.ts +978 -0
  202. package/src/skills/builtin/custom_skills.ts +312 -0
  203. package/src/skills/builtin/datasphere.ts +438 -0
  204. package/src/skills/builtin/datasphere_serverless.ts +339 -0
  205. package/src/skills/builtin/datetime.ts +130 -0
  206. package/src/skills/builtin/google_maps.ts +651 -0
  207. package/src/skills/builtin/index.ts +88 -0
  208. package/src/skills/builtin/info_gatherer.ts +405 -0
  209. package/src/skills/builtin/joke.ts +191 -0
  210. package/src/skills/builtin/math.ts +142 -0
  211. package/src/skills/builtin/mcp_gateway.ts +677 -0
  212. package/src/skills/builtin/native_vector_search.ts +901 -0
  213. package/src/skills/builtin/play_background_file.ts +358 -0
  214. package/src/skills/builtin/spider.ts +869 -0
  215. package/src/skills/builtin/swml_transfer.ts +635 -0
  216. package/src/skills/builtin/weather_api.ts +248 -0
  217. package/src/skills/builtin/web_search.ts +1074 -0
  218. package/src/skills/builtin/wikipedia_search.ts +299 -0
  219. package/src/skills/index.ts +12 -0
  220. package/src/types.ts +132 -0
  221. package/tests/AgentBase.test.ts +1093 -0
  222. package/tests/AgentServer.test.ts +126 -0
  223. package/tests/AuthHandler.test.ts +133 -0
  224. package/tests/ConfigLoader.test.ts +151 -0
  225. package/tests/ContextBuilder.test.ts +108 -0
  226. package/tests/DataMap.test.ts +367 -0
  227. package/tests/EphemeralSkillCopy.test.ts +107 -0
  228. package/tests/FunctionResult.test.ts +298 -0
  229. package/tests/GracefulShutdown.test.ts +46 -0
  230. package/tests/Logger.test.ts +420 -0
  231. package/tests/PomBuilder.test.ts +228 -0
  232. package/tests/ProxyDetection.test.ts +228 -0
  233. package/tests/SWMLService.test.ts +320 -0
  234. package/tests/SWMLVerbHandler.test.ts +523 -0
  235. package/tests/SchemaUtils.test.ts +106 -0
  236. package/tests/SchemaUtils.verb.test.ts +206 -0
  237. package/tests/SecurityUtils.test.ts +192 -0
  238. package/tests/ServerlessAdapter.test.ts +222 -0
  239. package/tests/SessionManager.test.ts +257 -0
  240. package/tests/SkillBaseFeatures.test.ts +130 -0
  241. package/tests/SkillMultiInstance.test.ts +102 -0
  242. package/tests/SkillParameterSchemas.test.ts +134 -0
  243. package/tests/SkillRegistrySchema.test.ts +84 -0
  244. package/tests/SslConfig.test.ts +97 -0
  245. package/tests/SwmlBuilder.test.ts +400 -0
  246. package/tests/TypeInference.test.ts +165 -0
  247. package/tests/VerbHandlerRegistry.test.ts +128 -0
  248. package/tests/cli/mock-data.test.ts +113 -0
  249. package/tests/cli/swaig-test.test.ts +108 -0
  250. package/tests/examples.test.ts +194 -0
  251. package/tests/fixtures/scrape-parity/README.md +53 -0
  252. package/tests/fixtures/scrape-parity/expected/01_simple_article.json +5 -0
  253. package/tests/fixtures/scrape-parity/expected/02_class_based_noise.json +5 -0
  254. package/tests/fixtures/scrape-parity/expected/03_nested_containers.json +5 -0
  255. package/tests/fixtures/scrape-parity/expected/04_bare_body.json +5 -0
  256. package/tests/fixtures/scrape-parity/expected/05_malformed.json +5 -0
  257. package/tests/fixtures/scrape-parity/expected/06_multi_class.json +5 -0
  258. package/tests/fixtures/scrape-parity/expected/07_anchor_pattern.json +5 -0
  259. package/tests/fixtures/scrape-parity/expected/08_inline_script.json +5 -0
  260. package/tests/fixtures/scrape-parity/expected/09_whitespace_nbsp.json +5 -0
  261. package/tests/fixtures/scrape-parity/expected/10_entity_unicode.json +5 -0
  262. package/tests/fixtures/scrape-parity/expected/11_cdata_comments.json +5 -0
  263. package/tests/fixtures/scrape-parity/expected/12_deep_nested_removals.json +5 -0
  264. package/tests/fixtures/scrape-parity/html/01_simple_article.html +18 -0
  265. package/tests/fixtures/scrape-parity/html/02_class_based_noise.html +18 -0
  266. package/tests/fixtures/scrape-parity/html/03_nested_containers.html +13 -0
  267. package/tests/fixtures/scrape-parity/html/04_bare_body.html +9 -0
  268. package/tests/fixtures/scrape-parity/html/05_malformed.html +11 -0
  269. package/tests/fixtures/scrape-parity/html/06_multi_class.html +18 -0
  270. package/tests/fixtures/scrape-parity/html/07_anchor_pattern.html +12 -0
  271. package/tests/fixtures/scrape-parity/html/08_inline_script.html +17 -0
  272. package/tests/fixtures/scrape-parity/html/09_whitespace_nbsp.html +21 -0
  273. package/tests/fixtures/scrape-parity/html/10_entity_unicode.html +10 -0
  274. package/tests/fixtures/scrape-parity/html/11_cdata_comments.html +13 -0
  275. package/tests/fixtures/scrape-parity/html/12_deep_nested_removals.html +24 -0
  276. package/tests/fixtures/scrape-parity/python_extract.py +109 -0
  277. package/tests/livewire/livewire.test.ts +780 -0
  278. package/tests/mcp.test.ts +221 -0
  279. package/tests/prefabs/prefabs.test.ts +1093 -0
  280. package/tests/relay/Action.test.ts +392 -0
  281. package/tests/relay/Call.test.ts +535 -0
  282. package/tests/relay/Deferred.test.ts +71 -0
  283. package/tests/relay/Message.test.ts +164 -0
  284. package/tests/relay/RelayClient.test.ts +779 -0
  285. package/tests/relay/RelayEvent.test.ts +463 -0
  286. package/tests/relay/helpers.ts +79 -0
  287. package/tests/rest/HttpClient.test.ts +274 -0
  288. package/tests/rest/RestError.test.ts +53 -0
  289. package/tests/rest/calling.test.ts +156 -0
  290. package/tests/rest/client.test.ts +197 -0
  291. package/tests/rest/compat.test.ts +335 -0
  292. package/tests/rest/datasphere.test.ts +71 -0
  293. package/tests/rest/fabric.test.ts +186 -0
  294. package/tests/rest/helpers.ts +95 -0
  295. package/tests/rest/logs.test.ts +68 -0
  296. package/tests/rest/pagination.test.ts +133 -0
  297. package/tests/rest/registry.test.ts +94 -0
  298. package/tests/rest/relay-rest.test.ts +290 -0
  299. package/tests/rest/video.test.ts +173 -0
  300. package/tests/setup.ts +6 -0
  301. package/tests/skills/SkillBase.test.ts +108 -0
  302. package/tests/skills/SkillManager.test.ts +268 -0
  303. package/tests/skills/SkillRegistry.test.ts +176 -0
  304. package/tests/skills/builtin.test.ts +1472 -0
  305. package/tests/skills/claude-skills.test.ts +54 -0
  306. package/tests/skills/custom-skills.test.ts +53 -0
  307. package/tests/skills/datasphere-serverless.test.ts +70 -0
  308. package/tests/skills/datasphere.test.ts +107 -0
  309. package/tests/skills/datetime.test.ts +101 -0
  310. package/tests/skills/google-maps.test.ts +78 -0
  311. package/tests/skills/info-gatherer.test.ts +411 -0
  312. package/tests/skills/joke.test.ts +81 -0
  313. package/tests/skills/math.test.ts +68 -0
  314. package/tests/skills/mcp-gateway.test.ts +101 -0
  315. package/tests/skills/play-background.test.ts +54 -0
  316. package/tests/skills/spider.test.ts +108 -0
  317. package/tests/skills/swml-transfer.test.ts +178 -0
  318. package/tests/skills/trivia.test.ts +54 -0
  319. package/tests/skills/vector-search.test.ts +135 -0
  320. package/tests/skills/weather-api.test.ts +77 -0
  321. package/tests/skills/web-search-parity.test.ts +59 -0
  322. package/tests/skills/web-search.test.ts +103 -0
  323. package/tests/skills/wikipedia.test.ts +63 -0
  324. package/tsconfig.json +18 -0
  325. package/vitest.config.ts +9 -0
@@ -0,0 +1,1257 @@
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()`