使用 API 自訂 Guide 聊天

您可以透過使用這些聊天相關的 API，自訂使用 Guide 實現的聊天的外觀和行為。

聊天行為 API 調用

本節中的調用允許您變更 Guide 聊天視窗的行為方式。

設定授權代碼

設定來自 OAuth 流程的授權代碼。Oauth 是一種驗證通訊協定。它用於使一個應用程式代表您與另一個應用程式互動，無需洩露您的密碼。其必須在聊天初始化前調用。

cxone('chat','setAuthorizationCode', 'authorization_code');

自訂初始自動聯絡訊息

當 Guide 中的聊天開始時，會建立一個新案例Closed 透過通道與客服專員的完整對話。例如，互動可以是語音通話、電郵、聊天或社交媒體對話。，並在傳送聊天工作階段的第一條訊息時將其新增到佇列中。聊天工作階段開始時，會代表訪客傳送隱藏的自動訊息。這可以減少訪客等待客服專員的時間。儘管初始訊息對聯絡人隱藏，但客服專員仍可以看到。

預設訊息是客戶點擊以開始對話的按鈕上的文字。您可以透過三種方式自訂初始自動訊息的文字：

  • 覆寫預設按鈕文字。

    cxone('chat','sendFirstMessageAutomatically', 'Hello');

  • 動態變更初始訊息。

    cxone('chat','setFirstAutomatedMessageContent', 'Hello, I have a question');

  • 變更翻譯頁面上的訊息文字。

使初始自動訊息對聯絡人可見

如果您希望訪客能夠看到初始自動訊息，請將此調用新增到指令碼中：

cxone('chat','hideFirstSentMessage', false);

延遲建立案例

Guide 建立一個新案例，並在傳送聊天工作階段的第一條訊息時將其新增到佇列中。聊天工作階段開始時，會代表訪客傳送隱藏的自動訊息。這可以減少訪客等待客服專員的時間。當訪客點擊聊天圖示開始對話時，聊天工作階段即已開始。儘管初始訊息對訪客隱藏，但客服專員仍可以看到。

您可以配置 Guide 在使用此調用建立案例之前等待訪客實際發出第一條訊息：

cxone('chat','sendFirstMessageAutomatically', false);

啟用遊戲模式

允許訪客在等待客服專員時玩貪吃蛇遊戲。

cxone('chat','allowGameMode');

自動滿足度調查

可以自動偵測並在彈出式視窗中顯示滿足度調查。此命令可以啟用或停用偵測和是否顯示。

cxone('chat','automatedSatisfactionSurveyModal', 'false');

聊天資訊 API 調用

這些調用允許您自訂聊天工作階段期間對訪客可用的資訊。

獲取客戶身份 ID

返回聊天中訪客的唯一識別碼。

cxone('chat','getCustomerIdentityId');

設定客戶 ID

設定聊天中訪客的唯一識別碼。

cxone('chat','setCustomerId', 'customer_id');

隱藏佇列計數器

佇列計數器能夠讓訪客知道，根據訪客在客服專員佇列中的位置，客服專員多久能與其通話。您可以在訪客被成功路由到客服專員後隱藏佇列計數器。這允許客服專員從其收件匣中刪除客戶卡而不被訪客注意到。

cxone('chat','hideQueueCounterAfterAssignment');

設定活動狀態

變更活動列中的訊息。例如，您可以使用它來傳輸您對聊天訊息Closed 非同步聊天，聯絡人隨時傳送訊息並等待回覆工作階段的回應時間。這可能會有所幫助，因為聊天訊息是一種異步的聊天形式，訪客可能必須等待接收客服專員的訊息。

cxone('chat','setStatusMessage', 'We typically reply within 3 hours.');

設定客服專員的圖像

動態變更聊天視窗中顯示的客服專員圖像。依預設，Guide 會使用客服專員設定檔中的圖像。當您在指令碼中包含此調用時，會使用代碼 Snippet 中以 URL 指定的圖像。將範例 URL 替換為您希望聊天使用的圖像的 URL。

cxone('chat','setAgentImage', 'http://classics.com/images/agents/elizabeth_bennet.png');

設定客戶名稱

客戶名稱是聊天前調查表中的一個欄位，訪客需要在與聊天訊息Closed 非同步聊天，聯絡人隨時傳送訊息並等待回覆通道中的客服專員聯絡前填寫。此 API 調用會動態填充此欄位。

cxone('chat','setCustomerName', 'Elizabeth');

設定日期格式

將日期格式設定為絕對日期格式 (01/01/2022) 或相對日期格式（今天，星期一）。

