|
| 1 | +## Chatdown |
| 2 | +Chatdown is a transcript generator which consumes a .chat file to generate mock transcripts. Generated mock transcript files are output to stdout. |
| 3 | + |
| 4 | +A good bot, just like any successful application or a website, starts with clarity on supported scenarios. Creating mockups of conversations between bot and user is useful for: |
| 5 | +- Framing the scenarios supported by the bot. |
| 6 | +- Business decision makers to review, provide feedback. |
| 7 | +- Defining a "happy path" (as well as other paths) through conversational flows between a user and a bot |
| 8 | + |
| 9 | +`.chat` file format helps you create mockups of conversations between a user and a bot. Chatdown CLI tool converts `.chat` files into conversation transcripts (`.transcript` files) that can be viewed in the Bot Framework Emulator. |
| 10 | + |
| 11 | +## .chat File Format |
| 12 | + |
| 13 | +Here's an example `.chat` file: |
| 14 | + |
| 15 | +```markdown |
| 16 | +user=Joe |
| 17 | +bot=LulaBot |
| 18 | + |
| 19 | +bot: Hi! |
| 20 | +user: yo! |
| 21 | +bot: [Typing][Delay=3000] |
| 22 | +Greetings! |
| 23 | +What would you like to do? |
| 24 | +* update - You can update your account |
| 25 | +* List - You can list your data |
| 26 | +* help - you can get help |
| 27 | + |
| 28 | +user: I need the bot framework logo. |
| 29 | + |
| 30 | +bot: |
| 31 | +Here you go. |
| 32 | +[Attachment=bot-framework.png] |
| 33 | +[Attachment=http://yahoo.com/bot-framework.png] |
| 34 | +[AttachmentLayout=carousel] |
| 35 | + |
| 36 | +user: thanks |
| 37 | +bot: |
| 38 | +Here's a form for you |
| 39 | +[Attachment=card.json adaptivecard] |
| 40 | + |
| 41 | +``` |
| 42 | + |
| 43 | +> See the [Examples](https://github.com/microsoft/botframework-cli/tree/master/packages/chatdown/docs/examples) folder for more samples. |
| 44 | +
|
| 45 | + |
| 46 | +Chat files are markdown files that contain 2 parts: |
| 47 | +- Header that defines who the participants are in the conversation |
| 48 | +- Back and forth conversation between a user and a bot |
| 49 | + |
| 50 | +### Header |
| 51 | +The header defines who the participants are in the conversation and defines other options. |
| 52 | + |
| 53 | +|Option |Description| |
| 54 | +|---------------------|------------------------------| |
| 55 | +|`user=<user>` |This option tells chatdown that a user message will begin with `<user>` followed by a colon. For example, `user=Joe` instructs chatdown that lines beginning with `Joe:` or `user:` are the start of a message from the user Joe. | |
| 56 | +|`users=<user1>,<user2>,<user3>` |This option tells chatdown that there are multiple users in the conversation. | |
| 57 | +|`bot=<bot>` | This options tells chatdown that a bot message will begin with `<bot>` followed by a colon. For example, `bot=LulaBot` instructs chadown that lines beginning with `LulaBot:` or `bot:` are the start of a message from the bot Lulabot. | |
| 58 | +| `channelId=<channelID>`| This option tells chatdown to use the specified `channelID` for each activity.| |
| 59 | + |
| 60 | +Once the configuration options for `users` and `bot` are defined, the rest of the conversation can use the alias prefixes `user:` and `bot:` or the names directly. Chatdown will correctly make the associations to the specified names for you. |
| 61 | + |
| 62 | +> The Bot will default to sending to the first user in the users list or the last user it received a message from, unless you directly specify a target user by using the bot->user: syntax. |
| 63 | +
|
| 64 | +For example: |
| 65 | +```markdown |
| 66 | +users=Joe,Fred |
| 67 | + |
| 68 | +bot: This will go to Joe, because he's first in the list |
| 69 | +Fred: What about me? |
| 70 | +bot: This will go to Fred, because he's the latest user to talk to the bot |
| 71 | +bot->Joe: This will always go to Joe |
| 72 | +bot->Fred: This will always go to Fred |
| 73 | +``` |
| 74 | + |
| 75 | +### Conversation |
| 76 | +The conversation between the user and the bot with markdown support for bot's responses. Every time a `user:` or `bot:` is found at the beginning of the line, a new activity will be inserted into the transcript. Inside the markdown, you can insert commands to generate richer transcripts: |
| 77 | + |
| 78 | +### Activity commands |
| 79 | +| Command | Description | |
| 80 | +| --------------- | ------------------------------------------------------------ | |
| 81 | +|`[Typing]` | Inserts a typing activity into the transcript to signify that a user or a bot is typing. | |
| 82 | +|`[Delay=<milliseconds>]` | Delays the transcript by `<milliseconds>`. | |
| 83 | +|`[ConversationUpdate=]` | Sends a conversationUpdate, with membersAdded= and membersRemoved= values| |
| 84 | + |
| 85 | +Example ConversationUpdate message |
| 86 | +```markdown |
| 87 | +[ConversationUpdate= |
| 88 | + MembersAdded=Joe,Susan] |
| 89 | +bot->Joe: Hi Joe! |
| 90 | +bot->Susan: Hi Susan! |
| 91 | +``` |
| 92 | + |
| 93 | +### Message commands |
| 94 | +When sending a message there are a number of commands for controlling layout. |
| 95 | + |
| 96 | +|Command | Description | |
| 97 | +|------------------|-----------------------------------------------------------| |
| 98 | +|<code>[Suggestions=<Option 1>|<Option 2>|<Option 3>]</code> | Add suggested action buttons, delimited by <code>|</code> | |
| 99 | +|`[AttachmentLayout=LayoutType]`| Specify how multiple attachments would be displayed. Layout types are `carousel` or `list`| |
| 100 | + |
| 101 | + |
| 102 | +#### Message Cards |
| 103 | +You can add cards using simple commands as well. Currently we support a number of cards: |
| 104 | + |
| 105 | +| description | card name | |
| 106 | +| ----------- | ------------------------------------------------------------ | |
| 107 | +| HeroCard | A simple card with single large image, title, subtitle, text and buttons | |
| 108 | +| ThumbnailCard | Same as herocard, but image is much smaller | |
| 109 | +| AudioCard | send audio card for playing back an audio url | |
| 110 | +| VideoCard | send an video player card for playing back a video file | |
| 111 | +| AnimationCard | send a animated gif card | |
| 112 | +| MediaCard | send arbitrary media with transport control | |
| 113 | +| SigninCard | send a signin card | |
| 114 | +| OauthCard | send an oauth card which uses azure bot service oauth flow |
| 115 | + |
| 116 | +```markdown |
| 117 | +Bot: |
| 118 | +[Herocard |
| 119 | + title=Cheese gromit! |
| 120 | + subtitle=Hero Card |
| 121 | + text=This is some text describing the card, it's cool because it's cool |
| 122 | + image=https://memegenerator.net/img/instances/500x/73055378/cheese-gromit.jpg |
| 123 | + buttons=Option 1| Option 2| Option 3] |
| 124 | + |
| 125 | +Bot: |
| 126 | +[ThumbnailCard |
| 127 | + title=Cheese gromit! |
| 128 | + subtitle=Thumbnail Card |
| 129 | + text=This is some text describing the card, it's cool because it's cool |
| 130 | + image=https://memegenerator.net/img/instances/500x/73055378/cheese-gromit.jpg |
| 131 | + buttons=Option 1| Option 2| Option 3] |
| 132 | +``` |
| 133 | +The properties that are supported are |
| 134 | + |
| 135 | +| property | description | |
| 136 | +|----|----| |
| 137 | +| title | The title of the card| |
| 138 | +| subtitle| a subtitle for the card with less emphasis| |
| 139 | +| text | a generic text property which can contain longer text describing the card| |
| 140 | +| image | image url to use for the card | |
| 141 | +| buttons | a set of button labels separated by `|`| |
| 142 | + |
| 143 | + |
| 144 | +#### Message Attachments |
| 145 | +To add an attachment, you use `[Attachment=path contentPath]`. The path can be a URL or a local path (either absolute or relative to `.chat` file). The content type is optional and if not passed, will be inferred from the file extension. You can also pass it using a shortcut or full mime type. |
| 146 | + |
| 147 | +```markdown |
| 148 | +[Attachment=path contentType] |
| 149 | +``` |
| 150 | + |
| 151 | +The following examples illustrates sending a carousel of photos: |
| 152 | +```markdown |
| 153 | +Enjoy these pictures! |
| 154 | +[AttachmentLayout=carousel] |
| 155 | +[Attachment=http://4.bp.blogspot.com/--cFa6t-x4qY/UAqEgUvPd2I/AAAAAAAANIg/pMLE080Zjh4/s1600/turtle.jpg] |
| 156 | +[Attachment=http://viagemempauta.com.br/wp-content/uploads/2015/09/2_All-Angle-By-Andreza-dos-Santos_FTS_2914-344-620x415.jpg] |
| 157 | +[Attachment=http://images.fineartamerica.com/images-medium-large/good-morning-turtles-freund-gloria.jpg] |
| 158 | +[Attachment=http://4.bp.blogspot.com/--cFa6t-x4qY/UAqEgUvPd2I/AAAAAAAANIg/pMLE080Zjh4/s1600/turtle.jpg] |
| 159 | +[Attachment=image.png] |
| 160 | +``` |
| 161 | + |
| 162 | +This example sends a local adaptive card using a content type shortcut: |
| 163 | +```markdown |
| 164 | +[Attachment=folder/sample.json "adaptivecard"] |
| 165 | +``` |
| 166 | + |
| 167 | +#### Attachment content type shortcuts |
| 168 | +Some of the content types have shortcuts: |
| 169 | + |
| 170 | +| ContentType Shortcuts | Description | |
| 171 | +| ----------------------|--------------------------------------------| |
| 172 | +| animation | `application/vnd.microsoft.card.animation` | |
| 173 | +| audio | `application/vnd.microsoft.card.audio` | |
| 174 | +| hero | `application/vnd.microsoft.card.hero` | |
| 175 | +| receipt | `application/vnd.microsoft.card.receipt` | |
| 176 | +| thumbnail | `application/vnd.microsoft.card.thumbnail` | |
| 177 | +| signin | `application/vnd.microsoft.card.signin` | |
| 178 | +| video | `application/vnd.microsoft.card.video` | |
| 179 | +| adaptivecard | `application/vnd.microsoft.card.adaptive` | |
| 180 | +| *application/custom* | `application/custom` | |
| 181 | + |
| 182 | + |
| 183 | + |
| 184 | +## CLI Examples |
| 185 | + |
| 186 | +### Basic usage |
| 187 | +In the simplest form, a chatdown command looks like the following: |
| 188 | +```bash |
| 189 | +bf chatdown:convert --in sample.chat > sample.transcript |
| 190 | +``` |
| 191 | +This will consume `sample.chat` and output `sample.transcript`. |
| 192 | + |
| 193 | +### Using stdin |
| 194 | +stdin can be used as an alternative to specifying an input file. |
| 195 | +```bash |
| 196 | +(echo user=Joe && echo bot=LulaBot && echo Joe: 'Hi!' && echo LulaBot: 'Hi there!') | bf chatdown:convert > sample.transcript |
| 197 | +``` |
| 198 | + |
| 199 | +### Using stdout |
| 200 | +stdout can be used as an alternative to specifying the output file. |
| 201 | +```bash |
| 202 | +bf chatdown:convert --in sample.chat |
| 203 | +``` |
| 204 | +or |
| 205 | +```bash |
| 206 | +bf chatdown:convert sample.chat > joe.transcript |
| 207 | +``` |
| 208 | +The transcript will be piped to stdout. |
| 209 | + |
| 210 | +### As a library |
| 211 | +Chatdown can be used within a Node.js application as an imported library. |
| 212 | +Install locally: |
| 213 | +```bash |
| 214 | +npm i -s @microsoft/bf-chatdown |
| 215 | +``` |
| 216 | +In your node project: |
| 217 | +```js |
| 218 | +const chatdown = require('chatdown'); |
| 219 | +const conversation = ` |
| 220 | + user=Joe |
| 221 | + bot=LulaBot |
| 222 | + user: Hello! |
| 223 | + bot: Hello, can I help you? |
| 224 | + user: I need an image |
| 225 | + bot: here you go! [Attachments:bot-framework.png] |
| 226 | +`; |
| 227 | +chatdown(conversation, config) |
| 228 | + .then(activities => { |
| 229 | + // do stuff with the resulting activities. |
| 230 | + }) |
| 231 | + .catch(e =>{ |
| 232 | + // oops! Something went wrong |
| 233 | + }); |
| 234 | +``` |
| 235 | + |
| 236 | +## Processing multiple Chatdown files |
| 237 | + |
| 238 | +If you are dealing strictly with files, and not standard input/output, you can process all Chatdown files at once: |
| 239 | + |
| 240 | +```bash |
| 241 | +chatdown -i **/*.chat -o ./transcripts |
| 242 | +``` |
| 243 | + |
| 244 | +The above command will process all `*.chat` files in the current directory and all subdirectories, and put the output in the "transcripts" folder of the current directory. If an output directory is not present, it will default to the current working directory. |
| 245 | + |
| 246 | +## Setting up a watcher to automatically transcribe chat files |
| 247 | +Chokidar-cli is a great utility to do this. |
| 248 | + |
| 249 | +To install: |
| 250 | +```bash |
| 251 | +npm install -g chokidar-cli |
| 252 | +``` |
| 253 | + |
| 254 | +To run as a watcher: |
| 255 | +```bash |
| 256 | +chokidar "**/*.chat" -c "bf chatdown:convert --in {path} > {path}.transcript" |
| 257 | +``` |
| 258 | + |
| 259 | +Now, any time a .chat file is created or saved, chatdown will automatically create the transcript file beside it. |
0 commit comments