Channel Settings overview

This article lists every parameter available in Whapi.Cloud channel settings

Read the current values with Get channel settings and change them with Update channel settings. Some parameters can also be set in the panel — see the Set in column.

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.

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.

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:

{ "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:

{
  "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.

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.

Full info: webhooks overview

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

Full info: webhook mode setting · webhook events

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

Full info: webhook update types

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

Full info: Customizable Webhook Headers

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

Full info: Persistent webhook setting

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 avatars are automatically fetched after channel authorization	API only

Full info: Setting Auto Download

Other params

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
mobile_proxy	Beta-only parameter — not in use, ignored in production	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
auto_read_messages	Automatically marks incoming messages as read as soon as they're received	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
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
pdo_sync	Stops retrying to decrypt old messages; fixes the looping/infinite push notification issue on iPhone	API only

Using Residential Proxies with Whapi.Cloud

Missing push notifications after connecting to API

Automatically Mark Incoming WhatsApp Messages as Read

WhatsApp usernames and BSUID

Examples

Example of full channel settings payload

{
  "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

{
  "media": {
    "auto_download": [],
    "init_avatars": false
  },
  "webhooks": [],
  "offline_mode": false,
  "full_history": false,
  "auto_read_messages": false,
  "pdo_sync": true
}