Settings

Turn only exposes a subset of the WhatsApp Business API. Each section and the functionality exposed is listed below.

Application Settings

Setting the application settings

$ curl -X PATCH https://whatsapp.turn.io/v1/settings/application \
    -H 'Authorization: Bearer token' \
    -H 'Content-Type: application/json' \
    -d '
    {
        "webhooks": {
            "url": "https://example.com"
        }
    }
    '

> {}

Retrieving the application settings

$ curl -X GET https://whatsapp.turn.io/v1/settings/application \
    -H 'Authorization: Bearer token'

> {
    "settings": {
        "application": {
            "webhooks": {
                "url": "https://example.com"
            }
        }
    }
}

Configure your primary webhook with this endpoint. The primary webhook is given priority when relaying messages to your endpoints.

Before an event is dispatched to your configured webhook endpoint, it is queued in Turn. Under normal conditions this is a matter of milliseconds.

Turn operates 3 levels of queue priority, low, default, and high. The low priority queue is drained with least urgency and the high priority queue is given maximum amount of resources to ensure fast delivery.

Which queues your events are dispatched to depends on how fast your endpoint responds. The response time of your endpoints are sampled once every 20 webhook event deliveries. The time it takes you to accept a message for delivery determines what queue the following event is going to be dispatched to.

Queue	Millisecond threshold
`low`	1 second or more
`default`	Longer than 200ms but less than 1 second
`high`	200ms or less

Turn's commitment is that if your webhook endpoint is fast in processing messages we will commit to process your messages as fast as we can. If your webhook endpoint is slow, we will treat the events with low priority.

Sampling of your webhook response time is constantly ongoing and as you change your processing speed you will automatically be moved to a higher or lower queue priority.

note

We may choose to expose more application settings functionality in the future. Please get in touch with us should you feel anything critical is missing.

Webhook Retry Strategy

Turn will rety to send a webhook event depending on the HTTP status code:

Error Type	Behavior	Example HTTP Response
4XX HTTP Status Codes (Client Errors)	Cancel further retries	`HTTP 404 Not Found`
Unresolvable Domain Errors (Permanent)	Cancel further retries	`HTTP 502 Bad Gateway (Unresolvable Domain)`
Network Errors (Temporary)	Retry	`HTTP 504 Gateway Timeout`
Other Errors	Retry	`HTTP 500 Internal Server Error`

This ensures that retriable errors are handled efficiently, while unrecoverable ones are quickly identified and canceled, optimizing the system’s response to different failure scenarios.

Turn will continue to retry it for a maximum of 5 times. Turn does this with an incremental backoff, meaning there is an increased delay in every retry.

The first retry follows roughly 17 seconds after the first failed attempt. The following retries occur about 19 seconds, 24, 31 and then 47 seconds later. Messages will be dropped if the endpoint is offline longer than about 140 seconds.

Some amount of jitter is introduced in the retry timings and so the exact timing interval may differ at times.

Reset Primary Webhook Settings

$ curl -X DELETE https://whatsapp.turn.io/v1/settings/application \
    -H 'Authorization: Bearer token'

Settings can be reset with an HTTP DELETE call to the endpoint. At this point that only results in clearing of the primary webhook, if one was set.

Setting the Business About Settings

note

Support for this API was removed with the move to the Cloud API. It will not continue to work for numbers that have migrated to the Cloud API as it was an on-premise only feature.

This information can now be changed in the Settings section of Turn.

Setting the business about

$ curl -X PATCH https://whatsapp.turn.io/v1/settings/profile/about \
    -H 'Authorization: Bearer token' \
    -H 'Content-Type: application/json' \
    -d '
    {
        "text": "your-profile-about-text"
    }
    '
> {}

Use the /v1/settings/profile/about endpoint to configure your about text:

Parameter

Name	Type	Description
`text`	string	Text to display in your profile's About section. The max length for the string is 139 characters.

A successful request returns the HTTP Status Code 200 OK and either null or .

Viewing the Business About Settings

Retrieving the business about

$ curl -X GET https://whatsapp.turn.io/v1/settings/profile/about \
    -H 'Authorization: Bearer token'
> '{
  "settings": {
    "profile": {
      "about": {
        "text": "your-profile-about-text"
      }
    }
  }
}'

A successful response contains the profile object with the text parameter containing your profile's About content.

Setting the Business Profile Settings

Setting the business profile

