通过该文档,您可以将云联络中心访客端IM嵌入到第三方系统中,下面的工作需要您公司的前端工程师来实施。您可以随时关注该文档页面,SDK有更新时会及时更新文档页面。
一、前端资源
更新前端资源版本以后,一定要在本地环境做全面测试以后再发布线上环境!
<!-- IM sdk样式文件 -->
<link rel="stylesheet" type="text/css" href="//g.alicdn.com/code/npm/@ali/cc-im-sdk/{version-im-sdk}/index.css">
<!-- IM sdk js文件 -->
<script src="//g.alicdn.com/code/npm/@ali/cc-im-sdk/{version-im-sdk}/index.js"></script>
UI版本脚本资源请放在</body>标签之前,请勿放在head标签中,因为脚本加载后会对document.body做操作。
以上静态资源,把上面的{version-im-sdk}替换为对应的版本号,当前最新版本号为:
version-im-sdk ==> 1.4.0
二、使用
js加载完成后,在window
变量中会新增ccImSdk
参数变量,window.ccImSdk.visitorCcImSdk
是访客SDK实例。
1. 设置基础配置参数以使用
window.ccImSdk.visitorCcImSdk.setConfig({
visitorId: 'xxxxxxxx', // 必填且唯一,用以区分不同访客
ajaxToken: 'xxxx', //必填,渠道连接中的token参数
ajaxPath: '/v-api', // 接口请求的pathname
});
2. 渲染界面
渲染IM容器界面,用以聊天(可登录后渲染界面,也可不渲染界面,渲染界面的时机可自定义)
window.ccImSdk.visitorCcImSdk.render(document.getElementById('im-container'))
// render 方法传递一个dom元素作为IM渲染的容器
3. 登录
登录IM聊天服务
window.ccImSdk.visitorCcImSdk.login();
4. 订阅数据变化
window.ccImSdk.visitorCcImSdk.subscribe((data) => {
console.log('SUBSCRIBE: ', data); // 连接状态、消息变更、会话变更等数据会在此处传递
});
5. 销毁IM服务
销毁操作包含,退出登录、界面卸载等操作
window.ccImSdk.visitorCcImSdk.destroy();
三、服务端准备
前端的接口需要业务方服务器做代理转发(解决前端跨域),转发到云联络中心的服务端地址。
接口地址为:https://ccc-v2.aliyun.com/v-api
以Nginx代理为例,假设业务方域名为 ccc.example.com :
server {
listen 443 ssl; # 使用 ssl
server_name ccc.example.com; # 替换为您的域名
ssl_certificate /path/to/your/certificate.crt;
ssl_certificate_key /path/to/your/certificate.key;
location /v-api {
proxy_pass https://ccc-v2.aliyun.com;
proxy_set_header Host ccc-v2.aliyun.com;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}
可根据实际业务情况选择代理方案。
四、visitorCcImSdk
实例方法
使用window.ccImSdk.visitorCcImSdk
来调用方法。
setConfig
类型:
(config: CCIMSDKConfig) => void
设置配置参数。
getConfig
类型:
() => CCIMSDKConfig
获取当前配置参数。
subscribe
类型:
(cb: (data: SubscribeStoreModel) => void) => (() => void);
订阅数据变更,包括连接状态、消息变更、会话变更等,并返回取消订阅的方法。
login
类型:
() => Promise<void>
登入IM服务。
reConnect
类型:
() => Promise<string>
重新连接,当连接状态断开时,可调用。一般客户不需要自己调用,内部实现了自动重连
logout
类型:
() => Promise<void>
登出并关闭连接。
releaseChat
类型:
() => Promise<any>
结束当前会话。
sendMessage
类型:
(message: SendMessageModel) => Promise<void>
发送消息。注意当前必须已激活会话,才能成功发送消息。
recallMessage
类型:
(appCid: string, messageId: string) => Promise<void>
撤回一条消息。
getUnreadMessageIdList
类型:
() => string[]
获取未读消息ID列表。
updateMessageToRead
类型:
(appCidstring, msgIds: string[]) => Promise<void>
批量读取消息,更新消息状态为已读。可使用getUnreadMessageIdList
获取当前会话中所有未读的消息ID列表。或者通过消息中的readStatus
字段来判断消息是否已读,并传递给msgIds参数
。
getMessageList
类型:() => Promise<MessageModel[]>
获取当前会话的消息列表。
getPrevMessageList
类型:
(cursor: string, count: number) => Promise<number>
拉取历史消息列表。cursor
表示消息游标,count
获取消息数量。是否有历史消息和cursor
可以从subscribe
获取。
getNextMessageList
类型:
(cursor: string, count: number) => Promise<number>
拉取最新消息列表。cursor
表示消息游标,count
获取消息数量。是否有最新消息和cursor
可以从subscribe
获取。
render
类型:
(container: HTMLElement) => void
渲染IM界面。传递的container
需要是已加载的DOM元素。
unmount
卸载IM界面(登录状态还在),React的unmount
一致。再次调用render
方法可再次显示界面。
destroy
卸载IM服务,包括卸载界面和退出登录。
on
类型:
(eventName: EventNames, fn: (...args: any[]) => void) => void
监听事件。
off
类型:
(eventName: EventNames, fn?: (...args: any[]) => void) => void
取消监听事件。
五、数据类型
CCIMSDKConfig(配置参数)
参数 | 描述 | 类型 | 默认值 |
参数 | 描述 | 类型 | 默认值 |
visitorId | 必填且唯一,用以区分不同访客 |
| - |
ajaxToken | 当未设置 |
| - |
user | 用户信息
|
| - |
ajaxOrigin | 请求源,默认请求当前源。 |
|
|
ajaxPath | 请求路径 |
|
|
withCredentials | 表示跨域请求时是否需要使用凭证,是否允许携带cookie |
|
|
ajaxApiParamName | 指定区分action的名称 |
|
|
ajaxMethod | 请求方式 |
|
|
ajaxOtherParams | 其他自定义参数和 | object | - |
ajaxHeaders | 请求的header | object | - |
apiAxiosFunc | 支持客户自己写请求接口的方法,最终返回结果为一个promise对象且返回的数据格式要和云联络中心公有云数据接口返回格式一致。
|
| - |
chatContainerConfig | Chat 内容区域的配置项。
|
| - |
language | 国际化语言,默认
|
|
|
locales | 自定义国际化文案。
|
| 系统内置 |
featureConfig | 特性功能配置。默认取渠道配置中的数据。 | 渠道配置 |
FeatureConfig(特性功能配置)
参数 | 描述 | 类型 |
参数 | 描述 | 类型 |
portrait | 系统消息显示的头像字段。 |
|
portraitLink | 系统消息头像点击跳转的链接。 |
|
allowSendPicture | 允许发送图片 |
|
allowSendFile | 允许发送文件 |
|
allowSendVoice | 允许发送语音 注意:只在小屏幕下或者移动端生效 |
|
navbar | 自定义导航栏配置,默认值是在控制台渠道部署中配置 | |
themeColor | 主题颜色 |
|
bubbleBgColor | 消息背景色 |
|
displayAliyunLogo | 是否展示阿里云LOGO |
|
pcWindowSize | PC端窗口大小 |
|
pcBackground | PC端背景图片(当不是全屏展示聊天窗的时候显示的背景图)
|
|
placeholder | 输入框引导语 |
|
showMessageReadStatus | 是否展示消息已读状态 |
|
allowMessageWithdrawn | 是否允许撤回消息 |
|
systemNickname | 系统消息昵称 |
|
NavbarProps(导航栏属性)
参数 | 描述 | 类型 |
参数 | 描述 | 类型 |
avatar | 导航栏头像 |
|
title | 导航栏标题 |
|
titleColor | 导航栏标题的颜色 |
|
titleBackgroundColor | 导航栏标题区域的背景色(导航栏背景色) |
|
underlineStyle | 导航栏下边框的颜色 |
|
description | 导航栏描述 |
|
type | 导航栏类型
|
|
image | 当 |
|
tags | 标签列表,在标题后面显示自定义标签 |
|
SubscribeStoreModel(数据订阅模块)
参数 | 描述 | 类型 |
参数 | 描述 | 类型 |
appCid | 当前激活的会话ID,不激活为null |
|
jobId | 当前激活的工作ID,不激活为null |
|
messageIdList | 当前会话消息ID集合 |
|
messageMap | 当前会话消息集合 |
|
msgNextHasMore | 在当前消息列表的前提下,是否还有更多新消息 |
|
msgPrevHasMore | 在当前消息列表的前提下,是否还有更多历史消息 |
|
msgNextCursor | 加载新消息的 Cursor |
|
msgPrevCursor | 加载历史消息的 Cursor |
|
convIdList | 会话ID集合 |
|
convMap | 会话集合 |
|
connectionStatus | 会话服务连接状态 0: 未连接; 1: 连接中; 2: 已连接; 3: 登录中; 4: 已登录; 5: 连接失败; |
|
MessageModel(消息模块)
参数 | 描述 | 类型 |
参数 | 描述 | 类型 |
uuid | 本地消息发送的id,随机生成 |
|
messageId | 消息发送成功或者从远程接收的消息的ID(当消息还未发送成功时,与 |
|
code | 当前消息类型编码(除 |
|
createdAt | 消息创建时间戳 |
|
user | 发送人信息
|
|
appCid | 会话ID |
|
jobId | 聊天ID(jobId) |
|
isMyMsg | 是否是自己发送的消息 |
|
isSystem | 是否是系统消息 |
|
readStatus | 是否已读 自己的消息,则表示对方是否已读,否则表示自己是否已读 |
|
recalled | 是否已撤回 |
|
status | 发送状态 "sent":已发送 "pending":发送中 "fail":发送失败 |
|
data | 消息数据 TextMessageContent:文本消息(code: ImageMessageContent:图片消息(code: FileMessageContent:文件消息(code: VoiceMessageContent:语音消息(code: VideoMessageContent:视频消息(code: AudioMessageContent:音频消息(code: SatisfactionMessageContent:满意度消息(code: |
|
TextMessageContent(文本消息内容)
参数 | 描述 | 类型 |
参数 | 描述 | 类型 |
text | 文本消息内容 |
|
referenceMessage | 引用的消息内容
|
|
uploadProgress | 当富文本消息中包含图片时,会显示图片的上传进度 |
|
ImageMessageContent(图片消息内容)
参数 | 描述 | 类型 |
参数 | 描述 | 类型 |
picUrl | 图片链接 |
|
mediaId | 图片媒体ID,用来换取图片链接 |
|
messageId | 消息ID |
|
convId | 会话ID |
|
width | 图片宽度 |
|
height | 图片高度 |
|
FileMessageContent(文件消息)
参数 | 描述 | 类型 |
参数 | 描述 | 类型 |
file | 文件信息
|
|
fileUrl | 文件URL |
|
uploadProgress | 文件发送进度 |
|
VoiceMessageContent(语音消息)
参数 | 描述 | 类型 |
参数 | 描述 | 类型 |
duration | 语音时长 |
|
src | 语音文件资源链接 |
|
VideoMessageContent(视频消息)
参数 | 描述 | 类型 |
参数 | 描述 | 类型 |
duration | 视频时长 |
|
src | 视频文件资源链接 |
|
uploadProgress | 视频文件发送进度 |
|
AudioMessageContent(音频消息)
参数 | 描述 | 类型 |
参数 | 描述 | 类型 |
duration | 音频时长 |
|
src | 音频文件资源链接 |
|
uploadProgress | 音频文件发送进度 |
|
SatisfactionMessageContent(满意度消息)
参数 | 描述 | 类型 |
参数 | 描述 | 类型 |
surveyId | 满意度ID |
|
titleContent | 标题内容 |
|
helpContent | 帮助内容 | |
ratingScaleOptions | 评分选项
|
|
score | 已经评分的结果,未评分的话无值为 |
|
expireSeconds | 满意度卡片过期时间,单位秒 |
|
ConversationModel(会话模块)
参数 | 描述 | 类型 |
参数 | 描述 | 类型 |
convId | 会话ID |
|
jobId | 会话ID(报表) |
|
channelId | 渠道ID |
|
channelType | 渠道类型 |
|
createAt | 创建时间 |
|
released | 是否已结束 |
|
SendMessageModel(发送消息模块)
参数 | 描述 | 类型 |
参数 | 描述 | 类型 |
type | 消息类型:
|
|
content | 发送消息的内容 |
SendMessageContent(发送消息内容)
参数 | 描述 | 类型 |
参数 | 描述 | 类型 |
text | 文本内容 |
|
referenceMessageId | 引用消息的ID(必须是已经发送成功或接收的消息) |
|
file | 文件、图片、音频、视频、语音等文件上传的消息时必传 |
|
duration | 音视频消息、语音消息必填 |
|
width | 视频消息的视频宽度 |
|
height | 视频消息的视频高度 |
|
EventNames(监听事件名称)
事件名称 | 描述 |
事件名称 | 描述 |
| 加入会话 |
| 会话结束 |
| 新消息 |
| 消息变化 |
| 消息撤回 |
| 连接错误 |
| 连接断开 |
| 连接变化 |
| 接口异常 |
| 错误通知 |
六、国际化
目前项目中使用到的所有国际化文案如下(只列出中文部分),如要更改描述文案,只需要更改对应key的中文文案,使用 locales
字段替换。IMSDK的UI渲染依赖ChatSDK,部分组件的国际化请参考ChatSDK国际化部分。
{
"ccImSdk.NetworkRequestException": "网络请求异常",
"ccImSdk.DisconnectPleaseCheckTheNetwork": "连接断开请检查网络后,刷新页面重试",
"ccImSdk.NoSessionIsCurrentlyActivated": "当前没有激活的会话",
"ccImSdk.TheSessionHasEndedAnd": "会话已结束,不能释放会话",
"ccImSdk.TheCurrentSessionHasEnded": "当前会话已结束,不能释放会话",
"ccImSdk.TheCurrentSessionDoesNot": "当前会话不存在",
"ccImSdk.TheSessionHasEndedAnd.1": "会话已结束,不能撤回消息",
"ccImSdk.BrandLogo.Pass": "通过",
"ccImSdk.BrandLogo.Support": "支持",
"ccImSdk.Messages.Download": "下载",
"ccImSdk.Messages.ReEdit": "重新编辑",
"ccImSdk.Messages.Copy": "复制",
"ccImSdk.Messages.Withdraw": "撤回",
"ccImSdk.Messages.Reference": "引用",
"ccImSdk.Messages.Read": "已读",
"ccImSdk.Messages.Unread": "未读",
"ccImSdk.SatisfactionMessage.AreYouSureYouWant": "有满意度评价未提交,确定离开吗?",
"ccImSdk.Claim": "认领",
"ccImSdk.CurrentlyItIsInDraft": "目前为草稿模式,确认要发送吗?",
"ccImSdk.Ok": "确定",
"ccImSdk.Cancel": "取消",
"ccImSdk.RichtextEditor.FileUpload": "文件上传",
"ccImSdk.RichtextEditor.QuickReply.QuickReply": "快捷回复",
"ccImSdk.RichtextEditor.QuickReply.Evoke": "/ 唤起",
"ccImSdk.RichtextEditor.QuickReply.Switch": "↑ ↓ 切换",
"ccImSdk.RichtextEditor.QuickReply.WomenSClothing": "└┘",
"ccImSdk.RichtextEditor.QuickReply.Selected": "选中",
"ccImSdk.RichtextEditor.QuickReply.NoRelevantQuickReplyIs": "暂无相关快捷回复",
"ccImSdk.RichtextEditor.PleaseEnterAMessage": "请输入消息",
"ccImSdk.RichtextEditor.Send": "发送",
"ccImSdk.RichtextEditor.AiErrorCorrection": "AI纠错",
"ccImSdk.RichtextEditor.AiExpansion": "AI扩写",
"ccImSdk.RichtextEditor.SpeechOptimization": "话术优化",
"ccImSdk.RichtextEditor.ReplaceDialogBoxContent": "替换对话框内容",
"ccImSdk.RichtextEditor.TheContentIsBeingGenerated": "内容正在AI生成中,请稍后...",
"ccImSdk.RichtextEditor.ExitDraft": "退出草稿",
"ccImSdk.RichtextEditor.Draft": "草稿",
"ccImSdk.RichtextEditor.SecondConfirmationIsRequiredFor": "打开草稿模式消息发送需要二次确认",
"ccImSdk.ProblemCard.Faq": "常见问题:",
"ccImSdk.ProblemCard.NoDataAvailable": "暂无数据",
"ccImSdk.ToolsCard.CommonTools": "常用工具:",
"ccImSdk.showModel.Confirm": "确认",
"ccImSdk.showModel.Cancel": "取消",
"ccImSdk.NoConsultation": "暂无咨询",
"ccImSdk.ChatApp.Expression": "表情",
"ccImSdk.ChatApp.PhotoAlbum": "相册",
"ccImSdk.ChatApp.File": "文件",
"ccImSdk.ChatApp.ClickLoadMore": "点击加载更多",
"ccImSdk.CloudContactCenter": "云联络中心",
"ccImSdk.NoMoreHistoricalMessages": "无更多历史消息",
"ccImSdk.useQuickReplies.EndSession": "结束会话",
"ccImSdk.useQuickReplies.SendSatisfaction": "发送满意度",
"ccImSdk.useRecorderVoice.TheSpeakingTimeIsToo": "说话时间太短,发送失败",
"ccImSdk.useRecorderVoice.StartRecording": "开始录音",
"ccImSdk.useRecorderVoice.Preparing": "正在准备中",
"ccImSdk.useRecorderVoice.ReleaseSendingSlideUpAnd": "松开发送,上滑取消",
"ccImSdk.useRecorderVoice.RecordingFailed": "录音失败",
"ccImSdk.useRecorderVoice.StopRecording": "停止录音",
"ccImSdk.useRecorderVoice.CancelRecording": "取消录音",
"ccImSdk.conversation.TheGroupOwnerWithdrewThe": "群主撤回了消息",
"ccImSdk.conversation.MessageWithdrawn": "消息已撤回",
"ccImSdk.conversation.Voice": "[语音]",
"ccImSdk.conversation.File": "[文件]",
"ccImSdk.conversation.Audio": "[音频]",
"ccImSdk.conversation.Video": "[视频]",
"ccImSdk.conversation.Picture": "[图片]",
"ccImSdk.NotConnected": "未连接",
"ccImSdk.Connecting": "连接中",
"ccImSdk.Connected": "已连接",
"ccImSdk.LoggingIn": "登录中",
"ccImSdk.LoggedIn": "已登录",
"ccImSdk.ConnectionFailed": "连接失败",
"ccImSdk.YouAreAlreadyLoggedIn": "已处于登录状态,请勿重复登录",
"ccImSdk.reConnect.SessionExpiration": "会话过期",
"ccImSdk.reConnect.TheCurrentSessionHasExpired": "当前会话已过期,如需继续会话,请点击刷新页面",
"ccImSdk.reConnect.NetworkException": "网络异常",
"ccImSdk.reConnect.TheImConnectionFailsDue": "网络异常导致IM连接失败,请刷新页面后重新上线",
"ccImSdk.reConnect.NetworkExceptionCausesConnectionFailure": "网络异常导致连接失败,请刷新页面",
"ccImSdk.reConnect.RefreshThePage": "刷新页面",
"ccImSdk.reConnect.Close": "关闭",
"ccImSdk.parser.File": "[文件]",
"ccImSdk.parser.Audio": "[音频]",
"ccImSdk.parser.Video": "[视频]",
"ccImSdk.parser.Picture": "[图片]",
"ccImSdk.parser.http.httpMessageParser.EndOfSession": "会话结束",
"ccImSdk.parser.AudioFilename": "[音频]{fileName}",
"ccImSdk.parser.VideoFilename": "[视频]{fileName}",
"ccImSdk.parser.Voice": "[语音]",
"ccImSdk.parser.FileFilename": "[文件]{fileName}",
"ccImSdk.parser.SystemMessages": "系统消息",
"ccImSdk.parser.FailedToSendResendThe": "发送失败,重发该消息?",
"ccImSdk.parser.Resend": "重发",
"ccImSdk.parser.TheCurrentSessionHasEnded": "当前会话已结束,无法重发",
"ccImSdk.parser.EndOfSession": "会话结束",
"ccImSdk.parser.MMonthDDayHh": "M月D日 HH:mm",
"ccImSdk.send.FiletypeIsATypeThat": "{fileType} 是不支持上传的类型",
"ccImSdk.send.ImageUploadIsNotSupported": "不支持图片上传",
"ccImSdk.send.FileUploadIsNotSupported": "不支持文件上传",
"ccImSdk.send.TheSessionDoesNotExist": "会话不存在",
"ccImSdk.send.TheSessionHasEndedAnd": "会话已结束,不能发送消息",
"ccImSdk.send.UnableToSendVoiceMessages": "不能发送语音消息",
"ccImSdk.useClaimChat.TheSessionHasBeenClaimed": "会话已被认领,请重新选择",
"ccImSdk.useClaimChat.TheSessionHasBeenClaimed.1": "会话已经认领,请勿重复操作",
"ccImSdk.useClaimChat.ClaimFailed": "认领失败",
"ccImSdk.LaunchSurvey.YouHaveAlreadyInitiatedA": "您已经发起过满意度调查,请勿重复发起",
"ccImSdk.LoadingTranscoderTimedOut": "加载转码器超时",
"ccImSdk.Navbar.QueueDuration": "排队时长",
"ccImSdk.Navbar.ServiceDuration": "服务时长",
"ccImSdk.VisitorNameid": "访客-{nameId}",
"ccImSdk.parser.You": "你",
"ccImSdk.parser.TheOtherParty": "对方",
"ccImSdk.parser.WhonameWithdrewAMessage": "{whoName}撤回了一条消息",
"ccImSdk.parser.VideoVideofilename": "[视频]{videoFileName}",
"ccImSdk.conversation.You": "你",
"ccImSdk.conversation.WhonameWithdrewTheMessage": "{whoName}撤回了消息"
}
{xxx} 包裹的是变量,翻译时不需要对 {xxx} 中的文案做翻译。如 {fileName}
,fileName
就不需要翻译,也要保持 {fileName}
这种格式。
七、更新日志
1.4.0
Bug Fixes
对机器人消息过长做兼容,而不是显示发送失败
修复其他部分已知问题
- 本页导读 (1)
- 一、前端资源
- 二、使用
- 1. 设置基础配置参数以使用
- 2. 渲染界面
- 3. 登录
- 4. 订阅数据变化
- 5. 销毁IM服务
- 三、服务端准备
- 四、visitorCcImSdk实例方法
- setConfig
- getConfig
- subscribe
- login
- reConnect
- logout
- releaseChat
- sendMessage
- recallMessage
- getUnreadMessageIdList
- updateMessageToRead
- getMessageList
- getPrevMessageList
- getNextMessageList
- render
- unmount
- destroy
- on
- off
- 五、数据类型
- CCIMSDKConfig(配置参数)
- FeatureConfig(特性功能配置)
- NavbarProps(导航栏属性)
- SubscribeStoreModel(数据订阅模块)
- MessageModel(消息模块)
- TextMessageContent(文本消息内容)
- ImageMessageContent(图片消息内容)
- FileMessageContent(文件消息)
- VoiceMessageContent(语音消息)
- VideoMessageContent(视频消息)
- AudioMessageContent(音频消息)
- SatisfactionMessageContent(满意度消息)
- ConversationModel(会话模块)
- SendMessageModel(发送消息模块)
- SendMessageContent(发送消息内容)
- EventNames(监听事件名称)
- 六、国际化
- 七、更新日志
- 1.4.0