Skip to content

Commit 6b2ac3f

Browse files
DLeylandDLeyland
authored
Update chat init args schema and improve security of auth docs (#138)
1 parent 5aaee0a commit 6b2ac3f

File tree

3 files changed

+115
-13
lines changed

3 files changed

+115
-13
lines changed

‎_snippets/chat/customization.mdx

Lines changed: 103 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -5,21 +5,43 @@ Plain.init({
55
// Optional. Hides the launcher, you can manually show it by calling `Plain.open()` (default: false)
66
hideLauncher: false,
77

8-
// Optional. The title of the chat window shown on the Welcome screen
9-
title: 'Chat with us',
10-
118
// Optional. A collection of links shown on the Welcome screen
129
links: [
1310
{
14-
icon: 'book', // Optional, we also support 'discord' and 'slack' as icons
11+
// Optional, supported icons are:
12+
// 'bell',
13+
// 'book',
14+
// 'bug',
15+
// 'bulb',
16+
// 'chat',
17+
// 'integration',
18+
// 'discord',
19+
// 'email',
20+
// 'slack',
21+
// 'link',
22+
// 'pencil',
23+
// 'send',
24+
// 'support',
25+
// 'error'
26+
icon: 'book',
1527
text: 'View our docs',
1628
url: 'https://www.plain.com/docs',
1729
},
1830
],
1931

20-
// Optional. The entry point of the Chat, is either 'default' or 'chat'
21-
// 'chat' will open the last conversation the user had (default: 'default')
22-
entryPoint: 'default',
32+
// Optional. The entry point of the Chat.
33+
entryPoint: {
34+
// Type is either 'default' or 'chat'. 'default' will open the intro screen, 'chat' opens up straight into a chat.
35+
type: 'chat',
36+
// Optional. The external ID of which chat to open. If not provided it will default to the last conversation the user had
37+
externalId: 'example_external_id',
38+
// Optional. Prevents the user from going back to the intro screen to start a new chat
39+
singleChatMode?: false,
40+
},
41+
42+
// Optional. Lets you specify which HTML element to insert the chat into.
43+
// When specified, launcher will be hidden by default.
44+
embedAt: '#embed',
2345

2446
// Optional. The color scheme of the Chat, is either 'auto', 'light', or 'dark'
2547
// 'auto' uses the user's browser preference to decide between light and dark mode (default: 'auto')
@@ -28,8 +50,80 @@ Plain.init({
2850
// Optional. Various styling options
2951
// Colors can also be passed in this format { light: '#FFFFFF', dark: '#000000' }. Based on the theme chosen by you or browser preference
3052
style: {
31-
chatButtonColor: '#000000'; // These can also be passed in this foramt { light: '#FFFFFF', dark: '#000000' }
32-
chatButtonIconColor: '#FFFFFF';
53+
launcherBackgroundColor: '#000000'; // These can also be passed in this format { light: '#FFFFFF', dark: '#000000' }
54+
launcherIconColor: '#FFFFFF';
3355
}
56+
57+
// Optional. Logo which is shown in the header of the chat intro screen
58+
logo: {
59+
// url to get the logo from
60+
url: 'http://example.com';
61+
// Optional. Alt text which is displayed on hover of the logo
62+
alt: 'An example logo';
63+
};
64+
65+
// Optional. Allows you to set fields for the threads which are created from chats
66+
threadDetails: {
67+
68+
// Optional. Labels to be set on created threads.
69+
// To find a label id open the Plain app and go to 'Settings' -> 'Labels', you can select `Copy label ID` from the overflow menu on each label
70+
labelTypeIds: ['lt_01JDAB92EBHP3DSXS43DW96WBS'],
71+
72+
// Optional. A tier to be set on created threads.
73+
// To find a tier ID open the Plain app and go to 'Settings' -> 'Tiers'. Select a tier and then copy the ID from the URL.
74+
// You can also specify a tier by its external ID e.g { externalId: 'example_external_id' }
75+
tierIdentifier: { tierId: 'tier_01JDABCAZBDFKH7WA6WNBDSA2F' },
76+
77+
// Optional. A tenant to be set on created threads.
78+
// To find a tenant ID open the Plain app and click 'Tenants' under 'Browse' in the left sidebar. Select a tenant and then copy the ID from the URL.
79+
// You can also specify a tenant by its external ID e.g { externalId: 'example_external_id' }
80+
tenantIdentifier: { tenantId: 'te_01HT539973HNVZFSDXWHPT8FH1' },
81+
82+
// Optional. An external ID to be set on created threads.
83+
externalId: 'example_external_id';
84+
};
85+
86+
// Optional. Lets you customize the buttons which are used to start a new chat on the intro screen
87+
chatButtons: [
88+
{
89+
// Optional. The name of the icon to display, see above for full options
90+
icon: 'bulb',
91+
92+
// The text to display on the button
93+
text: 'Give feedback',
94+
95+
// Optional. Allows you to set fields for the threads which are created with this button. See above for full options.
96+
threadDetails: {};
97+
98+
// Optional. Form elements which the user must fill out before sending a chat message
99+
form: {
100+
101+
// The fields which make up the form. All form fields must be filled in for a user to send a chat message
102+
fields: [
103+
{
104+
// Currently only dropdown form fields are supported
105+
type: 'dropdown',
106+
107+
// Optional. The placeholder text displayed on the dropdown
108+
placeholder: 'Select a topic...',
109+
110+
// The options which are available in the dropdown, minimum of 1 required.
111+
options: [
112+
{
113+
// Optional. An icon to be displayed on the dropdown option. See above for full options.
114+
icon: 'bug',
115+
116+
// The text which is displayed for this dropdown option
117+
text: 'Bug report',
118+
119+
// Optional. Enables setting values on threads when this option is selected by the user. See above for full options
120+
threadDetails: {},
121+
}
122+
],
123+
}
124+
]
125+
},
126+
}
127+
];
34128
});
35129
```

‎chat.mdx

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -13,9 +13,8 @@ Here’s how to get started:
1313

1414
<Steps>
1515
<Step title="Create your Chat app">
16-
*At the moment you can only create a single Chat app configuration per workspace. In future we
17-
will allow multiple configurations.* - In Plain, navigate to **`Settings`** > **`Chat`**. -
18-
Press **`Create Chat App`**.
16+
In Plain, navigate to **`Settings`** > **`Chat`**.
17+
Press **`Create a Chat App`**.
1918
</Step>
2019
<Step title="Add Chat to your webpage(s)">
2120
After creating your Chat app, you will be provided with a snippet of code that you can embed in

‎chat/authentication.mdx

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,9 @@ These details will be shown to you in the Plain app when you are chatting with t
2424
If you want to match the customer to an existing customer in your workspace, you will need to pass their email. To avoid security issues around impersonation you will also need to
2525
provide the email address hashed using a shared secret. You can generate this secret in the Chat settings page in the Plain app.
2626

27-
Once you have this secret, you can calculate the hash and pass it to the `Plain.init` function:
27+
Once you have this secret, you can calculate the hash. This must be done in backend code to avoid leaking the secret. If your secret is leaked malicious users will be able to impersonate your customers in chats.
28+
29+
Backend code:
2830

2931
```typescript
3032
import * as crypto from 'node:crypto';
@@ -34,6 +36,13 @@ const email = '[email protected]';
3436
const hmac = crypto.createHmac('sha256', secret);
3537
hmac.update(email);
3638
const hash = hmac.digest('hex');
39+
```
40+
41+
Then you can request the hash from your backend and init Plain:
42+
43+
```typescript
44+
const email = '[email protected]';
45+
const hash = fetchHashFromBackend(email);
3746

3847
Plain.init({
3948
customerDetails: {

0 commit comments

Comments
 (0)