docs(telephony): trunks-and-caller-IDs rework (PRO-2785, atoms-platform#3516) - #413
docs(telephony): trunks-and-caller-IDs rework (PRO-2785, atoms-platform#3516)#413abhishekmishragithub wants to merge 6 commits into
Conversation
Documents the telephony model shipping in atoms-platform#3516: SIP
trunks as one-resource-per-direction, agents answering on sources, and
per-call caller IDs. Written against the implementation, not the
proposal (no outbound bindings, transfer caller ID on the agent,
Deprecation header without a Sunset date since none is decided).
- OpenAPI: add /sip-trunk inbound+outbound CRUD, /agent/{id}/answers,
/agent/{id}/transfer-source; fromNumber on outbound calls (exact-match
semantics documented) and fromNumbers on campaigns with the legacy
fields marked deprecated; import-phone-number marked deprecated;
caller-ID resolution section rewritten (no platform fallback).
- New migration guide under the Deprecations tab: old-to-new mapping,
the compat window table, behavior changes, dashboard equivalents.
- SIP Trunking page: setup steps rewritten around the SIP Trunks page
and per-direction endpoints, agent attach step added, plus the
VPN-only/IP-whitelisting providers section (managed gateway, contact
support).
- Phone Numbers page: Import SIP tab content replaced with the SIP
Trunks flow; Campaigns page: Call from field + fromNumbers note.
- Changelog entry (re-date to the release day before merging).
Nav: SIP Trunks + Agent Telephony API groups, Telephony section in the
Deprecations tab.
|
crim doesn't review pull requests automatically here. Comment |
The literal 400 error string on `POST /conversation/outbound` keeps its em-dash because the platform emits it verbatim; every other em-dash in the migration guide, SIP trunking page, phone-numbers Import SIP tab, and openapi.yaml descriptions is rewritten to periods, semicolons, or commas.
Verification loop — docs claims vs platform PR #3516Cross-checked every routing, error, and lifecycle claim in the migration guide,
Push in this loop
Not blocking merge, but worth watching
Every claim in the migration guide, API-ref descriptions, and SIP Trunking page now matches the platform code at PR #3516's tip. |
Per the rework owner's direction, the deprecation list and window are now stated rather than left open: a Telephony section on the Deprecation Notices page enumerates every deprecated endpoint, request field, and response shape with its migration target; the migration guide gains an 'after the window' removal list and names 45 days from release (concrete sunset date to be published at release); the import-phone-number OpenAPI description and the changelog entry say the same.
|
Added per review direction: the deprecations are now communicated explicitly. A Telephony section on the Deprecation Notices page enumerates every deprecated endpoint, request field, and response shape with its migration target; the migration guide gains an after-the-window removal list; and the 45-day window is stated on the notices page, the migration guide, the import-phone-number API description, and the changelog entry (concrete sunset date to be published at release). One note for the platform side: the code currently sends only |
|
crim doesn't review pull requests automatically here. Comment |
|
crim review |
|
crim is reviewing this pull request. Findings will be posted shortly. |
![crim-app[bot]](https://avatars.githubusercontent.com/u/64185252?s=60&v=4){kind=small}
| "500": | ||
| $ref: "#/components/responses/InternalServerErrorResponse" | ||
|
|
||
| /sip-trunk/inbound: |
There was a problem hiding this comment.
Low: The new SIP-trunk / agent-answer / transfer-source paths declare x-fern-sdk-group-name/x-fern-sdk-method-name (so SDK methods are generated) but define no request/response body schemas beyond a description string on the responses.
Unlike the surrounding endpoints in this spec, the GET list endpoints have no 200 response schema and the mutating endpoints only describe the success body in prose. Generated SDK methods will return untyped/unknown bodies and the rendered API reference will show no response shape. Confidence: low on whether this is intentional for a docs-first stub.
There was a problem hiding this comment.
Assessment
A thorough, well-written documentation rework that introduces SIP trunks as first-class API resources, splits "who answers" from "what a call dials from," and provides migration/changelog/deprecation coverage; internal slugs, tags, and #operation/ anchors all check out. The main gap is that the developer-guide (SDK) pages were left untouched and still teach only the now-deprecated fields.
What this PR does
Adds OpenAPI paths for inbound/outbound SIP trunks, agent answer sources, and transfer caller ID; deprecates import-phone-number, fromProductId, phoneNumberIds, telephonyProductId/allowInboundCall; introduces fromNumber/fromNumbers; and adds a telephony migration guide, a changelog entry, deprecation-notice rows, and updates the SIP-trunking / phone-numbers / campaigns platform docs.
Findings
- Medium:
fern/products/atoms/pages/dev/build/phone-calling/outbound-calls.mdx:45— developer-guide pages still document the deprecated telephony model exclusively, inconsistent with this rework (alsocreating-campaigns.mdx,outbound-setup.mdx,buying-numbers.mdx,build-with-coding-agent.mdx). - Low:
fern/apis/atoms/openapi/openapi.yaml:4858— new SIP-trunk/answer endpoints declarex-fern-sdkmethods but no request/response body schemas, unlike surrounding endpoints.
Findings outside the diff
These concern lines GitHub won't allow inline comments on (unchanged or outside this PR's diff).
-
fern/products/atoms/pages/dev/build/phone-calling/outbound-calls.mdx:45— Medium: Developer-guide pages still teach the deprecated telephony model exclusively, so they now contradict this rework.This PR deprecates
fromProductId/phoneNumberIds/from_product_idand makesfromNumber/fromNumbersthe recommended surface, and the migration guide even calls campaigns "the one change that forces API integrators to ship code." Yetoutbound-calls.mdx(this line),creating-campaigns.mdx(phone_ids/phoneNumberIds),phone-numbers/outbound-setup.mdx,phone-numbers/buying-numbers.mdx, andbuild-with-coding-agent.mdxstill present the deprecated fields as the only/primary path with no deprecation note or pointer tofromNumber/fromNumbers. Readers following the developer guide will build against fields scheduled for removal. Consider updating these pages (or at least adding a deprecation callout linking to the telephony migration guide) as part of this change.
Hold off on mergingThe trunks got promoted to first-class resources, but the developer guide didn't get the memo and is still cheerfully handing out |
An agent answers on any number of sources; each source is answered by exactly one agent. Was implied by the conflict rule, now said outright on the SIP Trunking setup step and in the migration guide, with the transfers-refused-without-a-transfer-source consequence beside it.
1 participant
Summary
Public docs for the telephony rework in smallest-inc/atoms-platform#3516 (PRO-2785): SIP trunks become one resource per direction, an agent answers on a number/trunk, and every call names its own caller ID.
atoms-platform#3516 is live on prod (merged 2026-09-04 19:59 UTC); verified that no post-review commit touched the documented API surface (routes, validation, compat, resolution). Changelog entry dated to the release day. Stacked on #412: merge order is #411 -> #412 -> #413.
Written against the PR's implementation, not the Notion proposal. Where they diverge, the code wins:
fromNumber/fromNumbers/ transfer source). The/agent/{id}/telephonyroutes from the proposal were never built; the real surface is/agent/{id}/answers+PUT /agent/{id}/transfer-source.Deprecation: truewith noSunsetheader, and the docs say "a removal date will be announced" rather than repeating the proposal's 45-day window (which exists only in the ticket).fromNumberon/conversation/outboundis matched exactly (no E.164 normalization) — documented explicitly, since+1 415 555 2671fails where+14155552671works.import-phone-numberstill works (201 + Deprecation header), documented as deprecated, not removed.Changes
/sip-trunk/{inbound,outbound}CRUD,/agent/{agentId}/answers(+ delete by sourceId),/agent/{agentId}/transfer-source;fromNumber+ deprecatedfromProductIdon outbound calls;fromNumbers+ deprecatedphoneNumberIdson campaigns;import-phone-numbermarked deprecated; caller-ID resolution description rewritten (the silent platform-number fallback is gone from the product, so it is gone from the docs).fromNumbersAPI note (frozen list, rotation, retry stability).Test plan
/voice-agents/deprecations/telephony-migration).