message webhook

消息webhook

根据mt接口下发时提供的dr_webhook字段值或者应用上配置的webhook值【需要订阅以下事件】

mesages 消息事件
message_status_update 消息状态更新事件

对提供的webhook地址，进行状态回复，消息回复的推送信息

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

验签说明

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

状态回复【下行消息的状态更新回执】

对调用WhatsApp-API发送消息的场景，提供消息的回执情况 (sent/delivered/read/failed)

响应参数

参数名	类型	说明
statuses	array[Status Object]	状态对象
business_phone	String	商户电话
messaging_product	String	消息类型，固定值”whatsapp“
wabaId	String	waba id

Status Object参数：

参数名	类型	说明
conversation	Conversation Object	会话信息
errors	array[Error Object]	错误信息
recipient_id	String	收件人WhatsApp_id
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	Pricing Object	计费模式信息

Conversation Object参数：【未来将会被废弃】

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

Origin Object参数：

参数名	类型	说明
type	String	消息类型 marketing（营销消息），utility（通知消息），authentication（验证消息），service（服务消息）， referral_conversion（免费消息），marketing_lite（MM Lite API消息), authentication_international(国际验证消息)

Pricing Object参数:

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

Error Object参数：

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

Cost Object参数:

参数名	类型	说明
currency	String	币种
foreign_price	number	费用【币种对应的费用】
cdr_type	Integer	消息类型， 1（消息），4（营销会话），5（通知会话），6（验证会话），7（服务会话），8（免费会话），9（国际验证），10（MM Lite）
message_id	String	消息id（发送消息时返回的ID）
direction	Integer	方向，1（下行），2（上行）

响应示例

消息已发送 sent回执【带有costs费用信息】

{
    "app_id": "48",
    "business_phone": "xxx",
    "channel": 2,
    "merchant_phone": "xxx",
    "messaging_product": "whatsapp",
    "metadata": {
        "display_phone_number": "xxx",
        "phone_number_id": "xxx"
    },
    "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": "xxx",
            "status": "sent",
            "timestamp": "1750644366"
        }
    ],
    "wabaId": "xxx"
}

消息已送达 delivered回执

{
    "app_id": "48",
    "business_phone": "xxx",
    "channel": 2,
    "merchant_phone": "xxx",
    "messaging_product": "whatsapp",
    "metadata": {
        "display_phone_number": "xxx",
        "phone_number_id": "661162737077678"
    },
    "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",
            "status": "delivered",
            "timestamp": "1750644491"
        }
    ],
    "wabaId": "xxx"
}

消息已读 read回执

{
    "app_id": "6095",
    "business_phone": "xxx",
    "channel": 2,
    "merchant_phone": "xxx",
    "messaging_product": "whatsapp",
    "metadata": {
        "display_phone_number": "xxx",
        "phone_number_id": "xxx"
    },
    "statuses": [
        {
            "conversation": {
                "id": "b1e0cedd81ee48c86a8588e37c63fccf",
                "origin": {
                    "type": "service"
                }
            },
            "id": "311feb5b-8ffa-4096-9616-dda879ca2f5b",
            "meta_message_id": "wamid.HBgLNjY4MjcyNjA1OTAVAgARGBI0MThEQTgwQzUzRTA2MUY5RDYA",
            "pricing": {
                "billable": false,
                "category": "service",
                "pricing_model": "PMP",
                "type": "free_customer_service"
            },
            "recipient_id": "xxx",
            "status": "read",
            "timestamp": "1761274320"
        }
    ],
    "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",
            "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",
            "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",
            "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",
            "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",
            "status": "failed",
            "timestamp": "1754379592"
        }
    ],
    "wabaId": "xxx"
}

通话呼叫权限触发限制

{
    "business_phone": "xxx",
    "messaging_product": "whatsapp",
    "statuses": [
        {
            "errors": [
                {
                    "code": 10000,
                    "meta_code": 138009,
                    "title": "Meta Error((#138009) Limit reached for call permission request sends for the given business and consumer pair)"
                }
            ],
            "id": "wamid.1ffd4eaf06e646a492b91af63e0ab323",
            "recipient_id": "xxx",
            "status": "failed",
            "timestamp": "1761190717"
        }
    ],
    "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",
            "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",
            "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",
            "status": "failed",
            "timestamp": "1754380547"
        }
    ],
    "wabaId": "xxx"
}

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

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

