WhatsApp API webhook

WhatsApp Webhook

对提供的webhook地址，进行WhatsApp业务相关的推送信息（目前webhook支持推送状态回复，消息回复，模板状态更新，WABA账号更新）

收到HTTP 200 OK代表已接受NXCLOUD的回执推送，NXCLOUD将本次请求视为已完成。如果收到HTTP ERROR信息，NXCLOUD将在后续短时间内进行失败重试。最多重试10次。

URL：webhook_url
Method：POST
Content-Type：application/json

状态回复

对调用WhatsApp-API发送消息的场景，提供消息的回执情况

验签说明

对于客户应用配置了回执加签算法，所有的回执请求服务端都会进行加签处理，客户端可自行对回执请求进行验签处理，验签算法请参照签名算法

响应参数

body参数：

参数名	类型	说明
statuses	array[statuses Object]	状态对象
contacts	array[contact Object]	仅针对“已发送”、“已送达”和“已读”状态消息返回。对于 `failed` 状态消息 Webhook，将被完全省略。
business_phone	String	商户电话
messaging_product	String	消息类型，固定值”whatsapp“

statuses Object参数：

参数名	类型	说明
conversation	Object	会话信息
errors	array[error Object]	错误信息
recipient_id	String	用户的电话号码【用户采用匿名化后，该字段可能没有值】
recipient_user_id	String	如果您将消息发送给用户的 BSUID 或父级 BSUID，此属性会被设为该用户的 BSUID 或父级 BSUID。否则，这会被省略。
parent_recipient_user_id	String	如果您已启用父级 BSUID，此属性会被设为用户的父级BSUID。否则，这会被完全省略。
timestamp	String	回调时间戳
status	String	消息的状态，sent（已发送），delivered（已送达)，read（已读），failed（发送失败）
id	String	消息ID（发送消息时返回的ID）
costs	array[cost Object]	费用信息
meta_message_id	String	meta原始消息ID, 该字段不一定存在；发送引用消息时可能用到该字段值，id与meta_message_id 并存时使用meta_message_id作为被引用的消息id，否则使用id
biz_opaque_callback_data	String	发送消息时携带的追踪参数
pricing	Object	计费模式
template_id	String	模板id，当使用Direct send特性，会返回实际使用的模板id
is_bid_spec	String	如果该回执属于竞价消息的状态回执(delivered/read)，则会包含该字段is_bid_spec=1

conversation Object参数：

参数名	类型	说明
id	String	会话ID
expiration_timestamp	String	会话过期时间戳
origin	JsonObject	会话类型信息

origin Object参数：

参数名	类型	说明
type	String	会话类型，marketing（营销会话），utility（通知会话），authentication（验证会话），service（服务会话），referral_conversion（免费会话），marketing_lite（MM Lite API会话)

pricing Object参数:

参数名	类型	说明
billable	boolean	指示给定消息或对话是否计费。值因定价模型而异。1. 如果对话是从自由入口点false发起的，则此标志设置为。从免费入口点发起的对话不计费2. 对于所有其他对话，它设置为true
category	String	authentication — 表示身份验证模板消息 authentication_international — 表示向具有身份验证国际价格的国家或地区境内的 WhatsApp 用户发送的身份验证模板消息。marketing — 表示营销模板消息utility — 表示交易相关模板消息service — 表示非模板消息 referral_conversion — 表示该消息是免费接入点对话的一部分
pricing_model	String	CBP — 表示对话导向型定价适用 PMP — 表示单条消息定价适用
type	String	regular — 表示消息需要付费 free_customer_service — 表示消息免费，因为该消息是在客户服务时间窗内发送的交易相关模板消息或非模板消 free_entry_point — 表示消息免费，因为该消息是免费接入点对话的一部分

error Object参数：

参数名	类型	说明
code	Integer	平台错误码（错误码说明）
meta_code	Integer	meta错误码
title	String	错误信息

cost Object参数:

参数名	类型	说明
currency	String	币种
foreign_price	number	客户售价
cdr_type	Integer	cdr类型， 1（消息），4（营销会话），5（通知会话），6（验证会话），7（服务会话），8（免费会话），9（国际验证），10（MM Lite）
message_id	String	wa消息id
direction	Integer	方向，1（下行），2（上行）

contact Object参数:

参数名	类型	说明
profile	Object
wa_id	String	用户的电话号码【用户采用匿名化后，该字段可能没有值】
user_id	String	将设置为 WhatsApp 用户的 BSUID。
parent_user_id	String	如果您已启用父级 BSUID，此属性会被设为用户的父级BSUID。否则，该属性会被完全省略。

profile Object参数：

参数名	类型	说明
name	String	值将设为 WhatsApp 用户的显示名。
username	String	如果用户已启用匿名化功能，将设置为 WhatsApp 用户的匿名账户。对于 `sent` 状态消息 Webhook 或用户未启用匿名化功能的情况，此属性将被完全省略。

匿名化相关字段补充说明

响应示例

消息已发送[新版本]

场景1：用户未启用匿名化，能获得用户手机号

场景2：用户虽启用匿名化，但能获得用户手机号

{
    "app_id": "48",
    "business_phone": "xxx",
    "channel": 2,
    "merchant_phone": "xxx",
    "messaging_product": "whatsapp",
    "metadata": {
        "display_phone_number": "xxx",
        "phone_number_id": "xxx"
    },
    "contacts": [
        {
            "profile": {
                "name": "test user name"
            },
            "wa_id": "16315551111",
            "user_id": "US.13491208655302741918",
            "parent_user_id": "US.ENT.506847293015824"
        }
    ],
    "statuses": [
        {
            "conversation": {
                "expiration_timestamp": "1750644366",
                "id": "f9df70c0f6ec5413e57ff99d51792e41",
                "origin": {
                    "type": "marketing"
                }
            },
            "costs": [
                {
                    "cdr_type": 4,
                    "currency": "CNY",
                    "direction": 1,
                    "foreign_price": 11,
                    "message_id": "wamid.HBgNODYxMzMyMDIzNzQ0NhUCABEYEjA2RDk1OThCMkJGQ0FFRDJERQA="
                }
            ],
            "id": "wamid.b6caa84cad3c401090640edf0eff7fa3",
            "meta_message_id": "wamid.HBgNODYxMzMyMDIzNzQ0NhUCABEYEjA2RDk1OThCMkJGQ0FFRDJERQA=",
            "pricing": {
                "billable": true,
                "category": "marketing",
                "pricing_model": "PMP",
                "type": "regular"
            },
            "recipient_id": "16315551111",
            "recipient_user_id": "US.13491208655302741918",
            "parent_recipient_user_id": "US.ENT.506847293015824",
            "status": "sent",
            "timestamp": "1750644366"
        }
    ],
    "wabaId": "xxx"
}

消息已发送[新版本]

场景3：用户启用匿名化，且不能获得用户手机号则recipient_id 和 wa_id 省略

{
    "app_id": "48",
    "business_phone": "xxx",
    "channel": 2,
    "merchant_phone": "xxx",
    "messaging_product": "whatsapp",
    "metadata": {
        "display_phone_number": "xxx",
        "phone_number_id": "xxx"
    },
    "contacts": [
        {
            "profile": {
                "name": "test user name"
            },
            "user_id": "US.13491208655302741918",
            "parent_user_id": "US.ENT.506847293015824"
        }
    ],
    "statuses": [
        {
            "conversation": {
                "expiration_timestamp": "1750644366",
                "id": "f9df70c0f6ec5413e57ff99d51792e41",
                "origin": {
                    "type": "marketing"
                }
            },
            "costs": [
                {
                    "cdr_type": 4,
                    "currency": "CNY",
                    "direction": 1,
                    "foreign_price": 11,
                    "message_id": "wamid.HBgNODYxMzMyMDIzNzQ0NhUCABEYEjA2RDk1OThCMkJGQ0FFRDJERQA="
                }
            ],
            "id": "wamid.b6caa84cad3c401090640edf0eff7fa3",
            "meta_message_id": "wamid.HBgNODYxMzMyMDIzNzQ0NhUCABEYEjA2RDk1OThCMkJGQ0FFRDJERQA=",
            "pricing": {
                "billable": true,
                "category": "marketing",
                "pricing_model": "PMP",
                "type": "regular"
            },
            "recipient_user_id": "US.13491208655302741918",
            "parent_recipient_user_id": "US.ENT.506847293015824",
            "status": "sent",
            "timestamp": "1750644366"
        }
    ],
    "wabaId": "xxx"
}

消息已送达[新版本]

场景1：用户未启用匿名化，能获得用户手机号【不会包含username】

{
    "app_id": "48",
    "business_phone": "xxx",
    "channel": 2,
    "merchant_phone": "xxx",
    "messaging_product": "whatsapp",
    "metadata": {
        "display_phone_number": "xxx",
        "phone_number_id": "xxx"
    },
    "contacts": [
        {
            "profile": {
                "name": "test user name"
            },
            "wa_id": "xxx",
            "user_id": "US.13491208655302741918",
            "parent_user_id": "US.ENT.506847293015824"
        }
    ],
    "statuses": [
        {
            "conversation": {
                "id": "e0eea618562a40f99211ea617241b784",
                "origin": {
                    "type": "marketing"
                }
            },
            "id": "wamid.b3316b3b6d7c4dfd8f1a077aa8787140",
            "meta_message_id": "wamid.HBgNODYxMzMyMDIzNzQ0NhUCABEYEjgwQ0Q4NTk1Q0I4RkZDMjlEMAA=",
            "pricing": {
                "billable": true,
                "category": "marketing",
                "pricing_model": "PMP",
                "type": "regular"
            },
            "recipient_id": "xxx",
            "recipient_user_id": "US.13491208655302741918",
            "parent_recipient_user_id": "US.ENT.506847293015824",
            "status": "delivered",
            "timestamp": "1750644491"
        }
    ],
    "wabaId": "xxx"
}

场景2：用户虽启用匿名化，但能获得用户手机号【会包含username】

{
    "app_id": "48",
    "business_phone": "xxx",
    "channel": 2,
    "merchant_phone": "xxx",
    "messaging_product": "whatsapp",
    "metadata": {
        "display_phone_number": "xxx",
        "phone_number_id": "661162737077678"
    },
    "contacts": [
        {
            "profile": {
                "name": "test user name",
                "username": "test user name"
            },
            "wa_id": "16315551111",
            "user_id": "US.13491208655302741918",
            "parent_user_id": "US.ENT.506847293015824"
        }
    ],
    "statuses": [
        {
            "conversation": {
                "id": "e0eea618562a40f99211ea617241b784",
                "origin": {
                    "type": "marketing"
                }
            },
            "id": "wamid.b3316b3b6d7c4dfd8f1a077aa8787140",
            "meta_message_id": "wamid.HBgNODYxMzMyMDIzNzQ0NhUCABEYEjgwQ0Q4NTk1Q0I4RkZDMjlEMAA=",
            "pricing": {
                "billable": true,
                "category": "marketing",
                "pricing_model": "PMP",
                "type": "regular"
            },
            "recipient_id": "xxx",
            "recipient_user_id": "US.13491208655302741918",
            "parent_recipient_user_id": "US.ENT.506847293015824",
            "status": "delivered",
            "timestamp": "1750644491"
        }
    ],
    "wabaId": "xxx"
}

