Skip to content

Document SignalWire surfaces in Platform docs - #747

Open
niravcodes wants to merge 22 commits into
mainfrom
nko/surfaces
Open

niravcodes wants to merge 22 commits into
mainfrom
nko/surfaces

Conversation

@niravcodes

@niravcodes niravcodes commented Sep 29, 2026 •

Copy link
Copy Markdown
Contributor

Description

  • New Pick a product page in the Platform nav: what SWML (via the Server SDKs Agents namespace), the REST APIs, the Browser SDK, and Relay each do, when to use each, and how they combine with phone numbers, Resources, SWAIG tools, and Datasphere. Uses the Bayview Taxi example throughout.

Preview

Type of Change

  • Bug fix
  • New feature
  • Breaking change
  • Documentation update
  • Code cleanup / refactor

Related Issues

#746

Testing

  • Added/updated unit tests
  • Tested manually
  • Tested with live SignalWire credentials (if applicable)

Checklist

  • I have read the CONTRIBUTING guidelines
  • My code follows the project's style guidelines
  • I have added tests for my changes (if applicable)
  • I have updated documentation (if applicable)
  • All existing tests pass

Additional Notes

@niravcodes niravcodes changed the title Document SignalWire "surfaces" in platform UI Document SignalWire surfaces in Platform docs Sep 29, 2026
@github-actions

github-actions Bot commented Sep 29, 2026 •

Copy link
Copy Markdown
Contributor

@niravcodes
niravcodes marked this pull request as ready for review October 6, 2026 17:40

@Devon-White Devon-White left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nice framing, and the Bayview cast keeps it consistent with the AI guides. Branch still merges cleanly into main, and every /docs/ link resolves on the live site. I checked the samples against the latest Server SDKs (signalwire-sdk 3.7.6, @signalwire/sdk 3.7.1) and @signalwire/js 4.0.0-rc.5.

Blocking

  • TypeScript calling.transfer sends a malformed request on the current SDK (inline).
  • The Python active_calls loop can't run as described (inline).
  • Two factual conflicts with existing guides: Messaging SWML can be served from the Server SDK, and the fax setup step (inline).

Should fix

  • resources#in-the-dashboard breaks once #752 lands.
  • Server SDK prose names Python/TypeScript and links /reference/python/... pages in several places (inline, with the full list).
  • user_event example shape vs the SWML reference, and a call.id claim I couldn't verify (inline).

Checked and fine: the Python SWMLService dialplan renders exactly the YAML shown. The Python REST calls (set_swml_webhook, dial, ai_message, messages.create, transfer) match the 3.7.6 signatures. AgentBase.define_tool/run and AIChatClient usage are fine too, as are the SWML_BASIC_AUTH_* env var names and the Browser dial sample (passes tsc --strict). "More than thirty others" holds: the Calling API has 40 commands.

Minor: the PR body is still the empty template. Please add ## Notes for reviewers / ## Verification per the repo rules.

host: '<YOUR_SPACE>.signalwire.com',
});

