WhatsApp Business 开放平台
返回中文(简体)
文档已更新。
中文(简体) 译文尚未完成。
英语更新时间：11月15日
中文(简体) 更新时间：8月19日

WhatsApp Business 开放平台

Changelog

This document is a log of changes to the WhatsApp Business Platform.

November 13, 2024

Cloud API

November 12, 2024

Cloud API

November 5, 2024

All APIs

October 11, 2024

Business Management API

October 2, 2024

Cloud API, version 21.0 changes

September 25, 2024

Cloud API

September 24, 2024

Cloud API

  • Added checkout button templates (only available to India businesses that use business phone numbers with India country calling codes).

September 11, 2024

Cloud API

September 10, 2024

Cloud API

  • Changed media asset caching behavior from developer definable (via Cache-Control header) to a fixed time period of 10 minutes. You can still force us to fetch assets from your server instead of our cache, however. See Media Caching.

September 6, 2024

Cloud API

June 1, 2024

Cloud API

Business Management API

April 10, 2024

Cloud API

April 10, 2024

Cloud API

March 18, 2024

Cloud API

February 13, 2024

Cloud API

  • Changed business phone number registration/deregistration attempt limits to 10 requests per business number in a 72 hour moving window (was a one-week moving window).

February 6, 2024

Cloud API, On-Premises API

January 26, 2024

Cloud API

  • Changed Cloud API template message delivery retry time-to-live from 24 hours to 30 days. You can still override this value for authentication templates.
  • Changed biz_opaque_callback_data character maximum from 256 to 512.

January 18, 2024

Cloud API

December 18, 2023

Cloud API

December 12, 2023

Business Management API

November 20, 2023

Business Management API

  • Added console logging to help with debugging one-tap and zero-tap authentication templates.

November 14, 2023

Cloud API

November 3, 2023

Business Management API

October 23, 2023

Business Management API, Cloud API, On-Premises API

October 10, 2023

Flows

Cloud API

October 4, 2023

Business Management API, Cloud API, On-Premises API

  • Authentication templates using the code expiration warning now use the code_expiration_minutes value (instead of a default of 10 minutes) to determine if the delivered template message should display an autofill button or copy code button.
  • Autofill buttons displayed in a delivered template message will become disabled after the amount of time indicated by the template's code_expiration_minutes value, if present (or after 10 minutes, if not present).

October 2, 2023

Cloud API

September 27, 2023

Cloud API

  • Added ctwa_clid property to referral object in messages webhooks. Indicates the click ID generated when the user taps an ad that clicks to WhatsApp in order to send the message.

September 18, 2023

Cloud API, On-Premises API

  • Legacy authentication templates (authentication templates without one-time password buttons) can continue to be sent, edited, and appealed until April 1, 204 (extended from October 2, 2023).

September 12, 2023

Business Management API

Cloud API

Cloud API, On-Premises API

  • Migrating business phone numbers that have multiconnect running 2 or more shards from On-Premises API to Cloud API automatically upgrades the numbers to higher Cloud API throughput.

August 28, 2023

Cloud API, On-Premises API

August 15, 2023

Business Management API

August 8, 2023

Tools

Business Management API

Embedded Signup

August 2, 2023

Business Management API

July 11, 2023

Cloud API

  • Scheduling and performing an upgrade to a business phone number's throughput no longer requires a live call.
  • You can now specify an upgrade time when submitting a Direct Support ticket to request an upgrade to a business phone number's throughput.
  • Downtime for business phone numbers undergoing a throughput upgrade reduced to 5 minutes or less.

July 7, 2023

Business Management

June 13, 2023

Tools

Business Management

  • Added Business Management API error code 2494100 that indicates a business phone number is temporarily in maintenance mode.

Cloud API

May 26, 2023

Tools

  • Added error signals that can help debug authentication templates with one-time password autofill buttons.

May 23, 2023

Cloud API

  • Attempting to send a paused template in a template message using v17 or later now returns error code 132015 instead of 132001.
  • Attempting to send a disabled template in a template message using v17 or later now returns error code 132016 instead of 132001.

