消息回调 API
最新更新:2023-11-27
概述
将「消息状态」和「消息响应」的数据回调给企业的业务系统,可根据该信息进行统计、回复用户等动作。
回调地址
企业需要设置接收「消息状态」以及「消息响应」的回调地址,详情参见 回调设置。
回调格式
请求方式是 POST,请求体为 JSON,数据类型:"Content-Type: application/json"
一次请求将批量返回多条数据。
安全机制
待上线。目前回调暂未带上鉴权信息,故开发者接收回调的接口请不要设置权限验证。
应答机制
开发者服务接收到 Engagelab 的回调后,需要在 3 秒内按下述要求进行应答。
接收成功:HTTP 应答状态码需返回 200 ,无需返回应答报文。
重试机制
待上线。
请求参数
EngageLab 向业务系统的回调地址发起的请求参数如下:
字段 | 类型 | 选项 | 描述 |
---|---|---|---|
total | int | 必填 | 回调的数据量 |
rows | JSON Array | 必填 | 回调的详细信息 |
rows 中的参数如下:
字段 | 类型 | 选项 | 描述 |
---|---|---|---|
message_id | string | 可选 | 消息状态以及消息响应的时候返回。 |
from | string | 可选 | 发送方,消息状态以及上行消息的时候返回 |
to | string | 可选 | 接收方,消息状态以及上行消息的时候返回 |
server | string | 必选 | 回调信息所属的产品服务,固定取值 whatsapp |
channel | string | 可选 | 该状态或者响应属于哪一个通道,固定取值 whatsapp |
itime | int | 必选 | 回调数据真实产生的时间戳,与 message_status 字段相结合,可以得到:请求时间戳、发送时间戳、送达时间戳、已读时间戳 |
custom_args | JSON Object | 可选 | 在消息发送时自定义的可选字段,在消息状态回调中原样返回。 |
status | JSON Object | 可选 | 消息状态字段 |
response | JSON Object | 可选 | 消息响应字段 |
消息状态-status
回调参数
字段 | 类型 | 选项 | 描述 |
---|---|---|---|
message_status | string | 必选 | 消息的状态 |
status_data | JSON Object | 可选 | 该状态下的详细数据 |
error_code | int | 可选 | 错误码,失败时返回 |
error_detail | JSON Object | 可选 | 错误详情,失败时返回 |
loss | JSON Object | 可选 | 折损阶段和折损来源 |
message_status
取值 | 描述 | 定义 |
---|---|---|
plan | 计划发送 | 该号码在传递的「收件人号码」内,即为该号码记录 1 个计划发送目标的状态 |
target_valid | 目标有效 | 通过合法性校验 1、该号码被 EngageLab 判定为合法 2、该号码被 Meta WhatsApp 服务判定为合法 |
sent | 发送成功 | 该号码由 EngageLab 提交给 Meta WhatsApp 服务后返回了成功 |
delivered | 送达成功 | 由 Meta WhatsApp 服务确认消息已送达用户 |
read | 已读 | 由 Meta WhatsApp 服务确认用户已读消息 |
target_invalid | 目标无效 | 1、该号码被 EngageLab 判定为非法 2、该号码被 Meta WhatsApp 服务判定为非法 |
sent_failed | 发送失败 | 该号码提交给 Meta WhatsApp 服务后返回了失败 |
delivered_failed | 送达失败 | 该号码提交给 Meta WhatsApp 服务成功,但 Meta 回调告知失败。 |
delivered_timeout | 超时未送达 | 该号码提交给 Meta WhatsApp 服务成功,但在 5 分钟内 Meta 未回调告知是否成功/失败,计为超时。 |
status_data
字段 | 类型 | 选项 | 描述 |
---|---|---|---|
msg_time | int | 必填 | 消息下发时间,调用 API 请求发送消息成功的时间点 |
channel_message_id | String | 必填 | WhatsApp 官方返回的消息 ID |
whatsapp_business_account_id | String | 必填 | 发送号所属的 WhatsApp 商业账户的编号 |
timezone | String | 必填 | 组织所在时区 |
plan_user_total | int | 可选 | 计划目标总数,只有当 message_status=plan 时这个才会有值 |
country_code | String | 必填 | 接收方手机号码归属的国家/地区代码 |
from_phone_id | String | 必填 | 发送号码(from)的 ID 标识 |
conversation | JSON Object | 可选 | 会话信息 |
pricing | JSON Object | 可选 | 价格信息 |
conversation
字段 | 类型 | 选项 | 描述 |
---|---|---|---|
id | String | 可选 | 该条消息所属的 Meta 对话 ID |
origin | JSON Object | 可选 | 表示是由谁发起的对话。由 type 指定。 示例:"origin":{"type":"business_initiated"},取值如下: |
pricing
字段 | 类型 | 选项 | 描述 |
---|---|---|---|
pricing_model | String | 可选 | 固定取值为 CBP |
category | String | 可选 | 对话定价类别,取值如下: |
error_detail
字段 | 类型 | 选项 | 描述 |
---|---|---|---|
message | String | 必填 | 错误原因 |
loss
字段 | 类型 | 选项 | 描述 |
---|---|---|---|
loss_step | int | 必填 | 折损阶段 |
loss_source | String | 必填 | 折损来源,取值: |
回调示例
{
"total": 1,
"rows": [
{
"message_id": "1666165485030094861", // EngageLab 的消息 id
"from": "", // 发送方
"to": "", // 接收方
"server": "whatsapp",
"channel": "whatsapp",
"itime": 1640707579, // 消息状态产生的时间戳,如消息已送达的时间
"custom_args": {}, // 这条消息创建时提交的参数,将于此回调时原样返回
"status": {
// 成功时响应这些字段
"message_status": "delivered" // 消息状态
"status_data": { // 自定义
"msg_time": 1663432355, // 消息下发时间,历史记录上的消息发送时间,即用户调用 API 发送消息-调用 API 成功的那个时间
"channel_message_id": "wamid.123321abcdefed==", // 可选,Meta 返回的 msgid
"whatsapp_business_account_id": "", //发送号 from 对应的 Whatsapp 商业账户编码
"timezone": "", //组织时区
"plan_user_total": 2007, //计划目标总数,只有当 message_status=plan 时这个才会有值
"country_code": "CN", //接收方手机号码归属的国家/地区代码
"from_phone_id": "111111" // 发送号码(from)的 ID 标识
"conversation": { // 可选,会话信息
"id": "ebe2398cdaa37a0899ca5268b987b0c8",
"origin": {
"type": "business_initiated"
}
},
"pricing": { // 可选,价格信息
"pricing_model": "CBP",
"category": "business_initiated"
}
},
// 失败状态下(无效目标、发送失败、送达失败、未读)返回这些字段
"error_code": 0, //错误码
"error_detail": {
"message": "" //错误原因
},
"loss": {
"loss_step": 1,
"loss_source": "aa"
}
}
}
]
}
{
"total": 1,
"rows": [
{
"message_id": "1666165485030094861", // EngageLab 的消息 id
"from": "", // 发送方
"to": "", // 接收方
"server": "whatsapp",
"channel": "whatsapp",
"itime": 1640707579, // 消息状态产生的时间戳,如消息已送达的时间
"custom_args": {}, // 这条消息创建时提交的参数,将于此回调时原样返回
"status": {
// 成功时响应这些字段
"message_status": "delivered" // 消息状态
"status_data": { // 自定义
"msg_time": 1663432355, // 消息下发时间,历史记录上的消息发送时间,即用户调用 API 发送消息-调用 API 成功的那个时间
"channel_message_id": "wamid.123321abcdefed==", // 可选,Meta 返回的 msgid
"whatsapp_business_account_id": "", //发送号 from 对应的 Whatsapp 商业账户编码
"timezone": "", //组织时区
"plan_user_total": 2007, //计划目标总数,只有当 message_status=plan 时这个才会有值
"country_code": "CN", //接收方手机号码归属的国家/地区代码
"from_phone_id": "111111" // 发送号码(from)的 ID 标识
"conversation": { // 可选,会话信息
"id": "ebe2398cdaa37a0899ca5268b987b0c8",
"origin": {
"type": "business_initiated"
}
},
"pricing": { // 可选,价格信息
"pricing_model": "CBP",
"category": "business_initiated"
}
},
// 失败状态下(无效目标、发送失败、送达失败、未读)返回这些字段
"error_code": 0, //错误码
"error_detail": {
"message": "" //错误原因
},
"loss": {
"loss_step": 1,
"loss_source": "aa"
}
}
}
]
}
此代码块在浮窗中显示
消息响应
回调参数
字段 | 类型 | 选项 | 描述 |
---|---|---|---|
event | string | 可选 | 响应事件 |
response_data | JSON Object | 可选 | 上行回复/交互的消息内容 |
event
取值 | 描述 | 详细说明 |
---|---|---|
received | 收到用户的消息 | 用户直接发送了一条消息 |
reply | 用户回复了你的消息 | 企业先发送了消息给用户,用户选择对该条信息进行回复 |
order | 用户下订单 | - |
deleted | 用户删除了他的消息 | 用户将自己发出的消息删除了(待上线) |
response_data
字段 | 类型 | 选项 | 描述 |
---|---|---|---|
channel_message_id | String | 必填 | WhatsApp 官方返回的消息 ID |
whatsapp_business_account_id | String | 必填 | 发送号所属的 WhatsApp 商业账户的编号 |
contact | JSON Object | 可选 | 发送方信息 |
message | JSON Object | 必填 | 消息内容 |
contact
字段 | 类型 | 选项 | 描述 |
---|---|---|---|
profile | JSON Object | 可选 | 发送方(客户)的资料,当前仅有 name 字段表示客户的姓名。 示例:"profile": {"name": "bob"} |
wa_id | String | 可选 | 发送方的号码 |
message
字段 | 类型 | 选项 | 描述 |
---|---|---|---|
type | String | 必填 | 取值:text、image、audio、video、document、sticker、button、interactive、unknown、order |
text | JSON Object | 可选 | 详见 text object 说明 |
image | JSON Object | 可选 | 详见 image object 说明 |
audio | JSON Object | 可选 | 详见 audio object 说明 |
video | JSON Object | 可选 | 详见 video object 说明 |
document | JSON Object | 可选 | 详见 document object 说明 |
sticker | JSON Object | 可选 | 详见 sticker object 说明 |
回调示例
{
"total": 1,
"rows": [
{
"message_id": "1666165485030094861", // 极光侧的消息 id
"from": "", // 发送方,即客户的手机号码
"to": "", // 接收方,即开发者的发送号
"server": "whatsapp",
"channel": "whatsapp",
"itime": 1640707579, // 时间戳
"response": {
"event": "", // 响应事件
"response_data": { // 具体消息内容
"channel_message_id": "wamid.123321abcdefed==", // 可选,Meta 返回的 msgid
"whatsapp_business_account_id": "123321", //开发者的发送号 to 对应的 Whatsapp 商业账户编码
"contact": { // 可选,发送方信息
"profile": {
"name": "bob" // 发送方的昵称
},
"wa_id": "8613800138000" // 发送方的号码
},
"message": { // 具体消息内容
"type": "text", // 消息的类型,可以根据这个值来识别具体消息字段,如 text 则内容为 text 字段
"text": { // 消息内容
"body": "here is the message content text"
}
}
}
}
}
]
}
{
"total": 1,
"rows": [
{
"message_id": "1666165485030094861", // 极光侧的消息 id
"from": "", // 发送方,即客户的手机号码
"to": "", // 接收方,即开发者的发送号
"server": "whatsapp",
"channel": "whatsapp",
"itime": 1640707579, // 时间戳
"response": {
"event": "", // 响应事件
"response_data": { // 具体消息内容
"channel_message_id": "wamid.123321abcdefed==", // 可选,Meta 返回的 msgid
"whatsapp_business_account_id": "123321", //开发者的发送号 to 对应的 Whatsapp 商业账户编码
"contact": { // 可选,发送方信息
"profile": {
"name": "bob" // 发送方的昵称
},
"wa_id": "8613800138000" // 发送方的号码
},
"message": { // 具体消息内容
"type": "text", // 消息的类型,可以根据这个值来识别具体消息字段,如 text 则内容为 text 字段
"text": { // 消息内容
"body": "here is the message content text"
}
}
}
}
}
]
}
此代码块在浮窗中显示