├── LICENSE
├── README.md
├── docs
├── conversation.js
├── index.html
├── main.css
├── peekobot.css
└── peekobot.js
├── images
└── noun_chatbot_1585775.svg
├── peekobot.css
└── peekobot.js
/LICENSE:
--------------------------------------------------------------------------------
1 | MIT License
2 |
3 | Copyright (c) 2019 Peekobot
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:
--------------------------------------------------------------------------------
1 | # Peekobot
2 |
3 | Peekobot is a simple, choice-driven chatbot framework for your website written in ~~less
4 | than~~ just over 100 lines of ES6 vanilla JavaScript (and some CSS).
5 |
6 | There is an [example bot](https://peekobot.github.io/peekobot/) you can see in the [`/docs`](/docs) folder.
7 |
8 | There is also a [CodePen](https://codepen.io/magicroundabout/pen/RwwXxoo) you can tinker with.
9 |
10 | ## Features
11 |
12 | * Small, simple, zero dependencies (unless you need old browser compatibility)
13 | * Define your conversation as a simple JavaScript object
14 | * Choice/button driven conversations
15 | * Options to link to URLs as well as other parts of the conversation
16 |
17 | ## Browser Compatibility
18 |
19 | I use async/await and CSS custom properties, so, broadly speaking, Internet Explorer
20 | and Opera Mini are not supported.
21 |
22 | You can use Babel or similar to bring IE11 compatibility to the JavaScript.
23 |
24 | You can also manually inline the CSS custom properties if you want to.
25 |
26 | ## Usage
27 |
28 | Peekobot is not a package or library. You can't `npm install` it. Think of it as a starter kit or framework. The idea is that you take a copy of it and do your own thing with it.
29 |
30 | If you do use it, please [drop me a line](https://twitter.com/magicroundabout/) and show me what you made! I'd love to see what others are doing with it. Thanks! 🙌
31 |
32 | To use Peekobot, you need to:
33 |
34 | 1. Add Peekobot scripts and styles to your HTML
35 | 2. Add Peekobot markup to your HTML
36 | 3. Define your conversation
37 |
38 | ### 1. Add Peekobot scripts and styles to your HTML
39 |
40 | Download the [`peekobot.js`](peekobot.js) and [`peekobot.css`](peekobot.css) files into your project.
41 |
42 | You can do this by grabbing the raw code for these files from GitHub or by cloning the
43 | project.
44 |
45 | Then add the Peekobot scripts and styles to your HTML.
46 |
47 | These should go in the `head`:
48 |
49 | ```html
50 |
51 |
57 |
58 |
59 | ```
60 |
61 | Note that you can change the height of the chatbot window here and define an "avatar"
62 | URL to be used in the chat by your chatbot. This should be small, square and fit within a
63 | circle shape. My CSS displays at 24px square, so a 48px x 48px image should be fine.
64 |
65 | These should go at the bottom of your HTML to load the JavaScript:
66 |
67 | ```html
68 |
69 |
70 | ```
71 |
72 | ### 2. Add Peekobot markup to your HTML body
73 |
74 | Add the Peekobot markup to your HTML body where you want the chatbot to appear:
75 |
76 | ```html
77 |
78 |
79 |
80 |
81 |
82 |
83 | ```
84 |
85 | ### 3. Define your conversation
86 |
87 | The conversation definition should be placed in a JavaScript variable called `chat`.
88 | I define this in the `conversation.js` file. You can inline it if you want to.
89 |
90 | The `chat` variable should be an object. In the chat object:
91 |
92 | * the first property name/key should be the number 1
93 | * subsequent property names can be numbers or strings - strings allow you to group parts of your conversation
94 | * each property value is an entry in the conversation.
95 |
96 | A conversation entry should have:
97 |
98 | - A `text` property that is what the chatbot says at this point in the conversation
99 | - Either:
100 | - A `next` property, which defines the next chat entry by stating a numerical key
101 | of the chat object and is used when the chatbot needs to say several things
102 | in turn without input from the user
103 | OR
104 | - An `options` property that defines the choices a user can take. This is an
105 | array of option objects.
106 |
107 | An options object should have:
108 |
109 | - a `text` property that is the label for the user's choice
110 | AND EITHER
111 | - a `next` property that defines the next chat entry by stating a property key of
112 | the chat object and is used when the user selects this option
113 | OR
114 | - a `url` property that defines a link for the user to be taken to
115 |
116 | A simple example chat object is:
117 |
118 | ```js
119 | const chat = {
120 | 1: {
121 | text: 'Good morning sir',
122 | next: 'question1'
123 | },
124 | question1: {
125 | text: 'Would you like tea or coffee with your breakfast?',
126 | options: [
127 | {
128 | text: 'Tea',
129 | next: 'response1'
130 | },
131 | {
132 | text: 'Coffee',
133 | next: 'response2'
134 | }
135 | ]
136 | },
137 | response1: {
138 | text: 'Splendid - a fine drink if I do say so myself.'
139 | },
140 | response2: {
141 | text: 'As you wish, sir'
142 | }
143 | }
144 | ```
145 |
146 | ## Ensure utf-8
147 |
148 | To use emoji's and other extended characters it's a good idea to ensure you are specifying UTF-8.
149 |
150 | You are probably doing this anyway, or maybe your web server or CMS is doing this for you. But if not it's worth
151 | making sure you have the correct `meta` tag in your ``:
152 |
153 | ```html
154 |
155 | ```
156 |
157 | ## Disclaimers
158 |
159 | This is my first proper open source project. It's kinda neat, and it works, but it's
160 | probably not finished. My main concerns are
161 |
162 | * Accessibility: I've not really looked at accessibility of this code. It probably needs some work
163 | * Security - it's entirely possible that some script could hijack the bot's script code.
164 |
165 | Let me know if you have ideas about how to fix these things by raising an issue.
166 |
167 | ## Peeko-what?
168 |
169 | I released this in a bit of a hurry and needed a name. It's a mash-up of:
170 |
171 | * picobot
172 | * peek-a-boo
173 |
174 | and I mostly chose it becase all the other "small bot" names, such as picobot, nanobot, etc were taken. It kinda works.
175 |
176 | ## Buy me a coffee
177 |
178 | If you like Peekobot, or if it's helped you in some way, feel free to [buy me a coffee](https://ko-fi.com/magicroundabout).
179 |
180 | ## Credits/Contributors
181 |
182 | * [Jesper Johansson](https://github.com/JeppeJ)
183 |
--------------------------------------------------------------------------------
/docs/conversation.js:
--------------------------------------------------------------------------------
1 | /* The chat const defines the Peekobot conversation.
2 | *
3 | * It should be an object with numerical property names, and each property is an entry
4 | * in the conversation.
5 | *
6 | * A conversation entry should have:
7 | * - A "text" property that is what the chatbot says at this point in the conversation
8 | * - Either:
9 | * - A "next" property, which defines the next chat entry by stating a numerical key
10 | * of the chat object and is used when the chatbot needs to say several things
11 | * without input from the user
12 | * OR
13 | * - An "options" property that defines the choices a user can take this is an
14 | * array of option objects
15 | *
16 | * An options object should have:
17 | * - a "text" property that is the label for the user's choice
18 | * AND EITHER
19 | * - a "next" property that defines the next chat entry by stating a numerical key of
20 | * the chat object and is used when the user selects this option
21 | * OR
22 | * - a "url" property that defines a link for the user to be taken to
23 | *
24 | * A simple example chat object is:
25 | * const chat = {
26 | * 1: {
27 | * text: 'Good morning sir',
28 | * next: 2
29 | * },
30 | * 2: {
31 | * text: 'Would you like tea or coffee with your breakfast?',
32 | * options: [
33 | * {
34 | * text: 'Tea',
35 | * next: 3
36 | * },
37 | * {
38 | * text: 'Coffee',
39 | * next: 4
40 | * }
41 | * ]
42 | * },
43 | * 3: {
44 | * text: 'Splendid - a fine drink if I do say so myself.'
45 | * },
46 | * 4: {
47 | * text: 'As you wish, sir'
48 | * }
49 | * }
50 | */
51 | const chat = {
52 | 1: {
53 | text: 'Hi! Welcome to Peekobot.',
54 | options: [
55 | {
56 | text: '👋',
57 | next: 2
58 | }
59 | ]
60 | },
61 | 2: {
62 | text: 'Peekobot is a really simple, choice-driven chatbot framework made in less than just over 100 lines of vanilla JavaScript',
63 | next: 3
64 | },
65 | 3: {
66 | text: 'But you probably knew that anyway.',
67 | options: [
68 | {
69 | text: "Yes, I did!",
70 | next: 4
71 | },
72 | {
73 | text: "Nope, this is news.",
74 | next: 5
75 | }
76 | ]
77 | },
78 | 4: {
79 | text: 'Awesome. This chat is still in development. Happy coding!',
80 | },
81 | 5: {
82 | text: 'Aah, you\'re missing out!',
83 | next: 6
84 | },
85 | 6: {
86 | text: 'You should check it out on GitHub',
87 | options: [
88 | {
89 | text: "Go to GitHub",
90 | url: "https://github.com/peekobot/peekobot"
91 | }
92 | ]
93 | }
94 | };
95 |
--------------------------------------------------------------------------------
/docs/index.html:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 |
6 | Peekobot
7 |
8 |
9 |
10 |
11 |
12 |
13 |
14 |
15 |
16 |
22 |
23 |
24 |
25 |
26 |
27 |
28 |
29 |
30 |
31 |
32 |
33 |
Peekobot
34 |
35 | Peekobot is a simple choice-driven chatbot framework in less than just over 100 lines of vanilla JS
36 |
37 |
38 | I'm made by Ross Wintle and
39 | you can find me on GitHub
40 |
41 |
Icon credit: "chat bot" by GJR from the Noun Project