文档反馈官招募中，报名立赚积分兑换代金券！> HOT
文档中心>即时通信 IM>智能客服（Desk）>服务端配置>服务端 API>客服号相关接口>创建客服号

创建客服号

最近更新时间：2025-07-02 21:13:41

我的收藏

本页目录：

客服号是用户咨询的对话入口，而不是一个人工客服。客服号用于"应用/客户端"的自定义开发集成方式。客服号更详细的说明可参见 多客服号场景方案。
当您的业务需要多个咨询入口时，可通过创建多个客服号实现。

接口调用说明

通过该接口创建客服号，可以为该客服号设置欢迎语、关联的客服分组、客服工作时间等。

接口请求限制

智能客服试用版、标准版，限 10 个渠道账号（包括客服号）。
智能客服高级版，限 200 个渠道账号（包括客服号）。如果您需创建客服号超过 200 个，请 提交工单 联系我们。

请求 URL 示例

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

请求参数说明

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

请求包示例

分配策略是自动分配，不打开人工客服工作时间判断。
{
    "IMAgentUserID": "yourUserID",
    "IMAgentNick": "衣服官方旗舰店",
    "IMAgentAvatarUrl": "your avatar",
    "WelcomeMessage": "欢迎咨询衣服官方旗舰店，很高兴为您服务！",
    "ChatbotDisabled": 0,
    "AgentGroupId": 1234,
    "TransferToHumanPrompt": "正在为您转接，请稍候",
    "TransferToHumanSuccessPrompt": "转接人工成功，客服${StaffNickName}为您服务",
    "TransferToHumanFailPrompt": "抱歉，当前无客服在线，请稍后再试",
    "QueueingPrompt": "您的问题我们已经收到。当前咨询人数较多，您目前排在第${QueuePosition}位，前面还有${WaitNo}人，感谢您的耐心等待",
    "UserTimeout": 600,
    "EndPrompt": "本次服务已结束，感谢您的支持",
    "TimeoutEndPrompt": "由于您长时间未回复，本次服务已自动结束，感谢您的支持",
    "WorkTimeConfig": {
      "Type":0
    },
    "NotWorkTimePrompt": "当前无客服在线，请您于工作时间咨询"
    "AssignmentStrategy": 0
}
分配策略是用户选择分组，打开人工客服工作时间判断，并指定周一上午09:00 - 11:30，下午的14:00 - 18:00，周五的上午09:00 - 12:00为人工客服的工作时间。
{
    "IMAgentUserID": "yourUserID",
    "IMAgentNick": "衣服官方旗舰店",
    "IMAgentAvatarUrl": "your avatar",
    "WelcomeMessage": "欢迎咨询衣服官方旗舰店，很高兴为您服务！",
    "ChatbotDisabled": 0,
    "AgentGroupId": 1234,
    "TransferToHumanPrompt": "正在为您转接，请稍候",
    "TransferToHumanSuccessPrompt": "转接人工成功，客服${StaffNickName}为您服务",
    "TransferToHumanFailPrompt": "抱歉，当前无客服在线，请稍后再试",
    "QueueingPrompt": "您的问题我们已经收到。当前咨询人数较多，您目前排在第${QueuePosition}位，前面还有${WaitNo}人，感谢您的耐心等待",
    "UserTimeout": 600,
    "EndPrompt": "本次服务已结束，感谢您的支持",
    "TimeoutEndPrompt": "由于您长时间未回复，本次服务已自动结束，感谢您的支持",
    "WorkTimeConfig": {
      "Type":1,
      "Periods": [
        {
          "Day": "Monday",
          "PeriodsWithinOneDay": [
              {
                "Start": "09:00",
                "End": "11:30"
              },
              {
                "Start": "14:00",
                "End": "18:00"
              }
          ]
        },
        {
          "Day": "Friday",
          "PeriodsWithinOneDay": [
              {
                "Start": "09:00",
                "End": "12:00"
              }
          ]
        }
      ]
    },
    "NotWorkTimePrompt": "当前无客服在线，请您于工作时间咨询",
    "AssignmentStrategy": 1,
    "ChooseSkillGroupPrompt": "请选择分组",
    "DisplayGroupsChoices": [1,2,3,4]
}

请求包字段说明

