文档反馈官招募中，报名立赚积分兑换代金券！> HOT
文档中心>即时通信 IM>智能客服（Desk）>服务端 API>REST API>自定义角色管理>添加自定义角色

添加自定义角色

最近更新时间：2025-11-12 09:29:21

我的收藏

本页目录：

接口调用说明

业务可以通过该接口新增角色，为角色添加权限，并设置角色中包含的客服人员。

请求 URL 示例

https://console.tim.qq.com/v4/desk_http_svc/add_role?sdkappid=88888888&identifier=admin&usersig=xxx&random=99999999&contenttype=json

请求参数说明

下表仅列出调用本接口时涉及修改的参数及其说明，更多参数详情请参见 REST API 简介。
参数
说明
v4/desk_http_svc/add_role
请求接口。
sdkappid
创建应用时即时通信 IM 控制台分配的 SDKAppID。
identifier
必须为 App 管理员账号，更多详情请参见 App 管理员。
usersig
App 管理员账号生成的签名，具体操作请参见 生成 UserSig。
random
请输入随机的32位无符号整数，取值范围0 - 4294967295。
contenttype
请求格式固定值为 json。

请求包示例

新增角色、关联的权限、包含的客服成员以及角色可见的客服分组权限范围。
{
    "RoleName": "售后",   // 角色名称
    "MemberList": [    // 客服成员
        "767480289@qq.com"  
        "87673211@qq.com"
    ],
    "PermissionList": [  // 角色对应的权限
        "CHAT_WORKBENCH"   // 工作台权限
    ],
    "MemberGroupIDList": [    // 角色可见的客服分组权限范围
        4153    // 客服分组Id
    ]
}
新增角色、关联的权限和包含的客服成员
{
    "RoleName": "售后",   // 角色名称
    "MemberList": [    // 客服成员
        "767480289@qq.com"  
        "87673211@qq.com"
    ],
    "PermissionList": [  // 角色对应的权限
        "CHAT_WORKBENCH"    // 工作台权限
    ]
}

请求包字段说明

字段
类型
属性
说明
RoleName
String
必填
角色名称。
MemberList
Array
选填
角色中包含的客服成员。
PermissionList
Array
选填
角色对应的权限，目前仅支持 CHAT_WORKBENCH 工作台权限。
MemberGroupIDList
Array
选填
角色对应的客服分组权限范围。表示该角色在工作台模块内可见的客服分组，例如客服转接的时候可见的客服分组。

应答包体示例

{
    "ActionStatus": "OK",
    "ErrorCode": 0,
    "ErrorInfo": "",
    "RoleID": 626
}

应答包字段说明

字段
类型
说明
ErrorCode
Integer
错误码：
0表示成功。
非0表示失败。
ErrorInfo
String
错误信息。
ActionStatus
String
请求处理的结果。
RoleID
Integer
新创建的角色 ID。

错误码说明

除非发生网络错误（例如502错误），否则该接口的 HTTP 返回码均为200。真正的错误码，错误信息是通过应答包体中的 ErrorCode、ErrorInfo 来表示的。
公共错误码（60000到79999）参见 错误码 文档。
本 API 私有错误码如下：
错误码
描述
141002
内部错误，请重试。
141004
参数非法。

接口调试工具

通过 REST API 在线调试工具 调试本接口。

参考

修改自定义角色（v4/desk_http_svc/modify_role）
中国站
目录