Service Desk Chat JS Integrations-Guide
Service Desk Chat (sdc/js) ist eine JavaScript-Bibliothek, welche die Chat-Funktionalität auf Ihrer Website und die Kommunikation zwischen Website-Nutzern und Agenten über einen dedizierten Relay-Server ermöglicht.
Funktionen
- init(initRequestOpts)
-
- Beschreibung: Initialisiert die SDC-Bibliothek mit Hilfe der Relay Server URL, Farbpaletten und der übergebenen Sprache.
- Parameter:
- initRequestOpts (InitChatRequest): Optionen zum Initialisieren der SDC-Bibliothek.
- Rückgabewert: (Promise<boolean>) Ein Promise, welches zu „true“ aufgelöst wird, wenn die Initialisierung erfolgreich ist, und zu „false“, wenn ein Fehler auftritt.
- openChatWindow(options)
-
- Beschreibung: Öffnet das Chat Fenster anhand der übergebenen Optionen. Bietet auch die Möglichkeit das Chat Fenster nach Minimierung wieder zu maximieren.
- Parameter:
- options (object): Beinhaltet die Informationen des Nutzers und ggf. die Ticket Nummer (optional).
- Rückgabewert: Promise<void>
- closeChatWindow()
-
- Beschreibung: Schließt das Chat Fenster und trennt die Verbindung zum Relay.
- Rückgabewert: Nichts
- logout()
-
- Beschreibung: Löscht alle gespeicherten Sitzungsdaten innerhalb der SDC-Bibliothek. Schließt das Chat Fenster und trennt die Verbindung zum Relay.
- Rückgabewert: Nichts
Events
Die nachfolgenden Events werden ohne weitere Daten ausgelöst.
- “ltg.sdc.OpenedChatWindow”: Dieses Event wird versendet, wenn das Chat Fenster geöffnet wurde und sichtbar ist.
- “ltg.sdc.MinimizeWindow”: Mit diesem Event wird verdeutlicht, dass das Fenster minimiert wurde. Bei Minimierung des Fensters wird die Verbindung zum Relay nicht unterbrochen.
- “ltg.sdc.CloseWindow”: Bei Schließung des Fensters wird dieses Event ausgelöst. Die Verbindung zum Relay wird bei Schließung des Fensters getrennt.
- “ltg.sdc.NewMessage”: Dieses Event wird durch einkommende Nachrichten ausgelöst und kann ggf. abgefangen werden.
Alle Events könnten wie folgt abgefangen werden.
window.addEventListener("{eventName}", () => {
// your logic
});
InitChatRequest Objekt
Das initRequestOpts Objekt wird an die Funktion init(initRequestOpts) übergeben und initialisiert die SDC-Bibliothek.
- address (string): URL des Relay Servers.
- transportType (number | signalR.HttpTransportType): HTTP Transport Typ für die Hubverbindung. Nummer 1 ist für den Transport Typ WebSockets. Nummer 4 ist für LongPolling.
- headers (Headers): Optionale HTTP Header für die Hubverbindung. Die Header werden nur bei LongPolling erkannt und können bei WebSockets nicht genutzt werden.
- customPalettes (object): Farbpaletten zur Anpassung der Benutzeroberfläche. Sie können die Farbpaletten von Angular Material (Color – Style – Material Design) verwenden oder Ihre eigenen benutzerdefinierten Farbpaletten hinzufügen, wie im folgenden Beispiel.
- language (string): Sprache des Chats. (z.B. „en-GB“)
- keepAliveIntervalInMilliseconds (number): Dies ist das Zeitintervall, in dem der Client eine „Keep-Alive“-Nachricht an den Server sendet, um die Verbindung aktiv zu halten, auch wenn keine Daten ausgetauscht werden.
- serverTimeoutInMilliseconds (number): Dieses Intervall gibt an, wie lange der Client wartet, bevor er eine inaktive Server-Verbindung als abgebrochen betrachtet und sie schließt.
Beispiel:
var initRequest = {
address: "http://localhost:5001",
transportType: 4,
headers: headers,
customPalettes: palettes,
keepAliveIntervalInMilliseconds: 2000,
serverTimeoutInMilliseconds: 10000
}
const initialized = await ltgsdc.init(initRequest);
Headers Objekt
Das headers Objekt ist ein Schlüssel-Wert-Paar.
Zum Beispiel:
{
"Custom-Header": "test_header"
}
Options Objekt
Das options Objekt wird an die Funktion openChatWindow(options) übergeben und enthält verschiedene Eigenschaften, um Informationen zum Nutzer oder die Ticket Nummer an das Chat Fenster weiterzuleiten.
- firstName (string): Vorname des Nutzers.
- lastName (string): Nachname des Nutzers.
- emailAddress (string): Email Adresse des Nutzers.
- language (string): Spracheinstellung für den Chat (z.B. „en-GB“) (optional).
- ticketNumber (string): Ticket Nummer als Referenz zum Ticket im Matrix42 DWP System (optional).
Beispiel:
var options = {
firstName: "TEST",
lastName: "TEST",
emailAddress: "TEST@TEST.test",
language: "en-GB",
ticketNumber: "INC00058"
};
Chat Button Implementation
Der im Guide dargestellte Chat-Button (#ltg-sdc-create-chat) gehört nicht zum Produkt der SDC-Bibliothek selbst. Er dient als Beispiel-HTML-Element zu Demonstrationszwecken. Sie müssen ihren eigenen Chat-Button oder ähnliches in ihre HTML-Struktur integrieren, um die Funktion ‚openChatWindow()‘ auszulösen.
Für eine effektive Integration sollten Sie ihren Chat-Button gemäß dem Design ihrer Website und den Benutzererfahrungspräferenzen anpassen und integrieren. Die bereitgestellte HTML-Struktur für den Chat-Button (#ltg-sdc-create-chat) sollte angepasst und mit der Funktion ‚openChatWindow(options)‘ verknüpft werden, um die Chat-Funktionalität zu initiieren, wenn der Nutzer daraufklickt.
Einfaches Beispiel
<html>
<head>
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<script src="{relayServerUrl}/sdc/js"></script>
</head>
<body>
<p>
TEST External Relay Website
</p>
<button id="ltg-sdc-create-chat">Create Chat</button>
<button id="ltg-sdc-close-chat">Close Chat</button>
<button id="ltg-sdc-logout">Logout</button>
<script>
document.addEventListener("DOMContentLoaded", async function () {
var options = {
firstName: "TEST",
lastName: "TEST",
emailAddress: "TEST@TEST.test",
// language: "en-GB",
// ticketNumber: "INC00058"
};
var palettes = { isDark: false, primaryPalette: 'purple', accentPalette: 'indigo', warnPalette: 'red', backgroundPalette: 'grey' }
var initRequest = {
address: "http://localhost:5001",
transportType: 1,
customPalettes: palettes
}
const initialized = await ltgsdc.init(initRequest);
console.log("initialized", initialized);
document.getElementById("ltg-sdc-create-chat").addEventListener("click", () => {
ltgsdc.openChatWindow(options);
});
document.getElementById("ltg-sdc-close-chat").addEventListener("click", () => {
ltgsdc.closeChatWindow();
});
document.getElementById("ltg-sdc-logout").addEventListener("click", () => {
ltgsdc.logout();
});
});
</script>
</body>
</html>
Einfaches Beispiel mit benutzerdefinierten Farbpaletten
<html>
<head>
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<script src="{relayServerUrl}/sdc/js"></script>
<style>
/* simple example with custom palettes and not many CSS changes */
.ltg-sdc-root .ltg-sdc-chat-message-system .ltg-sdc-chat-message {
background-color: #717171 !important;
color: #fff !important;
}
.ltg-sdc-root .ltg-sdc-chat-message-wrapper-them .ltg-sdc-chat-message {
background-color: #1952AD !important;
color: #fff !important;
}
</style>
</head>
<body>
<p>
TEST External Relay Website
</p>
<button id="ltg-sdc-create-chat">Create Chat</button>
<button id="ltg-sdc-close-chat">Close Chat</button>
<button id="ltg-sdc-logout">Logout</button>
<script>
document.addEventListener("DOMContentLoaded", async function () {
var options = {
firstName: "TEST",
lastName: "TEST",
emailAddress: "TEST@TEST.test",
// language: "en-GB",
// ticketNumber: "INC00058"
};
// simple example with custom palettes
var primaryPalette = {
'50': 'e3eaf5',
'100': 'bacbe6',
'200': '8ca9d6',
'300': '5e86c6',
'400': '3c6cb9',
'500': '1952ad',
'600': '164ba6',
'700': '12419c',
'800': '0e3893',
'900': '082883',
'A100': 'b2c2ff',
'A200': '7f99ff',
'A400': '4c71ff',
'A700': '325dff',
'contrastDefaultColor': 'light',
'contrastDarkColors': [
'50',
'100',
'200',
'300',
'A100',
'A200'
],
'contrastLightColors': [
'400',
'500',
'600',
'700',
'800',
'900',
'A400',
'A700'
]
};
var accentPalette = {
'50': '174b9e',
'100': '174b9e',
'200': '174b9e',
'300': '174b9e',
'400': '174b9e',
'500': '174b9e',
'600': '174b9e',
'700': '174b9e',
'800': '174b9e',
'900': '174b9e',
'A100': '174b9e',
'A200': '174b9e',
'A400': '174b9e',
'A700': '174b9e',
'contrastDefaultColor': 'light',
'contrastDarkColors': [
'50',
'100',
'200',
'300',
'400',
'500',
'600',
'700',
'800',
'900',
'A100',
'A200',
'A400',
'A700'
],
'contrastLightColors': []
};
var backgroundPalette = {
'50': 'fdfdfd',
'100': 'f9f9f9',
'200': 'f5f5f5',
'300': 'f1f1f1',
'400': 'eeeeee',
'500': 'ebebeb',
'600': 'e9e9e9',
'700': 'e5e5e5',
'800': 'e2e2e2',
'900': 'dddddd',
'A100': 'ffffff',
'A200': 'ffffff',
'A400': 'ffffff',
'A700': 'ffffff',
'contrastDefaultColor': 'light',
'contrastDarkColors': [
'50',
'100',
'200',
'300',
'400',
'500',
'600',
'700',
'800',
'900',
'A100',
'A200',
'A400',
'A700'
],
'contrastLightColors': []
};
var palettes = {
primaryPalette: primaryPalette,
accentPalette: accentPalette,
warnPalette: 'red',
backgroundPalette: backgroundPalette
}
var initRequest = {
address: "http://localhost:5001",
transportType: 1,
customPalettes: palettes
}
const initialized = await ltgsdc.init(initRequest);
console.log("initialized", initialized);
document.getElementById("ltg-sdc-create-chat").addEventListener("click", () => {
ltgsdc.openChatWindow(options);
});
document.getElementById("ltg-sdc-close-chat").addEventListener("click", () => {
ltgsdc.closeChatWindow();
});
document.getElementById("ltg-sdc-logout").addEventListener("click", () => {
ltgsdc.logout();
});
});
</script>
</body>
</html>
Komplexeres Beispiel mit benutzerdefinierten Farbpaletten
<html>
<head>
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<script src="{relayServerUrl}/sdc/js"></script>
<style>
/* complex example with many CSS changes */
.ltg-sdc-root .ltg-sdc-relay-window {
background-color: #EBEBEB !important;
}
.ltg-sdc-root .ltg-sdc-chat-footer {
background-color: transparent !important;
}
.ltg-sdc-root .ltg-sdc-chat-footer svg {
fill: #1952AD !important;
}
.ltg-sdc-root .ltg-sdc-chat-message-system .ltg-sdc-chat-message {
background-color: #525252 !important;
color: #fff !important;
}
.ltg-sdc-root .ltg-sdc-chat-message-wrapper-them .ltg-sdc-chat-message {
background-color: #1952AD !important;
color: #fff !important;
}
.ltg-sdc-root .ltg-sdc-chat-actions {
background-color: #C4C4C4 !important;
color: black !important;
}
.ltg-sdc-root .ltg-sdc-chat-actions-button svg {
fill: black !important;
}
.ltg-sdc-root .ltg-sdc-close-wizard-header > md-content {
background-color: transparent !important;
}
</style>
</head>
<body>
<p>
TEST External Relay Website
</p>
<button id="ltg-sdc-create-chat">Create Chat</button>
<button id="ltg-sdc-close-chat">Close Chat</button>
<button id="ltg-sdc-logout">Logout</button>
<script>
document.addEventListener("DOMContentLoaded", async function () {
var options = {
firstName: "TEST",
lastName: "TEST",
emailAddress: "TEST@TEST.test",
// language: "en-GB",
// ticketNumber: "INC00199"
};
var primaryPalette = {
'50': 'e3eaf5',
'100': 'bacbe6',
'200': '8ca9d6',
'300': '5e86c6',
'400': '3c6cb9',
'500': '1952ad',
'600': '164ba6',
'700': '12419c',
'800': '0e3893',
'900': '082883',
'A100': 'b2c2ff',
'A200': '7f99ff',
'A400': '4c71ff',
'A700': '325dff',
'contrastDefaultColor': 'light',
'contrastDarkColors': [
'50',
'100',
'200',
'300',
'A100',
'A200'
],
'contrastLightColors': [
'400',
'500',
'600',
'700',
'800',
'900',
'A400',
'A700'
]
};
var accentPalette = {
'50': '174b9e',
'100': '174b9e',
'200': '174b9e',
'300': '174b9e',
'400': '174b9e',
'500': '174b9e',
'600': '174b9e',
'700': '174b9e',
'800': '174b9e',
'900': '174b9e',
'A100': '174b9e',
'A200': '174b9e',
'A400': '174b9e',
'A700': '174b9e',
'contrastDefaultColor': 'light',
'contrastDarkColors': [
'50',
'100',
'200',
'300',
'400',
'500',
'600',
'700',
'800',
'900',
'A100',
'A200',
'A400',
'A700'
],
'contrastLightColors': []
};
var backgroundPalette = {
'50': 'fdfdfd',
'100': 'f9f9f9',
'200': 'f5f5f5',
'300': 'f1f1f1',
'400': 'eeeeee',
'500': 'ebebeb',
'600': 'e9e9e9',
'700': 'e5e5e5',
'800': 'e2e2e2',
'900': 'dddddd',
'A100': 'ffffff',
'A200': 'ffffff',
'A400': 'ffffff',
'A700': 'ffffff',
'contrastDefaultColor': 'light',
'contrastDarkColors': [
'50',
'100',
'200',
'300',
'400',
'500',
'600',
'700',
'800',
'900',
'A100',
'A200',
'A400',
'A700'
],
'contrastLightColors': []
};
var palettes = {
primaryPalette: primaryPalette,
accentPalette: accentPalette,
warnPalette: 'red',
backgroundPalette: backgroundPalette
}
var initRequest = {
address: "http://localhost:5001",
transportType: 1,
customPalettes: palettes
}
const initialized = await ltgsdc.init(initRequest);
console.log("initialized", initialized);
document.getElementById("ltg-sdc-create-chat").addEventListener("click", () => {
ltgsdc.openChatWindow(options);
});
document.getElementById("ltg-sdc-close-chat").addEventListener("click", () => {
ltgsdc.closeChatWindow();
});
document.getElementById("ltg-sdc-logout").addEventListener("click", () => {
ltgsdc.logout();
});
});
</script>
</body>
</html>