Skip to content

Commit a5d4ab1

Browse files
billbabillba
committed
added event, updated docs
1 parent efe5357 commit a5d4ab1

6 files changed

Lines changed: 95 additions & 166 deletions

File tree

‎LICENSE‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
The MIT License (MIT)
22

3-
Copyright (c) 2016 Microsoft Corporation
3+
Copyright (c) 2017 Microsoft Corporation
44

55
Permission is hereby granted, free of charge, to any person obtaining a copy
66
of this software and associated documentation files (the "Software"), to deal

‎README.md‎

Lines changed: 79 additions & 92 deletions
Original file line numberDiff line numberDiff line change
@@ -1,136 +1,123 @@
1-
# Microsoft Bot Framework WebChat
1+
# Microsoft Bot Framework Direct Line library for JavaScript
22

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.
3+
Client ibrary for the [Microsoft Bot Framework](http://www.botframework.com) [DirectLine](https://docs.botframework.com/en-us/restapi/directline3/) protocol.
44

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)
5+
Used by [WebChat](https://github.com/Microsoft/BotFramework-WebChat) and thus (by extension) [Emulator](https://github.com/Microsoft/BotFramework-Emulator), WebChat channel, and [Azure Bot Service](https://azure.microsoft.com/en-us/services/bot-service/).
86

97
## FAQ
108

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).
9+
### *Who is this for?*
2410

