飞书开放平台 Server API 文档

主题

查询全部工单详情 ​

该接口用于获取全部工单详情。仅支持自建应用。

请求 ​

项目值
HTTP URLhttps://open.feishu.cn/open-apis/helpdesk/v1/tickets
HTTP MethodGET
接口频率限制1000 次/分钟、50 次/秒
支持的应用类型custom
权限要求 调用该 API 所需的权限。开启其中任意一项权限即可调用helpdesk:all:readonly 获取服务台资源详情

请求头 ​

名称类型必填描述
Authorizationstring是tenant_access_token 值格式："Bearer access_token" 示例值："Bearer t-7f1bcd13fc57d46bac21793a18e560" 了解更多：如何选择与获取 access token

Tip: 服务台请求Header中还需添加“服务台token”参数：

Key: X-Lark-Helpdesk-Authorization

Value: base64(helpdesk_id:helpdesk_token)，通过base64加密将helpdesk_id和helpdesk_token用':'连接而成的字符串。

了解更多：获取与使用服务台token

查询参数 ​

名称类型必填描述
ticket_idstring否搜索条件：工单ID
示例值：123456
agent_idstring否搜索条件: 客服id
示例值：ou_b5de90429xxx
closed_by_idstring否搜索条件: 关单客服id
示例值：ou_b5de90429xxx
typeint否搜索条件: 工单类型 1:bot 2:人工
示例值：1
channelint否搜索条件: 工单渠道
示例值：0
solvedint否搜索条件: 工单是否解决 1:没解决 2:已解决
示例值：1
scoreint否搜索条件: 工单评分
示例值：1
status_listint\[\]否搜索条件: 工单状态列表
示例值：1
guest_namestring否搜索条件: 用户名称
示例值：abc
guest_idstring否搜索条件: 用户id
示例值：ou_b5de90429xxx
tagsstring\[\]否搜索条件: 用户标签列表
示例值：备注
pageint否页数, 从1开始, 默认为1
示例值：1
page_sizeint否当前页大小，最大为200， 默认为20。分页查询最多累计返回一万条数据，超过一万条请更改查询条件，推荐通过时间查询。
示例值：20
create_time_startint否搜索条件: 工单创建起始时间 ms (也需要填上create_time_end)，相当于>=create_time_start
示例值：1616920429000
create_time_endint否搜索条件: 工单创建结束时间 ms (也需要填上create_time_start)，相当于<=create_time_end
示例值：1616920429000
update_time_startint否搜索条件: 工单修改起始时间 ms (也需要填上update_time_end)
示例值：1616920429000
update_time_endint否搜索条件: 工单修改结束时间 ms(也需要填上update_time_start)
示例值：1616920429000

响应 ​

响应体 ​

名称类型描述
codeint错误码，非 0 表示失败
msgstring错误描述
data\--
  └ totalint工单总数 (单次请求最大为10000条)
  └ ticketsticket\[\]工单
    └ ticket_idstring工单ID
可以从工单列表里面取
也可以订阅工单创建事件获取
    └ helpdesk_idstring服务台ID
    └ guestticket_user工单创建用户
      └ idstring用户ID
      └ avatar_urlstring用户头像url
      └ namestring用户名
      └ emailstring用户邮箱
      └ departmentstring所在部门名称
      └ citystring城市
      └ countrystring国家代号(CountryCode)，参考：http://www.mamicode.com/info-detail-2186501.html
    └ commentscomments备注
      └ contentstring备注
      └ created_atint备注时间，单位毫秒
      └ idint备注ID
      └ user_avatar_urlstring备注人头像
      └ user_namestring备注人姓名
      └ user_idint备注人ID
    └ ticket_typeint工单阶段：1. 机器人 2. 人工
    └ statusint工单状态，1：已创建 2: 处理中 3: 排队中 4：待定 5：待用户响应 50: 被机器人关闭 51: 被客服关闭 52: 用户自己关闭
    └ scoreint工单评分，1：不满意，2:一般，3:满意
    └ created_atint工单创建时间
    └ updated_atint工单更新时间，没有值时为-1
    └ closed_atint工单结束时间
    └ dissatisfaction_reasoni18n不满意原因
      └ zh_cnstring中文描述
      └ en_usstring英文描述
      └ ja_jpstring日文描述
    └ agentsticket_user\[\]工单客服
      └ idstring用户ID
      └ avatar_urlstring用户头像url
      └ namestring用户名
      └ emailstring用户邮箱
      └ departmentstring所在部门名称
      └ citystring城市
      └ countrystring国家代号(CountryCode)，参考：http://www.mamicode.com/info-detail-2186501.html
    └ channelint工单渠道，描述： 9：Open API 2：二维码 14：分享 13：搜索 其他数字：其他渠道
    └ solveint工单是否解决 1:没解决 2:已解决
    └ closed_byticket_user关单用户ID
      └ idstring用户ID
      └ avatar_urlstring用户头像url
      └ namestring用户名
      └ emailstring用户邮箱
      └ departmentstring所在部门名称
      └ citystring城市
      └ countrystring国家代号(CountryCode)，参考：http://www.mamicode.com/info-detail-2186501.html
    └ collaboratorsticket_user\[\]工单协作者
      └ idstring用户ID
      └ avatar_urlstring用户头像url
      └ namestring用户名
      └ emailstring用户邮箱
      └ departmentstring所在部门名称
      └ citystring城市
      └ countrystring国家代号(CountryCode)，参考：http://www.mamicode.com/info-detail-2186501.html
    └ customized_fieldscustomized_field_display_item\[\]自定义字段列表，没有值时不设置 下拉菜单的value对应工单字段里面的children.display_name 获取全部工单自定义字段
      └ idstring自定义字段ID
      └ valuestring自定义字段值
      └ key_namestring键名
      └ display_namestring展示名称
      └ positionint展示位置
      └ requiredboolean是否必填
      └ editableboolean是否可修改
    └ agent_service_durationnumber(float)客服服务时长，客服最后一次回复时间距离客服进入时间间隔，单位分钟
    └ agent_first_response_durationint客服首次回复时间距离客服进入时间的间隔(秒)
    └ bot_service_durationint机器人服务时间：客服进入时间距离工单创建时间的间隔，单位秒
    └ agent_resolution_timeint客服解决时长，关单时间距离客服进入时间的间隔，单位秒
    └ actual_processing_timeint工单实际处理时间：从客服进入到关单，单位秒
    └ agent_entry_timeint客服进入时间，单位毫秒
    └ agent_first_response_timeint客服首次回复时间，单位毫秒
    └ agent_last_response_timeint客服最后回复时间，单位毫秒
    └ agent_ownerticket_user主责客服
      └ idstring用户ID
      └ avatar_urlstring用户头像url
      └ namestring用户名
      └ emailstring用户邮箱
      └ departmentstring所在部门名称
      └ citystring城市
      └ countrystring国家代号(CountryCode)，参考：http://www.mamicode.com/info-detail-2186501.html

