我們即將停用內部部署 API。請參閱我們的內部部署 API 停用文件以取得詳細資訊,並瞭解如何轉移到我們的新一代雲端 API。

應用程式設定

WhatsApp Business 內部部署用戶端的應用程式設定。

必備條件

  • 您必須使用 admin 帳號才能提出要求
  • 所有回應皆必須包含 200 OK HTTPS

讀取

取得 WhatsApp Business 內部部署用戶端目前的應用程式設定

範例

傳送 GET 要求至 /v1/settings/application 端點可取得目前的應用程式設定。

GET /v1/settings/application

如果成功,回應會包含 200 OK 以及內含 application 物件的 JSON 承載,其中列出目前所有應用程式設定及其值。

回應範例

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

關係連線

關係連線說明

/media/providers

用於管理傳送媒體連結的媒體供應商清單。

更新

若要更新應用程式設定,請傳送包含 JSON 物件的 PATCH 要求至 /v1/settings/application 端點,該物件內含要設定的欄位名稱和值。

針對大量訊息的發訊行銷活動,建議將 garbagecollector_enable.messages 設為 false 來停用自動記憶體回收,並在行銷活動結束後將其設回 true 來重新啟用自動記憶體回收。

您可以傳送 GET 要求至 /v1/settings/application 端點並讀取 garbagecollector_enable 屬性,驗證是否已停用自動記憶體回收。

要求範例

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,
}

傳送成功後,回應會包含 200 OK,其中具有 null 或 JSON 物件。

如果發生任何錯誤,請參閱錯誤和狀態訊息

參數

部分設定會要求重新啟動核心應用程式,以使變更生效,這些設定為:callback_persistgarbagecollector_enableverbose_logginglog_levelwebhooks.max_concurrent_requests

`log_level`
名稱說明

axolotl_context_striping_disabled

類型:布林值

影響資料庫連線限制。


v2.25 提升了出站和入站效能。此最佳化仰賴於建立其他資料庫連線。對某些部署而言,這可能會導致達到資料庫連線限制。在此情況下,請將 axolotl_context_striping_disabled 設定設為 true 以停用此效能提升功能。這對核心應用程式的任何功能不會有其他影響。


值:truefalse(預設值)

需重新啟動核心應用程式。

callback_backoff_delay_ms

類型:字串

回呼失敗的後退延遲(單位為毫秒)。


此設定為用於設定重試失敗回呼前的後退延遲時間。每次回呼無法取得 HTTPS 200 OK 回應時,後退延遲都會線性增加此數值。後退延遲受 max_callback_backoff_delay_ms 設定的限制。例如,如果回呼第一次失敗,它會在 3,000 毫秒(3 秒)後重試一次。第二次失敗則會延遲 6,000 毫秒(6 秒)後重試。將持續直到回呼成功或延遲達到 900,000 毫秒(15 分鐘)為止,之後則會繼續重試回呼但不會增加延遲。


預設值:3000

callback_persist

類型:布林值

在磁碟上儲存回呼,直到 Webhook 成功認可它們為止。訊息和回呼都會儲存在本機資料庫上,以確保它們從本機資料庫移除之前成功送達。如此可在 WhatsApp Business API 用戶端或伺服器發生故障時保護回呼。
不成功的通知(沒有 HTTPS 200 回應)將無限期重試。請使用此設定來指定重試。


值:true(預設值)、false
需重新啟動核心應用程式。

db_garbagecollector_enable

類型:布林值

此欄位在 v2.49 中已停用


啟用訊息資料庫的自動記憶體回收,以協助進行資料庫管理。


對於 v2.29 之前將 pass_through 設為 false 的用戶,此參數為 false。建議啟用此設定,以確保資料庫穩定運作。如果想停用此設定,建議考慮使用 /services/message/gc 端點來管理資料庫。


值:true(預設值)、false

需重新啟動核心應用程式。

garbagecollector_enable

類型:記憶體回收器物件

啟用訊息和媒體的自動記憶體回收。


建議使用訊息和媒體記憶體回收設定,以確保移除舊的/未使用的橫列和檔案。如果停用,可以使用 /services/message/gc/services/media/gc 端點來啟用記憶體回收器。請參閱記憶體回收器參數表,瞭解這些值的資訊。


需重新啟動核心應用程式。

heartbeat_interval

類型:整數

Master 節點監控核心應用程式節點的間隔(單位為秒)。


預設值:5
套用至多點連線設定。

max_callback_backoff_delay_ms

類型:字串

回呼失敗的最大延遲(單位為毫秒)。如需詳細資訊,請閱讀下方 callback_backoff_delay_ms 的說明。


預設值:900000

media

類型:陣列

自動下載媒體的清單。如需詳細資訊,請參閱自動下載媒體設定

notify_user_change_number

類型:布林值