多语言配置的字段使用 Map<String, String> 类型，其中键是语言标签（例如：中文："zh", 英文："en"），值是对应语言的提示语。
字段
类型
属性
说明
IMAgentUserID
String
选填
客服号的 UserID，选填，若不填则会随机生成。
IMAgentNick
String
必填
客服号的昵称。
IMAgentAvatarUrl
String
必填
客服号的头像 URL。
WelcomeMessage
String
必填
欢迎语。
ChatbotDisabled
Integer
必填
该客服号是否停用机器人，0为启用机器人，1为停用机器人。
AgentGroupId
Integer
必填
关联的 客服分组 ID。
TransferToHumanPrompt
String
必填
转人工中提示语。
TransferToHumanSuccessPrompt
String
必填
转人工成功提示语。可使用参数 ${StaffNickName}，表示当前接待的客服昵称。
TransferToHumanFailPrompt
String
必填
转人工失败提示语。
QueueingPrompt
String
必填
排队提示语。可使用参数：${QueuePosition} 表示当前排队位置，从 1 开始计算；${WaitNo} 表示前方排队人数，从 0 开始计算。
UserTimeout
Integer
必填
转人工后，用户应答超时的会话自动结束时间，单位为秒。
EndPrompt
String
必填
用户或客服主动结束会话，系统自动发送的提示语。
TimeoutEndPrompt
String
必填
用户超时未回复，会话自动结束后系统发送的提示语。
WorkTimeConfig
Object
必填
人工客服工作时间设置。
Type
Integer
必填
人工客服工作时间的类型，0为不打开工作时间设置，1为打开。
Periods
Array
选填
人工客服工作时间的具体设置。
Day
String
选填
可选值为：Monday，Tuesday，Wednesday，Thursday，Friday，Saturday，Sunday。
PeriodsWithinOneDay
Array
选填
每一天的具体工作时间。
Start
String
选填
工作时间的开始时间点。
End
String
选填
工作时间的结束时间点。
NotWorkTimePrompt
String
必填
非人工客服工作时间的自动回复。
AssignmentStrategy
Integer
选填
转人工分配策略，值为0时表示自动分配，为1时表示用户选择分组，此时需填 DisplayGroupsChoices 参数，为2时表示业务服务器分配，此时需填 AssignedByWebhookURL 参数。默认为0。
ChooseSkillGroupPrompt
String
选填
用户选择分组的提示语。
DisplayGroupsChoices
Array
选填
分配策略是用户选择分组时的显示分组，是一个整数数组。
AssignedByWebhookURL
String
选填
分配策略是业务服务器分配时的回调 URL。
RobotId
String
选填
要绑定的机器人 ID。
需提前 创建机器人。
WelcomeMessageMultilingual
Map<String, String>
选填
欢迎语的多语言配置。
TransferToHumanPromptMultilingual
Map<String, String>
选填
转人工中提示语的多语言配置。
TransferToHumanSuccessPromptMultilingual
Map<String, String>
选填
转人工成功提示语的多语言配置。可使用参数 ${StaffNickName}，表示当前接待的客服昵称。
TransferToHumanFailPromptMultilingual
Map<String, String>
选填
转人工失败提示语的多语言配置。
QueueingPromptMultilingual
Map<String, String>
选填
排队提示语的多语言配置。可使用参数：${QueuePosition} 表示当前排队位置，从 1 开始计算；${WaitNo} 表示前方排队人数，从 0 开始计算。
EndPromptMultilingual
Map<String, String>
选填
用户或客服主动结束会话，系统自动发送的提示语的多语言配置。
TimeoutEndPromptMultilingual
Map<String, String>
选填
用户超时未回复，会话自动结束后系统发送的提示语的多语言配置。
NotWorkTimePromptMultilingual
Map<String, String>
选填
非人工客服工作时间的自动回复的多语言配置。
ChooseSkillGroupPromptMultilingual
Map<String, String>
选填
用户选择分组提示语 的多语言配置。
GroupChatMode
Integer
选填
客服号支持的群聊模式（默认不支持群聊）：
0：不支持群聊。
1：客服工作台接待群聊咨询。
2：智能机器人群聊被@时回复。
RemindUserBeforeUserTimeout
Integer
选填
用户超时前多久提醒用户，单位秒，取值范围1 - 86400。
RemindUserPromptBeforeUserTimeout
String
选填
用户超时前多久提醒用户提示语。
RemindUserPromptBeforeUserTimeoutMultilingual
Map<String, String>

选填
用户超时前多久提醒用户提示语多语言配置。
RemindAgentBeforeUserTimeout
Integer
选填
用户超时前多久提醒客服，单位秒，取值范围1 - 86400。
RemindAgentPromptBeforeUserTimeout
String
选填
用户超时前提醒客服提示语。
RemindAgentPromptBeforeUserTimeoutMultilingual
Map<String, String>

选填
用户超时前提醒客服提示语多语言配置。
AppeaseUserBeforeAgentRspTimeout
Integer
选填
客服多久未响应安抚用户，单位秒，取值范围1 - 86400。
AppeaseUserPromptBeforeAgentRspTimeout
String
选填
客服超时响应安抚用户提示语。
AppeaseUserPromptBeforeAgentRspTimeoutMultilingual
Map<String, String>

选填
客服超时响应安抚用户提示语多语言配置。

应答包体示例

{
    "ActionStatus": "OK",
    "ErrorInfo": "",
    "ErrorCode": 0,
    "IMAgentUserID": "iamTu5QojCp7TtUAMoLx7Cdt0ucHtDL1"
}

应答包字段说明

字段
类型
说明
ErrorCode
Integer
错误码：
0表示成功。
非0表示失败。
ErrorInfo
String
错误信息。
ActionStatus
String
请求处理的结果。
IMAgentUserID
String
客服号的 UserID。

错误码说明

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

接口调试工具

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

参考

查询单聊消息（v4/openim/admin_getroammsg）
中国站
目录