企业QQ开放API开发手册_20101126VIP

企业 QQ 开放 API 开发手册partner 公开 1 企业企业 QQQQ 开放开放 APIAPI 开发手册开发手册 腾讯科技 上海 有限公司腾讯科技 上海 有限公司 版权所有 侵权必究 企业 QQ 开放 API 开发手册partner 公开 2 目目 录录 1文档目的和范围文档目的和范围 3 2整体说明整体说明 4 2 1拓扑结构 4 2 2文件存放位置 4 2 2 1同一主机存放 4 2 3存放位置说明 5 2 4数据文件命名格式说明 5 2 4 1文件命名总体规则 5 3数据格式详细说明数据格式详细说明 7 3 1文件总体格式说明 7 3 2文件头格式说明 7 3 3聊天记录格式说明 7 3 4会话记录格式说明 8 3 5好友资料格式说明 8 3 6好友分组格式说明 9 4数据获取工具使用说明数据获取工具使用说明 10 4 1QQSERVER 10 4 2GETQQMSG 10 4 3GETQQSESS 10 4 4GETQQFRND 11 4 5SENDQQMSG 11 4 6QQTEST 11 5配置说明配置说明 12 5 1服务程序OAPI QQSERVER配置 12 5 2工具类程序OAPI TOOLS 配置 13 5 3企业 QQ 客户端自定义 TAB 配置 13 5 4客户端内嵌页面制作规范 16 6LOG 文件说明文件说明 18 6 1OAPI QQSERVER日志文件 18 6 2OAPI TOOLS 日志文件 18 7程序部署说明程序部署说明 19 7 1系统要求 19 8FAQ 20 企业 QQ 开放 API 开发手册partner 公开 3 1文档目的和范围文档目的和范围 本文档为企业 QQ 开放 API 的工具包使用方法和定制开发操作说明 企业 QQ 开放 API 开发手册partner 公开 4 2整体说明整体说明 企业 QQ 开放的数据以文件方式提供 腾讯公司提供获取文件的工具程序 由各企业 在需要时运行该工具程序从腾讯获取数据文件 工具程序使用方法参加 4 数据获取工具 使用说明 2 1 拓扑结构拓扑结构 获取数据的程序由 daemon 程序和 tools 程序组成 daemon 程序通过 TCP 连接与腾讯服务 器进行加密通讯 tools 程序向 daemon 程序发起各项取数据的请求 拓扑结构如下图 图 2 1 拓扑图 2 2 文件存放位置文件存放位置 假设 TOPDIR 为用户指定的存放企业 QQ 程序及数据的顶层目录 2 2 1 同一主机存放同一主机存放 假设所有内容位于同一台主机 则各类文件存放位置如下 图 2 2 同一主机部署目录结构 toolsdaemon腾讯服务器 内网 TCP 明文传输 公网 TCP 加密传输 企业 QQ 开放 API 开发手册partner 公开 5 2 3 存放位置说明存放位置说明 各目录说明如下 目录名称目录下文件备注 daemon运行与各企业接口机器上的 取数据服务程序 用于同腾讯公司服务器通讯 需要有外网接 口 此目录下仅有 QQServer 一个程序文件 tools具体获取各类数据文件的命 令工具存放位置 此目录下所有程序与上述 daemon 目录里的服 务程序交互以获取数据 此目录下有 getQQmsg getQQsess getQQfrnd sendQQ msg QQTest 等五个程序文件 conf程序配置文件存放路径此目录下有 qqserver ini 和 qqtools ini 文件 配置文件格式参见 5 配置文件说明 log程序运行产生的 log 文件存 放于此 此目录下为各程序运行产生的 log 文件 每 类文件每日产生一个 log 文件格式说明参见 6 log 文件说明 msg聊天消息记录文件存放目录此目录下为聊天消息记录文件 每工号每日 一个文件 sess会话记录文件存放目录此目录下为会话记录文件 每工号每日一个 文件 frnd好友资料文件存放目录此目录下为好友资料文件 每日一个好友详 细资料文件和一个好友分组信息文件 表 2 1 目录说明 2 4 数据文件命名格式说明数据文件命名格式说明 2 4 1 文件命名总体规则文件命名总体规则 所有文件命名总体规则如下 图 2 3 命名总体规则 各部分之间以下划线分割 TYPE 为 M S F G 之一 M 标识此文件为聊天消息记录文件 S 标识此文件为会话 记录文件 F 标识此文件为好友资料文件 G 标识此文件为好友分组信息文件 主号 为企业 QQ 号码 工号 为企业 QQ 的工号 若工号为 9999 表示不特定工号 起始日期 数据起始日期 日期格式为年月日以 YYYYMMDD 格式表示 终止日期 数据终止日期 后缀 各类数据文件后缀 默认为 dat 示例 TYPE主号起始日期终止日期后缀工号 企业 QQ 开放 API 开发手册partner 公开 6 主号 800123456 的 1002 工号 20100808 日的聊天记录文件文件名为 M 800123456 1002 20100808 20100808 dat 主号 800123456 的 20100808 日的好友分组信息文件文件名为 G 800123456 9999 20100808 20100808 dat 企业 QQ 开放 API 开发手册partner 公开 7 3数据格式详细说明数据格式详细说明 本章节对各类数据格式进行详细说明 3 1 文件总体格式说明文件总体格式说明 1 所有文件为纯文本格式 2 每个文件分为两大部分 文件头和文件体 文件头为单独一行内容 是对本数据文件的总体说明 之后内容全部为文件体 文件体为多行内容 每行是一个数据记录 3 文件内列分隔符为两个字节 取值为 0 x0203 4 文件内行分隔符为三个字节 取值为 0 x030404 5 若非特别说明 时间值均为 1970 1 1 0 0 0 至今的秒数 6 若非特别说明 日期格式为年月日以 YYYYMMDD 格式表示 7 若非特别说明 文件中所有字符编码集采用 UTF 8 编码 8 若非特别说明 数据文件都是未经排序的 3 2 文件头格式说明文件头格式说明 列编号数据备注 1主号企业主号 2工号此数据文件记录所属工号 3起始日期此数据文件起始时间 4终止日期此数据文件终止时间 表 3 1 文件头格式说明 3 3 聊天记录格式说明聊天记录格式说明 文件名为 M 主号 工号 日期 dat 列编号数据备注 1消息方向1 主动 即企业 QQ 发送消息 2 被动 即企业 QQ 接收消息 2对方 ID和企业 QQ 进行聊天的对方 3时间消息发送时间 4长度消息长度 5内容消息内容 6好友类型该好友的类型 0 普通用户 1 匿名用户 表 3 2 聊天消息记录文件格式 企业 QQ 开放 API 开发手册partner 公开 8 3 4 会话记录格式说明会话记录格式说明 文件名为 S 主号 工号 日期 dat 列编号数据备注 1操作工号操作工号 2对方 ID发生会话的对方 若会话为 5 工号登录 6 工号退出 则此值为 0 3操作时间会话发生时间 4操作类型会话数据类型 1 QQ 用户主动发起会话 2 QQ 用户发起会话接入 3 客服主动发起会话 4 关闭会话 5 工号登录 6 工号退出 表 3 2 会话记录文件格式 下面以 QQ 用户 567890123 与主号 800123456 的 1002 工号进行一次会话为例说明 1 T0 时间 1002 工号登录 2 T1 时间 567890123 向 800123456 发起会话 3 T2 时间 1002 工号接入该用户开始会话 4 T3 时间会话结束 1002 关闭会话 5 T4 时间 1002 工号下班退出登录 产生的会话记录文件名为 S 800123456 1002 日期 dat 文件体为如下 5 条记录 产生的会话记录文件名为 S 800123456 9999 日期 dat 文件体为如下 1 条记录 注 1 0123457897413614asdfaaff 01234ab假设为QQ号码567890123 的 Open ID 2 9999 表示获取企业主号下所有会话记录 目前只有 QQ 用户主动发起会话记录 包括 被工号接入和未被工号接入的 3 5 好友资料格式说明好友资料格式说明 文件名为 F 主号 工号 起始日期 终止日期 dat 列编号数据备注 1对方 ID好友身份 ID 2系统分组用户所属系统分组 3001 好友 3002 陌生人 3004 黑名单 3005 匿名客户 3分组列表该好友所属的分组 ID 列表 最多 8 个 多个工号间由英文字符逗 号分割 4好友类型该好友的类型 0 普通用户 1 匿名用户 5修改时间简单资料最后修改时间 1002 0 T0 5 1002 0123457897413614asdfaaff 01234ab T1 1 1002 0123457897413614asdfaaff 01234ab T2 2 1002 0123457897413614asdfaaff 01234ab T3 4 1002 0 T4 6 9999 0123457897413614asdfaaff 01234ab T1 1 企业 QQ 开放 API 开发手册partner 公开 9 6上次来访好友上次来访时间 7创建工号加该好友的工号 8最后访问时间最后访问时间 9上次接入时间该好友上次被接入的时间 10最后接入列表最后服务该好友的 5 个工号列表 多个工号间由英文字符逗号分割 11关系建立时间该好友与企业 QQ 建立好友关系的时间 12更新详细资料 时间 更新好友详细资料时间 13关闭时间关闭会话时间 14关闭 case 时 间 关闭 case 时间 15备注对该好友的备注 16备注姓名该好友备注的真实姓名 17性别好友性别 0 未指定 1 男 2 女 3 保密 18国家该好友所在国家名称 19省份该好友所在省份名称 20城市该好友所在城市名称 21地址该好友所在位置地址 22电话该好友的电话号码 23Email该好友的 email 24公司该好友的公司名称 表 3 3 好友资料文件格式 3 6 好友分组格式说明好友分组格式说明 文件名为 G 主号 9999 起始日期 终止日期 dat 列编号数据备注 1分组 ID好友分组 ID 2分组名称好友分组名称 企业 QQ 开放 API 开发手册partner 公开 10 4数据获取工具使用说明数据获取工具使用说明 本章节对获取数据的各程序使用方法进行说明 目前腾讯提供的所有程序均为 Linux 版本 内核 2 6 以上 4 1 QQServer 此工具用于和腾讯公司服务器进行加密通讯 并对企业内部提供各种数据获取接口 每次运行时提示输入企业 QQ 号码及管理密码 若为动态 IP 或变换了 IP 还将提示输入 token 码 4 2 getQQmsg 此工具用于获取聊天消息记录 使用方法为 取本企业 QQ 的前一天 1001 工号的聊天记录 若要指定工号请加参数 k 工号 若要指定日期请加参数 d 日期 4 3 getQQsess 此工具用于获取会话记录 使用方法为 取本企业 QQ 的前一天 1002 工号的会话记录 若要指定工号请加参数 k 工号 注意 这里约定用虚拟工号 9999 表示获取主号相关 的会话信息 若要指定日期请加参数 d 日期 4 4 getQQfrnd 此工具用于获取好友资料数据 cd TOPDIR prog tools oapi tools getQQmsg k 1001 cd TOPDIR prog tools oapi tools getQQsess k 1002 cd TOPDIR prog daemon oapi QQServer 企业 QQ 开放 API 开发手册partner 公开 11 使用方法为 默认取本企业 QQ 的前一天资料有变化的好友的详细资料 若要指定日期请加参数 d 日期 取该日期至今有资料变化的所有好友资料 注意 如果 输入的日期为 0 则取全部好友详细资料 4 5 sendQQmsg 此工具用于发送模板消息 向好友 12345678901234567890123456789012 发送模板 ID 为 1 的模板消息 模板消息可变 内容为 hello 4 6 QQTest 此工具用于测试 cd TOPDIR prog tools oapi tools getQQfrnd cd TOPDIR prog tools oapi tools sendQQmsg f 12345678901234567890123456789012 i 1 1 hello 企业 QQ 开放 API 开发手册partner 公开 12 5配置说明配置说明 本章节对相关配置进行详细说明 5 1 服务程序服务程序 oapi qqserver 配置配置 默认的配置文件为 conf qqserver ini 也可以在程序启动的时候指定配置文件运行 比如使用 c myconfig ini 本配置文件包括以下几个部分 net server tcp 0 0 qqserver oapi qqserver 相关配置相关配置 logLevel 2 oapi qqserver 日志打印级别 LOG TRACE 1 LOG DEBUG 2 LOG NORMAL 4 LOG ERROR 8 LOG FATAL 16 LOG NONE 10000 用于设置不打印任何日志 logType 2 oapi qqserver 日志打印类型 建议不做修改 logMaxSize 524288000 oapi qqserver 单个日志文件最大大小 logMaxNo 2 oapi qqserver 最多日志文件个数 建议不做修改 logFilePath log oapi qqserver 日志文件存放路径 logPrefix qs oapi qqserver 日志文件名前缀 appID 45680 内部参数 建议不做改动 appCount 0 内部参数 建议不做改动 queueCount 0 内部参数 建议不做改动 listenCount 1 监听通道个数 listen 0 local tcp listen 监听来自 oapi tools 的 tcp 请求通道名 whitelistCount 0 内部参数 建议不做改动 local tcp listen 监听来自监听来自 oapi tools 的的 tcp 请求相关配置请求相关配置 ip 127 0 0 1 监听 IP 由于 oapi tools 与 oapi qqserver 为非安全通道 建议仅监听 127 0 0 1 port 30600 监听 port qqserver 与与腾讯开放腾讯开放 API 服务器相关配置服务器相关配置 ip 腾讯开放 API 服务器域名 port 30500 腾讯开放 API 服务器 TCP 监听端口 refreshtime 5400 oapi qqserver 向腾讯开放 API 服务器获取票据时间 myip 本地外网 IP msgfilepath data msg 获取的聊天消息文件存放路径 sessfilepath data sess 获取的会话信息文件存放路径 frndfilepath data frnd 获取的好友资料文件存放路径 企业 QQ 开放 API 开发手册partner 公开 13 logFilePath log oapi qqserver 日志文件存放路径 5 2 工具类程序工具类程序 oapi tools 配置配置 默认的配置文件为 conf qqtools ini 也可以在程序启动的时候指定配置文件运行 比如使用 c myconfig ini 本配置文件包括以下几个部分 QQDataTools oapi tools 相关配置相关配置 logLevel 2 oapi tools 日志打印级别 LOG TRACE 1 LOG DEBUG 2 LOG NORMAL 4 LOG ERROR 8 LOG FATAL 16 LOG NONE 10000 用于设置不打印任何日志 logType 2 oapi tools 日志打印类型 建议不做修改 logMaxSize 524288000 oapi tools 单个日志文件最大大小 logMaxNo 2 oapi tools 最多日志文件个数 建议不做修改 logFilePath log oapi tools 日志文件存放路径 logPrefix qc oapi tools 日志文件名前缀 qqserver tcp listen oapi qqserver 相关监听配置相关监听配置 ip 127 0 0 1 监听 IP 由于 oapi tools 与 oapi qqserver 为非安全通 道 建议仅监听 127 0 0 1 port 30600 监听 port 5 3 企业企业 QQ 客户端自定义客户端自定义 TAB 配置配置 此项配置用于定制 CRM 客户端界面的 Tab 页头标题文字和对应的超链接地址 目前 没有提供专门的配置工具 需要配置的内容需要通过邮件等方式申请 当前支持的配置信 息包括 配置项格式配置项说明 企业主号数字企业主号 企业工号数字配置项针对的工号 不同工号可能提供不同 的界面展示 配置编号数字此配置编号 配置类型数字此配置类型 0 主窗口页面 1 右边框 Tab 页 Tab 页面标题文字 不包 括图片等丰 富格式 在 Tab 页上显示的标题文字 企业 QQ 开放 API 开发手册partner 公开 14 缺省选择页页面数字编 号 如果有多个 Tab 页面存在 CRM 客户端界 面初始化时显示的缺省被选中的 Tab 页面 Tab 页超链接含有模式通 配符的 URL 地址 Tab 页面对应的 URL 地址 详细格式如下说 明 Tab 页超链接格式 当前 CRM 客户端支持的 Tab 页超级链接格式为 URL http https url KFEXT OPENID CONTEXT KFGUIN URL 为用户希望点击针对某个接入的用户 点击 CRM Tab 页后跳转的页面地址 该地址 可以根据接入用户的 QQ 号码动态生成 例 假设 Tab 页配置如下 企业主 号 企业工 号 配置类型配置编 号 Tab 页标题缺省 选择 页 Tab 页链接地址 938032 469 100100主窗口 Tab 页标 题 0http welcomeToMyS 938032 469 100110聊天窗口 侧边栏自 定义 1Tab 页面标题 1http welcomToMySh KFGUIN 2 建议采用以下代码 二 图片规范 建议用 png 8 jpg gif 图片 jpg 的质量最好是 60 三 尺寸规范 2009 聊天面板右侧页面 Width 196px Height 393px 要求 因为聊天面板可以改变高宽 右侧页面需要做成宽度和高度自适应 企业 QQ 开放 API 开发手册partner 公开 18 四 缓存机制 为了加快页面显示速度 客户端这边给页面定制了专门的接口用来加速 需要在 head 中加 入下面代码 var time xxx function CRM getLastTime return time 说明 其中 var time 是字符串 从 1970 年 1 月 1 号午夜到现在一共花去的秒数 注意不是毫秒数 算法大概是 parseInt new Date getTime 1000 以后每次变更页面上线 需要递增数字 建议在服务器端生成页面时把当前时间带出来 例子 var time 1259654365 五 版本控制 鉴于目前没有相应的针对页面管理的系统 所以版本的维护都采用双方维护最新的版本 6log 文件说明文件说明 本章节对 log 文件进行详细说明 Log 文件仅在问题定位时候使用 无其他用途 6 1 oapi qqserver 日志文件日志文件 略 6 2 oapi tools 日志文件日志文件 略 企业 QQ 开放 API 开发手册partner 公开 19 7程序部署说明程序部署说明 本章节指导用户部署腾讯提供的程序 7 1 系统要求系统要求 要求项需求版本建议版本 操作系统Linux 内核 2 6 以上 32 位系统 SUSE Linux Enterprise Server 10 SP1 i586 glibcGNU C Library 2 4 以上GNU C Library development release version 2 4 20070506 gccgcc 4 1 2gcc GCC 4 1 2 20070115 prerelease SUSE Linux 企业 QQ 开放 API 开发手册partner 公开 20 8FAQ 本章节列出用户使用中可能会关心的一些问题 一 企业 QQ1 0用户可以使用 API 吗 原2 0标准版使用 API 后会有丢失数据的情况 吗 回答 企业回答 企业 QQQQ 开放开放 APIAPI 基于企业基于企业 QQQQ 标准版标准版2 02 0及后续版本 及后续版本 1 01 0用户需迁移至用户需迁移至2 02 0