响应体示例 ​

json
{
    "code": 0,
    "msg": "success",
    "data": {
        "total": 100,
        "tickets": [
            {
                "ticket_id": "6626871355780366331",
                "helpdesk_id": "6626871355780366330",
                "guest": {
                    "id": "ou_37019b7c830210acd88fdce886e25c71",
                    "avatar_url": "https://xxxx",
                    "name": "abc",
                    "email": "xxxx@abc.com",
                    "department": "用户部门名称(有权限才展示)",
                    "city": "城市",
                    "country": "国家"
                },
                "comments": {
                    "content": "备注内容",
                    "created_at": 1690970837624,
                    "id": 12,
                    "user_avatar_url": "备注人头像",
                    "user_name": "备注人姓名",
                    "user_id": 7262656095919128578
                },
                "ticket_type": 1,
                "status": 50,
                "score": 1,
                "created_at": 1616920429000,
                "updated_at": 1616920429000,
                "closed_at": 1616920429000,
                "dissatisfaction_reason": {
                    "zh_cn": "答案看不懂",
                    "en_us": "I don't understand",
                    "ja_jp": "回答が複雑すぎる"
                },
                "agents": [
                    {
                        "id": "ou_37019b7c830210acd88fdce886e25c71",
                        "avatar_url": "https://xxxx",
                        "name": "abc",
                        "email": "xxxx@abc.com",
                        "department": "用户部门名称(有权限才展示)",
                        "city": "城市",
                        "country": "国家"
                    }
                ],
                "channel": 0,
                "solve": 1,
                "closed_by": {
                    "id": "ou_37019b7c830210acd88fdce886e25c71",
                    "avatar_url": "https://xxxx",
                    "name": "abc",
                    "email": "xxxx@abc.com",
                    "department": "用户部门名称(有权限才展示)",
                    "city": "城市",
                    "country": "国家"
                },
                "collaborators": [
                    {
                        "id": "ou_37019b7c830210acd88fdce886e25c71",
                        "avatar_url": "https://xxxx",
                        "name": "abc",
                        "email": "xxxx@abc.com",
                        "department": "用户部门名称(有权限才展示)",
                        "city": "城市",
                        "country": "国家"
                    }
                ],
                "customized_fields": [
                    {
                        "id": "123",
                        "value": "value",
                        "key_name": "key",
                        "display_name": "display name",
                        "position": 1,
                        "required": true,
                        "editable": true
                    }
                ],
                "agent_service_duration": 42624.95,
                "agent_first_response_duration": 123869,
                "bot_service_duration": 1,
                "agent_resolution_time": 66,
                "actual_processing_time": 68,
                "agent_entry_time": 1636444596000,
                "agent_first_response_time": 1636444696000,
                "agent_last_response_time": 1636444796000,
                "agent_owner": {
                    "id": "ou_37019b7c830210acd88fdce886e25c71",
                    "avatar_url": "https://xxxx",
                    "name": "abc",
                    "email": "xxxx@abc.com",
                    "department": "用户部门名称(有权限才展示)",
                    "city": "城市",
                    "country": "国家"
                }
            }
        ]
    }
}

错误码 ​

HTTP状态码错误码描述排查建议
400154000Bad request, please check your request body请求不合法，请检查参数
500155000Internal error内部错误，请联系我们
401154001Unauthorized, please check you have the correct access检查Authorization 和 X-Lark-Helpdesk-Authorization 是否正确，应用和服务台属于同一租户

内容来源：飞书开放平台 · 自动爬取整理

本镜像仅供学习与查阅，文档版权归飞书所有