Yach开放平台

# 群聊

# 创建群

# host: https://yach-oapi.zhiyinlou.com 正式环境

# host: https://yach-oapi-test.zhiyinlou.com 测试环境

# 概述

名称 值
地址 /group/create?access_token=ACCESS_TOKEN
请求方式 POST
参数 见【参数】
返回值 见【返回值】

# 参数

参数 参数类型 必须 说明
access_token String 是 调用接口凭证
group_name String 是 群名称
group_owner String 是 群主userid 例如yach091805
group_userids String 是 群成员列表，半角竖线分割开来，group_userids 人数不得超过1000人
source Int 否 群类型（0:普通群 3:审批群 4:项目群，102:应用模版群，默认0）
tpl_id String 否 当模版群时，必填，这个字段目前只能群组服务手动提供,联系 李东军(197237) 获取
tpl_ext String 否 非必填，如果群应用跳转需要业务参数，必填
unique_key String 否 唯一值，用于验证幂等性，没有该参数，每个请求会自动生成一个

返回值

{
    "code": 200,
    "msg": "",
    "obj": {
        "group_id": "2771361680",//群ID，即group_tid
        "name": "测试建群",
        "pic": "群头像链接地址"
    }
}

# 修改群聊

# host: https://yach-oapi.zhiyinlou.com 正式环境

# host: https://yach-oapi-test.zhiyinlou.com 测试环境

# 概述

名称 值
地址 /group/edit?access_token=ACCESS_TOKEN
请求方式 POST
参数 见【参数】
返回值 见【返回值】

# 参数

参数 参数类型 必须 说明
access_token String 是 调用接口凭证
group_tid String 是 群id
group_name String 否 群名称
group_owner String 否 群主userid 例如yach091805
invite_uid String 否 邀请人的userid 例如yach091805
tpl_id String 否 当模版群时，必填，这个字段目前只能群组服务手动提供,联系 李东军(197237) 获取
tpl_ext String 否 非必填，如果群应用跳转需要业务参数，必填
del_useridlist String 否 删除群成员列表，竖线分割开来，del_useridlist 人数不得超过40人
add_useridlist String 否 添加群成员列表，竖线分割开来，add_useridlist 人数不得超过40人

返回值

{
    "code": 200,
    "msg": "",
    "obj": {
        "group_yach_id": 49560636174241884 //本次更新唯一ID
    }
}

# 获取群基本信息

# host: https://yach-oapi.zhiyinlou.com 正式环境

# host: https://yach-oapi-test.zhiyinlou.com 测试环境

# 概述

名称 值
地址 /group/info?access_token=ACCESS_TOKEN
请求方式 POST
参数 见【参数】
返回值 见【返回值】

# 参数

参数 参数类型 必须 说明
access_token String 是 调用接口凭证
group_tid String 是 群id

返回值

{
    "code": 200,
    "msg": "",
    "obj": {
        "group": {
                  "group_tid": "2771348607",
                  "group_name": "好好学习",
                  "group_icon": "",
                  "group_users_count": 3,
                  "group_owner": "Yach076429",
                  "group_manager":{
                      "Yach111",
                      "Yach222"
                  }
              },
              "uidlist": [ // 该接口只返回20个群成员，如需获取全部成员请使用群成员列表接口
                  "Yach137620",
                  "Yach076429",
                  "Yach091805"
              ]
    }
}

# 查询用户是否在群里

# host: https://yach-oapi.zhiyinlou.com 正式环境

# host: https://yach-oapi-test.zhiyinlou.com 测试环境

# 概述

名称 值
地址 /group/checkin?access_token=ACCESS_TOKEN
请求方式 POST
参数 见【参数】
返回值 见【返回值】

# 参数

参数 参数类型 必须 说明
access_token String 是 调用接口凭证
group_tid String 是 群id
user_id String 是 员工yach唯一标识，示例：yach076429

返回值

{
    "code": 200,
    "msg": "",
    "obj": {
        "status": 1（1:在群里面 0:不在群里面）
    }
}

# 获取群成员列表