$ curl -X POST https://whatsapp.turn.io/v1/settings/business/profile \
    -H 'Authorization: Bearer token' \
    -H 'Content-Type: application/json' \
    -d '
    {
        "address": "your-business-address",
        "description": "your-business-description",
        "email": "your-business-email",
        "vertical": "your-business-industry",
        "websites": [ "your-website-1", "your-website-2" ]
    }
    '

> {}

Retrieving a business profile

$ curl -X GET https://whatsapp.turn.io/v1/settings/business/profile \
    -H 'Authorization: Bearer token'

> {
   "settings": {
     "business": {
        "profile": {
          "address": "business-address",
          "description": "business-description",
          "email": "business-email",
          "vertical": "business-industry",
          "websites": [ "website-1", "website-2" ]
        }
      }
}

Use the /v1/settings/business/profile endpoint to configure your business profile settings such as:

Business address
Business description
Email for business contact
Business industry
Business website

Currently, settings can only be configured as a group. Future releases may enable setting individual settings.

Parameter

Name	Type	Description
`address`	string	address of the business. Maximum of 256 characters
`description`	string	Description of the business. Maximum of 256 characters
`email`	string	Email address to contact the business. Maximum of 128 characters
`vertical`	string	Industry of the business. Maximum of 128 characters
`websites`	array of strings	URLs associated with business (e.g., website, Facebook page, Instagram). Maximum of 2 websites with a maximum of 256 characters each

A successful request returns the HTTP Status Code 200 OK and either null or .

Setting the Profile Photo

$ curl -X POST https://whatsapp.turn.io/v1/settings/profile/photo \
    -H 'Authorization: Bearer token' \
    -H 'Content-Type: image/jpeg' \
    --data-binary @your-path-to-image

To change your profile photo using the API, send the raw image to the /v1/settings/profile/photo endpoint.

Profile photos can be of any dimension and size. The WhatsApp Business API Client will scale and crop it to be a square with a max edge of 640 and max size of 63KB before uploading to our servers. An image size of 640x640 is recommended.

note

If you are having trouble uploading your JPEG image it may be because of hidden attributes in your image file. We recommend using imagecompressor.com to clear your image of these attributes and then trying again.

A successful request returns the HTTP Status Code 200 OK and either null or .

Retrieve Profile Photo

note

Support for this API was removed with the move to the Cloud API. It will not continue to work for numbers that have migrated to the Cloud API as it was an on-premise only feature.

This information can now be changed in the Settings section of Turn.

$ curl -X GET https://whatsapp.turn.io/v1/settings/profile/photo \
    -H 'Authorization: Bearer token'

Use the WhatsApp Business API's /v1/settings/profile/photo endpoint to retrieve the image that you are using as your profile photo.

Two-Step Verification

note

Support for this API was removed with the move to the Cloud API. It will not continue to work for numbers that have migrated to the Cloud API as it was an on-premise only feature.

This information can now be changed in the Settings section of Turn.

$ curl -X POST https://whatsapp.turn.io/v1/settings/account/two-step \
    -H 'Authorization: Bearer token' \
    -H 'Content-Type: application/json' \
    -d '{"pin": "859274"}

$ curl -X DELETE https://whatsapp.turn.io/v1/settings/account/two-step \
    -H 'Authorization: Bearer token'

A successful request returns the HTTP Status Code 200 OK.

Use two-step verification to add an extra layer of security to the WhatsApp Business API Client. When you have two-step verification enabled, any attempt to register your phone number on WhatsApp must be accompanied by the six-digit PIN that you create using this feature. Two-step verification can be enabled and disabled using the /v1/settings/account/two-step endpoint.

To enable two-step verification, use HTTP POST with the pin parameter on the /v1/settings/account/two-step endpoint.

To remove two-step verification, use HTTP DELETE.

note

Two step verification must be enabled when wanting to apply for a verified business name.

Application Settings​

Webhook Retry Strategy​

Reset Primary Webhook Settings​

Setting the Business About Settings​

Parameter​

Viewing the Business About Settings​

Setting the Business Profile Settings​

Parameter​

Setting the Profile Photo​

Retrieve Profile Photo​

Two-Step Verification​

Application Settings

Webhook Retry Strategy

Reset Primary Webhook Settings

Setting the Business About Settings

Parameter

Viewing the Business About Settings

Setting the Business Profile Settings

Parameter

Setting the Profile Photo

Retrieve Profile Photo

Two-Step Verification