On-Premises API

  • Attempting to send a paused template in a template message now returns error code 2061.
  • Attempting to send a disabled template in a template message now returns error code 2062.

May 9, 2023

Business Management API

Cloud API

On-Premises API

May 1, 2023

Business Management API

  • Added new webhooks notifying you of denials of messaging limit increases to the account_alerts webhooks field.
  • All templates must now be categorized as AUTHENTICATION, MARKETING, or UTILITY.

April 26, 2023

Business Management API

April 18, 2023

Cloud API

  • Added last_onboarded_time to WhatsApp Business Phone Number node. Indicates when a user created a business phone number on their WhatsApp Business Account by completing the Embedded Signup flow.

April 11, 2023

Cloud API

Embedded Signup

April 4, 2023

Business Management AI, Cloud API, On-Premises API

March 17, 2023

Business Management API

March 14, 2023

Cloud API

  • You can now share location information with users by adding a Location Header in your template.

On-Premises API

March 1, 2023

Cloud API, On-Premises API

  • Migrating an India-based business phone number from On-Premises API to Cloud API no longer deletes its online selling compliance data, so you no longer have to manually repopulate this data after migration.

February 15, 2023

Business Management API

  • Added a new template comparison endpoint that allows you to compare template send counts and block ratios.

February 3, 2023

Cloud API, On-Premises API

February 2, 2023

Business Management API, Cloud API

Cloud API

  • Templates created or edited using v16.0 must now be categorized using one of the following categories; all other categories are no longer supported. Applies to Cloud API v16.0+. Will apply to all versions May 1, 2023. This change has been introduced to support our June 1, 2023 switch to a new conversation-based pricing model.
    • AUTHENTICATION
    • MARKETING
    • UTILITY
  • Error subcodes, which are rarely used and should not be relied upon, will no longer be included in v16.0+ error responses. Use code and details instead.
  • Error code 100 ("code":100) had multiple unique titles which indicated the nature of a given 100 error. All code 100 errors will now use Invalid parameter as their title. Old titles that described the nature of a given code 100 error have been moved to the details property. This change is also now reflected in webhooks payloads that describe a code 100 error response.

Cloud API Webhooks

  • The errors object in webhooks triggered by v16.0+ request errors now include message and error_data.details properties, and title values have changed for multiple error codes. Now, errors objects have the following structure and data:
[
  {
    "code": <CODE>,
    "title" : "<TITLE>",
    "message": "<MESSAGE>",
    "error_data": {
      "details": "<DETAILS>"
    }
  },
  ...
]
  • The title property value has been updated for the following error codes. Their old values now appear in error_data.details.
    • 130470 new title is now Re-engagement message
    • 130429 new title is now Rate limit hit
    • 131045 new title is now Incorrect certificate
    • 131031 new title is now Business Account locked
    • 131053 new title is now Media upload error
    • 131027 new title is now Something went wrong
    • 131042 new title is now Business eligibility payment issue
    • 131026 new title is now Message Undeliverable
    • 131000 new title is now Something went wrong
  • The message property value is the same as the title property value, which indicates the error code's title. This property maps to the message property in API error response payloads.
  • The error_data.details property now includes error code titles from the error codes listed above and describes the underlying cause of the error. This value maps to the details property in API error response payloads.

These changes are reflected in the following errors properties in error-related webhooks:

  • entry.changes.value.errors
  • entry.changes.value.messages.errors
  • entry.changes.value.statuses.errors

January 30, 2023

Cloud API

Unverified businesses can now initiate up to 250 conversations in a rolling 24-hour period.

December 13, 2022

Media Permission Check

Applies to all Cloud API versions.

Added new optional phone_number_id field to the Media endpoint. If you include this parameter and a business phone number ID, the operation will only be processed if the phone number ID matches the ID of the phone number upon which the media was uploaded.

December 8, 2022

HTTP Media Caching

Cloud API HTTP media caching is out of beta and available to everyone.