# host: https://yach-oapi.zhiyinlou.com 正式环境

# host: https://yach-oapi-test.zhiyinlou.com 测试环境

# 概述

名称 值
地址 /group/users/list?access_token=ACCESS_TOKEN
请求方式 POST
参数 见【参数】
返回值 见【返回值】

# 参数

参数 参数类型 必须 说明
access_token String 是 调用接口凭证
group_tid String 是 群id
page String 否 当前页数，默认1
count String 否 每页显示条数，最大100

返回值

{
    "code": 200,
    "msg": "",
    "obj": {
        "total":100, // 群成员总数
        "list": [
            {
                 "uuid": "Yach137620", // 用户yachid
                 "name": "好好学习", // 用户姓名
                 "pic": "", // 用户头像
                 "group_users_type": 0 // 用户在群里的类型（0:群主 1:管理员 2:普通用户）
            },
            {
                 "uuid": "Yach076429", // 用户yachid
                 "name": "天天向上", // 用户姓名
                 "pic": "", // 用户头像
                 "group_users_type": 2 // 用户在群里的类型（0:群主 1:管理员 2:普通用户）
            }
    }
}

# 获取群管理员和群主

# host: https://yach-oapi.zhiyinlou.com 正式环境

# host: https://yach-oapi-test.zhiyinlou.com 测试环境

# 概述

名称 值
地址 /group/manager?access_token=ACCESS_TOKEN
请求方式 POST
参数 见【参数】
返回值 见【返回值】

# 参数

参数 参数类型 必须 说明
access_token String 是 调用接口凭证
group_tid String 是 群id

返回值

{
    "code": 200,
    "msg": "",
    "obj": [
            {
                 "uuid": "Yach137620", // 用户yachid
                 "name": "好好学习", // 用户姓名
                 "work_code": "123001", // 用户工号
                 "group_users_type": 0 // 用户在群里的类型（0:群主 1:管理员 2:普通用户）
            },
            {
                 "uuid": "Yach076429", // 用户yachid
                 "name": "天天向上", // 用户姓名
                 "work_code": "456001", // 用户工号
                 "group_users_type": 2 // 用户在群里的类型（0:群主 1:管理员 2:普通用户）
            }
    ]
}

# 获取/搜索用户所管理的群列表

# host: https://yach-oapi.zhiyinlou.com 正式环境

# host: https://yach-oapi-test.zhiyinlou.com 测试环境

# 概述

名称 值
地址 /group/manage/list
请求方式 POST
参数 见【参数】
返回值 见【返回值】

# 参数

参数 参数类型 必须 说明
access_token String 是 调用接口凭证
user_id String 是 用户的yachid
group_name String 否 群名称

返回值

{
    "code": 200,
    "msg": "",
    "obj": [
        {
             "group_tid": "3821638765", // 群组id
             "group_name": "好好学习", // 群组名称
             "group_icon": "", // 群组头像
             "group_users_count": 10 // 群人数
        }
    ]
}

# 添加群成员

# host: https://yach-oapi.zhiyinlou.com 正式环境

# host: https://yach-oapi-test.zhiyinlou.com 测试环境

# 概述

名称 值
地址 /group/users/add?access_token=ACCESS_TOKEN
请求方式 POST
参数 见【参数】
返回值 见【返回值】

# 参数

参数 参数类型 必须 说明
access_token String 是 调用接口凭证
group_tid String 是 群id
userid_list String 是 用户的yachid列表，Json字符串，示例：['Yach076429', 'Yach137620']
op_uid String 是 邀请人的yachid
group_type int 否 1为话题群，否则为普通群

返回值

{
    "code": 200,
    "msg": "",
    "obj": {}
}

# 移除群成员

# host: https://yach-oapi.zhiyinlou.com 正式环境

# host: https://yach-oapi-test.zhiyinlou.com 测试环境

# 概述

名称 值
地址 /group/users/del?access_token=ACCESS_TOKEN
请求方式 POST
参数 见【参数】
返回值 见【返回值】

# 参数

参数 参数类型 必须 说明
access_token String 是 调用接口凭证
group_tid String 是 群id
userid_list String 是 用户的yachid列表，Json字符串，示例：["Yach076429", "Yach137620"]
op_uid String 是 操作用户的yachid

返回值

{
    "code": 200,
    "msg": "",
    "obj": {}
}

# 更换群主

# host: https://yach-oapi.zhiyinlou.com 正式环境

# host: https://yach-oapi-test.zhiyinlou.com 测试环境

# 概述

名称 值
地址 /group/changeowner?access_token=ACCESS_TOKEN
请求方式 POST
参数 见【参数】
返回值 见【返回值】

# 参数

参数 参数类型 必须 说明
access_token String 是 调用接口凭证
group_tid String 是 群id
new_owner String 是 新群主的yachid
old_owner String 是 旧群主的yachid

返回值

{
    "code": 200,
    "msg": "",
    "obj": {}
}

# 设置群管理员

# host: https://yach-oapi.zhiyinlou.com 正式环境

# host: https://yach-oapi-test.zhiyinlou.com 测试环境

# 概述

名称 值
地址 /group/setadmin?access_token=ACCESS_TOKEN
请求方式 POST
参数 见【参数】
返回值 见【返回值】

# 参数

参数 参数类型 必须 说明
access_token String 是 调用接口凭证
group_tid String 是 群id
admin_users String 是 要设置的管理员yachid列表，Json字符串（单次最多10个管理员）
owner_uid String 是 群主的yachid

返回值

{
    "code": 200,
    "msg": "",
    "obj": {}
}

# 取消群管理员

# host: https://yach-oapi.zhiyinlou.com 正式环境

# host: https://yach-oapi-test.zhiyinlou.com 测试环境

# 概述

名称 值
地址 /group/removeadmin?access_token=ACCESS_TOKEN
请求方式 POST
参数 见【参数】
返回值 见【返回值】

# 参数

参数 参数类型 必须 说明
access_token String 是 调用接口凭证
group_tid String 是 群id
admin_users String 是 要取消的管理员yachid列表，Json格式（单次最多10个管理员）
owner_uid String 是 群主的yachid

返回值

{
    "code": 200,
    "msg": "",
    "obj": {}
}

# 获取群应用scheme

# host: https://yach-oapi.zhiyinlou.com 正式环境

# host: https://yach-oapi-test.zhiyinlou.com 测试环境

# 概述

名称 值
地址 /openapi/v2/group/app/info?access_token=ACCESS_TOKEN
请求方式 GET
参数 见【参数】
返回值 见【返回值】

# 参数

参数 参数类型 必须 说明
access_token String 是 调用接口凭证
group_tid String 是 群id
work_code String 是 操作人工号

返回值

{
  "code":200,
  "msg":"success",
  "obj":{
    "url":"yach://xxxxxxx?token=xxxx&group_tid=xxx"
  }
}

# 获取数字伙伴所在群聊

# host: https://yach-oapi.zhiyinlou.com 正式环境

# host: https://yach-oapi-test.zhiyinlou.com 测试环境

# 概述

名称 值
地址 /openapi/v2/dify/robot/groups?access_token=ACCESS_TOKEN
请求方式 GET
参数 无入参，只有access_token
返回值 见【返回值】

返回值

{
  "code":200,
  "msg":"success",
  "obj":[
    {
        "group_tid":"342432424",
        "group_name":"我是一个群",
        "group_owner":"我是群主",
        "group_type":100
    }
  ]
}

# 获取群聊会话历史记录

# host: https://yach-oapi.zhiyinlou.com 正式环境

# host: https://yach-oapi-test.zhiyinlou.com 测试环境

# 概述

名称 值
地址 /openapi/v2/im/messages
请求方式 GET
参数 见【参数】
返回值 见【返回值】

# 参数（URL参数）

参数 参数类型 必须 说明
access_token String 是 调用接口凭证（示例值：NHhmZXp0VEtwMExJTzhxxxxxxx）
start_time Number 是 消息查询开始时间戳（秒级，示例值：1773331200）
end_time Number 是 消息查询结束时间戳（秒级，示例值：1773787125）
page_size Number 是 每页查询条数（示例值：100）
group_id String 是 群组ID（示例值：123456）
descending Boolean 否 是否降序排列（示例值：false）
page_token String 否 分页令牌，用于翻页（示例值：xsVbx59PxsQ6wsnxxxxxxx）

# 请求示例（curl）

curl --request GET \
  --url 'https://yach-oapi-test.zhiyinlou.com/openapi/v2/im/messages?start_time=1773331200&end_time=1773787125&page_size=100&group_id=123456&access_token=NHhmZXp0VEtwMExJTzhjxxxxxx&include_no_sense_msg=false&descending=false&page_token=xsVbx59PxsQ6wsnRwERPxrxcwxxxxxxx' \
  --header 'Accept: */*' \
  --header 'Accept-Encoding: gzip, deflate, br' \
  --header 'Connection: keep-alive' \
  --header 'User-Agent: PostmanRuntime-ApipostRuntime/1.1.0'

# 响应结构

{
  "messages": [
    {
      "senderName": "张三",
      "uuid": "user-uuid-xxx",
      "workCode": "107320",
      "userType": 1,
      "time": 1711252800000,
      "type": "text",
      "content": "消息内容"
    }
  ],
  "page_info": {
    "page_token": "xxx",
    "has_more": true
  }
}

# 公共字段说明

字段 类型 说明
senderName string 发送者名称
uuid string 发送者 UUID
workCode string 发送者工号
userType int 用户类型：1=普通用户，2=机器人
time int64 消息时间（毫秒级时间戳）
type string 消息类型标识（见下方消息类型列表）
content string 消息内容（不同类型格式不同，见下方详细说明）

# 消息类型总览

# 按 message_type 分类

message_type type 值 说明
0 text 文本消息
2 audio 语音消息
5 tips 群通知消息
100 见下表 附件消息（按 attachment.type 细分）

# 附件消息类型（message_type=100）

attachment.type type 值 说明
3 group_nnouncement 群公告
5 file 文件（Office 类）
6 text 回复消息
7 merge_forward 合并转发
8 image 图片
10 file 文件（非 Office 类）
15 card 或 markdown_card Markdown 消息（无 clickUrl 为 card，有 clickUrl 为 markdown_card）
16 document 在线文档卡片
23 link 链接卡片
25 image 表情
30 video 视频
31 position 位置
40 profile 个人名片
47 group_profile 群名片
51 meeting_record 会议纪要
52 card 流式消息（AI 对话卡片）
53 discuss_group 讨论组卡片
54 text 讨论组根消息
55 sscard SSCard 卡片
56 prompt_card 提示词卡片
58 knowledge_node 知识库节点
59 knowledge 知识库空间
60 schedule 日程

# 各类消息 content 详细格式

# 1. 文本消息 (type: text)

content: 纯文本字符串

你好，这是一条文本消息

# 2. 语音消息 (type: audio)

content: 语音文件 URL

https://xxx.zhiyinlou.com/audio/xxx.aac

# 3. 群通知消息 (type: tips)

content: 可读的提示文本，根据 ope 类型不同：

ope content 示例
0 张三 邀请 李四、王五 加入群聊
1 张三 将 李四 移出了群聊
3 张三 修改群名为 新群名
7 张三 将 李四 设置为管理员
8 张三 移除了 李四 的管理员

# 4. 群公告 (type: group_nnouncement)

content: 群公告的 aid（公告 ID）

公告ID

机器人需要自行通过公告ID查询完整公告内容

# 5. 文件消息 (type: file)

content: 文件预签名 URL

https://yach-upload-test.zhiyinlou.com/presigned/xxx?sign=xxx&expire=xxx

# 6. 回复消息 (type: text)

content: 回复的文本内容

这是回复的内容

# 7. 合并转发 (type: merge_forward)

content: 合并转发的 uniq 标识符

merge-forward-uniq-xxx

机器人需要根据uniq查询合并转发的内容详情

# 8. 图片消息 (type: image)

content: 图片原始 URL

https://xxx.zhiyinlou.com/images/xxx.png

# 9. 表情消息 (type: image)

content: 表情图片 URL

https://xxx.zhiyinlou.com/emoji/xxx.gif

# 10. Markdown 消息 (type: card)

content: Markdown 内容字符串

<p>这是一条 markdown 消息</p>

# 11. Markdown 卡片消息 (type: markdown_card)

content: JSON 字符串，包含卡片信息

{
  "clickUrl": "https://example.com",
  "pcClickUrl": "https://example.com/pc",
  "mobileClickUrl": "https://example.com/mobile",
  "buttons": [
    [{"clickUrl": "https://btn1.com", "text": "按钮1"}]
  ],
  "content": {
    "content": "<p>卡片内容</p>"
  },
  "i18n": {
    "zh": {
      "clickUrl": "...",
      "pcClickUrl": "...",
      "mobileClickUrl": "...",
      "buttons": [...],
      "content": {"content": "..."}
    }
  }
}

# 12. 在线文档卡片 (type: document)

content: 在线文档链接

https://doc.zhiyinlou.com/xxx

# 13. 链接卡片 (type: link)

content: 链接 URL

https://example.com/article

# 14. 视频消息 (type: video)

content: 视频 URL

https://xxx.zhiyinlou.com/video/xxx.mp4

# 15. 位置消息 (type: position)

content: 地址文本

北京市海淀区中关村大街1号

# 16. 个人名片 (type: profile)

content: JSON 字符串

{
  "userId": "uuid-xxx",
  "pic": "https://xxx.zhiyinlou.com/avatar.png",
  "name": "张三",
  "workCode": "107320"
}

# 17. 群名片 (type: group_profile)

content: JSON 字符串

{
  "group_tid": "group-tid-xxx",
  "pic": "https://xxx.zhiyinlou.com/group-avatar.png",
  "name": "群名称"
}

# 18. 会议纪要 (type: meeting_record)

content: 会议纪要链接

https://meeting.zhiyinlou.com/record/xxx

# 19. 流式消息/AI 对话卡片 (type: card)

content: AI 回复的文本内容

这是 AI 助手的回复内容...

# 20. 讨论组卡片 (type: discuss_group)

content: JSON 字符串

{
  "create_userid": "uuid-xxx",
  "group_name": "讨论组名称",
  "tid": "组ID"
}

# 21. 讨论组根消息 (type: text)

content: 讨论组第一条消息的文本内容

这是讨论组的第一条消息

# 22. SSCard 卡片 (type: sscard)

content: yachMid 字符串

1234567890

机器人需要根据yachMid查询详情

# 23. 提示词卡片 (type: prompt_card)

content: JSON 字符串

{
  "title": "提示词标题",
  "content": "提示词内容"
}

# 24. 知识库节点 (type: knowledge_node)

content: 知识库节点链接

https://lore.zhiyinlou.com/node/xxx

# 25. 知识库空间 (type: knowledge)

content: 知识库空间链接

https://lore.zhiyinlou.com/space/xxx

# 26. 日程 (type: schedule)

content: JSON 字符串，包含完整日程信息

{
  "eid": "event-id",
  "title": "团队周会",
  "summary": "讨论本周进展",
  "begin_time": 1711252800,
  "finish_time": 1711256400,
  "location": "会议室A",
  "creator": "creator-uuid",
  "share_uid": "sharer-uuid",
  "repeat_type": 0,
  "repeat_txt": "",
  "is_full": 0,
  "is_outside": 0,
  "source": 0,
  "scene_type": 0,
  "msg_type": 0,
  "msg_title": "...",
  "msg_resp_state": 0,
  "labels": null,
  "document_info": null,
  "attachments": null,
  "attachments_total": 0
}

# 备注

  1. 文件消息预签名：文件类消息，content 返回的是预签名后的临时下载 URL（有效期 30 分钟），不是永久链接。
  2. 翻页：使用 page_token 翻页，has_more=true 表示还有更多数据。
  3. 不支持的消息类型：不在上述列表中的消息类型会被过滤掉，不返回。

← 普通消息 →

foo