拉取客服号(多语言)

最近更新时间:2026-03-31 15:07:59

我的收藏

接口调用说明

客服号是用户咨询的对话入口,不是一个人工客服。客服号用于"应用/客户端"的自定义开发集成方式。客服号更详细的说明可参见 多客服号场景方案
通过该接口可拉取客服号列表,客服号语言相关配置。

请求 URL 示例

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

请求参数说明

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

请求包示例

{
}
{
"IMAgentUserIDList": ["@customer_service_account","@customer_service_account_01"]
}

请求包字段说明

字段
类型
属性
说明
IMAgentUserIDList
Array
选填
获取特定的多语言客服号列表,不填该字段则拉取全量的多语言客服号列表。

应答包体示例

{
"ActionStatus": "OK",
"ErrorInfo": "",
"ErrorCode": 0,
"Data": [
{
"IMAgentUserID": "@customer_service_account",
"IMAgentNick": "衣服官方旗舰店",
"IMAgentAvatarUrl": "avatar URL 1",
"ChatbotDisabled": 0,
"AgentGroupId": 1234,
"RobotId": "@RBT#DeskDefaultRobot",
"GroupChatMode": 0,
"CallbackSwitchBeforeIMContactUser": 0,
"ContactUserCallbackTimeoutStrategy": 0,
"MultilingualSettings": {
"zh": {
"WelcomeMessage": "欢迎咨询衣服官方旗舰店,很高兴为您服务!",
"TransferToHumanPrompt": "正在为您转接,请稍候",
"TransferToHumanSuccessPrompt": "转接人工成功,客服${StaffNickName}为您服务",
"TransferToHumanFailPrompt": "抱歉,当前无客服在线,请稍后再试",
"QueueingPrompt": "您的问题我们已经收到。当前咨询人数较多,您目前排在第${QueuePosition}位,前面还有${WaitNo}人,感谢您的耐心等待",
"UserTimeout": 600,
"EndPrompt": "本次服务已结束,感谢您的支持",
"TimeoutEndPrompt": "由于您长时间未回复,本次服务已自动结束,感谢您的支持",
"WorkTimeConfig": {
"Type": 0
},
"NotWorkTimePrompt": "当前无客服在线,请您于工作时间咨询",
"IsDefault": 1,
"AssignmentStrategy": 1,
"ChooseSkillGroupPrompt": "请选择分组",
"DisplayGroupsChoices": [1,2,3],
"RemindUserBeforeUserTimeout": 60,
"RemindUserPromptBeforeUserTimeout": "由于您长时间未回复,会话将于60秒结束。",
"RemindAgentBeforeUserTimeout": 60,
"RemindAgentPromptBeforeUserTimeout": "会话还有60秒结束,如有需要请及时联系用户。",
"AppeaseUserBeforeAgentRspTimeout": 60,
"AppeaseUserPromptBeforeAgentRspTimeout": "目前咨询量较大,正在全力为您处理,请您耐心等待片刻。",
"Satisfaction": {
"InvitationMethod": 3,
"SatisfactionContent": {
"RatingInvitationMessage": "感谢您使用我们的服务,请对此次服务进行评价。",
"SubmissionMessage": "感谢您对此次服务作出评价,祝您生活愉快,再见。",
"OneStarContent": "非常不满意。",
"TwoStarContent": "不满意。",
"ThreeStarContent": "一般。",
"FourStarContent": "满意。",
"FiveStarContent": "非常满意。",
"SubmissionValidityPeriod": 12
}
}
},
"en": {
"WelcomeMessage": "Welcome! How can we help you?",
"TransferToHumanPrompt": "Transferring you to an agent, please wait",
"TransferToHumanSuccessPrompt": "Connected to agent ${StaffNickName}",
"TransferToHumanFailPrompt": "Sorry, no agents are available. Please try again later",
"QueueingPrompt": "You are at position ${QueuePosition}, ${WaitNo} people ahead",
"UserTimeout": 600,
"EndPrompt": "This session has ended. Thank you!",
"TimeoutEndPrompt": "Session ended due to inactivity",
"WorkTimeConfig": {
"Type": 0
},
"NotWorkTimePrompt": "No agents available, please contact us during business hours",
"IsDefault": 0,
"AssignmentStrategy": 0,
"Satisfaction": {
"InvitationMethod": 1,
"SatisfactionContent": {
"RatingInvitationMessage": "Thank you for using our service, please rate this session.",
"SubmissionMessage": "Thank you for your feedback. Have a nice day!",
"OneStarContent": "Very Dissatisfied",
"TwoStarContent": "Dissatisfied",
"ThreeStarContent": "Neutral",
"FourStarContent": "Satisfied",
"FiveStarContent": "Very Satisfied",
"SubmissionValidityPeriod": 12
}
}
}
}
}
]
}

应答包字段说明

