Skip to content

Commit 25a6376

Browse files
billbabillba
committed
first draft
0 parents  commit 25a6376

10 files changed

Lines changed: 972 additions & 0 deletions

File tree

‎.gitignore‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
node_modules
2+
built
3+
.vscode
4+
/directLine.*

‎.npmignore‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
built/*.js.map
2+
node_modules
3+
samples
4+
src
5+
test
6+
tsconfig.json
7+
*.config.js
8+
*.js.map
9+
.gitattributes
10+
.gitignore
11+
.npmignore
12+
.vscode

‎LICENSE‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
The MIT License (MIT)
2+
3+
Copyright (c) 2016 Microsoft Corporation
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.
22+

‎README.md‎

Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
# Microsoft Bot Framework WebChat
2+
3+
Embeddable web chat control for the [Microsoft Bot Framework](http://www.botframework.com) using the [DirectLine](https://docs.botframework.com/en-us/restapi/directline3/) API.
4+
5+
Used by the Bot Framework developer portal, [Emulator](https://github.com/Microsoft/BotFramework-Emulator), WebChat channel, and [Azure Bot Service](https://azure.microsoft.com/en-us/services/bot-service/)
6+
7+
You can easily play with a recent build using [botchattest](https://botchattest.herokuapp.com)
8+
9+
## FAQ
10+
11+
### *How is it made?*
12+
13+
WebChat is a [React](https://facebook.github.io/react/) component built in [TypeScript](http://www.typescriptlang.org) using [Redux](http://redux.js.org) for state management and [RxJS](http://reactivex.io/rxjs/) for wrangling async.
14+
15+
### *How can I use it?*
16+
17+
* As an IFRAME in any website using the standard Bot Framework WebChat channel. In this case you don't need this repo or any of the information in it.
18+
* As a standalone website, primarily for testing purposes
19+
* As an IFRAME in any website, pointed at an instance hosted by you, customized to your needs
20+
* Inline in your non-React webapp, customized to your needs
21+
* Inline in your React webapp, customized to your needs
22+
23+
See more detailed instructions [below](#getting-webchat-up-and-running).
24+
25+
### *How do I customize it?*
26+
27+
* Follow the [below instructions](#1-install-and-build) to install and build
28+
* Customize the visuals by altering the [static/botchat.css](https://github.com/Microsoft/BotFramework-WebChat/blob/master/static/botchat.css) file
29+
* Or go farther and change the HTML/JSX and/or TypeScript
30+
31+
### *How do I contribute to it?*
32+
33+
* File [issues](https://github.com/Microsoft/BotFramework-WebChat/issues) and submit [pull requests](https://github.com/Microsoft/BotFramework-WebChat/pulls)!
34+
35+
### *Do you have a roadmap?*
36+
37+
Not the most formal one you'll ever see, but:
38+
39+
* Unit tests
40+
* DirectLine 3.0 WebSocket support for retrieving messages
41+
* Improved styling
42+
* Simple UI customization
43+
* npm package(s)
44+
* CDN
45+
46+
Feel free to suggest features by filing an [issue](https://github.com/Microsoft/BotFramework-WebChat/issues) (please make sure one doesn't already exist).
47+
48+
### How can I help?
49+
50+
* Add localized strings (see [below](#to-add-localized-strings))
51+
* Report any unreported [issues](https://github.com/Microsoft/BotFramework-WebChat/issues)
52+
* Propose new [features](https://github.com/Microsoft/BotFramework-WebChat/issues)
53+
* Fix an outstanding [issue](https://github.com/Microsoft/BotFramework-WebChat/issues) and submit a [pull request](https://github.com/Microsoft/BotFramework-WebChat/pulls) *(please only commit source code, non-generated files)*
54+
55+
## Getting WebChat up and running
56+
57+
### 1. Install and build
58+
59+
1. Clone this repo
60+
2. `npm install`
61+
3. `npm run build` (to build on every change `npm run watch`, to build minified `npm run minify`)
62+
63+
### 2. Obtain security credentials for your bot
64+
65+
1. If you haven't already, [register your bot](https://dev.botframework.com/bots/new).
66+
2. Add a DirectLine channel, and generate a Direct Line Secret. Make sure to enable Direct Line 3.0.
67+
3. For testing you can use your Direct Line Secret as a security token, but for production you will likely want to exchange that Secret for a Token as detailed in the Direct Line [documentation](https://docs.botframework.com/en-us/restapi/directline3/).
68+
69+
### 3. Decide how to run WebChat
70+
71+
#### Using the WebChat channel
72+
73+
1. Head over to the [Bot Framework developer portal](https://dev.botframework.com/bots) and add the WebChat channel to your bot. You don't need this repo or any of the information on this page.
74+
75+
#### As a standalone web page, for quick and easy testing
76+
77+
This is a quick and dirty method, perfect for testing. It requires embedding your Direct Line Secret in the web page or querystring, and as such should primarily be used for local testing.
78+
79+
0. Build
80+
1. Start a local web server using `npm run start` and aim your browser at `http://localhost:8000/samples?s={Direct Line Secret}`
81+
82+
#### Embedded via IFRAME
83+
84+
In this scenario you will host two web pages, one for WebChat and one for the page which embeds it. They could be hosted by the same web server, or two entirely different web servers.
85+
86+
1. Serve the botchat in its own standalone web page, as described [above](#as-a-standalone-web-page-for-quick-and-easy-testing)
87+
2. Optionally, on your web server, exchange the Direct Line Secret for a Token as detailed in the Direct Line [documentation](https://docs.botframework.com/en-us/restapi/directline3/).
88+
3. In a second web page, embed the botchat via `<iframe src="http://{host}:{port}/samples?[s={Direct Line Secret}|t={Direct Line Token}]" width="320" height="500"/>`
89+
4. You will probably want to customize the supplied sample index.html page
90+
91+
(An example of this approach is [botchattest](https://github.com/billba/botchattest))
92+
93+
#### Inline in your non-React website
94+
95+
In this scenario you will include a JavaScript file which embeds its own copy of React, which will run in a DOM element.
96+
97+
0. Build
98+
1. Include `webpacked/botchat.js` and you will get an object called `BotChat`
99+
2. For TypeScript users there is a type definition file called [static/botchat.d.ts](https://github.com/Microsoft/BotFramework-WebChat/blob/master/static/botchat.d.ts).
100+
3. Incorporate [static/botchat.css](https://github.com/Microsoft/BotFramework-WebChat/blob/master/static/botchat.css) into your website deployment
101+
4. Optionally, on your web server, exchange the Direct Line Secret for a Token as detailed in the Direct Line [documentation](https://docs.botframework.com/en-us/restapi/directline3/).
102+
5. Create an instance of `BotChat.DirectLine` using your Direct Line Secret or Token
103+
6. Call `BotChat.App` with the DOM element where you want your chat instance, your DirectLine instance, user and bot identities, and other properties as demonstrated in [samples/index.html](https://github.com/Microsoft/BotFramework-WebChat/blob/master/samples/index.html).
104+
105+
#### Inline in your React website
106+
107+
In this scenario you will incorporate WebChat's multiple JavaScript files into your React webapp.
108+
109+
0. Build
110+
1. Incorporate the files in the [/built](https://github.com/Microsoft/BotFramework-WebChat/blob/master/built) folder into your build process
111+
2. Incorporate [static/botchat.css](https://github.com/Microsoft/BotFramework-WebChat/blob/master/static/botchat.css) into your website deployment
112+
3. For TypeScript users there is a definition file called [static/botchat.d.ts](https://github.com/Microsoft/BotFramework-WebChat/blob/master/static/botchat.d.ts).
113+
4. Optionally, on your web server, exchange the Direct Line Secret for a Token as detailed in the Direct Line [documentation](https://docs.botframework.com/en-us/restapi/directline3/).
114+
5. Create an instance of `DirectLine` using your Direct Line Secret or Token
115+
6. Call the `Chat` React component with your DirectLine instance, user and bot identities, and other properties as demonstrated in [samples/index.html](https://github.com/Microsoft/BotFramework-WebChat/blob/master/samples/index.html).
116+
117+
## Misc. notes
118+
119+
### To see WebChat logging
120+
121+
* When IFRAMEd, set `window.frames["{iframe_id}"].botchatDebug = true` from the browser console
122+
* Otherwise set `window.botchatDebug = true` or `var botchatDebug = true` from the browser console
123+
124+
### To add localized strings
125+
126+
In [src/Strings.ts](https://github.com/Microsoft/BotFramework-WebChat/blob/master/src/Strings.ts) :
127+
* Add one or more locales (with associated localized strings) to `localizedStrings`
128+
* Add logic to map the requested locale to the support locale in `strings`
129+
* If you just adding a new locale for an existing set of strings, just update `strings` to return the existing locale's strings
130+
* ... and please help the community by submitting a [pull request](https://github.com/Microsoft/BotFramework-WebChat/pulls)!
131+
132+
## Copyright & License
133+
134+
© 2016 Microsoft Corporation
135+
136+
[MIT License](/LICENSE)

‎package.json‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
{
2+
"name": "botframework-directlinejs",
3+
"version": "0.6.0",
4+
"description": "client library for the Microsoft Bot Framework Direct Line protocol",
5+
"main": "built/directLine.js",
6+
"types": "directLine.d.ts",
7+
"scripts": {
8+
"build": "tsc && webpack",
9+
"watch": "npm-run-all -p -r -l tsc-watch webpack-watch",
10+
"tsc-watch": "tsc -w",
11+
"webpack-watch": "webpack -w",
12+
"clean": "rm -rf built",
13+
"prepublish": "tsc && webpack --config webpack.production.config.js",
14+
"start": "http-server -p 8000",
15+
"test": "mocha test"
16+
},
17+
"repository": {
18+
"type": "git",
19+
"url": "git://git@github.com/Microsoft/BotFramework-DirectLineJS.git"
20+
},
21+
"author": "Microsoft Corp",
22+
"license": "MIT",
23+
"dependencies": {
24+
"rxjs": "^5.0.3"
25+
},
26+
"devDependencies": {
27+
"@types/chai": "^3.4.34",
28+
"@types/chai-subset": "^1.0.29",
29+
"@types/deep-freeze": "0.0.29",
30+
"chai": "^3.5.0",
31+
"chai-subset": "^1.4.0",
32+
"deep-freeze": "0.0.1",
33+
"http-server": "^0.9.0",
34+
"mocha": "^3.2.0",
35+
"npm-run-all": "^3.1.2",
36+
"source-map-loader": "^0.1.5",
37+
"ts-loader": "^1.3.3",
38+
"typescript": "^2.1.5",
39+
"webpack": "^1.14.0"
40+
}
41+
}

‎samples/index.html‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
<!DOCTYPE html>
2+
<!--
3+
This is a sample HTML file which shows how to embed an instance of WebChat. Useful for testing.
4+
1. Build the project: "npm run build"
5+
2. Start a web server: "npm run start"
6+
3. Aim your browser at "http://localhost:8000/samples?[parameters as listed below]"
7+
8+
For ease of testing, several parameters can be set in the query string:
9+
* s = Direct Line secret, or
10+
* t = Direct Line token (obtained by calling Direct Line's Generate Token)
11+
* domain = optionally, the URL of an alternate Direct Line endpoint
12+
* webSocket = set to 'true' to use WebSocket to receive messages (currently defaults to false)
13+
* userid, username = id (and optionally name) of bot user
14+
* botid, botname = id (and optionally name) of bot
15+
-->
16+
<html>
17+
<head>
18+
<meta charset="UTF-8" />
19+
<title>Bot Chat</title>
20+
<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no" />
21+
<style>
22+
html, body {
23+
height: 100%;
24+
margin: 0;
25+
padding: 0;
26+
overflow: hidden;
27+
}
28+
</style>
29+
<link href="../botchat.css" rel="stylesheet" />
30+
</head>
31+
<body>
32+
<div id="BotChatGoesHere"></div>
33+
<script src="../botchat.js"></script>
34+
<script>
35+
var params = {};
36+
location
37+
.search
38+
.substring(1)
39+
.split("&")
40+
.forEach(function (pair) {
41+
var p = pair.split("=");
42+
params[p[0]] = decodeURIComponent(p[1]);
43+
});
44+
45+
var user = {
46+
id: params['userid'] || 'userid',
47+
name: params["username"] || 'username'
48+
};
49+
50+
var bot = {
51+
id: params['botid'] || 'botid',
52+
name: params["botname"] || 'botname'
53+
};
54+
55+
window['botchatDebug'] = params['debug'];
56+
57+
BotChat.App({
58+
directLine: {
59+
secret: params['s'],
60+
token: params['t'],
61+
domain: params['domain'],
62+
webSocket: params['webSocket']
63+
},
64+
user: user,
65+
bot: bot,
66+
locale: params['locale'],
67+
}, document.getElementById("BotChatGoesHere"));
68+
</script>
69+
</body>
70+
</html>

0 commit comments

Comments
 (0)