On-Premises API

We are sunsetting On-Premises API. Refer to our On-Premises API Sunset document for details, and to learn how to migrate to our next-generation Cloud API.

Application Settings

The application settings for your WhatsApp Business On-Premises client.

Requirements

  • Requests must be made using your admin account
  • All responses must include 200 OK HTTPS

Read

Get the current application settings for your WhatsApp Business On-Premises client

Example

Send a GET request to the /v1/settings/application endpoint to get the current application settings.

GET /v1/settings/application

On success, the response contains 200 OK and a JSON payload containing an application object listing all the current application settings and their values.

Sample Response

{
    "settings": {
        "application": {
            "callback_backoff_delay_ms": 3000,
            "callback_persist": true,
            "garbagecollector_enable": {
                "media": false,
                "messages": true
            },
            "heartbeat_interval": 5,
            "max_callback_backoff_delay_ms": 900000,
            "media": {
                "auto_download": [
                    "image",
                    "video",
                    "voice",
                    "sticker",
                    "audio",
                    "document"
                ]
            },
            "notify_user_change_number": true,
            "show_security_notifications": true,
            "unhealthy_interval": 30,
            "wa_id": "16315551019",
            "webhooks": {
               	"url": "<Webhook URL, https>",
               	"max_concurrent_requests": max-concurrent-requests,
               	"message": { // Available for v2.41.2 and above
                  	"sent": true,
                  	"delivered": true,
                  	"read": false
                 },
             },
             "verbose_logging": false,
             "log_level" : "info"
         },
    },
    "meta": {
        "api_status": "stable",
        "version": "3.0.1"
    }
}

Edges

EdgeDescription

/media/providers

Use to manage a list of media providers for sending media links.

Update

To update your application settings, send a PATCH request to the /v1/settings/application endpoint with a JSON object containing the field names and values to be set.

For messaging campaigns involving a large volume of messages, it is recommended that you disable automatic garbage collection by setting garbagecollector_enable.messages to false, and reenabling it after the campaign ends by setting it back to true.

You can verify if automatic garbage collection is disabled by sending a GET request to /v1/settings/application endpoint and reading the garbagecollector_enable property.

Example Request

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",
    "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-concurrent-requests,
        "url": "<Webhook URL, https>",
        "message": {              // Available on v2.41.2 and above
                "sent": false,
                "delivered": true,
                "read": false
           },
    },
    "axolotl_context_striping_disabled": false | true,
    "notify_user_change_number": false | true,
    "show_security_notifications": false | true,
    # Available on v2.49.1 and above
    "garbagecollector_enable": {
        "messages": true | false,
        "media": true | false
    }
    "skip_referral_media_download": true | false,
    "webhook_payload_conversation_pricingmodel_disabled": false | true
    # Available on v2.51.1 and above
    "verbose_logging": false | true,
    "log_level" : log-level-str,
}

On success, the response contains 200 OK with a null or a JSON object.

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

Parameters

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

`log_level`
NameDescription

axolotl_context_striping_disabled

type: Boolean

Affects database connection limits.


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.


Values: true, false (default)

Coreapp restart required.

callback_backoff_delay_ms

type: String

Backoff delay for a failed callback in milliseconds.


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.


Default: 3000

callback_persist

type: Boolean

Stores callbacks on disk until they are successfully acknowledged by the Webhook or not. 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.
Notifications that are not successful (no HTTPS 200 response) are retried indefinitely. Use this setting to configure the retry.


Values: true (default), false
Coreapp restart required.

db_garbagecollector_enable

type: Boolean

This field has been deprecated with v2.49.


Enables automatic garbage collection of the messages database to assist in database management.


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.


Values: true (default), false

Coreapp restart required.

garbagecollector_enable

type: Garbage collector Object

Enables automatic garbage collection of the messages and media.


Messages and media garbage collection setting is recommended to ensure old/unused rows and files are removed. If disabled, garbage collector may be initiated using /services/message/gc and /services/media/gc endpoints. See Garbage Collector Parameters table for the values.


Coreapp restart required.

heartbeat_interval

type: Integer

Interval of the Master node monitoring of Coreapp nodes in seconds.


Default: 5
Applies to Multiconnect setups.

max_callback_backoff_delay_ms

type: String

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


Default: 900000

media

type: Array

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

notify_user_change_number

type: Boolean

Affects the user_changed_number system notification.


Values: true, false (default)

pass_through

type: Boolean

Starting with v2.35, you can no longer re-enable the pass_through setting for WhatsApp Business API Clients.


Allows for individual messages to be deleted or stored to a local database after they've been delivered or read.


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.


Values: true, false (default)

Coreapp restart required.

show_security_notifications

type: Boolean

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.


Values: true, false (default)

skip_referral_media_download

type: Boolean

If set to true, the image or video that the user clicked on an ad that Clicks to WhatsApp is not downloaded.


Default: false

unhealthy_interval

type: 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.

webhook_payload_conversation_pricingmodel_disabled

type: Boolean

This field has been deprecated with v2.39.

Controls inclusion of conversation and pricing information payloads in message status notifications.


Values: true, false (default)

Coreapp restart is not required.

webhooks

type: Webhooks Object

Required when you are using Webhooks.

Provide the URL for your Webhook. If the Webhook URL is not set, then callbacks are dropped. See the Sample Testing App for a simple way to see and test your Webhooks.


You can validate Webhook events by specifying a shared secret as a query parameter when you set the Webhook URL. Example: https://url?auth='[shared_secret]'.

The Webhook URL. For example: https://spotless-process.glitch.me/webhook.


If the Webhook URL is not set, callbacks are 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. For details on the Webhook fields, see the Webhooks Parameters table below.

verbose_logging

type: Boolean

Enables verbose logging in coreapps. This logging level should be only used for testing because of the high output volume. If set to true, log_level attribute is ignored.


Values: true, false (default)

log_level

type: Webhooks Object

Configures the logging level in coreapps. Each level gradually reduces the amount of logs output: info has the most information, while fatal contains only critical errors.


Values: info (default), warning, error, fatal

Webhooks Parameters

NameDescription

max_concurrent_requests

type: Integer

Configures the maximum number of inflight callback requests that are sent out.


Values: 6 (default), 12, 18, or 24
Coreapp restart required.

url

type: String

Inbound and outbound notifications are routed to this URL. For more information, see the Webhooks documentation.


An HTTPS-based endpoint is required; HTTP will not work.
Example: https://spotless-process.glitch.me/webhook

message

type: Messages Object

Available in v2.41.2 and above

Nested within the webhooks object, it enables clients to set which message related webhook notifications they want to receive from this list: sent, delivered, read. More information about those statuses can be found here.


The business can elect to receive these webhook notifications or not by setting the values to either true (default) or false.

Media Parameters

NameDescription

auto_download

type: Array

Specifies which types of media to automatically download.


Values: audio, document, voice, video, image, sticker

Garbage Collector Parameters

NameDescription

messages

type: Bool

Configures the messages garbage collection.


Values: true (default), false
Coreapp restart required.

media

type: Bool

Configures the media garbage collection.


Values: true, false (default)
Coreapp restart required.

Reset to Default Settings

To reset all applications settings to their default values, send a DELETE request to the /v1/settings/application endpoint.

Example Request

DELETE /v1/settings/application

On success, the response contains 200 OK with null or {}.

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