响应参数

body参数：

参数名	类型	说明
contacts	array[Contact Object]	提供联系人的信息
messages	array[Message Object]	上行消息
business_phone	String	商户电话
messaging_product	String	消息类型，固定值”whatsapp“
wabaId	String	waba id

Contact Object参数：

参数名	类型	说明
profile	Profile Object	配置文件对象
wa_id	String	联系人的 WhatsApp ID

Profile Object参数：

参数名	类型	说明
name	String	发件人的配置文件名称

Message Object参数：

参数名	类型	说明
from	String	发件人的 WhatsApp ID
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 心情消息
context	Context Object	仅在用户回复或与您的消息之一互动时存在
cost	Cost Object	费用信息

Cost Object参数:

参数名	类型	说明
currency	String	币种
foreign_price	number	费用
cdr_type	Integer	消息类型，1上行消息
message_id	String	wa消息id
direction	Integer	方向，1（下行），2（上行）

消息类型

type = text 文本消息参数：

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

Text Object参数：

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

type = image 图片消息参数：

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

Image Object 参数：

参数名	类型	说明
id	String	媒体存储的id，可用于获取媒体链接
caption	String	图片的描述
mime_type	String	媒体文件的MiME类型
sha256	String	媒体文件的校验签名
link	String	媒体文件的url,有效期48小时

type = video 视频消息参数：

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

Video Object参数：

参数名	类型	说明
id	String	媒体存储的id，可用于获取媒体链接
caption	String	视频的描述
mime_type	String	媒体文件的MiME类型
sha256	String	媒体文件的校验签名
link	String	媒体文件的url,有效期48小时

type = voice 语音消息参数：

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

Voice Object参数：

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

type = audio 音频消息参数：

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

Audio Object参数：

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

type = document 文档消息参数：

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

Document Object参数：

参数名	类型	说明
id	String	媒体存储的id，可用于获取媒体链接
mime_type	String	媒体文件的MiME类型
sha256	String	媒体文件的校验签名
filename	String	文档文件名称

type = location 位置消息参数：

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

Location Object参数：

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

type = sticker 贴图表情消息参数：

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

Sticker Object参数：

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

type = interactive 互动消息参数：

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

Interactive Object参数：

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

ButtonReply Object 或者 ListReply Object参数：

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

NfmReply Object参数：

参数名	类型	说明
name	String	固定为 flow
body	String	消息提交后的文案
response_json	String	flow的json数据. The structure is either defined in flow JSON (see Complete action) or, if flow is using an endpoint, controlled by endpoint (see Final Response Payload in Data Exchange Request)

CallPermissionReply Objcet参数：

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

type = order 下单消息参数：

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

Order Object参数：

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

ProductItem Object 参数：

参数名	类型	说明
product_retailer_id	String	目录中产品的唯一标识符
quantity	Number	物品数量
item_price	Number	每个物品的价格
currency	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	ReferredProduct Object	引用回复商品消息时含有该对象

ReferredProduct Object参数：

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

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

参数名	类型	说明
referral	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	Reaction Object	否	参照请求示例	心情消息内容，type=reaction必填

Reaction Object参数：

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

响应示例

文本消息响应示例

{
    "app_id": "391",
    "business_phone": "xxx",
    "channel": 2,
    "contacts": [
        {
            "profile": {
                "name": "xxx"
            },
            "wa_id": "xxx"
        }
    ],
    "merchant_phone": "xxx",
    "messages": [
        {
            "cost": {
                "cdr_type": 1,
                "currency": "USD",
                "direction": 2,
                "foreign_price": 0,
                "message_id": "wamid.HBgNNjI4NTgwNjIyNjE1NhUCABIYFDNBRjUwRDUzNjUwNzkzQkEzOURCAA==",
                "price": 0
            },
            "from": "xxx",
            "id": "wamid.HBgNNjI4NTgwNjIyNjE1NhUCABIYFDNBRjUwRDUzNjUwNzkzQkEzOURCAA==",
            "text": {
                "body": "Halo Kopi Kenangan"
            },
            "timestamp": "1761274950",
            "type": "text"
        }
    ],
    "messaging_product": "whatsapp",
    "metadata": {
        "display_phone_number": "xxx",
        "phone_number_id": "xxx"
    },
    "wabaId": "xxx"
}

