Merge branch 'main' into august-20260623-whatsapp-messaging

Author: hey-august

fern/apis/signalwire-rest/openapi.yaml

@@ -216,6 +216,10 @@ navigation:
               - freeSwitchConnector
             contents: []
           - relayApplication
+          - section: SIP Addresses
+            referenced-packages:
+              - sipAddresses
+            contents: []
           - section: SIP Credentials
             referenced-packages:
               - sipCredentials

fern/products/apis/apis.yml

@@ -11,32 +11,67 @@ x-custom:
 ---
 
 
-Resources are the primary entities for communication within the Call Fabric ecosystem.
-They are the building blocks of the system, representing the various communication elements
-that can be used to interact with 
-[subscribers](/docs/platform/subscribers). 
+Resources are the core building blocks of the SignalWire ecosystem. 
+They are container objects that represent your choice of communication entity. 
+This can be anything from a SignalWire AI Agent or a SWML script, to a Subscriber that can be created, addressed and called within your SignalWire Space. 
+
+Every Resource has a **Type** and one or more **Addresses** that make it reachable, and all Resources share the same addressing and management model.
+No matter what Resource you need you can create, configure, and call them all in the same consistent way.
+
+## Resource types
+
+Call Fabric supports several Resource types. Some of the most common are:
+
+<CardGroup cols={3}>
+  <Card title="Subscribers" href="/docs/platform/subscribers">
+    Users in your communication system, with built-in authentication and communication endpoints.
+  </Card>
+  <Card title="AI Agents" href="/docs/platform/ai">
+    Conversational AI agents that can answer and place calls.
+  </Card>
+  <Card title="SWML Scripts" href="/docs/swml">
+    Programmable call logic written in SWML (JSON or YAML).
+  </Card>
+  <Card title="cXML Scripts" href="/docs/compatibility-api/cxml">
+    Twilio-compatible call logic for migrating existing applications.
+  </Card>
+  <Card title="SIP Endpoints" href="/docs/platform/voice/sip">
+    Register SIP devices and softphones to your Space.
+  </Card>
+  <Card title="Video Rooms" href="/docs/platform/video">
+    Programmable video conference rooms.
+  </Card>
+</CardGroup>
+
+Each of these Resource types use the same addressing and management patterns described below.
+
+## Resource addresses
+
+Every Resource is uniquely identified by one or more **Addresses** in the form `/context/name`. 
+For example, an AI Agent named `Sigmond` in the public context is reachable at `/public/Sigmond`. 
+The context is either `public` or `private`, and the name defaults to the Resource's name. Addresses are mutable, and a single Resource can have multiple addresses, including phone numbers and SIP URIs.
+
+Learn more in the [Resource Addresses](/docs/platform/addresses) guide, including contexts, naming conventions, and routing options.
 
 ## Manage Resources
 
 ### With the REST API
 
