chore: update documentation for telephony

docs/integrations/telephony/cloudonix.mdx

@@ -16,7 +16,7 @@ Before setting up Cloudonix integration, you'll need:
 - A [Cloudonix account](https://cockpit.cloudonix.io/onboarding?affiliate=DOGRAH)
 - A Cloudonix domain UUID (or the domain name)
 - A Cloudonix domain API Key (Bearer Token)
-- A Cloudonix **Voice Application** on that domain — Dograh will manage its `url`
+- A Cloudonix **Voice Application** on that domain (optional — leave the field blank in Dograh and we'll auto-create one for you on save, with the application `url` pre-set)
 - A Cloudonix outbound voice trunk service provider connection
 - Dograh AI instance running and accessible
 
@@ -38,8 +38,7 @@ Watch this step-by-step guide to set up Cloudonix with Dograh AI:
 
 1. Log in to your [Cloudonix Console](https://cockpit.cloudonix.io/onboarding?affiliate=DOGRAH)
 2. Find your **Domain ID** (UUID or domain name) and **Bearer Token** (Domain API Key) on the dashboard
-3. Navigate to your domain's **Applications** and create (or open) the application you'll use with Dograh
+3. (Optional) Navigate to your domain's **Applications** and create (or open) the application you'll use with Dograh, then copy its **Application Name**. Skip this if you want Dograh to auto-create the Voice Application for you on save.
-4. Copy the **Application Name** — Dograh will manage this application's `url`
 
 ### Step 2: Configure in Dograh AI
 
@@ -49,10 +48,18 @@ Watch this step-by-step guide to set up Cloudonix with Dograh AI:
 4. Enter your credentials:
    - Bearer Token
    - Domain ID
-   - Application Name
+   - Application Name — *optional*. Leave blank and Dograh will auto-create a Voice Application on save (with the application `url` and CXML runtime already configured) and store its name on this configuration.
 5. Click **Save Configuration**
 6. Open the configuration you just created and add at least one **phone number** (with country code in E.164 format, e.g. `+1234567890`). The default caller ID is used for outbound calls.
 
+   <Note>
+     If Dograh auto-created the Voice Application for you, you still need to
+     bind your DNIDs to that application in the Cloudonix cockpit (see
+     [Step 2 of Inbound Calling Setup](#step-2-create-the-voice-application-and-link-dnids)).
+     The auto-created application is named `dograh-<random>` — its name is
+     shown on the saved configuration.
+   </Note>
+
 ### Step 3: Test Your Configuration
 
 1. Create a test workflow
@@ -61,7 +68,7 @@ Watch this step-by-step guide to set up Cloudonix with Dograh AI:
 
 ## Inbound Calling Setup
 
-Cloudonix routes inbound calls per **Voice Application** — the webhook URL is set once on the application, and applies to every DNID bound to it. **When you save an inbound workflow on a phone number, Dograh automatically pushes the webhook URL to your Voice Application's `url`** (provided the credentials are correct), so you don't need to set the webhook by hand.
+Cloudonix routes inbound calls per **Voice Application** — the webhook URL is set once on the application, and applies to every DNID bound to it. **When you save an inbound workflow on a phone number, Dograh automatically pushes the webhook URL to your Voice Application's `url`** (provided the credentials are correct), so you don't need to set the webhook by hand. If Dograh auto-created the application during configuration save, the `url` is already set and this push is a no-op — you only need to bind your DNIDs to the auto-created application.
 
 ### Step 1: Set Up the Inbound Trunk
 

docs/integrations/telephony/plivo.mdx

@@ -13,7 +13,7 @@ Before setting up Plivo integration, you'll need:
 
 - A [Plivo account](https://www.plivo.com/)
 - Auth ID and Auth Token from your Plivo Console
-- A Plivo **Application** with Voice capability (used for inbound webhook routing)
+- A Plivo **Application** with Voice capability (optional — leave the field blank in Dograh and we'll auto-create one for you on save, with the `answer_url` pre-set)
 - At least one Plivo phone number
 - Dograh AI instance running and accessible
 
@@ -23,9 +23,8 @@ Before setting up Plivo integration, you'll need:
 
 1. Log in to your [Plivo Console](https://console.plivo.com/)
 2. Find your **Auth ID** and **Auth Token** on the dashboard
-3. Navigate to **Voice** → **Applications** and create (or open) the application you'll use with Dograh
+3. (Optional) Navigate to **Voice** → **Applications** and create (or open) the application you'll use with Dograh, then copy its **Application ID** (a UUID). Skip this if you want Dograh to auto-create the application for you on save.
-4. Copy the **Application ID** (a UUID) — you'll attach numbers to this app and Dograh will manage its `answer_url`
+4. Navigate to **Phone Numbers** → **Your Numbers** and copy the numbers you plan to use
-5. Navigate to **Phone Numbers** → **Your Numbers** and copy the numbers you plan to use
 
 ### Step 2: Configure in Dograh AI
 
@@ -34,10 +33,18 @@ Before setting up Plivo integration, you'll need:
 3. Enter your credentials:
    - Auth ID
    - Auth Token
-   - Application ID
+   - Application ID — *optional*. Leave blank and Dograh will auto-create a Plivo Application on save (with the `answer_url` already configured) and store its Application ID on this configuration.
 4. Click **Save Configuration**
 5. Open the configuration you just created and add at least one **phone number** (with country code in E.164 format, e.g. `+1234567890`). The default caller ID is used for outbound calls.
 
+   <Note>
+     If Dograh auto-created the Plivo Application for you, you still need to
+     link your Plivo numbers to that application in the Plivo Console under
+     **Phone Numbers** → **Your Numbers**. The auto-created application is
+     named `dograh-<random>` — its Application ID is shown on the saved
+     configuration.
+   </Note>
+
 ### Step 3: Test Your Configuration
 
 1. Create a test workflow
@@ -46,7 +53,7 @@ Before setting up Plivo integration, you'll need:
 
 ## Inbound Calling Setup
 
-Plivo numbers don't carry an `answer_url` directly — the URL lives on a Plivo **Application**, and each number is linked to one application. **When you save an inbound workflow on a phone number, Dograh automatically pushes the webhook URL to your Plivo Application's `answer_url`** (provided the credentials are correct). You don't need to set the webhook by hand.
+Plivo numbers don't carry an `answer_url` directly — the URL lives on a Plivo **Application**, and each number is linked to one application. **When you save an inbound workflow on a phone number, Dograh automatically pushes the webhook URL to your Plivo Application's `answer_url`** (provided the credentials are correct). You don't need to set the webhook by hand. If Dograh auto-created the application during configuration save, the `answer_url` is already set and this push is a no-op.
 
 ### Step 1: Link the Phone Number to Your Plivo Application
 

docs/integrations/telephony/telnyx.mdx

@@ -13,7 +13,7 @@ Before setting up Telnyx integration, you'll need:
 
 - A [Telnyx account](https://telnyx.com/)
 - An **API Key** from the Telnyx Mission Control Portal
-- A **Call Control Application** (its `connection_id` is what Dograh stores)
+- A **Call Control Application** (optional — leave the field blank in Dograh and we'll auto-create one for you on save, with the inbound webhook URL pre-set)
 - At least one Telnyx phone number assigned to that Call Control Application
 - Dograh AI instance running and accessible
 
@@ -23,9 +23,8 @@ Before setting up Telnyx integration, you'll need:
 
 1. Log in to the [Telnyx Mission Control Portal](https://portal.telnyx.com/)
 2. Navigate to **API Keys** and create (or copy) an API Key
-3. Navigate to **Call Control** → **Applications** and create (or open) the application you'll use with Dograh
+3. (Optional) Navigate to **Call Control** → **Applications** and create (or open) the application you'll use with Dograh, then copy its **Connection ID** (Call Control App ID). Skip this if you want Dograh to auto-create the Call Control Application for you on save.
-4. Copy the application's **Connection ID** (Call Control App ID)
+4. Navigate to **Numbers** → **My Numbers** and assign your phone numbers to the Call Control Application you'll use with Dograh (if you're letting Dograh auto-create the application, do this after saving the configuration in Step 2)
-5. Navigate to **Numbers** → **My Numbers** and assign your phone numbers to that Call Control Application
 
 ### Step 2: Configure in Dograh AI
 
@@ -33,10 +32,18 @@ Before setting up Telnyx integration, you'll need:
 2. Select **Telnyx** as your provider
 3. Enter your credentials:
    - API Key
-   - Call Control App ID (Connection ID)
+   - Call Control App ID (Connection ID) — *optional*. Leave blank and Dograh will auto-create a Call Control Application on save (with the inbound webhook URL already configured) and store its Connection ID on this configuration.
 4. Click **Save Configuration**
 5. Open the configuration you just created and add at least one **phone number** (with country code in E.164 format, e.g. `+1234567890`). The default caller ID is used for outbound calls.
 
+   <Note>
+     If Dograh auto-created the Call Control Application for you, you still
+     need to assign your Telnyx numbers to that application in the Telnyx
+     Portal under **Numbers** → **My Numbers**. The auto-created application
+     is named `dograh-<random>` — its Connection ID is shown on the saved
+     configuration.
+   </Note>
+
 ### Step 3: Test Your Configuration
 
 1. Create a test workflow
@@ -45,7 +52,7 @@ Before setting up Telnyx integration, you'll need:
 
 ## Inbound Calling Setup
 
-Telnyx delivers inbound webhooks at the **Call Control Application** level — the webhook URL is configured once on the application, and applies to every number assigned to it. **When you save an inbound workflow on a phone number, Dograh automatically pushes the webhook URL to your Call Control Application's `webhook_event_url`** (provided the credentials are correct).
+Telnyx delivers inbound webhooks at the **Call Control Application** level — the webhook URL is configured once on the application, and applies to every number assigned to it. **When you save an inbound workflow on a phone number, Dograh automatically pushes the webhook URL to your Call Control Application's `webhook_event_url`** (provided the credentials are correct). If Dograh auto-created the application during configuration save, the webhook URL is already set and this step is a no-op.
 
 ### Step 1: Assign an Inbound Workflow to the Phone Number
 

docs/integrations/telephony/vobiz.mdx

@@ -13,7 +13,7 @@ Before setting up Vobiz integration, you'll need:
 
 - A [Vobiz account](https://vobiz.com)
 - Auth ID and Auth Token from your Vobiz dashboard
-- A Vobiz **Application** (used for inbound webhook routing)
+- A Vobiz **Application** (optional — leave the field blank in Dograh and we'll auto-create one for you on save, with the `answer_url` pre-set)
 - At least one Vobiz phone number
 - Dograh AI instance running and accessible
 
@@ -23,9 +23,8 @@ Before setting up Vobiz integration, you'll need:
 
 1. Log in to your Vobiz dashboard
 2. Find your **Auth ID** and generate an **Auth Token** for API access
-3. Navigate to the **Applications** section and create (or open) the application you'll use with Dograh
+3. (Optional) Navigate to the **Applications** section and create (or open) the application you'll use with Dograh, then copy its **Application ID**. Skip this if you want Dograh to auto-create the application for you on save.
-4. Copy the **Application ID** — Dograh will manage its `answer_url`
+4. Navigate to **Phone Numbers** and copy the numbers you plan to use
-5. Navigate to **Phone Numbers** and copy the numbers you plan to use
 
 ### Step 2: Configure in Dograh AI
 
@@ -34,10 +33,18 @@ Before setting up Vobiz integration, you'll need:
 3. Enter your credentials:
    - Auth ID
    - Auth Token
-   - Application ID
+   - Application ID — *optional*. Leave blank and Dograh will auto-create a Vobiz Application on save (with the `answer_url` already configured) and store its Application ID on this configuration.
 4. Click **Save Configuration**
 5. Open the configuration you just created and add at least one **phone number** (with country code in E.164 format, e.g. `+1234567890`). The default caller ID is used for outbound calls.
 
+   <Note>
+     If Dograh auto-created the Vobiz Application for you, you still need to
+     attach your Vobiz numbers to that application in the Vobiz Console under
+     **Applications**. The auto-created application is named
+     `dograh-<random>` — its Application ID is shown on the saved
+     configuration.
+   </Note>
+
 ### Step 3: Test Your Configuration
 
 1. Create a test workflow
@@ -46,7 +53,7 @@ Before setting up Vobiz integration, you'll need:
 
 ## Inbound Calling Setup
 
-Vobiz numbers don't carry an `answer_url` directly — the URL lives on a Vobiz **Application**, and each number is linked to one application. **When you save an inbound workflow on a phone number, Dograh automatically pushes the webhook URL to your Vobiz Application's `answer_url`** (provided the credentials are correct).
+Vobiz numbers don't carry an `answer_url` directly — the URL lives on a Vobiz **Application**, and each number is linked to one application. **When you save an inbound workflow on a phone number, Dograh automatically pushes the webhook URL to your Vobiz Application's `answer_url`** (provided the credentials are correct). If Dograh auto-created the application during configuration save, the `answer_url` is already set and this push is a no-op.
 
 ### Step 1: Link the Phone Number to Your Vobiz Application
 

scripts/dump_docs_openapi.py

@@ -0,0 +1,39 @@
+"""Dump the FastAPI OpenAPI spec to docs/api-reference/openapi.json.
+
+Run from the repo root with the api environment available:
+
+    python -m scripts.dump_docs_openapi
+
+CI uses this to detect drift: it dumps the spec and asserts the file is
+unchanged versus what's checked in.
+"""
+
+import json
+from pathlib import Path
+
+from loguru import logger
+
+logger.remove()
+
+from fastapi.openapi.utils import get_openapi  # noqa: E402
+
+from api.app import app  # noqa: E402
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+OUTPUT = REPO_ROOT / "docs" / "api-reference" / "openapi.json"
+
+
+def main() -> None:
+    spec = get_openapi(
+        title=app.title,
+        version=app.version,
+        description=app.description,
+        routes=app.routes,
+        servers=app.servers,
+    )
+    OUTPUT.write_text(json.dumps(spec, separators=(",", ":")))
+    print(f"Wrote {len(spec['paths'])} paths to {OUTPUT.relative_to(REPO_ROOT)}")
+
+
+if __name__ == "__main__":
+    main()

scripts/generate_sdk.sh

@@ -6,6 +6,8 @@
 #   3. Pydantic request/response models + TS interfaces (datamodel-codegen
 #      / openapi-typescript)
 #   4. Client method mixins (_generated_client.py / _generated_client.ts)
+#   5. Full OpenAPI spec for the Mintlify docs site
+#      (docs/api-reference/openapi.json)
 #
 # Run from anywhere — the script resolves the repo root relative to itself.
 # Requires:
@@ -106,4 +108,9 @@ python -m sdk.codegen.client_codegen \
     --py-out "sdk/python/src/dograh_sdk/_generated_client.py" \
     --ts-out "sdk/typescript/src/_generated_client.ts"
 
+# ── 5. Docs OpenAPI spec ─────────────────────────────────────────────
+
+echo "→ Dumping full OpenAPI spec for docs site..."
+python -m scripts.dump_docs_openapi
+
 echo "✓ SDK regenerated."

sdk/python/src/dograh_sdk/_generated_models.py

@@ -1,6 +1,6 @@
 # generated by datamodel-codegen:
-#   filename:  dograh-openapi-XXXXXX.json.W6Dd8pliVH
+#   filename:  dograh-openapi-XXXXXX.json.b1W2sNrReS
-#   timestamp: 2026-04-25T11:15:04+00:00
+#   timestamp: 2026-05-02T11:27:23+00:00
 
 from __future__ import annotations
 
@@ -108,6 +108,9 @@ class InitiateCallRequest(BaseModel):
     workflow_id: Annotated[int, Field(title='Workflow Id')]
     workflow_run_id: Annotated[int | None, Field(title='Workflow Run Id')] = None
     phone_number: Annotated[str | None, Field(title='Phone Number')] = None
+    telephony_configuration_id: Annotated[
+        int | None, Field(title='Telephony Configuration Id')
+    ] = None
 
 
 class NodeCategory(Enum):
@@ -260,6 +263,7 @@ class WorkflowResponse(BaseModel):
     ] = None
     version_number: Annotated[int | None, Field(title='Version Number')] = None
     version_status: Annotated[str | None, Field(title='Version Status')] = None
+    workflow_uuid: Annotated[str | None, Field(title='Workflow Uuid')] = None
 
 
 class DocumentListResponseSchema(BaseModel):

sdk/typescript/src/_generated_models.ts

@@ -430,6 +430,8 @@ export interface components {
             workflow_run_id?: number | null;
             /** Phone Number */
             phone_number?: string | null;
+            /** Telephony Configuration Id */
+            telephony_configuration_id?: number | null;
         };
         /**
          * NodeCategory
@@ -738,6 +740,8 @@ export interface components {
             version_number?: number | null;
             /** Version Status */
             version_status?: string | null;
+            /** Workflow Uuid */
+            workflow_uuid?: string | null;
         };
     };
     responses: never;