企业微信数据与智能专区 SDK 实战指南：会话记录获取与消息统计（Senparc.Weixin.Work DataIntelligenceApi）

后端即时通讯金融科技【免费下载链接】WeiXinMPSDK微信全平台 .NET SDK Senparc.Weixin for C#支持 .NET Framework 及 .NET Core、.NET 10.0。已支持微信公众号、小程序、小游戏、微信支付、企业微信/企业号、开放平台、JSSDK、微信周边等全平台。 WeChat SDK for C#.项目地址https://gitcode.com/gh_mirrors/we/WeiXinMPSDK点击查看免费下载本文以仓库内 DataIntelligence/README.md 为核心骨架结合 DataIntelligenceApi.cs 源码与 DataIntelligenceTest.cs 测试用例展开。文中所有代码示例可直接复制到使用 Senparc.Weixin.Work 的项目中运行。一、概述数据与智能专区是什么在 WeiXinMPSDKSenparc.Weixin中数据与智能专区Data Intelligence是企业微信开放平台面向数据分析与智能化应用开放的一组高级接口。它围绕两大核心诉求设计会话记录获取GetConversationRecords拉取企业微信内部单聊、群聊的历史消息内容用于客服质检、合规审计、会议归档、团队沟通模式分析等场景消息统计GetMessageStatistics按天/周/月维度统计消息收发总量、各类型消息数量、活跃用户数、活跃群聊数用于生成企业沟通报表、评估协作活跃度。在仓库中这组能力由Senparc.Weixin.Work.AdvancedAPIs.DataIntelligence命名空间下的DataIntelligenceApi静态分部类提供源码位于 src/Senparc.Weixin.Work/Senparc.Weixin.Work/AdvancedAPIs/DataIntelligence/ 目录。该 API 类声明了[NcApiBind(NeuChar.PlatformType.WeChat_Work, true)]特性表明它是面向企业微信Work平台的绑定接口可直接被 NeuChar 平台识别与调用。从源码看DataIntelligenceApi内部封装了两个请求端点DataIntelligenceApi.cs#L42-L43private static string _urlFormatGetConversationRecords Config.ApiWorkHost /cgi-bin/data/get_conversation_records?access_token{0}; private static string _urlFormatGetMessageStatistics Config.ApiWorkHost /cgi-bin/data/get_message_statistics?access_token{0};所有请求均通过CommonJsonSend.SendT/SendAsyncT以POST方式提交 JSON 请求体并自动处理 access_token 注入与基础错误包装。二、使用前置条件在调用DataIntelligenceApi之前需要确认以下几点前置项说明权限开通需要企业微信管理员为企业开通数据与智能专区相关权限未开通时接口会返回权限错误详见下文错误处理章节数据授权只能获取已授权的会话和用户数据涉及员工隐私的数据需要按企业微信要求完成知情同意/授权流程调用凭证传入accessTokenOrAppKey参数即 AccessToken 或 AppKey。AppKey 可通过AccessTokenContainer.BuildingKey(corpId, corpSecret)获得SDK 会在内部自动换取/刷新 AccessTokenSDK 版本数据与智能专区接口自较新版本引入源码注释显示创建于 20241128 前后请使用包含该命名空间的 Senparc.Weixin.Work 版本获取 AccessToken 的典型方式在测试用例 DataIntelligenceTest.cs#L46 中可以看到标准取法var accessToken AccessTokenContainer.GetToken(_corpId, base._corpSecret);其中_corpId为企业 CorpId_corpSecret为应用的 Secret。你也可以直接传入由AccessTokenContainer.BuildingKey(corpId, corpSecret)生成的 AppKey 字符串ApiHandlerWapper.TryCommonApi会在调用链内部完成 AccessToken 的解析与容错处理。三、获取会话记录GetConversationRecords3.1 方法签名与参数说明DataIntelligenceApi为会话记录提供了参数式与请求对象式两套重载同步 异步完整定义见 DataIntelligenceApi.cs。参数式同步方法签名#L59public static GetConversationRecordsResult GetConversationRecords( string accessTokenOrAppKey, // AccessToken 或 AppKey string chatId, // 会话ID可通过会话创建接口获得 DateTime startTime, // 开始时间 DateTime endTime, // 结束时间 string cursor , // 分页游标首次查询传空字符串 int limit 100, // 每页数量最大1000 int timeOut Config.TIME_OUT // 超时时间 )各参数要点chatId会话ID单聊或群聊的会话标识可通过企业微信会话创建接口获得startTime / endTime时间范围。SDK 内部通过DateTimeHelper.GetUnixDateTime(DateTime)自动将DateTime转换为 Unix 秒级时间戳见 DataIntelligenceApi.cs#L66-L67无需手动换算cursor分页游标首次调用传空字符串后续分页使用返回结果中的next_cursorlimit分页数量默认 100最大 1000。源码在参数式重载中使用Math.Min(limit, 1000)强制限制#L69请求对象式重载中同样有if (request.limit 1000) request.limit 1000;的保护#L89-L92即即使你传入超过 1000 的值SDK 也会自动收敛到 1000测试用例 LimitValidationTest 正是验证了这一行为传入 1500 期望被自动调整为 1000。3.2 基本用法参数式// 使用参数方式调用 var result DataIntelligenceApi.GetConversationRecords( accessToken, // AccessToken或AppKey your_chat_id, // 会话ID DateTime.Now.AddDays(-7), // 开始时间 DateTime.Now, // 结束时间 , // 分页cursor首次查询传空字符串 100 // 每页数量最大1000 );3.3 基本用法请求对象式请求对象GetConversationRecordsRequest定义在 GetConversationRecordsRequest.cs字段与参数式一一对应var request new GetConversationRecordsRequest { chatid your_chat_id, starttime DateTimeOffset.Now.AddDays(-7).ToUnixTimeSeconds(), // Unix时间戳 endtime DateTimeOffset.Now.ToUnixTimeSeconds(), // Unix时间戳 cursor , limit 100 }; var result DataIntelligenceApi.GetConversationRecords(accessToken, request);请求字段类型说明chatidstring会话IDstarttimelong开始时间Unix 秒级时间戳endtimelong结束时间Unix 秒级时间戳cursorstring分页游标初始传空limitint分页数量默认 100最大 10003.4 异步调用异步方法同样提供参数式与请求对象式两种重载命名统一为GetConversationRecordsAsync且内部通过ConfigureAwait(false)避免上下文捕获开销#L159-L195// 异步方式调用 var result await DataIntelligenceApi.GetConversationRecordsAsync( accessToken, your_chat_id, DateTime.Now.AddDays(-7), DateTime.Now );3.5 完整分页处理循环会话记录接口采用 cursor 游标分页。返回结果中的has_more标记是否还有更多数据next_cursor给出下一页游标。以下循环可完整拉取某时间段的全部记录string cursor ; var allRecords new ListConversationRecord(); var startTime DateTime.Now.AddDays(-7); var endTime DateTime.Now; do { var result DataIntelligenceApi.GetConversationRecords( accessToken, your_chat_id, startTime, endTime, cursor, 1000); if (result.errcode ReturnCode_Work.请求成功) { allRecords.AddRange(result.records); cursor result.next_cursor; // 检查是否还有更多数据 if (!result.has_more) break; } else { Console.WriteLine($错误: {result.errmsg}); break; } } while (!string.IsNullOrEmpty(cursor));从源码结构可以推断分页约定的要点GetConversationRecordsResult继承自WorkJsonResult除标准errcode/errmsg外包含三个业务字段has_more是否还有更多、next_cursor下次游标、records记录数组见 GetConversationRecordsResult.cs#L20-L36当has_more为false或next_cursor为空字符串时终止循环双条件均可作为结束信号。四、获取消息统计GetMessageStatistics4.1 方法签名与参数说明消息统计接口用于获取企业微信中的消息统计信息支持按天、周、月统计。同步参数式方法签名#L110public static GetMessageStatisticsResult GetMessageStatistics( string accessTokenOrAppKey, // AccessToken 或 AppKey DateTime startTime, // 统计开始时间 DateTime endTime, // 统计结束时间 string type day, // 统计类型day/week/month string agentId null, // 应用ID为空时统计全部应用 string[] userIds null, // 用户ID列表为空时统计全部用户 int timeOut Config.TIME_OUT )参数说明参数默认值说明startTime/endTime必填统计时间范围SDK 内部自动转为 Unix 时间戳typeday统计粒度day按天、week按周、month按月agentIdnull应用ID传null表示统计全部应用userIdsnull用户ID数组传null表示统计全部用户4.2 基本用法参数式// 获取过去30天的日统计数据 var result DataIntelligenceApi.GetMessageStatistics( accessToken, DateTime.Now.AddDays(-30), // 开始时间 DateTime.Now, // 结束时间 day, // 统计类型day/week/month null, // 应用IDnull表示全部应用 null // 用户ID列表null表示全部用户 ); // 获取特定应用和用户的统计 var result2 DataIntelligenceApi.GetMessageStatistics( accessToken, DateTime.Now.AddDays(-7), DateTime.Now, day, your_agent_id, new[] { user1, user2, user3 } );4.3 使用请求对象请求对象GetMessageStatisticsRequest定义在 GetMessageStatisticsRequest.csvar request new GetMessageStatisticsRequest { starttime DateTimeOffset.Now.AddDays(-30).ToUnixTimeSeconds(), endtime DateTimeOffset.Now.ToUnixTimeSeconds(), type week, agentid your_agent_id, userids new[] { user1, user2 } }; var result DataIntelligenceApi.GetMessageStatistics(accessToken, request);请求字段类型默认值说明starttimelong—统计开始时间Unix 时间戳endtimelong—统计结束时间Unix 时间戳typestringday统计类型day/week/monthagentidstringnull应用ID为空统计全部应用useridsstring[]null用户ID列表为空统计全部用户4.4 异步调用var result await DataIntelligenceApi.GetMessageStatisticsAsync( accessToken, DateTime.Now.AddDays(-7), DateTime.Now, day, null, null );五、返回数据结构详解5.1 ConversationRecord会话记录每条会话记录由ConversationRecord描述GetConversationRecordsResult.cs#L41-L77public class ConversationRecord { public string msgid { get; set; } // 消息ID public string msgtype { get; set; } // 消息类型text/image/voice/video/file/location/link等 public string from { get; set; } // 发送者用户ID public string to { get; set; } // 接收者用户ID群聊时为空 public string roomid { get; set; } // 群聊ID单聊时为空 public long timestamp { get; set; } // 消息发送时间Unix时间戳 public ConversationContent content { get; set; } // 消息内容 }其中from/to/roomid的关系需要特别留意单聊场景下to有值、roomid为空群聊场景下roomid有值、to为空可通过这两个字段区分单聊与群聊消息。ConversationContent是消息内容载体GetConversationRecordsResult.cs#L82-L138按msgtype不同填充不同字段消息类型msgtype有效字段说明texttext文本内容image / voice / video / filemedia_id、filename、filesize媒体文件ID、文件名、文件大小linktitle、description、url链接标题、描述、地址locationlatitude、longitude、location_name、address位置纬度、经度、名称、地址从源码注释与字段结构可以推断读取记录时应先判断msgtype再访问对应的内容字段避免对未填充字段做空引用操作。5.2 MessageStatistics消息统计public class MessageStatistics { public long date { get; set; } // 统计日期Unix时间戳 public int total_send { get; set; } // 发送消息总数 public int total_receive { get; set; } // 接收消息总数 public int text_count { get; set; } // 文本消息数量 public int image_count { get; set; } // 图片消息数量 public int voice_count { get; set; } // 语音消息数量 public int video_count { get; set; } // 视频消息数量 public int file_count { get; set; } // 文件消息数量 public int link_count { get; set; } // 链接消息数量 public int location_count { get; set; } // 位置消息数量 public int active_users { get; set; } // 活跃用户数 public int active_groups { get; set; } // 活跃群聊数 }返回的GetMessageStatisticsResult.statistics是MessageStatistics[]数组GetMessageStatisticsResult.cs#L20-L26每个元素对应一个统计周期。例如type day时date字段即为具体统计日total_send total_receive可得到该周期消息总量各*_count字段可用于分析消息形态分布文本/图片/语音/视频/文件/链接/位置active_users与active_groups反映活跃规模。六、错误处理与容错6.1 返回值错误码判断所有结果类型均继承自WorkJsonResult包含标准的errcode错误码与errmsg错误描述。推荐先判断errcode ReturnCode_Work.请求成功再处理业务数据try { var result DataIntelligenceApi.GetConversationRecords(accessToken, chatId, startTime, endTime); if (result.errcode ReturnCode_Work.请求成功) { // 处理成功结果 foreach (var record in result.records) { Console.WriteLine($消息: {record.content.text}); } } else { Console.WriteLine($API调用失败: {result.errcode} - {result.errmsg}); } } catch (Exception ex) { Console.WriteLine($调用异常: {ex.Message}); }6.2 两类常见失败形态从测试用例 DataIntelligenceTest.cs#L42-L67 的注释可以看出官方 SDK 对失败形态的预期权限类错误接口需要数据与智能专区权限未开通时调用会返回非成功errcode。测试中特意不断言成功因为新功能可能尚未开通权限异常类错误网络异常、序列化失败等会抛出 .NET 异常需要通过try/catch捕获。6.3 底层调用链与自动降级从 DataIntelligenceApi.cs#L61-L73 可以看到每个公开方法都包了一层ApiHandlerWapper.TryCommonApi异步为TryCommonApiAsync这是 Senparc.Weixin 的通用容错包装当传入的是 AppKey 时SDK 会在内部解析出可用的 AccessToken当 AccessToken 过期时会自动刷新重试。也就是说业务代码无需关心 AccessToken 的刷新细节只需保证传入合法的凭证即可。七、进阶数据与智能专区订单管理接口从 v3.32.1 开始DataIntelligenceApi以分部类形式补齐了高级接口订单管理能力实现位于 DataIntelligenceApi.Order.cs。这是面向**应用服务商Provider**的能力用于为客户企业购买/管理会话内容数据等高级接口版本与普通应用的 AccessToken 体系不同——这些接口使用provider_access_token即服务商的 ProviderAccessToken#L48-L50。7.1 接口清单方法对应路径用途CreateAdvancedApiOrder/...Async/cgi-bin/advanced_api/create_order为客户企业创建高级接口订单CancelAdvancedApiOrder/...Async/cgi-bin/advanced_api/cancel_order取消尚未完成的订单SubmitAdvancedApiOrderPayment/...Async/cgi-bin/advanced_api/submit_pay用服务商充值账户余额支付订单GetAdvancedApiOrderList/...Async/cgi-bin/advanced_api/list_order分页获取订单列表GetAdvancedApiOrder/...Async/cgi-bin/advanced_api/get_order获取订单详情GetAdvancedApiCorpPurchaseInfo/...Async/cgi-bin/advanced_api/get_corp_buy_info获取客户企业已购版本信息实现细节DataIntelligenceApi.Order.cs#L211-L223所有订单接口统一走私有辅助方法PostAdvancedApiOrderT请求 URL 形如Config.ApiWorkHost path ?provider_access_token{0}并使用JsonSetting(true)忽略 null 字段避免向服务端提交空值。7.2 订单模型关键字段订单协议模型完整定义在 AdvancedApiOrderJson.cs核心枚举值高级接口类型advanced_api_type目前仅支持1会话内容数据接口订单类型order_type0新购、1增购、2续期、3升级订单状态order_status0待支付、1已支付、2已取消、3已过期、4申请退款中、5退款成功、6退款被拒绝会话内容数据版本edition2表示内外部会话3表示内外部会话及语音通话购买人数purchase_count范围为 1 至 1000000。7.3 创建订单示例var request new AdvancedApiCreateOrderRequest { advanced_api_type 1, // 会话内容数据接口 custom_corpid 客户企业CorpId, buyer_userid 服务商内下单人明文UserId, order_type 0, // 新购 chat_archive_api new AdvancedApiCreateOrderChatArchive { edition 2, // 内外部会话 purchase_count 100 } }; var result await DataIntelligenceApi.CreateAdvancedApiOrderAsync( providerAccessToken, request); Console.WriteLine($订单号: {result.order_id});注意订单接口的凭证是服务商 ProviderAccessToken而非企业应用的普通 AccessToken下单人buyer_userid必须是服务商企业内具有购买或管理高级接口权限的明文 UserId。八、延伸现行 ChatData 接口ChatDataApi在较新版本中仓库还提供了现行 ChatData 接口族ChatDataApi源码 ChatDataApi.cs覆盖会话内容存档的完整闭环。契约测试 ChatDataContractTests.cs#L20-L64 验证了其包含 31 组同步/异步方法包括授权与配置GetAuthorizedUserList获取授权用户列表、GetCorpAuthorization、SetPublicKey、SetReceiveCallback、SetLogLevel数据拉取SyncMessages同步消息、GetGroupChat获取群聊信息、GetSingleAgreeStatus/GetRoomAgreeStatus单聊/群聊同意状态智能分析AddAnalyzeTask/SubmitAnalyzeTask/GetAnalyzeTaskResult分析任务、SearchChat/SearchMessage会话与消息检索合规与导出SetSensitiveInfoConfig/GetSensitiveInfoConfig敏感信息配置、CreateExportJob/GetExportJobStatus导出任务、关键字规则keyword/create_rule等 5 个接口调试与异步程序OpenDebugMode/CloseDebugMode/GetDebugMode、SyncCallProgram/CreateAsyncProgramTask/GetAsyncProgramResult。同时契约测试 ChatDataContractTests.cs#L369-L378 中的LegacyDataIntelligenceEntriesRemainAvailable用例明确断言本文主角DataIntelligenceApi.GetConversationRecords / GetMessageStatistics作为早期实现被完整保留以保证既有业务代码的向后兼容。如果你需要的是会话存档全链路能力可以结合ChatDataApi使用如果仅需本文所述的记录拉取与消息统计DataIntelligenceApi即可满足。九、注意事项汇总结合 README 原文与源码实现使用数据与智能专区接口时应重点遵守以下约束权限要求需要企业微信管理员开通数据与智能专区相关权限未开通会返回权限类错误码数据范围只能获取已授权的会话和用户数据涉及敏感数据须符合企业微信的合规要求分页限制会话记录查询单次最多返回 1000 条记录SDK 会自动将超限的limit收敛到 1000时间范围建议查询时间范围不超过 31 天跨度过大可能导致查询失败或数据不完整频率限制遵循企业微信 API 调用频率限制批量拉取时应配合游标分页、避免高频重复请求凭证差异普通数据接口使用应用 AccessToken/AppKey订单管理接口使用服务商 ProviderAccessToken切勿混用。十、示例场景10.1 会话记录分析客服服务质量分析按chatid拉取客服会话记录结合msgtype与content.text统计响应时效、高频问题主题会议归档导出重要会议群聊记录roomid定位群聊按timestamp排序后落库归档团队沟通模式分析聚合from/to/roomid字段构建成员间的沟通网络。10.2 消息统计分析部门消息活跃度按agentiduserids维度拉取day级统计横向对比各部门沟通量沟通工具使用分析对比text_count、image_count、file_count、link_count等字段评估文件共享、外链传播等形态占比企业沟通报表以week/month粒度汇总total_send、total_receive、active_users、active_groups周期性生成管理层报表。这些 API 为企业提供了从会话数据到沟通洞察的完整数据分析链路帮助企业更好地了解和优化内部沟通效率。十一、测试与验证仓库为数据与智能专区接口提供了完整的测试保障可作为接入时的参考实现DataIntelligenceTest.cs覆盖参数式/请求对象式/异步调用与 limit 上限收敛LimitValidationTest验证 1500 被自动收敛为 1000ChatDataContractTests.cs契约测试验证ChatDataApi31 组方法的存在性与官方路径正确性并断言旧接口DataIntelligenceApi的四个入口GetConversationRecords、GetConversationRecordsAsync、GetMessageStatistics、GetMessageStatisticsAsync依然可用AdvancedApiOrderContractTests.cs验证订单管理六个方法的同步/异步入口齐全。提示会话记录与消息统计属于企业微信真实数据接口单元测试中仅验证调用结构、参数校验与返回格式测试注释明确说明需要实际的企业微信环境和真实的会话数据真实业务数据请在企业微信管理后台开通权限后以实际返回为准进行联调。赞分享后端即时通讯金融科技【免费下载链接】WeiXinMPSDK微信全平台 .NET SDK Senparc.Weixin for C#支持 .NET Framework 及 .NET Core、.NET 10.0。已支持微信公众号、小程序、小游戏、微信支付、企业微信/企业号、开放平台、JSSDK、微信周边等全平台。 WeChat SDK for C#.项目地址https://gitcode.com/gh_mirrors/we/WeiXinMPSDK点击查看免费下载相关推荐JeecgBoot企业微信客服集成指南实现智能会话转接与完整消息记录JeecgBoot企业微信客服集成指南实现智能会话转接与完整消息记录 JeecgBoot作为一款强大的企业级低代码平台提供了全面的前后端分离架构解决方案。在低代码后端前端AI 应用大模型RAG工作流自动化企业微信会话存档 Go SDK 实战指南基于 silenceper/wechat msgaudit 模块的消息拉取、解密与媒体下载企业微信会话存档 Go SDK 实战指南基于 silenceper/wechat msgaudit 模块的消息拉取、解密与媒体下载 导读 本文围绕当前仓库中网络安全企业微信会话存档SDK实战指南快速构建合规数据管理系统在现代企业运营中会话数据的合规存档已成为金融机构、医疗行业等监管严格领域的必备需求。WeWorkFinanceSDK作为企业微信官方会话存档功能的Go语言封装创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考