25-
### *How do I customize it?*
11+
Anyone who is building a Bot Framework JavaScript client who does not want to use [WebChat](https://github.com/Microsoft/BotFramework-WebChat).
2612

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
13+
### *What is Rx?*
3014

31-
### *How do I contribute to it?*
15+
**R**eactive E**x**tensions are a set of libraries for different languages implementing Reactive Functional Programming a.k.a. the Observable pattern. This library uses [RxJS](http://reactivex.io/rxjs/).
3216

33-
* File [issues](https://github.com/Microsoft/BotFramework-WebChat/issues) and submit [pull requests](https://github.com/Microsoft/BotFramework-WebChat/pulls)!
17+
### *Can I use [TypeScript](http://www.typescriptlang.com)?*
3418

35-
### *Do you have a roadmap?*
19+
You bet.
3620

37-
Not the most formal one you'll ever see, but:
21+
### How ready for prime time is this library?
3822

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
23+
This library is an official Microsoft-supported library, and is considered largely complete. Future changes (aside from supporting future updates to the Direct Line protocol) will likely be limited to performance improvements, tutorials, and samples. The big missing piece here is unit tests.
4524

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).
25+
## How to build from source
4726

48-
### How can I help?
27+
0. Clone this repo
28+
1. `npm install`
29+
2. `npm run build` (or `npm run watch` to rebuild on every change)
4930

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)*
31+
## How to include in your app
5432

55-
## Getting WebChat up and running
33+
There are several ways:
5634

57-
### 1. Install and build
35+
1. Build from scratch and include either `/directLine.js` (webpacked with rxjs) or `built/directline.js` in your app
36+
2. Use the unpkg CDN, e.g. `<script src="http://unpkg.com/botframework-directlinejs/directLine.js"/>`
37+
3. `npm install botframework-directlinejs`
5838

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`)
39+
## How to create and use a directLine object
6240

63-
### 2. Obtain security credentials for your bot
41+
### First, obtain security credentials for your bot:
6442

6543
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.
44+
2. Add a DirectLine (**not WebChat**) channel, and generate a Direct Line Secret. Make sure to Direct Line 3.0 is enabled.
6745
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/).
6846

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.
47+
### Second, create a DirectLine object:
7848

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}`
49+
var directLine = new DirectLine({
50+
secret: /* put your Direct Line secret here */,
51+
token: /* or put your Direct Line token here (supply secret OR token, not both) */,
52+
domain: /* optional: if you are not using the default Direct Line endpoint, e.g. if you are using a region-specific endpoint, put its full URL here */
53+
webSocket: /* optional: true if you want to use WebSocket to receive messages. Currently defaults to false. */,
54+
});
8155

82-
#### Embedded via IFRAME
56+
### Post activities to the bot:
8357

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.
58+
directLine.postActivity({
59+
from: { id: 'myUserId', name: 'myUserName' }, // required (from.name is optional)
60+
type: 'message',
61+
text: 'a message for you, Rudy'
62+
}).subscribe(
63+
id => console.log("Posted activity, assigned ID ", id),
64+
error => console.log("Error posting activity", error)
65+
);
8566

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
67+
You can also post messages with attachments, and non-message activities such as events, by supplying the appropriate fields in the activity.
9068

91-
(An example of this approach is [botchattest](https://github.com/billba/botchattest))
69+
### Listen to activities sent from the bot:
9270

93-
#### Inline in your non-React website
71+
directLine.activity$
72+
.subscribe(
73+
activity => console.log("received activity ", activity)
74+
);
9475

95-
In this scenario you will include a JavaScript file which embeds its own copy of React, which will run in a DOM element.
76+
You can use RxJS operators on incoming activities. To see only message activities:
9677

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).
78+
directLine.activity$
79+
.filter(activity => activity.type === 'message')
80+
.subscribe(
81+
message => console.log("received message ", message)
82+
);
10483

105-
#### Inline in your React website
84+
Direct Line will helpfully send your client a copy of every sent activity, so a common pattern is to filter incoming messages on `from`:
10685

107-
In this scenario you will incorporate WebChat's multiple JavaScript files into your React webapp.
86+
directLine.activity$
87+
.filter(activity => activity.type === 'message' && activity.from.id !== 'yourBotHandle')
88+
.subscribe(
89+
message => console.log("received message ", message)
90+
);
10891

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).
92+
### Monitor connection status
11693

117-
## Misc. notes
94+
Subscribing to either `postActivity` or `activity$` will start the process of connecting to the bot. Your app can monitor the current connection status and react appropriately :
11895

119-
### To see WebChat logging
96+
directLine.connectionStatus$
97+
.subscribe(connectionStatus =>
98+
switch(connectionStatus) {
99+
case ConnectionStatus.Uninitialized: // the status when the DirectLine object is first created/constructed
100+
case ConnectionStatus.Connecting: // currently trying to connect to the conversation
101+
case ConnectionStatus.Online: // successfully connected to the converstaion. Connection is healthy so far as we know.
102+
case ConnectionStatus.ExpiredToken: // last operation errored out with an expired token. Your app should supply a new one.
103+
case ConnectionStatus.FailedToConnect: // the initial attempt to connect to the conversation failed. No recovery possible.
104+
case ConnectionStatus.Ended: // the bot ended the conversation
105+
}
106+
);
120107

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
108+
### Reconnecting to a conversation
123109

124-
### To add localized strings
110+
If your app created your DirectLine object by passing a token, DirectLine will refresh that token every 15 minutes.
111+
Should your client lose connectivity (e.g. close laptop, fail to pay Internet access bill, go under a tunnel), `connectionStatus$`
112+
will change to `ConnectionStatus.ExpiredToken`. Your app can request a new token from its server, which should call
113+
the [Reconnect](https://docs.botframework.com/en-us/restapi/directline3/#reconnecting-to-a-conversation) API.
114+
The resultant Conversation object can then be passed by the app to DirectLine:
125115

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)!
116+
var conversation = /* a Conversation object obtained from your app's server */;
117+
directLine.reconnect(conversation);
131118

132119
## Copyright & License
133120

134-
© 2016 Microsoft Corporation
121+
© 2017 Microsoft Corporation
135122

136123
[MIT License](/LICENSE)

‎directLine.d.ts‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -178,7 +178,14 @@ export interface Message extends IActivity {
178178
export interface Typing extends IActivity {
179179
type: "typing";
180180
}
181-
export declare type Activity = Message | Typing;
181+
export interface EventActivity extends IActivity {
182+
name: string,
183+
value: any
184+
}
185+
export type Activity = Message | Typing | EventActivity;
186+
187+
// These types are specific to this client library, not to Direct Line 3.0
188+
182189
export declare enum ConnectionStatus {
183190
Uninitialized = 0,
184191
Connecting = 1,

‎package.json‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,6 @@
1111
"webpack-watch": "webpack -w",
1212
"clean": "rm -rf built",
1313
"prepublish": "tsc && webpack --config webpack.production.config.js",
14-
"start": "http-server -p 8000",
1514
"test": "mocha test"
1615
},
1716
"repository": {

‎samples/index.html‎

Lines changed: 0 additions & 70 deletions
This file was deleted.

‎src/directLine.ts‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -192,7 +192,13 @@ export interface Typing extends IActivity {
192192
type: "typing"
193193
}
194194

195-
export type Activity = Message | Typing;
195+
export interface EventActivity extends IActivity {
196+
type: 'event',
197+
name: string,
198+
value: any
199+
}
200+
201+
export type Activity = Message | Typing | EventActivity;
196202

197203
interface ActivityGroup {
198204
activities: Activity[],

0 commit comments

Comments
 (0)