Skip to content

Commit 17a99ee

Browse files
openpublishbuildopenpublishbuild
committed
Merging changes synced from https://github.com/MicrosoftDocs/bot-docs-pr (branch live)
2 parents b4e3d9d + abd5b8c commit 17a99ee

File tree

3 files changed

+645
-0
lines changed

3 files changed

+645
-0
lines changed

‎articles/resources/TOC.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,9 @@
55
# Skills
66
## [Overview](../v4sdk/bot-builder-skills-overview.md)
77
## [Getting Started](../v4sdk/bot-builder-skills-gettingstarted.md)
8+
# WebChat
9+
## [Overview](../v4sdk/bot-builder-webchat-overview.md)
10+
## [Customization](../v4sdk/bot-builder-webchat-customization.md)
811
# [FAQ](../bot-service-resources-bot-framework-faq.md)
912
# [Get support](../bot-service-resources-links-help.md)
1013
# [Channel reference](../bot-service-channels-reference.md)

‎articles/v4sdk/bot-builder-webchat-customization.md‎

Lines changed: 363 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,363 @@
1+
---
2+
title: Web Chat customization | Microsoft Docs
3+
description: Learn how to customize the Bot Framework Web Chat.
4+
keywords: bot framework, webchat, chat, samples, react, reference
5+
author: ivorb
6+
ms.author: v-ivorb
7+
manager: kamrani
8+
ms.topic: article
9+
ms.service: bot-service
10+
ms.subservice: sdk
11+
ms.date: 06/07/2019
12+
---
13+
14+
# Web Chat customization
15+
16+
This article details how to customize the Web Chat samples to fit your bot.
17+
18+
## Integrate Web Chat into your website
19+
20+
Follow the instructions on the [overview page](bot-builder-webchat-overview.md) page to integrate the Web Chat control into your website.
21+
22+
## Customizing styles
23+
24+
The latest version of Web Chat control provides rich customization options: you can change colors, sizes, placement of elements, add custom elements, and interact with the hosting webpage. Below are several examples of how to customize those elements of the Web Chat UI.
25+
26+
You can find the full list of all settings that you can easily modify in Web Chat on the [`defaultStyleOptions.js` file](https://github.com/Microsoft/BotFramework-WebChat/blob/master/packages/component/src/Styles/defaultStyleOptions.js).
27+
28+
These settings will generate a _style set_, which is a set of CSS rules enhanced with [glamor](https://github.com/threepointone/glamor). You can find the full list of CSS styles generated in the style set on the [`createStyleSet.js` file](https://github.com/Microsoft/BotFramework-WebChat/blob/master/packages/component/src/Styles/createStyleSet.js).
29+
30+
## Set the size of the Web Chat container
31+
32+
It is now possible to adjust the size of the Web Chat container using `styleSetOptions`. The following example has a `body` background-color of `paleturquoise` to show the Web Chat container (section with white background).
33+
34+
```js
35+
…
36+
<head>
37+
<style>
38+
html, body { height: 100% }
39+
body {
40+
margin: 0;
41+
background-color: paleturquoise;
42+
}
43+
44+
#webchat {
45+
height: 100%;
46+
width: 100%;
47+
}
48+
</style>
49+
</head>
50+
<body>
51+
<div id="webchat" role="main"></div>
52+
<script>
53+
(async function () {
54+
window.WebChat.renderWebChat({
55+
directLine: window.WebChat.createDirectLine({ token }),
56+
styleOptions: {
57+
rootHeight: '100%',
58+
rootWidth: '50%'
59+
}
60+
}, document.getElementById('webchat'));
61+
})()
62+
</script>
63+
…
64+
```
65+
66+
Here is the result:
67+
68+
<img alt="Web Chat with root height and root width set" src="https://raw.githubusercontent.com/Microsoft/BotFramework-WebChat/master/media/rootHeightWidth.png" width="600"/>
69+
70+
## Change font or color
71+
72+
Instead of using the default background color and the fonts used inside of the chat bubbles, you can customize those to match the style of the target web page. The code snippet below allows you to change the background color of messages from the user and from the bot.
73+
74+
<img alt="Screenshot with custom style options" src="https://raw.githubusercontent.com/Microsoft/BotFramework-WebChat/master/media/sample-custom-style-options.png" width="396" />
75+
76+
If you need to do some simple styling, you can set them via `styleOptions`. Style options are set of predefined styles that you can modify directly, and Web Chat will compute the whole stylesheet based on it.
77+
78+
```html
79+
<!DOCTYPE html>
80+
<html>
81+
<body>
82+
<div id="webchat" role="main"></div>
83+
<script src="https://cdn.botframework.com/botframework-webchat/latest/webchat.js"></script>
84+
<script>
85+
const styleOptions = {
86+
bubbleBackground: 'rgba(0, 0, 255, .1)',
87+
bubbleFromUserBackground: 'rgba(0, 255, 0, .1)'
88+
};
89+
90+
window.WebChat.renderWebChat(
91+
{
92+
directLine: window.WebChat.createDirectLine({
93+
secret: 'YOUR_BOT_SECRET'
94+
}),
95+
96+
// Passing 'styleOptions' when rendering Web Chat
97+
styleOptions
98+
},
99+
document.getElementById('webchat')
100+
);
101+
</script>
102+
</body>
103+
</html>
104+
```
105+
106+
## Change the CSS manually
107+
108+
In addition to colors, you can modify fonts used to render messages:
109+
110+
<img alt="Screenshot with custom style set" src="https://raw.githubusercontent.com/Microsoft/BotFramework-WebChat/master/media/sample-custom-style-set.png" width="396" />
111+
112+
For deeper styling, you can also modify the style set manually by setting the CSS rules directly.
113+
114+
> Since CSS rules are tightly-coupled to the structure of the DOM tree, there is possibility that these rules need to be updated to work with the newer version of Web Chat.
115+
116+
```html
117+
<!DOCTYPE html>
118+
<html>
119+
<body>
120+
<div id="webchat" role="main"></div>
121+
<script src="https://cdn.botframework.com/botframework-webchat/latest/webchat.js"></script>
122+
<script>
123+
// "styleSet" is a set of CSS rules which are generated from "styleOptions"
124+
const styleSet = window.WebChat.createStyleSet({
125+
bubbleBackground: 'rgba(0, 0, 255, .1)',
126+
bubbleFromUserBackground: 'rgba(0, 255, 0, .1)'
127+
});
128+
129+
// After generated, you can modify the CSS rules
130+
styleSet.textContent = {
131+
...styleSet.textContent,
132+
fontFamily: "'Comic Sans MS', 'Arial', sans-serif",
133+
fontWeight: 'bold'
134+
};
135+
136+
window.WebChat.renderWebChat(
137+
{
138+
directLine: window.WebChat.createDirectLine({
139+
secret: 'YOUR_BOT_SECRET'
140+
}),
141+
142+
// Passing 'styleSet' when rendering Web Chat
143+
styleSet
144+
},
145+
document.getElementById('webchat')
146+
);
147+
</script>
148+
</body>
149+
</html>
150+
```
151+
152+
## Change the avatar of the bot within the dialog box
153+
154+
The latest Web Chat support avatar, you can customize them using `botAvatarInitials` and `userAvatarInitials` props.
155+
156+
<img alt="Screenshot with avatar initials" src="https://raw.githubusercontent.com/Microsoft/BotFramework-WebChat/master/media/sample-avatar-initials.png" width="396" />
157+
158+
```html
159+
<!DOCTYPE html>
160+
<html>
161+
<body>
162+
<div id="webchat" role="main"></div>
163+
<script src="https://cdn.botframework.com/botframework-webchat/latest/webchat.js"></script>
164+
<script>
165+
window.WebChat.renderWebChat(
166+
{
167+
directLine: window.WebChat.createDirectLine({
168+
secret: 'YOUR_BOT_SECRET'
169+
}),
170+
171+
// Passing avatar initials when rendering Web Chat
172+
botAvatarInitials: 'BF',
173+
userAvatarInitials: 'WC'
174+
},
175+
document.getElementById('webchat')
176+
);
177+
</script>
178+
</body>
179+
</html>
180+
```
181+
182+
Inside the `renderWebChat` code, we added `botAvatarInitials` and `userAvatarInitials`:
183+
184+
```js
185+
botAvatarInitials: 'BF',
186+
userAvatarInitials: 'WC'
187+
```
188+
189+
`botAvatarInitials` will set the text inside the avatar on the left-hand side. If it is set to falsy value, the avatar on the bot side will be hidden. In contrast, `userAvatarInitials` will set the avatar text on the right-hand side.
190+
191+
## Custom rendering activity or attachment
192+
193+
With the latest version of Web Chat, you can also render activities or attachments that Web Chat does not support out-of-the-box. Activities and attachments render are sent thru a customizable pipeline that modeled after [Redux middleware](https://redux.js.org/api/applymiddleware). The pipeline is flexible enough that you can do the following tasks easily:
194+
195+
- Decorate existing activities/attachments
196+
- Add new activities/attachments
197+
- Replace existing activities/attachments (or remove them)
198+
- Daisy chain middleware together
199+
200+
### Show GitHub repository as an attachment
201+
202+
If you want to display a deck of GitHub repository cards, you can create a new React component for the GitHub repository and add it as a middleware for attachment.
203+
204+
<img alt="Screenshot with custom GitHub repository attachment" src="https://raw.githubusercontent.com/Microsoft/BotFramework-WebChat/master/media/sample-custom-github-repository-attachment.png" width="396" />
205+
206+
```jsx
207+
import ReactWebChat from 'botframework-webchat';
208+
import ReactDOM from 'react-dom';
209+
210+
// Create a new React component that accept render a GitHub repository attachment
211+
const GitHubRepositoryAttachment = props => (
212+
<div
213+
style={{
214+
fontFamily: "'Calibri', 'Helvetica Neue', Arial, sans-serif",
215+
margin: 20,
216+
textAlign: 'center'
217+
}}
218+
>
219+
<svg
220+
height="64"
221+
viewBox="0 0 16 16"
222+
version="1.1"
223+
width="64"
224+
aria-hidden="true"
225+
>
226+
<path
227+
fillRule="evenodd"
228+
d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0 0 16 8c0-4.42-3.58-8-8-8z"
229+
/>
230+
</svg>
231+
<p>
232+
<a
233+
href={`https://github.com/${encodeURI(props.owner)}/${encodeURI(
234+
props.repo
235+
)}`}
236+
target="_blank"
237+
>
238+
{props.owner}/<br />
239+
{props.repo}
240+
</a>
241+
</p>
242+
</div>
243+
);
244+
245+
// Creating a new middleware pipeline that will render <GitHubRepositoryAttachment> for specific type of attachment
246+
const attachmentMiddleware = () => next => card => {
247+
switch (card.attachment.contentType) {
248+
case 'application/vnd.microsoft.botframework.samples.github-repository':
249+
return (
250+
<GitHubRepositoryAttachment
251+
owner={card.attachment.content.owner}
252+
repo={card.attachment.content.repo}
253+
/>
254+
);
255+
256+
default:
257+
return next(card);
258+
}
259+
};
260+
261+
ReactDOM.render(
262+
<ReactWebChat
263+
// Prepending the new middleware pipeline
264+
attachmentMiddleware={attachmentMiddleware}
265+
directLine={window.WebChat.createDirectLine({ token })}
266+
/>,
267+
document.getElementById('webchat')
268+
);
269+
```
270+
271+
The full sample can be found in [the customization-card-components sample](https://github.com/microsoft/BotFramework-WebChat/tree/master/samples/10.a.customization-card-components).
272+
273+
In this sample, we are adding a new React component called `GitHubRepositoryAttachment`:
274+
275+
```jsx
276+
const GitHubRepositoryAttachment = props => (
277+
<div
278+
style={{
279+
fontFamily: "'Calibri', 'Helvetica Neue', Arial, sans-serif",
280+
margin: 20,
281+
textAlign: 'center'
282+
}}
283+
>
284+
<svg
285+
height="64"
286+
viewBox="0 0 16 16"
287+
version="1.1"
288+
width="64"
289+
aria-hidden="true"
290+
>
291+
<path
292+
fillRule="evenodd"
293+
d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0 0 16 8c0-4.42-3.58-8-8-8z"
294+
/>
295+
</svg>
296+
<p>
297+
<a
298+
href={`https://github.com/${encodeURI(props.owner)}/${encodeURI(
299+
props.repo
300+
)}`}
301+
target="_blank"
302+
>
303+
{props.owner}/<br />
304+
{props.repo}
305+
</a>
306+
</p>
307+
</div>
308+
);
309+
```
310+
311+
Then, we create a middleware that will render the new React component when the bot sends an attachment of content type `application/vnd.microsoft.botframework.samples.github-repository`. Otherwise, it will continue on the middleware by calling `next(card)`.
312+
313+
```jsx
314+
const attachmentMiddleware = () => next => card => {
315+
switch (card.attachment.contentType) {
316+
case 'application/vnd.microsoft.botframework.samples.github-repository':
317+
return (
318+
<GitHubRepositoryAttachment
319+
owner={card.attachment.content.owner}
320+
repo={card.attachment.content.repo}
321+
/>
322+
);
323+
324+
default:
325+
return next(card);
326+
}
327+
};
328+
```
329+
330+
The activity sent from the bot looks like the following:
331+
332+
```json
333+
{
334+
"type": "message",
335+
"from": {
336+
"role": "bot"
337+
},
338+
"attachmentLayout": "carousel",
339+
"attachments": [
340+
{
341+
"contentType": "application/vnd.microsoft.botframework.samples.github-repository",
342+
"content": {
343+
"owner": "Microsoft",
344+
"repo": "BotFramework-WebChat"
345+
}
346+
},
347+
{
348+
"contentType": "application/vnd.microsoft.botframework.samples.github-repository",
349+
"content": {
350+
"owner": "Microsoft",
351+
"repo": "BotFramework-Emulator"
352+
}
353+
},
354+
{
355+
"contentType": "application/vnd.microsoft.botframework.samples.github-repository",
356+
"content": {
357+
"owner": "Microsoft",
358+
"repo": "BotFramework-DirectLineJS"
359+
}
360+
}
361+
]
362+
}
363+
```

0 commit comments

Comments
 (0)