cxone('chat','setDateFormat', 'date_format');

設定地區

設定聊天視窗中的翻譯區域。

cxone('chat','setLocale', 'locale');

展示案例資訊

只適用於聊天訊息Closed 非同步聊天，聯絡人隨時傳送訊息並等待回覆通道。向訪客顯示案例資訊。

cxone('chat','showCaseInfo');

顯示/隱藏傳送轉錄按鈕

如果您將傳送轉錄按鈕設定為顯示，您必須配置聊天通道以允許訪客將聊天轉錄傳送給自己。為聊天訊息或即時聊天配置此選項。

cxone('chat','showSendTranscript');
cxone('chat','hideSendTranscript');

顯示/隱藏系統訊息

顯示或隱藏系統訊息，如客服專員指派歷程。

cxone('chat','showSystemMessages');
cxone('chat','hideSystemMessages');

使用條款

讓您可以在聊天視窗中向訪客提供使用條款文件。此功能會在視窗中新增一個按鈕。您可以自訂按鈕的標籤和樣式，以及訪客點擊後會執行的動作。點擊動作可將使用條款顯示為內部視窗或外部連結。

一個內部視窗：

cxone('chat','showTermsOfUse', 'Show terms of Use', 'modal' , 'Our terms of use are ...');

一個外部連結：

cxone('chat','showTermsOfUse', 'Show terms of Use', 'externalLink' , 'http://yourdomain.com/terms-of-use');

若要停用該功能：

cxone('chat','hideTermsOfUse');

自訂欄位、標籤和短語

建立和填充自訂欄位

您在此調用操作時可以使用的自訂欄位與您在 客戶卡片 中使用的欄位相同。如果您在打開聊天視窗前使用這些調用，聯絡前表單中的欄位將用您在 API 調用中包含的資料填充。

要定義一個 案例 自訂欄位的值：

cxone('chat','setCaseCustomField', 'ident_of_custom_field', 'value_of_custom_field');

要定義一個 客戶卡片 自訂欄位的值：

cxone('chat','setCustomerCustomField', 'ident_of_custom_field', 'value_of_custom_field');

自訂標籤和短語

您可以自訂 Guide 聊天使用的許多標籤和短語，以及定義自訂。如果您需要動態變更短語或螢幕標籤，請使用這些 API 調用。

若要變更單個訊息或標籤：

cxone('chat','setTranslation', 'key', 'your translation');

若要變更多個訊息或標籤：

cxone('chat','setTranslations', {key1: 'your custom label', key2: 'your custom message'});

大括號表示系統用實際資料替換的變數。例如，{caseNumber} 被替換為聯絡人聊天工作階段的案例編號。

Key Default label/Message
allAgentsForQueueAreBusy 我們專為此佇列安排的客服專員目前正忙。隊列中在您前面有 {queue, plural, one {is} other {are}} <strong>{queue, number}</strong> {queue, plural, one {person} other {people}}。

beginButton