场景3：用户启用匿名化，且不能获得用户手机号则recipient_id 和 wa_id 省略【会包含username】

{
    "app_id": "48",
    "business_phone": "xxx",
    "channel": 2,
    "merchant_phone": "xxx",
    "messaging_product": "whatsapp",
    "metadata": {
        "display_phone_number": "xxx",
        "phone_number_id": "xxx"
    },
    "contacts": [
        {
            "profile": {
                "name": "test user name",
                "username": "test user name"
            },
            "user_id": "US.13491208655302741918",
            "parent_user_id": "US.ENT.506847293015824"
        }
    ],
    "statuses": [
        {
            "conversation": {
                "id": "e0eea618562a40f99211ea617241b784",
                "origin": {
                    "type": "marketing"
                }
            },
            "id": "wamid.b3316b3b6d7c4dfd8f1a077aa8787140",
            "meta_message_id": "wamid.HBgNODYxMzMyMDIzNzQ0NhUCABEYEjgwQ0Q4NTk1Q0I4RkZDMjlEMAA=",
            "pricing": {
                "billable": true,
                "category": "marketing",
                "pricing_model": "PMP",
                "type": "regular"
            },
            "recipient_user_id": "US.13491208655302741918",
            "parent_recipient_user_id": "US.ENT.506847293015824",
            "status": "delivered",
            "timestamp": "1750644491"
        }
    ],
    "wabaId": "xxx"
}

消息已送[新版本]

场景1：用户未启用匿名化，能获得用户手机号【不会包含username】

{
    "app_id": "725",
    "business_phone": "xxx",
    "channel": 2,
    "merchant_phone": "xxx",
    "messaging_product": "whatsapp",
    "metadata": {
        "display_phone_number": "xxx",
        "phone_number_id": "xxx"
    },
    "contacts": [
        {
            "profile": {
                "name": "test user name"
            },
            "wa_id": "xxx",
            "user_id": "US.13491208655302741918",
            "parent_user_id": "US.ENT.506847293015824"
        }
    ],
    "statuses": [
        {
            "id": "wamid.HBgMOTIzMzEwMTU3ODg0FQIAERgSMDhCOEYzRjA5MUYyRDBGQTY0AA==",
            "meta_message_id": "wamid.HBgMOTIzMzEwMTU3ODg0FQIAERgSMDhCOEYzRjA5MUYyRDBGQTY0AA==",
            "recipient_id": "xxx",
            "recipient_user_id": "US.13491208655302741918",
            "parent_recipient_user_id": "US.ENT.506847293015824",
            "status": "read",
            "timestamp": "1773993327"
        }
    ],
    "wabaId": "xxx"
}

场景2：用户虽启用匿名化，但能获得用户手机号【会包含username】

{
    "app_id": "725",
    "business_phone": "xxx",
    "channel": 2,
    "merchant_phone": "xxx",
    "messaging_product": "whatsapp",
    "metadata": {
        "display_phone_number": "xxx",
        "phone_number_id": "xxx"
    },
    "contacts": [
        {
            "profile": {
                "name": "test user name",
                "username": "@testusername"
            },
            "wa_id": "xxx",
            "user_id": "US.13491208655302741918",
            "parent_user_id": "US.ENT.506847293015824"
        }
    ],
    "statuses": [
        {
            "id": "wamid.HBgMOTIzMzEwMTU3ODg0FQIAERgSMDhCOEYzRjA5MUYyRDBGQTY0AA==",
            "meta_message_id": "wamid.HBgMOTIzMzEwMTU3ODg0FQIAERgSMDhCOEYzRjA5MUYyRDBGQTY0AA==",
            "recipient_id": "xxx",
            "recipient_user_id": "US.13491208655302741918",
            "parent_recipient_user_id": "US.ENT.506847293015824",
            "status": "read",
            "timestamp": "1773993327"
        }
    ],
    "wabaId": "xxx"
}

场景3：用户启用匿名化，且不能获得用户手机号则recipient_id 和 wa_id 省略【会包含username】

{
    "app_id": "725",
    "business_phone": "xxx",
    "channel": 2,
    "merchant_phone": "xxx",
    "messaging_product": "whatsapp",
    "metadata": {
        "display_phone_number": "xxx",
        "phone_number_id": "xxx"
    },
    "contacts": [
        {
            "profile": {
                "name": "test user name",
                "username": "@testusername"
            },
            "user_id": "US.13491208655302741918",
            "parent_user_id": "US.ENT.506847293015824"
        }
    ],
    "statuses": [
        {
            "id": "wamid.HBgMOTIzMzEwMTU3ODg0FQIAERgSMDhCOEYzRjA5MUYyRDBGQTY0AA==",
            "meta_message_id": "wamid.HBgMOTIzMzEwMTU3ODg0FQIAERgSMDhCOEYzRjA5MUYyRDBGQTY0AA==",
            "recipient_user_id": "US.13491208655302741918",
            "parent_recipient_user_id": "US.ENT.506847293015824",
            "status": "read",
            "timestamp": "1773993327"
        }
    ],
    "wabaId": "xxx"
}

消息发送失败

错误码说明

code	message	解决办法
9001	System business error	平台错误，请联系相关人员排查
10000	Meta Error	WhatsApp官方发送错误，详情参见meta_code、title
10001	Wa Engine Error	WhatsApp-Engine上游错误，请联系相关人员排查
10002	Wa Engine Send Message Timeout	WhatsApp-Engine发送超时，请联系相关人员排查

消息发送失败[提交给meta同步返回的异常]

{
    "business_phone": "xxx",
    "messaging_product": "whatsapp",
    "statuses": [
        {
            "errors": [
                {
                    "code": 10000,
                    "meta_code": 132001,
                    "title": "Meta Error((#132001) Template name does not exist in the translation)"
                }
            ],
            "id": "wamid.e5d9f560d762417093b20632f959edaf",
            "recipient_id": "xxx",
            "recipient_user_id": "US.13491208655302741918",
            "parent_recipient_user_id": "US.ENT.506847293015824",
            "status": "failed",
            "timestamp": "1754379719"
        }
    ],
    "wabaId": "xxx"
}

{
    "business_phone": "xxx",
    "messaging_product": "whatsapp",
    "statuses": [
        {
            "errors": [
                {
                    "code": 10000,
                    "meta_code": 132005,
                    "title": "Meta Error((#132005) Translated text too long)"
                }
            ],
            "id": "wamid.20250805065001002957",
            "recipient_id": "xxx",
            "recipient_user_id": "US.13491208655302741918",
            "parent_recipient_user_id": "US.ENT.506847293015824",
            "status": "failed",
            "timestamp": "1754347801"
        }
    ],
    "wabaId": "xxx"
}

{
    "business_phone": "xxx",
    "messaging_product": "whatsapp",
    "statuses": [
        {
            "errors": [
                {
                    "code": 10000,
                    "meta_code": 131009,
                    "title": "Meta Error((#131009) Parameter value is not valid)"
                }
            ],
            "id": "wamid.aee91da808384646801081988e407f26",
            "recipient_id": "xxx",
            "recipient_user_id": "US.13491208655302741918",
            "parent_recipient_user_id": "US.ENT.506847293015824",
            "status": "failed",
            "timestamp": "1754373435"
        }
    ],
    "wabaId": "xxx"
}

{
    "business_phone": "xxx",
    "messaging_product": "whatsapp",
    "statuses": [
        {
            "errors": [
                {
                    "code": 10000,
                    "meta_code": 100,
                    "title": "Meta Error((#100) Invalid parameter)"
                }
            ],
            "id": "wamid.519617086f75439885db384697910fb9",
            "recipient_id": "xxx",
            "recipient_user_id": "US.13491208655302741918",
            "parent_recipient_user_id": "US.ENT.506847293015824",
            "status": "failed",
            "timestamp": "1754379958"
        }
    ],
    "wabaId": "xxx"
}

{
    "business_phone": "xxx",
    "messaging_product": "whatsapp",
    "statuses": [
        {
            "errors": [
                {
                    "code": 10000,
                    "meta_code": 131056,
                    "title": "Meta Error((#131056) (Business Account, Consumer Account) pair rate limit hit)"
                }
            ],
            "id": "wamid.6d848cd539254caf94feeae5baf186c0",
            "recipient_id": "xxx",
            "recipient_user_id": "US.13491208655302741918",
            "parent_recipient_user_id": "US.ENT.506847293015824",
            "status": "failed",
            "timestamp": "1754379592"
        }
    ],
    "wabaId": "xxx"
}

Meta回调失败[提交给meta成功后异步返回的异常信息]

{
    "app_id": "1109",
    "business_phone": "xxx",
    "channel": 2,
    "merchant_phone": "xxx",
    "messaging_product": "whatsapp",
    "metadata": {
        "display_phone_number": "xxx",
        "phone_number_id": "xxx"
    },
    "statuses": [
        {
            "errors": [
                {
                    "code": 131026,
                    "title": "Message undeliverable"
                }
            ],
            "id": "wamid.9fd734dfdde54a14bcef35a907d36da5",
            "meta_message_id": "wamid.HBgNNjI4NTI1MDE2NTI1MxUCABEYEjFCNjQzNDc1NTA1NzY2QjVDMQA=",
            "recipient_id": "xxx",
            "recipient_user_id": "US.13491208655302741918",
            "parent_recipient_user_id": "US.ENT.506847293015824",
            "status": "failed",
            "timestamp": "1754380417"
        }
    ],
    "wabaId": "xxx"
}

{
    "app_id": "547",
    "business_phone": "xxx",
    "channel": 2,
    "merchant_phone": "xxx",
    "messaging_product": "whatsapp",
    "metadata": {
        "display_phone_number": "xxx",
        "phone_number_id": "xxx"
    },
    "statuses": [
        {
            "errors": [
                {
                    "code": 131053,
                    "title": "Media upload error"
                }
            ],
            "id": "wamid.40ab29af312f4f8b8ba96c231d55a96e",
            "meta_message_id": "wamid.HBgLNDg2Njk5Njk4ODUVAgARGBJDQUNDQkQ2QTg4NjA1MEQxRUEA",
            "recipient_id": "xxx",
            "recipient_user_id": "US.13491208655302741918",
            "parent_recipient_user_id": "US.ENT.506847293015824",
            "status": "failed",
            "timestamp": "1754379976"
        }
    ],
    "wabaId": "xxx"
}

{
    "app_id": "456",
    "business_phone": "xxx",
    "channel": 2,
    "merchant_phone": "xxx",
    "messaging_product": "whatsapp",
    "metadata": {
        "display_phone_number": "xxx",
        "phone_number_id": "xxx"
    },
    "statuses": [
        {
            "errors": [
                {
                    "code": 131047,
                    "href": "https://developers.facebook.com/docs/whatsapp/cloud-api/support/error-codes/",
                    "title": "Re-engagement message"
                }
            ],
            "id": "wamid.084034bfd79e42d1b97dc387c4abbcd0",
            "meta_message_id": "wamid.HBgLNjAxOTg1NTg5OTMVAgARGBI4RDFFMTM0MEE0MkUwNDdFM0QA",
            "recipient_id": "xxx",
            "recipient_user_id": "US.13491208655302741918",
            "parent_recipient_user_id": "US.ENT.506847293015824",
            "status": "failed",
            "timestamp": "1754380547"
        }
    ],
    "wabaId": "xxx"
}