Webhooks

Cloud API will now reattempt to deliver failed webhooks notifications for up to 7 days instead of up to 30 days. See Webhooks Delivery Failure.

November 23, 2022

New Webhooks Field

Applies to all versions.

  • Added a new template_performance_metrics field. Notifies you weekly of all template performance metrics, including messages sent count, messages opened count, and top reasons for blocks.

November 22, 2022

New Webhooks Fields and Values

Applies to all versions.

New account_alerts field:

  • Added a new account_alerts field. Notifies you of Business, WhatsApp Business Account, and business phone number alerts.

New account_update field values:

  • Added a new account_update.events value: ACCOUNT_DELETED. Indicates that a phone number has been de-registered or deleted from a WhatsApp Business Account.
  • Added a new message_template_status_update.events value: PENDING_DELETION. Indicates a message template has been marked for deletion.

Sample Webhooks notifications that are sent when these new events are triggered:

New WhatsApp Business Account Node Fields

Added the following WhatsApp Business Account node fields:

  • country (applies to v15.0+)
  • ownership_type (applies to v15.0+)
  • business_verification_status (applies to all versions)

New Business Endpoint Filters

Applies to v15.0+.

Added the following filter options to the Business Client Whatsapp Business Accounts endpoint:

  • Filter by WhatsApp Business Account creation_time field using GREATER_THAN, LESS_THAN, or IN_RANGE operators.
  • Filter by WhatsApp Business Account ownership_type using EQUAL or IN operators.

Added the following filter options to the Business Owned WhatsApp Business Accounts endpoint:

  • Filter by WhatsApp Business Account creation_time using GREATER_THAN, LESS_THAN, or IN_RANGE operators.
  • Filter by WhatsApp Business Account ownership_type using EQUAL or IN operators.
  • Filter by WhatsApp Business Account country using EQUAL or IN operators.

New Phone Number Node Fields

Applies to v15.0+

Added the following WhatsApp Business Phone Number node fields:

  • is_official_business_account
  • messaging_limit_tier

In addition, you can filter WhatsApp Business Account Phone Numbers endpoint by is_official_business_account.

November 3, 2022

Messages Per Second

Cloud API now supports up to 500 (up from 350) messages per second (mps) of combined text and media messages, by request. See Throughput for details.

If you already have 350 mps it will be increased to 500 mps automatically. If you already requested 350 mps but the process has not been completed, you will receive 500 mps upon completion.

Media HTTP Caching

We are now beta testing Cloud API media HTTP caching. If you are a Solution Partner, see Media HTTP Caching to learn how to use headers in your server responses that instruct us to cache your media assets for reuse with future messages.

Document Captions

Cloud API now supports captions on documents sent to and received from customers. See Media Object in the Media reference.

October 25, 2022

Message Template Limit Increased

WhatsApp Business Accounts can now have up to 6,000 message templates if their parent business has been verified and at least one of the parent business's WhatsApp Business Accounts has a business phone number with an approved display name.

As part of this change, translated versions of a message template now count against a WhatsApp Business Account's template limit.

October 20, 2022

Billing

Businesses in India can now use a credit card to pay for messages sent using the platform. See Add a Credit Card to Your WhatsApp Business Platform Account.

October 12, 2022

Business Phone Number Migration

You can now migrate a business phone number to and from Cloud API WhatsApp Business Accounts. See Migrate Phone Number to a Different WABA.

October 6, 2022

Callback Override

Cloud API only.

You can now use different callback URLs for each of your WhatsApp Business Accounts without having to create a unique app for each WhatsApp Business Account. See Overriding the Callback URL for details.

Version 15 Calls

All Cloud API endpoints now support version 15 calls.

Message Templates

Cloud API only.

Text parameters (components.parameters.text) for message templates that only use a body component (components.type:body) can now total up to 32,768 characters. See Parameters object.

Messages Per Second

Cloud API only.

Cloud API now supports up to 350 (up from 250) messages per second (mps) of combined text and media messages, by request. See Throughput for details.

