docs(voice): add inbound calling guide - #697
Open
Devon-White wants to merge 20 commits into
Open
Devon-White wants to merge 20 commits into
Devon-White wants to merge 20 commits into
Conversation
Companion to the outbound calling guide. Covers how a call reaches a Resource through its addresses (phone number, SIP address, alias), then answers a first call with SDK-served SWML, Relay, or the Browser SDK, assigns the number in the Dashboard or with REST, follows the call, and adds AI agent, phone menu, whisper, voicemail, recording, streaming, and browser-answering examples. Adds two themed lifecycle diagrams, a card on the Voice overview, and a root llms.txt link.
Contributor
Turn the Addresses page from a one-snippet stub into the reference for how a Resource is reached: phone numbers, SIP addresses, and aliases; contexts and channels; how SignalWire resolves an address; one Resource with many addresses; and how to manage addresses in the Dashboard, the REST API, and the Browser SDK. Add a shared snippet for assigning a Resource to a phone number, use it from Resources, Addresses, and the inbound calling guide, and trim the guide's addressing section to a summary that links here.
Frame the guide around where the logic runs and how SignalWire reaches it: SWML over HTTP (Server SDK), serverless SWML (hosted in the Space), WebSocket from your server (Relay), and WebSocket from the browser. Give serverless SWML its own tab in the handler and assignment steps instead of an aside and accordion, compare all four in one table, and state that only Subscriber tokens receive calls in the browser while guest and embed tokens are outbound-only.
Add a step that chooses how callers reach the handler: phone number, SIP address, or alias, independent of the handler choice. Split the old number-assignment step into creating the Resource (per handler) and giving it an address (per address type), with Dashboard and REST paths for each, and make the test-call step follow the chosen address.
…er SDK Name the four approaches by SDK and transport: Server SDK over HTTP (SWML), Server SDK over WebSocket (Relay), Browser SDK over WebSocket, and serverless SWML. Say outright that SWML is what the Server SDK serves and that the Browser SDK is Relay in the browser, so the comparison no longer sets SWML against a WebSocket it also uses.
Collaborator
|
Errors
Minor issues
Verified correct Two independent handlers per number. Message handlers restricted to messaging-capable types. SIP host format |
- Default alias context for AI Agents, scripts, and applications is private, not public; note which types get a public alias instead - Aliases can't be re-pointed in the Dashboard or REST: delete and re-create - Resource picker offers Video Room, not Conference Room, with its sub-choices - Link the admin List Resource Addresses endpoint, not the client one - Lowercase external context; 'such as' on the call handler list; SIP Credentials card; client.directory$ observable
Collaborator
Review: Resources and Addresses pagesGaps in the model
Structure
Already strongTwo-handler phone number explanation, SIP address vs Credential vs gateway, resolution flowchart, swap-a-handler example, REST task table. |
- Define handler at first use; state address/Resource relationship rules - Per-type table for the first alias's context; External URL scripts are public - Alias property list matching the REST object; display_type is derived - WhatsApp number as its own address type; deletion behavior - Contexts: public/private built in; only Subscriber dials may omit the context - Resources page hands off to Addresses instead of duplicating it; drop the self-referencing admonition; snippet says SIP Credentials
- Browser SDK: register() resolves on guest and embed tokens (they never ring); answer() with no options mirrors the caller's offer; transfer() needs a destination; pin @signalwire/js@4.0.0-rc.2 rxjs@7.8.2 in both voice guides (@latest resolves to 3.x) - Drop unsourced claims: a token with a new reference creating the Subscriber, ringback during connect.confirm, record_call posting at call end - Phone menu: Relay sample dials phones only, so prose says E.164; type the TypeScript lookup table so it passes tsc --strict - Create the Resource: Dashboard plus one cURL per tab; the TypeScript swmlWebhooks.create is deprecated in favor of setSwmlWebhook, which the shortcut Accordion already shows - Move the approach choice out of Steps into "Pick the right product", fold the Resource/address model into it, add per-surface bullets - Remove duplicated alias, guest-token, and browser status prose; add missing placeholders and sample headers; highlight the lines the Relay tracking sample adds; drop the Next steps section - Bare slug; alias form field is Name, matching the Addresses guide - Outbound: attach media before the capture-failure subsection
…aims Follow the outbound guide's flow — prepare, choose, set up, test, track, examples — and keep each handler's code and Dashboard setup together. Correct the capability claims the old matrix got wrong: - SWML and Relay do reach a person, via `connect` to a phone number, SIP address, or queue. The old table's single "a person answers" row conflated how a call is routed with where a person picks it up. - Serverless SWML can look a caller up with `request` and branch on the result with `switch`. What it can't do is vary the document per call. - Drop wording implying a company number must be assigned directly to a Subscriber for a browser user to answer; a routing handler can forward. Replace the check/cross scorecards with descriptive comparisons of purpose and control model, so a missing direct SDK method isn't read as the whole surface being underpowered. Build SWML through `SWMLService` and `SwmlBuilder` wherever the pinned SDK versions support the instruction, and order examples Python, TypeScript, then cURL. The raw `stream` payload stays, with a comment naming the version gap that requires it.
…risons Codify two conventions the calling guides now follow. Examples lead with the supported SDK: Python, then TypeScript, then cURL as the direct HTTP alternative. SWML instructions go through the builders, with YAML and JSON after. Any SDK or version gap that forces a raw request gets explained where it appears. Compare approaches by purpose and control model rather than by check/cross scorecard. A missing direct SDK method is not the same as something the whole flow can't do, since a browser client can reach a Resource that does it. State real restrictions at the scope the evidence supports. Link the capability-guides rule from CONTRIBUTING so the template is discoverable alongside the other authoring rules.
Flatten the Architecture section's pages directly into Platform > Core, and lead Core with Projects, Resources, Addresses, Subscribers, and Webhooks — the concepts the calling guides assume a reader already has. All 11 pages are preserved, each appearing exactly once.
…uides The combined SWML walkthrough is now covered by the platform inbound and outbound calling guides, which carry the same setup in more depth. Delete the page, redirect its URL to the inbound guide, and resolve all seven references: the SWML recipes and the phone numbers overview point at the inbound sections that replace them, and the voice overview drops the duplicate card, since both new guides are already listed there.
…o devon/inbound-calling-guide
Collaborator
Inbound calling vs. Receive WhatsApp calls: keep separate, cross-linkRecommendation: keep the two guides separate. They share a skeleton (prepare → credentials → hosted SWML → attach address → test → troubleshoot → read caller → follow the call), and the WhatsApp page duplicates the hosted-script creation and the Relay client almost verbatim. But about half of the WhatsApp page has no home in the inbound guide:
It's also step 3 of August's four-page WhatsApp calling cluster (overview → onboarding → enable voice → receive calls), and the inbound guide is already ~2,300 lines. Merging would either bury the WhatsApp-specific content or grow a page that needs splitting. The actual gap: the two pages don't link to each other at all. Suggested changes
Worth borrowing the other way: the WhatsApp page's "Pick the right product" matrix (SWML / Relay / REST / Call Flow Builder by function) is stronger than the inbound guide's approach table. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
/docs/platform/voice/inbound-calling, a companion to the outbound calling guide with the same shape: prepare, answer a first call, follow the call, examples, next steps.<llms-only>Mermaid equivalents.llms.txt.Review notes
PUT /api/relay/rest/phone_numbers/{id}withrelay_scriptandrelay_topic. The TypeSpec core model marks the Relay topic status callback URL as required, but the request model and both SDK wrappers make it optional; the guide follows the SDKs.sip:<user>@<space>-<context>.dapp.signalwire.comis taken from the Dashboard form's fixed prefix and suffix; confirm it's stable.host, per the RelayClient reference; the outbound guide passes the Space host.Verification
yarn fern-md-check: all 2749 MDX files valid.