消息回复 [上行消息用户发送消息给商户]

对WhatsApp用户发送消息到商户号码的场景，提供入站消息的推送情况

响应参数

body参数：

参数名	类型	说明
contacts	array[contact Object]	提供联系人的信息
messages	array[message Object]	入站消息
business_phone	String	商户电话
messaging_product	String	消息类型，固定值”whatsapp“

contact object参数：

参数名	类型	说明
profile	Object	配置文件对象
wa_id	String	用户的电话号码【用户采用匿名化后，该字段可能没有值】
user_id	String	设置为用户的 BSUID。
parent_user_id	String	如果您已启用父级 BSUID，会被设为用户的父级 BSUID。否则，这会被省略。

profile object参数：

参数名	类型	说明
name	String	值将设为 WhatsApp 用户的显示名。
username	String	如果用户已启用匿名化功能，将设置为 WhatsApp 用户的匿名账户。用户未启用匿名化功能的情况，此属性将被完全省略

message object参数：

参数名	类型	说明
from	String	用户的电话号码【用户采用匿名化后，该字段可能没有值】
from_user_id	String	设置为用户的 BSUID
from_parent_user_id	String	如果您已启用父级 BSUID，则设为用户的父级 BSUID。否则，这会被省略。
id	String	消息标识，此 ID 可用于将消息标记为已读
timestamp	String	消息接收时间戳
type	String	支持接收的消息类型 1. text 文本 2. image 图片 3. video 视频 4. voice 语音 5. audio 音频 6. document 文件 7. location 位置 8. sticker 贴图表情 9. interactive 互动消息 10. order 下单消息 11. referral 被广告引流来的客户消息 12. reaction 心情消息 13. button 按钮 14. 引用context 15. system 系统消息 16. edit 编辑消息 17. revoke 删除消息 18. contacts 联系人
context	Object	仅在用户回复或与您的消息之一互动时存在
cost	Object	费用信息

cost object参数:

参数名	类型	说明
currency	String	币种
foreign_price	number	客户售价
cdr_type	Integer	cdr类型，4营销 5通知 6验证 7服务 8广告推广这五个类型
message_id	String	wa消息id
direction	Integer	方向，1（下行），2（上行）

消息类型

文本消息参数：

参数名	类型	说明
text	Object	参照响应示例文本消息内容，type=text时有值

text object参数：

参数名	类型	说明
body	String	消息文本

图片消息参数：

参数名	类型	说明
image	JsonObject	参照响应示例图片消息内容，type=image时有值

image object参数：

参数名	类型	说明
id	String	媒体存储的id，可用于获取媒体链接，Webhook 中的影音内容编号会在 7 天后过期。
caption	String	图片的描述
mime_type	String	媒体文件的MiME类型
sha256	String	媒体文件的校验签名
link	String	媒体文件的url,有效期48小时

视频消息参数：

参数名	类型	说明
video	JsonObject	参照响应示例视频消息内容，type=video时有值

video object参数：

参数名	类型	说明
id	String	媒体存储的id，可用于获取媒体链接，Webhook 中的影音内容编号会在 7 天后过期。
caption	String	视频的描述
mime_type	String	媒体文件的MiME类型
sha256	String	媒体文件的校验签名
link	String	媒体文件的url,有效期48小时

语音消息参数：

参数名	类型	说明
voice	JsonObject	参照响应示例语音消息内容，type=voice时有值

voice object参数：

参数名	类型	说明
id	String	媒体存储的id，可用于获取媒体链接，Webhook 中的影音内容编号会在 7 天后过期。
mime_type	String	媒体文件的MiME类型
sha256	String	媒体文件的校验签名
link	String	媒体文件的url,有效期48小时

音频消息参数：

参数名	类型	说明
audio	JsonObject	参照响应示例音频消息内容，type=audio时有值

audio object参数：

参数名	类型	说明
id	String	媒体存储的id，可用于获取媒体链接，Webhook 中的影音内容编号会在 7 天后过期。
mime_type	String	媒体文件的MiME类型
sha256	String	媒体文件的校验签名
link	String	媒体文件的url,有效期48小时

文档消息参数：

参数名	类型	说明
document	JsonObject	参照响应示例文档消息内容，type=document时有值

document object参数：

参数名	类型	说明
id	String	媒体存储的id，可用于获取媒体链接，Webhook 中的影音内容编号会在 7 天后过期。
mime_type	String	媒体文件的MiME类型
sha256	String	媒体文件的校验签名
filename	String	文档文件名称

位置消息参数：

参数名	类型	说明
location	JsonObject	参照响应示例位置消息内容，type=location时有值

location object参数：

参数名	类型	说明
longitude	String	位置的经度信息
latitude	String	位置的维度信息
name	String	位置的名称
address	String	位置的详细地址信息

贴图表情消息参数：

参数名	类型	说明
sticker	JsonObject	参照响应示例贴图表情消息内容，type=sticker时有值

sticker object参数：

参数名	类型	说明
id	String	媒体存储的id，可用于获取媒体链接
link	String	媒体文件的url,有效期48小时

互动消息参数：

参数名	类型	说明
interactive	Object	参照响应示例1 参照响应示例2 type=interactive时有值

interactive object参数：

参数名	类型	说明
type	String	button_reply (按钮回复) list_reply（列表回复） nfm_reply（表单提交）
button_reply	Object	当用户点击按钮时发送，具有该属性的对象。
list_reply	Object	当用户从列表中选择一个项目时发送，具有该属性的对象。
nfm_reply	Object	当用户表单提交，具有该属性的对象。
call_permission_reply	Object	当用户点击通话权限申请反馈，具有该属性的对象。

button_reply 或者 list_reply object参数：

参数名	类型	说明
id	String	按钮id
title	String	标题
description	String	选项描述，list_reply才有

nfm_reply object参数：

