> For the complete documentation index, see [llms.txt](https://support.whapi.cloud/help-desk/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://support.whapi.cloud/help-desk/account-and-whapi-channels/channel-settings-overview.md). # Channel Settings overview This article lists every parameter available in Whapi.Cloud channel settings Read the current values with [Get channel settings](https://whapi.readme.io/reference/getchannelsettings) and change them with [Update channel settings](https://whapi.readme.io/reference/updatechannelsettings). Some parameters can also be set in the panel — see the **Set in** column. {% hint style="info" %} Most users won't need to configure most of these parameters — the defaults work fine for typical setups. They're here for cases where you need finer control over channel behavior. {% endhint %} {% hint style="warning" %} **Updating via API: omitted settings can be reset.** If a setting has a default value and you leave it out of an update request, it returns to that default — even when you are changing something else. Include every non-default value in each update request. {% endhint %}
Example: why pdo_sync turned back on, and which settings this affects A `PATCH /settings` request can contain only the fields you want to change. Settings that have a default value behave differently: if such a field is missing from the request, it returns to its default. | Setting | Default | If omitted from the request | | -------------------- | ------- | --------------------------- | | `pdo_sync` | `true` | returns to `true` | | `offline_mode` | `false` | returns to `false` | | `full_history` | `false` | returns to `false` | | `auto_read_messages` | `false` | returns to `false` | All other settings (`webhooks`, `media`, `proxy`, `callback_persist`, `data_mode`, `ignored_presences`, etc.) stay unchanged when omitted. **Example.** You turned `pdo_sync` off to stop the endless sync notification on iPhone: ```json { "pdo_sync": false } ``` Later you add an event to your webhook and send only `webhooks`. As a result, `pdo_sync` is `true` again and the notification comes back. **Correct** — send both values: ```json { "pdo_sync": false, "webhooks": [ { "url": "https://example.com/webhook", "events": [ { "type": "messages", "method": "post" }, { "type": "users", "method": "post" } ] } ] } ``` **How to check.** The response to an update request contains `changes` — the list of settings that changed. If it lists a setting you didn't touch, that setting was reset to its default. You can always compare the current values with [Get channel settings](https://whapi.readme.io/reference/getchannelsettings). Saving settings in the panel doesn't reset anything — this applies only to API requests.
### Webhooks Webhook technology allows you to fulfill incoming notifications directly to your server. Some settings can be done through the interface. {% hint style="info" %} Full info: [webhooks overview](https://support.whapi.cloud/help-desk/receiving/webhooks) {% endhint %} #### Core parameters | Parameter | Values | Description | Set in | | --------- | -------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- | ----------- | | `url` | required | The address where notifications will be sent | Panel + API | | `mode` | `body` / `path` / `method` | How the event is transmitted in the request | Panel + API | | `events` | `messages`, `statuses`, `chats`, `contacts`, `presences`, `groups`, `calls`, `labels`, `users`, `channel`, `service` | Which event types to track | Panel + API | **Mode options:** * `body` — all information about the event in the request body (default option) * `path` — the event type is added to the URL, e.g. `.../message/post` * `method` — the event type determines the HTTP method of the request, e.g. `PATCH .../message` {% hint style="info" %} Full info: [webhook mode setting](https://support.whapi.cloud/help-desk/receiving/webhooks/detailed-webhook-settings#mode-setting) · [webhook events](https://support.whapi.cloud/help-desk/receiving/webhooks/our-webhooks-tracked-events) {% endhint %} **Update types** For each event type, you also specify an update type. Update type ≠ HTTP method. | Update type | Meaning | | ----------- | -------------- | | `post` | created | | `put` | full update | | `patch` | partial update | | `delete` | deleted | {% hint style="info" %} Full info: [webhook update types](https://support.whapi.cloud/help-desk/receiving/webhooks/detailed-webhook-settings#webhook-events-and-update-types-post-put-patch-delete) {% endhint %} #### Privacy | Parameter | Description | Set in | | --------- | ------------------------------------------------------------------------------------------------------------------------------ | -------- | | `headers` | Custom headers for verifying that a webhook request really came from Whapi (e.g. a secret token your server checks on receipt) | API only | {% hint style="info" %} Full info: [Customizable Webhook Headers](/help-desk/account-and-whapi-channels/customizable-webhook-headers.md) {% endhint %} #### Undecrypted messages | Parameter | Values | Description | Set in | | ------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | `send_undecrypted_ad` | default `false` | Send a webhook even for an undecrypted message if it's the first message in a new chat. Useful for tracking Click-to-WhatsApp ad campaigns — the webhook still arrives even if the ad message text itself couldn't be immediately decrypted | API only | | `webhook_max_age_seconds` | 15 sec – 2 days | If a message decrypts later than the specified time, its webhook won't be sent. Prevents your bot from being flooded with webhooks for very outdated messages | API only | #### Guaranteed webhooks | Parameter | Description | Set in | | ------------------------------- | ---------------------------------------------------------------------------------------------------------------- | ----------- | | `callback_persist` | Turns retry behavior on; also stores undelivered webhooks on disk until acknowledged. Requires a channel restart | Panel + API | | `callback_backoff_delay_ms` | Delay before the first retry, growing with each failure | API only | | `max_callback_backoff_delay_ms` | The cap on that delay | API only | {% hint style="info" %} Full info: [Persistent webhook setting](https://support.whapi.cloud/help-desk/receiving/webhooks/detailed-webhook-settings#persistent-webhook-setting-ex-persist) {% endhint %} ### Media | Parameter | Description | Set in | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | | `auto_download` | Adds a direct link to the media file contained in the message, both in the webhook and in GET request responses. Media types: images, documents, video, audio | Panel + API | | `init_avatars` | If `true`, contact, chat and group avatars are loaded automatically after channel authorization. Enable it before re-authorizing the channel: enabling it on an already linked channel does not load existing contacts. Loading runs in the background, roughly one contact every 3 seconds | API only | {% hint style="info" %} Full info: [Setting Auto Download](https://support.whapi.cloud/help-desk/account-and-whapi-channels/setting-auto-download) {% endhint %} ### Other params The most commonly used parameters come first; the ones needed in rare cases are at the end. | Parameter | Description | Set in | | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | | `proxy` | Allows you to add a SOCKS5 proxy. Reduces WhatsApp's suspicions related to IP channel and phone region mismatches, improving session stability and reducing the risk of blocking | Panel + API | | `pdo_sync` | Stops retrying to decrypt old messages; fixes the looping/infinite push notification issue on iPhone | API only | | `offline_mode` | Prevents the channel from sending an "online" status on connection, so push notifications keep arriving on the iPhone | API only | | `full_history` | Allows you to access the entire message history available in WhatsApp after reconnecting (instead of partial). Working after reconnect | API only | | `data_mode` | Identifier format: LID, phone number, or both at once (`extend`, beta — it also carries the counterpart's `username` where WhatsApp provides one) | API only | | `ignored_presences` | A list of contacts whose presence events (online/typing) should not be sent to the webhook (unsubscribe from presence) | API only | | `auto_read_messages` | Automatically marks incoming messages as read as soon as they're received | API only | | `proxy_trust_filters` | Lets a custom proxy work on a network where HTTPS traffic is filtered by Netspark/Rimon or NetFree — the channel trusts those providers' root certificates. Turn it on after the custom proxy is configured | API only | | `mobile_proxy` | Beta-only parameter — not in use, ignored in production | API only | {% hint style="info" %} [Using Residential Proxies with Whapi.Cloud](https://support.whapi.cloud/help-desk/blocking/using-residential-proxies-with-whapi.cloud#using-residential-proxies-with-whapi.cloud) [Missing push notifications after connecting to API](https://support.whapi.cloud/help-desk/troubleshooting/missing-push-notifications-after-connecting-to-api) [Automatically Mark Incoming WhatsApp Messages as Read](https://support.whapi.cloud/help-desk/hints/automatically-mark-incoming-whatsapp-messages-as-read) [WhatsApp usernames and BSUID](https://support.whapi.cloud/help-desk/faq/whatsapp-usernames-and-bsuid) {% endhint %} ### Examples Example of full channel settings payload ```json { "webhooks": [ { "url": "https://example.com/webhook", "mode": "body", "events": [ { "type": "messages", "method": "post" }, { "type": "messages", "method": "put" }, { "type": "messages", "method": "delete" }, { "type": "messages", "method": "patch" } ], "headers": { "Headers key": "Headers value" }, "send_undecrypted_ad": true, "webhook_max_age_seconds": 15 } ], "callback_persist": true, "callback_backoff_delay_ms": 4000, "max_callback_backoff_delay_ms": 3600000, "media": { "auto_download": [ "image", "audio", "voice", "video", "document", "sticker" ], "init_avatars": true }, "proxy": "socks5://login:password@ip:port", "offline_mode": true, "full_history": true, "auto_read_messages": true, "ignored_presences": [ "7777777777" ], "data_mode": "extend", "pdo_sync": true } ``` Default (empty) channel settings ```json { "media": { "auto_download": [], "init_avatars": false }, "webhooks": [], "offline_mode": false, "full_history": false, "auto_read_messages": false, "pdo_sync": true } ```