影響 user_changed_number 系統通知。


值:truefalse(預設值)

pass_through

類型:布林值

v2.35 開始,您無法再為 WhatsApp Business API 用戶端重新啟用 pass_through 設定。


允許在傳遞或讀取個別訊息後將其刪除或儲存至本機資料庫。


系統傳送訊息時,會將訊息儲存在本機資料庫中。此資料庫將用作應用程式的記錄。由於企業會自行保留記錄,因此您可指定訊息是否要 pass_through

  • 設為 true 時,當系統將訊息送達給收件人或收件人已讀取訊息後,系統會移除本機資料庫的訊息。
  • 設為 false 時,系統在自動刪除(亦即 db_garbagecollector_enabletrue)或明確刪除(亦即 db_garbagecollector_enablefalse)訊息之前,會將所有訊息儲存在本機資料庫中。如需詳細資訊,請參閱服務文件。

建議停用 pass_through,使 status 回呼能正常運作。


值:truefalse(預設值)

需重新啟動核心應用程式。

show_security_notifications

類型:布林值

如果啟用,您將在 WhatsApp Business API 用戶端偵測到正與您對話的用戶可能變更時收到 user_identity_changed Webhook 通知。發生此狀況時,直到您使用 identity 端點確認此用戶的身分變更之前,系統將封鎖傳送給該用戶的所有傳出訊息。


值:truefalse(預設值)

skip_referral_media_download

類型:布林值

若設為 true,系統將不會下載用戶點擊的 WhatsApp 發訊廣告圖像或影片。


預設值:false

unhealthy_interval

類型:整數

Master 節點等待 Coreapp 節點回應活動訊號的最大秒數,超過此秒數便會將其視為不正常並開始容錯移轉程序。


預設值:30
套用至多點連線設定。

webhook_payload_conversation_pricingmodel_disabled

類型:布林值

此欄位在 v2.39 中已停用

包含訊息狀態通知對話定價資訊承載的控制。


值:truefalse(預設值)

不需重新啟動核心應用程式。

webhooks

類型:Webhooks 物件

使用 Webhooks 時為必要項目。

為您的 Webhook 提供網址。如果未設定 Webhook 網址,系統會捨棄回呼。請參閱樣本測試應用程式,以瞭解查看和測試 Webhooks 的簡單方法。


設定 Webhook 網址時,可以透過將共用密鑰指定為查詢參數來驗證 Webhook 事件。範例:https://url?auth='[shared_secret]'

Webhook 網址。例如:https://spotless-process.glitch.me/webhook


如果未設定 Webhook 網址,系統會捨棄回呼。回呼是傳遞即時通知和頻外錯誤兩者的重要管道,因此強烈建議設定 Webhook 網址端點。如需 Webhook 欄位的詳細資料,請參閱以下的 Webhooks 參數表

verbose_logging

類型:布林值

在核心應用程式中啟用詳細記錄。由於匯出量較高,此記錄層級應僅用於測試。如果設為 true,則忽略 log_level 屬性。


值:truefalse(預設值)

log_level

類型:Webhooks 物件

在核心應用程式中設定記錄層級。每個層級會逐漸減少記錄匯出量:info 包含最多資訊,fatal 則僅包含嚴重錯誤。


值:info(預設值)、warningerrorfatal

Webhooks 參數

名稱說明

max_concurrent_requests

類型:整數

設定送出的進行中回呼要求的最大數量。


值:6(預設值)、121824
需重新啟動核心應用程式。

url

類型:字串

將入站和出站通知路由至此網址。如需詳細資訊,請參閱 Webhooks 文件


需要 HTTPS 型的端點;HTTP 無法運作。
範例:https://spotless-process.glitch.me/webhook

message

類型:訊息物件

在 v2.41.2 及後續版本中可供使用

此物件巢狀於 webhooks 物件中,可讓用戶端設定從此清單中所要接收的訊息相關 Webhook 通知:sentdeliveredread。如需這些狀態的詳細相關資訊,請參閱此處


商家可以將值設為 true(預設值)或 false,選擇是否接收這些 Webhook 通知。

媒體參數

名稱說明

auto_download

類型:陣列

指定要自動下載的媒體類型。


值:audiodocumentvoicevideoimagesticker

記憶體回收器參數

名稱說明

messages

類型:布林值

設定訊息記憶體回收。


值:true(預設值)、false
需重新啟動核心應用程式。

media

類型:布林值

設定媒體記憶體回收。


值:truefalse(預設值)
需重新啟動核心應用程式。

重設為預設設定

若要將所有應用程式設定重設為預設值,請傳送 DELETE 要求至 /v1/settings/application 端點。

要求範例

DELETE /v1/settings/application

傳送成功後,回應會包含 200 OK,其中具有 null{}

如果發生任何錯誤,請參閱錯誤和狀態訊息