参数名	类型	说明
name	String	固定为 flow
body	String	消息提交后的文案
response_json	String	flow的json数据. The structure is either defined in flow JSON ([see Complete action]

call_permission_reply object参数：

参数名	类型	说明
expiration_timestamp	Long	通话权限过期时间戳
response	String	accept/reject 接受/拒绝
response_source	String	user_action/automatic 用户反馈/系统反馈

下单消息参数：

参数名	类型	说明
order	Object	参照响应示例 type=order时有值

order object参数：

参数名	类型	说明
catalog_id	String	目录id
text	String	当客户点击按钮时发送，具有该属性的对象。
product_items	Array[Object]	当客户从列表中选择一个项目时发送，具有该属性的对象。

product_items object参数：

参数名	类型	说明
product_retailer_id	String	目录中产品的唯一标识符
quantity	Number	物品数量
item_price	Number	每个物品的价格
currency	String	货币类型

广告引入客户的消息参数：

参数名	类型	说明
referral	Object	消息响应示例当客户点击一个广告且该广告将他们重定向到WhatsApp时，此对象会包含在消息对象中

referral object参数：

参数名	类型	说明
source_url	String	指向客户点击的广告或帖子的Meta URL。打开这个URL将会看到客户视角的广告
source_type	String	广告或帖子的Meta ID
headline	String	广告或帖子中使用的标题
body	String	广告或帖子的正文
media_type	String	广告或帖子中存在的媒体类型；图片或视频
image_url	String	当媒体类型为图片时的图片URL
video_url	String	当媒体类型为视频时的视频URL
thumbnail_url	String	当媒体类型为视频时的缩略图URL
ctwa_clid	String	由Meta为点击至WhatsApp的广告生成的点击ID

reaction消息参数：

参数名	类型	必选	示例值	说明
reaction	Object	否	参照请求示例	心情消息内容，type=reaction必填

reaction object参数：

参数名	类型	必选	示例值	说明
meta_message_id	String	是	-	meta消息id
message_id	String	是	-	消息回复id,例如:wamid.HBgNODYxMzE2MzczMTQ2NxUCABIYEkVCQkE4NjdGRUE5RDgyQzg0RAA=
emoji	String	是	-	表情例如:"❤️"

button object 参数:

参数名	类型	说明
text	String	按钮预设文本
payload	String	不可见特殊字符串

context 引用消息参数：

参数名	类型	说明
context	Object	商品消息响应示例引用消息响应示例仅在用户回复或与您的消息之一互动时存在

context object参数：

参数名	类型	说明
from	String	被引用消息来源号码
id	String	消息id
meta_message_id	String	meta消息id(不一定存在)
forwarded	Boolean	如果商家收到的该消息已被转发，则设置为true
frequently_forwarded	Boolean	如果商家收到的该消息已被转发超过5次，则设置为true。
referred_product	Object	引用回复商品消息时含有该对象

referred_product object参数：

参数名	类型	说明
catalog_id	String	目录id
product_retailer_id	String	目录中产品的唯一标识符

system object参数：

参数名	类型	说明
body	String	如果用户更改了其业务电话号码，将设置为 User <WHATSAPP_USER_PROFILE_NAME> changed from <OLD_BSUID> to <NEW_BSUID>
wa_id	String	用户的电话号码【用户采用匿名化后，该字段可能没有值】
user_id	String	将设置为用户的新 BSUID。
parent_user_id	String	如果您已启用父级 BSUID，此属性会被设为用户的父级BSUID。否则，该属性会被完全省略
type	String	如果 WhatsApp 用户更改了其电话号码，此属性将设为 user_changed_user_id。

contacts Object参数: | 参数名 | 类型 | 说明 | | ------------- | ------ | ------------------------------------------------------------ | | name | Object | 联系人名称信息 | | origin | String | 来源 contact_request — 用户通过轻触 REQUEST_CONTACT_INFO 按钮分享了联系方式。 other — 用户直接在聊天中（而非通过 REQUEST_CONTACT_INFO 按钮）分享联系方式。 | | phones | Array[Object] | 联系人号码信息 |

name Object

参数名	类型	说明
first_name	String	联系人首部名称
formatted_name	String	联系人完整名称
last_name	String	联系人尾部名称
middle_name	String	联系人中部名称

phones Arrary[Object] 参数:

参数名	类型	说明
phone	String	格式化号码
type	String	号码类型 cell, mobile, main, iPhone, home, work等
wa_id	String	号码

匿名化相关字段补充说明

响应示例

文本消息响应示例【可获得用户手机号】

{
  "contacts": [
    {
      "profile": {
        "name": "Jay",
        "username": "@realsheenanelson"
      },
      "wa_id": "852xxxx705",
      "user_id": "uUS.13491208655302741918",
      "parent_user_id": "US.11815799212886844830"
    }
  ],
  "messages": [
    {
      "from": "852xxxx705",
      "from_user_id": "US.13491208655302741918",
      "from_parent_user_id": "US.ENT.506847293015824",
      "id": "ABGHhhdgYFCBnwIQNkLO2ipL1_ZpZ41mwgMHEg",
      "text": {
        "body": "你好"
      },
      "timestamp": "1663053831",
      "type": "text",
      "cost": {
                "currency": "USD",
                "foreign_price": 0,
                "cdr_type": 4,
                "message_id": "ABGHhhdgYFCBnwIQNkLO2ipL1_ZpZ41mwgMHEg",
                "direction": 1
            }
    }
  ],
  "merchant_phone": "86176xxxx0819",
  "messaging_product": "whatsapp"
}

文本消息响应示例【不可获得用户手机号】

{
  "contacts": [
    {
      "profile": {
        "name": "Jay",
        "username": "@realsheenanelson"
      },
      "user_id": "uUS.13491208655302741918",
      "parent_user_id": "US.11815799212886844830"
    }
  ],
  "messages": [
    {
      "from_user_id": "US.13491208655302741918",
      "from_parent_user_id": "US.ENT.506847293015824",
      "id": "ABGHhhdgYFCBnwIQNkLO2ipL1_ZpZ41mwgMHEg",
      "text": {
        "body": "你好"
      },
      "timestamp": "1663053831",
      "type": "text",
      "cost": {
                "currency": "USD",
                "foreign_price": 0,
                "cdr_type": 4,
                "message_id": "ABGHhhdgYFCBnwIQNkLO2ipL1_ZpZ41mwgMHEg",
                "direction": 1
            }
    }
  ],
  "merchant_phone": "86176xxxx0819",
  "messaging_product": "whatsapp"
}

图片消息响应示例

{
  "contacts": [
    {
      "profile": {
        "name": "Jay",
        "username": "@realsheenanelson"
      },
      "wa_id": "852xxxx705",
      "user_id": "uUS.13491208655302741918",
      "parent_user_id": "US.11815799212886844830"
    }
  ],
  "messages": [
    {
      "from": "852xxxx705",
      "from_user_id": "US.13491208655302741918",
      "from_parent_user_id": "US.ENT.506847293015824",
      "id": "ABGHhhdgYFCBnwIQk5kC-xMSoi3XpEwoF2ZkIg",
      "image": {
        "id": "2bc7102f-5491-40b1-a92f-338303eab9d3",
        "mime_type": "image/jpeg",
        "sha256": "0ed3d9d4db83ed7751314af5f2e9bf008edc49a101bebb9054a97f824cf2136b",
        "link": "https://dd.xx"
      },
      "timestamp": "1663053029",
      "type": "image",
      "cost": {
                "currency": "USD",
                "foreign_price": 0,
                "cdr_type": 4,
                "message_id": "ABGHhhdgYFCBnwIQk5kC-xMSoi3XpEwoF2ZkIg",
                "direction": 1
            }
    }
  ],
  "merchant_phone": "86176xxxx0819",
  "messaging_product": "whatsapp"
}

视频消息响应示例

{
  "contacts": [
    {
      "profile": {
        "name": "Jay",
        "username": "@realsheenanelson"
      },
      "wa_id": "852xxxx705",
      "user_id": "uUS.13491208655302741918",
      "parent_user_id": "US.11815799212886844830"
    }
  ],
  "messages": [
    {
      "from": "852xxxx705",
      "from_user_id": "US.13491208655302741918",
      "from_parent_user_id": "US.ENT.506847293015824",
      "id": "ABGHhhdgYFCBnwIQysyxXFholwoQ-lCwUTTWfw",
      "timestamp": "1663054466",
      "type": "video",
      "video": {
        "id": "bfc0619d-995e-49da-9869-e911a34c43b9",
        "mime_type": "video/mp4",
        "sha256": "e0ceec95f44fec6282ab02f947ee92dbe481dacf0478618a997580a822acc88b",
        "link": "https://dd.xx"
      },
      "cost": {
        "currency": "USD",
        "foreign_price": 0,
        "cdr_type": 4,
        "message_id": "ABGHhhdgYFCBnwIQysyxXFholwoQ-lCwUTTWfw",
        "direction": 1
      }
    }
  ],
  "merchant_phone": "86176xxxx0819",
  "messaging_product": "whatsapp"
}

语音消息响应示例

{
  "contacts": [
    {
      "profile": {
        "name": "Jay",
        "username": "@realsheenanelson"
      },
      "wa_id": "852xxxx705",
      "user_id": "uUS.13491208655302741918",
      "parent_user_id": "US.11815799212886844830"
    }
  ],
  "messages": [
    {
      "from": "852xxxx705",
      "from_user_id": "US.13491208655302741918",
      "from_parent_user_id": "US.ENT.506847293015824",
      "id": "ABGHhhdgYFCBnwIQyrJn0a5IBKlmHZqf_uAuFw",
      "timestamp": "1663055136",
      "type": "voice",
      "voice": {
        "id": "25fdf335-d846-4e6c-9aa8-35f25abc564c",
        "mime_type": "audio/ogg; codecs=opus",
        "sha256": "f321ac774459c50e376048d6f2c02fc2c14f13be85c5e52a67ec16a358b34de7",
        "link": "https://dd.xx"
      },
      "cost": {
        "currency": "USD",
        "foreign_price": 0,
        "cdr_type": 4,
        "message_id": "ABGHhhdgYFCBnwIQyrJn0a5IBKlmHZqf_uAuFw",
        "direction": 1
      }
    }
  ],
  "merchant_phone": "86176xxxx0819",
  "messaging_product": "whatsapp"
}

音频消息响应示例

{
  "contacts": [
    {
      "profile": {
        "name": "Jay",
        "username": "@realsheenanelson"
      },
      "wa_id": "852xxxx705",
      "user_id": "uUS.13491208655302741918",
      "parent_user_id": "US.11815799212886844830"
    }
  ],
  "messages": [
    {
      "audio": {
        "id": "aab95384-fc19-4136-a330-97e1f8a4cb02",
        "mime_type": "audio/mpeg",
        "sha256": "9a73ab6362694fba48a5027c8443ceb34838009601ce480d85f08c600cf520f1",
        "link": "https://dd.xx"
      },
      "from": "852xxxx705",
      "from_user_id": "US.13491208655302741918",
      "from_parent_user_id": "US.ENT.506847293015824",
      "id": "ABGHhhdgYFCBnwIQdSLi6R7UCDSsCqNkjrtczg",
      "timestamp": "1663053098",
      "type": "audio",
      "cost": {
        "currency": "USD",
        "foreign_price": 0,
        "cdr_type": 4,
        "message_id": "ABGHhhdgYFCBnwIQdSLi6R7UCDSsCqNkjrtczg",
        "direction": 1
      }
    }
  ],
  "merchant_phone": "86176xxxx819",
  "messaging_product": "whatsapp"
}

文档消息响应示例

{
  "contacts": [
    {
      "profile": {
        "name": "Jay",
        "username": "@realsheenanelson"
      },
      "wa_id": "852xxxx705",
      "user_id": "uUS.13491208655302741918",
      "parent_user_id": "US.11815799212886844830"
    }
  ],
  "messages": [
    {
      "document": {
        "caption": "null.txt",
        "filename": "null.txt",
        "id": "806bb2f3-d8cc-4477-8b4d-d89df862f6c0",
        "mime_type": "text/plain",
        "sha256": "90c7bd7c509aa1d68c09a67b9ba2d17022a6861681fbd75c8845ee48193e8646",
        "link": "https://dd.xx"
      },
      "from": "852xxxx705",
      "from_user_id": "US.13491208655302741918",
      "from_parent_user_id": "US.ENT.506847293015824",
      "id": "ABGHhhdgYFCBnwIQGvyQjDNptdnjvjN0dkD90Q",
      "timestamp": "1663052759",
      "type": "document",
      "cost": {
        "currency": "USD",
        "foreign_price": 0,
        "cdr_type": 4,
        "message_id": "ABGHhhdgYFCBnwIQGvyQjDNptdnjvjN0dkD90Q",
        "direction": 1
      }
    }
  ],
  "merchant_phone": "86176xxxx0819",
  "messaging_product": "whatsapp"
}

位置消息响应示例

{
  "contacts": [
    {
      "profile": {
        "name": "Jay",
        "username": "@realsheenanelson"
      },
      "wa_id": "852xxxx705",
      "user_id": "uUS.13491208655302741918",
      "parent_user_id": "US.11815799212886844830"
    }
  ],
  "messages": [
    {
      "from": "852xxxx705",
      "from_user_id": "US.13491208655302741918",
      "from_parent_user_id": "US.ENT.506847293015824",
      "id": "ABGHhhdgYFCBnwIQO8HTCPOtJUZLNLRo2dPufw",
      "location": {
        "address": "深圳市, 广东",
        "latitude": 22.550802897696343,
        "longitude": 113.93844723701477,
        "name": "KFC (肯德基)",
        "url": "http://www.kfc.com.cn"
      },
      "timestamp": "1663053163",
      "type": "location",
      "cost": {
        "currency": "USD",
        "foreign_price": 0,
        "cdr_type": 4,
        "message_id": "ABGHhhdgYFCBnwIQO8HTCPOtJUZLNLRo2dPufw",
        "direction": 1
      }
    }
  ],
  "merchant_phone": "86176xxxx0819",
  "messaging_product": "whatsapp"
}

贴图表情消息响应示例

{
  "contacts": [
    {
      "profile": {
        "name": "Jay",
        "username": "@realsheenanelson"
      },
      "wa_id": "852xxxx705",
      "user_id": "uUS.13491208655302741918",
      "parent_user_id": "US.11815799212886844830"
    }
  ],
  "messages": [
    {
      "from": "852xxxx705",
      "from_user_id": "US.13491208655302741918",
      "from_parent_user_id": "US.ENT.506847293015824",
      "id": "ABGHhhdgYFCBnwIQ1kuKFSU5LfuDxSUPOjKIwA",
      "sticker": {
        "id": "1b0a4c77-c5e7-44fa-b2a3-b69941ed3c64",
        "metadata": {
          "emojis": [
            "☕",
            "🙂"
          ],
          "is-first-party-sticker": 1,
          "sticker-pack-id": "whatsappcuppy"
        },
        "mime_type": "image/webp",
        "sha256": "98267fedaeac67a4cc6b5e18a2444249fba5b6363a690115139675d53a63b0ff",
        "link": "https://dd.xx"
      },
      "timestamp": "1663054803",
      "type": "sticker",
      "cost": {
        "currency": "USD",
        "foreign_price": 0,
        "cdr_type": 4,
        "message_id": "ABGHhhdgYFCBnwIQ1kuKFSU5LfuDxSUPOjKIwA",
        "direction": 1
      }
    }
  ],
  "merchant_phone": "86176xxxx0819",
  "messaging_product": "whatsapp"
}

互动消息快速回复响应示例

{
  "contacts": [
    {
      "profile": {
        "name": "Jay",
        "username": "@realsheenanelson"
      },
      "wa_id": "852xxxx705",
      "user_id": "uUS.13491208655302741918",
      "parent_user_id": "US.11815799212886844830"
    }
  ],
  "messages": [
    {
      "context": {
        "from": "86176xxxx0819",
        "id": "wamid.HBgLODUyNTUzMTE3MDUVAgARGBJDNDI1ODA3QzE0NkEwMUY1NjQA"
      },
      "from": "852xxxx705",
      "from_user_id": "US.13491208655302741918",
      "from_parent_user_id": "US.ENT.506847293015824",
      "id": "wamid.HBgLODUyNTUzMTE3MDUVAgASGBQzQTc1OEVGOEFBQ0U4QkIwNzFCOQA=",
      "timestamp": "1701849537",
      "type": "interactive",
      "interactive": {
        "type": "button_reply",
        "button_reply": {
          "id": "2",
          "title": "不愿意"
        }
      },
      "cost": {
        "currency": "CNY",
        "foreign_price": 0,
        "cdr_type": 1,
        "message_id": "wamid.HBgLODUyNTUzMTE3MDUVAgASGBQzQTc1OEVGOEFBQ0U4QkIwNzFCOQA=",
        "direction": 2
      }
    }
  ],
  "merchant_phone": "86176xxxx0819",
  "messaging_product": "whatsapp"
}

互动消息列表响应示例

{
  "contacts": [
    {
      "profile": {
        "name": "Jay",
        "username": "@realsheenanelson"
      },
      "wa_id": "852xxxx705",
      "user_id": "uUS.13491208655302741918",
      "parent_user_id": "US.11815799212886844830"
    }
  ],
  "messages": [
    {
      "context": {
        "from": "86176xxxx0819",
        "id": "wamid.HBgLODUyNTUzMTE3MDUVAgARGBI2NDFBRDA4NzcyOUU3NUJDODIA"
      },
      "from": "852xxxx705",
      "from_user_id": "US.13491208655302741918",
      "from_parent_user_id": "US.ENT.506847293015824",
      "id": "wamid.HBgLODUyNTUzMTE3MDUVAgASGBQzQUVGMzA0MDM0QUZGRUJGOTRCMgA=",
      "timestamp": "1701850329",
      "type": "interactive",
      "interactive": {
        "type": "list_reply",
        "list_reply": {
          "id": "2",
          "title": "牛肉面",
          "description": "红烧牛肉面"
        }
      },
      "cost": {
        "currency": "CNY",
        "foreign_price": 0,
        "cdr_type": 1,
        "message_id": "wamid.HBgLODUyNTUzMTE3MDUVAgASGBQzQUVGMzA0MDM0QUZGRUJGOTRCMgA=",
        "direction": 2
      }
    }
  ],
  "merchant_phone": "86176xxxx0819",
  "messaging_product": "whatsapp"
}

商品消息响应示例

{
  "contacts": [
    {
      "profile": {
        "name": "Jay",
        "username": "@realsheenanelson"
      },
      "wa_id": "852xxxx705",
      "user_id": "uUS.13491208655302741918",
      "parent_user_id": "US.11815799212886844830"
    }
  ],
  "messages": [
    {
      "context": {
        "from": "86176xxxx0819",
        "id": "wamid.HBgLODUyNTUzMTE3MDUVAgARGA9wcm9kdWN0X2lucXVpcnkA",
        "referred_product": {
          "catalog_id": "310639698193384",
          "product_retailer_id": "qnp7xflxk9"
        }
      },
      "from": "852xxxx705",
      "from_user_id": "US.13491208655302741918",
      "from_parent_user_id": "US.ENT.506847293015824",
      "id": "wamid.HBgLODUyNTUzMTE3MDUVAgASGBQzQTQ0MEI2Rjc4MURCM0VFOTQwMwA=",
      "timestamp": "1701846846",
      "type": "text",
      "text": {
        "body": "我想要"
      },
      "cost": {
        "currency": "CNY",
        "foreign_price": 0,
        "cdr_type": 1,
        "message_id": "wamid.HBgLODUyNTUzMTE3MDUVAgASGBQzQTQ0MEI2Rjc4MURCM0VFOTQwMwA=",
        "direction": 2
      }
    }
  ],
  "merchant_phone": "86176xxxx0819",
  "messaging_product": "whatsapp"
}

下单消息响应示例

{
  "contacts": [
    {
      "profile": {
        "name": "Jay",
        "username": "@realsheenanelson"
      },
      "wa_id": "852xxxx705",
      "user_id": "uUS.13491208655302741918",
      "parent_user_id": "US.11815799212886844830"
    }
  ],
  "messages": [
    {
      "from": "852xxxx705",
      "from_user_id": "US.13491208655302741918",
      "from_parent_user_id": "US.ENT.506847293015824",
      "id": "wamid.HBgLODUyNTUzMTE3MDUVAgASGBQzQTJEQ0M5MEM0OURFNjZDQjY0MQA=",
      "timestamp": "1701847162",
      "type": "order",
      "order": {
        "catalog_id": "310639698193384",
        "text": "",
        "product_items": [
          {
            "product_retailer_id": "h0v6snwgg6",
            "quantity": 1.0,
            "item_price": 124.0,
            "currency": "CNY"
          },
          {
            "product_retailer_id": "qnp7xflxk9",
            "quantity": 1.0,
            "item_price": 1000.0,
            "currency": "CNY"
          }
        ]
      },
      "cost": {
        "currency": "CNY",
        "foreign_price": 0,
        "cdr_type": 1,
        "message_id": "wamid.HBgLODUyNTUzMTE3MDUVAgASGBQzQTJEQ0M5MEM0OURFNjZDQjY0MQA=",
        "direction": 2
      }
    }
  ],
  "merchant_phone": "86176xxxx0819",
  "messaging_product": "whatsapp"
}

flow表单提交消息响应示例

{
  "contacts": [
    {
      "profile": {
        "name": "Jay",
        "username": "@realsheenanelson"
      },
      "wa_id": "852xxxx705",
      "user_id": "uUS.13491208655302741918",
      "parent_user_id": "US.11815799212886844830"
    }
  ],
  "messages": [
    {
      "context": {
        "from": "86176xxxx0819",
        "id": "wamid.HBgLODUyNTUzMTE3MDUVAgARGBJFRjIzOTZGNDhBOTRCQTIzNjcA"
      },
      "from": "852xxxx705",
      "from_user_id": "US.13491208655302741918",
      "from_parent_user_id": "US.ENT.506847293015824",
      "id": "wamid.HBgLODUyNTUzMTE3MDUVAgASGBQzQTkxRUFCRTc2QjJBRTZBQ0ZEMwA=",
      "timestamp": "1701847428",
      "type": "interactive",
      "interactive": {
        "type": "nfm_reply",
        "nfm_reply": {
          "response_json": "{\"screen_0_RadioButtonsGroup_0\":\"0_10分\",\"flow_token\":\"AQAAAAACS5FpgQ_cAAAAAD0QI3s\",\"screen_0_TextInput_1\":\"好评，满意\"}",
          "body": "已发送",
          "name": "flow"
        }
      },
      "cost": {
        "currency": "CNY",
        "foreign_price": 0,
        "cdr_type": 1,
        "message_id": "wamid.HBgLODUyNTUzMTE3MDUVAgASGBQzQTkxRUFCRTc2QjJBRTZBQ0ZEMwA=",
        "direction": 2
      }
    }
  ],
  "merchant_phone": "86176xxxx0819",
  "messaging_product": "whatsapp"
}

广告引入客户的消息响应示例

{
  "contacts": [
    {
      "profile": {
        "name": "Jay",
        "username": "@realsheenanelson"
      },
      "wa_id": "852xxxx705",
      "user_id": "uUS.13491208655302741918",
      "parent_user_id": "US.11815799212886844830"
    }
  ],
  "messages": [
    {
      "from": "852xxxx705",
      "from_user_id": "US.13491208655302741918",
      "from_parent_user_id": "US.ENT.506847293015824",
      "id": "wamid.HBgNODYxMzE2MzczMTQ2NxUCABIYIDM3REYzQUZEMzQ5MDY1RkYxQjg4NEY0NURBMjg3QUIxAA==",
      "timestamp": "1700222189",
      "type": "text",
      "text": {
        "body": "您好，我想多了解一些信息。"
      },
      "referral": {
        "headline": "与我们聊天",
        "source_type": "ad",
        "source_id": "120200744305620497",
        "source_url": "https://fb.me/6cf1tN8rT"
      },
      "cost": {
        "currency": "USD",
        "foreign_price": 0,
        "cdr_type": 1,
        "message_id": "wamid.HBgNODYxMzE2MzczMTQ2NxUCABIYIDM3REYzQUZEMzQ5MDY1RkYxQjg4NEY0NURBMjg3QUIxAA==",
        "direction": 2
      }
    }
  ],
  "merchant_phone": "86176xxxx0819",
  "messaging_product": "whatsapp"
}

引用消息响应示例

{
  "contacts": [
    {
      "profile": {
        "name": "Jay",
        "username": "@realsheenanelson"
      },
      "wa_id": "852xxxx705",
      "user_id": "uUS.13491208655302741918",
      "parent_user_id": "US.11815799212886844830"
    }
  ],
  "messages": [
    {
      "context": {
        "from": "86176xxxx0819",
        "id": "wamid.d148508dce0149c9aca912ea6fb6035d",
        "meta_message_id": "wamid.HBgLODUyNTUzMTE3MDUVAgARGBI3NEZGOTg5NDc5RkExRjg2RjUA"
      },
      "from": "85255311705",
      "from_user_id": "US.13491208655302741918",
      "from_parent_user_id": "US.ENT.506847293015824",
      "id": "wamid.HBgLODUyNTUzMTE3MDUVAgASGBQzQTkwNDhEMDQ0MEY2QzA1NDE4OAA=",
      "timestamp": "1701856516",
      "type": "text",
      "text": {
        "body": "OK you"
      },
      "cost": {
        "currency": "CNY",
        "foreign_price": 0,
        "cdr_type": 1,
        "message_id": "wamid.HBgLODUyNTUzMTE3MDUVAgASGBQzQTkwNDhEMDQ0MEY2QzA1NDE4OAA=",
        "direction": 2
      }
    }
  ],
  "merchant_phone": "86176xxxx0819",
  "messaging_product": "whatsapp"
}

WhatsAppBusinessAPI账号不支持的消息响应示例

{
  "contacts": [
    {
      "profile": {
        "name": "Jay",
        "username": "@realsheenanelson"
      },
      "wa_id": "852xxxx705",
      "user_id": "uUS.13491208655302741918",
      "parent_user_id": "US.11815799212886844830"
    }
  ],
  "messages": [
    {
      "from": "852xxxx705",
      "from_user_id": "US.13491208655302741918",
      "from_parent_user_id": "US.ENT.506847293015824",
      "id": "wamid.HBgLODUyNTUzMTE3MDUVAgASGBQzQUY3OTA5Mzg5MDU2NDU5RDg4NgA=",
      "timestamp": "1701861490",
      "type": "unsupported",
      "errors": [
        {
          "code": 131051,
          "title": "Message type is currently not supported."
        }
      ],
      "cost": {
        "currency": "CNY",
        "foreign_price": 0,
        "cdr_type": 1,
        "message_id": "wamid.HBgLODUyNTUzMTE3MDUVAgASGBQzQUY3OTA5Mzg5MDU2NDU5RDg4NgA=",
        "direction": 2
      }
    }
  ],
  "merchant_phone": "86176xxxx0819",
  "messaging_product": "whatsapp"
}

心情消息示例

{
  "messaging_product": "whatsapp",
  "contacts": [
    {
      "wa_id": "8617xxxx50819",
      "profile": {
        "name": "Jay",
        "username": "@realsheenanelson"
      },
      "user_id": "uUS.13491208655302741918",
      "parent_user_id": "US.11815799212886844830"
    }
  ],
  "messages": [
    {
      "from": "8617xxxx50819",
      "from_user_id": "US.13491208655302741918",
      "from_parent_user_id": "US.ENT.506847293015824",
      "id": "wamid.HBgNODYxNzYwNjA1MDgxORUCABISVASBMzBDMjVFNkIxRUFGMzAzNTREAA==",
      "timestamp": "1724118060",
      "type": "reaction",
      "reaction": {
        "message_id": "wamid.4092fc1a7877448f8ec8c8d2216dfdd4",
        "meta_message_id": "wamid.HBgNODYxNzYwNjA1MDgxORUCABISVASBMzBDMjVFNkIxRUFGMzAzNTREAA=",
        "emoji": "👍"
      },
      "cost": {
        "currency": "CNY",
        "foreign_price": 0,
        "cdr_type": 1,
        "message_id": "wamid.HBgNODYxNzYwNjA1MDgxORUCABISVASBMzBDMjVFNkIxRUFGMzAzNTREAA==",
        "direction": 2
      }
    }
  ],
  "metadata": {
    "display_phone_number": "8523xxxx859",
    "phone_number_id": "12487xxxxx14609"
  },
  "app_id": "48",
  "business_phone": "8523xxxx859",
  "merchant_phone": "8523xxxx859",
  "channel": 2
}

互动消息-通话权限申请反馈示例

{
  "app_id": "48",
  "business_phone": "xxx",
  "channel": 2,
  "contacts": [
    {
      "profile": {
        "name": "xxx",
        "username": "@realsheenanelson"
      },
      "wa_id": "xxx",
      "user_id": "uUS.13491208655302741918",
      "parent_user_id": "US.11815799212886844830"
    }
  ],
  "merchant_phone": "xxx",
  "messages": [
    {
      "context": {
        "from": "xxx",
        "id": "wamid.3a5d01a5b5ce49279f3dcb9c3bd6341a",
        "meta_message_id": "wamid.HBgNODYxMzMyMDIzNzQ0NhUCABEYEkM3NUFFOUY4MDQ4Q0NCQUIzNQA="
      },
      "cost": {
        "cdr_type": 1,
        "currency": "USD",
        "direction": 2,
        "foreign_price": 0,
        "message_id": "wamid.HBgNODYxMzMyMDIzNzQ0NhUCABIYFDNBNUNEQjFBQURBRTk4OTY3REE5AA=="
      },
      "from": "xxx",
      "from_user_id": "US.13491208655302741918",
      "from_parent_user_id": "US.ENT.506847293015824",
      "id": "wamid.HBgNODYxMzMyMDIzNzQ0NhUCABIYFDNBNUNEQjFBQURBRTk4OTY3REE5AA==",
      "interactive": {
        "call_permission_reply": {
          "expiration_timestamp": 1756452996,
          "response": "accept",
          "response_source": "user_action"
        },
        "type": "call_permission_reply"
      },
      "timestamp": "1755848199",
      "type": "interactive"
    }
  ],
  "messaging_product": "whatsapp",
  "metadata": {
    "display_phone_number": "xxx",
    "phone_number_id": "xxx"
  },
  "wabaId": "xxx"
}

ctwa_clid

{
    "app_id": "1247",
    "business_phone": "xxx",
    "channel": 2,
    "contacts": [
        {
            "profile": {
                "name": "xx"
            },
            "wa_id": "xxx"
        }
    ],
    "merchant_phone": "xxx",
    "messages": [
        {
            "cost": {
                "cdr_type": 1,
                "currency": "CNY",
                "direction": 2,
                "foreign_price": 0,
                "message_id": "wamid.HBgLODUyOTA1NjE2NDcVAgASGCBBQ0JGMUI5NzVBQkE5MzY4NkVEMDM3Q0I2QTQ4NTU0OQA=",
                "price": 0
            },
            "from": "xxx",
            "id": "wamid.HBgLODUyOTA1NjE2NDcVAgASGCBBQ0JGMUI5NzVBQkE5MzY4NkVEMDM3Q0I2QTQ4NTU0OQA=",
            "referral": {
                "source_url": "https://fb.me/xxx",
                "source_id": "12023493xxx0049",
                "source_type": "ad",
                "body": "🔥",
                "headline": "名額",
                "media_type": "image",
                "image_url": "https://xxx/xxx",
                "ctwa_clid": "Afd-zemhsx0OacUuxxx",
                "welcome_message": {
                    "text": "您好"
                }
            },
            "text": {
                "body": "諮詢"
            },
            "timestamp": "1762334856",
            "type": "text"
        }
    ],
    "messaging_product": "whatsapp",
    "metadata": {
        "display_phone_number": "xxx",
        "phone_number_id": "xxx"
    },
    "wabaId": "xxx"
}

系统消息如果用户更改了其业务电话号码，则将触发系统消息回执

{
    "app_id": "224",
    "business_phone": "xxx",
    "channel": 2,
    "merchant_phone": "xxx",
    "messages": [
        {
            "cost": {
                "cdr_type": 1,
                "currency": "USD",
                "direction": 2,
                "foreign_price": 0,
                "message_id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQUFERjg0NDEzNDdFODU3MUMxMAA=",
                "price": 0
            },
            "from": "xxx",
            "id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQUFERjg0NDEzNDdFODU3MUMxMAA=",
            "system": {
                "body": "User Ooops changed from US.34534546553065465 to  US.13491208655302741918",
                "parent_user_id": "US.ENT.13491208342343918",
                "type": "user_changed_user_id",
                "user_id": "US.13491208655302741918",
                "wa_id": "xxx"
            },
            "timestamp": "1750030073",
            "type": "system"
        }
    ],
    "messaging_product": "whatsapp",
    "metadata": {
        "display_phone_number": "xxx",
        "phone_number_id": "xxx"
    },
    "wabaId": "xxx"
}

删除消息

{
    "app_id": "3205",
    "business_phone": "xxx",
    "channel": 2,
    "contacts": [
        {
            "profile": {
                "name": "xxx"
            },
            "user_id": "CN.1163458429160977",
            "wa_id": "xxx"
        }
    ],
    "merchant_phone": "xxx",
    "messages": [
        {
            "cost": {
                "cdr_type": 1,
                "currency": "EUR",
                "direction": 2,
                "foreign_price": 0,
                "message_id": "wamid.HBgNODYxNTgwNjA0NjI1NBUCABIYIEFDQUM2REI2NjM5QUJCNjZCQ0IyQjBBNzM4OUM0QjBFAA==",
                "price": 0
            },
            "from": "xxx",
            "from_user_id": "CN.1163458429160977",
            "id": "wamid.HBgNODYxNTgwNjA0NjI1NBUCABIYIEFDQUM2REI2NjM5QUJCNjZCQ0IyQjBBNzM4OUM0QjBFAA==",
            "revoke": {
                "original_message_id": "wamid.HBgNODYxNTgwNjA0NjI1NBUCABIYIEFDRDExNkEyNEIyQUVFRkNGRDUwNUU3RjU2ODQ1MjkxAA=="
            },
            "timestamp": "1776307550",
            "type": "revoke"
        }
    ],
    "messaging_product": "whatsapp",
    "metadata": {
        "display_phone_number": "xxx",
        "phone_number_id": "xxx"
    },
    "wabaId": "xxx"
}

编辑后的新消息

{
    "app_id": "3205",
    "business_phone": "xxx",
    "channel": 2,
    "contacts": [
        {
            "profile": {
                "name": "xxx"
            },
            "user_id": "CN.1163458429160977",
            "wa_id": "xxx"
        }
    ],
    "merchant_phone": "xxx",
    "messages": [
        {
            "cost": {
                "cdr_type": 1,
                "currency": "EUR",
                "direction": 2,
                "foreign_price": 0,
                "message_id": "wamid.HBgNODYxNTgwNjA0NjI1NBUCABIYIEFDNTkyQUFBREU2MTFBRjM4QTQ3RDRFMzhBNjA0QUQ4AA==",
                "price": 0
            },
            "edit": {
                "original_message_id": "wamid.HBgNODYxNTgwNjA0NjI1NBUCABIYIEFDRDcyOUIzNUY4NjM2MkNCNTE1NjBCNUVGNDcxNERCAA==",
                "message": {
                    "type": "text",
                    "text": {
                        "body": "Ruuu UU and"
                    }
                }
            },
            "from": "xxx",
            "from_user_id": "CN.1163458429160977",
            "id": "wamid.HBgNODYxNTgwNjA0NjI1NBUCABIYIEFDNTkyQUFBREU2MTFBRjM4QTQ3RDRFMzhBNjA0QUQ4AA==",
            "timestamp": "1776307591",
            "type": "edit"
        }
    ],
    "messaging_product": "whatsapp",
    "metadata": {
        "display_phone_number": "xxx",
        "phone_number_id": "xxx"
    },
    "wabaId": "xxx"
}

编辑前的旧消息

{
    "app_id": "3205",
    "business_phone": "xxx",
    "channel": 2,
    "contacts": [
        {
            "profile": {
                "name": "xxx"
            },
            "user_id": "CN.1163458429160977",
            "wa_id": "xxx"
        }
    ],
    "merchant_phone": "xxx",
    "messages": [
        {
            "cost": {
                "cdr_type": 1,
                "currency": "EUR",
                "direction": 2,
                "foreign_price": 0,
                "message_id": "wamid.HBgNODYxNTgwNjA0NjI1NBUCABIYIEFDRDcyOUIzNUY4NjM2MkNCNTE1NjBCNUVGNDcxNERCAA==",
                "price": 0
            },
            "from": "xxx",
            "from_user_id": "CN.1163458429160977",
            "id": "wamid.HBgNODYxNTgwNjA0NjI1NBUCABIYIEFDRDcyOUIzNUY4NjM2MkNCNTE1NjBCNUVGNDcxNERCAA==",
            "text": {
                "body": "Ruuu"
            },
            "timestamp": "1776307568",
            "type": "text"
        }
    ],
    "messaging_product": "whatsapp",
    "metadata": {
        "display_phone_number": "xxx",
        "phone_number_id": "xxx"
    },
    "wabaId": "xxx"
}

分享联系方式

当用户分享其联系方式（通过轻触 REQUEST_CONTACT_INFO 按钮或直接在聊天中分享联系方式）时，将触发联系人 Webhook。
origin — 新属性。表示联系方式的分享方式。值可以是：
contact_request — 用户通过轻触 REQUEST_CONTACT_INFO 按钮分享了联系方式。
other — 用户直接在聊天中（而非通过 REQUEST_CONTACT_INFO 按钮）分享联系方式。
vcard — 用户的虚拟联系人卡片，采用 vCard 格式。如果 origin 为 other，此属性将设置为用户的 vCard。如果 origin 是 contact_request，则将被省略。

用户通过轻触 REQUEST_CONTACT_INFO 按钮分享了联系方式。

{
    "app_id": "547",
    "business_phone": "xxx",
    "channel": 2,
    "contacts": [
        {
            "profile": {
                "name": "xxx xxx",
                "username": "xxx"
            },
            "user_id": "GB.3560462274116992",
            "wa_id": "xxx"
        }
    ],
    "merchant_phone": "xxx",
    "messages": [
        {
            "contacts": [
                {
                    "name": {
                        "formatted_name": "Oranxxx"
                    },
                    "origin": "contact_request",
                    "phones": [
                        {
                            "phone": "+62 895-xxx-xxx",
                            "type": "MOBILE",
                            "wa_id": "xxx"
                        }
                    ]
                }
            ],
            "cost": {
                "cdr_type": 1,
                "currency": "USD",
                "direction": 2,
                "foreign_price": 0,
                "message_id": "wamid.HBgMNDQ3MzQ5MzIwNDk3FQIAEhggQUM5QzMzQUUxQTdEOEYwOEVENkI4OUM1MjZEQTM1NkQA",
                "price": 0
            },
            "from": "xxx",
            "from_user_id": "GB.3560462274116992",
            "id": "wamid.HBgMNDQ3MzQ5MzIwNDk3FQIAEhggQUM5QzMzQUUxQTdEOEYwOEVENkI4OUM1MjZEQTM1NkQA",
            "timestamp": "1779264041",
            "type": "contacts"
        }
    ],
    "messaging_product": "whatsapp",
    "metadata": {
        "display_phone_number": "xxx",
        "phone_number_id": "xxxx"
    },
    "wabaId": "xxx"
}

用户直接在聊天中（而非通过 REQUEST_CONTACT_INFO 按钮）分享联系方式。

{
    "app_id": "547",
    "business_phone": "xxx",
    "channel": 2,
    "contacts": [
        {
            "profile": {
                "name": "Mohxxx xxx"
            },
            "user_id": "GB.3560462274116992",
            "wa_id": "xxx"
        }
    ],
    "merchant_phone": "xxx",
    "messages": [
        {
            "contacts": [
                {
                    "name": {
                        "formatted_name": "Oranxxx"
                    },
                    "origin": "other",
                    "phones": [
                        {
                            "phone": "+62 895-xxx-xxx",
                            "type": "MOBILE",
                            "wa_id": "xxx"
                        }
                    ],
                    "vcard": "QkVHSU46VkNBUkQKVkVSU0lPTjozLjAKTjxxxxx"
                }
            ],
            "cost": {
                "cdr_type": 1,
                "currency": "USD",
                "direction": 2,
                "foreign_price": 0,
                "message_id": "wamid.HBgMNDQ3MzQ5MzIwNDk3FQIAEhggQUM5QzMzQUUxQTdEOEYwOEVENkI4OUM1MjZEQTM1NkQA",
                "price": 0
            },
            "from": "xxx",
            "from_user_id": "GB.3560462274116992",
            "id": "wamid.HBgMNDQ3MzQ5MzIwNDk3FQIAEhggQUM5QzMzQUUxQTdEOEYwOEVENkI4OUM1MjZEQTM1NkQA",
            "timestamp": "1779264041",
            "type": "contacts"
        }
    ],
    "messaging_product": "whatsapp",
    "metadata": {
        "display_phone_number": "xxx",
        "phone_number_id": "xxxx"
    },
    "wabaId": "xxx"
}

号码质量更新

{
    "field": "phone_number_quality_update",
    "value": {
        "business_phone": "xxx",
        "current_limit": "TIER_1K",
        "display_phone_number": "xxx",
        "event": "ONBOARDING",
        "time": 1760074010,
        "wabaId": "xxx"
    }
}

模板状态更新

模板状态事件event。值可以是： APPROVED — 表示模板已获批准，现可在模板消息中发送。 ARCHIVED — 表示模板因不再使用而被归档。除非取消归档，否则已归档的模板预定将在 28 天后删除。 UNARCHIVED — 表示模板已取消归档并恢复到之前的状态。 DELETED — 表示模板已被删除。 DISABLED — 表示模板因用户反馈而被禁用。 FLAGGED — 表示模板收到了负面反馈，有被禁用的风险。 IN_APPEAL — 表示模板处于申诉流程。 LIMIT_EXCEEDED — 表示 WhatsApp Business 业务账户模板已达到其模板限制。 LOCKED — 表示模板已被锁定，无法编辑。 PAUSED — 表示模板已被暂停。 PENDING — 表示模板正在接受模板审核。 REINSTATED — 表示模板不再被标记或禁用，可以再次通过模板消息发送。 PENDING_DELETION — 表示模板已通过 WhatsApp 管理工具被删除。 REJECTED — 表示模板已被拒。您可以编辑模板以重新提交模板审核，或者针对未通过审核的模板提出申诉。

模板已批准

{
	"value": {
		"wabaId": "1049513xxxx7327",
		"event": "APPROVED",
		"time": 1713313467,
		"message_template_id": "1370101990353470",
		"message_template_name": "lostgreethungarian20",
		"message_template_language": "hu",
		"reason": "NONE"
	},
	"field": "message_template_status_update"
}

模板被拒绝

{
	"value": {
		"wabaId": "1049513xxxx7327",
		"event": "REJECTED",
		"time": 1713165587,
		"message_template_id": "1084366229523542",
		"message_template_name": "mulanfreeen",
		"message_template_language": "en",
		"reason": "INCORRECT_CATEGORY"
	},
	"field": "message_template_status_update"
}

计划禁用的模板

{
  "field": "message_template_status_update",
  "value": {
    "wabaId": "1049513xxxx7327",
    "event": "FLAGGED",
    "message_template_id": "TEMPLATE-ID",
    "message_template_name": "My message template",
    "message_template_language": "en-US",
    "reason": null,
    "disable_info": {
      "disable_date": "DATE"
    }
  }
}

模板已暂停

{
    "value": {
        "wabaId": "1049513xxxx7327",
        "event": "PAUSED",
        "message_template_id": 6048,
        "message_template_name": "welcome",
        "message_template_language": "en_US",
        "reason": "NONE",
        "other_info": {
            "title": "SECOND_PAUSE",
            "description": "Your WhatsApp message template has been paused for 6 hours until Aug 31 at 12:47 AM UTC because it continued to have issues."
        }
    },
    "field": "message_template_status_update"
}

模板待删除

{
    "value": {
        "wabaId": "1049513xxxx7327",
        "event": "PENDING_DELETION",
        "message_template_id": 1137,
        "message_template_name": "<MY_TEMPLATE_NAME>",
        "message_template_language": "en_US",
        "reason": "NONE"
    },
    "field": "message_template_status_update"
}

模板质量变更

{
    "value": {
        "time": 1730390145,
        "message_template_id": "301336xxxx511624",
        "message_template_name": "simon_def2",
        "message_template_language": "en_US",
        "previous_quality_score": "UNKNOWN",
        "new_quality_score": "YELLOW",
        "wabaId": "10903xxxxxx0925"
    },
    "field": "message_template_quality_update"
}

模板类型变更

{
	"field": "template_category_update",
	"value": {
		"message_template_id": "138641***878",
		"message_template_language": "zh_CN",
		"message_template_name": "test_service_1",
		"new_category": "MARKETING",
		"time": 1745385279,
		"wabaId": "1386417***78"
	}
}

{
    "field": "template_category_update",
    "value": {
        "message_template_id": "13864****7878",
        "message_template_language": "zh_CN",
        "message_template_name": "test_service_1",
        "new_category": "MARKETING",
        "previous_category": "UTILITY",
        "time": 1745385279,
        "wabaId": "13864****878"
    }
}

WABA账号更新

沙盒号码升级为验证帐户

{
    "value": {
        "business_phone": "1669xxxx193",
        "wabaId": "1049513xxxx7327",
        "phone_number": "PHONE_NUMBER",
        "event": "VERIFIED_ACCOUNT"
    },
    "field": "account_update"
}

WhatsApp 企业帐户被禁止

{
    "value": {
        "business_phone": "1669xxxx193",
        "wabaId": "1049513xxxx7327",
        "event": "DISABLED_UPDATE",
        "ban_info": {
            "waba_ban_state": "REINSTATE",
            "waba_ban_date": "DATE"
        }
    },
    "field": "account_update"
}

WhatsApp 企业帐户违反政策

{
    "value": {
        "business_phone": "1669xxxx193",
        "wabaId": "1049513xxxx7327",
        "event": "ACCOUNT_VIOLATION",
        "violation_info": {
            "violation_type": "VIOLATION_TYPE"
        }
    },
    "field": "account_update"
}

WhatsApp 企业帐户因违反政策而受到限制

-restriction_type "RESTRICTED_BIZ_INITIATED_MESSAGING" | "RESTRICTION_ON_ADD_PHONE_NUMBER_ACTION"| "RESTRICTED_CUSTOMER_INITIATED_MESSAGING"

{
    "value": {
        "business_phone": "1669xxxx193",
        "wabaId": "1049513xxxx7327",
        "event": "ACCOUNT_RESTRICTION",
        "restriction_info": [
            {
                "restriction_type": "RESTRICTED_BIZ_INITIATED_MESSAGING",
                "expiration": "TIMESTAMP"
            }
        ]
    },
    "field": "account_update"
}

WhatsApp 企业帐户审核已完成

{
    "value": {
        "business_phone": "1669xxxx193",
        "wabaId": "1049513xxxx7327",
        "decision": "APPROVED"
    },
    "field": "account_review_update"
}

WhatsApp 企业帐户已删除

{
    "value": {
        "business_phone": "1669xxxx193",
        "wabaId": "1049513xxxx7327",
        "phone_number": "1669xxxx193",
        "event": "ACCOUNT_DELETED"
    },
    "field": "account_update"
}

WhatsApp 企业帐户已从合作伙伴中添加

{
    "field": "account_update",
    "value": {
        "business_phone": "xxx",
        "event": "PARTNER_ADDED",
        "time": 1772521398,
        "wabaId": "xxx",
        "waba_info": {
            "owner_business_id": "xxx",
            "waba_id": "xxx"
        }
    }
}

WhatsApp 企业帐户已从合作伙伴中删除 [USER主动解除关联]

disconnection_info object 指明断连是由您的客户端还是系统发起的。仅当存在 disconnection_info 时，才会包含在 PARTNER_REMOVED 事件中。
initiated_by 值可以是：

SYSTEM — 断连由系统发起（例如，由于设备处于非活跃状态或强制断开）。
USER — 断连由客户发起（例如，更改了电话号码、在新设备上重新注册、删除了 WhatsApp 账户或使用消费者 WhatsApp 应用注册了业务电话号码）。

reason 断连的原因。仅在商家同时使用 WhatsApp Business 应用和云端 API 时，才会包含在 PARTNER_REMOVED 事件中。[即共存方式注册] 值可以是：

ACCOUNT_DISCONNECTED — 由于系统强制执行或明确删除了其 WhatsApp 账户，账户已解除关联。可由 USER 或 SYSTEM 发起。
BUSINESS_DOWNGRADE — 已通过消费者 WhatsApp 应用注册其业务电话号码。
CHANGE_NUMBER — 更改了其电话号码。
COMPANION_INACTIVITY — 配套设备约 30 天处于非活跃状态。
PRIMARY_INACTIVITY — 主要设备约 14 天处于非活跃状态。
USER_RE_REGISTERED — 在新设备上重新注册。

{
    "field": "account_update",
    "value": {
        "business_phone": "xxx",
        "disconnection_info": {
            "reason": "ACCOUNT_DISCONNECTED",
            "initiated_by": "USER"
        },
        "event": "PARTNER_REMOVED",
        "time": 1779853772,
        "wabaId": "xxx",
        "waba_info": {
            "owner_business_id": "xxx",
            "waba_id": "xxx"
        }
    }
}

WhatsApp 企业帐户已从合作伙伴中删除[已通过消费者 WhatsApp 应用注册其业务电话号码。]

{
    "field": "account_update",
    "value": {
        "business_phone": "xxx",
        "disconnection_info": {
            "reason": "BUSINESS_DOWNGRADE",
            "initiated_by": "USER"
        },
        "event": "PARTNER_REMOVED",
        "time": 1779981862,
        "wabaId": "xxx",
        "waba_info": {
            "owner_business_id": "xxx",
            "waba_id": "xxx"
        }
    }
}

WhatsApp 企业帐户已从合作伙伴中删除[主要设备约 14 天处于非活跃状态。]

{
    "field": "account_update",
    "value": {
        "business_phone": "xxx",
        "disconnection_info": {
            "reason": "PRIMARY_INACTIVITY",
            "initiated_by": "SYSTEM"
        },
        "event": "PARTNER_REMOVED",
        "time": 1779839797,
        "wabaId": "xxx",
        "waba_info": {
            "owner_business_id": "xxx",
            "waba_id": "xxx"
        }
    }
}

账户已移除当 WhatsApp Business 业务账户因设备更换或电话号码重新注册而停用时发送。

{
    "field": "account_update",
    "value": {
        "business_phone": "xxx",
        "event": "ACCOUNT_OFFBOARDED",
        "time": 1779776412,
        "wabaId": "xxx"
    }
}

当业务账号状态更改时，会触发此 Webhook。

username — 状态发生变更的账号。如果 status 设置为 deleted，则省略。
status — 值可以是：

approved — 表示账号已通过审核并对 WhatsApp 用户可见。当账号的状态从 reserved 更改为 approved，或账号通过 WhatsApp Business 应用进行更改时触发。
deleted — 表示账号已通过 WhatsApp Business 应用被删除。
reserved — 表示账号是为业务电话号码预留的，但对 WhatsApp 用户不可见。账号功能对所有人开放后，该账号就会变为可见。

{
    "field": "business_username_updates",
    "value": {
        "business_phone": "xxx",
        "display_phone_number": "xxx",
        "status": "approved",
        "time": 1780275371,
        "username": "xxx",
        "wabaId": "xxx"
    }
}

账户已重新关联在更换设备或重新注册电话号码后重新关联 WhatsApp Business 业务账户时发送。

{
    "field": "account_update",
    "value": {
        "business_phone": "xxx",
        "event": "ACCOUNT_RECONNECTED",
        "time": 1779776471,
        "wabaId": "xxx"
    }
}

用户恢复接收营销消息

{
    "value": {
        "messaging_product": "whatsapp",
        "metadata": {
            "display_phone_number": "xxx",
            "phone_number_id": "xxx"
        },
        "contacts": [
            {
                "profile": {
                    "name": "test user name"
                },
                "wa_id": "16315551111",
                "user_id": "US.13491208655302741918",
                "parent_user_id": "US.ENT.506847293015824"
            }
        ],
        "user_preferences": [
            {
                "wa_id": "xxx",
                "user_id": "US.13491208655302741918",
                "parent_user_id": "US.ENT.506847293015824",
                "detail": "User requested to resume marketing messages",
                "category": "marketing_messages",
                "value": "resume",
                "timestamp": 1753865209
            }
        ]
    },
    "field": "user_preferences"
}

用户关闭接收营销消息

{
    "value": {
        "messaging_product": "whatsapp",
        "metadata": {
            "display_phone_number": "xxx",
            "phone_number_id": "xxx"
        },
        "contacts": [
            {
                "profile": {
                    "name": "test user name"
                },
                "wa_id": "16315551111",
                "user_id": "US.13491208655302741918",
                "parent_user_id": "US.ENT.506847293015824"
            }
        ],
        "user_preferences": [
            {
                "wa_id": "xxx",
                "user_id": "US.13491208655302741918",
                "parent_user_id": "US.ENT.506847293015824",
                "detail": "User requested to stop marketing messages",
                "category": "marketing_messages",
                "value": "stop",
                "timestamp": 1753407219
            }
        ]
    },
    "field": "user_preferences"
}

flows

FLOW_STATUS_CHANGE

{
    "field": "flows",
    "value": {
        "business_phone": "xxx",
        "event": "FLOW_STATUS_CHANGE",
        "flow_id": "xxx",
        "message": "Flow zelin2 changed status from DRAFT to PUBLISHED",
        "new_status": "PUBLISHED",
        "old_status": "DRAFT",
        "time": 1754040220,
        "wabaId": "xxx"
    }
}

flows ACTIVATED

{
    "field": "flows",
    "value": {
        "alert_state": "ACTIVATED",
        "business_phone": "xxx",
        "event": "ENDPOINT_AVAILABILITY",
        "flow_id": "xxx",
        "message": "Flow endpoint availability was below 90% threshold in the last 60 minutes. Users are unable to open or use the flow.",
        "threshold": 90,
        "time": 1754335811,
        "wabaId": "xxx"
    }
}

flows DEACTIVATED

{
    "field": "flows",
    "value": {
        "alert_state": "DEACTIVATED",
        "business_phone": "xx",
        "event": "ENDPOINT_AVAILABILITY",
        "flow_id": "xxx",
        "message": "Flow endpoint availability successfully recovered. Users will now be able to open and use the flow.",
        "threshold": 90,
        "time": 1754306033,
        "wabaId": "xxx"
    }
}

call回执

calls object参数：

参数名	类型	说明
call_id	String	call_id
from	String	拨打方号码
to	String	接听方号码
costs	Objects	费用信息
start_time	String	通话开始时间戳
end_time	String	通话终止时间戳
record	String	录音文件地址
call_duration	Integer	通话时长
fee_duration	Integer	计费时长
bill_type	String	计费方式6+6
end_direction	Integer	挂断方：0主叫， 1被叫，2服务器,3 未知
end_reason	String	终止原因

costs object参数：

参数名	类型	说明
direction	Integer	1-呼出 0-呼入
currency	String	币种
price	Double	币种对应的费用

{
    "app_id": 277,
    "business_phone": "xxx",
    "channel": 2,
    "merchant_phone": "xxx",
    "messaging_product": "whatsapp",
    "wabaId": "xxx",
    "calls": [
        {
            "call_id": "ae5b182f-f37b-123e-dcb0-42010a34f811",
            "from": "xxx",
            "to": "xxx",
            "costs": [
                {
                    "direction": 1,
                    "currency": "EUR",
                    "price": 1.2948
                }
            ],
            "start_time": "1755153316",
            "end_time": "1755153319",
            "record": "https://xxx",
            "call_duration": 55,
            "fee_duration": 60,
            "bill_type": "6+6",
            "end_direction": 1,
            "end_reason": "Busy Here"
        }
    ]
}

简介

Home

短信

语音

云呼叫中心（NXLink）

云呼叫中心（AI自动外呼）

Flash Call

短链

邮件验证码

DID号码

通用

号码检测

Viber

Zalo ZNS

Super Message API

发送消息 (新接口，未启用)
webhook (新接口，未启用)

隐私号(旧)

PNS

坐席（旧版）

NXLINK(HKG)

NXLINK(IDN)

NXLINK(CHL)

AI Agent

RCS

Uh oh!

WhatsApp API webhook

WhatsApp Webhook

状态回复

验签说明

响应参数

匿名化相关字段补充说明

响应示例

消息已发送[新版本]

消息已发送[新版本]

消息已送达[新版本]

消息已送[新版本]

消息发送失败

错误码说明

消息发送失败[提交给meta同步返回的异常]

Meta回调失败[提交给meta成功后异步返回的异常信息]

消息回复 [上行消息 用户发送消息给商户]

响应参数

匿名化相关字段补充说明

响应示例

文本消息响应示例 【可获得用户手机号】

文本消息响应示例 【不可获得用户手机号】

图片消息响应示例

视频消息响应示例

语音消息响应示例

音频消息响应示例

文档消息响应示例

位置消息响应示例

贴图表情消息响应示例

互动消息快速回复响应示例

互动消息列表响应示例

商品消息响应示例

下单消息响应示例

flow表单提交消息响应示例

广告引入客户的消息响应示例

引用消息响应示例

WhatsAppBusinessAPI账号不支持的消息响应示例

心情消息示例

互动消息-通话权限申请反馈示例

ctwa_clid

系统消息 如果用户更改了其业务电话号码，则将触发系统消息回执

删除消息

编辑后的新消息

编辑前的旧消息

分享联系方式

用户通过轻触 REQUEST_CONTACT_INFO 按钮分享了联系方式。

用户直接在聊天中（而非通过 REQUEST_CONTACT_INFO 按钮）分享联系方式。

号码质量更新

模板状态更新

模板已批准

模板被拒绝

计划禁用的模板

模板已暂停

模板待删除

模板质量变更

模板类型变更

WABA账号更新

沙盒号码升级为验证帐户

WhatsApp 企业帐户被禁止

WhatsApp 企业帐户违反政策

WhatsApp 企业帐户因违反政策而受到限制

WhatsApp 企业帐户审核已完成

WhatsApp 企业帐户已删除

WhatsApp 企业帐户已从合作伙伴中添加

WhatsApp 企业帐户已从合作伙伴中删除 [USER主动解除关联]

WhatsApp 企业帐户已从合作伙伴中删除[已通过消费者 WhatsApp 应用注册其业务电话号码。]

WhatsApp 企业帐户已从合作伙伴中删除[主要设备约 14 天处于非活跃状态。]

账户已移除 当 WhatsApp Business 业务账户因设备更换或电话号码重新注册而停用时发送。

当业务账号状态更改时，会触发此 Webhook。

账户已重新关联 在更换设备或重新注册电话号码后重新关联 WhatsApp Business 业务账户时发送。

用户恢复接收营销消息

用户关闭接收营销消息

flows

FLOW_STATUS_CHANGE

flows ACTIVATED

flows DEACTIVATED

call回执

Uh oh!

Uh oh!

Uh oh!

消息回复 [上行消息用户发送消息给商户]

文本消息响应示例【可获得用户手机号】

文本消息响应示例【不可获得用户手机号】

系统消息如果用户更改了其业务电话号码，则将触发系统消息回执

账户已移除当 WhatsApp Business 业务账户因设备更换或电话号码重新注册而停用时发送。

账户已重新关联在更换设备或重新注册电话号码后重新关联 WhatsApp Business 业务账户时发送。