图片消息响应示例

{
    "app_id": "6676",
    "business_phone": "xxx",
    "channel": 2,
    "contacts": [
        {
            "profile": {
                "name": "xxx"
            },
            "wa_id": "xxx"
        }
    ],
    "merchant_phone": "xxx",
    "messages": [
        {
            "cost": {
                "cdr_type": 1,
                "currency": "USD",
                "direction": 2,
                "foreign_price": 0,
                "message_id": "wamid.HBgNNjI4NTg3NjE0NjU1OBUCABIYIEFDNjBEOEQ2RTVCRkE1NjI1OUY3N0UwODhGRUUzNTBCAA==",
                "price": 0
            },
            "from": "xxx",
            "id": "wamid.HBgNNjI4NTg3NjE0NjU1OBUCABIYIEFDNjBEOEQ2RTVCRkE1NjI1OUY3N0UwODhGRUUzNTBCAA==",
            "image": {
                "id": "1415735676749398",
                "link": "https://goss.oss-accelerate.aliyuncs.com/xxx",
                "mime_type": "image/jpeg",
                "sha256": "1pCw7W8gxrPqGt1+RQdvszriXsD3QMFM72hQSw2iINo="
            },
            "timestamp": "1761276109",
            "type": "image"
        }
    ],
    "messaging_product": "whatsapp",
    "metadata": {
        "display_phone_number": "xxx",
        "phone_number_id": "xxx"
    },
    "wabaId": "xxx"
}

视频消息响应示例

{
    "app_id": "1533",
    "business_phone": "xxx",
    "channel": 2,
    "contacts": [
        {
            "profile": {
                "name": "xxx"
            },
            "wa_id": "xxx"
        }
    ],
    "merchant_phone": "xxx",
    "messages": [
        {
            "context": {},
            "cost": {
                "cdr_type": 1,
                "currency": "USD",
                "direction": 2,
                "foreign_price": 0,
                "message_id": "wamid.HBgMODU1OTYzODExMDYxFQIAEhgUM0E5RjIxQjUzQjNENUFFQzEzNTgA",
                "price": 0
            },
            "from": "xxx",
            "id": "wamid.HBgMODU1OTYzODExMDYxFQIAEhgUM0E5RjIxQjUzQjNENUFFQzEzNTgA",
            "timestamp": "1761276177",
            "type": "video",
            "video": {
                "id": "1590334752132263",
                "link": "https://goss.oss-accelerate.aliyuncs.com/xxx",
                "mime_type": "video/mp4",
                "sha256": "ngskJYFiYWNH5G+aeNJhE+GLX6wPJRbIzcYooCrDxXQ="
            }
        }
    ],
    "messaging_product": "whatsapp",
    "metadata": {
        "display_phone_number": "xxx",
        "phone_number_id": "xxx"
    },
    "wabaId": "xxx"
}

音频消息响应示例

{
    "app_id": "48",
    "business_phone": "xxx",
    "channel": 2,
    "contacts": [
        {
            "profile": {
                "name": "xxx"
            },
            "wa_id": "xxx"
        }
    ],
    "merchant_phone": "xxx",
    "messages": [
        {
            "audio": {
                "id": "815965824171837",
                "link": "https://goss.oss-accelerate.aliyuncs.com/xxx",
                "mime_type": "audio/ogg; codecs=opus",
                "sha256": "mPpj0uVUDAQW3WH1XS93J9jjC9mtmOE7FHRJJlfD2/Q="
            },
            "cost": {
                "cdr_type": 1,
                "currency": "USD",
                "direction": 2,
                "foreign_price": 0,
                "message_id": "wamid.HBgNODYxMzMyMDIzNzQ0NhUCABIYFDJBQzExNjU0QTQwNjYwOUEzOUYxAA==",
                "price": 0
            },
            "from": "xxx",
            "id": "wamid.HBgNODYxMzMyMDIzNzQ0NhUCABIYFDJBQzExNjU0QTQwNjYwOUEzOUYxAA==",
            "timestamp": "1761276394",
            "type": "audio"
        }
    ],
    "messaging_product": "whatsapp",
    "metadata": {
        "display_phone_number": "xxx",
        "phone_number_id": "xxx"
    },
    "wabaId": "xxx"
}

