Repository navigation
Document SignalWire surfaces in Platform docs - #747
niravcodes wants to merge 22 commits into
Conversation
# Conflicts: # fern/products/platform/platform.yml
Devon-White
left a comment
There was a problem hiding this comment.
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.transfersends a malformed request on the current SDK (inline). - The Python
active_callsloop 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-dashboardbreaks once #752 lands.- Server SDK prose names Python/TypeScript and links
/reference/python/...pages in several places (inline, with the full list). user_eventexample shape vs the SWML reference, and acall.idclaim 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>', { |
There was a problem hiding this comment.
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 |
There was a problem hiding this comment.
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, |
There was a problem hiding this comment.
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 |
There was a problem hiding this comment.
"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 |
There was a problem hiding this comment.
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, |
There was a problem hiding this comment.
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. |
There was a problem hiding this comment.
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`, |
There was a problem hiding this comment.
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, |
There was a problem hiding this comment.
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, |
There was a problem hiding this comment.
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
left a comment
There was a problem hiding this comment.
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 TypeScriptcalling.transfersample wraps the document in{ dest }; the Pythonactive_callsloop can't run afterserve(); "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_eventfields sit at the top level (the SWML reference says to nest custom data); the "call.idis the same ID the REST API takes" claim; the Pythonswml_user_eventlink.- 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-dashboardno longer exists. Use#create-and-manage-resources. - AI Agent "no code" claim (
:439-440):resources.mdxnow 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 wayresources.mdxdoes.
Factual fixes
:451: "Each SWAIG request tells your server whether the conversation isvoiceorchat." The webhook spec saysconversation_typeis not sent on function calls made during a call. Suggest: "SWAIG requests from a chat conversation carryconversation_type: chat.":538: Recordings, "start them from any product": Browser SDK v4startRecording()isn't implemented yet. Suggest "Start them from SWML, Relay, or a REST call command."- The page never mentions the Compatibility API, which
getting-startedlists 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 ongetting-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:ridesis undefined, so the first tool call raisesNameError. Stub it.:306: rename "Execution environment" to "Where your code runs", since SWML always runs on SignalWire (as:327says).: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'sdescription(which includes AI chat).- Consider moving the page out of
call-fabric/topages/orpages/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.
|
I pushed the fixes from my review (f383ebd), after merging main into the branch. Every sample now type-checks or runs against Not changed: the glossary |
Description
Preview
Type of Change
Related Issues
#746
Testing
Checklist
Additional Notes