消息回调 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"},取值如下:
  • business_initiated:示对话由企业向客户发送第一条消息开始。这适用于距离最后一条客户消息超过 24 小时的任何时间。
  • customer_initiated:示对话是由企业回复客户消息开始的。这仅适用于业务回复距离最后一条客户消息在 24 小时内的情况。
  • referral_conversion:示对话源自一个 自由入口点。这些对话总是由客户发起的。
  • pricing
    字段 类型 选项 描述
    pricing_model String 可选 固定取值为 CBP
    category String 可选 对话定价类别,取值如下:
  • business_initiated:商家对话。
  • customer_initiated: 用户对话。
  • referral_conversion: 免费接入点对话。
  • error_detail

    字段 类型 选项 描述
    message String 必填 错误原因

    loss

    字段 类型 选项 描述
    loss_step int 必填 折损阶段
  • 1:计划目标 ~ 有效目标,即无效目标
  • 2:有效目标 ~ 发送,即发送失败
  • 3:发送 ~ 送达。即送达失败
  • loss_source String 必填 折损来源,取值:
  • engagelab:EngageLab WhatsApp 服务进行校验产生的折损
  • meta:Meta 官方返回的错误
  • 回调示例

    { "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"
                            }
                        }
                    }
                }
            }
        ]
    }
    
            
    此代码块在浮窗中显示
    在文档中心打开