文档消息响应示例

{
    "app_id": "749",
    "business_phone": "xxx",
    "channel": 2,
    "contacts": [
        {
            "profile": {
                "name": "xxx"
            },
            "wa_id": "xxx"
        }
    ],
    "merchant_phone": "xxx",
    "messages": [
        {
            "cost": {
                "cdr_type": 1,
                "currency": "USD",
                "direction": 2,
                "foreign_price": 0,
                "message_id": "wamid.HBgNNTIxODEyMTcxNjE4NxUCABIYIEFDQjIzNDMzQTVCRDFGMTVFM0JENTkzMjA1MDAwQUNBAA==",
                "price": 0
            },
            "document": {
                "filename": "xxx231025.docx",
                "id": "25133622559612021",
                "link": "https://goss.oss-accelerate.aliyuncs.com/xxx",
                "mime_type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
                "sha256": "3+ROalU+T+/pXILjLMQNpurk7pkaNe9I/fHtWwmr6yA="
            },
            "from": "xxx",
            "id": "wamid.HBgNNTIxODEyMTcxNjE4NxUCABIYIEFDQjIzNDMzQTVCRDFGMTVFM0JENTkzMjA1MDAwQUNBAA==",
            "timestamp": "1761276228",
            "type": "document"
        }
    ],
    "messaging_product": "whatsapp",
    "metadata": {
        "display_phone_number": "xxx",
        "phone_number_id": "xxx"
    },
    "wabaId": "xxx"
}

位置消息响应示例

{
    "app_id": "48",
    "business_phone": "xxx",
    "channel": 2,
    "contacts": [
        {
            "profile": {
                "name": "xxx"
            },
            "wa_id": "xxx"
        }
    ],
    "merchant_phone": "xxx",
    "messages": [
        {
            "cost": {
                "cdr_type": 1,
                "currency": "USD",
                "direction": 2,
                "foreign_price": 0,
                "message_id": "wamid.HBgNODYxMzMyMDIzNzQ0NhUCABIYFDJBQUVGRkQzNEU2MTUwRjA3RkM0AA==",
                "price": 0
            },
            "from": "xxx",
            "id": "wamid.HBgNODYxMzMyMDIzNzQ0NhUCABIYFDJBQUVGRkQzNEU2MTUwRjA3RkM0AA==",
            "location": {
                "address": "深圳市, 广东",
                "latitude": 22.550802897696343,
                "longitude": 113.93844723701477,
                "name": "KFC (肯德基)",
                "url": "http://www.kfc.com.cn"
            },
            "timestamp": "1761276723",
            "type": "location"
        }
    ],
    "messaging_product": "whatsapp",
    "metadata": {
        "display_phone_number": "xxx",
        "phone_number_id": "xxx"
    },
    "wabaId": "xxx"
}

贴图表情消息响应示例

