add documentation (#187)

README.md

@@ -4,10 +4,9 @@
 
 
 AI Chatbot Framework is an open-source, self-hosted, DIY Chatbot building platform built in Python. With this tool, it’s easy to create Natural Language conversational scenarios with no coding efforts whatsoever. 
-The smooth UI makes it effortless to create and train conversations to the bot. AI Chatbot Framework can live on any channel of your choice (such as Messenger, Slack etc.) by integrating it’s API with that platform.
-
-You don’t need to be an expert at artificial intelligence to create an awesome chatbot that has AI capabilities. With this project you can create an AI powered chatting machine in no time. 
+The smooth UI makes it effortless to create and train conversations to the bot. AI Chatbot Framework can live on any channel of your choice (such as Messenger, Slack etc.).
 
+You don’t need to be an expert at artificial intelligence to create an awesome chatbot that has AI capabilities. With this project you can create an AI powered chatbot in no time.  Read the [getting started guide](docs/01-getting-started.md) to get started.
 
 ![](docs/screenshots/admin_chat_screenshot.png)
 

docs/01-getting-started.md

@@ -0,0 +1,33 @@
+# Getting started
+
+## Understanding Key Concepts
+
+### Intents
+
+Intents are the building blocks of your chatbot's understanding - they define what your bot can recognize and how it should respond. An intent represents a specific action or request that users might make.
+
+For example, when a user asks "What's the weather like today?", the intent would be "check_weather".
+
+### Entities
+
+Entities are specific pieces of information that you want to extract from user messages. For example, in the message "Book a table for 4 people at 7 PM", "4" (number of people) and "7 PM" (time) are entities.
+
+### Channels
+
+Channels are the platforms where your chatbot can be accessed. They can be web, or social media platforms like Facebook Messenger.
+
+## Admin Panel
+
+The admin panel serves as the central hub for managing your chatbot. You can use it for following:
+
+- Configure and manage intents
+- Create and edit entities
+- Train your chatbot
+- Test conversations in real-time
+- Monitor conversation logs
+- Manage Channel integrations
+
+Access the admin panel at [http://localhost:3000](http://localhost:3000) after starting the application.
+
+## Next Steps
+- [Create your first intent](02-creating-order-status-check.md)

docs/02-creating-order-status-check.md

@@ -0,0 +1,115 @@
+# Creating Order Status Check Bot
+
+This guide walks you through creating a practical example of implementing order status check functionality in your chatbot.
+
+For a quick start, you can find a pre-configured bot in the [examples folder](../examples/order_status.json). Import it through Settings/Data Management, then train the model via the "Train Models" button in the Intents page. Once done, you can proceed directly to the [testing](#testing) section.
+
+## Configuration
+
+### 1. Create Order Number Entity
+
+1. Go to the Entities section
+2. Create a new entity named "order_number"
+
+### 2. Create the Intent
+
+1. Navigate to the Intents section in the admin interface
+2. Click "Create Intent"
+3. Configure the basic intent information:
+   - **Intent Name**: "Check Order Status"
+   - **Intent ID**: "check_order_status"
+
+#### Configure Parameters
+
+Add the following parameter:
+- **Name**: "order_number"
+- **Type**: Select your order number entity type
+- **Required**: Yes
+- **Prompt**: "Please provide your order number"
+
+[![intent_configuration_1.png](screenshots/intent_configuration_1.png)](screenshots/intent_configuration_1.png)
+
+### 3. Set Up API Integration
+
+We'll use a free dummy order status API for this example:
+
+```
+https://fake-store-api.mock.beeceptor.com/api/orders/status?order_id=ORD1234
+```
+
+Example API Response:
+```json
+{
+  "order_id": 1,
+  "user_id": 1,
+  "status": "Shipped",
+  "total_price": 849.97,
+  "items": [ { "product_id": 1, "quantity": 2 }, { "product_id": 3, "quantity": 1 } ]
+}
+```
+
+Configuration steps:
+1. Enable "Trigger API"
+2. Add the API URL with parameter templating:
+   ```
+   https://fake-store-api.mock.beeceptor.com/api/orders/status?order_id={{ parameters['name'] }}
+   ```
+3. Choose method as GET
+4. Leave the headers and JSON payload configurations as default
+
+[![API Trigger](screenshots/intent_configuration_api_trigger.png)](screenshots/intent_configuration_api_trigger.png)
+
+### 4. Configure Response Template
+
+In the response section of the intent, customize the response using the API result:
+```
+Your order status is {{ result['status'] }}
+```
+
+## Training
+
+### 1. Add Training Phrases
+
+1. Go to Intents Page and click on the training icon
+   [![Training](screenshots/training_icon.png)](screenshots/training_icon.png)
+
+2. Add the following example phrases:
+   - Tell me order status
+   - What's the status of my order ORD123456?
+   - Track order ORDER789012
+   - Where is my order ORD123456?
+   - Can you check order ORD789012 for me?
+   - I want to know about order ORD123456
+   - What is my order status
+
+### 2. Label Entities
+
+1. In each training phrase, highlight the order numbers
+2. Select the "order_number" entity type
+3. Ensure all variations are properly labeled
+
+[![Entity Labeling](screenshots/training_entity_label.png)](screenshots/training_entity_label.png)
+
+### 3. Train the Model
+
+1. Return to the Intents Page
+2. Click "Train Models"
+3. Wait for training completion
+4. Test the intent with sample queries
+
+## Testing
+
+1. Navigate to the Chat Page
+2. Test with different variations:
+   - "What is my order status?"
+   - "Track my order ORD123456"
+   - "Where is ORDER789012?"
+3. Verify the following:
+   - Intent is correctly identified
+   - Order number is properly extracted
+   - API is triggered with correct parameters
+
+[![Testing](screenshots/testing.png)](screenshots/testing.png)
+
+## Next Steps
+- [Integrate with other channels](03-integrating-with-channels.md)

docs/03-integrating-with-channels.md

@@ -0,0 +1,85 @@
+# Integrating with Channels
+
+This guide explains how to integrate your chatbot with different communication channels to make it accessible to your users.
+
+## Chat Widget
+
+### Setting Up the Widget
+1. Navigate to the Integrations section under Settings
+2. Enable the chat widget integration
+3. Configure widget settings:
+   - Set base URL (`iky_base_url`)
+   - Add custom context (`chat_context`)
+
+### Implementation
+1. Copy the widget code snippet
+2. Paste it into your website's HTML:
+   ```html
+   <html>
+    <head>...</head>
+   <body>
+    ...
+   </body>
+    <script type="text/javascript">
+    !function(win,doc){"use strict";var script_loader=()=>{try
+    {var head=doc.head||doc.getElementsByTagName("head")[0],script=doc.createElement("script");script.setAttribute("type","text/javascript"),script.setAttribute("src","https://alfredfrancis.in/ai-chatbot-framework/app/static/widget/script.js"),head.appendChild(script)}
+    catch(e){}};win.chat_context={"username":"John"},win.iky_base_url="http://localhost:8080/admin/",script_loader()}(window,document);
+    </script>
+    </html>
+   ```
+
+## REST API
+
+### Authentication
+1. Generate an API key from the admin dashboard
+2. Include the key in your API requests:
+   ```
+   Authorization: Bearer YOUR_API_KEY
+   ```
+
+### Making Requests
+- Endpoint: `POST /api/chat`
+- Request format:
+  ```json
+  {
+    "thread_id":"123456",
+    "text": "hello world",
+    "context": {
+      "Name": "Alfred",
+      // additional context data
+    }
+  }
+  ```
+- Response Format:
+  ```json
+  [{"text":"Hello Alfred 👋 "},{"text":" What can i do for you ?"}]
+  ```
+
+Sample cURL request:
+```sh
+curl 'http://localhost:8080/bots/channels/rest/webbook' \
+  -H 'Content-Type: application/json' \
+  --data-raw '{"thread_id":"test-user","text":"/init_conversation","context":{"username":"Admin"}}'
+```
+
+## Facebook Messenger
+
+### Prerequisites
+- Facebook Developer Account
+- Facebook Page for your chatbot
+
+### Configuration Steps
+1. Create a Facebook App
+2. Enable Messenger integration
+3. In your chatbot admin panel:
+   - Enable Facebook integration
+   - Configure webhook URL
+   - Set up authentication:
+     - Verify token
+     - App secret
+     - Page access token
+
+### Testing the Integration
+1. Send a test message to your Facebook Page
+2. Verify the chatbot responds correctly
+3. Check webhook events in the Facebook Developer Console

docs/README.md

@@ -1 +1,19 @@
-# Docs
+# AI Chatbot Framework Documentation
+
+Welcome to the AI Chatbot Framework documentation. This documentation provides comprehensive guidance on setting up, developing, and deploying your chatbot.
+
+## Table of Contents
+
+1. [Getting Started](01-getting-started.md)
+   - [Understanding Key Concepts](01-getting-started.md#understanding-key-concepts)
+   - [Admin Panel](01-getting-started.md#admin-panel)
+
+2. [Creating Order Status Check Bot](02-creating-order-status-check.md)
+   - [Configuration](02-creating-order-status-check.md#configuration)
+   - [Training the Intent and Entities](02-creating-order-status-check.md#training)
+   - [Testing](02-creating-order-status-check.md#testing)
+
+3. [Integrating with Channels](03-integrating-with-channels.md)
+   - [Chat Widget](03-integrating-with-channels.md#chat-widget)
+   - [REST API](03-integrating-with-channels.md#rest-api)
+   - [Facebook Messenger](03-integrating-with-channels.md#facebook-messenger)

examples/order_status.json

@@ -0,0 +1 @@
+{"intents": [{"name": "Default Fallback intent", "userDefined": false, "intentId": "fallback", "apiTrigger": false, "apiDetails": null, "speechResponse": "{{ \n\n[\n    \"Sorry ### I'm having trouble understanding you.\",\n    \"Hmm ### I cant handle that yet.\",\n    \"Can you please re-phrase your query ?\"\n] | random \n\n}}\ufeff\n\n", "parameters": [], "labeledSentences": [], "trainingData": []}, {"name": "cancel", "userDefined": false, "intentId": "cancel", "apiTrigger": false, "apiDetails": null, "speechResponse": "Ok. Canceled.", "parameters": [], "labeledSentences": [], "trainingData": [{"text": "i want to cancel", "entities": []}, {"text": "cancel that", "entities": []}, {"text": "cancel", "entities": []}]}, {"name": "Welcome message", "userDefined": false, "intentId": "init_conversation", "apiTrigger": false, "apiDetails": null, "speechResponse": "Hi {{context[\"username\"] }} ### What can i do for you ?", "parameters": [], "labeledSentences": [], "trainingData": [{"text": "hello there", "entities": []}, {"text": "hey there", "entities": []}, {"text": "hii", "entities": []}, {"text": "heyy", "entities": []}, {"text": "howdy", "entities": []}, {"text": "hey", "entities": []}, {"text": "hello", "entities": []}, {"text": "hi", "entities": []}]}, {"name": "Check Order Status", "userDefined": true, "intentId": "check_order_status", "apiTrigger": true, "apiDetails": {"url": "https://fake-store-api.mock.beeceptor.com/api/orders/status?order_id={{ parameters['order_number'] }}", "requestType": "GET", "headers": [], "isJson": false, "jsonData": ""}, "speechResponse": "Your order status is {{ result['status'] }}", "parameters": [{"name": "order_number", "required": true, "type": "order_number", "prompt": "Please provide your order number"}], "labeledSentences": [], "trainingData": [{"text": "my order number is ORD113134", "entities": [{"value": "ORD113134", "begin": 19, "end": 28, "name": "order_number"}]}, {"text": "What is my order status", "entities": []}, {"text": "I want to know about order ORD123456", "entities": [{"value": "ORD123456", "begin": 27, "end": 36, "name": "order_number"}]}, {"text": "Can you check order ORD789012 for me ?", "entities": [{"value": "ORD789012", "begin": 20, "end": 29, "name": "order_number"}]}, {"text": "Where is my order ORD123456 ?", "entities": [{"value": "ORD123456", "begin": 18, "end": 27, "name": "order_number"}]}, {"text": "Track order ORDER789012", "entities": [{"value": "ORDER789012", "begin": 12, "end": 23, "name": "order_number"}]}, {"text": "What's the status of my order ORD123456 ?", "entities": [{"value": "ORD123456", "begin": 30, "end": 39, "name": "order_number"}]}, {"text": "Tell me order status", "entities": []}]}], "entities": [{"name": "order_number", "entity_values": []}]}