If you already have 250 mps it will be increased to 350 mps automatically. If you already requested 250 mps but the process has not been completed, you will receive 350 mps upon completion.

Cloud API - September 22, 2022

Reactions

Reactions are now supported. See Send Messages - Reaction Messages to learn how to send and receive reactions and Payload Examples - Reaction Messages for webhook payload notification examples.

Business Profile

The about field on business profiles is now supported. See Business Profiles for details.

Cloud API — September 7, 2022

Messages Per Second

Latest documentation for requesting migration from 80 messages per second to 250 messages per second of combined sending and receiving of text and media messages is now available. See Throughput.

Cloud API — August 25, 2022

Animated Stickers

You can now include animated stickers in outbound, business-initiated messages and receive message webhooks describing those messages the same way you would if you were sending a non-animated sticker. Refer to the Message object's sticker property and for animated sticker asset requirements.

Product Messages

You can now include products and services in messages sent to customers, and customers can add them to shopping carts without having to leave the chat thread. Refer to the Sell Products & Services guide to learn how to send Single and Multi-Product messages to customers.

Cloud API - July 21, 2022

Replies

Businesses can now reply to any message in a conversation thread. Replies will include a contextual bubble referencing the replied-to message. Refer to the Send Messages guide to learn how to reply to a message.

Messages Per Second

Cloud API now supports up to 250 messages per second of combined sending and receiving (inclusive of text and media messages), by request. If you are an enterprise partner you can open a Direct Support ticket to request 250 MPS throughput by selecting Question Topic: "Cloud API Issues", Request Type: "Request to migrate to 250 MPS throughput" and filling out the required information.

Notice for Developers: Announcing Backwards Incompatible Changes for Future Versions v2.43 and v2.45

v2.43 October 11, 2022

  • Starting in v2.43, there will be changes to the behavior of the contacts endpoint
    • Responses for status will change. Regardless of whether a user has WhatsApp, it will always return valid for status in the response and a wa_id. There is no guarantee that the returned wa_id will be valid. These changes are applicable for both direct responses, as well as webhook responses for non-blocking calls
    • Ensure your code avoids relying on status and wa_id returned in the contacts node. In addition, sending a message on v2.39.1 or higher can be completed without calling the contacts node

  • Ensure your code handles a potential 1013 User is not valid error when trying to send a template message, which will be returned if you attempt to send the template message to a phone number without a WhatsApp account

  • For non template messages, sending a message to a phone number without a WhatsApp account will return a 470 error

v2.45 January 10, 2023

  • Starting in v2.45, the optional cert parameter in the shards node will become mandatory for all requests. Please update your integration to always include a valid cert when calling the shards node

  • Starting in v2.41.2, businesses can use the application node to filter out sent message statuses they are not interested in through the message object within the webhooks object. In v2.45, sent_status will be deprecated, so update your integration to use the webhooks object in the application node for all webhook controls

  • As of v2.39.1, recipient_id is available in both the statuses object and in the message object. In v2.45, recipient_id will be removed in the statuses object, so update your integration to use recipient_id under the message object

On-Premises API - September 19, 2022 (v2.41.3)

Release 2.41.3

The v2.41.3 version of our Business API client includes: Added a new table index on message_receipt_log that could benefit partners with high throughput needs. For instance, this improvement allows partners to send more than 200 messages/second.

On-Premises API - June 27, 2022 (v2.41.2)

Please follow the best practices below to ensure a seamless upgrade to v2.41.2:

In v2.41.2, we are introducing DB schema changes to improve the performance of the system. As a result, upgrades from v2.37.2 and v2.39.x for set ups with large databases which have millions of message and contact entries will take longer than usual.

Generally, perform upgrades during off-peak hours and upgrade lower-throughput setups first.

