飞书开放平台 Server API 文档

主题

查询指定工单详情 ​

该接口用于获取单个服务台工单详情。仅支持自建应用。

请求 ​

项目值
HTTP URLhttps://open.feishu.cn/open-apis/helpdesk/v1/tickets/:ticket_id
HTTP MethodGET
接口频率限制10 次/秒
支持的应用类型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"

响应 ​

响应体 ​

名称类型描述
codeint错误码，非 0 表示失败
msgstring错误描述
data\--
  └ ticketticket_v2工单详情
    └ 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
    └ tagsticket_tag\[\]工单标签（仅工单含有工单标签会返回）
      └ idstring标签 ID
      └ namestring标签

响应体示例 ​

json
{
    "code": 0,
    "msg": "success",
    "data": {
        "ticket": {
            "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": "国家"
            },
            "tags": [
               {
                   "id": "7474857595946745884",
                   "name": "标签名称"
               }
           ]
        }
    }
}

错误码 ​

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

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

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