WhatsApp Business 平台企業內部 API

我們即將停用內部部署 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

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

更新

如要更新應用程式設定，請將 PATCH 要求傳送至 /v1/settings/application 端點，並使用 JSON 物件來包含待設定的欄位名稱和值。

如果是涉及大量訊息的傳送訊息宣傳活動，建議您將 garbagecollector_enable.messages 設定為 false 來停用自動垃圾回收功能，並在宣傳活動結束後將其設定回 true 來重新啟用此功能。

您可以向 /v1/settings/application 端點傳送 GET 要求並讀取 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,
}

成功後，回應會包含帶有 null 或 JSON 物件的 200 OK。

如果遇到任何錯誤，請參閱錯誤和狀態訊息。

參數

更改特定設定時，系統會要求您重新開啟核心應用程式，以便執行此等變更。這些設定為 callback_persist、garbagecollector_enable、verbose_logging、log_level 和 webhooks.max_concurrent_requests。

`log_level`
名稱說明

axolotl_context_striping_disabled

類型：布林值

影響資料庫連接上限。


v2.25 改善了發出和接收效能。此優化項目需要建立更多數據庫連接。對於某些部署，這可能會導致系統達到資料庫連接上限。在這種情況下，請將 axolotl_context_striping_disabled 配置設定為 true，以停用此成效提升功能。這不會影響核心應用程式的任何功能。


值：true、false（預設）

必須重新開啟核心應用程式。

callback_backoff_delay_ms

類型：字串

回呼失敗的退避延遲時間（以毫秒為單位）。


此設定可用於配置重試失敗回呼前的退避延遲時長。每當回呼無法獲取 HTTPS 200 OK 回應時，退避延遲時長便會按此增幅呈線性上升。退避延遲的上限視乎 max_callback_backoff_delay_ms 設定而定。例如，回呼第一次失敗時，系統將在 3000 毫秒（3 秒）後重試。回呼第二次失敗時，系統會在等待 6000 毫秒（6 秒）後重試；如此類推，直至回呼成功，或者延遲時長達到 900000 毫秒（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

類型：整數

主節點監控核心應用程式節點的間隔時長（以秒為單位）。


預設：5
適用於多點連線設定。

max_callback_backoff_delay_ms

類型：字串

回呼失敗的最長延遲時間（以毫秒為單位）。詳情請參閱下文對 callback_backoff_delay_ms 的說明。


預設：900000

media

類型：陣列

媒體自動下載清單。請參閱自動下載媒體設定，以了解更多相關資訊。

notify_user_change_number

類型：布林值

影響 user_changed_number 系統通知。


值：true、false（預設）

pass_through

類型：布林值

由 v2.35 起，您將無法再為 WhatsApp Business API 用戶端重新啟用 pass_through 設定。


允許系統在個別訊息送達或獲讀取後將之刪除或儲存在本機資料庫中。


傳送訊息後，系統會將之儲存到本機資料庫中。此資料庫將用作為應用程式的歷史記錄。由於企業需自行負責保留自己的歷史記錄，您可以指定是否需要訊息 pass_through。

  • 若為 true，系統會在訊息送達傳送對象或傳送對象讀取訊息後，將之從本機資料庫中移除。
  • 若為 false，則在自動刪除（即 db_garbagecollector_enable 為 true）或明確刪除（即 db_garbagecollector_enable 為 false）訊息前，系統會將所有訊息儲存在本機儲存空間中。詳情請參閱服務文件。

建議您停用 pass_through，以便 status 回呼正常運作。


值：true、false（預設）

必須重新開啟核心應用程式。

show_security_notifications

類型：布林值

啟用後，當 WhatsApp Business API 用戶端偵測到與您對話的用戶可能發生變化時，您將收到 user_identity_changed Webhook 通知。若發生這種情況，傳送給此用戶的所有發送訊息均會被封鎖，直到您使用 identity 端點確認此用戶的身分變更為止。


值：true、false（預設）

skip_referral_media_download

類型：布林值

如果設定為 true，用戶在點擊圖片或影片上的 WhatsApp 發訊廣告後，相關圖片和影片不會下載。


預設：false

unhealthy_interval

類型：整數

在認定心跳狀態不健康並啟動故障轉移過程之前，主節點等待核心應用程式節點回應該心跳的時長秒數上限。


預設：30
適用於多點連線設定。

webhook_payload_conversation_pricingmodel_disabled

類型：布林值

此欄位已在 v2.39 中停用。

控制範圍包括訊息狀態通知中的對話和定價資訊裝載。


值：true、false（預設）

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

webhooks

類型：Webhooks 物件

當您使用 Webhooks 時，此為必要項目。

為您的 Webhooks 提供網址。若您尚未設定 Webhooks 網址，則系統會放棄回呼。查閱測試應用程式範例，了解更容易查看和測試 Webhooks 的方法。


設定 Webhooks 網址時，您可以將共享密鑰指定為查詢參數，以此驗證 Webhooks 事件。範例：https://url?auth='[shared_secret]'。

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


若您尚未設定 Webhook 網址，則系統會放棄回呼。回呼是傳遞及時通知和帶外錯誤的重要渠道，因此我們強烈建議您配置 Webhook 網址端點。如需有關 Webhook 欄位的詳細資訊，請參閱下方的 Webhooks 參數表。

verbose_logging

類型：布林值

在核心應用程式啟用詳細資訊記錄。出於輸出量高，記錄級別僅應用於測試。若設定為 true，則略過 log_level 屬性。


值：true、false（預設）

log_level

類型：Webhooks 物件

在核心應用程式配置記錄級別。每個級別逐漸減少記錄輸出數量：info 擁有最多資料，而 fatal 只包含嚴重錯誤。


值：info（預設）、warning、error、fatal

Webhooks 參數

名稱說明

max_concurrent_requests

類型：整數

配置系統執行的待處理回呼要求之上限。


值：6（預設）、12、18 或 24
必須重新開啟核心應用程式。

url

類型：字串

接收和發出的通知會導向到此網址。如需更多資訊，請參閱 Webhooks 文件。


必須使用 HTTPS 端點；不支援 HTTP 網址。
範例：https://spotless-process.glitch.me/webhook

message

類型：訊息物件

v2.41.2 及以上版本可用

內嵌於 webhooks 物件，能夠讓用戶端設定要從此 sent、delivered、read 清單中接收哪些訊息相關 Webhook 通知。請參閱此處，進一步了解相關狀態。


企業可將值設定為 true（預設）或 false，以選擇是否接收這些 Webhook 通知。

媒體參數

名稱說明

auto_download

類型：陣列

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


值：audio、document、voice、video、image、sticker

垃圾回收參數

名稱說明

messages

類型：布林值

配置訊息垃圾回收設定。


值：true（預設）、false
必須重新開啟核心應用程式。

media

類型：布林值

配置媒體垃圾回收設定。


值：true、false（預設）
必須重新開啟核心應用程式。

重設為預設設定

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

要求範例

DELETE /v1/settings/application

成功後，回應會包含帶有 null 或 {} 的 200 OK。

如果遇到任何錯誤，請參閱錯誤和狀態訊息。