For large databases, follow these steps:

  • Run garbage collection via the /services/message/gc endpoint before your upgrade, and ensure it completes successfully

  • Please use the dbupgrade tool to upgrade the DB schemas prior to the version upgrade. Once done, you will be able to upgrade API versions with minimal down time. It is strongly recommended to bring the API client down before using the dbupgrade tool. Ensure the dbupgrade tool completes successfully (exit code 0), and avoid or limit API requests while the upgrade is taking place

We recommend increasing the query timeout on your database servers to one hour, until the upgrade completes successfully.

This client version contains the following features and updates:

  • Improvements to the latency of the bulk /contacts endpoint requests and resolution of deadlock issues
  • Improvements to the performance and reliability of the garbage collection process
  • Businesses now have the ability to enable/disable delivered and read webhook notifications which gives them greater control over webhook notifications for messages. This can be achieved through the settings/applications endpoint
  • namespace field is optional for the template object
  • More robust handling of media download errors so businesses should experience less issues downloading media sent by customers
  • Additional reliability and bug fixes within the send message and registration workflows

WhatsApp Business Cloud API - May 19, 2022

Starting today, the WhatsApp Business Cloud API is open to all developers building products or services for themselves or their organizations. To get started, see our guide. If you are interested in offering API access to your customers, please join our waitlist.

WhatsApp Business Management API - May 19, 2022

Message Template Categories

The following values for the category parameter for the /WHATSAPP-BUSINESS-ACCOUNT-ID/message_template endpoint have been deprecated for v14.0 and later:

  • ACCOUNT_UPDATE
  • ALERT_UPDATE
  • APPOINTMENT_UPDATE
  • AUTO_REPLY
  • ISSUE_RESOLUTION
  • PAYMENT_UPDATE
  • PERSONAL_FINANCE_UPDATE
  • RESERVATION_UPDATE
  • SHIPPING_UPDATE
  • TICKET_UPDATE
  • TRANSPORTATION_UPDATE

The following values have been added:

  • TRANSACTIONAL
  • MARKETING

WhatsApp On-Premises API - May 10, 2022 (v2.39.4)

This client version contains all features and fixes shipped with v2.39.1. Additionally, this release:

  • Fixes a bug that prevented video messages from being sent under certain circumstances. This fix was also included in v2.39.2.
  • Fixes a bug that prevented businesses from sending messages to a customer, if the customer was the first to initiate an interaction between the two parties on WhatsApp, and that initiation happened more than 7 days ago. This fix was also included in v2.39.3.
  • Fixes a bug that prevented businesses from receiving disappearing messages from customers. After v2.39.4 is installed, businesses will get notified they received a disappearing message by a webhooks notification with type set to "ephemeral". Businesses will not be able to see the message's content.

When we launched v2.39.3, the disappearing messages issue was handled by WhatsApp automatically disabling these messages in the chat thread with the client. For v2.39.4, we will not do that. With this version, businesses that receive disappearing messages must ask the customer to disable disappearing messages and resend their latest message.

WhatsApp On-Premises API - AWS Service Templates - May 4, 2022

Release 2.3.8

Template URLs

Changelog

  • Updating AMIs for CentOS 7 machines

Cloud API - May 3, 2022

Starting today, the Cloud API includes the following upgrades:

  • Fixed an issue related to disappearing messages from users.
  • Better determination of thumbnail quality for media messages.

WhatsApp On-Premises API - AWS Service Templates - Apr 26, 2022

Release 2.3.7

Template URLs

Changelog

  • Moved from using pip to pip3 to install AWS bootstrap scripts.
  • Fixed an issue with awscli installation.

Cloud API - Apr 5, 2022

Starting today, the Cloud API is generally available to all existing Solution Partners and direct clients. Additionally, we’re releasing the following features for Cloud API developers:

  • Messages with Stickers: Send media messages containing third-party static stickers. See the following documentation for more details: Reference, Messages and Reference, Media. We support inbound both and outbound stickers. For outbound, we only support static third-party stickers. For inbound, we support all types of stickers.
  • Deregister Phone Number API: Make POST calls to PHONE_NUMBER_ID/deregister in order to remove a phone number from the WhatsApp Business API. See Registration for information.
  • New Phone Verification Option: Verify your business phone number via Graph API calls. See Phone Numbers for information.
  • New Referral Webhooks: Receive Webhooks notifications when a user clicks on an ad that clicks to WhatsApp and sends a message to the business. See Webhooks for information. Be aware that the Cloud API's webhooks referral object is different from the On-Premises API's referral object.