{
    "app_id": "6741",
    "business_phone": "xxx",
    "channel": 2,
    "contacts": [
        {
            "profile": {
                "name": "Oops"
            },
            "wa_id": "xxx"
        }
    ],
    "merchant_phone": "xxx",
    "messages": [
        {
            "cost": {
                "cdr_type": 1,
                "currency": "USD",
                "direction": 2,
                "foreign_price": 0,
                "message_id": "wamid.HBgNODYxMzMyMDIzNzQ0NhUCABIYFDJBQTQwMkI3NDc1NkUyNUM3NjVFAA==",
                "price": 0
            },
            "from": "xxx",
            "id": "wamid.HBgNODYxMzMyMDIzNzQ0NhUCABIYFDJBQTQwMkI3NDc1NkUyNUM3NjVFAA==",
            "sticker": {
                "id": "837214938818066",
                "link": "https://goss.oss-accelerate.aliyuncs.com/837214938818066?xxx",
                "mime_type": "image/webp",
                "sha256": "AGPB7Vnhnd3RtkCmidNcpfWityDQTiyMNW95o1QAkWg="
            },
            "timestamp": "1761276932",
            "type": "sticker"
        }
    ],
    "messaging_product": "whatsapp",
    "metadata": {
        "display_phone_number": "xxx",
        "phone_number_id": "xxx"
    },
    "wabaId": "xxx"
}

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

{
    "app_id": "433",
    "business_phone": "xxx",
    "channel": 2,
    "contacts": [
        {
            "profile": {
                "name": "xxx"
            },
            "wa_id": "xxx"
        }
    ],
    "merchant_phone": "xxx",
    "messages": [
        {
            "context": {
                "from": "xxx",
                "id": "wamid.76297db0cfc64b1cbefb18f67811140d",
                "meta_message_id": "wamid.HBgMOTcxNTYxMDAwNjg3FQIAERgSMzBDODA5N0MxNEY2RTA2RUI4AA=="
            },
            "cost": {
                "cdr_type": 1,
                "currency": "USD",
                "direction": 2,
                "foreign_price": 0,
                "message_id": "wamid.HBgMOTcxNTYxMDAwNjg3FQIAEhgUM0FFREUyQUQwOUNDMEVCQjlFMTEA",
                "price": 0
            },
            "from": "xxx",
            "id": "wamid.HBgMOTcxNTYxMDAwNjg3FQIAEhgUM0FFREUyQUQwOUNDMEVCQjlFMTEA",
            "interactive": {
                "button_reply": {
                    "id": "26073",
                    "title": "لا"
                },
                "type": "button_reply"
            },
            "timestamp": "1761276998",
            "type": "interactive"
        }
    ],
    "messaging_product": "whatsapp",
    "metadata": {
        "display_phone_number": "xxx",
        "phone_number_id": "xxx"
    },
    "wabaId": "xxx"
}

互动消息列表响应示例

{
    "app_id": "5828",
    "business_phone": "xxx",
    "channel": 2,
    "contacts": [
        {
            "profile": {
                "name": "xxx"
            },
            "wa_id": "xxx"
        }
    ],
    "merchant_phone": "xxx",
    "messages": [
        {
            "context": {
                "from": "xxx",
                "id": "wamid.f8bdecd37a4e44269f26e0eb29a66ac0",
                "meta_message_id": "wamid.HBgNNTIxNzI5NTQ0Njc3ORUCABEYEjFDRTMyNzRERkI1RjYxNUFCQwA="
            },
            "cost": {
                "cdr_type": 1,
                "currency": "USD",
                "direction": 2,
                "foreign_price": 0,
                "message_id": "wamid.HBgNNTIxNzI5NTQ0Njc3ORUCABIYIEFDOUY3Nzg4Mzc5OTBDOTkyMjQ1Q0I4ODdENTYwMUQ4AA==",
                "price": 0
            },
            "from": "xxx",
            "id": "wamid.HBgNNTIxNzI5NTQ0Njc3ORUCABIYIEFDOUY3Nzg4Mzc5OTBDOTkyMjQ1Q0I4ODdENTYwMUQ4AA==",
            "interactive": {
                "list_reply": {
                    "id": "44594",
                    "title": "Demora de aprobación"
                },
                "type": "list_reply"
            },
            "timestamp": "1761276268",
            "type": "interactive"
        }
    ],
    "messaging_product": "whatsapp",
    "metadata": {
        "display_phone_number": "xxx",
        "phone_number_id": "xxx"
    },
    "wabaId": "xxx"
}

商品消息响应示例

