ZOLOZZOLOZDOCS

CallbackMessage

本文详细介绍ZOLOZ Global Chatapp服务的回调协议规范。当您发送的Chatapp消息（例如Whatsapp、Viber）的最终投递状态发生变化时，例如成功送达或发送失败，ZOLOZ会通过HTTP请求主动将状态报告推送到您预先配置的回调地址，帮助您及时获取消息投递结果。

回调机制

ZOLOZ系统接收到Viber官方返回的Chatapp消息（例如Whatsapp、Viber）的投递结果后，会立即将状态信息推送到您预先配置的回调URL。

此过程为异步回调。从API调用成功到收到回调通知的时间间隔通常在几秒到几分钟之间，具体时长取决于Viber官方的处理速度和实时网络状况。

请求内容

请求方式

  • 请求方法：HTTP POST
  • 内容类型：Content-Type为application/json

请求参数

字段名称

数据类型

是否必填

描述

示例值

channelType

String

是

渠道类型，固定值为VIBER。

"VIBER"

transactionId

String

是

消息发送的唯一ID，可通过SendMessage API获取。

"G0062000061MT20230325dAqiXBpQUbVB9h****"

mobile

String

是

接收消息的手机号码，格式为“国际区号+号码”。

"6321245567****"

status

String

是

消息发送状态。取值：

  • Delivered：消息发送成功。
  • DeliveryFailed：消息发送失败。
  • Read：已读消息。
  • Sent：消息已发送。

"Delivered"

sendNum

Int

是

用于计费的消息条数。

1

sendDate

String

是

消息发送时间。

"2024-03-14T20:26:22+08:00"

deliveredDate

String

否

成功发送消息的回执时间。

说明：仅当status设置为Delivered时该参数才生效。

"2024-03-14T20:26:36+08:00"

readDate

String

否

阅读消息时间。

"2024-03-14T20:26:36+08:00"

errorCode

String

否

消息发送失败编码。

"ERROR"

errorMsg

String

否

消息发送失败说明。

"ERROR"

回调示例

copy
{
    "channelType": "VIBER", 
    "transactionId": "G0062000061MT20230325dAqiXBpQUbVB9h****", 
    "mobile": "6321245567****", 
    "Status": "Delivered", 
    "sendNum": 1, 
    "sendDate": "2024-03-14T20:26:22+08:00", 
    "deliveredDate": "2024-03-14T20:26:36+08:00", 
    "readDate": "2024-03-14T20:26:36+08:00", 
    "errorCode": "ERROR", 
    "errorMsg": "ERROR"
}

响应内容

为了确认您已成功接收到回调通知，您的服务器接口必须返回以下响应。

成功响应

HTTP状态码200 OK表示回调成功，且ZOLOZ系统仅以HTTP状态码200作为回调成功的唯一判断标准。响应体内容不用于任何判定，仅供您调试使用。

失败响应

如果您的接口返回任何非200的HTTP状态码或发生网络超时，ZOLOZ系统将判定为回调失败并触发重试机制。

重试机制

为确保回调消息的可靠送达，系统将在回调失败时自动进行重试，具体机制如下：

参数

值

说明

最大重试次数

10次

总共尝试推送10次，包含1次首次请求和9次重试请求。

重试间隔

5秒

每次重试的间隔时间，每间隔5秒重试一次。

请求超时时间

3秒

连接和读取您的接口的超时时间。

当满足以下任一条件时，系统将停止重试：

  • 您的接口成功返回200 OK状态码。
  • 已达到最大重试次数（10次），系统将停止推送该状态报告。

幂等校验

受网络等因素影响，可能导致重复回调，建议接收方根据transactionId字段进行幂等校验处理。