await client.calling.transfer('<YOUR_CALL_ID>', {

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The TypeScript sample sends a malformed transfer. In the current Server SDK (@signalwire/sdk 3.7.1), calling.transfer(callId, dest) takes the SWML document itself as its second argument, not { dest }. With a stubbed fetch, this sample sends "params": {"dest": {"dest": {...}}}, and tsc --strict rejects it: 'dest' does not exist in type 'SWMLObject'. Pass the document directly:

await client.calling.transfer('<YOUR_CALL_ID>', {
  version: '1.0.0',
  sections: { main: [ /* ... */ ] },
});

To steer a live call,
like the one the dialplan above answered,
send it a Calling API command from anywhere, at any time.
The Python code continues the dialplan above

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The Python REST sample can't see active_calls. bayview.serve() blocks, so nothing after it in that script runs. A separate script that runs this loop has its own empty active_calls. So "continues the dialplan above and ends each call in active_calls" doesn't work as written. Either make the Python sample end one call by ID, like the TypeScript and cURL tabs, or show where the loop runs (for example a route or thread inside the same process). One example per direction is enough here, so ending one call is the simpler fix.

point a phone number at a [Messaging SWML][swml-messaging] document,
or [receive them in a Relay process][relay-receive].
Messaging SWML is a separate flavor of SWML with methods such as `reply`.
The Agents namespace generates calling SWML only,

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This contradicts the SMS guide. "Reply to incoming messages via SWML" in /docs/platform/messaging/send-and-receive-messages serves Messaging SWML from the Server SDK, using SWMLService with schema validation off and adding reply as a verb. #908 adds a TypeScript tab that does the same thing. Suggest describing what the reader can do ("the Server SDKs can serve a Messaging SWML document such as a reply") and linking that section, instead of saying they have to write YAML or JSON by hand.


Fax runs on a call.
To send one, place a call with the REST `dial` command and have its SWML run [`send_fax`][swml-send-fax].
To receive faxes, set a phone number to accept incoming calls as fax

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"Set a phone number to accept incoming calls as fax" reads like the legacy number setting. Send and receive faxes doesn't use it. That guide points the number at a SWML document that runs receive_fax, the same way it handles any other call. Suggest dropping the first half of this sentence. Also, the link text on line 510 says "First steps with fax", but /docs/platform/fax is the Fax overview. Link /docs/platform/fax/send-and-receive-faxes directly, since that's the page that walks through both directions.

[click-to-call]: /docs/browser-sdk/v4/guides/click-to-call-widget
[cfb]: /docs/call-flow-builder
[resources]: /docs/platform/resources
[resources-dashboard]: /docs/platform/resources#in-the-dashboard

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This anchor breaks once #752 merges. #752 is approved and rewrites the Resources page. ## Manage Resources / ### In the Dashboard becomes ## Create and manage Resources, so #in-the-dashboard stops resolving. Please re-check this link, and addresses#one-resource-many-addresses (which survives), against whichever lands second.

[SWML][swml] (SignalWire Markup Language) describes how a call should go:
answer, play a greeting, run an AI agent, record, transfer.
With the Agents namespace of the [Server SDKs][server-sdks],
you create an [`AgentBase`][agent-base] in Python or TypeScript,

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Prose should stay language-neutral for the Server SDKs. More SDK languages are coming, and adding one should only mean adding a code tab. "In Python or TypeScript" and the AgentBase class name belong in the code, not the sentence. Something like: "With the Agents namespace of the Server SDKs, you create an agent, give it a prompt and tools, and run it as a web server."

The conversation uses the agent's prompt, state, and SWAIG tools, as a call does.
Each SWAIG request tells your server whether the conversation is `voice` or `chat`.

From your server, the Server SDKs' [`AIChatClient`][chat-client] sends each turn.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same language-neutral point. AIChatClient and ChatGateway are named and linked to the Python reference here and in the use-case table (line 523). Other spots do the same: send_message (494), the send_sms tool action (495), Relay receive (499), send_fax/receive_fax "on its call object" (509), the datasphere skill (518, 536), Datasphere REST (536), and "the [Python] and [TypeScript] REST client references" (550). Please describe the operation and link /docs/server-sdks or the language-neutral platform guide, such as /docs/platform/ai/chat#hold-an-ai-chat-conversation-via-the-server-sdks, instead of /reference/python/... pages. The reference links at the top (agent-base, rest-client, relay-client) have the same issue.

});
```

Your fields are sent in `event.params`,

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The user_event reference says SignalWire adds call_id, node_id, and segment_id at the top level of the payload. It also says top-level fields aren't guaranteed to arrive unchanged, so put custom data under your own key. This example puts driver and plate at the top level, and the JSON below shows only call_id. Suggest nesting them, for example { "ride": { "driver": "Sam", "plate": "BAY-123" } } and event.params.ride, and showing the other added fields so the shape matches the reference.

}
```

The browser's `call.id` is the same ID the REST API takes,

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you point me to the source for this? In @signalwire/js 4.0.0-rc.5, an outbound call's id is options.callId ?? uuid(), which is generated in the browser. I couldn't confirm that the platform uses that same value as the call_id that REST call commands take. If it's verified, great. If not, I'd drop the sentence rather than leave readers guessing which ID to send.


Your server can push custom JSON to a browser that's on a call.
The SWML [`user_event`][swml-user-event] method,
the Server SDKs' [`swml_user_event`][fr-user-event] tool action,

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This links the Python swml_user_event reference from guide prose. Suggest "a Server SDK tool result" with a link to /docs/server-sdks, or the Result actions guide, so the sentence stays language-neutral.

@Devon-White
Devon-White self-requested a review November 11, 2026 15:56

@Devon-White Devon-White left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for this. Before it can merge, the inline comments from my last review still need answers, and #752 (merged 11/11) has since broken one link and contradicted one claim on the page.