{
    "app_id": "433",
    "business_phone": "xxx",
    "channel": 2,
    "contacts": [
        {
            "profile": {
                "name": "xxx"
            },
            "wa_id": "xxx"
        }
    ],
    "merchant_phone": "xxx",
    "messages": [
        {
            "context": {
                "from": "xxx",
                "id": "wamid.HBgMOTY2NTQ0NzA2NjE0FQIAEhggQUNBRkFDQjg0RDhGQjI1NTFDNEM4ODlFQTdDRkJGMzgA",
                "referred_product": {
                    "catalog_id": "5608734xxx9426",
                    "product_retailer_id": "23g1xxxk0"
                }
            },
            "cost": {
                "cdr_type": 1,
                "currency": "USD",
                "direction": 2,
                "foreign_price": 0,
                "message_id": "wamid.HBgMOTY2NTQ0NzA2NjE0FQIAEhggQUM0NzgzOUM3Mjc3NTZCQTc0NUI0NzlBOEU4QkQ0NjcA",
                "price": 0
            },
            "from": "xxx",
            "id": "wamid.HBgMOTY2NTQ0NzA2NjE0FQIAEhggQUM0NzgzOUM3Mjc3NTZCQTc0NUI0NzlBOEU4QkQ0NjcA",
            "text": {
                "body": "كم السعر"
            },
            "timestamp": "1759561659",
            "type": "text"
        }
    ],
    "messaging_product": "whatsapp",
    "metadata": {
        "display_phone_number": "xxx",
        "phone_number_id": "xxx"
    },
    "wabaId": "xxx"
}

下单消息响应示例

{
    "app_id": "5753",
    "business_phone": "xxx",
    "channel": 2,
    "contacts": [
        {
            "profile": {
                "name": "xxx"
            },
            "wa_id": "xxx"
        }
    ],
    "merchant_phone": "xxx",
    "messages": [
        {
            "cost": {
                "cdr_type": 1,
                "currency": "CNY",
                "direction": 2,
                "foreign_price": 0,
                "message_id": "wamid.HBgLMTQzNzYwMDU2NTMVAgASGBQzQUYzN0UzMzhFNjU3RENEQkE4NAA=",
                "price": 0
            },
            "from": "xxx",
            "id": "wamid.HBgLMTQzNzYwMDU2NTMVAgASGBQzQUYzN0UzMzhFNjU3RENEQkE4NAA=",
            "order": {
                "catalog_id": "94437xxx9123",
                "text": "",
                "product_items": [
                    {
                        "product_retailer_id": "jpaxxxx8o",
                        "quantity": 1,
                        "item_price": 10,
                        "currency": "HKD"
                    }
                ]
            },
            "timestamp": "1759639681",
            "type": "order"
        }
    ],
    "messaging_product": "whatsapp",
    "metadata": {
        "display_phone_number": "xxx",
        "phone_number_id": "xxx"
    },
    "wabaId": "xxx"
}

flow表单提交消息响应示例

{
    "app_id": "391",
    "business_phone": "xxx",
    "channel": 2,
    "contacts": [
        {
            "profile": {
                "name": "xxx"
            },
            "wa_id": "xxx"
        }
    ],
    "merchant_phone": "xxx",
    "messages": [
        {
            "context": {
                "from": "xxx",
                "id": "wamid.c4825f4807d04f5480cbd3f52834e96f",
                "meta_message_id": "wamid.HBgNNjI4MTkwNjYzNTQ1MxUCABEYEkY0OTMzQ0E0MjU1NjM0NkU1NAA="
            },
            "cost": {
                "cdr_type": 1,
                "currency": "USD",
                "direction": 2,
                "foreign_price": 0,
                "message_id": "wamid.HBgNNjI4MTkwNjYzNTQ1MxUCABIYIEFDMjhFMDhBOEMwMURENzYxQUVDQjUzODNGQ0Q5OTdCAA==",
                "price": 0
            },
            "from": "xxx",
            "id": "wamid.HBgNNjI4MTkwNjYzNTQ1MxUCABIYIEFDMjhFMDhBOEMwMURENzYxQUVDQjUzODNGQ0Q5OTdCAA==",
            "interactive": {
                "nfm_reply": {
                    "response_json": "{\"email\":\"xxx.com\",\"action_name\":\"add_email\",\"first_request\":\"1761xxx034\",\"last_reply\":\"xxx.\\nreferenceid:#xxx#\",\"ctwa_clid\":\"\",\"flow_token\":\"xxx-6f0a-7ab4208b2f9b\"}",
                    "body": "Sent",
                    "name": "flow"
                },
                "type": "nfm_reply"
            },
            "timestamp": "1761277258",
            "type": "interactive"
        }
    ],
    "messaging_product": "whatsapp",
    "metadata": {
        "display_phone_number": "xxx",
        "phone_number_id": "xxx"
    },
    "wabaId": "xxx"
}

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

