> ## Documentation Index > Fetch the complete documentation index at: https://docs.polymorfa.com/llms.txt > Use this file to discover all available pages before exploring further. # Update call settings > **Required scope:** `sessions:manage` Changes the settings you send; omitted settings keep their current values. Send `expectedRevision` to refuse the update when someone else changed the settings after you read them. ## OpenAPI ````yaml api-reference/features/communicate.json PUT /platform/sessions/{session}/call-settings openapi: 3.0.3 info: title: Communicate API methods version: 1.0.0 description: >- Task-focused communicate methods across supported Polymorfa connection types. servers: [] security: [] paths: /platform/sessions/{session}/call-settings: put: tags: - Calls summary: Update call settings description: >- **Required scope:** `sessions:manage` Changes the settings you send; omitted settings keep their current values. Send `expectedRevision` to refuse the update when someone else changed the settings after you read them. operationId: managementUpdateCallSettings parameters: - schema: type: string minLength: 1 maxLength: 128 required: true name: session in: path description: |- Identifier of the connected Polymorfa session. **Value constraints** | Constraint | Accepted input | | --- | --- | | String length | `1` through `128` characters | requestBody: required: true content: application/json: schema: $ref: >- #/components/schemas/management__PlatformAccessUpdateCallSettingsRequest responses: '200': description: >- Call settings saved. Audio settings apply to a call the next time a participant answers or connects to it, including calls in progress. Routing settings apply to calls that arrive after the change. content: application/json: schema: $ref: >- #/components/schemas/management__PlatformAccessUpdateCallSettingsResponse '400': description: Bad request — request body or params failed validation content: application/json: schema: $ref: '#/components/schemas/management__PlatformAccessPublicError' example: error: type: invalid_request_error code: invalid_parameter message: Correct the invalid request field. param: null request_id: 5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30 data: null docs: https://docs.polymorfa.com/api/errors#invalid-parameter '401': description: Missing or invalid authentication token content: application/json: schema: $ref: '#/components/schemas/management__PlatformAccessPublicError' example: error: type: authentication_error code: invalid_credential message: Supply a valid credential. param: null request_id: 5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30 data: null docs: https://docs.polymorfa.com/api/errors#invalid-credential '403': description: Authenticated but not permitted (missing scope or rule violation) content: application/json: schema: $ref: '#/components/schemas/management__PlatformAccessPublicError' example: error: type: permission_error code: permission_denied message: The credential does not have access to this resource. param: null request_id: 5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30 data: null docs: https://docs.polymorfa.com/api/errors#permission-denied '404': description: Resource not found content: application/json: schema: $ref: '#/components/schemas/management__PlatformAccessPublicError' example: error: type: invalid_request_error code: resource_not_found message: The resource is unavailable to this caller. param: null request_id: 5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30 data: null docs: https://docs.polymorfa.com/api/errors#resource-not-found '409': description: '`state_conflict`: the settings changed after `expectedRevision`.' content: application/json: schema: $ref: '#/components/schemas/management__PlatformAccessPublicError' example: error: type: conflict_error code: state_conflict message: The request conflicts with the resource state. param: null request_id: 5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30 data: null docs: https://docs.polymorfa.com/api/errors#state-conflict '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/management__PlatformAccessPublicError' example: error: type: api_error code: internal_error message: >- An unexpected service failure occurred. Keep the request ID for support. param: null request_id: 5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30 data: null docs: https://docs.polymorfa.com/api/errors#internal-error security: - management__ApiKeyAuth: [] servers: - url: https://api.polymorfa.com components: schemas: management__PlatformAccessUpdateCallSettingsRequest: type: object properties: callsEnabled: type: boolean description: >- Set to false to refuse new and incoming calls on the session; true allows them again. conferenceMode: type: boolean description: >- Set to true so that the participants you connect to a call hear each other as well as the WhatsApp party, or false so that each hears only the WhatsApp party. inboundRoute: allOf: - $ref: '#/components/schemas/management__PlatformAccessCallInboundRoute' - description: Where incoming WhatsApp calls ring. description: >- Specifies inbound route for this management platform access update call settings request. **Allowed values** | Value | Meaning | | --- | --- | | `clients` | Clients. | | `sip_trunk` | Sip trunk. | sipTrunkId: type: string nullable: true format: uuid description: >- The SIP trunk for `sip_trunk`: a trunk in the session's project whose direction is `outbound` or `both`. Required when switching the route to `sip_trunk`; omit it to keep the stored trunk. With `clients` send `null` or omit it: a trunk ID is refused, and `clients` clears the stored trunk. **Accepted alternatives** | Alternative | Accepted input | | --- | --- | | Alternative 1 | Type: `string`; Format: `uuid` | | Alternative 2 | `null` | **Value constraints** | Constraint | Accepted input | | --- | --- | | Format | `uuid` | sipClaim: type: boolean description: Whether an answer from the SIP trunk claims the call. hostCloudApiCalls: type: boolean description: >- Set to true to have Polymorfa Calls answer the session's Cloud API calls instead of your Graph API integration. Applies to calls that arrive after the change. expectedRevision: type: integer minimum: 0 description: >- Apply the update only if the settings still have this `revision` (0 for a session using the defaults). Otherwise the update fails with `409 state_conflict`. **Value constraints** | Constraint | Accepted input | | --- | --- | | Numeric value | `0` or greater | additionalProperties: false management__PlatformAccessUpdateCallSettingsResponse: type: object properties: success: type: boolean enum: - true description: |- Whether the request succeeded. **Allowed values** | Value | Meaning | | --- | --- | | `true` | True. | data: allOf: - $ref: '#/components/schemas/management__PlatformAccessCallSettings' description: Structured data carried by this object. required: - success - data management__PlatformAccessPublicError: type: object properties: error: type: object properties: type: type: string enum: - invalid_request_error - authentication_error - permission_error - conflict_error - rate_limit_error - api_error - upstream_error description: |- Type discriminator for this object. **Allowed values** | Value | Meaning | | --- | --- | | `invalid_request_error` | Invalid request error. | | `authentication_error` | Authentication error. | | `permission_error` | Permission error. | | `conflict_error` | Conflict error. | | `rate_limit_error` | Rate limit error. | | `api_error` | Api error. | | `upstream_error` | Upstream error. | code: type: string enum: - invalid_parameter - invalid_credential - entitlement_required - method_not_allowed - permission_denied - missing_scope - resource_not_found - media_fetch_failed - resource_gone - feature_unavailable - stream_cursor_invalid - stream_cursor_expired - stream_connection_limit_reached - state_conflict - idempotency_conflict - idempotency_in_progress - idempotency_completed - idempotency_outcome_unknown - call_claimed - call_not_ringing - connection_limit - unsupported_for_connection - call_permission_required - invalid_sip_trunk - calls_disabled - sip_trunk_in_use - sip_trunk_revision_conflict - sip_trunk_limit - sip_unavailable - rate_limit_exceeded - internal_error - operation_not_supported - upstream_failure - service_unavailable - credential_verification_unavailable - session_not_ready - command_dispatch_failed - result_unknown - recipient_not_on_whatsapp - conversation_window_closed - template_not_approved - media_too_large - whatsapp_rate_limited - new_chat_limit_reached - whatsapp_account_restricted - bansafe_suspended - bansafe_org_suspended - bansafe_cold_blocked - bansafe_cold_held - bansafe_throttled - bansafe_daily_allowance_reached - bansafe_accounting_unavailable - bansafe_send_outcome_unknown - campaigns_not_entitled description: >- Stable machine-readable code for this result. **Allowed values** | Value | Meaning | | --- | --- | | `invalid_parameter` | Invalid parameter. | | `invalid_credential` | Invalid credential. | | `entitlement_required` | Entitlement required. | | `method_not_allowed` | Method not allowed. | | `permission_denied` | Permission denied. | | `missing_scope` | Missing scope. | | `resource_not_found` | Resource not found. | | `media_fetch_failed` | Media fetch failed. | | `resource_gone` | Resource gone. | | `feature_unavailable` | Feature unavailable. | | `stream_cursor_invalid` | Stream cursor invalid. | | `stream_cursor_expired` | Stream cursor expired. | | `stream_connection_limit_reached` | Stream connection limit reached. | | `state_conflict` | State conflict. | | `idempotency_conflict` | Idempotency conflict. | | `idempotency_in_progress` | Idempotency in progress. | | `idempotency_completed` | Idempotency completed. | | `idempotency_outcome_unknown` | Idempotency outcome unknown. | | `call_claimed` | Call claimed. | | `call_not_ringing` | Call not ringing. | | `connection_limit` | Connection limit. | | `unsupported_for_connection` | Unsupported for connection. | | `call_permission_required` | Call permission required. | | `invalid_sip_trunk` | Invalid sip trunk. | | `calls_disabled` | Calls disabled. | | `sip_trunk_in_use` | Sip trunk in use. | | `sip_trunk_revision_conflict` | Sip trunk revision conflict. | | `sip_trunk_limit` | Sip trunk limit. | | `sip_unavailable` | Sip unavailable. | | `rate_limit_exceeded` | Rate limit exceeded. | | `internal_error` | Internal error. | | `operation_not_supported` | Operation not supported. | | `upstream_failure` | Upstream failure. | | `service_unavailable` | Service unavailable. | | `credential_verification_unavailable` | Credential verification unavailable. | | `session_not_ready` | Session not ready. | | `command_dispatch_failed` | Command dispatch failed. | | `result_unknown` | Result unknown. | | `recipient_not_on_whatsapp` | Recipient not on whatsapp. | | `conversation_window_closed` | Conversation window closed. | | `template_not_approved` | Template not approved. | | `media_too_large` | Media too large. | | `whatsapp_rate_limited` | Whatsapp rate limited. | | `new_chat_limit_reached` | New chat limit reached. | | `whatsapp_account_restricted` | Whatsapp account restricted. | | `bansafe_suspended` | Bansafe suspended. | | `bansafe_org_suspended` | Bansafe org suspended. | | `bansafe_cold_blocked` | Bansafe cold blocked. | | `bansafe_cold_held` | Bansafe cold held. | | `bansafe_throttled` | Bansafe throttled. | | `bansafe_daily_allowance_reached` | Bansafe daily allowance reached. | | `bansafe_accounting_unavailable` | Bansafe accounting unavailable. | | `bansafe_send_outcome_unknown` | Bansafe send outcome unknown. | | `campaigns_not_entitled` | Campaigns not entitled. | message: type: string description: Human-readable message associated with this result. param: type: string nullable: true description: |- Specifies param for this error. **Accepted alternatives** | Alternative | Accepted input | | --- | --- | | Alternative 1 | Type: `string` | | Alternative 2 | `null` | request_id: type: string description: >- Matches the X-Request-Id response header. Include it when you contact support. request_log_url: type: string format: uri description: >- Console page that shows this request. Returned only to organization and project credentials whose request was logged. **Value constraints** | Constraint | Accepted input | | --- | --- | | Format | `uri` | required: - type - code - message - param - request_id description: Error details returned when the operation fails. data: type: string nullable: true enum: - null description: |- Always null for a failed request. **Allowed values** | Value | Meaning | | --- | --- | | `null` | Null. | **Accepted alternatives** | Alternative | Accepted input | | --- | --- | | Alternative 1 | Type: `string` | | Alternative 2 | `null` | docs: type: string format: uri description: |- Specifies docs for this management platform access public error. **Value constraints** | Constraint | Accepted input | | --- | --- | | Format | `uri` | required: - error - data - docs management__PlatformAccessCallInboundRoute: type: string enum: - clients - sip_trunk description: >- Where incoming WhatsApp calls ring. `clients` rings your connected clients only. `sip_trunk` also sends each incoming call to the SIP trunk named by `sipTrunkId`. Defaults to `clients`. management__PlatformAccessCallSettings: type: object properties: callsEnabled: type: boolean description: >- Whether the session can place, answer and receive calls. When false, placing, answering, joining and attaching media fail with `403 calls_disabled`, incoming calls are declined, and SIP trunks cannot place calls through the session. Calls in progress continue, and the participant that answered or placed one can reconnect to it. Defaults to true. conferenceMode: type: boolean description: >- Conference mode. When true, every participant you connect to a call (including SIP trunk callers) hears the WhatsApp party and every other participant you connected. When false, each of them hears only the WhatsApp party. The WhatsApp party always hears all of your participants, and no participant hears their own audio. Defaults to true. inboundRoute: allOf: - $ref: '#/components/schemas/management__PlatformAccessCallInboundRoute' description: >- Specifies inbound route for this management platform access call setting. **Allowed values** | Value | Meaning | | --- | --- | | `clients` | Clients. | | `sip_trunk` | Sip trunk. | sipTrunkId: type: string nullable: true format: uuid description: >- The SIP trunk that receives incoming calls when `inboundRoute` is `sip_trunk`; otherwise null. **Accepted alternatives** | Alternative | Accepted input | | --- | --- | | Alternative 1 | Type: `string`; Format: `uuid` | | Alternative 2 | `null` | **Value constraints** | Constraint | Accepted input | | --- | --- | | Format | `uuid` | sipClaim: type: boolean description: >- Whether an answer from the SIP trunk claims the call, which ends ringing on your other clients. Defaults to true. hostCloudApiCalls: type: boolean description: >- Whether Polymorfa Calls answers the session's incoming calls when the session uses the Cloud API. When false (the default), your app answers them through the Graph API `/calls` endpoint and Polymorfa Calls does not host them. Sessions on a linked device ignore it. revision: type: integer minimum: 0 description: >- Increases on every change; 0 while the session uses the defaults. Send it as `expectedRevision` to refuse an update that would overwrite someone else's change. **Value constraints** | Constraint | Accepted input | | --- | --- | | Numeric value | `0` or greater | updatedAt: type: string nullable: true format: date-time description: >- When the settings were last changed, or null when the session uses the defaults. **Accepted alternatives** | Alternative | Accepted input | | --- | --- | | Alternative 1 | Type: `string`; Format: `date-time` | | Alternative 2 | `null` | **Value constraints** | Constraint | Accepted input | | --- | --- | | Format | `date-time` | required: - callsEnabled - conferenceMode - inboundRoute - sipTrunkId - sipClaim - hostCloudApiCalls - revision - updatedAt additionalProperties: false securitySchemes: management__ApiKeyAuth: type: http scheme: bearer description: >- Send your team API key or project token as `Authorization: Bearer `. The credential must have the required permissions. Project tokens can access only their own project. ````