Fila 回调 API 文档

1. 回调管理接口

通过 GuidRequest 接口（OpenApp 鉴权）管理回调 URL，设置后设备事件自动 POST 到指定地址。

2. 回调推送格式

设置回调后，设备事件会以 HTTP POST 推送到 callback_url。

2.1 HTTP 请求

POST {callback_url}
Content-Type: application/json
AppKey: {open_app 的 app_key}
AppSecret: {open_app 的 app_secret}

2.2 推送 JSON 结构

{
  "guid": "ad1615a1ee59860e",
  "notify_type": 1,
  "payload": { ... }
}

2.3 事件类型

notify_type	类型	说明
1	设备上线	设备连接成功，含企微用户资料
2	设备下线	设备断开连接
3	新消息	收到聊天消息（数组）
4	客户申请	收到好友申请
5	客户变更	联系人信息变更
6	群信息变更	群名/群成员等变更

3. 各事件 payload 详情

notify_type: 1 — 设备上线

{
  "guid": "ad1615a1ee59860e",
  "notify_type": 1,
  "payload": {
    "profile": {
      "user_id": "1688853377964182",
      "name": "张三",
      "avatar": "https://wx.qlogo.cn/xxx"
    }
  }
}

字段	类型	说明
profile.user_id	string	企微 uin
profile.name	string	用户昵称
profile.avatar	string	头像 URL

notify_type: 2 — 设备下线

{
  "guid": "ad1615a1ee59860e",
  "notify_type": 2,
  "payload": {
    "profile": {
      "user_id": "1688853377964182",
      "name": "张三"
    },
    "scene": 1
  }
}

字段	类型	说明
profile.user_id	string	企微 uin
profile.name	string	用户昵称
scene	int	下线场景

notify_type: 3 — 新消息

{
  "guid": "ad1615a1ee59860e",
  "notify_type": 3,
  "payload": {
    "messages": [
      {
        "msg_id": "1234567890",
        "from_user_id": "1688853377964182",
        "to_user_id": "vid_xxx",
        "msg_type": 1,
        "create_time": 1718000000,
        "content": "Hello"
      }
    ]
  }
}

字段	类型	说明
messages	array	消息对象数组（JSON 对象，非字符串）

messages 为 JSON 对象数组，每条消息的具体字段取决于 msg_type（文本/图片/文件等）。

notify_type: 4 — 客户申请

{
  "guid": "ad1615a1ee59860e",
  "notify_type": 4,
  "payload": null
}

当前版本 payload 暂无数据，后续迭代补充。

notify_type: 5 — 客户变更

{
  "guid": "ad1615a1ee59860e",
  "notify_type": 5,
  "payload": null
}

当前版本 payload 暂无数据，后续迭代补充。

notify_type: 6 — 群信息变更

{
  "guid": "ad1615a1ee59860e",
  "notify_type": 6,
  "payload": {
    "room_id": "1234567890",
    "operator_id": "1688853377964182"
  }
}

字段	类型	说明
room_id	string	群 ID
operator_id	string	操作者企微 uin

4. 补充说明

guid 是设备 device_id（手机硬件 ID），不是企微 uin

payload 字段为 snake_case 格式（如 user_id、room_id、operator_id）

HTTP 头自动携带 AppKey + AppSecret（来自设置回调的 OpenApp）

推送失败不重试，仅记录日志

回调格式

Fila 回调 API 文档#

1. 回调管理接口#

2. 回调推送格式#

2.1 HTTP 请求#

2.2 推送 JSON 结构#

2.3 事件类型#

3. 各事件 payload 详情#

notify_type: 1 — 设备上线#

notify_type: 2 — 设备下线#

notify_type: 3 — 新消息#

notify_type: 4 — 客户申请#

notify_type: 5 — 客户变更#

notify_type: 6 — 群信息变更#

4. 补充说明#