Service Desk Chat JS Integrations-Guide

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

  1. 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.

 

  1. 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>

 

  1. closeChatWindow()
    • Beschreibung: Schließt das Chat Fenster und trennt die Verbindung zum Relay.
    • Rückgabewert: Nichts

 

  1. 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.

  1. “ltg.sdc.OpenedChatWindow”: Dieses Event wird versendet, wenn das Chat Fenster geöffnet wurde und sichtbar ist.
  2. “ltg.sdc.MinimizeWindow”: Mit diesem Event wird verdeutlicht, dass das Fenster minimiert wurde. Bei Minimierung des Fensters wird die Verbindung zum Relay nicht unterbrochen.
  3. “ltg.sdc.CloseWindow”: Bei Schließung des Fensters wird dieses Event ausgelöst. Die Verbindung zum Relay wird bei Schließung des Fensters getrennt.
  4. “ltg.sdc.NewMessage”: Dieses Event wird durch einkommende Nachrichten ausgelöst und kann ggf. abgefangen werden.

Alle Events könnten wie folgt abgefangen werden.

1
2
3
4
5
window.addEventListener("{eventName}", () =&gt; {
 
// 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:

1
2
3
4
5
6
7
8
9
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:

1
2
3
4
5
{
 
"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:

1
2
3
4
5
6
7
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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
<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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
<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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
<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>