---
title: "Upsert Telephony Config"
method: PUT
path: "/integrations/telephony/config"
tags: ["integrations", "telephony"]
---

# Upsert Telephony Config

`PUT /integrations/telephony/config`

## Request

- Base URL: `https://dev.whispa.net` (the document declares no server; this is the origin it was published from)
- URL: `https://dev.whispa.net/integrations/telephony/config`
- Auth: one of:
  - OAuth 2
    - Password
    - Token URL: `auth/bearer/login`
  - API key in cookie `access_token`

## Request body

- TelephonyIntegrationConfig
  - `provider` string, required: Provider identifier, e.g. 'threecx' or 'awsconnect'
  - `enabled` boolean
  - `config` ThreeCXConfig, required
    - `host` string, required: 3CX host or URL
    - `client_id` string: OAuth2 client ID
    - `default_region` string: ISO country code used to interpret national customer numbers and format autonomous-agent dial destinations
    - `client_secret` string: OAuth2 client secret
    - `api_key` string, nullable: [Deprecated] Use client_secret
    - `monitored_extensions` string[]
    - `extension_user_map` object, nullable: Maps extension numbers to Whispa user IDs
    - `use_external_audio` boolean: Use external audio source (e.g. desktop app) instead of 3CX audio stream
    - `store_audio` boolean: Archive call audio to Whispa storage — copilot desktop audio (per-chunk PCM plus a final WAV per call) and the autonomous agent's full-call WAV alike. When off, audio only feeds live transcription and the telephony system's own recording is the recording of record.
    - `voice_agent` ThreeCXVoiceAgentConfig: Outbound autonomous-agent settings, nested under the 3CX provider config. The agent dials OUT over the same 3CX connection (host/client_id/secret) as the inbound copilot — only the outbound routing differs, so it lives here as a sub-section rather than a separate provider. A future telephony provider that supports the autonomous agent would carry its own equivalent sub-config. STT keys stay in env (ASSEMBLYAI_API_KEY or DEEPGRAM_API_KEY), as does the selected provider's API key; the TTS voice is per-scenario (voice_agent_config.voice_id, with legacy Cartesia ids still accepted).
      - `enabled` boolean: Whether the autonomous agent can place outbound calls
      - `agent_dn` string: Route Point DN the agent dials FROM (must be a Wroutepoint)
      - `agent_device_id` string: Device ID for makecall (blank → device-less)
      - `human_destination` string: Extension/queue to warm-transfer callers to (blank → transfer disabled)
      - `human_queue` string: Queue DN that takes outbound callers when the agent cannot continue (model failure, failed identity check); blank → the call closes
      - `dial_prefix` string: PBX access prefix prepended after converting customer numbers to the configured default region's national format

## Response `200`

Successful Response

- TelephonyIntegrationResponse
  - `provider` string, required: Provider identifier, e.g. 'threecx' or 'awsconnect'
  - `enabled` boolean
  - `config` ThreeCXConfig, required
    - `host` string, required: 3CX host or URL
    - `client_id` string: OAuth2 client ID
    - `default_region` string: ISO country code used to interpret national customer numbers and format autonomous-agent dial destinations
    - `client_secret` string: OAuth2 client secret
    - `api_key` string, nullable: [Deprecated] Use client_secret
    - `monitored_extensions` string[]
    - `extension_user_map` object, nullable: Maps extension numbers to Whispa user IDs
    - `use_external_audio` boolean: Use external audio source (e.g. desktop app) instead of 3CX audio stream
    - `store_audio` boolean: Archive call audio to Whispa storage — copilot desktop audio (per-chunk PCM plus a final WAV per call) and the autonomous agent's full-call WAV alike. When off, audio only feeds live transcription and the telephony system's own recording is the recording of record.
    - `voice_agent` ThreeCXVoiceAgentConfig: Outbound autonomous-agent settings, nested under the 3CX provider config. The agent dials OUT over the same 3CX connection (host/client_id/secret) as the inbound copilot — only the outbound routing differs, so it lives here as a sub-section rather than a separate provider. A future telephony provider that supports the autonomous agent would carry its own equivalent sub-config. STT keys stay in env (ASSEMBLYAI_API_KEY or DEEPGRAM_API_KEY), as does the selected provider's API key; the TTS voice is per-scenario (voice_agent_config.voice_id, with legacy Cartesia ids still accepted).
      - `enabled` boolean: Whether the autonomous agent can place outbound calls
      - `agent_dn` string: Route Point DN the agent dials FROM (must be a Wroutepoint)
      - `agent_device_id` string: Device ID for makecall (blank → device-less)
      - `human_destination` string: Extension/queue to warm-transfer callers to (blank → transfer disabled)
      - `human_queue` string: Queue DN that takes outbound callers when the agent cannot continue (model failure, failed identity check); blank → the call closes
      - `dial_prefix` string: PBX access prefix prepended after converting customer numbers to the configured default region's national format
  - `id` string, uuid, required

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/whispa/apis/whispa-api.md) - [All operations](https://skmtc.dev/whispa/apis/whispa-api/llms.txt) - [OpenAPI document](https://skmtc.dev/whispa/apis/whispa-api/revisions/12c2e4aca43c?raw)