WhatsApp Business 开放平台本地 API

我们将弃用本地 API。请参阅我们的本地 API 弃用文档，了解弃用详情以及如何迁移到我们的下一代云端 API。

应用程序设置

WhatsApp Business On-Premises 客户端的应用程序设置。

要求

  • 必须使用您的 admin 帐号发出请求
  • 所有响应必须包括 200 OK HTTPS

读取

获取 WhatsApp Business On-Premises 客户端当前的应用程序设置

示例

向 /v1/settings/application 端点发送 GET 请求，以获取当前的应用程序设置。

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

用于管理媒体提供方列表，以发送媒体链接。

更新

如要更新应用程序设置，请向 /v1/settings/application 端点发送 PATCH 请求，在请求中加入一个 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,
}

若请求成功，响应会包含 200 OK 以及 null 或 JSON 对象。

如果遇到任何错误，请参阅错误和状态消息。

参数

某些设置需要重新开启核心应用，才能使更改生效。这些设置为 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 设置。例如，如果第一次回调失败，则系统将在 3,000 毫秒（3 秒）后重试。如果第二次回调失败，则必须等待 6,000 毫秒（6 秒）方可重试。这种情况会持续，直至回调成功或者延迟时间达到 900,000 毫秒（15 分钟）。达到这一时间后，继续重试回调将不会增加延长时间。


默认值：3,000

callback_persist

类型：布尔值

请选择是否在 Webhooks 成功确认收到消息之前，将回调存储在磁盘上。消息和回调均存储在本地数据库中，以确保系统成功发送这些项目后才会从本地数据库中将其移除。如此一来，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 的描述。


默认值：900,000

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 Webhooks 通知。当出现这种情况时，在您使用 identity 端点核实该用户的身份变更前，系统将阻止发送给该用户的所有传出消息。


值：true、false（默认值）

skip_referral_media_download

类型：布尔值

如果设置为 true，用户在点击 WhatsApp 直达广告上的图片或视频后，系统不会下载该图片或视频。


默认值：false

unhealthy_interval

类型：整数

在认定核心应用状态不佳并启动故障转移流程前，Master 节点等待核心应用节点响应检测信号的最长时间（以秒为单位）。


默认值：30
适用于多连接设置。

webhook_payload_conversation_pricingmodel_disabled

类型：布尔值

在 v2.39 中已停用此字段。

控制消息状态通知中是否包含对话和定价信息有效负载。


值：true、false（默认值）

不必重新开启核心应用。

webhooks

类型：Webhooks 对象

使用 Webhooks 时为必要项。

为 Webhooks 提供网址。如果未设置 Webhooks 网址，则系统会放弃回调。请参阅测试应用示例，了解查看和测试 Webhooks 的简便方法。


您可以在设置 Webhooks 网址时将共享密钥指定为查询参数，以此验证 Webhooks 事件。示例：https://url?auth='[shared_secret]'。

Webhooks 网址。示例：https://spotless-process.glitch.me/webhook。


如果未设置 Webhooks 网址，系统会放弃回调。回调是传递及时通知和带外错误的重要渠道，因此我们强烈建议您配置 Webhooks 网址端点。如需 Webhooks 字段的详细信息，请参阅下方的 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

类型：消息对象

在 2.41.2 及更高版本中可用

该参数嵌套在 webhooks 对象中，支持客户根据以下列表设置要接收哪些与消息相关的 Webhooks 通知：sent、delivered、read。请参阅此文档，获取有关这些状态的更多信息。


公司可以将相关值设置为 true（默认值）或 false，以选择是否接收这些 Webhooks 通知。

媒体参数

名称描述

auto_download

类型：数组

指定要自动下载的媒体类型。


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

垃圾回收器参数

名称描述

messages

类型：布尔值

配置消息的垃圾回收设置。


值：true（默认值）、false
必须重新开启核心应用。

media

类型：布尔值

配置媒体的垃圾回收设置。


值：true、false（默认值）
必须重新开启核心应用。

重置为默认设置

如要将所有应用程序设置重置为默认值，请向 /v1/settings/application 端点发送 DELETE 请求。

请求示例

DELETE /v1/settings/application

若请求成功，响应会包含 200 OK 以及 null 或 {}。

如果遇到任何错误，请参阅错误和状态消息。