> ## Documentation Index > Fetch the complete documentation index at: https://docs.flowapt.com/llms.txt > Use this file to discover all available pages before exploring further. # Update Calling Settings > Change WhatsApp's calling settings for your number and/or who answers incoming calls. Fields you leave out of calling stay as they are. Scope: write. Change WhatsApp's calling settings for your number (`calling`) and/or who answers incoming calls (`answered_by`). Send only what you change; the response shows the settings WhatsApp now holds. ## Basic Usage ```bash theme={null} curl -X PATCH "https://api.flowiq.live/v1/calling/settings" \ -H "Authorization: Bearer fiq_YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"calling": {"status": "ENABLED"}, "answered_by": "stream", "stream": {"url": "wss://agent.example.com/flowiq", "format": "pcm16_16k", "headers": {"Authorization": "Bearer my-secret"}}}' ``` *** ## Body Parameters | Parameter | Type | Required | Description | | - | - | - | - | | `answered_by` | string | No | `api`: incoming calls are left for your server (the FlowIQ inbox does not ring, FlowIQ's voice AI does not pick up); you answer each with [Accept Call](https://docs.flowapt.com/flowiq-api-reference/endpoint/accept-call.md). `stream`: FlowIQ answers every incoming call and streams the audio to `stream.url`. `flowiq`: FlowIQ answers again | | `stream` | object | With `stream` | `{ url: "wss://…", format?, headers?, custom_parameters? }`, the [media stream](https://docs.flowapt.com/flowiq-api-reference/calling.md#stream-the-audio-to-your-own-voice-agent) target. Kept until you set `answered_by` to `api` | | `calling.status` | string | No | `ENABLED` or `DISABLED`: calling on your number | | `calling.call_icon_visibility` | string | No | `DEFAULT` shows the call button in WhatsApp; `DISABLE_ALL` hides it (you can still call people who gave permission) | | `calling.call_icons.restrict_to_user_countries` | array | No | Show the call button only to numbers from these countries, e.g. `["ZA"]` | | `calling.callback_permission_status` | string | No | `ENABLED`: after calling you, people are asked whether you may call them back | | `calling.call_hours` | object | No | `status`, `timezone_id`, `weekly_operating_hours` (`day_of_week`, `open_time` / `close_time` as `HHMM`, max 2 per day) and optional `holiday_schedule`. Replaces the stored hours | | `calling.sip` | object | No | `status` and `servers` (`hostname`, `port`, `request_uri_user_params`): send calls to your SIP server | | `calling.audio.additional_codecs` | array | No | `PCMA` and/or `PCMU` besides Opus | | `calling.voicemail` | object | No | WhatsApp voicemail (`status`, `triggers`, `audio`) | *** ## Response ### Success (200) ```json theme={null} { "organization_id": "a4234f32-…", "success": true, "calling": { "status": "ENABLED", "call_icon_visibility": "DEFAULT", "callback_permission_status": "ENABLED" }, "answered_by": "stream", "flowiq_ai_answers": false, "stream": { "url": "wss://agent.example.com/flowiq", "format": "pcm16_16k", "headers": { "Authorization": "•••" }, "custom_parameters": {} } } ``` *** > [!WARNING] > > Turning on `calling.sip` hands every call on the number to your SIP server: FlowIQ then gets no call events, the FlowIQ inbox and voice AI no longer see calls, and the other call endpoints stop working for the number until SIP is off again. WhatsApp checks each value; a refused change answers `400` with WhatsApp's reason in `message` and changes nothing. ## OpenAPI ````yaml flowiq-api-reference/openapi-calls.json PATCH /v1/calling/settings openapi: 3.1.0 info: title: FlowIQ Calling API version: 1.0.0 description: >- Run WhatsApp calls on your FlowIQ number from your own server: answer, decline, end and start calls, ask for call permission, read call history and change the number's calling settings. Every response carries X-Request-Id; errors carry a stable code; POST / PATCH accept Idempotency-Key. servers: - url: https://api.flowiq.live description: FlowIQ Production API security: - BearerAuth: [] paths: /v1/calling/settings: patch: tags: - Calling summary: Update Calling Settings description: >- Change WhatsApp's calling settings for your number and/or who answers incoming calls. Fields you leave out of calling stay as they are. Scope: write. operationId: updateCallingSettings requestBody: required: true content: application/json: schema: type: object properties: calling: $ref: '#/components/schemas/CallingSettings' answered_by: type: string enum: - api - stream - flowiq description: >- api: incoming calls are left for your server (the FlowIQ inbox does not ring, FlowIQ's AI does not pick up); you answer with POST /v1/calls/accept. stream: FlowIQ answers every incoming call and streams the audio to stream.url. flowiq: FlowIQ answers (the inbox rings, or the voice AI when it is on) stream: $ref: '#/components/schemas/StreamConfig' responses: '200': description: Success content: application/json: schema: type: object properties: organization_id: type: string format: uuid success: type: boolean calling: $ref: '#/components/schemas/CallingSettings' answered_by: type: string enum: - api - stream - flowiq flowiq_ai_answers: type: boolean stream: type: - object - 'null' description: >- The media stream set for this number (header values hidden) properties: url: type: string format: type: string headers: type: object custom_parameters: type: object '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/RateLimited' components: schemas: CallingSettings: type: object description: WhatsApp's calling settings for your number, as WhatsApp returns them properties: status: type: string enum: - ENABLED - DISABLED call_icon_visibility: type: string enum: - DEFAULT - DISABLE_ALL call_icons: type: object properties: restrict_to_user_countries: type: array items: type: string callback_permission_status: type: string enum: - ENABLED - DISABLED call_hours: type: object properties: status: type: string enum: - ENABLED - DISABLED timezone_id: type: string example: Africa/Johannesburg weekly_operating_hours: type: array items: type: object properties: day_of_week: type: string enum: - MONDAY - TUESDAY - WEDNESDAY - THURSDAY - FRIDAY - SATURDAY - SUNDAY open_time: type: string example: '0800' close_time: type: string example: '1700' holiday_schedule: type: array items: type: object sip: type: object properties: status: type: string enum: - ENABLED - DISABLED servers: type: array items: type: object properties: hostname: type: string port: type: integer request_uri_user_params: type: object sip_user_password: type: string description: Only with ?include_sip_credentials=true audio: type: object properties: additional_codecs: type: array items: type: string enum: - PCMA - PCMU voicemail: type: object StreamConfig: type: object description: >- Have FlowIQ answer the call and stream its audio to your WebSocket (media stream), instead of answering with sdp required: - url properties: url: type: string example: wss://agent.example.com/flowiq/stream description: Your WebSocket endpoint (wss:// only) format: type: string enum: - pcm16_16k - pcm16_8k - pcm16_24k - mulaw_8k default: pcm16_16k description: >- Audio format on the socket, both directions. mulaw_8k matches Twilio Media Streams headers: type: object additionalProperties: type: string description: Headers FlowIQ sends when it connects, e.g. Authorization custom_parameters: type: object description: Echoed in the start message (max 4 KB) Error: type: object properties: error: type: string description: Short label (Bad request, Not found, …) code: type: string description: Stable machine-readable code, see Conventions message: type: string request_id: type: string format: uuid description: Quote this to support whatsapp_error_code: type: integer description: WhatsApp's own code, on whatsapp_rejected responses: BadRequest: description: Invalid request, or WhatsApp refused it (the message says why) content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Request failed message: Parameter value is not valid Unauthorized: description: Missing or invalid API key content: application/json: schema: $ref: '#/components/schemas/Error' Forbidden: description: The key lacks the scope, or the person has not given call permission content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Request failed message: Contact has not granted callback permission RateLimited: description: 240 reads or 60 actions per minute per key; Retry-After says when content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: fiq_ API key description: >- Your FlowIQ organisation API key (Settings → API Keys), sent as a bearer token. Format: `Bearer fiq_YOUR_API_KEY` ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.