Application Settings

/v1/settings/application

Update, retrieve, or reset the application settings of the WhatsApp Business API client. A complete list of all valid application settings is listed in the Parameters table below.

You must use the admin account to access the application settings.

Update the Application Settings

To configure settings for the WhatsApp Business API client, use the /v1/settings/application endpoint with a JSON message body containing the field names and values to be set.

Request

If a field is not present in the request, no change is made to that setting. For example, if callback_persist is not sent with the request, the existing configuration for callback_persist is unchanged.

PATCH /v1/settings/application
{
    "callback_persist": true | false,
    "max_callback_backoff_delay_ms": "max-delay-in-ms",
    "media": {
        "auto_download": ["audio", "document", "voice", "video", "image", "sticker"]
    }
    "callback_backoff_delay_ms": "delay-in-ms",
    "pass_through": false | true,
    "sent_status": false | true,
    "heartbeat_interval": heartbeat-interval-in-secs,
    "unhealthy_interval": unhealthy-interval-in-secs,
    "webhooks": { 
        # See the Webhooks Parameters table below for more information
        "max_concurrent_requests": max-num-of-callback-requests,
        "url": "webhook.your-domain"
    },
    "axolotl_context_striping_disabled": false | true,
    "notify_user_change_number": false | true,
    "show_security_notifications": false | true,
    "db_garbagecollector_enable": true | false
}

Parameters

Some settings require that the Coreapp be restarted in order for the changes to go into effect. Those settings are callback_persist, pass_through, db_garbage_collector, and webhooks: max_concurrent_requests.

NameTypeDescription

callback_persist

Boolean

Stores callbacks on disk until they are successfully acknowledged by the Webhook or not
Values: true (default), false

Messages and callbacks are both stored in a local database to ensure that they are delivered successfully before being removed from the local database. This protects the callbacks in the event the WhatsApp Business API client or server goes down.
Coreapp restart required.

max_callback_backoff_delay_ms

String

Maximum delay for a failed callback in milliseconds
Default: 900000
For more information, read the description for callback_backoff_delay_ms below.

media

Array

List of media to auto-download
See Auto-download Media Settings for more information.

callback_backoff_delay_ms

String

Backoff delay for a failed callback in milliseconds
Default: 3000
This setting is used to configure the amount of time the backoff delays before retrying a failed callback. The backoff delay increases linearly by this value each time a callback fails to get a HTTPS 200 OK response. The backoff delay is capped by the max_callback_backoff_delay_ms setting. For example, if a callback fails the first time, it will try again in 3000ms (3 sec). A second failure will result in a 6000ms (6 sec) delay before retry. This continues until the callback is successful or the delay reaches 900000ms (15 min) after which the callback will continue to be retried but the delay will not increase.

on_call_pager
The on_call_pager will be deprecated in v2.29+. The same alerts are sent with Webhook callbacks and monitoring dashboard alerts. Please use these channels for critical errors.

String

Set to a valid WhatsApp Group with users who wish to see alerts for critical errors and messages.
Follow steps in the Groups documentation to create a valid WhatsApp group:

pass_through

Boolean

Allows for individual messages to be deleted or stored to a local database after they've been delivered or read
Values: true, false (default)
The pass_through parameter only applies to individual messages; group messages are not affected by this parameter.
When messages are sent, they are stored in a local database. This database is used as the application's history. Since the business keeps its own history, you can specify whether you want message pass_through or not.

  • When true, it removes messages from the local database after they are delivered to or read by the recipient.
  • When false, it saves all messages on local storage until they are automatically deleted (i.e., db_garbagecollector_enable is true) or explicitly deleted (i.e., db_garbagecollector_enable is false). See the Services documentation for more information.

We recommend you disable pass_through so the status callback can function as expected.
Coreapp restart required.

sent_status

Boolean

Receive a notification that a message was sent to the server
Options: true (default), false

  • When set to true, you will receive a message indicating that a message has been sent.
  • When set to false, you will not receive a notification.

webhooks

Webhooks Object

The Webhook URL
If the Webhook URL is not set, callbacks will be dropped. Callbacks are an important channel to deliver both timely notifications as well as out-of-band errors, and it is thus highly recommended you configure the Webhook URL endpoint.
Example: https://spotless-process.glitch.me/webhook.
For details on the Webhook fields, see the Webhooks Parameters table below.

unhealthy_interval

Integer

Maximum amount of seconds a Master node waits for a Coreapp node to respond to a heartbeat before considering it unhealthy and starting the failover process
Default: 30
Applies to Multiconnect setups.

heartbeat_interval

Integer

Interval of the Master node monitoring of Coreapp nodes in seconds
Default: 5
Applies to Multiconnect setups.

axolotl_context_striping_disabled

Boolean

Affects database connection limits
Values: true, false (default)

Outbound and inbound performance improved with v2.25. This optimization relies on creating additional database connections. For some deployments, this can cause database connection limits to be reached. In that case, set the axolotl_context_striping_disabled configuration to true to disable this performance improvement feature. There is no other effect on any functionalities of the Coreapp.
Coreapp restart required.

notify_user_change_number

Boolean

Affects the user_changed_number system notification
Values: true, false (default)

show_security_notifications

Boolean

Values: true, false (default)
If enabled, you will receive a user_identity_changed Webhook notification when the WhatsApp Business API client detects a user you are in a conversation with has potentially changed. When this happens, all outgoing messages to this user will be blocked until you have acknowledged the identity change for this user using the identity endpoint.

db_garbagecollector_enable

Boolean

Enables automatic garbage collection of the messages database to assist in database management
Values: true (default), false
This parameter is false for users who had pass_through set to false before v2.29. We recommend you enable this setting to ensure your database operates with stability.
If you would like to disable this setting, we recommend you consider using the /services/message/gc endpoint to manage the database.
Coreapp restart required.

Webhooks Parameters

The following table describes fields in the webhooks object in more detail.

NameTypeDescription

url

String

Inbound and outbound notifications are routed to this URL
An HTTPS-based endpoint is required; HTTP will not work.
Example: https://spotless-process.glitch.me/webhook
For more information, see the Webhooks documentation.

max_concurrent_requests

Integer

Configures the maximum number of inflight callback requests that are sent out
Values: 6 (default), 12, 18, or 24
Coreapp restart required.

Auto-download Media Parameters

The following table describes the media object in more detail.

NameTypeDescription

auto_download

Array

Specifies which types of media to automatically download
Values: audio, document, voice, video, image, sticker

Response

A successful response is the HTTP status code 200 OK with a null or {} message body.

If you encounter any errors, see Error and Status Messages.

Retrieve the Application Settings

Use the /v1/settings/application endpoint to retrieve all the current application settings.

Request

GET /v1/settings/application

Response

If successful, the response contains 200 OK and a message body containing an application object listing all the current application settings and their values.

Example

{
    "settings": {
        "application": {
            "callback_backoff_delay_ms": 2000,
            "callback_persist": true,
            "heartbeat_interval": 5,
            "max_callback_backoff_delay_ms": 800000,
            "media": {
                "auto_download": [
                    "document",
                    "image"
                ]
            },
            "pass_through": true,
            "sent_status": true,
            "unhealthy_interval": 30,
            "wa_id": "16315558011",
            "webhooks": {
                "max_concurrent_requests": 12, 
                "url": "https://spotless-process.glitch.me/webhook"
            }
        }
    }
}

Reset the Application Settings

Use the /v1/settings/application endpoint to reset the application settings to their default values.

Request

DELETE /v1/settings/application

Response

A successful response is 200 OK with null or {}.

If you encounter any errors, see Error and Status Messages.