開始聊天！
cancel 取消
caseNumber 案例編號 #{caseNumber}
change 變更
chattedWith 您剛剛進行了聊天
commonErrorText 出現意外錯誤。請稍後再試。
done 完成
dragAndDropDropzone 將檔案拖放到此處以傳送
dragAndDropDropzoneRejected 無法上載檔案 :(
EmailLabel 電郵
endChat 結束聊天
endChatTitle 是否確定要結束此次對話？
endGame 結束遊戲
ending 正在結束聊天...
fileSendingFailed 檔案傳送失敗
getTranscriptDescription 將此對話的轉錄送到以下電郵地址：
getTranscriptLink 獲取聊天轉錄
invalidToken 權標無效
ipAddressBlocked IP 位址被封鎖
loading 載入中…
loadPreviousButton 載入以前的對話
messageLabel 訊息
networkErrorText 發生一個網路錯誤。請再試一次。
newCase 新案例
noAgentOnlineForQueue 目前沒有客服專員可處理您的佇列。
offline 離線
offlineFormDesc 我們暫時不可用
offlineFormSuccessMsgHead 謝謝！
offlineFormSuccessMsgSub 您的電郵傳送成功。我們會盡快回覆您。
online 線上
onlineFormText 要開始聊天，請告訴我們您的姓名。我們的一位客服專員將立即開始為您提供幫助。
pleaseSelect 請選擇...
poweredBy 技術支援
preparingSession 正在準備工作階段...
replyBoxPlaceholder 在此輸入，然後按 <enter> 傳送
retry 重試
sendFileTextSize 請上載小於 {filesize} 的檔案
sendFileTextSupportedFormat 支援的格式。
sendFileTextSupportedFormatDesc 圖像、影片、{fileFormats}
sendMessageButton 傳送訊息
sendNewEmail 傳送新電郵
sendTranscript 傳送轉錄
snakeWaiting 您在佇列中排第 {queue} 個。
startChatInPopup 諮詢我們！
startNewChat 開始新的聊天
statusReconnecting 正在嘗試連接…
surveySuccesfullySent 感謝您的反饋意見！
systemChattingWith 您正在與 {name} 聊天
topic 題目
transciptSentFailed 傳送失敗。
transciptSuccesfullySent 轉錄傳送成功！
tryAgainButton 再試一次
unexpectedError 發生意外錯誤。
validationInvalidEmail 電郵地址無效
validationMandatory 此乃必填欄位
validationShorterName 請使用較短的名稱
validationShortMessage 您的訊息太短
waiting 等待中...
waitingDescription 我們的一位客服專員將很快與您對話。
waitingFooter 點擊 <spacebar> 可縮短等待時間。
waitingForAgent 正在等待客服專員...
waitingInQueue 等待客服專員。您在佇列中排第 {queue} 個。
weAreOffline 我們目前已離線。
weAreOnline 我們在線
yourNameLabel 您的姓名

聊天視窗外觀 API 調用

您可以修改 Guide 使用的聊天視窗的外觀。

隱藏指派的客服專員

cxone('chat','hideAssignedAgent');

隱藏標頭

cxone('chat','hideHeader');

顯示客戶頭像

cxone('chat','showCustomerAvatar');

顯示傳送按鈕

cxone('chat','showSendButton');

為回覆框設定字元限制

cxone('chat','setReplyBoxLimit', '280');

帶有資料選擇器的自訂 CSS

您可以在 API 調用中使用資料選擇器來透過自訂的 CSS 自訂聊天視窗的外觀。資料選擇器允許您指定要套用自訂 CSS 的聊天視窗部分。使用 data-selector 屬性定義資料選擇器。將其設定為您要修改的聊天視窗元件的名稱。

要使用資料選擇器新增自訂 CSS，請使用以下 API 調用作為參考：

cxone('chat','setCustomCss', '[data-selector="CUSTOMER_MESSAGE_BUBBLE"] {color: white !important; background: black !important};');

  • ACTIVITY_BAR

  • AGENT_MESSAGE

  • AGENT_MESSAGE_BUBBLE

  • AVATAR

  • CONTENT

  • CUSTOMER_MESSAGE

  • CUSTOMER_MESSAGE_BUBBLE

  • DELIMITER

  • DROPDOWN_MENU

  • HEADER

  • INPUT

  • IS_TYPING

  • MESSENGER

  • POPUP

  • PRECONTACT_SURVEY

  • PRECONTACT_SURVEY_DESCRIPTION

  • PRIMARY_BUTTON

  • REPLY_BOX

  • SECONDARY_BUTTON

  • SEND_BUTTON

  • TEXTAREA

  • TEXT_BUTTON

  • WIDGET

  • WINDOW

僅使用 data-selector 屬性套用自訂 CSS 元件。不要將其套用於如下列範例中的類別選擇器或 JavaScript 程式碼的其他部分：

.Widget__Widget___1qQCf { background: red; }

與第三方應用程式整合

本節中的叫用操作允許您在發生某些聊天事件時接收推送通知。

識別聊天視窗中的作用中執行緒

cxone('chat','getOngoingThreads');

識別聊天視窗中正在進行的聯絡

cxone('chat','getOngoingContact');

接收特定聊天事件的推送通知

使用以下任何輸入代替下述範例中的「事件」。

  • CaseToRoutingQueueAssignmentChanged

  • PageViewCreated

  • MessageCreated

  • MessageDeliveredToUser

  • MessageDeliveredToEndUser

  • MessageSeenByUser

  • MessageSeenByEndUser

  • MessageReadChanged

  • MessageAddedIntoCase

  • CaseInboxAssigneeChanged

  • CaseCreated

  • CaseStatusChanged

  • SenderTypingStarted

  • SenderTypingEnded

  • MessageNoteCreated

  • ContactRecipientsChanged

要接收一個聊天事件的通知：

cxone('chat','onPushUpdate', 'event', callback);

要接收多個聊天事件的通知：

cxone('chat','onPushUpdate', ['event', 'event', 'event'], callback);

要接收所有聊天事件的通知：

cxone('chat','onAnyPushUpdate', callback);