WhatsApp Business API 客户端会发送通知,告知您与用户之间往来消息的 status
。这些通知会通过 statuses
对象发送。
对于公司发送的所有消息,您都会收到关于这些消息状态的通知。在下方表格中,点击左栏中的箭头可了解每种状态在 WhatsApp 应用程序中对应的呈现方式(如有)。
名称 | 描述 |
---|---|
| 用户已删除自己发送的消息。收到此通知时,如果您已从服务器下载该消息,请确保将其从您的系统中删除。 |
| 您公司发送的消息已送达用户设备。 |
| 您公司发送的消息发送失败。回调中将包含失败原因。请查阅错误消息文档,以协助进行调试: |
| 用户已读取您公司发送的消息。 |
| 您公司发送的消息在我们的系统间传递。 本地 API 用户:如要接收 |
| 在您公司发送的消息中,某个项目所在的目录不可用或不存在。 |
这些通知在应用程序中的顺序并不一定反映消息状态的实际时间。如有需要,请查看时间戳来确定时间。
如果消息状态是 read
,则该消息肯定已经是 delivered
状态。在有些情境下,例如当用户正处于聊天界面时收到一条消息,则该消息几乎同时被 delivered
及 read
。在这种或其他类似情景中,应用将不会发送 delivered
通知,因为消息如果已被读取则意味着其已送达。该行为的原因是内部优化。
自 2022 年 2 月 1 日起,出站通知中的 statuses
对象将包含两个新的嵌套对象:conversation
和 pricing
。此对话对象和定价对象的组件因对话发起方或发起位置而异。对话可由用户或商家发起,也可从免费接入点发起。详情请参阅下方:
在以下示例中,recipient_id
可被 group_id
字段取代。这取决于消息是发送给个人还是小组。
当您(商家)在用户发起的对话中发送消息时(如果该对话并非从免费接入点发起),您会收到以下 Webhooks:
{ "statuses": [{ "id": "ID", "recipient_id": "WHATSAPP_ID", "status": "sent", "timestamp": "TIMESTAMP", "type": "message", "message": { "recipient_id":"WHATSAPP_ID" }, "conversation": { "id": "CONVERSATION_ID", "expiration_timestamp": TIMESTAMP, "origin": { "type": "user_initiated" } }, "pricing": { "pricing_model": "CBP", "billable": true, "category": "user_initiated" } }] }
当您(商家)在用户发起的对话中发送消息以回复媒体消息时(如果该对话并非从免费接入点发起),您会收到以下 Webhooks:
{ "statuses": [{ "id": "ID", "recipient_id": "WHATSAPP_ID", "status": "sent", "timestamp": "TIMESTAMP", "type": "message", "message": { "media_id": "98d14c8e-0310-4061-8f99-2d148274c286", "recipient_id":"WHATSAPP_ID" }, "conversation": { "id": "CONVERSATION_ID", "expiration_timestamp": TIMESTAMP, "origin": { "type": "user_initiated" } }, "pricing": { "pricing_model": "CBP", "billable": true, "category": "user_initiated" } }] }
当您(商家)在商家发起的对话中发送消息时,您会收到以下 Webhooks:
{ "statuses": [{ "id": "ID", "recipient_id": "WHATSAPP_ID", "status": "sent", "timestamp": "TIMESTAMP", "type": "message", "message": { "recipient_id":"WHATSAPP_ID" }, "conversation": { "id": "CONVERSATION_ID", "expiration_timestamp": TIMESTAMP, "origin": { "type": "business_initiated" } }, "pricing": { "pricing_model": "CBP", "billable": true, "category": "business_initiated" } }] }
当您(商家)为回复用户发起的对话(从免费接入点发起)而发送消息时,您会收到以下 Webhooks:
{ "statuses": [{ "id": "ID", "recipient_id": "WHATSAPP_ID", "status": "sent", "timestamp": "TIMESTAMP", "type": "message", "message": { "recipient_id":"WHATSAPP_ID" }, "conversation": { "id": "CONVERSATION_ID", "expiration_timestamp": TIMESTAMP, "origin": { "type": "referral_conversion", } }, "pricing": { "pricing_model": "CBP", "billable": false, "category": "referral_conversion" } }] }
当您(商家)在用户发起的对话中发送消息且该消息已送达时(如果该对话并非从免费接入点发起),您会收到以下 Webhooks:
{ "statuses": [{ "id": "ID", "recipient_id": "WHATSAPP_ID", "status": "delivered", "timestamp": "TIMESTAMP", "type": "message", "message": { "recipient_id":"WHATSAPP_ID" }, "conversation": { "id": "CONVERSATION_ID", "origin": { "type": "user_initiated" } }, "pricing": { "pricing_model": "CBP", "billable": true, "category": "user_initiated" } }] }
当您(商家)在商家发起的对话中发送消息且该消息已送达时,您会收到以下 Webhooks:
{ "statuses": [{ "id": "ID", "recipient_id": "WHATSAPP_ID", "status": "delivered", "timestamp": "TIMESTAMP", "type": "message", "message": { "recipient_id": "WHATSAPP_ID" }, "conversation": { "id": "CONVERSATION_ID", "origin": { "type": "business_initiated" } }, "pricing": { "pricing_model": "CBP", "billable": true, "category": "business_initiated" } }] }
当您(商家)在用户发起的对话(从免费接入点发起)中发送消息且该消息已送达时,您会收到以下 Webhooks:
{ "statuses": [{ "id": "ID", "recipient_id": "WHATSAPP_ID", "status": "delivered", "timestamp": "TIMESTAMP", "type": "message", "message": { "recipient_id": "WHATSAPP_ID" }, "conversation": { "id": "CONVERSATION_ID", "origin": { "type": "referral_conversion", } }, "pricing": { "pricing_model": "CBP", "billable": false, "category": "referral_conversion" } }] }
以下是已读取消息的标准回调:
{ "statuses":[{ "id": "ID", "recipient_id": "WHATSAPP_ID", "status": "read", "timestamp": "TIMESTAMP", "type": "message", "message": { "recipient_id": "WHATSAPP_ID" } }] }
{ "statuses": [{ "errors": [{ "code": 470, "title": "Failed to send message because you are outside the support window for freeform messages to this user. Please use a valid HSM notification or reconsider." }], "id": "ID", "recipient_id": "WHATSAPP_ID", "status": "failed", "timestamp": "TIMESTAMP" }] }
{ "statuses": [{ "errors": [{ "code": 480, "title": "Failed to send message since we detect an identity change of the contact" }], "id": "ID", "recipient_id": "WHATSAPP_ID", "status": "failed", "timestamp": "TIMESTAMP" }] }
如果消息发送失败,回调中不会包含 conversation 子版块。在这种情况下,不涉及计费或对话激活。
以下是已删除消息的标准回调:
{ "statuses": [{ "id": "ID", "recipient_id": "WHATSAPP_ID", "status": "deleted", "timestamp": "TIMESTAMP", "type": "message", "message": { "recipient_id": "WHATSAPP_ID" } }] }
如果消息已被删除,回调中不会包含 conversation 子版块。在这种情况下,不涉及计费或对话激活。
详情请参阅概览 > 消息。
Yes, there is a specific scenario where you can get pricing information on your webhook alert for read messages. For each sent message, there can be 3 scenarios:
Scenario | When it Happens |
---|---|
You get a webhook alert when the message is delivered (including pricing information) and another webhook alert when the message is read (not including pricing information). | This is the most common scenario. |
You get a webhook alert when the message is delivered (including pricing information). You do not get a webhook alert that the message has been read. | Common when a customer has turned off the feature that lets people know they have read a message. |
You get a webhook alert when the message is read (including pricing information). You do not get a webhook alert that the message has been delivered. | Only triggered when the user is already reading the thread with the business when the message comes in. |