企业微信数据与智能专区 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 的项目中运行。

一、概述：数据与智能专区是什么

在 WeiXinMPSDK（Senparc.Weixin）中，数据与智能专区（Data Intelligence）是企业微信开放平台面向数据分析与智能化应用开放的一组高级接口。它围绕两大核心诉求设计：

1. 会话记录获取（GetConversationRecords）：拉取企业微信内部单聊、群聊的历史消息内容，用于客服质检、合规审计、会议归档、团队沟通模式分析等场景；
2. 消息统计（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-L43）：

private 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.Send<T>/SendAsync<T>以POST方式提交 JSON 请求体，并自动处理 access_token 注入与基础错误包装。

二、使用前置条件

在调用DataIntelligenceApi之前，需要确认以下几点：

前置项	说明
权限开通	需要企业微信管理员为企业开通"数据与智能专区"相关权限，未开通时接口会返回权限错误（详见下文错误处理章节）
数据授权	只能获取已授权的会话和用户数据，涉及员工隐私的数据需要按企业微信要求完成知情同意/授权流程
调用凭证	传入accessTokenOrAppKey参数，即 AccessToken 或 AppKey。AppKey 可通过AccessTokenContainer.BuildingKey(corpId, corpSecret)获得，SDK 会在内部自动换取/刷新 AccessToken
SDK 版本	数据与智能专区接口自较新版本引入（源码注释显示创建于 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 的解析与容错处理。

三、获取会话记录（GetConversationRecords）

3.1 方法签名与参数说明

DataIntelligenceApi为会话记录提供了参数式与请求对象式两套重载（同步 + 异步），完整定义见 DataIntelligenceApi.cs。

参数式同步方法签名（#L59）：

public 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_cursor；
• limit（分页数量）：默认 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);

请求字段	类型	说明
chatid	string	会话ID
starttime	long	开始时间，Unix 秒级时间戳
endtime	long	结束时间，Unix 秒级时间戳
cursor	string	分页游标，初始传空
limit	int	分页数量，默认 100，最大 1000

3.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 List<ConversationRecord>(); 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为空字符串时终止循环，双条件均可作为结束信号。

四、获取消息统计（GetMessageStatistics）

4.1 方法签名与参数说明

消息统计接口用于获取企业微信中的消息统计信息，支持按天、周、月统计。同步参数式方法签名（#L110）：

public 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 时间戳
type	"day"	统计粒度：day（按天）、week（按周）、month（按月）
agentId	null	应用ID，传null表示统计全部应用
userIds	null	用户ID数组，传null表示统计全部用户

4.2 基本用法（参数式）

// 获取过去30天的日统计数据 var result = DataIntelligenceApi.GetMessageStatistics( accessToken, DateTime.Now.AddDays(-30), // 开始时间 DateTime.Now, // 结束时间 "day", // 统计类型：day/week/month null, // 应用ID，null表示全部应用 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.cs：

var 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);

请求字段	类型	默认值	说明
starttime	long	—	统计开始时间，Unix 时间戳
endtime	long	—	统计结束时间，Unix 时间戳
type	string	"day"	统计类型：day/week/month
agentid	string	null	应用ID，为空统计全部应用
userids	string[]	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-L77）：

public 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）	有效字段	说明
text	text	文本内容
image / voice / video / file	media_id、filename、filesize	媒体文件ID、文件名、文件大小
link	title、description、url	链接标题、描述、地址
location	latitude、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 对失败形态的预期：

1. 权限类错误：接口需要"数据与智能专区"权限，未开通时调用会返回非成功errcode。测试中特意"不断言成功"，因为新功能可能尚未开通权限；
2. 异常类错误：网络异常、序列化失败等会抛出 .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）：所有订单接口统一走私有辅助方法PostAdvancedApiOrder<T>，请求 URL 形如Config.ApiWorkHost + path + "?provider_access_token={0}"，并使用JsonSetting(true)忽略 null 字段（避免向服务端提交空值）。

7.2 订单模型关键字段

订单协议模型完整定义在 AdvancedApiOrderJson.cs，核心枚举值：

• 高级接口类型advanced_api_type：目前仅支持1（会话内容数据接口）；
• 订单类型order_type：0新购、1增购、2续期、3升级；
• 订单状态order_status：0待支付、1已支付、2已取消、3已过期、4申请退款中、5退款成功、6退款被拒绝；
• 会话内容数据版本edition：2表示内外部会话，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 原文与源码实现，使用数据与智能专区接口时应重点遵守以下约束：

1. 权限要求：需要企业微信管理员开通数据与智能专区相关权限，未开通会返回权限类错误码；
2. 数据范围：只能获取已授权的会话和用户数据，涉及敏感数据须符合企业微信的合规要求；
3. 分页限制：会话记录查询单次最多返回 1000 条记录，SDK 会自动将超限的limit收敛到 1000；
4. 时间范围：建议查询时间范围不超过 31 天，跨度过大可能导致查询失败或数据不完整；
5. 频率限制：遵循企业微信 API 调用频率限制，批量拉取时应配合游标分页、避免高频重复请求；
6. 凭证差异：普通数据接口使用应用 AccessToken/AppKey；订单管理接口使用服务商 ProviderAccessToken，切勿混用。

十、示例场景

10.1 会话记录分析

• 客服服务质量分析：按chatid拉取客服会话记录，结合msgtype与content.text统计响应时效、高频问题主题；
• 会议归档：导出重要会议群聊记录（roomid定位群聊），按timestamp排序后落库归档；
• 团队沟通模式分析：聚合from/to/roomid字段，构建成员间的沟通网络。

10.2 消息统计分析

• 部门消息活跃度：按agentid+userids维度拉取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 被自动收敛为 1000）；
• ChatDataContractTests.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语言封装