> ## Documentation Index
> Fetch the complete documentation index at: https://docs.open.cx/llms.txt
> Use this file to discover all available pages before exploring further.

# Update an AI phone agent

> Update an existing AI phone agent. Use when managing AI phone agents and their voices, knowledge and workflows from code.



## OpenAPI

````yaml patch /phone/{phone_agent_id}
openapi: 3.1.0
info:
  title: OpenCX API
  description: >

    OpenCX is an AI-powered, all-in-one platform for customer support and
    outbound communications.


    Use this API to manage your OpenCX organization's AI agents, actions,
    conversations, contacts, and more.


    To get started, generate a new API key from the dashboard.


    ## Authentication

    All API endpoints require authentication using a Bearer token. You can
    generate an API key from your OpenCX dashboard.


    ## Rate Limiting

    API requests are rate limited to ensure fair usage. The current limits are:

    - 100 requests per minute for standard endpoints

    - 1000 requests per minute for streaming endpoints


    ## Error Handling

    The API uses standard HTTP status codes and returns detailed error messages
    in the response body.
  version: 1.0-beta
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
servers:
  - url: http://localhost:8080
    description: Development
  - url: https://api.open.cx
    description: Production
security:
  - bearerAuth: []
paths:
  /phone/{phone_agent_id}:
    patch:
      summary: Update an AI phone agent
      description: >-
        Update an existing AI phone agent. Only the fields you provide will be
        changed. Changes are saved to the agent’s draft and reach calls after
        POST /phone/{phone_agent_id}/publish; the response shows the draft.
        Agents on the older runtimes have no draft and save immediately. The SIP
        endpoints (inbound numbers, outbound trunk, transfer destinations)
        change the live agent immediately and copy the change into the draft.
      operationId: updatePhoneAgent
      parameters:
        - schema:
            type: string
          in: path
          name: phone_agent_id
          required: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdatePhoneAgentPublicDto'
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PhoneAgentDto'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDto'
components:
  schemas:
    UpdatePhoneAgentPublicDto:
      $schema: https://json-schema.org/draft/2020-12/schema
      $id: '#/components/schemas/UpdatePhoneAgentPublicDtoInput'
      type: object
      properties:
        name:
          type: string
          description: Agent display name
        type:
          description: >-
            Agent type: "inbound" (receives calls, default) or "outbound" (makes
            calls)
          type: string
          enum:
            - inbound
            - outbound
        voice_id:
          description: Voice ID from the /phone/voices endpoint. Omit for default voice.
          type:
            - string
            - 'null'
        tts_provider:
          description: >-
            Voice provider returned by the /phone/voices endpoint. It is
            inferred from voice_id when omitted.
          type: string
          enum:
            - elevenlabs
            - cartesia
            - hamsa
        language:
          description: >-
            ISO-639-1 language codes the agent should speak. Supported languages
            can be combined; Arabic accepts dialect tags such as "ar-SA".
          minItems: 1
          type: array
          items:
            type: string
        first_message:
          description: 'What the agent says when it picks up (default: "Hello?")'
          type:
            - string
            - 'null'
        instructions:
          anyOf:
            - type: array
              items:
                type: string
            - type: 'null'
          description: >-
            The call prompt as an array of instruction blocks. Joined in order
            into the system prompt at call time. Sending this on update replaces
            the whole array.
        actionIds:
          anyOf:
            - type: array
              items:
                type: string
            - type: 'null'
          description: >-
            HTTP actions the agent can call as tools during calls (action IDs
            from GET /actions). The full set is replaced on every write; send []
            to detach all, omit or send null to leave it unchanged. IDs must
            belong to your organization.
        transfer_destination_ids:
          description: >-
            Transfer destinations the agent may transfer calls to (IDs from GET
            /phone/transfer-destinations). The full set is replaced on every
            write; send [] to detach all. Destinations themselves are managed in
            the dashboard.
          type: array
          items:
            type: string
            format: uuid
            pattern: >-
              ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
        failover_transfer_destination_id:
          anyOf:
            - type: string
              format: uuid
              pattern: >-
                ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
            - type: 'null'
          description: >-
            Destination the call is transferred to if the voice pipeline fails
            mid-call. Any destination of your organization; null falls back to
            the first allowed destination, then to a graceful hangup.
        tts_speed_pct:
          anyOf:
            - type: integer
              minimum: 1
              maximum: 100
            - type: 'null'
          description: >-
            Speaking speed on a 1-100 scale (null = the voice default). Lower is
            slower; natural-sounding voices in some languages (e.g. Dutch) run
            best around 80-85. On voices whose id starts with "hamsa:" the same
            field sets expressiveness instead: the value divided by 50 (null or
            50 = 1, the default; 100 = 2, the most expressive). Omitted on
            create, it starts at the voice's default.
        stt_keyterms:
          anyOf:
            - type: array
              items:
                type: string
            - type: 'null'
          description: >-
            Custom vocabulary to boost in speech recognition: brand and product
            names, jargon, spellings the transcriber typically mishears. The
            agent name is merged in automatically.
        recording_enabled:
          description: 'Record calls handled by this agent (default: false).'
          type: boolean
        background_volume_pct:
          description: >-
            Background sound volume, as a percentage of the default level
            (1–200, 100 = default).
          type: integer
          minimum: 1
          maximum: 200
        typing_sound_enabled:
          description: >-
            Play a soft typing sound while the agent runs an action (default:
            true).
          type: boolean
    PhoneAgentDto:
      $schema: https://json-schema.org/draft/2020-12/schema
      $id: '#/components/schemas/PhoneAgentDto'
      type: object
      properties:
        id:
          type: string
        org_id:
          type: string
        phone_number:
          type:
            - string
            - 'null'
        outbound_caller_number:
          type:
            - string
            - 'null'
        name:
          type:
            - string
            - 'null'
        type:
          type: string
          enum:
            - inbound
            - outbound
        language:
          type: array
          items:
            type: string
        accent:
          type:
            - string
            - 'null'
        handoff_phone_number:
          type:
            - string
            - 'null'
        speed:
          type:
            - number
            - 'null'
        interruptible:
          type: boolean
        actionIds:
          anyOf:
            - type: array
              items:
                type: string
            - type: 'null'
        instructions:
          anyOf:
            - type: array
              items:
                type: string
            - type: 'null'
        data_collection_fields:
          anyOf:
            - type: array
              items:
                type: string
            - type: 'null'
        data_collection_webhook_url:
          type:
            - string
            - 'null'
        model:
          type: string
          enum:
            - oppie-vox
            - oppie-vox-turbo
            - oppie-vox-livekit
        voice_id:
          type:
            - string
            - 'null'
        voice_mode:
          type: string
          enum:
            - modular
            - live
        first_message:
          type:
            - string
            - 'null'
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        provider_external_id:
          type:
            - string
            - 'null'
        flow:
          anyOf:
            - {}
            - type: 'null'
        use_org_knowledgebase:
          type: boolean
        background_noise_preset:
          anyOf:
            - type: string
              enum:
                - office
                - bar
                - city-street
            - type: 'null'
        background_volume_pct:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
          description: >-
            Background sound volume, as a percentage of the default level
            (1–200, 100 = default).
        typing_sound_enabled:
          type: boolean
          description: Whether a soft typing sound plays while the agent runs an action.
        recording_enabled:
          type: boolean
        search_enabled:
          type: boolean
          description: >-
            Whether the agent searches its selected knowledge during calls. Set
            on save: on only when the selection is too large to load at the
            start of each call.
        stt_keyterms:
          type: array
          items:
            type: string
        stt_model:
          anyOf:
            - type: string
              enum:
                - deepgram/flux-general
                - deepgram/nova-3
                - deepgram/nova-3-medical
                - cartesia/ink-whisper
                - elevenlabs/scribe_v2_realtime
                - xai/stt-1
                - assemblyai/universal-3-5-pro
                - speechmatics/enhanced
                - google/gemini-3.5-transcribe-live
                - soniox/stt-rt-v6
                - openai/gpt-live-transcribe
            - type: 'null'
        tts_speed_pct:
          anyOf:
            - type: integer
              minimum: -9007199254740991
              maximum: 9007199254740991
            - type: 'null'
        tts_provider:
          type: string
          enum:
            - elevenlabs
            - cartesia
            - hamsa
        failover_transfer_destination_id:
          anyOf:
            - type: string
              format: uuid
              pattern: >-
                ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
            - type: 'null'
        transfer_destination_ids:
          type: array
          items:
            type: string
            format: uuid
            pattern: >-
              ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
          description: >-
            Transfer destinations the agent may transfer to (`transfer_call`
            targets).
        published:
          type: boolean
          description: >-
            False until the agent is published for the first time. An
            unpublished agent takes no calls; its settings here are its draft.
        has_unpublished_changes:
          type: boolean
          description: Whether the draft holds changes that are not live yet.
      required:
        - id
        - org_id
        - phone_number
        - outbound_caller_number
        - name
        - type
        - language
        - accent
        - handoff_phone_number
        - speed
        - interruptible
        - actionIds
        - instructions
        - data_collection_fields
        - data_collection_webhook_url
        - model
        - voice_id
        - voice_mode
        - first_message
        - created_at
        - updated_at
        - provider_external_id
        - use_org_knowledgebase
        - background_noise_preset
        - background_volume_pct
        - typing_sound_enabled
        - recording_enabled
        - search_enabled
        - stt_keyterms
        - stt_model
        - tts_speed_pct
        - tts_provider
        - failover_transfer_destination_id
        - transfer_destination_ids
        - published
        - has_unpublished_changes
      additionalProperties: false
    ErrorDto:
      type: object
      properties:
        statusCode:
          type: integer
        message:
          type: string
        error:
          type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.