顶层字段说明:
字段
类型
说明
ErrorCode
Integer
错误码:
0表示成功。
非0表示失败。
ErrorInfo
String
错误信息。
ActionStatus
String
请求处理的结果。
Data
Array
多语言客服号列表。
Data 中每个元素的顶层字段说明:
字段
类型
说明
IMAgentUserID
String
客服号的 UserID。
IMAgentNick
String
客服号的昵称。
IMAgentAvatarUrl
String
客服号的头像 URL。
ChatbotDisabled
Integer
该客服号是否停用机器人,0为启用机器人,1为停用机器人。
AgentGroupId
Integer
关联的 客服分组 ID。
RobotId
String
当前客服号绑定的机器人。
GroupChatMode
Integer
客服号支持的群聊模式:
0:不支持群聊。
1:客服工作台接待群聊咨询。
2:智能机器人群聊被@时回复。
CallbackSwitchBeforeIMContactUser
Integer
主动联系客户之前回调开关,0为不开启,1为开启。默认不开启。
ContactUserCallbackTimeoutStrategy
Integer
客服主动联系之前回调 超时策略,0为超时允许主动联系,1为超时不允许主动联系,默认超时允许主动联系。
QueueLeavePageTimeoutEnable
Integer
排队中离开页面超时结束(默认关闭):
0:关闭。
1:开启。
QueueLeavePageTimeout
Integer
排队中离开页面超时时间,单位秒。
MultilingualSettings
Object
多语言配置,key 为语言标识(例如 "zh"、"en" 等),value 为该语言下的客服号配置。
当前支持的语言包括:简体中文(zh)、繁体中文(zh-TW)、英语(en)、日语(ja)、菲律宾语(fil)、马来语(ms)、印尼语(id)、泰语(th)、越南语(vi)、俄语(ru)、韩语(ko)、西班牙语(es)。
MultilingualSettings 中每种语言的字段说明:
字段
类型
说明
WelcomeMessage
String
欢迎语。
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为每周计划类型,2为法定工作日类型。
Periods
Array
人工客服工作时间的具体设置。
Day
String
可选值为:Monday,Tuesday,Wednesday,Thursday,Friday,Saturday,Sunday。
PeriodsWithinOneDay
Array
每一天的具体工作时间。
Start
String
工作时间的开始时间点。
End
String
工作时间的结束时间点。
NotWorkTimePrompt
String
非人工客服工作时间的自动回复。
IsDefault
Integer
是否为默认语言配置,0为否,1为是。
AssignmentStrategy
Integer
转人工分配策略,值为0时表示自动分配,为1时表示用户选择分组,为2时表示业务服务器分配。
ChooseSkillGroupPrompt
String
用户选择分组的提示语。
DisplayGroupsChoices
Array
分配策略是用户选择分组时的显示分组,是一个整数数组。
AssignedByWebhookURL
String
分配策略是业务服务器分配时的回调 URL。
RemindUserBeforeUserTimeout
Integer
用户超时前多久提醒用户,单位秒,取值范围0 - 86400,设置为0表示关闭该功能。
RemindUserPromptBeforeUserTimeout
String
用户超时前多久提醒用户提示语。
RemindAgentBeforeUserTimeout
Integer
用户超时前多久提醒客服,单位秒,取值范围0 - 86400,设置为0表示关闭该功能。
RemindAgentPromptBeforeUserTimeout
String
用户超时前提醒客服提示语。
AppeaseUserBeforeAgentRspTimeout
Integer
客服多久未响应安抚用户,单位秒,取值范围0 - 86400,设置为0表示关闭该功能。
AppeaseUserPromptBeforeAgentRspTimeout
String
客服超时响应安抚用户提示语。
AssignCallbackTimeoutStrategy
Integer
业务服务器分配客服回调 超时回调策略。
0为超时继续分配。
1为超时不继续分配。
默认超时继续分配。
PrioritizeAssignmentToTheLastMember
Integer
优先分配给上次接待客服。
0为关闭。
1为开启。
TransHumanConfirmEnabled
Integer
转人工排队人数超过阈值后二次确认开关(默认关闭):
0:关闭。
1:开启。
TransHumanConfirmQueueThreshold
Integer
转人工触发二次确认的排队人数阈值。
TransHumanConfirmPrompt
String
转人工排队超过阈值时的二次确认提示语,可使用参数 ${WaitNo} 表示前方排队人数,从 0 开始计算。
Satisfaction
Object
满意度评价设置。
InvitationMethod
Integer
邀评方式:
0表示关闭满意度评价
1表示会话结束后自动发送。
2表示客服主动邀评。
3表示两种方式。
默认关闭满意度评价。
SatisfactionContent
Object
满意度评价内容。
SatisfactionContent.RatingInvitationMessage
String
邀请评价的提示语。
SatisfactionContent.SubmissionMessage
String
提交评价后的感谢语。
SatisfactionContent.OneStarContent
String
一星评价的内容,例如:非常不满意。
SatisfactionContent.TwoStarContent
String
二星评价的内容,例如:不满意。
SatisfactionContent.ThreeStarContent
String
三星评价的内容,例如:一般。
SatisfactionContent.FourStarContent
String
四星评价的内容,例如:满意。
SatisfactionContent.FiveStarContent
String
五星评价的内容,例如:非常满意。
SatisfactionContent.SubmissionValidityPeriod
Integer
提交评价的有效期,单位为小时。

错误码说明

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

接口调试工具

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