Still open from my last review

  • pick-a-product.mdx: the TypeScript calling.transfer sample wraps the document in { dest }; the Python active_calls loop can't run after serve(); "Agents namespace generates calling SWML only" contradicts the SMS guide; the fax wording ("set a number to accept calls as fax", "First steps with fax"); language-neutral prose; Python-only reference links.
  • call-controls.mdx: user_event fields sit at the top level (the SWML reference says to nest custom data); the "call.id is the same ID the REST API takes" claim; the Python swml_user_event link.
  • PR description: please fill in the template, including notes for reviewers and how you verified the samples.

New since #752

  • Broken anchor (pick-a-product.mdx:41, used again near :439): /docs/platform/resources#in-the-dashboard no longer exists. Use #create-and-manage-resources.
  • AI Agent "no code" claim (:439-440): resources.mdx now says the Dashboard asks for an Agent Name and Agent URL, which point to an agent you build with the Server SDKs and host yourself. Take AI Agent out of the no-code accordion, or describe it the way resources.mdx does.

Factual fixes

  • :451: "Each SWAIG request tells your server whether the conversation is voice or chat." The webhook spec says conversation_type is not sent on function calls made during a call. Suggest: "SWAIG requests from a chat conversation carry conversation_type: chat."
  • :538: Recordings, "start them from any product": Browser SDK v4 startRecording() isn't implemented yet. Suggest "Start them from SWML, Relay, or a REST call command."
  • The page never mentions the Compatibility API, which getting-started lists as the path for existing Twilio apps. Add it, or say what the page covers. The page also overlaps the "What are you trying to build?" table on getting-started; please link the two pages to each other.
  • Tone (:57, :76-81): drop phrases like "apps of any size", "deep AI integrations", "easier maintenance and better validation". Say plainly what each option does; for example, the Agents namespace generates, validates, and serves SWML.

Suggestions

  • Add TypeScript tabs for the AgentBase, SWMLService and AIChatClient samples. The TS reference covers all three.
  • :342-343: rides is undefined, so the first tool call raises NameError. Stub it.
  • :306: rename "Execution environment" to "Where your code runs", since SWML always runs on SignalWire (as :327 says).
  • :540-550: "How the pieces work together" has a single ###. Flatten it, or add another combination.
  • :379-380: "the same commands the Relay namespace sends": "mirror" is safer unless that's verified.
  • :533: the Resource list reads as complete; write "such as".
  • Diagram: start the "calls SWAIG tools" arrow from "Live call", not the Resource, in both the SVG and the mermaid.
  • fern/llms.txt: shorten the entry to one sentence that matches the page's description (which includes AI chat).
  • Consider moving the page out of call-fabric/ to pages/ or pages/platform/core/. The slug and nav entry don't need to change.

Please merge main before the next round so the anchors can be re-checked. The branch merges cleanly today and fern docs md check passes.

- Fix the TypeScript transfer sample (pass the SWML document directly) and
  make the Python one end a single call by ID instead of looping over an
  active_calls dict that serve() never lets it reach.
- Add TypeScript tabs for the dialplan, agent, REST, and AI chat samples;
  all samples type-check or run against @signalwire/sdk 3.7.1 and
  signalwire-sdk 3.7.7. Stub the ride lookup so the agent sample runs.
- Fix the Resources anchor (#create-and-manage-resources) and describe the
  AI Agent Resource as pointing at an agent you host, per the Resources page.
- Correct claims: conversation_type is only sent on chat; the Browser SDK
  can't start recordings; Messaging SWML can be served from your server.
- Mention the Compatibility API, cross-link Get started, keep prose
  language-neutral, link guides instead of Python reference pages, and
  drop marketing phrasing.
- Nest user_event data under its own key in the Browser SDK call controls
  guide, show the fields SignalWire adds, and drop the unverified call.id claim.
- Start the SWAIG arrow at the live call in the diagram and its mermaid
  equivalent; strengthen the dashed group border in dark mode.
- Move the page next to Get started and shorten its llms.txt entry.
@Devon-White

Copy link
Copy Markdown
Collaborator

I pushed the fixes from my review (f383ebd), after merging main into the branch. Every sample now type-checks or runs against @signalwire/sdk 3.7.1 and signalwire-sdk 3.7.7, I hand-checked every new link and anchor against the live site, and fern docs md check passes. The commit message lists each change. The page moved to pages/pick-a-product.mdx; its slug is unchanged.

Not changed: the glossary <Info> pointer. Nirav, keep it or drop it, your call. The PR description template is still empty, so please fill it in.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants