Cloud Contact Center Frontend IMSDK Visitor Client Documentation

Frontend resources

<!-- IM SDK style file -->
<link rel="stylesheet" type="text/css" href="//g.alicdn.com/code/npm/@ali/cc-im-sdk/{version-im-sdk}/index.css">

<!-- IM SDK JS file -->
<script src="//g.alicdn.com/code/npm/@ali/cc-im-sdk/{version-im-sdk}/index.js"></script>

Usage

After the JS file loads, the window object contains the ccImSdk parameter. window.ccImSdk.visitorCcImSdk is the visitor SDK instance.

Set basic configuration parameters

window.ccImSdk.visitorCcImSdk.setConfig({
  visitorId: 'xxxxxxxx', // Required and unique. Used to distinguish different visitors.
  ajaxToken: 'xxxx', // Required. The token parameter in the channel connection.
  ajaxPath: '/v-api', // The pathname of the API request.
});

Render the interface

This step renders the IM container interface for chatting. You can render the interface after logon or at a different time. The rendering timing is customizable.

window.ccImSdk.visitorCcImSdk.render(document.getElementById('im-container'))
// The render method passes a DOM element as the container for IM rendering.

Log on

Logs on to the IM chat service.

window.ccImSdk.visitorCcImSdk.login();

Subscribe to data changes

window.ccImSdk.visitorCcImSdk.subscribe((data) => {
    console.log('SUBSCRIBE: ',  data); // Data such as connection status, message changes, and session changes are passed here.
  });

Destroy the IM service

The destroy operation includes logging out and unmounting the interface.

window.ccImSdk.visitorCcImSdk.destroy();

Server-side preparation

The frontend API requires your server to perform proxy forwarding to resolve cross-domain issues. You must forward requests to the Cloud Contact Center server-side address.

The API address is: https://ccc-v2.aliyun.com/v-api. The following example uses Nginx as a proxy. Assume that your domain name is ccc.example.com:

    server {
       listen 443 ssl; # Use SSL
       server_name ccc.example.com; # Replace with your domain name
    
       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 instance methods

Use window.ccImSdk.visitorCcImSdk to call methods.

setConfig

Sets configuration parameters.

• Type: (config: <a baseurl="t2853054_v1_0_0.xdita" data-node="5498293" data-root="16411" data-tag="xref" href="#31311018a5k5o" id="16a81a9fa2ral">CCIMSDKConfig</a>) => void

getConfig

Retrieves the current configuration parameters.

• Type: () => <a baseurl="t2853054_v1_0_0.xdita" data-node="5498293" data-root="16411" data-tag="xref" href="#31311018a5k5o" id="1885ae47c2tcd">CCIMSDKConfig</a>

subscribe

Subscribes to data changes, such as connection status, message changes, and session changes. It returns a method to unsubscribe.

• Type: (cb: (data: <a baseurl="t2853054_v1_3_0.xdita" data-node="5498293" data-root="16411" data-tag="xref" href="#4ecda6ecf1g39" id="e46a0c1d33bxl">SubscribeStoreModel</a>) => void) => (() => void);

login

Logs on to the IM service.

• Type: () => Promise<void>

reConnect

Reconnects to the service. You can call this method when the connection is lost. However, you do not typically need to call this method because the SDK has an automatic reconnection feature.

• Type: () => Promise<string>

logout

Logs out and closes the connection.

• Type: () => Promise<void>

releaseChat

Ends the current session.

• Type: () => Promise<any>

sendMessage

Sends a message. A session must be active for the message to be sent successfully.

• Type: (message: <a baseurl="t2853054_v1_0_0.xdita" data-node="5498293" data-root="16411" data-tag="xref" href="#e23518af0be1o" id="44918a9f8bl44">SendMessageModel</a>) => Promise<void>

recallMessage

Revokes a message.

• Type: (appCid: string, messageId: string) => Promise<void>

getUnreadMessageIdList

Retrieves the list of unread message IDs.

• Type: () => string[]

updateMessageToRead

Reads messages in batches and updates their status to 'Read'. You can use getUnreadMessageIdList to retrieve the list of all unread message IDs in the current session. You can also check the readStatus field of a message to determine if it is read, and then pass the ID to the msgIds parameter.

• Type: (appCidstring, msgIds: string[]) => Promise<void>

getMessageList

Retrieves the message list of the current session.

• Type: () => Promise<MessageModel[]>

getPrevMessageList

Pulls the list of historical messages. cursor is the message cursor, and count is the number of messages to retrieve. You can obtain information about whether historical messages exist and the cursor value from subscribe.

• Type: (cursor: string, count: number) => Promise<number>

getNextMessageList

Pulls the list of latest messages. cursor is the message cursor, and count is the number of messages to retrieve. You can obtain information about whether new messages exist and the cursor value from subscribe.

• Type: (cursor: string, count: number) => Promise<number>

render

Renders the IM interface. The passed container must be a loaded DOM element.

• Type: (container: HTMLElement) => void

unmount

Unmounts the IM interface. The logon status is maintained. This is consistent with the React unmount method. You can call the render method again to display the interface.

destroy

Destroys the IM service, which includes unmounting the interface and logging out.

on

Listens for events.

• Type: (eventName: <a baseurl="t2853054_v1_0_0.xdita" data-node="5498293" data-root="16411" data-tag="xref" href="#684e426c07o6e" id="0114daee6aqcd">EventNames</a>, fn: (...args: any[]) => void) => void

off

Cancels the event listener.

• Type: (eventName: <a baseurl="t2853054_v1_0_0.xdita" data-node="5498293" data-root="16411" data-tag="xref" href="#684e426c07o6e" id="7462433943qub">EventNames</a>, fn?: (...args: any[]) => void) => void

Data types

CCIMSDKConfig (configuration parameters)

interface User {
  /** Display name */
  nickname?: string;
  /** Profile picture URL */
  avatarUrl?: string;
}

{
  apiAxiosFunc: (apiName, params) => {
    console.log(apiName, params);
    const promise = axios({
        method: 'post',
        url:`/alibaba-cloud/ccc/api?action=${apiName}`,
        headers: {
          'Content-Type': 'application/x-www-form-urlencoded',
        },
        data: Qs.stringify({ request: JSON.stringify(params)}),
      });
    return promise;
  }
};

interface ChatContainerConfig {
  /** Hide the editor area */
  hiddenComposer?: boolean;
};

{
  "zh-CN": {
    "xxxxx": "xxxxxx"
  },
 "en-US": {
    "xxxxx": "xxxxxx"
  },
 "Custom Language": {
    "xxxx": "xxxxxx"
 }
}

FeatureConfig (feature configuration)

interface PcBackground {
  /** Image link */
  image: string
}

NavbarProps (navigation bar properties)

SubscribeStoreModel (data subscription module)

MessageModel (message module)

interface User {
  /** Profile picture */
  avatar?: string;
  /** Nickname */
  name?: string;
  /** Link to which the user is redirected when they click the profile picture */
  url?: string;
  [k: string]: any;
}

TextMessageContent (text message content)

interface ReferenceMessageContent {
  nickname: string;
  subContentType: "text" | "image" | "richtext" | "audio" | "voice" | "video" | "file" | "system" | "survey";
  content: string | ImageMessageContent;
}

ImageMessageContent (image message content)

FileMessageContent (file message)

interface FileInfo {
  name: string;
  size: string;
}

VoiceMessageContent (voice message)

VideoMessageContent (video message)

AudioMessageContent (audio message)

SatisfactionMessageContent (satisfaction message)

interface RatingScaleOption {
  number: number;
  description:  string;
}

QueueMessage (queue message)

ConversationModel (session module)

SendMessageModel (send message module)

SendMessageContent (send message content)

EventNames (listener event names)

Internationalization

The following list contains all the internationalization text strings used in the project. Only the Chinese strings are listed. To change a description, update the text for the corresponding key and use the locales field to replace it. The UI rendering of the IMSDK depends on the ChatSDK. For more information about the internationalization of some components, see the ChatSDK internationalization section.

{
  "ccImSdk.NetworkRequestException": "Network request abnormal",
  "ccImSdk.DisconnectPleaseCheckTheNetwork": "Connection lost. Check your network and refresh the page to retry.",
  "ccImSdk.NoSessionIsCurrentlyActivated": "No session is currently active",
  "ccImSdk.TheSessionHasEndedAnd": "The session has ended. You cannot release the session.",
  "ccImSdk.TheCurrentSessionHasEnded": "The current session has ended. You cannot release the session.",
  "ccImSdk.TheCurrentSessionDoesNot": "The current session does not exist",
  "ccImSdk.TheSessionHasEndedAnd.1": "The session has ended. You cannot revoke the message.",
  "ccImSdk.BrandLogo.Pass": "Provided by",
  "ccImSdk.BrandLogo.Support": "Support",
  "ccImSdk.Messages.Download": "Download",
  "ccImSdk.Messages.ReEdit": "Edit again",
  "ccImSdk.Messages.Copy": "Copy",
  "ccImSdk.Messages.Withdraw": "Revoke",
  "ccImSdk.Messages.Reference": "Reference",
  "ccImSdk.Messages.Read": "Read",
  "ccImSdk.Messages.Unread": "Unread",
  "ccImSdk.SatisfactionMessage.AreYouSureYouWant": "A satisfaction survey has not been submitted. Are you sure you want to leave?",
  "ccImSdk.Claim": "Claim",
  "ccImSdk.CurrentlyItIsInDraft": "This is a draft. Are you sure you want to send it?",
  "ccImSdk.Ok": "OK",
  "ccImSdk.Cancel": "Cancel",
  "ccImSdk.RichtextEditor.FileUpload": "File Upload",
  "ccImSdk.RichtextEditor.QuickReply.QuickReply": "Quick Reply",
  "ccImSdk.RichtextEditor.QuickReply.Evoke": "/ to evoke",
  "ccImSdk.RichtextEditor.QuickReply.Switch": "↑ ↓ to switch",
  "ccImSdk.RichtextEditor.QuickReply.WomenSClothing": "└┘",
  "ccImSdk.RichtextEditor.QuickReply.Selected": "Selected",
  "ccImSdk.RichtextEditor.QuickReply.NoRelevantQuickReplyIs": "No relevant quick replies",
  "ccImSdk.RichtextEditor.PleaseEnterAMessage": "Please enter a message",
  "ccImSdk.RichtextEditor.Send": "Send",
  "ccImSdk.RichtextEditor.AiErrorCorrection": "AI Error Correction",
  "ccImSdk.RichtextEditor.AiExpansion": "AI Expansion",
  "ccImSdk.RichtextEditor.SpeechOptimization": "Speech Optimization",
  "ccImSdk.RichtextEditor.ReplaceDialogBoxContent": "Replace dialog box content",
  "ccImSdk.RichtextEditor.TheContentIsBeingGenerated": "Content is being generated by AI. Please wait...",
  "ccImSdk.RichtextEditor.ExitDraft": "Exit Draft",
  "ccImSdk.RichtextEditor.Draft": "Draft",
  "ccImSdk.RichtextEditor.SecondConfirmationIsRequiredFor": "A second confirmation is required to send messages in draft mode",
  "ccImSdk.ProblemCard.Faq": "FAQ:",
  "ccImSdk.ProblemCard.NoDataAvailable": "No data available",
  "ccImSdk.ToolsCard.CommonTools": "Developer Tools:",
  "ccImSdk.showModel.Confirm": "Confirm",
  "ccImSdk.showModel.Cancel": "Cancel",
  "ccImSdk.NoConsultation": "No consultation",
  "ccImSdk.ChatApp.Expression": "Expression",
  "ccImSdk.ChatApp.PhotoAlbum": "Album",
  "ccImSdk.ChatApp.File": "File",
  "ccImSdk.ChatApp.ClickLoadMore": "Click to load more",
  "ccImSdk.CloudContactCenter": "Cloud Contact Center",
  "ccImSdk.NoMoreHistoricalMessages": "No more historical messages",
  "ccImSdk.useQuickReplies.EndSession": "End Session",
  "ccImSdk.useQuickReplies.SendSatisfaction": "Send Satisfaction",
  "ccImSdk.useRecorderVoice.TheSpeakingTimeIsToo": "Speaking time is too short. Sending failed.",
  "ccImSdk.useRecorderVoice.StartRecording": "Start Recording",
  "ccImSdk.useRecorderVoice.Preparing": "Preparing",
  "ccImSdk.useRecorderVoice.ReleaseSendingSlideUpAnd": "Release to send, slide up to cancel",
  "ccImSdk.useRecorderVoice.RecordingFailed": "Recording failed",
  "ccImSdk.useRecorderVoice.StopRecording": "Stop Recording",
  "ccImSdk.useRecorderVoice.CancelRecording": "Cancel Recording",
  "ccImSdk.conversation.TheGroupOwnerWithdrewThe": "The group owner revoked the message",
  "ccImSdk.conversation.MessageWithdrawn": "Message revoked",
  "ccImSdk.conversation.Voice": "[Voice]",
  "ccImSdk.conversation.File": "[File]",
  "ccImSdk.conversation.Audio": "[Audio]",
  "ccImSdk.conversation.Video": "[Video]",
  "ccImSdk.conversation.Picture": "[Picture]",
  "ccImSdk.NotConnected": "Not Connected",
  "ccImSdk.Connecting": "Connecting",
  "ccImSdk.Connected": "Connected",
  "ccImSdk.LoggingIn": "Logging In",
  "ccImSdk.LoggedIn": "Logged In",
  "ccImSdk.ConnectionFailed": "Connection Failed",
  "ccImSdk.YouAreAlreadyLoggedIn": "You are already logged in. Do not log in again.",
  "ccImSdk.reConnect.SessionExpiration": "Session Expiration",
  "ccImSdk.reConnect.TheCurrentSessionHasExpired": "The current session has expired. To continue the session, refresh the page.",
  "ccImSdk.reConnect.NetworkException": "Network Exception",
  "ccImSdk.reConnect.TheImConnectionFailsDue": "The IM connection failed due to a network exception. Refresh the page and go online again.",
  "ccImSdk.reConnect.NetworkExceptionCausesConnectionFailure": "The connection failed due to a network exception. Refresh the page.",
  "ccImSdk.reConnect.RefreshThePage": "Refresh Page",
  "ccImSdk.reConnect.Close": "Close",
  "ccImSdk.parser.File": "[File]",
  "ccImSdk.parser.Audio": "[Audio]",
  "ccImSdk.parser.Video": "[Video]",
  "ccImSdk.parser.Picture": "[Picture]",
  "ccImSdk.parser.http.httpMessageParser.EndOfSession": "End of Session",
  "ccImSdk.parser.AudioFilename": "[Audio]{fileName}",
  "ccImSdk.parser.VideoFilename": "[Video]{fileName}",
  "ccImSdk.parser.Voice": "[Voice]",
  "ccImSdk.parser.FileFilename": "[File]{fileName}",
  "ccImSdk.parser.SystemMessages": "System Messages",
  "ccImSdk.parser.FailedToSendResendThe": "Failed to send. Resend the message?",
  "ccImSdk.parser.Resend": "Resend",
  "ccImSdk.parser.TheCurrentSessionHasEnded": "The current session has ended. Cannot resend.",
  "ccImSdk.parser.EndOfSession": "End of Session",
  "ccImSdk.parser.MMonthDDayHh": "MMM D, HH:mm",
  "ccImSdk.send.FiletypeIsATypeThat": "{fileType} is an unsupported upload type",
  "ccImSdk.send.ImageUploadIsNotSupported": "Image upload is not supported",
  "ccImSdk.send.FileUploadIsNotSupported": "File upload is not supported",
  "ccImSdk.send.TheSessionDoesNotExist": "The session does not exist",
  "ccImSdk.send.TheSessionHasEndedAnd": "The session has ended. You cannot send messages.",
  "ccImSdk.send.UnableToSendVoiceMessages": "Cannot send voice messages",
  "ccImSdk.useClaimChat.TheSessionHasBeenClaimed": "The session has been claimed. Please select again.",
  "ccImSdk.useClaimChat.TheSessionHasBeenClaimed.1": "The session has been claimed. Do not repeat the operation.",
  "ccImSdk.useClaimChat.ClaimFailed": "Claim failed",
  "ccImSdk.LaunchSurvey.YouHaveAlreadyInitiatedA": "You have already initiated a satisfaction survey. Do not initiate it again.",
  "ccImSdk.LoadingTranscoderTimedOut": "Loading transcoder timed out",
  "ccImSdk.Navbar.QueueDuration": "Queue Duration",
  "ccImSdk.Navbar.ServiceDuration": "Service Duration",
  "ccImSdk.VisitorNameid": "Visitor-{nameId}",
  "ccImSdk.parser.You": "You",
  "ccImSdk.parser.TheOtherParty": "The other party",
  "ccImSdk.parser.WhonameWithdrewAMessage": "{whoName} revoked a message",
  "ccImSdk.parser.VideoVideofilename": "[Video]{videoFileName}",
  "ccImSdk.conversation.You": "You",
  "ccImSdk.conversation.WhonameWithdrewTheMessage": "{whoName} revoked the message",
  "ccImSdk.ExitQueuing": "Exit Queue"
}

Update Log

1.6.0

Features

• Optimized the PC editor features.

• Optimized the progress display for sending multiple images.

• Optimized the display logic for the message context menu.

1.5.3

Bug Fixes

• Optimized the display of messages in the queue.

1.5.2

Features

• [Breaking Change] Optimized the display of queue messages. A new message format was added, which requires a version upgrade.

• Added the `queueMessage` message code format.

1.4.0

Bug Fixes

• Added compatibility for long bot messages to prevent sending failures.

• Fixed other known issues.