[Manny-r31]

Summary

• Adds Coach live calls with an AI sidecar (/docs/swml/guides/ai-sidecar), a basics guide for the ai_sidecar SWML method. Its structure and phrasing follow the call queues guide in docs(voice): add call queues guide #780.
• Running example: the document from the ai_sidecar reference page's example: a sales-copilot prompt, hints, and a lookup_account SWAIG function. Webhook URLs and phone numbers are swapped for placeholders. The server answers lookup_account from a stand-in CRM record, so the reader sees a tool call and a tip.
• Shared sections:
  • The SWML and REST comparison table, prepare, and how the AI sidecar works.
  • Run the sidecar server: a short Python or TypeScript SWMLService that answers the tool at /swaig and prints sidecar callbacks at /events.
• Coach a call via SWML: the document goes in a hosted SWML Script, whose YAML and JSON the reader pastes into the Dashboard. The reader assigns it to a number and calls between two phones.
• Coach a call in progress via REST: attach a sidecar by call ID, then stop it while the call continues.
• Left to the reference pages and Next steps cards: REST ask and poke, tool actions, and options.
• Reference example: drops answer_on_bridge: true from the ai_sidecar reference example, YAML and JSON. The document answers the call before connect runs, so the setting has no effect (mod_infrastructure/swml.c:4827-4832). The guide's document matches the trimmed example.
• Nav and index: the page lives in the folder-driven Recipes section of the SWML Guides tab, so swml.yml is unchanged. The fern/llms.txt AI sidecar entry now points at the guide.

Notes for reviewers

• Hosted script, not served SWML: the document is static, so a hosted SWML Script delivers it. The server only receives callbacks, which avoids an External URL with credentials embedded in it.
• SDK gap: neither SDK's REST client wraps the calling.ai_sidecar* commands, so the REST section uses the existing EndpointRequestSnippet examples. Per author review, the page doesn't call out the gap.
• TypeScript SDK quirk the sample works around: registerRoutingCallback redirects unless the callback returns exactly null, so the sample returns null, never undefined. Its /swaig route also neither awaits a handler's promise nor cleanly serializes a FunctionResult, so the tool handler is synchronous and returns .toDict().
• Facts trace to the platform source (mod_openai sidecar implementation, mod_infrastructure schema), the TypeSpec, and the existing reference pages. Internal detail is kept out: engine, transport, Relay topic names, and billing SKUs.
  • ai_sidecar answers the call itself, so the document has no answer.
  • After calling.ai_sidecar.stop, the call can take a new sidecar.
• The existing ai_sidecar reference pages disagree with the source in places. The guide avoids these claims, and this PR doesn't fix them; that's a follow-up:
  • They say a sidecar and live_transcribe can't run on one call. The source allows it.
  • They list prompt variables (${global_data.x}, ${local_date}, ${session_uuid}) that the source mostly doesn't support.
  • They say params.transcribe_prompt biases speech recognition. It never reaches the speech engine.
  • permissions.swaig_set_global_data isn't enforced.
  • The settings, back_to_back_functions, extensive_data, and set_meta_data actions do nothing in a sidecar.
  • They say final is always the last callback. After a transfer or hangup action, it arrives before stop.
  • The reference index exposes internal detail: the Relay topic name, curl_code, and the speech engine vendor.
• Code block titles keep the template's <Language> — <client> format.

Verification

• yarn fern-md-check: passes (all MDX files valid).
• yarn fern-check: only the Fern-auth-gated "missing redirects" check fails locally because this machine isn't logged in to Fern. The one warning is the existing accent-color contrast warning.
• Samples were reviewed statically against the pinned SDK source; none were run. The author is testing them against a live call.
  • Python signalwire-sdk==3.4.1: SWMLService basic auth, define_tool with /swaig dispatch (it reads arguments from argument.parsed, the shape the sidecar sends), and register_routing_callback, which runs on a non-empty POST after the auth check.
  • TypeScript @signalwire/sdk@2.0.5: SWMLService basic auth, defineTool with /swaig dispatch, registerRoutingCallback, and FunctionResult.toDict().
• Internal links are checked against slug: frontmatter. Anchors are checked by hand: #callback-types, #answer-a-call-via-swml, #prepare-for-your-first-call, and the in-page anchors.

Preview

• /docs/swml/guides/ai-sidecar
• /docs/swml/reference/calling/ai-sidecar (example only)

🤖 Generated with Claude Code

[github-actions]

🌿 Preview

https://signalwire-preview-docs-783.docs.buildwithfern.com/docs

---

View workflow run