{
    "app_id": "1176",
    "business_phone": "xxx",
    "channel": 2,
    "contacts": [
        {
            "profile": {
                "name": "xxx"
            },
            "wa_id": "xxx"
        }
    ],
    "merchant_phone": "xxx",
    "messages": [
        {
            "cost": {
                "cdr_type": 1,
                "currency": "CNY",
                "direction": 2,
                "foreign_price": 0,
                "message_id": "wamid.HBgLODUyOTIwMTUxMTgVAgASGCBBQzEwNzNGNjM5RTkwNTcyMjhCN0NEMTQ2QUJERjRCRgA=",
                "price": 0
            },
            "from": "xxx",
            "id": "wamid.HBgLODUyOTIwMTUxMTgVAgASGCBBQzEwNzNGNjM5RTkwNTcyMjhCN0NEMTQ2QUJERjRCRgA=",
            "referral": {
                "source_url": "https://fb.me/xxx",
                "source_id": "120231520xxx278",
                "source_type": "ad",
                "body": "test",
                "headline": "ok",
                "media_type": "image",
                "image_url": "https://scontent.fhkg5-1.fna.fbcdn.netxxx",
                "ctwa_clid": "xxJnF0_ngg",
                "welcome_message": {
                    "text": "up"
                }
            },
            "text": {
                "body": "H"
            },
            "timestamp": "1761277455",
            "type": "text"
        }
    ],
    "messaging_product": "whatsapp",
    "metadata": {
        "display_phone_number": "xxx",
        "phone_number_id": "xxx"
    },
    "wabaId": "xxx"
}

引用消息响应示例

{
    "app_id": "6741",
    "business_phone": "xxx",
    "channel": 2,
    "contacts": [
        {
            "profile": {
                "name": "xxx"
            },
            "wa_id": "xxx"
        }
    ],
    "merchant_phone": "xxx",
    "messages": [
        {
            "context": {
                "from": "xxx",
                "id": "wamid.bc2f84d43be145b7abb2c93dbd65bcb2",
                "meta_message_id": "wamid.HBgNODYxMzMyMDIzNzQ0NhUCABEYEjgwNjZEMTYxM0U0MEFCOEEwOQA="
            },
            "cost": {
                "cdr_type": 1,
                "currency": "USD",
                "direction": 2,
                "foreign_price": 0,
                "message_id": "wamid.HBgNODYxMzMyMDIzNzQ0NhUCABIYFDJBNzIzNzY1MTVFQTg1N0QxRjUyAA==",
                "price": 0
            },
            "from": "xxx",
            "id": "wamid.HBgNODYxMzMyMDIzNzQ0NhUCABIYFDJBNzIzNzY1MTVFQTg1N0QxRjUyAA==",
            "text": {
                "body": "okk"
            },
            "timestamp": "1761277801",
            "type": "text"
        }
    ],
    "messaging_product": "whatsapp",
    "metadata": {
        "display_phone_number": "xxx",
        "phone_number_id": "xxx"
    },
    "wabaId": "xxx"
}

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

