diff --git a/fern/assets/images/img/how-apps-are-built-themed.svg b/fern/assets/images/img/how-apps-are-built-themed.svg
new file mode 100644
index 0000000000..2dc4c52d72
--- /dev/null
+++ b/fern/assets/images/img/how-apps-are-built-themed.svg
@@ -0,0 +1,103 @@
+
diff --git a/fern/llms.txt b/fern/llms.txt
index c4bb5bf947..845f682f40 100644
--- a/fern/llms.txt
+++ b/fern/llms.txt
@@ -49,6 +49,7 @@ Find the task that matches what you want to build, how your application connects
### Learn the platform and get started
- [Get started](/docs/platform/getting-started): Walkthrough of your Space, the build paths, and the core concepts.
+- [Pick the right SignalWire product](/docs/platform/pick-a-product): Compare SWML, the REST APIs, the Browser SDK, and Relay, and match each calling, AI chat, messaging, or fax use case to one.
- [Create an account](/docs/platform/signing-up-for-a-space): Open a new Space on the SignalWire platform.
- [API credentials](/docs/platform/your-signalwire-api-space): Find the Project ID and API token that SDKs and APIs use to authenticate.
- [Projects and Subprojects](/docs/platform/projects): How a SignalWire Space, its Projects, and their Subprojects fit together, how to structure them for customers, environments, and teams, and how to manage them in the Dashboard and through the API.
diff --git a/fern/products/browser-sdk/pages/v4/guides/build-voice-video/call-controls.mdx b/fern/products/browser-sdk/pages/v4/guides/build-voice-video/call-controls.mdx
index c642735576..69c83e71d2 100644
--- a/fern/products/browser-sdk/pages/v4/guides/build-voice-video/call-controls.mdx
+++ b/fern/products/browser-sdk/pages/v4/guides/build-voice-video/call-controls.mdx
@@ -137,6 +137,43 @@ call.status$
For interactive dialpads (digits sent as the user presses), wire
the button click directly — by that point the call is connected.
+## Receive user events from the call
+
+Your server can push custom JSON to a browser that's on a call.
+The SWML [`user_event`][swml-user-event] method,
+a Server SDK tool result's [user event action][fr-user-event],
+and the REST [`calling.user_event`][call-commands] command
+each fire a `user_event` on the call.
+Subscribe to it with [`subscribe`]:
+
+```js
+call.subscribe("user_event").subscribe((event) => {
+ const { driver, plate } = event.params.ride;
+ driverName.textContent = driver;
+ plateNumber.textContent = plate;
+});
+```
+
+Your data arrives in `event.params`.
+SignalWire adds call details such as `call_id`, `node_id`, and `segment_id` at the top level of `params`,
+so put your own fields under a key of your own, such as `ride`, to keep them from colliding.
+The event `{ "ride": { "driver": "Sam", "plate": "BAY-123" } }` reaches the browser with this shape:
+
+```json
+{
+ "event_type": "user_event",
+ "params": {
+ "ride": {
+ "driver": "Sam",
+ "plate": "BAY-123"
+ },
+ "call_id": "",
+ "node_id": "",
+ "segment_id": ""
+ }
+}
+```
+
## Moderation — check the capability first
Methods on other participants exist (`participant.mute()`,
@@ -245,7 +282,7 @@ per-class reference:
- [`Participant`] — mute, deaf, hand raise, audio processing, server-mixed volumes; also the surface for moderation actions on other members ([`remove`], [`end`], [`setPosition`]).
- [`SelfParticipant`] — adds [`enableStudioAudio`] / [`disableStudioAudio`] on top of `Participant`.
-- [`WebRTCCall`] — session-level controls: [`hangup`], [`sendDigits`], [`toggleLock`], [`toggleHold`], [`transfer`], local-mic pipeline ([`setLocalMicrophoneGain`], [`localAudioLevel$`], [`localSpeaking$`], [`enablePushToTalk`], [`setPushToTalkActive`]).
+- [`WebRTCCall`] — session-level controls: [`hangup`], [`sendDigits`], [`toggleLock`], [`toggleHold`], [`transfer`], custom events ([`subscribe`]), local-mic pipeline ([`setLocalMicrophoneGain`], [`localAudioLevel$`], [`localSpeaking$`], [`enablePushToTalk`], [`setPushToTalkActive`]).
- [`SelfCapabilities`] — server-authoritative flags for gating moderation UI; see [Capabilities](/docs/browser-sdk/v4/guides/capabilities).
[reference]: /docs/browser-sdk/v4/reference
@@ -280,6 +317,10 @@ per-class reference:
[`toggleLock`]: /docs/browser-sdk/v4/reference/webrtc-call/toggle-lock
[`toggleHold`]: /docs/browser-sdk/v4/reference/webrtc-call/toggle-hold
[`transfer`]: /docs/browser-sdk/v4/reference/webrtc-call/transfer
+[`subscribe`]: /docs/browser-sdk/v4/reference/webrtc-call/subscribe
+[swml-user-event]: /docs/swml/reference/calling/user-event
+[fr-user-event]: /docs/server-sdks/guides/result-actions
+[call-commands]: /docs/apis/rest/calls/call-commands
[`setLocalMicrophoneGain`]: /docs/browser-sdk/v4/reference/webrtc-call/set-local-microphone-gain
[`enablePushToTalk`]: /docs/browser-sdk/v4/reference/webrtc-call/enable-push-to-talk
[`setPushToTalkActive`]: /docs/browser-sdk/v4/reference/webrtc-call/set-push-to-talk-active
diff --git a/fern/products/platform/pages/getting-started.mdx b/fern/products/platform/pages/getting-started.mdx
index 35277d93f9..e689111827 100644
--- a/fern/products/platform/pages/getting-started.mdx
+++ b/fern/products/platform/pages/getting-started.mdx
@@ -46,6 +46,8 @@ The Dashboard's left navigation includes **My Resources**, **Click-to-Call**, **
Let's begin by figuring out the best way for you to build.
The right approach depends on what you're creating and how you prefer to work.
+To compare the products side by side and see how they combine,
+see [Pick the right SignalWire product](/docs/platform/pick-a-product).
### What are you trying to build?
diff --git a/fern/products/platform/pages/pick-a-product.mdx b/fern/products/platform/pages/pick-a-product.mdx
new file mode 100644
index 0000000000..d37bd7cab6
--- /dev/null
+++ b/fern/products/platform/pages/pick-a-product.mdx
@@ -0,0 +1,684 @@
+---
+title: Pick the right SignalWire product
+sidebar-title: Pick a product
+subtitle: What each product does, when to use it, and how they work together
+slug: pick-a-product
+description: Compare SignalWire's products (SWML through the Server SDKs, the REST APIs, the Browser SDK, and Relay), see which one fits each calling, AI chat, messaging, or fax use case, and combine them with phone numbers, Resources, tools, and Datasphere.
+max-toc-depth: 3
+---
+
+[swml]: /docs/swml
+[swml-ai]: /docs/swml/reference/calling/ai
+[swml-send-sms]: /docs/swml/reference/calling/send-sms
+[swml-send-fax]: /docs/swml/reference/calling/send-fax
+[swml-receive-fax]: /docs/swml/reference/calling/receive-fax
+[swml-messaging]: /docs/swml/reference/messaging
+[server-sdks]: /docs/server-sdks
+[sdk-quickstart]: /docs/server-sdks/guides/quickstart
+[agent-base]: /docs/server-sdks/guides/agent-base
+[result-actions]: /docs/server-sdks/guides/result-actions
+[datasphere-skill]: /docs/server-sdks/guides/builtin-skills#datasphere
+[rest-client]: /docs/server-sdks/guides/rest-client
+[relay-client]: /docs/server-sdks/guides/relay-client
+[rest-api]: /docs/apis
+[call-commands]: /docs/apis/rest/calls/call-commands
+[create-message]: /docs/apis/rest/messages/create-message
+[purchase-number]: /docs/apis/rest/phone-numbers/purchase-phone-number
+[create-subscriber]: /docs/apis/rest/subscribers/create-subscriber
+[subscriber-token]: /docs/apis/rest/subscribers/tokens/create-subscriber-token
+[list-recordings]: /docs/apis/rest/recordings/list-call-recordings
+[datasphere-create]: /docs/apis/rest/documents/create-document
+[browser-sdk]: /docs/browser-sdk/v4/guides/overview
+[browser-auth]: /docs/browser-sdk/v4/guides/authentication
+[browser-inbound]: /docs/browser-sdk/v4/guides/inbound-calls
+[click-to-call]: /docs/browser-sdk/v4/guides/click-to-call-widget
+[cfb]: /docs/call-flow-builder
+[compat]: /docs/compatibility-api
+[getting-started]: /docs/platform/getting-started
+[resources]: /docs/platform/resources
+[resources-dashboard]: /docs/platform/resources#create-and-manage-resources
+[addresses]: /docs/platform/addresses
+[subscribers]: /docs/platform/subscribers
+[phone-numbers]: /docs/platform/phone-numbers
+[webhooks]: /docs/platform/webhooks
+[api-credentials]: /docs/platform/your-signalwire-api-space
+[tool-calling]: /docs/platform/ai/tool-calling
+[make-receive-calls]: /docs/platform/voice/make-and-receive-calls
+[fax-guide]: /docs/platform/fax/send-and-receive-faxes
+[sms-relay-send]: /docs/platform/messaging/send-and-receive-messages#send-a-message-via-websocket-relay
+[sms-relay-receive]: /docs/platform/messaging/send-and-receive-messages#receive-and-reply-to-messages-via-websocket-relay
+[sms-swml-reply]: /docs/platform/messaging/send-and-receive-messages#reply-to-incoming-messages-via-swml
+[ai-chat]: /docs/platform/ai/chat
+[ai-chat-sdk]: /docs/platform/ai/chat#hold-an-ai-chat-conversation-via-the-server-sdks
+[ai-chat-web]: /docs/platform/ai/chat#hold-an-ai-chat-conversation-from-a-web-page
+[ai-chat-sms]: /docs/platform/ai/chat#hold-an-ai-chat-conversation-over-sms-text-messages
+[chat-api]: /docs/apis/rest/ai-chat/chat-methods
+
+A SignalWire app can [make and receive phone calls][make-receive-calls] with an AI agent,
+put calls and chat in a web page,
+and text your customers.
+You build it from four products (SWML, the REST APIs, the Browser SDK, and Relay),
+and most apps combine more than one.
+This page explains what each product does, which one fits your use case, and how they fit together.
+For the setup steps that come first, see [Get started][getting-started].
+
+Calls are where the products differ most, so most of this page is about calls.
+[Text conversations with an AI agent](#text-conversations-with-an-ai-agent) covers AI chat,
+and [Messaging and fax](#messaging-and-fax) covers texting and faxing.
+If you're moving an existing Twilio application,
+start with the [Compatibility API][compat] instead.
+It replaces Twilio's REST API and TwiML with few code changes, but it doesn't support AI,
+so this page covers SignalWire's native products.
+
+## How most SignalWire apps are built
+
+Write your AI agents and call flows as SWML with the Agents namespace of the Server SDKs,
+and use its REST namespace to send commands to live calls and manage your Resources.
+
+A SWML script is a JSON or YAML document that defines the dialplan:
+a set of rules for how the call proceeds and how it responds to the caller,
+such as forwarding the call, recording a voicemail, or running a full IVR system.
+The Agents namespace generates, validates, and serves that document,
+and can change it for each call based on the request.
+SWML's [`ai`][swml-ai] method runs a conversation with an AI agent on the call,
+and SWML methods can send status callbacks to your server as the call progresses.
+
+
+
+
+
+
+
+
+
+```mermaid
+flowchart LR
+ Caller["Caller phone · SIP · browser"]
+ subgraph SignalWire["SignalWire"]
+ Address["Phone number or Address"]
+ Resource["Resource SWML Script · external URL"]
+ Call(("Live call"))
+ Platform["Your Space numbers · Resources · Subscribers"]
+ end
+ subgraph App["Your server application"]
+ Systems["Your business logic bookings · data · rules"]
+ subgraph SDKs["Server SDKs"]
+ Agent["Agent Agents namespace"]
+ Backend["REST client REST namespace"]
+ end
+ end
+ Caller --> Address
+ Address --> Resource
+ Resource --> Call
+ Resource -- "fetches SWML" --> Agent
+ Call -- "calls SWAIG tools" --> Agent
+ Agent -- "looks up data" --> Systems
+ Backend -- "call commands over HTTP" --> Call
+ Backend -- "provisions" --> Platform
+```
+
+
+
+1. A phone number or [Address][addresses] points at a [Resource][resources].
+ For a call you build in code,
+ that Resource is a SWML Script set to an external URL
+ that points at the agent running on your server.
+2. When a call arrives,
+ SignalWire sends your server a POST request with the call context,
+ and runs the SWML document your server returns:
+ answering, speaking, listening, recording, and running the AI conversation.
+3. When the AI needs data or needs to act, such as looking up a booking,
+ it calls a tool on your server through SWAIG (the SignalWire AI Gateway).
+ The reply can steer the conversation and trigger actions on the call.
+4. At any point,
+ your backend can send the call a command through the REST APIs:
+ inject a message into the conversation, start a recording, play audio, or transfer the call.
+
+For example, this dialplan for Bayview Taxi
+asks the caller to press 1 for Ada, the AI dispatcher, or 2 for a person,
+then routes the call.
+When Ada's conversation ends,
+her `post_prompt` asks the AI for a summary,
+and SignalWire posts it to the `post_prompt_url` on your server.
+The Python and TypeScript versions each generate the SWML in the YAML tab.
+
+
+
+```python title="Python — Agents"
+from signalwire import SWMLService
+
+bayview = SWMLService(name="bayview-taxi", route="/bayview")
+
+bayview.answer()
+bayview.prompt(
+ play=["say:Thanks for calling Bayview Taxi. Press 1 to book with Ada, our AI dispatcher, or 2 to speak with a person."],
+ max_digits=1,
+)
+bayview.switch(
+ variable="prompt_value",
+ case={
+ "1": [{"execute": {"dest": "ada"}}],
+ "2": [{"execute": {"dest": "person"}}],
+ },
+ default=[{"play": {"url": "say:Sorry, I didn't get that. Goodbye."}}, {"hangup": {}}],
+)
+
+bayview.add_section("ada")
+bayview.add_verb_to_section("ada", "ai", {
+ "prompt": {"text": "You are Ada, the dispatcher for Bayview Taxi. Help the caller book a ride."},
+ "post_prompt": {"text": "Summarize the call in two sentences, including the pickup address."},
+ "post_prompt_url": "https://example.com/call-summary",
+})
+
+bayview.add_section("person")
+bayview.add_verb_to_section("person", "connect", {"to": ""})
+
+bayview.serve()
+```
+
+```typescript title="TypeScript — Agents"
+import { SWMLService } from '@signalwire/sdk';
+
+const bayview = new SWMLService({ name: 'bayview-taxi', route: '/bayview' });
+
+bayview
+ .getBuilder()
+ .answer()
+ .prompt({
+ play: ['say:Thanks for calling Bayview Taxi. Press 1 to book with Ada, our AI dispatcher, or 2 to speak with a person.'],
+ max_digits: 1,
+ })
+ .switch({
+ variable: 'prompt_value',
+ case: {
+ '1': [{ execute: { dest: 'ada' } }],
+ '2': [{ execute: { dest: 'person' } }],
+ },
+ default: [{ play: { url: "say:Sorry, I didn't get that. Goodbye." } }, { hangup: {} }],
+ });
+
+bayview.addSection('ada');
+bayview.addVerbToSection('ada', 'ai', {
+ prompt: { text: 'You are Ada, the dispatcher for Bayview Taxi. Help the caller book a ride.' },
+ post_prompt: { text: 'Summarize the call in two sentences, including the pickup address.' },
+ post_prompt_url: 'https://example.com/call-summary',
+});
+
+bayview.addSection('person');
+bayview.addVerbToSection('person', 'connect', { to: '' });
+
+await bayview.serve();
+```
+
+```yaml title="YAML"
+version: 1.0.0
+sections:
+ main:
+ - answer: {}
+ - prompt:
+ play:
+ - say:Thanks for calling Bayview Taxi. Press 1 to book with Ada, our AI dispatcher,
+ or 2 to speak with a person.
+ max_digits: 1
+ - switch:
+ variable: prompt_value
+ case:
+ '1':
+ - execute:
+ dest: ada
+ '2':
+ - execute:
+ dest: person
+ default:
+ - play:
+ url: say:Sorry, I didn't get that. Goodbye.
+ - hangup: {}
+ ada:
+ - ai:
+ prompt:
+ text: You are Ada, the dispatcher for Bayview Taxi. Help the caller book a
+ ride.
+ post_prompt:
+ text: Summarize the call in two sentences, including the pickup address.
+ post_prompt_url: https://example.com/call-summary
+ person:
+ - connect:
+ to:
+```
+
+
+
+The Server SDKs protect your server with basic auth.
+Set `SWML_BASIC_AUTH_USER` and `SWML_BASIC_AUTH_PASSWORD` environment variables,
+and put the same credentials in the SWML Script Resource's URL,
+as in `https://user:pass@your-server.com/bayview`.
+
+To steer a live call,
+like the one the dialplan above answered,
+send it a Calling API command from anywhere, at any time.
+This one ends a call with a message:
+
+
+
+```python title="Python — REST client"
+from signalwire.rest import RestClient
+
+client = RestClient(project="", token="", host=".signalwire.com")
+
+client.calling.transfer(
+ "",
+ dest={
+ "version": "1.0.0",
+ "sections": {
+ "main": [
+ {"play": {"url": "say:Sorry, we need to end this call for server maintenance. Please call back in 20 minutes."}},
+ {"hangup": {}},
+ ]
+ },
+ },
+)
+```
+
+```typescript title="TypeScript — REST client"
+import { RestClient } from '@signalwire/sdk';
+
+const client = new RestClient({
+ project: '',
+ token: '',
+ host: '.signalwire.com',
+});
+
+await client.calling.transfer('', {
+ version: '1.0.0',
+ sections: {
+ main: [
+ { play: { url: 'say:Sorry, we need to end this call for server maintenance. Please call back in 20 minutes.' } },
+ { hangup: {} },
+ ],
+ },
+});
+```
+
+```bash title="cURL — Calling API"
+curl -X POST "https://.signalwire.com/api/calling/calls" \
+ -u ":" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "id": "",
+ "command": "calling.transfer",
+ "params": {
+ "dest": {
+ "version": "1.0.0",
+ "sections": {
+ "main": [
+ { "play": { "url": "say:Sorry, we need to end this call for server maintenance. Please call back in 20 minutes." } },
+ { "hangup": {} }
+ ]
+ }
+ }
+ }
+ }'
+```
+
+
+
+Replace the placeholders with the values from your [API credentials][api-credentials] page
+and `` with the ID of the call to end.
+
+## The products
+
+| Product | Description | Where your code runs | Use cases |
+|---|---|---|---|
+| SWML | JSON or YAML call flow, generated by the Server SDKs | Your web server, or nowhere when SignalWire hosts the document | Call flows and AI agents (the recommended starting point) |
+| REST APIs | HTTP endpoints for resources, messaging, and call commands | Any server or script | Provisioning, outbound calls and messages, and controlling calls in progress |
+| Browser SDK | JavaScript client for voice, video, and chat | The user's browser | Calling and chat from a web page |
+| Relay | Persistent connection that streams call events to your code | A long-running process you host | Event-driven, step-by-step call control |
+
+### SWML
+
+[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 agent][agent-base],
+give it a prompt and tools,
+and run it as a web server.
+
+Use it for any call your code handles, with or without AI.
+For a fixed flow with no server of your own,
+you can paste the document into a SWML Script in your Dashboard,
+and SignalWire hosts it.
+
+The call runs on SignalWire,
+so your server only answers short HTTP requests:
+one for the document and one for each tool call.
+Nothing holds a connection open,
+so your server stays stateless and deploys anywhere that serves HTTPS.
+The [Server SDKs quickstart][sdk-quickstart] builds your first agent.
+This one gives Ada a tool that looks up a ride:
+
+
+
+```python title="Python — Agents"
+from signalwire import AgentBase, FunctionResult
+
+
+def lookup_ride(booking_id):
+ """Stands in for your booking system."""
+ return {"booking_id": booking_id, "eta": 7}
+
+
+agent = AgentBase(name="ada", route="/agent")
+agent.prompt_add_section("Role", body="You are Ada, the dispatcher for Bayview Taxi. Help callers check on their ride.")
+
+
+def check_ride(args, raw_data):
+ ride = lookup_ride(args["booking_id"])
+ return FunctionResult(f"The driver arrives in {ride['eta']} minutes.")
+
+
+agent.define_tool(
+ name="check_ride",
+ description="Look up a ride by its booking ID",
+ parameters={
+ "type": "object",
+ "properties": {"booking_id": {"type": "string", "description": "The booking ID"}},
+ "required": ["booking_id"],
+ },
+ handler=check_ride,
+)
+
+agent.run()
+```
+
+```typescript title="TypeScript — Agents"
+import { AgentBase, FunctionResult } from '@signalwire/sdk';
+
+// Stands in for your booking system.
+function lookupRide(bookingId: string) {
+ return { bookingId, eta: 7 };
+}
+
+const agent = new AgentBase({ name: 'ada', route: '/agent' });
+agent.promptAddSection('Role', {
+ body: 'You are Ada, the dispatcher for Bayview Taxi. Help callers check on their ride.',
+});
+
+agent.defineTool({
+ name: 'check_ride',
+ description: 'Look up a ride by its booking ID',
+ parameters: {
+ type: 'object',
+ properties: { booking_id: { type: 'string', description: 'The booking ID' } },
+ required: ['booking_id'],
+ },
+ handler: (args) => {
+ const ride = lookupRide(String(args.booking_id));
+ return new FunctionResult(`The driver arrives in ${ride.eta} minutes.`);
+ },
+});
+
+await agent.run();
+```
+
+
+
+Replace the ride lookup with a call to your booking system.
+
+### REST APIs
+
+The [REST APIs][rest-api] cover everything that isn't the call flow itself.
+You buy phone numbers,
+create Resources and Subscribers,
+issue client tokens,
+send messages,
+fetch recordings and logs,
+and upload documents to Datasphere.
+From code, the [REST namespace][rest-client] of the Server SDKs wraps each endpoint in a method.
+
+The Calling API controls live calls.
+Its `dial` command starts a new call,
+and its [call commands][call-commands] act on a call in progress:
+`calling.play`, `calling.record`, `calling.transfer`, `calling.ai_message`, `calling.ai_hold`, `calling.end`,
+and more than thirty others.
+Relay offers the same kind of call control over its WebSocket.
+
+
+
+```python title="Python — REST client"
+from signalwire.rest import RestClient
+
+client = RestClient(project="", token="", host=".signalwire.com")
+
+client.phone_numbers.set_swml_webhook("", url="https://example.com/bayview")
+client.calling.dial(from_="", to="", url="https://example.com/bayview")
+client.calling.ai_message("", role="system", message_text="Driver Sam has arrived.")
+client.messages.create(from_="", to="", body="Your Bayview Taxi driver is outside.")
+```
+
+```typescript title="TypeScript — REST client"
+import { RestClient } from '@signalwire/sdk';
+
+const client = new RestClient({
+ project: '',
+ token: '',
+ host: '.signalwire.com',
+});
+
+await client.phoneNumbers.setSwmlWebhook('', 'https://example.com/bayview');
+await client.calling.dial('', '', { url: 'https://example.com/bayview' });
+await client.calling.aiMessage('', { role: 'system', message_text: 'Driver Sam has arrived.' });
+await client.messages.create('', '', { body: 'Your Bayview Taxi driver is outside.' });
+```
+
+
+
+### Browser SDK
+
+The [Browser SDK][browser-sdk] (`@signalwire/js`) puts voice, video, and chat in a web page.
+A signed-in user can dial an Address,
+such as the one your agent answers,
+and [receive calls][browser-inbound] addressed to them.
+Your backend creates each user a short-lived [Subscriber token][browser-auth]
+with the REST APIs,
+since an API token never belongs in a browser.
+For a public "call us" button,
+the [click-to-call widget][click-to-call] needs no sign-in at all.
+
+The Browser SDK is a participant in the call, not its controller.
+When a browser user calls your agent,
+the flow they hear still comes from SWML,
+and your backend still steers it with REST commands.
+
+```javascript title="JavaScript — Browser SDK"
+import { SignalWire, StaticCredentialProvider } from "@signalwire/js";
+
+const client = new SignalWire(
+ new StaticCredentialProvider({ token: "" })
+);
+
+client.ready$.subscribe(async (ready) => {
+ if (!ready) return;
+
+ const call = await client.dial("/public/bayview-dispatch", { audio: true });
+ call.status$.subscribe((status) => console.log("status:", status));
+});
+```
+
+### Relay
+
+The [Relay namespace][relay-client] of the Server SDKs holds a persistent WebSocket connection to SignalWire.
+Your process subscribes to contexts,
+receives each inbound call as it arrives,
+and drives it with procedural code:
+answer, play, collect digits, bridge.
+Your code receives every call event as it happens
+and reacts to it directly,
+without the webhook layer.
+
+
+
+[Call Flow Builder][cfb] lets you draw a dialplan, one node per step,
+and saves it as a Call Flow Resource that you point a phone number at, with no code at all.
+An AI Agent Resource in the Dashboard is different:
+it points at the public URL of an agent you build with the Server SDKs and host yourself,
+as described in [Create and manage Resources][resources-dashboard].
+
+
+
+## Text conversations with an AI agent
+
+The agent that answers your phone can also hold a [text conversation][ai-chat]
+through the [AI Chat API][chat-api].
+Each turn is one HTTP request:
+you send the user's message, and the agent's reply comes back in the response.
+The conversation uses the agent's prompt, state, and SWAIG tools, as a call does,
+and SWAIG requests from a chat conversation carry `conversation_type: chat`.
+
+From your server, the [Server SDKs send each turn][ai-chat-sdk].
+A web page reaches the agent through a [gateway in your web application][ai-chat-web],
+which keeps the API token on your server.
+To answer SMS with the agent,
+your [inbound message webhook passes each text to AI chat][ai-chat-sms]
+and replies with Messaging SWML.
+
+
+
+```python title="Python — AI chat client"
+import asyncio
+
+from signalwire.ai_chat import AIChatClient
+
+CONFIG_URL = "https://.signalwire.com/relay-bins/"
+
+
+async def main():
+ async with AIChatClient(
+ project="", token="", space=""
+ ) as client:
+ info = await client.create_conversation("rider-1", config_url=CONFIG_URL)
+ print("Ada:", info.initial_message)
+
+ reply = await client.chat("rider-1", "I need a ride to the airport.")
+ print("Ada:", reply.text)
+
+ await client.end("rider-1")
+
+
+asyncio.run(main())
+```
+
+```typescript title="TypeScript — AI chat client"
+import { AIChatClient } from '@signalwire/sdk';
+
+const CONFIG_URL = 'https://.signalwire.com/relay-bins/';
+
+const client = new AIChatClient({
+ project: '',
+ token: '',
+ space: '',
+});
+
+const info = await client.createConversation('rider-1', { configUrl: CONFIG_URL });
+console.log('Ada:', info.initialMessage);
+
+const reply = await client.chat('rider-1', 'I need a ride to the airport.');
+console.log('Ada:', reply.text);
+
+await client.end('rider-1');
+await client.close();
+```
+
+
+
+`CONFIG_URL` is the request URL of a SWML Script that holds your agent,
+and the API token needs the **Chat** permission.
+
+## Messaging and fax
+
+Messaging and fax use the same products as calls.
+
+To send an SMS or MMS,
+call the REST APIs' [Create message][create-message] endpoint,
+which the REST namespace of the Server SDKs wraps in a method.
+A Relay process can [send one over its WebSocket][sms-relay-send].
+During a call, the SWML [`send_sms`][swml-send-sms] method or the `send_sms` [tool action][result-actions] texts the caller.
+
+To handle inbound texts,
+point a phone number at a [Messaging SWML][swml-messaging] document,
+or [receive them in a Relay process][sms-relay-receive].
+Messaging SWML is a separate flavor of SWML with methods such as `reply`.
+You can host the document in SignalWire or serve it from your own server,
+as in [Reply to incoming messages via SWML][sms-swml-reply].
+
+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, point a phone number at SWML that runs [`receive_fax`][swml-receive-fax].
+The Agents namespace generates both methods,
+and Relay can send and receive faxes on a call.
+[Send and receive faxes][fax-guide] walks through both directions.
+
+## Match your use case to a product
+
+| You're building | Use |
+|---|---|
+| An AI agent that answers your phone number | Server SDKs (Agents namespace) |
+| A phone menu or call forwarding | Server SDKs (Agents namespace) |
+| An agent that answers from your documents | Server SDKs (Agents namespace) with the [`datasphere` skill][datasphere-skill] |
+| Outbound reminder or survey calls | REST `dial`, running your Server SDKs (Agents namespace) flow |
+| Buttons that record, transfer, or hold a live call | [REST call commands][call-commands] |
+| Text notifications and confirmations | [REST messages][create-message] |
+| Two-way texting or automatic replies | [Messaging SWML][swml-messaging] or [Relay][sms-relay-receive] |
+| An AI agent customers chat with on your website or over SMS | [AI Chat API][chat-api], from the [Server SDKs][ai-chat-sdk] or a [web gateway][ai-chat-web] |
+| Sending or receiving faxes | Server SDKs (Agents namespace) with [`send_fax`][swml-send-fax] and [`receive_fax`][swml-receive-fax] |
+| A "call us" button on a web page | [Click-to-call widget][click-to-call] |
+| Voice or video calling between your users | [Browser SDK][browser-sdk] |
+| An existing Twilio application | [Compatibility API][compat] |
+
+## The building blocks every product shares
+
+| Building block | What it is | Where you work with it |
+|---|---|---|
+| [Phone numbers][phone-numbers] | Numbers on your Space that receive and place calls and messages | Buy and assign them in the Dashboard or with [REST][purchase-number]. Each one points at a Resource. |
+| [Resources][resources] and [Addresses][addresses] | Anything that handles a call, such as a SWML Script, AI Agent, Subscriber, Video Room, or Call Flow, and the paths that reach it, such as `/public/bayview-dispatch` | Create them in the Dashboard or with REST. SWML, the Browser SDK, and Relay all dial Addresses. |
+| [Subscribers][subscribers] and tokens | The people who sign in to your app, and the short-lived tokens their browsers use | [Create Subscribers][create-subscriber] and [tokens][subscriber-token] with REST, then use them in the Browser SDK |
+| SWAIG tools | Functions on your server that an AI agent calls mid-conversation | Declare them on the agent. Their replies can carry [actions][result-actions] on the call. See [Tool calling][tool-calling]. |
+| Datasphere | Document storage with semantic search, for agents that answer from your content | [Upload documents][datasphere-create] with REST, then give the agent the [`datasphere` skill][datasphere-skill] |
+| [Webhooks and status callbacks][webhooks] | HTTP requests SignalWire sends your server when a call or message changes state | Set a `status_url` on REST commands, or a callback on a SWML method |
+| Recordings | Audio files from recorded calls | Start them from SWML, Relay, or a REST call command, then [list, fetch, and delete][list-recordings] them with REST |
+
+## Steer a running agent from your backend
+
+The products work together on a single call.
+Every SWAIG request your agent receives carries the call's `call_id`,
+so your server can store it with the booking.
+When a driver accepts the ride,
+your dispatch system sends [`calling.ai_message`][call-commands] to that call through the REST APIs.
+Ada receives it as a system instruction the caller doesn't hear,
+and tells the caller their driver is on the way.
+The [REST client guide][rest-client] shows how to send call commands from the Server SDKs.
+
+## Next steps
+
+
+
+ Write an agent with the Agents namespace and answer a call with it.
+
+
+ Connect an agent to your systems with SWAIG functions, state, and actions.
+
+
+ Every command the Calling API sends to a live call.
+
+
+ Place and receive calls from a web page.
+
+
+ Reach the same agent from a phone number, SIP, and the browser.
+
+
+ Reach your agent by text, and move a conversation onto a phone call and back.
+
+
+ Update a web page from inside the call.
+
+
diff --git a/fern/products/platform/pages/platform/core/glossary.mdx b/fern/products/platform/pages/platform/core/glossary.mdx
index 278e34cca9..919bd0ddb8 100644
--- a/fern/products/platform/pages/platform/core/glossary.mdx
+++ b/fern/products/platform/pages/platform/core/glossary.mdx
@@ -38,6 +38,10 @@ max-toc-depth: 3
This glossary defines each SignalWire term, with the aliases and historical names it answers to and the similar terms it should not be confused with. An alias is listed only where it is still live in the product, such as a Dashboard label, an API path or field, an SDK parameter, or a package name, and each entry says where.
+
+Deciding what to build with? [Pick the right SignalWire product](/docs/platform/pick-a-product) compares SWML, the REST APIs, the Browser SDK, and Relay, and shows how they work together.
+
+
## Accounts and access
One account owns one or more Spaces, each Space holds one or more Projects, and a Project can hold subprojects.
diff --git a/fern/products/platform/platform.yml b/fern/products/platform/platform.yml
index 3fdf27d4f3..1a2dd72557 100644
--- a/fern/products/platform/platform.yml
+++ b/fern/products/platform/platform.yml
@@ -30,6 +30,9 @@ navigation:
- page: Get started
path: ./pages/getting-started.mdx
icon: fa-regular fa-rocket
+ - page: Pick a product
+ path: ./pages/pick-a-product.mdx
+ icon: fa-regular fa-compass
- changelog: ./changelog
title: Changelog
icon: fa-regular fa-clock