From 4d4e4f68d2cc62f2fa13a2e13cf92c3272ce0f52 Mon Sep 17 00:00:00 2001 From: nirav Date: Tue, 29 Sep 2026 23:30:45 +0545 Subject: [PATCH 01/13] surfaces --- fern/llms.txt | 1 + .../platform/call-fabric/pick-a-product.mdx | 435 ++++++++++++++++++ .../platform/pages/platform/core/glossary.mdx | 4 + 3 files changed, 440 insertions(+) create mode 100644 fern/products/platform/pages/platform/call-fabric/pick-a-product.mdx diff --git a/fern/llms.txt b/fern/llms.txt index f5d5144515..09987d2101 100644 --- a/fern/llms.txt +++ b/fern/llms.txt @@ -51,6 +51,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 SignalWire's products (SWML through the Server SDKs, the REST APIs, the Browser SDK, and Relay), see which one fits each use case, and combine them with phone numbers, Resources, tools, and Datasphere. - [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. - [Resources](/docs/platform/resources): Communication entities such as AI agents, SignalWire Markup Language (SWML) scripts, Subscribers, and Video Rooms. diff --git a/fern/products/platform/pages/platform/call-fabric/pick-a-product.mdx b/fern/products/platform/pages/platform/call-fabric/pick-a-product.mdx new file mode 100644 index 0000000000..82b09b3382 --- /dev/null +++ b/fern/products/platform/pages/platform/call-fabric/pick-a-product.mdx @@ -0,0 +1,435 @@ +--- +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 +position: 0 +description: Compare SignalWire's products (SWML through the Server SDKs, the REST APIs, the Browser SDK, and Relay), see which one fits each use case, and combine them with phone numbers, Resources, tools, and Datasphere. +max-toc-depth: 3 +--- + +[swml]: /docs/swml +[swml-messaging]: /docs/swml/reference/messaging +[swml-send-sms]: /docs/swml/reference/calling/send-sms +[swml-user-event]: /docs/swml/reference/calling/user-event +[swml-transfer]: /docs/swml/reference/calling/transfer +[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 +[function-result]: /docs/server-sdks/reference/python/agents/function-result +[fr-send-sms]: /docs/server-sdks/reference/python/agents/function-result/send-sms +[fr-user-event]: /docs/server-sdks/reference/python/agents/function-result/swml-user-event +[fr-rpc-ai-message]: /docs/server-sdks/reference/python/agents/function-result/rpc-ai-message +[swml-service]: /docs/server-sdks/reference/python/agents/swml-service +[datasphere-skill]: /docs/server-sdks/reference/python/agents/skills/datasphere +[mapping-numbers]: /docs/server-sdks/guides/mapping-numbers +[rest-client]: /docs/server-sdks/guides/rest-client +[py-rest-calling]: /docs/server-sdks/reference/python/rest/calling +[ts-rest-calling]: /docs/server-sdks/reference/typescript/rest/calling +[py-rest-datasphere]: /docs/server-sdks/reference/python/rest/datasphere +[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 +[ai-chat-api]: /docs/apis/rest/ai-chat/chat-methods +[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 +[resources]: /docs/platform/resources +[resources-dashboard]: /docs/platform/resources#in-the-dashboard +[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 +[ai-overview]: /docs/platform/ai +[tool-calling]: /docs/platform/ai/tool-calling +[record-calls]: /docs/platform/voice/record-calls +[outbound-calling]: /docs/platform/voice/outbound-calling +[messaging]: /docs/platform/messaging + +SignalWire helps you create powerful and flexible communication apps that span across channels from PSTN and fax +to the web browser. SignalWire lets you wire in state-of-the-art conversational agents, use AI for + + +SignalWire runs every call, message, and media session itself. Its products are the ways your code +tells it what to do, and they differ in who holds control of the call, and when. +Most applications need two of them at most: the Server SDKs' Agents namespace, which writes +[SWML][swml] for your calls, and the REST APIs for everything around those calls. Add the Browser +SDK when people talk to you from a web page or app. + +## The recommended path + +Start with a call that is described up front and then adjusted from outside. Your agent tells +SignalWire how to handle a call, and SignalWire runs it. When something changes in your own +systems, your backend sends the live call a command over HTTP. Nothing in your stack holds a +connection open, so each piece scales like an ordinary web service. + +```mermaid +flowchart LR + Caller["Caller
phone · SIP · browser"] --> Address["Phone number
or Address"] + Address --> Resource["Resource
SWML Script"] + Resource -- "fetches SWML" --> Agent["Your agent
Server SDKs · Agents"] + Agent -- "SWAIG tool calls" --> Systems["Your systems
data · rules"] + Backend["Your backend
Server SDKs · REST"] -- "call commands over HTTP" --> Call(("Live call")) + Resource --> Call + Backend -- "numbers · Resources · tokens" --> Platform["Space configuration"] +``` + +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 whose URL is your agent. +2. When a call arrives, SignalWire requests a SWML document from your agent and runs it: answering, + speaking, listening, recording, and running the AI conversation. +3. When the AI needs data or permission, 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. + +## The products + +| Product | What you write | Where it runs | Connection | Reach for it when | +|---|---|---|---|---| +| SWML, via the Server SDKs' Agents namespace | A description of the whole call, generated by an `AgentBase` class | Your HTTP server, or hosted by SignalWire as a SWML Script | SignalWire requests the document over HTTP | You're handling a call or an AI conversation. Start here. | +| REST APIs, via the Server SDKs' REST namespace | One request per action | Anywhere that can send HTTPS | None held open | You're provisioning your Space, starting calls and messages, or acting on a live call | +| Browser SDK | A client that places, receives, and displays calls and chat | The user's browser | A session authenticated with a Subscriber token | A person talks to you from a web page or app | +| WebSocket (Relay) | Procedural code that answers and drives each call | Your long-running process | A persistent WebSocket you keep open | Your code must own the call step by step and react to every event as it arrives | + +### SWML, written with the Agents namespace + +[SWML][swml] (SignalWire Markup Language) is a JSON or YAML document that describes how a call +should go: answer, play a greeting, run an AI agent, record, transfer. You rarely write it by hand. +The Agents namespace of the [Server SDKs][server-sdks] generates it from Python or TypeScript: you +subclass [`AgentBase`][agent-base], give it a prompt and tools, and run it as a web server. +SignalWire requests the document when a call arrives and executes it for the rest of the call. + +Use it for any call your code handles, with or without AI. [`SWMLService`][swml-service] builds +non-AI flows, such as a phone menu or call forwarding, the same way. For a fixed flow with no +server of your own, 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. That makes it stateless and deployable anywhere that serves HTTPS, and +it leaves your code with only the parts you alone can write: prompts, tools, and business rules. The [Server SDKs quickstart][sdk-quickstart] builds your +first agent. + +### 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 is the part that reaches live calls. Its `dial` command starts a new call, and its +[call commands][call-commands] act on a call already in progress: `calling.play`, `calling.record`, +`calling.transfer`, `calling.ai_message`, `calling.ai_hold`, `calling.end`, and more than thirty +others. These are the same commands the Relay namespace sends over its WebSocket, delivered over +HTTP instead. A call running SWML accepts them, so the recommended path gets most of Relay's +real-time control without a connection to keep open. + +### 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. + +### WebSocket (Relay) + +The [Relay namespace][relay-client] of the Server SDKs holds a persistent WebSocket 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. Every event on the call reaches your code +the moment it happens. + +That control comes with a process you keep running and connected, and your code owns every call +from answer to hangup. Most applications don't need it. If you can describe the flow up front and +adjust it with commands, SWML and the REST APIs do the same work with less to operate. + + + +[Call Flow Builder][cfb] draws a voice application on a canvas in your Dashboard, one node per +step. An [AI Agent Resource][resources-dashboard] configures an agent's prompt, voice, and tools in +the Dashboard. Both produce Resources that you point a phone number at, with no code at all. Move +to the Agents namespace when the flow needs your own data, logic, or version control. + + + +## What each product can do + +The table shows where each capability lives. A capability-specific guide, such as +[Record calls][record-calls], breaks its own capability down further. + +| Function | SWML | REST | Browser SDK | WebSocket (Relay) | +|---|---|---|---|---| +| Handle an inbound call to a phone number or Address | | | | | +| Start a new outbound call | | | | | +| Run an AI agent on a call | | | | | +| Play audio, collect input, record, or stream a live call | | | | | +| Change a live AI conversation from outside it | | | | | +| Send an SMS or MMS | | | | | +| Handle an inbound SMS or MMS | | | | | +| Talk from a web page, with audio, video, or chat | | | | | +| Buy numbers, create Resources and Subscribers, issue tokens | | | | | +| Find recordings and logs after the call | | | | | + +- **SWML** runs on a call that already exists. To start one, send a REST `dial` whose `url` + points at your agent, and SWML takes over once the call is answered. Inbound SMS uses its own + document type, [Messaging SWML][swml-messaging]. +- **REST** acts on calls, but a call has to reach a Resource first. SignalWire routes an inbound + call to the Resource behind the number, never to a REST client. +- **Agents** is not a separate column. It generates SWML, so it can do anything the SWML column + can, and its tools can also act on the call from inside the conversation. + +## Match your use case to a product + +| You're building | Start with | Add | +|---|---|---| +| An AI agent that answers your phone number | The Agents namespace | A phone number pointed at the agent's SWML Script Resource ([Mapping numbers][mapping-numbers]) | +| A phone menu or call forwarding, without AI | [`SWMLService`][swml-service], or a hosted SWML Script | A phone number pointed at it | +| Outbound reminder or survey calls | A REST `dial` whose `url` is your agent ([Outbound calling][outbound-calling]) | Status callbacks to track each call | +| Buttons that act on live calls, such as record, transfer, or hold the AI | [REST call commands][call-commands] | The `call_id` your agent receives on every tool call | +| A "call us" button on a public web page | The [click-to-call widget][click-to-call] | An agent at the Address the widget dials | +| Voice or video calling between your own users | The [Browser SDK][browser-sdk] | [Subscribers][subscribers], and Subscriber tokens from your backend | +| Text notifications and confirmations | [REST messages][create-message] | A messaging-enabled [phone number][messaging] | +| Automatic replies to inbound texts | [Messaging SWML][swml-messaging] | A phone number whose message handler is that document | +| The same agent over text as well as voice | The [AI Chat API][ai-chat-api] | Nothing new: the agent's prompt and tools carry over ([AI overview][ai-overview]) | +| An agent that answers from your documents | The Agents namespace with the [`datasphere` skill][datasphere-skill] | Documents uploaded through the [REST namespace][py-rest-datasphere] | + +## The building blocks every product shares + +These pieces aren't products you build with. They're the platform objects every product reads and writes, so a +number bought with REST can route to an agent written with the Agents namespace, and a browser can +dial it. + +| 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 (SWML Script, AI Agent, Subscriber, Video Room, 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 with the [REST namespace][py-rest-datasphere], 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 any product, then [list, fetch, and delete][list-recordings] them with REST | + +## How the pieces work together + +Each pattern below combines a product with a building block or with another product. The running +example is Bayview Taxi, whose AI dispatcher Ada answers the phone. + +### Steer a running agent from your backend with REST commands + +Ada books a ride, and the call stays up while the dispatch system finds a driver. When a driver +accepts, the dispatch system needs to tell Ada, and through her the caller. The call is SWML, run +by SignalWire, and your dispatch system never held a connection to it. It needs only the call's ID +and one HTTP request. + +Every SWAIG request carries the call's `call_id`. Store it with the booking: + + + +```python title="Python — Agents" +# Install: python -m pip install signalwire-sdk==3.4.1 +# Save as dispatch_agent.py and run: python dispatch_agent.py +from signalwire import AgentBase, FunctionResult + +bookings = {} + +agent = AgentBase(name="dispatch-agent", route="/agent") +agent.add_language("English", "en-US", "rime.spore") +agent.prompt_add_section( + "Role", + body="You are Ada, the dispatcher for Bayview Taxi. Book the ride with book_ride, " + "then tell the caller you'll confirm their driver in a moment.", +) + + +def book_ride(args, raw_data): + booking_id = f"BT-{len(bookings) + 1:04d}" + bookings[booking_id] = {"pickup": args.get("pickup"), "call_id": raw_data.get("call_id")} + return FunctionResult(f"Booked as {booking_id}. A driver is being assigned.") + + +agent.define_tool( + name="book_ride", + description="Book a pickup at the address the caller gave", + parameters={ + "type": "object", + "properties": {"pickup": {"type": "string", "description": "The pickup address"}}, + "required": ["pickup"], + }, + handler=book_ride, +) + +if __name__ == "__main__": + agent.run() +``` + +```typescript title="TypeScript — Agents" +// Install: npm install @signalwire/sdk@2.0.5 +// This sample also runs as JavaScript: save as dispatch-agent.mjs, +// then run: node dispatch-agent.mjs +import { AgentBase, FunctionResult } from '@signalwire/sdk'; + +const bookings = new Map(); + +const agent = new AgentBase({ name: 'dispatch-agent', route: '/agent' }); +agent.addLanguage({ name: 'English', code: 'en-US', voice: 'rime.spore' }); +agent.promptAddSection('Role', { + body: + "You are Ada, the dispatcher for Bayview Taxi. Book the ride with book_ride, " + + "then tell the caller you'll confirm their driver in a moment.", +}); + +agent.defineTool({ + name: 'book_ride', + description: 'Book a pickup at the address the caller gave', + parameters: { + type: 'object', + properties: { pickup: { type: 'string', description: 'The pickup address' } }, + required: ['pickup'], + }, + handler: (args, rawData) => { + const bookingId = `BT-${String(bookings.size + 1).padStart(4, '0')}`; + bookings.set(bookingId, { pickup: args.pickup, callId: rawData.call_id }); + return new FunctionResult(`Booked as ${bookingId}. A driver is being assigned.`); + }, +}); + +await agent.run(); +``` + + + +The `bookings` map stands in for your dispatch system's database. When a driver accepts, the +dispatch system sends [`calling.ai_message`][call-commands] to that call. The message joins Ada's +conversation as a system instruction, which the caller doesn't hear: + + + +```python title="Python — REST client" +# Install: python -m pip install signalwire-sdk==3.4.1 +# Save as driver_assigned.py and run: python driver_assigned.py +from signalwire.rest import RestClient + +client = RestClient( + project="", + token="", + host=".signalwire.com", +) + +client.calling.ai_message( + "", + role="system", + message_text="Driver Sam accepted booking BT-0001 and arrives in 6 minutes " + "in a white Prius. Tell the caller.", +) +``` + +```typescript title="TypeScript — REST client" +// Install: npm install @signalwire/sdk@2.0.5 +// This sample also runs as JavaScript: save as driver-assigned.mjs, +// then run: node driver-assigned.mjs +import { RestClient } from '@signalwire/sdk'; + +const client = new RestClient({ + project: '', + token: '', + host: '.signalwire.com', +}); + +await client.calling.aiMessage('', { + role: 'system', + message_text: + 'Driver Sam accepted booking BT-0001 and arrives in 6 minutes ' + + 'in a white Prius. Tell the caller.', +}); +``` + +```bash title="cURL — Calling API" +curl -X POST "https://.signalwire.com/api/calling/calls" \ + -u ":" \ + -H "Content-Type: application/json" \ + -d '{ + "id": "", + "command": "calling.ai_message", + "params": { + "role": "system", + "message_text": "Driver Sam accepted booking BT-0001 and arrives in 6 minutes in a white Prius. Tell the caller." + } + }' +``` + + + +Replace ``, ``, and `` with the values from your +[API credentials][api-credentials] page, and `` with the `call_id` stored with the +booking. The token needs the **Voice** permission. + +The same request shape carries every other call command. A supervisor's dashboard can hold the AI +with `calling.ai_hold`, start a recording with `calling.record`, or hand the call to a person with +`calling.transfer`, each one a single HTTP request against the `call_id`. See the +[Python][py-rest-calling] and [TypeScript][ts-rest-calling] REST client references for every +command. + +### Let a tool act on the call + +A SWAIG tool can do more than return text. Its [`FunctionResult`][function-result] can also carry +actions that SignalWire performs on the call as soon as the reply arrives. Ada's `book_ride` could +[text the caller a confirmation][fr-send-sms], start a recording, or transfer the call to a person. +It can even [send a message to the agent on a different call][fr-rpc-ai-message], which is how one +caller's agent can update another's. The same capabilities exist as SWML methods, such as +[`send_sms`][swml-send-sms] and [`transfer`][swml-transfer]; the SDK writes them for you. + +Use tool actions when the conversation itself decides what happens next. Use REST commands when +something outside the conversation does, like the driver accepting. + +### Point a phone number, or a browser, at the same agent + +An agent is reachable at an Address once it's behind a Resource. Create a SWML Script Resource +whose URL is your agent, then give it the Addresses callers use: a phone number for the phone +network, and an alias such as `/public/bayview-dispatch` for everything else. The +[Mapping numbers guide][mapping-numbers] walks through it. + +A Browser SDK user dials that alias and talks to Ada from a web page, with no phone number +involved. The agent doesn't change: the Browser SDK is one more way to reach the same Address. + +### Update a browser from inside the call + +When the caller is in a browser, the call can push data to the page. The SWML +[`user_event`][swml-user-event] method, the [`swml_user_event`][fr-user-event] tool action, and the +`calling.user_event` REST command each fire a custom JSON event on the call, and the Browser SDK +receives it on the call object. Ada can put the driver's name and plate on screen while she says +them. + +### Answer from your own documents + +Datasphere stores documents with vector embeddings and searches them in natural language. Upload a +rate card or a service-area FAQ with the [REST namespace][py-rest-datasphere], then add the +[`datasphere` skill][datasphere-skill] to the agent. The skill gives Ada a `search_knowledge` tool, +so she can look up an answer without a tool handler of your own. + +## 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. + + diff --git a/fern/products/platform/pages/platform/core/glossary.mdx b/fern/products/platform/pages/platform/core/glossary.mdx index 2c32b415d5..638fb188a1 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. + +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. From 311697f6f4ff639f08a61049ed1bf1a95ed94382 Mon Sep 17 00:00:00 2001 From: nirav Date: Mon, 5 Oct 2026 18:12:54 +0545 Subject: [PATCH 02/13] update --- .../images/img/recommended-path-themed.svg | 92 ++++++ .../platform/call-fabric/pick-a-product.mdx | 300 +++++++++++------- 2 files changed, 282 insertions(+), 110 deletions(-) create mode 100644 fern/assets/images/img/recommended-path-themed.svg diff --git a/fern/assets/images/img/recommended-path-themed.svg b/fern/assets/images/img/recommended-path-themed.svg new file mode 100644 index 0000000000..fffddf73d0 --- /dev/null +++ b/fern/assets/images/img/recommended-path-themed.svg @@ -0,0 +1,92 @@ + + The recommended path: SWML and REST API from your stack + A caller on a phone, SIP, or a browser reaches a phone number or Address, which points at a Resource, an External SWML script. The Resource fetches SWML from your stack, written with the Server SDKs Agents namespace, and the live call runs on SignalWire. The SWML makes SWAIG tool calls to your systems. The REST API, used through the Server SDKs REST namespace, sends call commands over HTTP to the live call, and manages numbers, Resources, and tokens in your Space configuration. + + + + + + + + + + + Caller + Phone · SIP · browser + + + SIGNALWIRE + + + YOUR STACK + + + Phone number or Address + Points at a Resource + + + Resource + External SWML script + + + Live call + SignalWire runs your SWML + + + Space configuration + + + Your systems + Data · rules + + + SWML + Server SDKs · Agents + + REST API + Server SDKs · REST + + + + + + fetches SWML + + + SWAIG tool calls + + + call commands + + over HTTP + + numbers · Resources · tokens + + + diff --git a/fern/products/platform/pages/platform/call-fabric/pick-a-product.mdx b/fern/products/platform/pages/platform/call-fabric/pick-a-product.mdx index 82b09b3382..236305b870 100644 --- a/fern/products/platform/pages/platform/call-fabric/pick-a-product.mdx +++ b/fern/products/platform/pages/platform/call-fabric/pick-a-product.mdx @@ -9,7 +9,6 @@ max-toc-depth: 3 --- [swml]: /docs/swml -[swml-messaging]: /docs/swml/reference/messaging [swml-send-sms]: /docs/swml/reference/calling/send-sms [swml-user-event]: /docs/swml/reference/calling/user-event [swml-transfer]: /docs/swml/reference/calling/transfer @@ -21,7 +20,6 @@ max-toc-depth: 3 [fr-send-sms]: /docs/server-sdks/reference/python/agents/function-result/send-sms [fr-user-event]: /docs/server-sdks/reference/python/agents/function-result/swml-user-event [fr-rpc-ai-message]: /docs/server-sdks/reference/python/agents/function-result/rpc-ai-message -[swml-service]: /docs/server-sdks/reference/python/agents/swml-service [datasphere-skill]: /docs/server-sdks/reference/python/agents/skills/datasphere [mapping-numbers]: /docs/server-sdks/guides/mapping-numbers [rest-client]: /docs/server-sdks/guides/rest-client @@ -36,7 +34,6 @@ max-toc-depth: 3 [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 -[ai-chat-api]: /docs/apis/rest/ai-chat/chat-methods [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 @@ -49,43 +46,125 @@ max-toc-depth: 3 [phone-numbers]: /docs/platform/phone-numbers [webhooks]: /docs/platform/webhooks [api-credentials]: /docs/platform/your-signalwire-api-space -[ai-overview]: /docs/platform/ai [tool-calling]: /docs/platform/ai/tool-calling -[record-calls]: /docs/platform/voice/record-calls -[outbound-calling]: /docs/platform/voice/outbound-calling -[messaging]: /docs/platform/messaging -SignalWire helps you create powerful and flexible communication apps that span across channels from PSTN and fax -to the web browser. SignalWire lets you wire in state-of-the-art conversational agents, use AI for +SignalWire helps you create powerful and flexible communication apps that span channels from the PSTN +to the web browser, and integrate AI agents, payments, and backend hooks. You can build them with several +products and SDK surfaces. This page walks you through each one and helps you pick the right one for your +use case. +## The recommended path -SignalWire runs every call, message, and media session itself. Its products are the ways your code -tells it what to do, and they differ in who holds control of the call, and when. -Most applications need two of them at most: the Server SDKs' Agents namespace, which writes -[SWML][swml] for your calls, and the REST APIs for everything around those calls. Add the Browser -SDK when people talk to you from a web page or app. +The recommended path uses the Server SDKs' Agents namespace to create a SWML dialplan. +A dialplan is a set of rules that describes how you want the call to proceed. This can include forwarding the +call, recording a voicemail, or running a full IVR system. -## The recommended path +SWML is SignalWire's native dialplan script. It is a JSON or YAML document, but you should compose it with the +Server SDKs' Agents namespace for easier maintenance and better validation. SWML has deep AI integrations +and webhook support, so you can keep track of the call while it happens. + +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. The Python code and the SWML it generates are shown below. + + + +```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."}, +}) -Start with a call that is described up front and then adjusted from outside. Your agent tells -SignalWire how to handle a call, and SignalWire runs it. When something changes in your own -systems, your backend sends the live call a command over HTTP. Nothing in your stack holds a -connection open, so each piece scales like an ordinary web service. +bayview.add_section("person") +bayview.add_verb_to_section("person", "connect", {"to": "+15551234567"}) + +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. + person: + - connect: + to: '+15551234567' +``` + + + +When the call ends, the SWML can send a call summary to your server through a webhook. The Server SDKs +also send REST commands and receive webhooks from the same codebase, so in practice a single backend +manages your entire call flow. + + + +A caller on a phone, SIP, or a browser reaches a phone number or Address, which points at an External SWML script Resource. The Resource fetches SWML from your stack, written with the Server SDKs Agents namespace, and SignalWire runs the live call. The SWML makes SWAIG tool calls to your systems. From the same stack, the REST API, used through the Server SDKs REST namespace, sends call commands over HTTP to the live call, and manages numbers, Resources, and tokens in your Space configuration. + + + + ```mermaid flowchart LR Caller["Caller
phone · SIP · browser"] --> Address["Phone number
or Address"] - Address --> Resource["Resource
SWML Script"] - Resource -- "fetches SWML" --> Agent["Your agent
Server SDKs · Agents"] + Address --> Resource["Resource
External SWML script"] + subgraph Stack["Your stack"] + Agent["SWML
Server SDKs · Agents"] + Backend["REST API
Server SDKs · REST"] + end + Resource -- "fetches SWML" --> Agent Agent -- "SWAIG tool calls" --> Systems["Your systems
data · rules"] - Backend["Your backend
Server SDKs · REST"] -- "call commands over HTTP" --> Call(("Live call")) + Backend -- "call commands over HTTP" --> Call(("Live call")) Resource --> Call Backend -- "numbers · Resources · tokens" --> Platform["Space configuration"] ``` +
+ 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 whose URL is your agent. -2. When a call arrives, SignalWire requests a SWML document from your agent and runs it: answering, + in code, that Resource is an External SWML script whose URL is 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 permission, 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. @@ -94,29 +173,49 @@ flowchart LR ## The products -| Product | What you write | Where it runs | Connection | Reach for it when | -|---|---|---|---|---| -| SWML, via the Server SDKs' Agents namespace | A description of the whole call, generated by an `AgentBase` class | Your HTTP server, or hosted by SignalWire as a SWML Script | SignalWire requests the document over HTTP | You're handling a call or an AI conversation. Start here. | -| REST APIs, via the Server SDKs' REST namespace | One request per action | Anywhere that can send HTTPS | None held open | You're provisioning your Space, starting calls and messages, or acting on a live call | -| Browser SDK | A client that places, receives, and displays calls and chat | The user's browser | A session authenticated with a Subscriber token | A person talks to you from a web page or app | -| WebSocket (Relay) | Procedural code that answers and drives each call | Your long-running process | A persistent WebSocket you keep open | Your code must own the call step by step and react to every event as it arrives | +| Product | What you write | Runs on | Use it for | +|---|---|---|---| +| SWML | The call flow, as a document | Your web server, or hosted by SignalWire | Handling calls and AI agents. Start here. | +| REST APIs | One request per action | Anywhere | Setup, outbound calls and messages, live call commands | +| Browser SDK | A calling client | The user's browser | Calls and chat from a web page | +| WebSocket (Relay) | Code that drives each call | Your always-on process | Step-by-step, event-driven call control | -### SWML, written with the Agents namespace +### SWML -[SWML][swml] (SignalWire Markup Language) is a JSON or YAML document that describes how a call -should go: answer, play a greeting, run an AI agent, record, transfer. You rarely write it by hand. -The Agents namespace of the [Server SDKs][server-sdks] generates it from Python or TypeScript: you -subclass [`AgentBase`][agent-base], give it a prompt and tools, and run it as a web server. -SignalWire requests the document when a call arrives and executes it for the rest of the call. +[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 +subclass [`AgentBase`][agent-base] in Python or TypeScript, 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. [`SWMLService`][swml-service] builds -non-AI flows, such as a phone menu or call forwarding, the same way. For a fixed flow with no -server of your own, paste the document into a SWML Script in your Dashboard, and SignalWire hosts it. +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. That makes it stateless and deployable anywhere that serves HTTPS, and -it leaves your code with only the parts you alone can write: prompts, tools, and business rules. The [Server SDKs quickstart][sdk-quickstart] builds your -first agent. +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 + + +class Ada(AgentBase): + def __init__(self): + super().__init__(name="ada", route="/ada") + self.prompt_add_section("Role", body="You are Ada, the dispatcher for Bayview Taxi. Help callers check on their ride.") + + @AgentBase.tool( + name="check_ride", + description="Look up a ride by its booking ID", + parameters={"booking_id": {"type": "string", "description": "The booking ID"}}, + ) + def check_ride(self, args, raw_data): + ride = rides.lookup(args["booking_id"]) + return FunctionResult(f"The driver arrives in {ride.eta} minutes.") + + +Ada().run() +``` ### REST APIs @@ -125,12 +224,22 @@ create Resources and Subscribers, issue client tokens, send messages, fetch reco 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 is the part that reaches live calls. Its `dial` command starts a new call, and its -[call commands][call-commands] act on a call already in progress: `calling.play`, `calling.record`, +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. These are the same commands the Relay namespace sends over its WebSocket, delivered over -HTTP instead. A call running SWML accepts them, so the recommended path gets most of Relay's -real-time control without a connection to keep open. +HTTP instead. + +```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.") +``` ### Browser SDK @@ -143,73 +252,52 @@ For a public "call us" button, the [click-to-call widget][click-to-call] needs n 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)); +}); +``` + ### WebSocket (Relay) -The [Relay namespace][relay-client] of the Server SDKs holds a persistent WebSocket to SignalWire. +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. Every event on the call reaches your code -the moment it happens. - -That control comes with a process you keep running and connected, and your code owns every call -from answer to hangup. Most applications don't need it. If you can describe the flow up front and -adjust it with commands, SWML and the REST APIs do the same work with less to operate. +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] draws a voice application on a canvas in your Dashboard, one node per +[Call Flow Builder][cfb] lets you draw a dialplan, one node per step. An [AI Agent Resource][resources-dashboard] configures an agent's prompt, voice, and tools in -the Dashboard. Both produce Resources that you point a phone number at, with no code at all. Move -to the Agents namespace when the flow needs your own data, logic, or version control. +the Dashboard. Both produce Resources that you point a phone number at, with no code at all. +The click to test button helps you test the call straight from the Space dashboard. -## What each product can do - -The table shows where each capability lives. A capability-specific guide, such as -[Record calls][record-calls], breaks its own capability down further. - -| Function | SWML | REST | Browser SDK | WebSocket (Relay) | -|---|---|---|---|---| -| Handle an inbound call to a phone number or Address | | | | | -| Start a new outbound call | | | | | -| Run an AI agent on a call | | | | | -| Play audio, collect input, record, or stream a live call | | | | | -| Change a live AI conversation from outside it | | | | | -| Send an SMS or MMS | | | | | -| Handle an inbound SMS or MMS | | | | | -| Talk from a web page, with audio, video, or chat | | | | | -| Buy numbers, create Resources and Subscribers, issue tokens | | | | | -| Find recordings and logs after the call | | | | | - -- **SWML** runs on a call that already exists. To start one, send a REST `dial` whose `url` - points at your agent, and SWML takes over once the call is answered. Inbound SMS uses its own - document type, [Messaging SWML][swml-messaging]. -- **REST** acts on calls, but a call has to reach a Resource first. SignalWire routes an inbound - call to the Resource behind the number, never to a REST client. -- **Agents** is not a separate column. It generates SWML, so it can do anything the SWML column - can, and its tools can also act on the call from inside the conversation. - ## Match your use case to a product -| You're building | Start with | Add | -|---|---|---| -| An AI agent that answers your phone number | The Agents namespace | A phone number pointed at the agent's SWML Script Resource ([Mapping numbers][mapping-numbers]) | -| A phone menu or call forwarding, without AI | [`SWMLService`][swml-service], or a hosted SWML Script | A phone number pointed at it | -| Outbound reminder or survey calls | A REST `dial` whose `url` is your agent ([Outbound calling][outbound-calling]) | Status callbacks to track each call | -| Buttons that act on live calls, such as record, transfer, or hold the AI | [REST call commands][call-commands] | The `call_id` your agent receives on every tool call | -| A "call us" button on a public web page | The [click-to-call widget][click-to-call] | An agent at the Address the widget dials | -| Voice or video calling between your own users | The [Browser SDK][browser-sdk] | [Subscribers][subscribers], and Subscriber tokens from your backend | -| Text notifications and confirmations | [REST messages][create-message] | A messaging-enabled [phone number][messaging] | -| Automatic replies to inbound texts | [Messaging SWML][swml-messaging] | A phone number whose message handler is that document | -| The same agent over text as well as voice | The [AI Chat API][ai-chat-api] | Nothing new: the agent's prompt and tools carry over ([AI overview][ai-overview]) | -| An agent that answers from your documents | The Agents namespace with the [`datasphere` skill][datasphere-skill] | Documents uploaded through the [REST namespace][py-rest-datasphere] | +| You're building | Use | +|---|---| +| An AI agent that answers your phone number | Server SDK (Agents namespace) | +| A phone menu or call forwarding | Server SDK (Agents namespace) | +| An agent that answers from your documents | Server SDK (Agents namespace) with the [`datasphere` skill][datasphere-skill] | +| Outbound reminder or survey calls | REST `dial`, running your Server SDK (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] | +| 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] | ## The building blocks every product shares -These pieces aren't products you build with. They're the platform objects every product reads and writes, so a -number bought with REST can route to an agent written with the Agents namespace, and a browser can -dial it. - | 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. | @@ -374,9 +462,8 @@ Replace ``, ``, and `` with the val [API credentials][api-credentials] page, and `` with the `call_id` stored with the booking. The token needs the **Voice** permission. -The same request shape carries every other call command. A supervisor's dashboard can hold the AI -with `calling.ai_hold`, start a recording with `calling.record`, or hand the call to a person with -`calling.transfer`, each one a single HTTP request against the `call_id`. See the +The same request shape carries every other call command, each one a single HTTP request against the +`call_id`. See the [Python][py-rest-calling] and [TypeScript][ts-rest-calling] REST client references for every command. @@ -394,13 +481,13 @@ something outside the conversation does, like the driver accepting. ### Point a phone number, or a browser, at the same agent -An agent is reachable at an Address once it's behind a Resource. Create a SWML Script Resource +An agent is reachable at an Address once it's behind a Resource. Create an External SWML script Resource whose URL is your agent, then give it the Addresses callers use: a phone number for the phone network, and an alias such as `/public/bayview-dispatch` for everything else. The [Mapping numbers guide][mapping-numbers] walks through it. A Browser SDK user dials that alias and talks to Ada from a web page, with no phone number -involved. The agent doesn't change: the Browser SDK is one more way to reach the same Address. +involved. ### Update a browser from inside the call @@ -410,13 +497,6 @@ When the caller is in a browser, the call can push data to the page. The SWML receives it on the call object. Ada can put the driver's name and plate on screen while she says them. -### Answer from your own documents - -Datasphere stores documents with vector embeddings and searches them in natural language. Upload a -rate card or a service-area FAQ with the [REST namespace][py-rest-datasphere], then add the -[`datasphere` skill][datasphere-skill] to the agent. The skill gives Ada a `search_knowledge` tool, -so she can look up an answer without a tool handler of your own. - ## Next steps From ad65bc3aebce948d70d7d2cf827764fd6589d0e7 Mon Sep 17 00:00:00 2001 From: nirav Date: Mon, 5 Oct 2026 18:20:05 +0545 Subject: [PATCH 03/13] bump visibility --- fern/products/platform/platform.yml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/fern/products/platform/platform.yml b/fern/products/platform/platform.yml index 6f7f06ec96..0a90b34871 100644 --- a/fern/products/platform/platform.yml +++ b/fern/products/platform/platform.yml @@ -23,6 +23,9 @@ navigation: - page: Get started path: ./pages/getting-started.mdx icon: fa-regular fa-home + - page: Pick a product + path: ./pages/platform/call-fabric/pick-a-product.mdx + icon: fa-regular fa-compass - changelog: ./changelog title: Changelog icon: fa-regular fa-clock From 1eaf9efd6fa3d0a222d60d89359b136c754b963e Mon Sep 17 00:00:00 2001 From: nirav Date: Tue, 6 Oct 2026 17:09:22 +0545 Subject: [PATCH 04/13] update wording --- .../images/img/recommended-path-themed.svg | 4 +- .../platform/call-fabric/pick-a-product.mdx | 192 +++++++++++++----- 2 files changed, 139 insertions(+), 57 deletions(-) diff --git a/fern/assets/images/img/recommended-path-themed.svg b/fern/assets/images/img/recommended-path-themed.svg index fffddf73d0..2977f8e9a6 100644 --- a/fern/assets/images/img/recommended-path-themed.svg +++ b/fern/assets/images/img/recommended-path-themed.svg @@ -1,6 +1,6 @@ The recommended path: SWML and REST API from your stack - A caller on a phone, SIP, or a browser reaches a phone number or Address, which points at a Resource, an External SWML script. The Resource fetches SWML from your stack, written with the Server SDKs Agents namespace, and the live call runs on SignalWire. The SWML makes SWAIG tool calls to your systems. The REST API, used through the Server SDKs REST namespace, sends call commands over HTTP to the live call, and manages numbers, Resources, and tokens in your Space configuration. + A caller on a phone, SIP, or a browser reaches a phone number or Address, which points at a SWML Script Resource set to an external URL. The Resource fetches SWML from your stack, written with the Server SDKs Agents namespace, and the live call runs on SignalWire. The SWML makes SWAIG tool calls to your systems. The REST API, used through the Server SDKs REST namespace, sends call commands over HTTP to the live call, and manages numbers, Resources, and tokens in your Space configuration. A caller on a phone, SIP, or a browser reaches a phone number or Address, which points at a SWML Script Resource set to an external URL. The Resource fetches SWML from your stack, written with the Server SDKs Agents namespace, and SignalWire runs the live call. The SWML makes SWAIG tool calls to your systems. From the same stack, the REST API, used through the Server SDKs REST namespace, sends call commands over HTTP to the live call, and manages numbers, Resources, and tokens in your Space configuration. + + + + + +```mermaid +flowchart LR + Caller["Caller
phone · SIP · browser"] --> Address["Phone number
or Address"] + Address --> Resource["Resource
SWML Script · external URL"] + subgraph Stack["Your stack"] + Agent["SWML
Server SDKs · Agents"] + Backend["REST API
Server SDKs · REST"] + end + Resource -- "fetches SWML" --> Agent + Agent -- "SWAIG tool calls" --> Systems["Your systems
data · rules"] + Backend -- "call commands over HTTP" --> Call(("Live call")) + Resource --> Call + Backend -- "numbers · Resources · tokens" --> Platform["Space configuration"] +``` + +
+ +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 permission, 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. The Python code and the SWML it generates are shown below. +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 code and the SWML it generates are shown below. @@ -90,6 +129,8 @@ bayview.switch( 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") @@ -125,6 +166,9 @@ sections: 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: '+15551234567' @@ -132,44 +176,77 @@ sections: -When the call ends, the SWML can send a call summary to your server through a webhook. The Server SDKs -also send REST commands and receive webhooks from the same codebase, so in practice a single backend -manages your entire call flow. +Step 4 in practice: before a maintenance window, your backend can transfer each live call to a short +inline SWML document that apologizes and hangs up: - + -A caller on a phone, SIP, or a browser reaches a phone number or Address, which points at an External SWML script Resource. The Resource fetches SWML from your stack, written with the Server SDKs Agents namespace, and SignalWire runs the live call. The SWML makes SWAIG tool calls to your systems. From the same stack, the REST API, used through the Server SDKs REST namespace, sends call commands over HTTP to the live call, and manages numbers, Resources, and tokens in your Space configuration. +```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": {}}, + ] + }, + }, +) +``` -```mermaid -flowchart LR - Caller["Caller
phone · SIP · browser"] --> Address["Phone number
or Address"] - Address --> Resource["Resource
External SWML script"] - subgraph Stack["Your stack"] - Agent["SWML
Server SDKs · Agents"] - Backend["REST API
Server SDKs · REST"] - end - Resource -- "fetches SWML" --> Agent - Agent -- "SWAIG tool calls" --> Systems["Your systems
data · rules"] - Backend -- "call commands over HTTP" --> Call(("Live call")) - Resource --> Call - Backend -- "numbers · Resources · tokens" --> Platform["Space configuration"] +```typescript title="TypeScript — REST client" +import { RestClient } from '@signalwire/sdk'; + +const client = new RestClient({ + project: '', + token: '', + host: '.signalwire.com', +}); + +await 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: {} }, + ], + }, + }, +}); ``` -
+```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": {} } + ] + } + } + } + }' +``` -1. A phone number or [Address][addresses] points at a [Resource][resources]. For a call you build - in code, that Resource is an External SWML script whose URL is 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 permission, 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. + + +Replace the placeholders with the values from your [API credentials][api-credentials] page and the +ID of the call to end. ## The products @@ -179,6 +256,7 @@ flowchart LR | REST APIs | One request per action | Anywhere | Setup, outbound calls and messages, live call commands | | Browser SDK | A calling client | The user's browser | Calls and chat from a web page | | WebSocket (Relay) | Code that drives each call | Your always-on process | Step-by-step, event-driven call control | +| Call Flow Builder | Nothing: you draw the flow in the Dashboard | SignalWire | Simple voice flows without code | ### SWML @@ -198,23 +276,27 @@ agent. This one gives Ada a tool that looks up a ride: ```python title="Python — Agents" from signalwire import AgentBase, FunctionResult +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.") + -class Ada(AgentBase): - def __init__(self): - super().__init__(name="ada", route="/ada") - self.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 = rides.lookup(args["booking_id"]) + return FunctionResult(f"The driver arrives in {ride.eta} minutes.") - @AgentBase.tool( - name="check_ride", - description="Look up a ride by its booking ID", - parameters={"booking_id": {"type": "string", "description": "The booking ID"}}, - ) - def check_ride(self, args, raw_data): - ride = rides.lookup(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, +) -Ada().run() +agent.run() ``` ### REST APIs @@ -279,7 +361,7 @@ happens and reacts to it directly, without the webhook layer. [Call Flow Builder][cfb] lets you draw a dialplan, one node per step. An [AI Agent Resource][resources-dashboard] configures an agent's prompt, voice, and tools in the Dashboard. Both produce Resources that you point a phone number at, with no code at all. -The click to test button helps you test the call straight from the Space dashboard. +The **Click-to-Test** button lets you test the call straight from the Dashboard. @@ -310,8 +392,8 @@ The click to test button helps you test the call straight from the Space dashboa ## How the pieces work together -Each pattern below combines a product with a building block or with another product. The running -example is Bayview Taxi, whose AI dispatcher Ada answers the phone. +Each pattern below combines a product with a building block or with another product, and continues +the Bayview Taxi example, whose AI dispatcher Ada answers the phone. ### Steer a running agent from your backend with REST commands @@ -481,8 +563,8 @@ something outside the conversation does, like the driver accepting. ### Point a phone number, or a browser, at the same agent -An agent is reachable at an Address once it's behind a Resource. Create an External SWML script Resource -whose URL is your agent, then give it the Addresses callers use: a phone number for the phone +An agent is reachable at an Address once it's behind a Resource. Create a SWML Script Resource +set to an external URL that points at the agent running on your server, then give it the Addresses callers use: a phone number for the phone network, and an alias such as `/public/bayview-dispatch` for everything else. The [Mapping numbers guide][mapping-numbers] walks through it. From 01042753fb7df24333fbe56c21cf261bbb95bc65 Mon Sep 17 00:00:00 2001 From: nirav Date: Tue, 6 Oct 2026 18:19:10 +0545 Subject: [PATCH 05/13] update --- .../build-voice-video/call-controls.mdx | 40 ++++++++++++++++++- .../platform/call-fabric/pick-a-product.mdx | 8 +++- 2 files changed, 46 insertions(+), 2 deletions(-) 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..12c0804922 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,40 @@ 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, the Server SDKs' +[`swml_user_event`][fr-user-event] tool action, 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; + driverName.textContent = driver; + plateNumber.textContent = plate; +}); +``` + +Your fields are sent in `event.params`, alongside SignalWire-added fields +like `call_id`. The event +`{ "driver": "Sam", "plate": "BAY-123" }` reaches the browser as: + +```json +{ + "event_type": "user_event", + "params": { + "driver": "Sam", + "plate": "BAY-123", + "call_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6" + } +} +``` + +The browser's `call.id` is the same ID the REST API takes, so your +backend can target the call directly. + ## Moderation — check the capability first Methods on other participants exist (`participant.mute()`, @@ -245,7 +279,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 +314,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/reference/python/agents/function-result/swml-user-event +[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/platform/call-fabric/pick-a-product.mdx b/fern/products/platform/pages/platform/call-fabric/pick-a-product.mdx index f66c2126b7..cb663543c8 100644 --- a/fern/products/platform/pages/platform/call-fabric/pick-a-product.mdx +++ b/fern/products/platform/pages/platform/call-fabric/pick-a-product.mdx @@ -38,6 +38,7 @@ max-toc-depth: 3 [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 +[browser-user-events]: /docs/browser-sdk/v4/guides/call-controls#receive-user-events-from-the-call [cfb]: /docs/call-flow-builder [resources]: /docs/platform/resources [resources-dashboard]: /docs/platform/resources#in-the-dashboard @@ -176,6 +177,11 @@ sections: +The Server SDKs protect your server with basic auth. Set `SWML_BASIC_AUTH_USER` and +`SWML_BASIC_AUTH_PASSWORD` before you start it, and put the same credentials in the SWML Script +Resource's URL, as in `https://user:pass@your-server.com/bayview`. Without them, the server generates +a random password at startup and rejects SignalWire's requests. + Step 4 in practice: before a maintenance window, your backend can transfer each live call to a short inline SWML document that apologizes and hangs up: @@ -576,7 +582,7 @@ involved. When the caller is in a browser, the call can push data to the page. The SWML [`user_event`][swml-user-event] method, the [`swml_user_event`][fr-user-event] tool action, and the `calling.user_event` REST command each fire a custom JSON event on the call, and the Browser SDK -receives it on the call object. Ada can put the driver's name and plate on screen while she says +[receives it on the call object][browser-user-events]. Ada can put the driver's name and plate on screen while she says them. ## Next steps From 9ad5af1f1208ccfb7c8196673f74781f1190aca4 Mon Sep 17 00:00:00 2001 From: nirav Date: Tue, 6 Oct 2026 18:25:32 +0545 Subject: [PATCH 06/13] fix diagram --- .../platform/call-fabric/pick-a-product.mdx | 49 +++++++++++-------- 1 file changed, 28 insertions(+), 21 deletions(-) diff --git a/fern/products/platform/pages/platform/call-fabric/pick-a-product.mdx b/fern/products/platform/pages/platform/call-fabric/pick-a-product.mdx index cb663543c8..d5bc18a67d 100644 --- a/fern/products/platform/pages/platform/call-fabric/pick-a-product.mdx +++ b/fern/products/platform/pages/platform/call-fabric/pick-a-product.mdx @@ -3,7 +3,6 @@ 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 -position: 0 description: Compare SignalWire's products (SWML through the Server SDKs, the REST APIs, the Browser SDK, and Relay), see which one fits each use case, and combine them with phone numbers, Resources, tools, and Datasphere. max-toc-depth: 3 --- @@ -49,17 +48,15 @@ max-toc-depth: 3 [api-credentials]: /docs/platform/your-signalwire-api-space [tool-calling]: /docs/platform/ai/tool-calling -SignalWire helps you create powerful and flexible communication apps that span channels from the PSTN -to the web browser, and integrate AI agents, payments, and backend hooks. You can build them with several -products and SDK surfaces. This page walks you through each one and helps you pick the right one for your -use case. +A SignalWire app can answer phone calls with an AI agent, put calls and chat in a web page, and text +your customers. You build those pieces with a handful of products (SWML, the REST APIs, the Browser +SDK, and Relay), and most apps combine more than one. Start with the recommended path, then use the +tables below to match each part of your app to a product. ## The recommended path -We recommend that you use the Server SDKs' Agents namespace to create AI agents or a SWML dialplan, and -use its REST namespace to send commands to a live call and to manage your resources. -This path is the easiest to get up and running, and gives you a production-ready scalable system with the least -amount of work. +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 defines the dialplan: a set of rules that describes how you want the call to proceed. This can include forwarding the call, recording a voicemail, or running a full IVR system. @@ -77,17 +74,25 @@ and webhook support, so you can let AI handle most of the communication and keep ```mermaid flowchart LR - Caller["Caller
phone · SIP · browser"] --> Address["Phone number
or Address"] - Address --> Resource["Resource
SWML Script · external URL"] + Caller["Caller
phone · SIP · browser"] + subgraph SignalWire["SignalWire"] + Address["Phone number
or Address"] + Resource["Resource
SWML Script · external URL"] + Call(("Live call")) + Platform["Space configuration"] + end subgraph Stack["Your stack"] + Systems["Your systems
data · rules"] Agent["SWML
Server SDKs · Agents"] Backend["REST API
Server SDKs · REST"] end - Resource -- "fetches SWML" --> Agent - Agent -- "SWAIG tool calls" --> Systems["Your systems
data · rules"] - Backend -- "call commands over HTTP" --> Call(("Live call")) + Caller --> Address + Address --> Resource Resource --> Call - Backend -- "numbers · Resources · tokens" --> Platform["Space configuration"] + Resource -- "fetches SWML" --> Agent + Agent -- "SWAIG tool calls" --> Systems + Backend -- "call commands over HTTP" --> Call + Backend -- "numbers · Resources · tokens" --> Platform ``` @@ -258,7 +263,7 @@ ID of the call to end. | Product | What you write | Runs on | Use it for | |---|---|---|---| -| SWML | The call flow, as a document | Your web server, or hosted by SignalWire | Handling calls and AI agents. Start here. | +| SWML | The call flow, as a document | Served from your web server, or hosted by SignalWire | Handling calls and AI agents. Start here. | | REST APIs | One request per action | Anywhere | Setup, outbound calls and messages, live call commands | | Browser SDK | A calling client | The user's browser | Calls and chat from a web page | | WebSocket (Relay) | Code that drives each call | Your always-on process | Step-by-step, event-driven call control | @@ -268,7 +273,7 @@ ID of the call to end. [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 -subclass [`AgentBase`][agent-base] in Python or TypeScript, give it a prompt and tools, and run it as +create an [`AgentBase`][agent-base] in Python or TypeScript, 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 @@ -305,6 +310,8 @@ agent.define_tool( agent.run() ``` +`rides.lookup` stands in for your booking system. + ### REST APIs The [REST APIs][rest-api] cover everything that isn't the call flow itself. You buy phone numbers, @@ -375,10 +382,10 @@ The **Click-to-Test** button lets you test the call straight from the Dashboard. | You're building | Use | |---|---| -| An AI agent that answers your phone number | Server SDK (Agents namespace) | -| A phone menu or call forwarding | Server SDK (Agents namespace) | -| An agent that answers from your documents | Server SDK (Agents namespace) with the [`datasphere` skill][datasphere-skill] | -| Outbound reminder or survey calls | REST `dial`, running your Server SDK (Agents namespace) flow | +| 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] | | A "call us" button on a web page | [Click-to-call widget][click-to-call] | From 9c822a8ef2c54ab90be91e20334147e85e18b80a Mon Sep 17 00:00:00 2001 From: nirav Date: Tue, 6 Oct 2026 18:27:37 +0545 Subject: [PATCH 07/13] sembr --- .../build-voice-video/call-controls.mdx | 21 +- .../platform/call-fabric/pick-a-product.mdx | 270 +++++++++++------- 2 files changed, 177 insertions(+), 114 deletions(-) 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 12c0804922..8e36321ad4 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 @@ -139,11 +139,12 @@ 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, the Server SDKs' -[`swml_user_event`][fr-user-event] tool action, and the REST -[`calling.user_event`][call-commands] command each fire a `user_event` -on the call. Subscribe to it with [`subscribe`]: +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, +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) => { @@ -153,9 +154,9 @@ call.subscribe("user_event").subscribe((event) => { }); ``` -Your fields are sent in `event.params`, alongside SignalWire-added fields -like `call_id`. The event -`{ "driver": "Sam", "plate": "BAY-123" }` reaches the browser as: +Your fields are sent in `event.params`, +alongside SignalWire-added fields like `call_id`. +The event `{ "driver": "Sam", "plate": "BAY-123" }` reaches the browser as: ```json { @@ -168,8 +169,8 @@ like `call_id`. The event } ``` -The browser's `call.id` is the same ID the REST API takes, so your -backend can target the call directly. +The browser's `call.id` is the same ID the REST API takes, +so your backend can target the call directly. ## Moderation — check the capability first diff --git a/fern/products/platform/pages/platform/call-fabric/pick-a-product.mdx b/fern/products/platform/pages/platform/call-fabric/pick-a-product.mdx index d5bc18a67d..210a47a127 100644 --- a/fern/products/platform/pages/platform/call-fabric/pick-a-product.mdx +++ b/fern/products/platform/pages/platform/call-fabric/pick-a-product.mdx @@ -48,21 +48,28 @@ max-toc-depth: 3 [api-credentials]: /docs/platform/your-signalwire-api-space [tool-calling]: /docs/platform/ai/tool-calling -A SignalWire app can answer phone calls with an AI agent, put calls and chat in a web page, and text -your customers. You build those pieces with a handful of products (SWML, the REST APIs, the Browser -SDK, and Relay), and most apps combine more than one. Start with the recommended path, then use the -tables below to match each part of your app to a product. +A SignalWire app can answer phone calls with an AI agent, +put calls and chat in a web page, +and text your customers. +You build those pieces with a handful of products (SWML, the REST APIs, the Browser SDK, and Relay), +and most apps combine more than one. +Start with the recommended path, +then use the tables below to match each part of your app to a product. ## The recommended path -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. +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 defines the dialplan: a set of rules that describes how you want the call to proceed. +A SWML script defines the dialplan: +a set of rules that describes how you want the call to proceed. This can include forwarding the call, recording a voicemail, or running a full IVR system. -SWML is a JSON or YAML document, and the Agents namespace generates it for you with easier maintenance -and better validation than writing it by hand. SWML has deep AI integrations -and webhook support, so you can let AI handle most of the communication and keep track of the call while it happens. +SWML is a JSON or YAML document, +and the Agents namespace generates it for you +with easier maintenance and better validation than writing it by hand. +SWML has deep AI integrations and webhook support, +so you can let AI handle most of the communication +and keep track of the call while it happens. @@ -97,19 +104,28 @@ flowchart LR -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 permission, 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 code and the SWML it generates are shown below. +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 permission, + 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 code and the SWML it generates are shown below. @@ -182,13 +198,16 @@ sections: -The Server SDKs protect your server with basic auth. Set `SWML_BASIC_AUTH_USER` and -`SWML_BASIC_AUTH_PASSWORD` before you start it, and put the same credentials in the SWML Script -Resource's URL, as in `https://user:pass@your-server.com/bayview`. Without them, the server generates -a random password at startup and rejects SignalWire's requests. +The Server SDKs protect your server with basic auth. +Set `SWML_BASIC_AUTH_USER` and `SWML_BASIC_AUTH_PASSWORD` before you start it, +and put the same credentials in the SWML Script Resource's URL, +as in `https://user:pass@your-server.com/bayview`. +Without them, the server generates a random password at startup +and rejects SignalWire's requests. -Step 4 in practice: before a maintenance window, your backend can transfer each live call to a short -inline SWML document that apologizes and hangs up: +Step 4 in practice: +before a maintenance window, +your backend can transfer each live call to a short inline SWML document that apologizes and hangs up: @@ -256,8 +275,8 @@ curl -X POST "https://.signalwire.com/api/calling/calls" \ -Replace the placeholders with the values from your [API credentials][api-credentials] page and the -ID of the call to end. +Replace the placeholders with the values from your [API credentials][api-credentials] page +and the ID of the call to end. ## The products @@ -271,18 +290,25 @@ ID of the call to end. ### 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 [`AgentBase`][agent-base] in Python or TypeScript, 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: +[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, +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 @@ -314,16 +340,22 @@ agent.run() ### 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. These are the same commands the Relay namespace sends over its WebSocket, delivered over -HTTP instead. +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. +These are the same commands the Relay namespace sends over its WebSocket, +delivered over HTTP instead. ```python title="Python — REST client" from signalwire.rest import RestClient @@ -338,14 +370,20 @@ client.messages.create(from_="", to="", body=" ### 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. +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"; @@ -365,15 +403,19 @@ client.ready$.subscribe(async (ready) => { ### WebSocket (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. +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. An [AI Agent Resource][resources-dashboard] configures an agent's prompt, voice, and tools in -the Dashboard. Both produce Resources that you point a phone number at, with no code at all. +[Call Flow Builder][cfb] lets you draw a dialplan, one node per step. +An [AI Agent Resource][resources-dashboard] configures an agent's prompt, voice, and tools in the Dashboard. +Both produce Resources that you point a phone number at, with no code at all. The **Click-to-Test** button lets you test the call straight from the Dashboard. @@ -405,17 +447,23 @@ The **Click-to-Test** button lets you test the call straight from the Dashboard. ## How the pieces work together -Each pattern below combines a product with a building block or with another product, and continues -the Bayview Taxi example, whose AI dispatcher Ada answers the phone. +Each pattern below combines a product with a building block or with another product, +and continues the Bayview Taxi example, +whose AI dispatcher Ada answers the phone. ### Steer a running agent from your backend with REST commands -Ada books a ride, and the call stays up while the dispatch system finds a driver. When a driver -accepts, the dispatch system needs to tell Ada, and through her the caller. The call is SWML, run -by SignalWire, and your dispatch system never held a connection to it. It needs only the call's ID -and one HTTP request. +Ada books a ride, +and the call stays up while the dispatch system finds a driver. +When a driver accepts, +the dispatch system needs to tell Ada, +and through her the caller. +The call is SWML, run by SignalWire, +and your dispatch system never held a connection to it. +It needs only the call's ID and one HTTP request. -Every SWAIG request carries the call's `call_id`. Store it with the booking: +Every SWAIG request carries the call's `call_id`. +Store it with the booking: @@ -492,9 +540,11 @@ await agent.run(); -The `bookings` map stands in for your dispatch system's database. When a driver accepts, the -dispatch system sends [`calling.ai_message`][call-commands] to that call. The message joins Ada's -conversation as a system instruction, which the caller doesn't hear: +The `bookings` map stands in for your dispatch system's database. +When a driver accepts, +the dispatch system sends [`calling.ai_message`][call-commands] to that call. +The message joins Ada's conversation as a system instruction, +which the caller doesn't hear: @@ -553,44 +603,56 @@ curl -X POST "https://.signalwire.com/api/calling/calls" \ -Replace ``, ``, and `` with the values from your -[API credentials][api-credentials] page, and `` with the `call_id` stored with the -booking. The token needs the **Voice** permission. +Replace ``, ``, and `` +with the values from your [API credentials][api-credentials] page, +and `` with the `call_id` stored with the booking. +The token needs the **Voice** permission. -The same request shape carries every other call command, each one a single HTTP request against the -`call_id`. See the -[Python][py-rest-calling] and [TypeScript][ts-rest-calling] REST client references for every -command. +The same request shape carries every other call command, +each one a single HTTP request against the `call_id`. +See the [Python][py-rest-calling] and [TypeScript][ts-rest-calling] REST client references for every command. ### Let a tool act on the call -A SWAIG tool can do more than return text. Its [`FunctionResult`][function-result] can also carry -actions that SignalWire performs on the call as soon as the reply arrives. Ada's `book_ride` could -[text the caller a confirmation][fr-send-sms], start a recording, or transfer the call to a person. -It can even [send a message to the agent on a different call][fr-rpc-ai-message], which is how one -caller's agent can update another's. The same capabilities exist as SWML methods, such as -[`send_sms`][swml-send-sms] and [`transfer`][swml-transfer]; the SDK writes them for you. - -Use tool actions when the conversation itself decides what happens next. Use REST commands when -something outside the conversation does, like the driver accepting. +A SWAIG tool can do more than return text. +Its [`FunctionResult`][function-result] can also carry +actions that SignalWire performs on the call +as soon as the reply arrives. +Ada's `book_ride` could [text the caller a confirmation][fr-send-sms], +start a recording, +or transfer the call to a person. +It can even [send a message to the agent on a different call][fr-rpc-ai-message], +which is how one caller's agent can update another's. +The same capabilities exist as SWML methods, +such as [`send_sms`][swml-send-sms] and [`transfer`][swml-transfer]; +the SDK writes them for you. + +Use tool actions when the conversation itself decides what happens next. +Use REST commands when something outside the conversation does, +like the driver accepting. ### Point a phone number, or a browser, at the same agent -An agent is reachable at an Address once it's behind a Resource. Create a SWML Script Resource -set to an external URL that points at the agent running on your server, then give it the Addresses callers use: a phone number for the phone -network, and an alias such as `/public/bayview-dispatch` for everything else. The -[Mapping numbers guide][mapping-numbers] walks through it. +An agent is reachable at an Address once it's behind a Resource. +Create a SWML Script Resource set to an external URL that points at the agent running on your server, +then give it the Addresses callers use: +a phone number for the phone network, +and an alias such as `/public/bayview-dispatch` for everything else. +The [Mapping numbers guide][mapping-numbers] walks through it. -A Browser SDK user dials that alias and talks to Ada from a web page, with no phone number -involved. +A Browser SDK user dials that alias +and talks to Ada from a web page, +with no phone number involved. ### Update a browser from inside the call -When the caller is in a browser, the call can push data to the page. The SWML -[`user_event`][swml-user-event] method, the [`swml_user_event`][fr-user-event] tool action, and the -`calling.user_event` REST command each fire a custom JSON event on the call, and the Browser SDK -[receives it on the call object][browser-user-events]. Ada can put the driver's name and plate on screen while she says -them. +When the caller is in a browser, the call can push data to the page. +The SWML [`user_event`][swml-user-event] method, +the [`swml_user_event`][fr-user-event] tool action, +and the `calling.user_event` REST command +each fire a custom JSON event on the call, +and the Browser SDK [receives it on the call object][browser-user-events]. +Ada can put the driver's name and plate on screen while she says them. ## Next steps From f3a32e9d877ee0d3ac08b6de1d93a3bda7d87ba1 Mon Sep 17 00:00:00 2001 From: nirav Date: Tue, 6 Oct 2026 22:16:43 +0545 Subject: [PATCH 08/13] tweaks to title --- ...emed.svg => how-apps-are-built-themed.svg} | 2 +- .../platform/call-fabric/pick-a-product.mdx | 52 +++++++++++-------- 2 files changed, 31 insertions(+), 23 deletions(-) rename fern/assets/images/img/{recommended-path-themed.svg => how-apps-are-built-themed.svg} (98%) diff --git a/fern/assets/images/img/recommended-path-themed.svg b/fern/assets/images/img/how-apps-are-built-themed.svg similarity index 98% rename from fern/assets/images/img/recommended-path-themed.svg rename to fern/assets/images/img/how-apps-are-built-themed.svg index 2977f8e9a6..ab4e60b2b5 100644 --- a/fern/assets/images/img/recommended-path-themed.svg +++ b/fern/assets/images/img/how-apps-are-built-themed.svg @@ -1,5 +1,5 @@ - The recommended path: SWML and REST API from your stack + How most SignalWire apps are built: SWML and REST API from your stack A caller on a phone, SIP, or a browser reaches a phone number or Address, which points at a SWML Script Resource set to an external URL. The Resource fetches SWML from your stack, written with the Server SDKs Agents namespace, and the live call runs on SignalWire. The SWML makes SWAIG tool calls to your systems. The REST API, used through the Server SDKs REST namespace, sends call commands over HTTP to the live call, and manages numbers, Resources, and tokens in your Space configuration. diff --git a/fern/products/platform/pages/platform/call-fabric/pick-a-product.mdx b/fern/products/platform/pages/platform/call-fabric/pick-a-product.mdx index 210a47a127..533bc922a1 100644 --- a/fern/products/platform/pages/platform/call-fabric/pick-a-product.mdx +++ b/fern/products/platform/pages/platform/call-fabric/pick-a-product.mdx @@ -47,16 +47,17 @@ max-toc-depth: 3 [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 -A SignalWire app can answer phone calls with an AI agent, +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 those pieces with a handful of products (SWML, the REST APIs, the Browser SDK, and Relay), and most apps combine more than one. -Start with the recommended path, +Start with how most SignalWire apps are built, then use the tables below to match each part of your app to a product. -## The recommended path +## 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. @@ -73,7 +74,7 @@ and keep track of the call while it happens. -A caller on a phone, SIP, or a browser reaches a phone number or Address, which points at a SWML Script Resource set to an external URL. The Resource fetches SWML from your stack, written with the Server SDKs Agents namespace, and SignalWire runs the live call. The SWML makes SWAIG tool calls to your systems. From the same stack, the REST API, used through the Server SDKs REST namespace, sends call commands over HTTP to the live call, and manages numbers, Resources, and tokens in your Space configuration. +A caller on a phone, SIP, or a browser reaches a phone number or Address, which points at a SWML Script Resource set to an external URL. The Resource fetches SWML from your stack, written with the Server SDKs Agents namespace, and SignalWire runs the live call. The SWML makes SWAIG tool calls to your systems. From the same stack, the REST API, used through the Server SDKs REST namespace, sends call commands over HTTP to the live call, and manages numbers, Resources, and tokens in your Space configuration. @@ -132,7 +133,17 @@ The Python code and the SWML it generates are shown below. ```python title="Python — Agents" from signalwire import SWMLService -bayview = SWMLService(name="bayview-taxi", route="/bayview") +# to be used in the injecting call command example below +active_calls = {} + + +class BayviewTaxi(SWMLService): + def on_request(self, request_data=None, callback_path=None): + call = (request_data or {}).get("call", {}) + active_calls[call.get("call_id")] = call.get("from") + + +bayview = BayviewTaxi(name="bayview-taxi", route="/bayview") bayview.answer() bayview.prompt( @@ -199,15 +210,11 @@ sections: The Server SDKs protect your server with basic auth. -Set `SWML_BASIC_AUTH_USER` and `SWML_BASIC_AUTH_PASSWORD` before you start it, +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`. -Without them, the server generates a random password at startup -and rejects SignalWire's requests. -Step 4 in practice: -before a maintenance window, -your backend can transfer each live call to a short inline SWML document that apologizes and hangs up: +The following Calling API command sent asynchronously will end the targeted live call with a message. @@ -216,18 +223,19 @@ 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": {}}, - ] +for call_id in active_calls: + client.calling.transfer( + call_id, + 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" From 61a500ffae8236d7511ddcb746f8ce8fb3b75570 Mon Sep 17 00:00:00 2001 From: nirav Date: Tue, 6 Oct 2026 22:25:35 +0545 Subject: [PATCH 09/13] update wording --- .../platform/pages/platform/call-fabric/pick-a-product.mdx | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/fern/products/platform/pages/platform/call-fabric/pick-a-product.mdx b/fern/products/platform/pages/platform/call-fabric/pick-a-product.mdx index 533bc922a1..ce43321357 100644 --- a/fern/products/platform/pages/platform/call-fabric/pick-a-product.mdx +++ b/fern/products/platform/pages/platform/call-fabric/pick-a-product.mdx @@ -214,7 +214,10 @@ 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`. -The following Calling API command sent asynchronously will end the targeted live call with a message. +To steer a live call, +like the one the dialplan above answered, +send it a Calling API command from anywhere, at any time. +This code ends each call in `active_calls` with a message: From 4d2c59d59a8de829c86f62180e81bd3c79335cc4 Mon Sep 17 00:00:00 2001 From: nirav Date: Wed, 7 Oct 2026 17:34:04 +0545 Subject: [PATCH 10/13] wording --- .../platform/call-fabric/pick-a-product.mdx | 26 +++++++++---------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/fern/products/platform/pages/platform/call-fabric/pick-a-product.mdx b/fern/products/platform/pages/platform/call-fabric/pick-a-product.mdx index ce43321357..6adb219862 100644 --- a/fern/products/platform/pages/platform/call-fabric/pick-a-product.mdx +++ b/fern/products/platform/pages/platform/call-fabric/pick-a-product.mdx @@ -49,25 +49,25 @@ max-toc-depth: 3 [tool-calling]: /docs/platform/ai/tool-calling [make-receive-calls]: /docs/platform/voice/make-and-receive-calls +SignalWire helps you build communications apps of any size, +from an AI voicemail assistant to a HIPAA-compliant telehealth platform. 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 those pieces with a handful of products (SWML, the REST APIs, the Browser SDK, and Relay), +You compose your app from a handful of products (SWML, the REST APIs, the Browser SDK, and Relay) and most apps combine more than one. -Start with how most SignalWire apps are built, -then use the tables below to match each part of your app to a product. ## 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 defines the dialplan: -a set of rules that describes how you want the call to proceed. +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. This can include forwarding the call, recording a voicemail, or running a full IVR system. -SWML is a JSON or YAML document, -and the Agents namespace generates it for you +The Agents namespace generates the SWML for you, with easier maintenance and better validation than writing it by hand. +It also serves the SWML and adapts it to each call's context. SWML has deep AI integrations and webhook support, so you can let AI handle most of the communication and keep track of the call while it happens. @@ -291,13 +291,13 @@ and the ID of the call to end. ## The products -| Product | What you write | Runs on | Use it for | +| Product | Description | Execution environment | Use cases | |---|---|---|---| -| SWML | The call flow, as a document | Served from your web server, or hosted by SignalWire | Handling calls and AI agents. Start here. | -| REST APIs | One request per action | Anywhere | Setup, outbound calls and messages, live call commands | -| Browser SDK | A calling client | The user's browser | Calls and chat from a web page | -| WebSocket (Relay) | Code that drives each call | Your always-on process | Step-by-step, event-driven call control | -| Call Flow Builder | Nothing: you draw the flow in the Dashboard | SignalWire | Simple voice flows without code | +| SWML | JSON or YAML call flow, generated by the Server SDKs | Your web server, or hosted by SignalWire | 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 | +| WebSocket (Relay) | Persistent connection that streams call events to your code | A long-running process you host | Event-driven, step-by-step call control | +| Call Flow Builder | Visual call flow editor in the Dashboard | SignalWire | Simple voice flows without code | ### SWML From e3b2c636f662b5ac340f6c9cea9c0a9ea5685e32 Mon Sep 17 00:00:00 2001 From: nirav Date: Wed, 14 Oct 2026 23:50:07 +0545 Subject: [PATCH 11/13] ux update --- .../images/img/how-apps-are-built-themed.svg | 31 +- fern/llms.txt | 2 +- .../platform/call-fabric/pick-a-product.mdx | 299 +++++------------- 3 files changed, 102 insertions(+), 230 deletions(-) diff --git a/fern/assets/images/img/how-apps-are-built-themed.svg b/fern/assets/images/img/how-apps-are-built-themed.svg index ab4e60b2b5..2e9e99c169 100644 --- a/fern/assets/images/img/how-apps-are-built-themed.svg +++ b/fern/assets/images/img/how-apps-are-built-themed.svg @@ -1,6 +1,6 @@ - How most SignalWire apps are built: SWML and REST API from your stack - A caller on a phone, SIP, or a browser reaches a phone number or Address, which points at a SWML Script Resource set to an external URL. The Resource fetches SWML from your stack, written with the Server SDKs Agents namespace, and the live call runs on SignalWire. The SWML makes SWAIG tool calls to your systems. The REST API, used through the Server SDKs REST namespace, sends call commands over HTTP to the live call, and manages numbers, Resources, and tokens in your Space configuration. + How most SignalWire apps are built: an agent and a REST client in your server application + A caller on a phone, SIP, or a browser reaches a phone number or Address, which points at a SWML Script Resource set to an external URL. The Resource fetches SWML from the agent in your server application, built with the Server SDKs Agents namespace, and SignalWire runs the live call. During the call, SignalWire calls SWAIG tools on the agent, which looks up data in your business logic. The REST client in the same application, built with the Server SDKs REST namespace, sends call commands over HTTP to the live call and provisions numbers, Resources, and Subscribers in your Space. diff --git a/fern/llms.txt b/fern/llms.txt index 5766f1bbd7..677d148530 100644 --- a/fern/llms.txt +++ b/fern/llms.txt @@ -49,7 +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 SignalWire's products (SWML through the Server SDKs, the REST APIs, the Browser SDK, and Relay), see which one fits each use case, and combine them with phone numbers, Resources, tools, and Datasphere. +- [Pick the right SignalWire product](/docs/platform/pick-a-product): Compare SignalWire's products (SWML through the Server SDKs, the REST APIs, the Browser SDK, and Relay), see which one fits each calling, messaging, or fax use case, and combine them with phone numbers, Resources, tools, and Datasphere. - [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. - [Resources](/docs/platform/resources): Communication entities such as AI agents, SignalWire Markup Language (SWML) scripts, Subscribers, and Video Rooms. diff --git a/fern/products/platform/pages/platform/call-fabric/pick-a-product.mdx b/fern/products/platform/pages/platform/call-fabric/pick-a-product.mdx index 6adb219862..c81bd74398 100644 --- a/fern/products/platform/pages/platform/call-fabric/pick-a-product.mdx +++ b/fern/products/platform/pages/platform/call-fabric/pick-a-product.mdx @@ -3,14 +3,16 @@ 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 use case, and combine them with phone numbers, Resources, tools, and Datasphere. +description: Compare SignalWire's products (SWML through the Server SDKs, the REST APIs, the Browser SDK, and Relay), see which one fits each calling, messaging, or fax use case, and combine them with phone numbers, Resources, tools, and Datasphere. max-toc-depth: 3 --- [swml]: /docs/swml [swml-send-sms]: /docs/swml/reference/calling/send-sms [swml-user-event]: /docs/swml/reference/calling/user-event -[swml-transfer]: /docs/swml/reference/calling/transfer +[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 @@ -26,6 +28,8 @@ max-toc-depth: 3 [ts-rest-calling]: /docs/server-sdks/reference/typescript/rest/calling [py-rest-datasphere]: /docs/server-sdks/reference/python/rest/datasphere [relay-client]: /docs/server-sdks/guides/relay-client +[relay-send-message]: /docs/server-sdks/reference/python/relay/client/send-message +[relay-receive]: /docs/server-sdks/reference/python/relay/client/receive [rest-api]: /docs/apis [call-commands]: /docs/apis/rest/calls/call-commands [create-message]: /docs/apis/rest/messages/create-message @@ -48,14 +52,18 @@ max-toc-depth: 3 [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 +[hipaa]: /docs/platform/compliance/hipaa +[fax]: /docs/platform/fax SignalWire helps you build communications apps of any size, -from an AI voicemail assistant to a HIPAA-compliant telehealth platform. +from an AI voicemail assistant to a [HIPAA-compliant][hipaa] telehealth platform. 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 compose your app from a handful of products (SWML, the REST APIs, the Browser SDK, and Relay) and most apps combine more than one. +Calls are where the products differ most, so most of this page is about calls. +[Messaging and fax](#messaging-and-fax) covers texting and faxing. ## How most SignalWire apps are built @@ -74,7 +82,7 @@ and keep track of the call while it happens. -A caller on a phone, SIP, or a browser reaches a phone number or Address, which points at a SWML Script Resource set to an external URL. The Resource fetches SWML from your stack, written with the Server SDKs Agents namespace, and SignalWire runs the live call. The SWML makes SWAIG tool calls to your systems. From the same stack, the REST API, used through the Server SDKs REST namespace, sends call commands over HTTP to the live call, and manages numbers, Resources, and tokens in your Space configuration. +A caller on a phone, SIP, or a browser reaches a phone number or Address, which points at a SWML Script Resource set to an external URL. The Resource fetches SWML from the agent in your server application, built with the Server SDKs Agents namespace, and SignalWire runs the live call. During the call, SignalWire calls SWAIG tools on the agent, which looks up data in your business logic. The REST client in the same application, built with the Server SDKs REST namespace, sends call commands over HTTP to the live call and provisions numbers, Resources, and Subscribers in your Space. @@ -87,20 +95,20 @@ flowchart LR Address["Phone number
or Address"] Resource["Resource
SWML Script · external URL"] Call(("Live call")) - Platform["Space configuration"] + Platform["Your Space
numbers · Resources · Subscribers"] end - subgraph Stack["Your stack"] - Systems["Your systems
data · rules"] - Agent["SWML
Server SDKs · Agents"] - Backend["REST API
Server SDKs · REST"] + subgraph App["Your server application"] + Systems["Your business logic
bookings · data · rules"] + Agent["Agent
Server SDKs · Agents"] + Backend["REST client
Server SDKs · REST"] end Caller --> Address Address --> Resource Resource --> Call - Resource -- "fetches SWML" --> Agent - Agent -- "SWAIG tool calls" --> Systems + Resource -- "fetches SWML, calls SWAIG tools" --> Agent + Agent -- "looks up data" --> Systems Backend -- "call commands over HTTP" --> Call - Backend -- "numbers · Resources · tokens" --> Platform + Backend -- "provisions" --> Platform ``` @@ -113,7 +121,7 @@ flowchart LR 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 permission, +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, @@ -133,7 +141,7 @@ The Python code and the SWML it generates are shown below. ```python title="Python — Agents" from signalwire import SWMLService -# to be used in the injecting call command example below +# call IDs of live calls, used by the call command example below active_calls = {} @@ -167,7 +175,7 @@ bayview.add_verb_to_section("ada", "ai", { }) bayview.add_section("person") -bayview.add_verb_to_section("person", "connect", {"to": "+15551234567"}) +bayview.add_verb_to_section("person", "connect", {"to": ""}) bayview.serve() ``` @@ -204,7 +212,7 @@ sections: post_prompt_url: https://example.com/call-summary person: - connect: - to: '+15551234567' + to: ```
@@ -217,7 +225,9 @@ 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 code ends each call in `active_calls` with a message: +The Python code continues the dialplan above +and ends each call in `active_calls` with a message. +The TypeScript and cURL versions end one call: @@ -287,17 +297,16 @@ curl -X POST "https://.signalwire.com/api/calling/calls" \ Replace the placeholders with the values from your [API credentials][api-credentials] page -and the ID of the call to end. +and `` with the ID of the call to end. ## The products | Product | Description | Execution environment | Use cases | |---|---|---|---| -| SWML | JSON or YAML call flow, generated by the Server SDKs | Your web server, or hosted by SignalWire | Call flows and AI agents. The recommended starting point. | +| SWML | JSON or YAML call flow, generated by the Server SDKs | Your web server, or hosted by SignalWire | 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 | -| WebSocket (Relay) | Persistent connection that streams call events to your code | A long-running process you host | Event-driven, step-by-step call control | -| Call Flow Builder | Visual call flow editor in the Dashboard | SignalWire | Simple voice flows without code | +| Relay | Persistent connection that streams call events to your code | A long-running process you host | Event-driven, step-by-step call control | ### SWML @@ -411,7 +420,7 @@ client.ready$.subscribe(async (ready) => { }); ``` -### WebSocket (Relay) +### Relay The [Relay namespace][relay-client] of the Server SDKs holds a persistent WebSocket connection to SignalWire. Your process subscribes to contexts, @@ -427,10 +436,34 @@ without the webhook layer. [Call Flow Builder][cfb] lets you draw a dialplan, one node per step. An [AI Agent Resource][resources-dashboard] configures an agent's prompt, voice, and tools in the Dashboard. Both produce Resources that you point a phone number at, with no code at all. -The **Click-to-Test** button lets you test the call straight from the Dashboard. +## 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 as `messages.create`. +A Relay process can send one with [`send_message`][relay-send-message]. +During a call, the SWML [`send_sms`][swml-send-sms] method or the [`send_sms`][fr-send-sms] tool action 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][relay-receive]. +Messaging SWML is a separate flavor of SWML with methods such as `reply`. +The Agents namespace generates calling SWML only, +so you write Messaging SWML as YAML or JSON yourself. + +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 +and point it at SWML that runs [`receive_fax`][swml-receive-fax]. +The Agents namespace generates both methods, +and Relay has `send_fax` and `receive_fax` on its call object. +[First steps with fax][fax] walks through both directions. + ## Match your use case to a product | You're building | Use | @@ -441,6 +474,8 @@ The **Click-to-Test** button lets you test the call straight from the Dashboard. | 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 | +| 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] | @@ -458,212 +493,46 @@ The **Click-to-Test** button lets you test the call straight from the Dashboard. ## How the pieces work together -Each pattern below combines a product with a building block or with another product, -and continues the Bayview Taxi example, +These patterns continue the Bayview Taxi example, whose AI dispatcher Ada answers the phone. ### Steer a running agent from your backend with REST commands -Ada books a ride, -and the call stays up while the dispatch system finds a driver. -When a driver accepts, -the dispatch system needs to tell Ada, -and through her the caller. -The call is SWML, run by SignalWire, -and your dispatch system never held a connection to it. -It needs only the call's ID and one HTTP request. - -Every SWAIG request carries the call's `call_id`. -Store it with the booking: - - - -```python title="Python — Agents" -# Install: python -m pip install signalwire-sdk==3.4.1 -# Save as dispatch_agent.py and run: python dispatch_agent.py -from signalwire import AgentBase, FunctionResult - -bookings = {} - -agent = AgentBase(name="dispatch-agent", route="/agent") -agent.add_language("English", "en-US", "rime.spore") -agent.prompt_add_section( - "Role", - body="You are Ada, the dispatcher for Bayview Taxi. Book the ride with book_ride, " - "then tell the caller you'll confirm their driver in a moment.", -) - - -def book_ride(args, raw_data): - booking_id = f"BT-{len(bookings) + 1:04d}" - bookings[booking_id] = {"pickup": args.get("pickup"), "call_id": raw_data.get("call_id")} - return FunctionResult(f"Booked as {booking_id}. A driver is being assigned.") - - -agent.define_tool( - name="book_ride", - description="Book a pickup at the address the caller gave", - parameters={ - "type": "object", - "properties": {"pickup": {"type": "string", "description": "The pickup address"}}, - "required": ["pickup"], - }, - handler=book_ride, -) - -if __name__ == "__main__": - agent.run() -``` - -```typescript title="TypeScript — Agents" -// Install: npm install @signalwire/sdk@2.0.5 -// This sample also runs as JavaScript: save as dispatch-agent.mjs, -// then run: node dispatch-agent.mjs -import { AgentBase, FunctionResult } from '@signalwire/sdk'; - -const bookings = new Map(); - -const agent = new AgentBase({ name: 'dispatch-agent', route: '/agent' }); -agent.addLanguage({ name: 'English', code: 'en-US', voice: 'rime.spore' }); -agent.promptAddSection('Role', { - body: - "You are Ada, the dispatcher for Bayview Taxi. Book the ride with book_ride, " + - "then tell the caller you'll confirm their driver in a moment.", -}); - -agent.defineTool({ - name: 'book_ride', - description: 'Book a pickup at the address the caller gave', - parameters: { - type: 'object', - properties: { pickup: { type: 'string', description: 'The pickup address' } }, - required: ['pickup'], - }, - handler: (args, rawData) => { - const bookingId = `BT-${String(bookings.size + 1).padStart(4, '0')}`; - bookings.set(bookingId, { pickup: args.pickup, callId: rawData.call_id }); - return new FunctionResult(`Booked as ${bookingId}. A driver is being assigned.`); - }, -}); - -await agent.run(); -``` - - - -The `bookings` map stands in for your dispatch system's database. -When a driver accepts, -the dispatch system sends [`calling.ai_message`][call-commands] to that call. -The message joins Ada's conversation as a system instruction, -which the caller doesn't hear: - - - -```python title="Python — REST client" -# Install: python -m pip install signalwire-sdk==3.4.1 -# Save as driver_assigned.py and run: python driver_assigned.py -from signalwire.rest import RestClient - -client = RestClient( - project="", - token="", - host=".signalwire.com", -) - -client.calling.ai_message( - "", - role="system", - message_text="Driver Sam accepted booking BT-0001 and arrives in 6 minutes " - "in a white Prius. Tell the caller.", -) -``` - -```typescript title="TypeScript — REST client" -// Install: npm install @signalwire/sdk@2.0.5 -// This sample also runs as JavaScript: save as driver-assigned.mjs, -// then run: node driver-assigned.mjs -import { RestClient } from '@signalwire/sdk'; - -const client = new RestClient({ - project: '', - token: '', - host: '.signalwire.com', -}); - -await client.calling.aiMessage('', { - role: 'system', - message_text: - 'Driver Sam accepted booking BT-0001 and arrives in 6 minutes ' + - 'in a white Prius. Tell the caller.', -}); -``` - -```bash title="cURL — Calling API" -curl -X POST "https://.signalwire.com/api/calling/calls" \ - -u ":" \ - -H "Content-Type: application/json" \ - -d '{ - "id": "", - "command": "calling.ai_message", - "params": { - "role": "system", - "message_text": "Driver Sam accepted booking BT-0001 and arrives in 6 minutes in a white Prius. Tell the caller." - } - }' -``` - - - -Replace ``, ``, and `` -with the values from your [API credentials][api-credentials] page, -and `` with the `call_id` stored with the booking. -The token needs the **Voice** permission. - -The same request shape carries every other call command, -each one a single HTTP request against the `call_id`. +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. See the [Python][py-rest-calling] and [TypeScript][ts-rest-calling] REST client references for every command. ### Let a tool act on the call -A SWAIG tool can do more than return text. -Its [`FunctionResult`][function-result] can also carry -actions that SignalWire performs on the call -as soon as the reply arrives. -Ada's `book_ride` could [text the caller a confirmation][fr-send-sms], +A tool's [reply][function-result] can carry actions on the call as well as text. +Ada's `book_ride` tool can [text the caller a confirmation][fr-send-sms], start a recording, -or transfer the call to a person. -It can even [send a message to the agent on a different call][fr-rpc-ai-message], -which is how one caller's agent can update another's. -The same capabilities exist as SWML methods, -such as [`send_sms`][swml-send-sms] and [`transfer`][swml-transfer]; -the SDK writes them for you. - -Use tool actions when the conversation itself decides what happens next. -Use REST commands when something outside the conversation does, -like the driver accepting. - -### Point a phone number, or a browser, at the same agent - -An agent is reachable at an Address once it's behind a Resource. -Create a SWML Script Resource set to an external URL that points at the agent running on your server, -then give it the Addresses callers use: -a phone number for the phone network, -and an alias such as `/public/bayview-dispatch` for everything else. -The [Mapping numbers guide][mapping-numbers] walks through it. +transfer the call to a person, +or [send a message to the agent on another call][fr-rpc-ai-message]. +Use tool actions when the conversation decides what happens next, +and REST commands when something outside the conversation does, like a driver accepting. -A Browser SDK user dials that alias -and talks to Ada from a web page, -with no phone number involved. +### Reach the same agent from a phone or a browser + +Give the agent's SWML Script Resource two Addresses: +a phone number for callers on the phone network, +and an alias such as `/public/bayview-dispatch` for Browser SDK users. +Both reach the same agent. +The [Mapping numbers guide][mapping-numbers] walks through it. ### Update a browser from inside the call -When the caller is in a browser, the call can push data to the page. -The SWML [`user_event`][swml-user-event] method, +When the caller is in a browser, +your server can push JSON to the page during the call +with the SWML [`user_event`][swml-user-event] method, the [`swml_user_event`][fr-user-event] tool action, -and the `calling.user_event` REST command -each fire a custom JSON event on the call, -and the Browser SDK [receives it on the call object][browser-user-events]. -Ada can put the driver's name and plate on screen while she says them. +or the [`calling.user_event`][call-commands] REST command. +The Browser SDK [receives it on the call object][browser-user-events], +so Ada can put the driver's name and plate on screen while she says them. ## Next steps From 191699ea286dbdc8fea04d82d86915d0ed80994e Mon Sep 17 00:00:00 2001 From: nirav Date: Mon, 19 Oct 2026 18:46:19 +0545 Subject: [PATCH 12/13] address review --- .../images/img/how-apps-are-built-themed.svg | 37 +++--- .../platform/call-fabric/pick-a-product.mdx | 108 +++++++++++------- 2 files changed, 87 insertions(+), 58 deletions(-) diff --git a/fern/assets/images/img/how-apps-are-built-themed.svg b/fern/assets/images/img/how-apps-are-built-themed.svg index 2e9e99c169..e7e02aeb70 100644 --- a/fern/assets/images/img/how-apps-are-built-themed.svg +++ b/fern/assets/images/img/how-apps-are-built-themed.svg @@ -1,6 +1,6 @@ - How most SignalWire apps are built: an agent and a REST client in your server application - A caller on a phone, SIP, or a browser reaches a phone number or Address, which points at a SWML Script Resource set to an external URL. The Resource fetches SWML from the agent in your server application, built with the Server SDKs Agents namespace, and SignalWire runs the live call. During the call, SignalWire calls SWAIG tools on the agent, which looks up data in your business logic. The REST client in the same application, built with the Server SDKs REST namespace, sends call commands over HTTP to the live call and provisions numbers, Resources, and Subscribers in your Space. + How most SignalWire apps are built: the Server SDKs' Agents and REST namespaces in your server application + A caller on a phone, SIP, or a browser reaches a phone number or Address, which points at a SWML Script Resource set to an external URL. Your server application uses the Server SDKs. The Resource fetches SWML from the agent, built with the Agents namespace, and SignalWire runs the live call. During the call, SignalWire calls SWAIG tools on the agent, which looks up data in your business logic. The REST client, built with the REST namespace of the same Server SDKs, sends call commands over HTTP to the live call and provisions numbers, Resources, and Subscribers in your Space. @@ -62,34 +64,37 @@ Your Space Numbers · Resources · Subscribers - - Your business logic - Bookings · data · rules + + Your business logic + Bookings · data · rules - - Agent - Server SDKs · Agents + + SERVER SDKS - + + Agent + Agents namespace + + REST client - Server SDKs · REST + REST namespace fetches SWML - + calls SWAIG tools - looks up data - + looks up data + call commands - + over HTTP - provisions - + provisions + diff --git a/fern/products/platform/pages/platform/call-fabric/pick-a-product.mdx b/fern/products/platform/pages/platform/call-fabric/pick-a-product.mdx index c81bd74398..ffcf3be7bc 100644 --- a/fern/products/platform/pages/platform/call-fabric/pick-a-product.mdx +++ b/fern/products/platform/pages/platform/call-fabric/pick-a-product.mdx @@ -3,13 +3,12 @@ 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, messaging, or fax use case, and combine them with phone numbers, Resources, tools, and Datasphere. +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-send-sms]: /docs/swml/reference/calling/send-sms -[swml-user-event]: /docs/swml/reference/calling/user-event [swml-send-fax]: /docs/swml/reference/calling/send-fax [swml-receive-fax]: /docs/swml/reference/calling/receive-fax [swml-messaging]: /docs/swml/reference/messaging @@ -17,12 +16,8 @@ max-toc-depth: 3 [sdk-quickstart]: /docs/server-sdks/guides/quickstart [agent-base]: /docs/server-sdks/guides/agent-base [result-actions]: /docs/server-sdks/guides/result-actions -[function-result]: /docs/server-sdks/reference/python/agents/function-result [fr-send-sms]: /docs/server-sdks/reference/python/agents/function-result/send-sms -[fr-user-event]: /docs/server-sdks/reference/python/agents/function-result/swml-user-event -[fr-rpc-ai-message]: /docs/server-sdks/reference/python/agents/function-result/rpc-ai-message [datasphere-skill]: /docs/server-sdks/reference/python/agents/skills/datasphere -[mapping-numbers]: /docs/server-sdks/guides/mapping-numbers [rest-client]: /docs/server-sdks/guides/rest-client [py-rest-calling]: /docs/server-sdks/reference/python/rest/calling [ts-rest-calling]: /docs/server-sdks/reference/typescript/rest/calling @@ -41,7 +36,6 @@ max-toc-depth: 3 [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 -[browser-user-events]: /docs/browser-sdk/v4/guides/call-controls#receive-user-events-from-the-call [cfb]: /docs/call-flow-builder [resources]: /docs/platform/resources [resources-dashboard]: /docs/platform/resources#in-the-dashboard @@ -54,6 +48,11 @@ max-toc-depth: 3 [make-receive-calls]: /docs/platform/voice/make-and-receive-calls [hipaa]: /docs/platform/compliance/hipaa [fax]: /docs/platform/fax +[ai-chat]: /docs/platform/ai/chat +[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 +[chat-client]: /docs/server-sdks/reference/python/agents/ai-chat-client +[chat-gateway]: /docs/server-sdks/reference/python/agents/chat-gateway SignalWire helps you build communications apps of any size, from an AI voicemail assistant to a [HIPAA-compliant][hipaa] telehealth platform. @@ -63,7 +62,8 @@ and text your customers. You compose your app from a handful of products (SWML, the REST APIs, the Browser SDK, and Relay) and most apps combine more than one. Calls are where the products differ most, so most of this page is about calls. -[Messaging and fax](#messaging-and-fax) covers texting and faxing. +[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. ## How most SignalWire apps are built @@ -82,7 +82,7 @@ and keep track of the call while it happens. -A caller on a phone, SIP, or a browser reaches a phone number or Address, which points at a SWML Script Resource set to an external URL. The Resource fetches SWML from the agent in your server application, built with the Server SDKs Agents namespace, and SignalWire runs the live call. During the call, SignalWire calls SWAIG tools on the agent, which looks up data in your business logic. The REST client in the same application, built with the Server SDKs REST namespace, sends call commands over HTTP to the live call and provisions numbers, Resources, and Subscribers in your Space. +A caller on a phone, SIP, or a browser reaches a phone number or Address, which points at a SWML Script Resource set to an external URL. Your server application uses the Server SDKs. The Resource fetches SWML from the agent, built with the Agents namespace, and SignalWire runs the live call. During the call, SignalWire calls SWAIG tools on the agent, which looks up data in your business logic. The REST client, built with the REST namespace of the same Server SDKs, sends call commands over HTTP to the live call and provisions numbers, Resources, and Subscribers in your Space. @@ -99,8 +99,10 @@ flowchart LR end subgraph App["Your server application"] Systems["Your business logic
bookings · data · rules"] - Agent["Agent
Server SDKs · Agents"] - Backend["REST client
Server SDKs · REST"] + subgraph SDKs["Server SDKs"] + Agent["Agent
Agents namespace"] + Backend["REST client
REST namespace"] + end end Caller --> Address Address --> Resource @@ -439,6 +441,49 @@ Both produce Resources that you point a phone number at, with no code at all. +## 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. +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. +A web page reaches the agent through [`ChatGateway`][chat-gateway] running in your web application, +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 — AIChatClient" +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()) +``` + +`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. @@ -475,6 +520,7 @@ and Relay has `send_fax` and `receive_fax` on its call object. | 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 | +| An AI agent customers chat with on your website or over SMS | [AI Chat API][chat-api] with [`AIChatClient`][chat-client] or [`ChatGateway`][chat-gateway] | | 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] | @@ -493,9 +539,6 @@ and Relay has `send_fax` and `receive_fax` on its call object. ## How the pieces work together -These patterns continue the Bayview Taxi example, -whose AI dispatcher Ada answers the phone. - ### Steer a running agent from your backend with REST commands Every SWAIG request your agent receives carries the call's `call_id`, @@ -506,34 +549,6 @@ Ada receives it as a system instruction the caller doesn't hear, and tells the caller their driver is on the way. See the [Python][py-rest-calling] and [TypeScript][ts-rest-calling] REST client references for every command. -### Let a tool act on the call - -A tool's [reply][function-result] can carry actions on the call as well as text. -Ada's `book_ride` tool can [text the caller a confirmation][fr-send-sms], -start a recording, -transfer the call to a person, -or [send a message to the agent on another call][fr-rpc-ai-message]. -Use tool actions when the conversation decides what happens next, -and REST commands when something outside the conversation does, like a driver accepting. - -### Reach the same agent from a phone or a browser - -Give the agent's SWML Script Resource two Addresses: -a phone number for callers on the phone network, -and an alias such as `/public/bayview-dispatch` for Browser SDK users. -Both reach the same agent. -The [Mapping numbers guide][mapping-numbers] walks through it. - -### Update a browser from inside the call - -When the caller is in a browser, -your server can push JSON to the page during the call -with the SWML [`user_event`][swml-user-event] method, -the [`swml_user_event`][fr-user-event] tool action, -or the [`calling.user_event`][call-commands] REST command. -The Browser SDK [receives it on the call object][browser-user-events], -so Ada can put the driver's name and plate on screen while she says them. - ## Next steps @@ -549,4 +564,13 @@ so Ada can put the driver's name and plate on screen while she says them. 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. + From f383ebdf2b96e058a2cd46187a8fa2cd3ed95e9a Mon Sep 17 00:00:00 2001 From: Devon-White Date: Thu, 12 Nov 2026 11:06:59 -0500 Subject: [PATCH 13/13] Apply review feedback on the Pick a product page - 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. --- .../images/img/how-apps-are-built-themed.svg | 13 +- fern/llms.txt | 2 +- .../build-voice-video/call-controls.mdx | 26 +- .../platform/pages/getting-started.mdx | 2 + .../call-fabric => }/pick-a-product.mdx | 306 ++++++++++++------ fern/products/platform/platform.yml | 2 +- 6 files changed, 233 insertions(+), 118 deletions(-) rename fern/products/platform/pages/{platform/call-fabric => }/pick-a-product.mdx (67%) diff --git a/fern/assets/images/img/how-apps-are-built-themed.svg b/fern/assets/images/img/how-apps-are-built-themed.svg index e7e02aeb70..2dc4c52d72 100644 --- a/fern/assets/images/img/how-apps-are-built-themed.svg +++ b/fern/assets/images/img/how-apps-are-built-themed.svg @@ -1,6 +1,6 @@ How most SignalWire apps are built: the Server SDKs' Agents and REST namespaces in your server application - A caller on a phone, SIP, or a browser reaches a phone number or Address, which points at a SWML Script Resource set to an external URL. Your server application uses the Server SDKs. The Resource fetches SWML from the agent, built with the Agents namespace, and SignalWire runs the live call. During the call, SignalWire calls SWAIG tools on the agent, which looks up data in your business logic. The REST client, built with the REST namespace of the same Server SDKs, sends call commands over HTTP to the live call and provisions numbers, Resources, and Subscribers in your Space. + A caller on a phone, SIP, or a browser reaches a phone number or Address, which points at a SWML Script Resource set to an external URL. Your server application uses the Server SDKs. The Resource fetches SWML from the agent, built with the Agents namespace, and SignalWire runs the live call. During the call, the live call calls SWAIG tools on the agent, which looks up data in your business logic. The REST client, built with the REST namespace of the same Server SDKs, sends call commands over HTTP to the live call and provisions numbers, Resources, and Subscribers in your Space. A caller on a phone, SIP, or a browser reaches a phone number or Address, which points at a SWML Script Resource set to an external URL. Your server application uses the Server SDKs. The Resource fetches SWML from the agent, built with the Agents namespace, and SignalWire runs the live call. During the call, SignalWire calls SWAIG tools on the agent, which looks up data in your business logic. The REST client, built with the REST namespace of the same Server SDKs, sends call commands over HTTP to the live call and provisions numbers, Resources, and Subscribers in your Space. +A caller on a phone, SIP, or a browser reaches a phone number or Address, which points at a SWML Script Resource set to an external URL. Your server application uses the Server SDKs. The Resource fetches SWML from the agent, built with the Agents namespace, and SignalWire runs the live call. During the call, the live call calls SWAIG tools on the agent, which looks up data in your business logic. The REST client, built with the REST namespace of the same Server SDKs, sends call commands over HTTP to the live call and provisions numbers, Resources, and Subscribers in your Space. @@ -107,7 +110,8 @@ flowchart LR Caller --> Address Address --> Resource Resource --> Call - Resource -- "fetches SWML, calls SWAIG tools" --> Agent + Resource -- "fetches SWML" --> Agent + Call -- "calls SWAIG tools" --> Agent Agent -- "looks up data" --> Systems Backend -- "call commands over HTTP" --> Call Backend -- "provisions" --> Platform @@ -136,28 +140,18 @@ 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 code and the SWML it generates are shown below. +The Python and TypeScript versions each generate the SWML in the YAML tab. ```python title="Python — Agents" from signalwire import SWMLService -# call IDs of live calls, used by the call command example below -active_calls = {} - - -class BayviewTaxi(SWMLService): - def on_request(self, request_data=None, callback_path=None): - call = (request_data or {}).get("call", {}) - active_calls[call.get("call_id")] = call.get("from") - - -bayview = BayviewTaxi(name="bayview-taxi", route="/bayview") +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.", + 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( @@ -182,14 +176,49 @@ 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. + 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 @@ -227,9 +256,7 @@ 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. -The Python code continues the dialplan above -and ends each call in `active_calls` with a message. -The TypeScript and cURL versions end one call: +This one ends a call with a message: @@ -238,19 +265,18 @@ from signalwire.rest import RestClient client = RestClient(project="", token="", host=".signalwire.com") -for call_id in active_calls: - client.calling.transfer( - call_id, - 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": {}}, - ] - }, +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" @@ -263,14 +289,12 @@ const client = new RestClient({ }); await 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: {} }, - ], - }, + 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: {} }, + ], }, }); ``` @@ -303,9 +327,9 @@ and `` with the ID of the call to end. ## The products -| Product | Description | Execution environment | Use cases | +| Product | Description | Where your code runs | Use cases | |---|---|---|---| -| SWML | JSON or YAML call flow, generated by the Server SDKs | Your web server, or hosted by SignalWire | Call flows and AI agents (the recommended starting point) | +| 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 | @@ -315,7 +339,7 @@ and `` with the ID of the call to end. [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, +you [create an agent][agent-base], give it a prompt and tools, and run it as a web server. @@ -332,16 +356,24 @@ 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 = rides.lookup(args["booking_id"]) - return FunctionResult(f"The driver arrives in {ride.eta} minutes.") + ride = lookup_ride(args["booking_id"]) + return FunctionResult(f"The driver arrives in {ride['eta']} minutes.") agent.define_tool( @@ -358,7 +390,39 @@ agent.define_tool( agent.run() ``` -`rides.lookup` stands in for your booking system. +```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 @@ -376,8 +440,9 @@ 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. -These are the same commands the Relay namespace sends over its WebSocket, -delivered over HTTP instead. +Relay offers the same kind of call control over its WebSocket. + + ```python title="Python — REST client" from signalwire.rest import RestClient @@ -390,6 +455,23 @@ client.calling.ai_message("", role="system", message_text="Driver 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. @@ -433,11 +515,13 @@ 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. -An [AI Agent Resource][resources-dashboard] configures an agent's prompt, voice, and tools in the Dashboard. -Both produce Resources that you point a phone number at, with no code at all. +[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]. @@ -447,17 +531,19 @@ 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. -Each SWAIG request tells your server whether the conversation is `voice` or `chat`. +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' [`AIChatClient`][chat-client] sends each turn. -A web page reaches the agent through [`ChatGateway`][chat-gateway] running in your web application, +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 — AIChatClient" + + +```python title="Python — AI chat client" import asyncio from signalwire.ai_chat import AIChatClient @@ -481,6 +567,29 @@ async def main(): 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. @@ -490,24 +599,23 @@ 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 as `messages.create`. -A Relay process can send one with [`send_message`][relay-send-message]. -During a call, the SWML [`send_sms`][swml-send-sms] method or the [`send_sms`][fr-send-sms] tool action texts the caller. +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][relay-receive]. +or [receive them in a Relay process][sms-relay-receive]. Messaging SWML is a separate flavor of SWML with methods such as `reply`. -The Agents namespace generates calling SWML only, -so you write Messaging SWML as YAML or JSON yourself. +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, set a phone number to accept incoming calls as fax -and point it at SWML that runs [`receive_fax`][swml-receive-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 has `send_fax` and `receive_fax` on its call object. -[First steps with fax][fax] walks through both directions. +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 @@ -519,35 +627,35 @@ and Relay has `send_fax` and `receive_fax` on its call object. | 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 | -| An AI agent customers chat with on your website or over SMS | [AI Chat API][chat-api] with [`AIChatClient`][chat-client] or [`ChatGateway`][chat-gateway] | +| 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 (SWML Script, AI Agent, Subscriber, Video Room, 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. | +| [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 with the [REST namespace][py-rest-datasphere], then give the agent the [`datasphere` skill][datasphere-skill] | +| 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 any product, then [list, fetch, and delete][list-recordings] them with REST | - -## How the pieces work together +| 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 with REST commands +## 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. -See the [Python][py-rest-calling] and [TypeScript][ts-rest-calling] REST client references for every command. +The [REST client guide][rest-client] shows how to send call commands from the Server SDKs. ## Next steps diff --git a/fern/products/platform/platform.yml b/fern/products/platform/platform.yml index d515db864c..1a2dd72557 100644 --- a/fern/products/platform/platform.yml +++ b/fern/products/platform/platform.yml @@ -31,7 +31,7 @@ navigation: path: ./pages/getting-started.mdx icon: fa-regular fa-rocket - page: Pick a product - path: ./pages/platform/call-fabric/pick-a-product.mdx + path: ./pages/pick-a-product.mdx icon: fa-regular fa-compass - changelog: ./changelog title: Changelog