chore: add telephony configuration docs

docs/api-reference/campaigns/create.mdx

@@ -6,6 +6,8 @@ openapi: "POST /api/v1/campaign/create"
 
 Before creating a campaign, [upload your contacts CSV](/api-reference/campaigns/upload-contacts) to get a `source_url`.
 
+Set `telephony_configuration_id` to pin the campaign to a specific [telephony configuration](/api-reference/telephony-configs). If omitted, Dograh falls back to the organization's [default outbound configuration](/api-reference/telephony-configs/set-default-outbound) — supplying an id that doesn't exist in your organization returns `400 telephony_configuration_not_found`.
+
 The `time_slots` field controls when Dograh is allowed to place calls. If omitted, calls can be placed at any time. The `timezone` field applies to all time slot windows.
 
 ```json

docs/api-reference/telephony-configs.mdx

@@ -0,0 +1,35 @@
+---
+title: "Overview"
+description: "Configure telephony providers and manage phone numbers"
+---
+
+A **telephony configuration** binds an organization to a telephony provider (Twilio, Vonage, Plivo, Telnyx, etc.) along with the credentials needed to place and receive calls. Each configuration owns a set of phone numbers; campaigns and inbound routing pin to a specific configuration.
+
+One configuration in your organization can be marked as the **default outbound** — campaigns and ad-hoc calls that omit `telephony_configuration_id` fall back to it.
+
+| Method | Endpoint | Quick Link |
+|---|---|---|
+| `GET` | `/organizations/telephony-providers/metadata` | [List supported providers](/api-reference/telephony-configs/providers) |
+| `GET` | `/organizations/telephony-configs` | [List configurations](/api-reference/telephony-configs/list) |
+| `POST` | `/organizations/telephony-configs` | [Create a configuration](/api-reference/telephony-configs/create) |
+| `GET` | `/organizations/telephony-configs/{config_id}` | [Get a configuration](/api-reference/telephony-configs/get) |
+| `PUT` | `/organizations/telephony-configs/{config_id}` | [Update a configuration](/api-reference/telephony-configs/update) |
+| `DELETE` | `/organizations/telephony-configs/{config_id}` | [Delete a configuration](/api-reference/telephony-configs/delete) |
+| `POST` | `/organizations/telephony-configs/{config_id}/set-default-outbound` | [Set as default outbound](/api-reference/telephony-configs/set-default-outbound) |
+
+## Phone numbers
+
+Phone numbers are nested under a configuration:
+
+| Method | Endpoint | Quick Link |
+|---|---|---|
+| `GET` | `/organizations/telephony-configs/{config_id}/phone-numbers` | [List phone numbers](/api-reference/telephony-configs/phone-numbers/list) |
+| `POST` | `/organizations/telephony-configs/{config_id}/phone-numbers` | [Add a phone number](/api-reference/telephony-configs/phone-numbers/create) |
+| `GET` | `/organizations/telephony-configs/{config_id}/phone-numbers/{phone_number_id}` | [Get a phone number](/api-reference/telephony-configs/phone-numbers/get) |
+| `PUT` | `/organizations/telephony-configs/{config_id}/phone-numbers/{phone_number_id}` | [Update a phone number](/api-reference/telephony-configs/phone-numbers/update) |
+| `DELETE` | `/organizations/telephony-configs/{config_id}/phone-numbers/{phone_number_id}` | [Delete a phone number](/api-reference/telephony-configs/phone-numbers/delete) |
+| `POST` | `/organizations/telephony-configs/{config_id}/phone-numbers/{phone_number_id}/set-default-caller` | [Set as default caller](/api-reference/telephony-configs/phone-numbers/set-default-caller) |
+
+## Sensitive credentials
+
+Provider credentials (API keys, auth tokens, etc.) are masked in `GET` responses. When updating a configuration, you can re-submit the masked value as-is — Dograh detects the mask and preserves the original secret.

docs/api-reference/telephony-configs/create.mdx

@@ -0,0 +1,9 @@
+---
+title: "Create Configuration"
+description: "Create a new telephony configuration"
+openapi: "POST /api/v1/organizations/telephony-configs"
+---
+
+Call [List Supported Providers](/api-reference/telephony-configs/providers) first to discover the credential fields for the provider you want to configure — they vary per provider.
+
+Configuration `name` must be unique within your organization. Set `is_default_outbound: true` to mark this configuration as the org-wide default for outbound calls (any existing default is unset). New configurations have no phone numbers; add them via [Add a phone number](/api-reference/telephony-configs/phone-numbers/create).

docs/api-reference/telephony-configs/delete.mdx

@@ -0,0 +1,7 @@
+---
+title: "Delete Configuration"
+description: "Delete a telephony configuration"
+openapi: "DELETE /api/v1/organizations/telephony-configs/{config_id}"
+---
+
+Returns `409 Conflict` if the configuration is referenced by any campaign or phone number. Detach those resources first, then retry.

docs/api-reference/telephony-configs/get.mdx

@@ -0,0 +1,7 @@
+---
+title: "Get Configuration"
+description: "Retrieve a telephony configuration by id"
+openapi: "GET /api/v1/organizations/telephony-configs/{config_id}"
+---
+
+Sensitive credential fields (API keys, auth tokens) are returned in masked form.

docs/api-reference/telephony-configs/list.mdx

@@ -0,0 +1,5 @@
+---
+title: "List Configurations"
+description: "List all telephony configurations in your organization"
+openapi: "GET /api/v1/organizations/telephony-configs"
+---

docs/api-reference/telephony-configs/phone-numbers/create.mdx

@@ -0,0 +1,9 @@
+---
+title: "Add Phone Number"
+description: "Attach a new phone number to a telephony configuration"
+openapi: "POST /api/v1/organizations/telephony-configs/{config_id}/phone-numbers"
+---
+
+Set `inbound_workflow_id` to bind incoming calls on this number to a specific agent — Dograh will register the inbound webhook with the provider and the response will include a `provider_sync` block reporting the result. Omit it to add the number for outbound use only.
+
+The `(provider, account_id, address)` tuple must be globally unique across all Dograh organizations, since inbound dispatch keys on it. Attempting to add a number that another organization already owns returns `409`.

docs/api-reference/telephony-configs/phone-numbers/delete.mdx

@@ -0,0 +1,5 @@
+---
+title: "Delete Phone Number"
+description: "Remove a phone number from a telephony configuration"
+openapi: "DELETE /api/v1/organizations/telephony-configs/{config_id}/phone-numbers/{phone_number_id}"
+---

docs/api-reference/telephony-configs/phone-numbers/get.mdx

@@ -0,0 +1,5 @@
+---
+title: "Get Phone Number"
+description: "Retrieve a phone number by id"
+openapi: "GET /api/v1/organizations/telephony-configs/{config_id}/phone-numbers/{phone_number_id}"
+---

docs/api-reference/telephony-configs/phone-numbers/list.mdx

@@ -0,0 +1,5 @@
+---
+title: "List Phone Numbers"
+description: "List phone numbers attached to a telephony configuration"
+openapi: "GET /api/v1/organizations/telephony-configs/{config_id}/phone-numbers"
+---

docs/api-reference/telephony-configs/phone-numbers/set-default-caller.mdx

@@ -0,0 +1,7 @@
+---
+title: "Set Default Caller"
+description: "Designate a phone number as the configuration's default outbound caller id"
+openapi: "POST /api/v1/organizations/telephony-configs/{config_id}/phone-numbers/{phone_number_id}/set-default-caller"
+---
+
+Outbound calls placed through this configuration that don't specify a `from_number` use the default caller. Setting a new default automatically clears the previous one — at most one phone number per configuration can be the default caller.

docs/api-reference/telephony-configs/phone-numbers/update.mdx

@@ -0,0 +1,9 @@
+---
+title: "Update Phone Number"
+description: "Update label, inbound binding, or activation state of a phone number"
+openapi: "PUT /api/v1/organizations/telephony-configs/{config_id}/phone-numbers/{phone_number_id}"
+---
+
+Changing `inbound_workflow_id` re-syncs the inbound webhook with the provider; the response includes a `provider_sync` block with the result.
+
+To remove an existing inbound binding, send `clear_inbound_workflow: true`. Sending `inbound_workflow_id: null` alone is treated as "no change".

docs/api-reference/telephony-configs/providers.mdx

@@ -0,0 +1,7 @@
+---
+title: "List Supported Providers"
+description: "Discover available telephony providers and the credential fields each one requires"
+openapi: "GET /api/v1/organizations/telephony-providers/metadata"
+---
+
+Use this endpoint to discover which telephony providers Dograh supports and the exact credential fields each one expects. The response drives the configuration form in the dashboard, and is the recommended way to build a provider-agnostic integration.

docs/api-reference/telephony-configs/set-default-outbound.mdx

@@ -0,0 +1,7 @@
+---
+title: "Set Default Outbound"
+description: "Designate this configuration as the org-wide default for outbound calls"
+openapi: "POST /api/v1/organizations/telephony-configs/{config_id}/set-default-outbound"
+---
+
+Campaigns and ad-hoc calls that omit `telephony_configuration_id` use the default outbound configuration. Setting a new default automatically clears the previous one — at most one configuration can be the default at a time.

docs/api-reference/telephony-configs/update.mdx

@@ -0,0 +1,9 @@
+---
+title: "Update Configuration"
+description: "Rename a configuration or rotate its credentials"
+openapi: "PUT /api/v1/organizations/telephony-configs/{config_id}"
+---
+
+The `provider` cannot be changed once a configuration exists — create a new configuration if you need to switch providers.
+
+When rotating credentials, you only need to send the fields you're changing. Re-submitting a masked sensitive value preserves the original secret, so it's safe to round-trip a `GET` response back to a `PUT`.