Webhook API

大约 8 分钟

Webhook API

接口文档变更记录

第几次变更	变更内容	变更人
1	1、增加客服号上下线记录接口	陈超
2	1、增加接口加密逻辑说明(header方式)	陈超

一、接口接入规范

注意: 要接入webhook API，请联系客户成功人员(提供对应的配置webhook的地址、类型）进行配置。

1、交互流程

webhook回调业务时序图

2、接口安全规范

联系管理员获取秘钥（SalesEpoch管理后台获取）
接口请求加密方式-1

此接口加密方式，加密字段是放到接口的请求体（ body）里面。

1、把 tenant_id+timestamp+密钥当做签名字符串（access_token），使用 HmacSHA256 算法计算签名。

    String appSecret = "f9a40a4780f5e1306c46f1c8daecee3b";
    String tenantId = "500975";
    String timestamp = "1666942813620";
    String message = tenantId + timestamp ;
    String access_token = HmacSHA256Util.hmacSHA256(appSecret,message);
    // 小写
    // str = df98eda524132837317c5ea7e4f67ef4224dedc3f01548b6cb211b08eb0328c5

接口请求加密方式-2

此接口加密方式，加密字段是放到请求头（ header）里面。

1、把 tenant_id+timestamp+密钥当做签名字符串（access_token），使用 HmacSHA256 算法计算签名。

    String appSecret = "f9a40a4780f5e1306c46f1c8daecee3b";
    String tenantId = "500975";
    String timestamp = "1666942813620";
    String message = tenantId + timestamp ;
    String access_token = HmacSHA256Util.hmacSHA256(appSecret,message);
    // 小写
    // str = df98eda524132837317c5ea7e4f67ef4224dedc3f01548b6cb211b08eb0328c5

注: 202406之后的新接口全部使用第二种加密方式（请求头传递参数）。

java HmacSHA256加密，可以引用common-codec(1.15)包。

    public static String hmacSha256(String message, String secretKey) {
        return (new HmacUtils(HmacAlgorithms.HMAC_SHA_256, secretKey.getBytes(StandardCharsets.UTF_8))).hmacHex(message.getBytes(StandardCharsets.UTF_8));
    }

3、HTTP 状态码

均以 code 为准

Code	描述	详细解释
200	ok	success!

4、公共参数

参数名	类型	是否必填	备注
accessToken	String	是	签名字符串 token
tenantId	int	是	公司 id
timestamp	Long	是	毫秒时间戳

二、接口列表

1、用户画像信息修改通知

描述 pc 端客户修改用户画像（基本信息、扩展字段）

请求参数

参数名	类型	是否必填	备注
accessToken	String	是	签名字符串 token
tenantId	int	是	公司 id
timestamp	Long	是	毫秒时间戳
data	List	是	格式[{},{}],详细如下(数量 0-50 条)

data 详细参数:

参数名	类型	是否必填	备注
id	String	是	数据 id 标识(uuid)
userName	String	是	坐席登录账号
type	int	是	类型 1、用户画像修改 2、写跟进
friendWhatsId	String	是	修改对象客服号
field	String	是	修改字段项,扩展字段为字段名称如:扩展-附件
fieldType	int	是	字段类型 0、基本字段 1、扩展字段
fieldConfig	int	是	字段配置 1、单行文本 2、多行文本 3、单选 4、多选 5、数值 6、日期 7、时间 8、附件
sourceValue	String	否	修改原值
targetValue	String	否	修改结果
updateAt	String	是	修改时间

示例请求参数:

{
  "accessToken": "83293d01dddd628e3b457142f8a48a0cf4dae3b587e7febea7effea6bdcfd344",
  "tenantId": 500975,
  "timestamp": 1667293135274,
  "data": [
    {
      "id": "a0cb1ad15ed24e618b4b12d9cdff1ad4",
      "type": 1,
      "userName": "张三",
      "friendWhatsId": "8615601882491",
      "field": "Address",
      "fieldType": 0,
      "fieldConfig": 1,
      "sourceValue": "",
      "targetValue": "123123",
      "updateAt": "2022-09-29 20:34:58"
    },
    {
      "id": "81c968134be648e19187db83efa60152",
      "type": 1,
      "userName": "张三",
      "friendWhatsId": "8615601882491",
      "field": "Gender",
      "fieldType": 0,
      "fieldConfig": 3,
      "sourceValue": "MALE",
      "targetValue": "FEMALE",
      "updateAt": "2022-10-02 20:34:58"
    },
    {
      "id": "4d8ac8a3a5164ab2b066dcf8fac5bd45",
      "type": 2,
      "userName": "张三",
      "friendWhatsId": "33758618170",
      "field": "Follow up records",
      "fieldType": 0,
      "fieldConfig": 1,
      "sourceValue": "",
      "targetValue": "{\"data\":{\"text\":\"你好\",\"url\":[]},\"dataTypeMap\":{\"writeFollow\":\"写跟进\"}}",
      "updateAt": "2022-10-31 17:44:06"
    }
  ]
}

写跟进(Follow up records):
fieldType、fieldConfig、fieldType 以上都是初始值
写跟进 sourceValue、 targetValue 为固定格式 data: 数据(text:跟进文本,url:上传文件地址) 、dataTypeMap(value 固定格式) 类型
field 说明
fieldConfig:是我方标识的数据 value 类型、可选择不接收、不是必要字段

field	fieldConfig	说明(sourceValue ->targetValue)
Name(姓名)	单行文本	字符串如:小明 ->小王
Gender(性别)	单选	字符串可选值(MALE、FEMALE、UNKOWNN) 如:MALE -> FEMALE
DOB(生日)	日期	字符串格式(yyyy-MM-dd) 如:2022-12-01-> 2022-12-02
Address(地址)	单行文本	字符串如:上海-> 北京
Email(邮箱)	单行文本	字符串如: 123@qq.com-> 123@163.com
Position(职业)	单行文本	字符串如: 运营->销售
Income(收入)	单行文本	字符串如: 1 万->2 万
Description(备注)	多行文本	字符串 (包含换行符 \n) 如: 1\n2\n3 -> 1\n2\n3\n4
From(客户来源)	单选	字符串根据后台客户管理-设置如:默认 -> 自挖掘
State(阶段)	单选	字符串根据后台客户管理-设置如:新客户 -> 需求匹配
Language(客户语言)	单选	字符串根据后台客户管理-设置如:auto -> am
Tags(标签)	多选	数组字符串根据后台客户管理-设置如:[标签 1] -> [标签 1,标签 2]
多选(扩展字段以自定义名称为准)	多选	数组字符串根据后台客户管理-设置如:[多选 1] -> [多选 1,多选 2]
时间(扩展字段以自定义名称为准)	时间	字符串格式(HH:mm:ss) 如:17:26:59-> 17:27:35
附件(扩展字段以自定义名称为准)	附件	字符串格式(,http 分隔) 如:http://123.img,http://456.img

返回值
参数名类型是否必填备注
code int 是状态码
message String 是描述
data String 是数据
- 举例如下:
```
{
  "code": 200,
  "message": "",
  "data": ""
}
```

参数名	类型	是否必填	备注
code	int	是	状态码
message	String	是	描述
data	String	是	数据

2、消息同步

描述
客户端收发消息同步

请求参数说明

参数名	类型	是否必填	备注
accessToken	String	是	签名字符串 token
tenantId	int	是	公司 id
timestamp	Long	是	毫秒时间戳
data	List	是	格式[{},{}],详细如下(数量 0-50 条)

data 参数说明:

参数名	类型	是否必填	备注
id	String	是	数据 id 标识(uuid)
messageId	String	是	消息 id
userName	String	是	坐席登录账号
whatsId	String	是	消息发送whatsapp（个人指谁发送的消息，群聊指群里谁发送的消息）
friendWhatsId	String	是	好友whatsapp （当类型为群聊的时候是群名称）
currentWhatsId	String	是	当前客服号
actionType	int	是	行为类型 1、发消息 2、收消息
chatType	int	是	聊天性质 1、普通聊天 2、群聊
messageStatus	int	是	消息状态 1、已发送（客户端） 3、已到达 4、已读
content	String	是	内容(详细如下)
contentType	int	是	内容类型 0、普通文字 1、图片 2、视频 3、音频 4、文件
sendTime	String	是	消息聊天时间
originType	int	是	来源 1、pc 2、app 3、web
userProfile	object	是	好友用户画像

data 参数 messageStatus 发生变更时会重新同步状态,其他内容不变

content 参数说明:
参数名类型是否必填备注
filename String 是文件名称
url String 是文件地址
mimeType String 是 mime 类型
caption String 是文件说明
- 当内容类型为 1,2,3,4 时:
1 图片: image/jpeg、image/png、image/webp
2 视频: video/mp4
3 音频: audio/aac、audio/m4a、audio/amr、audio/mpeg、audio/ogg; codecs=opus、codecs=opus
4 文件: application/pdf、application/msword、application/ppt、application/xls

参数名	类型	是否必填	备注
filename	String	是	文件名称
url	String	是	文件地址
mimeType	String	是	mime 类型
caption	String	是	文件说明

userProfile 参数说明

参数名	类型	是否必填	备注
id	Long	是	客户id
name	String	是	客户昵称
whatsApp	String	是	客户whastapp
username	String	是	负责人名字
income	String	是	收入
profession	String	是	职业
desc	String	是	备注
tags	array	是	标签
email	String	是	邮箱地址
address	String	是	地址
extendsMap	String	是	扩展信息(json字符串)

请求示例:

{
    "accessToken": "e6e18763d8212d26ced4f92512881c63c468d5a756d45c01486d7ad6742152ac",
    "tenantId": 1238,
    "timestamp": 1667295870936,
    "data": [
        {
            "id": "30e873ab8f4840e2b610c414fe967327",
            "messageId": "7a324c7b5512468cb7a9296af0f8379b",
            "userName": "gdkj002",
            "whatsId": "8617633819542@c.us",
            "friendWhatsId": "8615601882491@c.us",
            "currentWhatsId": "8617633819542@c.us",
            "actionType": 1,
            "chatType": 1,
            "messageStatus": 1,
            "content": "再见",
            "contentType": 0,
            "originType": 1,
            "sendTime": "2022-10-31 16:25:42",
            "userProfile":{
                "id":8423922419416375296,
                "name":"好友1",
                "whatsApp":"447759820897",
                "username":"testlsl001",
                "extendsMap":"{\"单行文本\":\"caseId009\",\"多选\":\"[]\",\"日期\":\"\"}",
                "income":"",
                "profession":"",
                "desc":"",
                "tags":[
                    "测试",
                    "测试000000000000000000",
                    "11111"
                ],
                "email":"",
                "address":"北京"
            }
        },
        {
            "id": "31057e55b9f842b4becf4a9ff699b64e",
            "messageId": "82bfefadceb948428fd3f3ef659e14b3",
            "userName": "gdkj002",
            "whatsId": "8617633819542@c.us",
            "friendWhatsId": "8615601882491@c.us",
            "currentWhatsId": "8617633819542@c.us",
            "actionType": 1,
            "chatType": 1,
            "messageStatus": 1,
            "content": "{"caption":"","filename":"","mimetype":"video/mp4","url":"https://image.whatsappscrm.com/client/603704/chat_history/1665198225749_video"}",
            "contentType": 2,
            "originType": 1,
            "sendTime": "2022-10-31 16:25:42",
            "userProfile":{
                "id":8423922419416375296,
                "name":"好友2",
                "whatsApp":"447759820897",
                "username":"testlsl001",
                "extendsMap":"{\"单行文本\":\"caseId007\",\"多选\":\"[]\",\"日期\":\"\"}",
                "income":"100002",
                "profession":"IT",
                "desc":"备注",
                "tags":[
                    "测试",
                    "测试000000000000000000",
                    "11111"
                ],
                "email":"",
                "address":"北京"
            }
        }
    ]
}

返回参数说明
参数名类型是否必填备注
code int 是状态码
message String 否描述
data String 否数据

参数名	类型	是否必填	备注
code	int	是	状态码
message	String	否	描述
data	String	否	数据

响应示例:

{
  "code": 200,
  "message": "success!",
  "data": ""
}

3、群行为埋点通知

当 whatsapp 触发加群退群动作时，主动推送通知成员加群、退群的日志

3.1 推送数据

请求参数说明

字段	类型	是否必填	备注
accessToken	String	是	签名字符串 token
tenantId	int	是	公司 id
timestamp	Long	是	毫秒时间戳
data	List	是	格式[{},{}],详细如下(数量 0-50 条

data 参数说明

字段	类型	是否必填	备注
id	String	是	数据 id 标识(uuid)
friendWhatsId	String	是	whatsapp 手机号
actionType	int	是	1 进群 2 退群
createTime	String	是	操作时间，进群时间或者退群时间
groupWhatsId	String	是	群 ID
groupLink	String	否	群链接
dataType	int	是	是否是虚拟数据数据类型 1 真实 2 虚拟

请求示例

{
  "accessToken": "e6e18763d8d5a756d45c01486d7ad6742152ac",
  "callBackUrl": "host/wscrm-bus-api/part/callback/groupAction",
  "tenantId": 1238,
  "timestamp": 1667295870936,
  "data": [
    {
      "id": "30e873ab8f4840e2b610c414fe967327",
      "friendWhatsId": "8617633819542",
      "actionType": 1,
      "create_time": "2023-02-01 00:00:00",
      "groupWhatsId": "120xxxxx",
       "dataType": 1,
      "groupLink": "https://chat.xxx.com/CEwwCoiy7Qa1MVKex3x4p4"
    }
  ]
}

响应示例

{
  "code": 200,
  "message": "Success",
  "data": ""
}

4、客服号上下线通知

注: 接口加密规则使用header头的方式！！！

类型
WebHook
URI
/api/callback/whatsapp/onlineStatus
请求方式
POST、Content-Type: application/json
请求参数说明

字段	类型	是否必填	备注
whatsAppList	List	是	格式[{},{}],详细如下(数量 0-50 条

whatsAppList 参数说明

字段	类型	是否必填	备注
whatsId	String	是	whatsapp 手机号
status	int	是	状态 10、在线 20、掉线 30、离线 40、死号
detailStatus	int	是	详细状态 (具体请查看下面注释)
account	String	是	坐席账号
platformType	int	是	平台类型 1、pc 2、android
time	String	是	时间 2024-06-27 19:52:12

详细状态介绍: 11、PC扫码登录 12、PC上线 21、PC掉线 31、PC关闭客户号离线 32、PC关闭客户端离线33、PC触发监控下线41、封号

请求示例

[
    {
      "whatsId": "8617633819542",
      "status": 1,
      "detailStatus": 11,
      "account":"",
      "time":"2024-07-03 15:27:00",
      "platformType":1
    },
    {
      "whatsId": "8617633819542",
      "status": 1,
      "detailStatus": 11,
      "account":"",
      "time":"2024-07-03 15:27:00",
      "platformType":1
    }
  ]
}

响应示例

{
  "code": 200,
  "message": "Success",
  "data": ""
}

三、常见问题

通知失败重试次数
说明:通知进行同步后,不响应或不为 200 的状态码均为失败,5 次以上将关闭该类型的 WebHook 配置信息.
配置关闭如何处理
说明:关闭配置后,仍进行数据的采集但不进行同步,当配置打开后以 10 分钟为间隔进行一次检测,检测到打开
后进行同步所有的历史数据。
时区
UTC+8

Webhook API

# Webhook API

# 接口文档变更记录

# 一、 接口接入规范

# 1、交互流程

# 2、接口安全规范

# 3、HTTP 状态码

# 4、公共参数

# 二、 接口列表

# 1、用户画像信息修改通知

# 2、消息同步

# 3、群行为埋点通知

# 3.1 推送数据

# 4、客服号上下线通知

# 三、常见问题

Webhook API

接口文档变更记录

一、接口接入规范

1、交互流程

2、接口安全规范

3、HTTP 状态码

4、公共参数

二、接口列表

1、用户画像信息修改通知

2、消息同步

3、群行为埋点通知

3.1 推送数据

4、客服号上下线通知

三、常见问题