Additionally, we are announcing that App Review is no longer required for first-party developers using the Cloud API. All developers are subject to the WhatsApp Business Platform messaging limits.

On-Premises API - Mar 26, 2022

This version contains the same features as v2.37.1, but there's a different expiration date. v2.37.2 expires on Sep 22, 2022.

Known Issues

Some Kubernetes developers may see CrashLoopBackOff for their webapp container and their container may fail to start. To fix that, add following line in the Kubernetes deployment YML file under webapp configuration:

command: ["/opt/whatsapp/bin/wait_on_mysql.sh", "/opt/whatsapp/bin/launch_within_docker.sh"]

On-Premises API - Mar 25, 2022

The v2.39.3 version of our Business API client is available for developers today. The new client includes two fixes and additional logs to support debugging. The two fixes are:

  • Fixed a bug that prevented businesses from sending messages to a customer, if the customer was the first to initiate an interaction between the two parties on WhatsApp, and that initiation happened more than 7 days ago.
  • Fixed a bug that prevented businesses from receiving disappearing messages from customers. After v2.39.3 is installed, businesses will get notified they received a disappearing message by a webhooks notification. On their end, customers will see a warning saying that the disappearing messages mode has been turned off.

Cloud API - Mar 15, 2022

List Messages and Reply Buttons

Starting today, Cloud API beta users can start sending and list and reply button messages. See the following documentation for more details:

Preview URL

Starting today, Cloud API beta users can add a preview URL box to text messages that include a URL. See the following documentation for more details:

New Documentation Guides

On-Premises API - Mar 4, 2022

We just released the On-Premises API v2.39.2. This version fixes a bug that prevented video messages from being sent under certain circumstances.

Known Issues

  • A bug exists that prevents businesses from sending messages to a customer, if the customer was the first to initiate an interaction between the two parties on WhatsApp, and that initiation happened more than 7 days ago.
  • A bug exists that prevents businesses from receiving disappearing messages from customers.

Cloud API - Mar 1, 2022

Video Messages

Starting today, Cloud API beta users can start sending and receiving video messages. The following documentation provides more information:

Feb 1, 2022

WhatsApp Business Platform

Starting today, WhatsApp has switched from a notification-based pricing model to a conversation-based pricing model. Businesses are charged per conversation, which includes all messages delivered in a 24 hour session. See Conversation-Based Pricing for information.

Cloud API

Location and Contact Messages

Starting today, Cloud API beta users can start sending and receiving location and contact messages. See the documentation below for more information:

Peak Throughput Update

We now support 80 messages per second peak throughput per phone number. This includes incoming and outgoing messages, as well as text, template and media messages.

On-Premises API (2.39.1)

The 2.39.1 version of our Business API client is available for developers starting today. The new client includes:

Set Shards API

Starting with the new API client version, you may provide your phone’s certificate when you are setting up multiconnect. That means that, when calling the /v1/account/shards endpoint, you can add the Base64-encoded certificate in the cert field. See Scale Your API Client With Multiconnect for information.

New Hostname

We have added graph.whatsapp.com to the list of WhatsApp server hostnames that the Business API client requires connectivity to. See Set Up and Debug Your Network, Hostnames for information.

Error Code Updates

With v2.39, we have added error code 1031. You will get this error if your account has been locked and can’t send any messages due to an integrity policy violation. See Error and Status Messages and Policy Enforcement for information.

Deprecations

  • Messages API: The hsm type has been deprecated with v2.39. You should use the template type instead.
  • Application Setting: The application setting webhook_payload_conversation_pricingmodel_disabled has been deprecated.

Known Issues

Some video messages fail to send under certain circumstances.