Application Settings

/v1/settings/application

Update, retrieve, or reset your application settings using the WhatsApp Busines web tool or by using API calls to the /v1/settings/application endpoint.

This document covers using API calls in order to:

The complete list of valid application settings is listed under the Parameters section.

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

Update 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 on_call_pager is not sent with the request, the existing configuration for on_call_pager 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"]
    }
    "callback_backoff_delay_ms": "delay-in-ms",
    "on_call_pager": "on-call-pager-group-id",
    "pass_through": false | true,
    "sent_status": false | true,
    "heartbeat_interval": heartbeat-interval-in-secs,
    "unhealthy_interval": unhealthy-interval-in-secs,
    "webhooks": { 
        # see Webhooks Settings below
        "max_concurrent_requests": max-num-of-callback-requests,
        "url": "webhook.your-domain"
    }
}

Parameters

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

NameTypeDescription

callback_persist

Boolean

Options: true (default), false
Stores callbacks on disk until they are successfully acknowledged by the Webhook or not. Restart required.
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.

max_callback_backoff_delay_ms

String

Default: 900000
Maximum delay for a failed callback in milliseconds
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

Default: 3000
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.

on_call_pager

String

Set to valid WhatsApp Group with users who wish to see alerts for critical errors and messages.


Please follow steps as per the Groups documentation to create valid WhatsApp Group. Here is the summary of those steps:

pass_through

Boolean

Options: true, false
Default (for new installs): true
When true, removes messages from the local database after they are delivered to or read by the recipient. When false, saves all messages on local storage until they are explicitly deleted.
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. Restart required.

sent_status

Boolean

Options: true, false (default)
Receive a notification that a message is sent to server. When true, you will receive a message indicating that a message has been sent. If false (default), you will not receive notification.

webhooks

Webhooks Object

URL for your Webhook
If the Webhook URL is not set, then 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 to configure the Webhook URL endpoint.
Example: https://spotless-process.glitch.me/webhook.
For details on the Webhook fields, see the Webhooks Settings.

unhealthy_interval

Integer

Default: 30
Multiconnect: 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.

heartbeat_interval

Integer

Default: 5
Multiconnect: Interval of the Master node monitoring of Coreapp nodes in seconds

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. A HTTPS-based endpoint is required; HTTP will not work. This URL may look like this: https://spotless-process.glitch.me/webhook. For more information, read the Webhooks documentation.

max_concurrent_requests

Integer

Configures the maximum number of inflight callback requests that are sent out. Can be set to 6 (default), 12, 18, or 24. Restart required.

Auto-download Media Parameters

The following table describes the media object in more detail.

NameTypeDescription

auto_download

Array

An array specifying which types of media to automatically download. Can contain any or all of the following: audio, document, voice, video, image.

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 Application Settings

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

Request

GET /v1/settings/application

Response

If successful, your request returns 200 OK and a message body containing an application object. For example, the complete response, including the application object, might look like this:

{
    "settings": {
        "application": {
            "callback_backoff_delay_ms": 2000,
            "callback_persist": true,
            "heartbeat_interval": 5,
            "max_callback_backoff_delay_ms": 800000,
            "media": {
                "auto_download": [
                    "document",
                    "image"
                ]
            },
            "on_call_pager": "12345678890-1533229619",
            "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 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.