-Use the Resources endpoints to manage your Resources programmatically.
+Use the Resources endpoints to work with any Resource programmatically, regardless of type. 
+The generic Resources endpoint lets you [list](/docs/apis/rest/resources/list-resources) all Resources,
+ [retrieve](/docs/apis/rest/resources/get-resource) or [delete](/docs/apis/rest/resources/delete-resource) a Resource by
+ID, and [list a Resource's addresses](/docs/apis/rest/addresses/list-resource-addresses-client).
 
-<Card title="Resources endpoints" href="/docs/apis/rest/resources/list-resources">
-  Control Resources using the SignalWire REST API.
-</Card>
+To **create** or **update** a Resource, use the endpoint for its specific type. 
+For example, if you wanted to create a new SWML Script you would utilize the [Create SWML Script](/docs/apis/rest/swml-scripts/create-swml-script) endpoint.
 
 ### In the Dashboard
 
-The Dashboard is your unified command center for your SignalWire Space. Access it at `{your-space-name}.signalwire.com`.
+The [SignalWire Dashboard](https://my.signalwire.com/resources) can also be used as your unified command center for your SignalWire Resources.
+You can create, manage, edit, delete, and test your Space's Resources all from your web browser.
 
 #### Create
 
-<Info title="No Resources tab?">
-If you don't see the **My Resources** tab, your SignalWire Space is on the **Legacy Dashboard**.
-Refer to the [Legacy](#in-the-legacy-dashboard) section of this guide for instructions for your Dashboard and information about the migration.
-</Info>
-
 <Steps>
   <Step title="Navigate to Resources">
     To create a Resource in your SignalWire Space, click on the **My Resources** tab in the left-hand navigation menu.
@@ -48,15 +83,8 @@ Refer to the [Legacy](#in-the-legacy-dashboard) section of this guide for instru
   </Step>
 </Steps>
 
-
-
-
-<Frame 
-
-  caption="Create a new Resource from the Dashboard">
-
+<Frame caption="Create a new Resource from the Dashboard">
   ![Create a new Resource from the Dashboard.](/assets/images/dashboard/home/home-resources-marked.webp)
-
 </Frame>
 
 Click the **Add** button to select from the grid of available Resource types.
@@ -67,9 +95,13 @@ Click the **Add** button to select from the grid of available Resource types.
 
 Alternatively, you can create new Resources from their subpages in the sidebar menu, or using the shortcuts on the Dashboard homepage.
 
-After selecting a Resource, 
-enter the details for the Resource on a new page,
-and select <kbd>Create</kbd> to confirm.
+After selecting a Resource, enter the details for the Resource on a new page, and select <kbd>Create</kbd> to confirm.
+
+<Info title="No Resources tab?">
+If you don't see the **My Resources** tab, your SignalWire Space is on the **Legacy Dashboard**,
+which does not support the Resources experience. [Contact Support](https://support.signalwire.com/)
+to upgrade your Space to the new UI.
+</Info>
 
 #### Modify or delete
 
@@ -80,12 +112,19 @@ Here, by selecting the `Edit` button, you can alter the specifics of the Resourc
   ![The list of Resources in a SignalWire Space.](/assets/images/dashboard/resources/resource-list.webp)
 </Frame>
 
----
-
-## In the Legacy Dashboard
-
-The **Resources experience** is not available in the Legacy Dashboard.
-
-To upgrade your Space to the New UI, [contact Support](https://support.signalwire.com/).
-
-<Markdown src="/snippets/common/dashboard/_ui-accordion.mdx" />
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Subscribers" href="/docs/platform/subscribers">
+    Manage the users in your communication system via subscribers.
+  </Card>
+  <Card title="Resource Addresses" href="/docs/platform/addresses">
+    Understand contexts, naming, and how Resources are identified and called.
+  </Card>
+  <Card title="Resources REST API" href="/docs/apis/rest/resources/list-resources">
+    List, retrieve, and delete Resources programmatically.
+  </Card>
+  <Card title="AI Agents" href="/docs/platform/ai">
+    Build conversational AI agents as Resources.
+  </Card>
+</CardGroup>

fern/products/platform/pages/platform/call-fabric/resources.mdx

@@ -191,7 +191,7 @@ Configure how the AI agent processes and understands spoken input, including spe
 </ParamField>
 
 
-<ParamField path="params.openai_asr_engine" type="string" default="gcloud_speech_v2_async" toc={true}>
+<ParamField path="params.openai_asr_engine" type="string" default="deepgram:nova-3" toc={true}>
   The ASR (Automatic Speech Recognition) engine to use. Common values include `deepgram:nova-2`, `deepgram:nova-3`, and other supported ASR engines.
 </ParamField>
 

fern/products/swml/pages/reference/methods/calling/ai/ai_params/index.mdx

@@ -13,6 +13,7 @@ import "./freeswitch-connectors";
 import "./cxml-applications";
 import "./relay-applications";
 import "./resources";
+import "./sip-addresses";
 import "./sip-endpoints";
 import "./sip_gateways";
 import "./subscribers";

specs/signalwire-rest/fabric-api/main.tsp

@@ -0,0 +1,15 @@
+enum SipAddressEncryption {
+  Required: "required",
+  Optional: "optional",
+  Forbidden: "forbidden",
+}
+
+enum SipAddressCodec {
+  OPUS: "OPUS",
+  G722: "G722",
+  PCMU: "PCMU",
+  PCMA: "PCMA",
+  G729: "G729",
+  VP8: "VP8",
+  H264: "H264",
+}

specs/signalwire-rest/fabric-api/sip-addresses/enums.tsp

@@ -0,0 +1,119 @@
+import "@typespec/http";
+import "@typespec/openapi";
+import "./models/core.tsp";
+import "./models/requests.tsp";
+import "./models/responses.tsp";
+import "./models/errors.tsp";
+import "../../types";
+import "../tags.tsp";
+import "../../../_shared/alias/token-permissions.tsp";
+
+using TypeSpec.Http;
+using TypeSpec.OpenAPI;
+using Types.StatusCodes;
+
+@route("/sip_addresses")
+namespace SignalWireAPI.Fabric.SipAddresses {
+  @tag(SIP_ADDRESSES_TAG)
+  @friendlyName("SIP Addresses")
+  @doc("""
+    SIP Addresses API category. A SIP address gives you a SIP URI that other SIP devices, PBXs, or
+    softphones can register to or dial — with its own username, codec, cipher, and encryption
+    settings, IP authentication, and a resource that answers the calls it receives. Use this API to
+    list, create, update, and delete SIP addresses without the dashboard.
+
+    This API only sees SIP addresses that belong to your project. An ID from another project, or an
+    ID that belongs to a different kind of address (for example, a video room), returns a 404.
+
+    <Note>
+    This is the public REST management API for standalone SIP addresses. It's separate from
+    [Assign domain application handler](/docs/apis/rest/domain-applications/assign-domain-application-handler),
+    which attaches an already-created Domain Application to a resource.
+    </Note>
+    """)
+  interface SipAddresses {
+    @operationId("list_sip_addresses")
+    @summary("List SIP addresses")
+    @doc("""
+      Returns a paginated list of SIP addresses in the authenticated project.
+
+      ${tokenPermissions<"_Calling_, _Fax_, _Messaging_, or _Video_">}
+      """)
+    list(...SipAddressListQuery):
+      | SipAddressListResponse
+      | StatusCode401
+      | StatusCode404
+      | SipAddressListStatusCode422
+      | StatusCode500;
+
+    @operationId("get_sip_address")
+    @summary("Get SIP address")
+    @doc("""
+      Returns a SIP address by ID.
+
+      ${tokenPermissions<"_Calling_, _Fax_, _Messaging_, or _Video_">}
+      """)
+    read(...SipAddressPathID):
+      | {
+          @statusCode statusCode: 200;
+          @body sip_address: SipAddress;
+        }
+      | StatusCode401
+      | StatusCode404
+      | StatusCode500;
+
+    @operationId("create_sip_address")
+    @summary("Create SIP address")
+    @doc("""
+      Creates a SIP address, along with its username, encryption, codec, cipher, and IP authentication settings.
+
+      ${tokenPermissions<"_Calling_, _Fax_, _Messaging_, or _Video_">}
+      """)
+    @post
+    create(@body request: SipAddressCreateRequest):
+      | {
+          @statusCode statusCode: 201;
+          @body sip_address: SipAddress;
+        }
+      | StatusCode401
+      | SipAddressCreateStatusCode422
+      | StatusCode500;
+
+    @operationId("update_sip_address")
+    @summary("Update SIP address")
+    @doc("""
+      Updates a SIP address by ID. Partial update: any field omitted from the body keeps its current value.
+      `calling_handler_resource_id` cannot be changed via this endpoint.
+
+      ${tokenPermissions<"_Calling_, _Fax_, _Messaging_, or _Video_">}
+      """)
+    @patch
+    update(...SipAddressPathID, @body request: SipAddressUpdateRequest):
+      | {
+          @statusCode statusCode: 200;
+          @body sip_address: SipAddress;
+        }
+      | StatusCode400
+      | StatusCode401
+      | StatusCode404
+      | SipAddressUpdateStatusCode422
+      | StatusCode500;
+
+    @operationId("delete_sip_address")
+    @summary("Delete SIP address")
+    @doc("""
+      Deletes a SIP address by ID, along with its SIP configuration. Calls and registrations to this
+      address will stop working immediately.
+
+      ${tokenPermissions<"_Calling_, _Fax_, _Messaging_, or _Video_">}
+      """)
+    @delete
+    delete(...SipAddressPathID):
+      | {
+          @statusCode statusCode: 204;
+        }
+      | StatusCode401
+      | StatusCode404
+      | StatusCode500;
+  }
+}