{
    "app_id": "48",
    "business_phone": "xxx",
    "channel": 2,
    "contacts": [
        {
            "profile": {
                "name": "xxx"
            },
            "wa_id": "xxx"
        }
    ],
    "merchant_phone": "xxx",
    "messages": [
        {
            "from": "xxx",
            "id": "wamid.HBgNODYxMzMyMDIzNzQ0NhUCABIYFDJBQzExNjU0QTQwNjYwOUEzOUYxAA==",
            "timestamp": "1761276394",
            "type": "audio",
            "errors": [
                {
                    "code": 131051,
                    "title": "Message type is currently not supported."
                }
            ],
            "cost": {
                "cdr_type": 1,
                "currency": "USD",
                "direction": 2,
                "foreign_price": 0,
                "message_id": "wamid.HBgNODYxMzMyMDIzNzQ0NhUCABIYFDJBQzExNjU0QTQwNjYwOUEzOUYxAA==",
                "price": 0
            }
        }
    ],
    "messaging_product": "whatsapp",
    "metadata": {
        "display_phone_number": "xxx",
        "phone_number_id": "xxx"
    },
    "wabaId": "xxx"
}

心情消息示例

{
    "app_id": "1147",
    "business_phone": "xxx",
    "channel": 2,
    "contacts": [
        {
            "profile": {
                "name": "xxx"
            },
            "wa_id": "xxx"
        }
    ],
    "merchant_phone": "xxx",
    "messages": [
        {
            "cost": {
                "cdr_type": 1,
                "currency": "USD",
                "direction": 2,
                "foreign_price": 0,
                "message_id": "wamid.HBgLNjAxNjM2MDMyMTQVAgASGBQzQUJCQ0IyM0Q3M0NGQ0I2RTM1MwA=",
                "price": 0
            },
            "from": "xxx",
            "id": "wamid.HBgLNjAxNjM2MDMyMTQVAgASGBQzQUJCQ0IyM0Q3M0NGQ0I2RTM1MwA=",
            "reaction": {
                "emoji": "❤️",
                "message_id": "wamid.8e27687b7afe4e9aa10d588709a83ac4",
                "meta_message_id": "wamid.HBgLNjAxNjM2MDMyMTQVAgARGBJCNUU3MkFGMTA4NEJGMDI3NDgA"
            },
            "timestamp": "1761277967",
            "type": "reaction"
        }
    ],
    "messaging_product": "whatsapp",
    "metadata": {
        "display_phone_number": "xxx",
        "phone_number_id": "xxx"
    },
    "wabaId": "xxx"
}

互动消息-通话权限申请反馈示例[接受]

{
    "app_id": "48",
    "business_phone": "xxx",
    "channel": 2,
    "contacts": [
        {
            "profile": {
                "name": "xxx"
            },
            "wa_id": "xxx"
        }
    ],
    "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",
            "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"
}

互动消息-通话权限申请反馈示例[拒绝]

{
    "app_id": "48",
    "business_phone": "xxx",
    "channel": 2,
    "contacts": [
        {
            "profile": {
                "name": "xxx"
            },
            "wa_id": "xxx"
        }
    ],
    "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",
            "id": "wamid.HBgNODYxMzMyMDIzNzQ0NhUCABIYFDNBNUNEQjFBQURBRTk4OTY3REE5AA==",
            "interactive": {
                "call_permission_reply": {
                    "expiration_timestamp": 1756452996,
                    "response": "reject",
                    "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"
}

简介

Home

短信

语音

云呼叫中心（NXLink）

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

Flash Call

短链

邮件验证码

DID号码

通用

号码检测

Viber

Zalo ZNS

Super Message API

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

隐私号(旧)

PNS

坐席（旧版）

AI Agent

Uh oh!

message webhook

消息webhook

验签说明

状态回复【下行消息的状态更新回执】

响应参数

响应示例

消息已发送 sent回执 【带有costs费用信息】

消息已送达 delivered回执

消息已读 read回执

消息发送失败

错误码说明

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

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

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

响应参数

响应示例

文本消息响应示例

图片消息响应示例

视频消息响应示例

音频消息响应示例

文档消息响应示例

位置消息响应示例

贴图表情消息响应示例

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

互动消息列表响应示例

商品消息响应示例

下单消息响应示例

flow表单提交消息响应示例

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

引用消息响应示例

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

心情消息示例

互动消息-通话权限申请反馈示例[接受]

互动消息-通话权限申请反馈示例[拒绝]

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

消息已发送 sent回执【带有costs费用信息】

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