# Hello World Welcome to the BotDistrikt Documentation. This guide will help you automate your customer service processes through an intuitive AI chatbot regardless of your industry. ## What is BotDistrikt? What do you call a marketer's and developer's love child? 👶 **BotDistrikt** is a chatbot-building platform to help you set up workflow automation on messaging apps like Facebook Messenger, Instagram, WhatsApp, Telegram, and even your own website. Chatbots have a reputation for being little sidekicks to Customer Service agents. With BotDistrikt, the customer service function is just the tip of the iceberg. You will be able to replace apps and build entire marketplaces, recommendation engines, watchlists, and robotic community managers 🤖 ## Features ### ♻️ Nonlinear Chat Components Flow-builders are linear; They give chatbot owners a false impression of control over customer conversations. On BotDistrikt, your customers themselves *create* their own chat experiences with nonlinear components like **Rules** and **Stories.** ### **🙅‍♂️ No-Code Design** Marketers and Product Owners create lead-generation tools with **Forms**, search engines with **Cards**, and A/B tested drip campaigns with **Broadcasts** and so much more with absolutely no coding needed. ### 📥 In-built CRM Whether it's from your website, Telegram, or Instagram, you get a unified view of every chat from every customer using your chatbot in our Omni-channel **Inbox**. With attributes and tags, it's easier to create customer segments and provide highly personalized experiences at scale. ### 🕷 Low-Code Customization Developers can create fully integrated chat experiences by connecting to your in-house tech or third-party systems like Google Sheets, Airtable, and HubSpot with **Webhooks**. They can even write vanilla JavaScript **Functions** so your bot handles lookups and calculations. ### 🧰 Must-Have Marketing Tool Our bots take the guesswork out of customer interaction with multiple touchpoints. Customer segmentation lets you execute successful drip campaigns, and qualify leads - all with the power of effectively leveraged **Rules** and **Conditions.** ## Try it out! The best way to discover BotDistrikt is to try it out yourself. Our non-linear AI chatbots offer a more dynamic and context-aware approach to conversational AI. They provide personalized, engaging, and efficient interactions, making them valuable tools for all businesses, customer support, and user engagement across a variety of industries and use cases. Whether you are thinking of making a new bot from scratch or already have one in use, [**Contact Us**](https://botdistrikt.com/contact?purpose=demo) to get a demo and free trial account. No credit card required! If you already have a Bot on the platform, you can brush up on the platform navigation and some of our features [here](https://flow.botdistrikt.com/bots/722/rules#). ## Using the Manual * Use the Search function (CTRL/CMD + K) if you are looking for specific information. * Navigate through topics using the sidebar. ## # Quick Start Here is a quick guide on how can you get started on BotDistrikt ## Register an Account [Contact us](https://botdistrikt.com/contact) for a demo bot and we will set up your bot account with your registered email address. **Step 1: Go to the Register page** Click [this link](https://flow.botdistrikt.com/register) to register your account **Step 2: Select a Sign-Up method** You can sign up using your Google or Facebook account. Alternatively, you can choose to sign up using your work email and password. {% hint style="info" %} You may skip the following steps if you signed up with Google or Facebook. {% endhint %} **Step 3: Fill in the required information** Fill up your personal details like first name, last name, email, and password. Avoid using your same password from other websites! Finally, accept the terms and privacy policies.

Sign up to BotDistrikt

**Step 4: Submit** Click on **Register.** If there is no error, you should be prompted to check your email to activate your account. You should have received an email from BotDistrikt. Click on the link inside the email body to verify your registration. Successfully Signed Up **Step 5: Verify your email address** You should have received a verification email from BotDistrikt to complete the verification. Proceed to verify your email by clicking on the link in the email.

Verify your Email Address

{% hint style="info" %} If you don't see the email, check your spam or junk folder. Also check that you have entered the correct email address, request to resend the verification email. If you still do not receive the email within 10 minutes, do not hesitate to contact us at . {% endhint %} Click on the link to verify your account, The link will take you to a page saying that your email has been verified. After that, click on **Take Me To Login** and login to BotDistrikt. ## Create your bot Log in with your email on the BotDistrikt [login page](https://flow.botdistrikt.com/login). In the event that the BotDistrikt team has created a bot for you through your registered email ID, you can view your bot on the Chatbot dashboard upon logging in.

Sample Bot Dashboard with (Sample) Bot Created by BotDistrikt Team

## Try your Chatbot Click on your chatbot and you will be taken to the **Personality** page. This page allows you to get an overview of your bot's personality, its default greeting and fallback messages, the messaging apps it is already connected to, and your team managing its account. Click on the chatbot widget on the bottom right of the page, and click **Get Started**.
Type something your customer would say to your chatbot. By default, it will not be able to handle to message and reply with your bot's **fallback story**. When this happens, you will be prompted with a link to Create a rule. Click on the link. A new rule will be populated into the **UNASSIGNED** group, with the message you had entered. Click [here](/features/rules) to learn more about Rules and configuring one. ## Adding a new bot **Step 1 of 5:** Click on . You will be instantly redirected to the [new](https://flow.botdistrikt.com/new) dashboard. Here, you can view the various templates available including starting from a blank bot.

Chatbot Templates

**Step 2 of 5:** Select from **Blank Bot**/**Import Bot**/**Website Bot**/**Food Ordering Bot**.

Add New Chatbot --> Select from Blank Bot/Import Bot/Template Bot

**Step 3 of 5:** Regardless of which template is chosen for your chatbot, BotDistrikt allows you to customize it. Proceed with adding the relevant details to your bot. **Import Bot**

Import a bot

**Website Bot**

Generative AI Website Bot Template

**Food Ordering Bot**

Food Ordering Bot Template

**Blank Bot**

Blank Bot Template

In this example, we will use the Bank Bot template. At this step you can add a profile picture as well as your bot's name and description.

Uploading a Profile Picture and Chatbot Description

**Step 4 of 5:** Next, set up your bot's greeting story. What will your bot say for the first time? You can learn more about stories [here](/features/stories). In this example, we add a greeting story with two quick reply buttons.

Setup your greeting story

**Step 5 of 5:** The next step is to setup your chatbot's fallback story. Your chatbot responds with this message if it cannot answer a question. Click **Finish** to create your chatbot!

Setup your fallback story

🎉 Your bot is now ready! You can now view the **BotDistrikt Dashboard** where (from the left-hand side navigation panel) you can update your bot's: * Personality * Dashboard * Forms * Rules * Stories * Responses * Sources * Users * Inbox * Broadcasts * Integrations * Settings

Chatbot Personality Tab

## Creating a Linear Flow A linear flow is a chatbot conversation design principle that allows users to navigate from one story to another story in a fixed way. The user has to view the former story, and only then will they be able to view the latter story. Linear flows require memory. In this example, we will create a linear flow: **Greeting → Transport options → Bus** **Step 1 of 4:** In the left sidebar, navigate to **Stories** > **greeting** in the story dashboard (or any story you wish to set this flow up in). **Step 2 of 4:** In the greeting story, select the button you wish to be linked to another story and click **Create rule to fix.**

What will the user say next?

**Step 3 of 4:** A popup will appear prompting you to create a rule to fix. Click on , this creates a memory key which is used in this rule to help the chatbot identify that specific button click.

Create rule to fix

Memory key used in a rule condition

**Step 4 of 4:** After saving, if you have yet to configure the linked story in the bot's answer, you can do so in the Story tab. Once configured, you can test your 2-step linear flow by clicking on the chatbot widget. To enable a user to go back to the previous story, configure the quick reply button to .

Return Quick Reply Button

The Bus story can be accessed from a linear flow

If a user clicks **Get Started** and sends a message 'Bus' or any other keyword condition in the rule, the Bus story will not be triggered.

The Bus story cannot be accessed from a nonlinear flow

## Create a Nonlinear Flow Nonlinear flows are stories which can be triggered from anywhere in a chatbot conversation, even from free text, as long as a message or NLP condition is met. Nonlinear flows do not require memory. In this example, we will create a nonlinear flow: **Promotions** **Step 1 of 4:** In the left sidebar, navigate to **Stories** > **greeting** in the story dashboard (or any story you wish to set this flow up in). **Step 2 of 4:** In the greeting story, select the button you wish to be linked to another story and click **Create rule to fix.**

What will the user say next?

**Step 3 of 4:** A popup will appear prompting you to create a rule to fix. Select the Nonlinear option and **Save**. This condition means that as long as the text contains promotions, it will trigger the linked story.

Creating a Nonlinear Flow

**Step 4 of 4:** After saving, if you have yet to configure the linked story in the bot's answer, you can do so in the Story tab. Once configured, you can test your nonlinear flow by clicking on the chatbot widget.

Promotions can be accessed from any part of the chatbot conversation

# Setup your Account Setting up your account is the first step to unleashing the power of our cutting-edge bot development platform. In this guide, we'll walk you through the seamless process of creating and configuring your BotDistrikt account. Whether you're a seasoned developer or just getting started, our step-by-step instructions and intuitive interface will ensure a smooth onboarding experience. By the end of this guide, you'll have a fully set up account, ready to explore the endless possibilities of bot creation, automation, and integration that BotDistrikt offers. Let's get started on your journey to building innovative bots that can transform the way you engage with your audience. # Register for BotDistrikt ## Register for a BotDistrikt Account (Create your Account) 1. To create a free BotDistrikt Account, visit the [BotDistrikt Account Registration page](https://flow.botdistrikt.com/register). Enter the field entries according to the following specifications:
Field NameDescription
Name
Enter first nameEnter your first name
Enter last nameEnter your last name
EmailEnter a valid email ID
Password
Enter PasswordMinimum length 12 characters, minimum 1 uppercase, minimum 1 lowercase, minimum 1 special character, minimum 1 numerical
Re-type PasswordSame as Enter Password

Register with BotDistrikt

2. Click **Register**. 3. Upon successful registration, you will be redirected to the following page indicating **Success** ✅ and receive an account activation email in your registered email ID.

Successful Registration. Proceed to Account Activation.

{% hint style="info" %} If you do not receive the account activation email, check your spam folder. In case, you do not receive the account activation email within 10 minutes, contact us at {% endhint %} 4. Or Sign Up with Single Sign On (SSO) through your **Google** or **Facebook** account.

Or sign up with Google or Facebook SSO.

#### SSO Sign Up with Google Account 1. Click **Google**
Login with Google SSO

Sign up with Google SSO

2. Enter your **email address** and click **Next**

Enter your email address

3. **Enter your password** and click **Next**

Enter your password

4. Upon successful authentication, you will be redirected to the following page.

BotDistrikt Platform Main Page

#### SSO Sign Up with Facebook Account 1. Click **Facebook**

Sign up with Facebook SSO

2. Enter your **Facebook credentials** i.e. email and password

Enter your Facebook email and password

3. Click **Log in** 4. Upon successful authentication, you will be redirected to the following page.

BotDistrikt Platform Main Page - show all chatbots

## Account Activation and Verification 1. If you have registered through your email ID, click on the email titled '**BotDistrikt - Verify your Account**' ![Account Activation Email from BotDistrikt](/files/-LjAmgDwC578-0GZnkJ3) 2. Click on the link to complete your registration. You will be redirected to a page indicating successful email verification.

Successful Email Verification and Account Activation

3. To log in to your account, click **Take me to Login.** 4. In case you have registered through Google or Facebook SSO, you will receive a **Welcome to BotDistrikt** email.

Welcome Email

## Login to BotDistrikt #### Login via Email ID 1. Access the login page via 2. Enter your (registered) **Email** and **Password.**

Login to BotDistrikt Account

2. Click **Login.** You will be redirected to the login page. #### Login via Google SSO 1. Access the login page via 2. Click on **Google**

Login using Google SSO

3. Select the (registered) **Google account** to login.

Choose the Google account to login

4. Upon successful authentication, you will be redirected to the following page.

BotDistrikt Platform Main Page

#### Login via Facebook SSO 1. Access the login page via 2. Click on **Facebook**

Login using Facebook SSO

3. Enter your (registered) **Facebook account** **Email** and **Password** and click **Log In**
4. Upon successful authentication, you will be redirected to the following page.

BotDistrikt Platform Main Page

#### Login via Multi-Factor Authentication (MFA) Multi-Factor Authentication (MFA) is available for customers who have implemented it, requiring users to verify their identity with an additional authentication factor (e.g. a time-based one-time code from an authenticator app) on top of their email and password. 1. Enter your (registered) **MFA account** **Email** and **Password** and click **Login**

Provide MFA account email and password

2. Launch your Authenticator App (see [below](#enable-mfa-on-base-platform) to setup MFA for new user, you wil be asked to scan a new QR code to setup) 3. Provide 6-digit MFA Code below

Provide 6-digit MFA Code

4. Click **Verify** 5. Upon successful authentication, you will be redirected to the following page.

BotDistrikt Platform Main Page

#### Setup MFA on Base Platform On the base platform, MFA is optional and can be enabled with below steps: 1. Login to the Bot 2. Click at the top right at your name 3. Click "Edit Profile"

Edit Profile

4. Click "Setup MFA"

Setup MFA

5. You will see below "Setup Multi-Factor Authentication" page 6. Open your Authenticator app and scan the QR code as shown on this page

Scan QR Code using Authenticator app to get MFA Code

6. After scanning the QR code, **enter the 6-digit MFA token** displayed for your Bot 7. Click **Verify & Complete Setup** 8. Upon successful MFA setup, you will be redirected to the following page indicating **Success** ✅. 9. Click "Show me my bots" to see your bot(s)

Setup MFA successfully

#### MFA on Customer Platforms * On customer platforms, MFA is mandatory and will be required to be set up after you log in for the first time. Customer cannot access the "Bots" without entering their MFA first * On customer platforms, self-registration is not possible. Only exclusive and explicit [invitations](/features/settings/user-access-management) are available for team members to log in. # Forgot Password To recover your password: 1. Go to the BotDistrikt [**Login**](https://flow.botdistrikt.com/login) page 2. Click **Forget Password** at the right-hand side bottom of the Login card.

Forgot Password

3. You will be redirected to the [**Password Reset**](https://flow.botdistrikt.com/reset) page. 4. Enter your **Email** and click **Change Password.**

Change Password

5. You will be redirected to the **Success ✅** (Please check your email to reset your password.) page.

Success - Reset Password Link Sent

6. Go to your registered email ID and click on the link (within 15 minutes of receiving the link) to reset your password. 7. You will be redirected to the reset page.

Change Password

8. Enter **New Password** and **Confirm New Password.** 9. Click **Change Password.** Your screen will redirect to **Success ✅** (Your password has been reset. Please login.)

Change your Password Walkthrough

# Chatbots Dashboard Once logged in, you can view the following [dashboard](https://flow.botdistrikt.com/bots).

Chatbot Dashboard

1. Click on **Add New Bot.** You will be instantly redirected to the [new](https://flow.botdistrikt.com/new) dashboard.
2. Select from **Blank Bot**/**Import Bot**/**Food Ordering Bot\***.

Add New Chatbot --> Select from Blank Bot/Import Bot/Template Bot

In case, the BotDistrikt team has already created a bot for you through your registered email ID, you can view your bot on the Chatbot dashboard.

Sample Bot Dashboard with (Sample) Bot Created by BotDistrikt Team

Click on your sample chatbot, or **Add new bot.** You will be redirected to the **BotDistrikt Dashboard** where (from the left-hand side navigation panel) you can update your bot's: * Personality * Dashboard * Forms * Rules * Stories * Responses * Users * Inbox * Broadcasts * Integrations * Settings \***Blank Bot**

Add a Blank Bot - Homepage (first step)

Click on **Next Step** to **Setup your greeting story** with a small walkthrough.

Setup your chatbot (walkthrough)

Skip this to proceed to the main **Dashboard.** You can always update the skipped details on the main dashboard. \***Import Bot** **\*Template Bot**

Add a Template Bot (e.g. Food Ordering Bot)

Click on **Next Step** to proceed to set up business specifics.

Template Bot - Setup your Food Ordering Bot with Business Specifics

Enter basic details: * **Restaurant Address** * **Country** (of operation) * **Currency** * **Opening Hours** * **Contact Email**

Enter Menu Categories

Enter parent **Menu Categories** (type a category and press tab).

Add Menu Items

1. Click **Add Item** at the bottom of the default **Menu Items** and add a menu item. 2. Add a title 3. Add a menu image 4. Select from the dropdown menu categories. Update your menu categories from **Menu Categories.** 5. Click the delete icon to delete the current menu item 6. Move the current menu item up and down the menu.

Delivery Details

Enter delivery details in the last section: * **Delivery - Minimum Order Value** (enter delivery fee). * **Free Delivery - Minimum Order Value** (enter minimum order value to avail free delivery). * **Delivery Fee - Fixed** (enter delivery fee for orders below minimum order value threshold). Click **Next Step** to proceed.

Generating Food Ordering Bot after Entering Specifics

Your Template Bot for your food business is generated. # Edit Profile Update your personal information To update your **First Name**, **Last Name**, and **Passwords:** * Navigate to the top right-hand corner of your top panel. * Click on your name at the top right-hand corner of your dashboard. * Click **Edit Profile.**

Update Profile Information

Click **Save** to save your updated profile information. View your **Access Token** in your **Account** section.

View Access Token

{% hint style="info" %} Access tokens are used in token-based authentication. It allows your app to access our API. Your app receives an access token after we successfully authenticate and authorize access, then pass the access token as a credential when you call the target API. The passed token informs the API that the token bearer (you) is authorized to access our API and perform specific actions (e.g. integrate your BotDistrikt bot to your website) specified by the **scope** that was granted during authorization. {% endhint %} Click **Change Password** to update your current password. Click **Save.**

Change Email Preferences

Click **Email Preferences** to view current email preferences. Each bot has separate email preferences that you can update in each bot's dashboard.

Change Email Preferences

# Channels Overview ## Supported Channels BotDistrikt supports the following channels currently and to provide a seamless and user-centric experience, we continue to onboard a broader range of communication channels for maximum scalability. Channels Summary The table below summarizes the channels you can launch your bot on, and additional requirements needed. | **Facebook Messenger** | Facebook Page | | ---------------------: | ----------------------------------------------- | | **Instagram** | Instagram Business Account | | **WhatsApp** | WhatsApp Business API | | **Telegram** | Telegram Bot | | **Twitter** | Twitter Account | | **Skype** | Microsoft Azure Bot Channels Registration | | **Website Chat** | Ability to add custom scripts to website's HTML | | **Google Assistant** | Action on Google | | **WeChat** | WeChat Account | # Website Chat You may deploy your bot to appear as a widget on your own website. Your website's visitors may chat with your bot on it or link to other live messaging channels. The end product looks like this on a desktop screen.

Chatbot live on website

like this on mobile

BotDistrikt Bot on Mobile

## Capturing Conversations To encourage users to visit your chatbot widgets, you can implement: * Embedding: Embed your chatbot widget into a variety of platforms ranging from websites to mobile applications. * Chat links: Add your chatbot URL in marketing collaterals or in stages of your user journey to direct them to your widget. * QR Codes: Add a QR code which directs users to your chatbot widget. This can be placed on digital assets as well as in physical locations. * Live chat: A live chat option allows you to provide assistance to users and capture request details in real time. This can be done with BotDistrikt's integration with CRM tools such as Salesforce, Twilio, and more. ## Supported File Types The [supported file types](https://docs.botdistrikt.com/how-botdistrikt-works/engagement#image) on Website Chat Widget and the maximum file size for each type are as follows: * Audio - MP3s, WAVs (10 MB) * File - PDFs, DOCs, PPTs, XLSs (10 MB) * Image - PNGs, JPEGs, GIFs (10 MB) * Video - MP4s, MOVs, AVIs (20 MB) Should an unsupported file type be uploaded, a tooltip with an error message will appear.

Error Message for Unsupported File

## **How to reach out to chatbot users?** You can reach out to users with [Broadcasts](/features/broadcasts), or via the [Console](/features/inbox/console). If a user leaves your website, reaching out to them can be done via their personal contact details. To collect a [user's personal details](/features/users/dear-user), you can use [Forms](/features/forms) or [manually record](/features/users/edit-users) details in a user's profile page. # Website Chat Quick Start ## Prerequisites In order to deploy your bot on your website: * Have a live and publicly accessible HTTPS-secured website * Ability to add custom scripts to the website's HTML source code ## Setup From your bot account * Go to **Integrations** * Select **Website**

Go to Integrations --> Select Website

* Enter basic details to set up the chatbot widget on your website Under the **Domains** field, enter the domain URL(s) of the websites that you wish to install the website widget on. Some examples are * * *

Enter your Domain(s)

If you do not add your domains, the chatbot displays an error message like this ![Error if you do not add your website's domain](/files/-M10ti8iRe5OKYymd45l) You can enter multiple domain URLs for the chatbot to be on multiple websites. ## Install You will be presented with some customized HTML code to copy.

Custom HTML code to copy

Copy and paste the code into your website's HTML source code, just before the closing `` tag ``` ... ... ... ``` Your bot widget will appear as soon as you refresh the page. ## Customize Customize the website chat widget:
FieldUsed For
FieldUsed For
Primary ColorKeeping your website's branding consistent
Terms of UseGiving visitors a checkbox to consent to before they use the chatbot widget
Privacy Policy Giving visitors a checkbox to consent to before they use the chatbot widget
Custom CSSOverwrite BotDistrikt's chatbot widget styles with your own custom
CSS
Event WebhookReceive message response events at your own webhook. This is useful for consuming admin-generated messages and broadcasts.
{% hint style="info" %} It is recommended to have a privacy policy set up to keep compliant with GDPR and other data privacy regulations around the globe {% endhint %} ## Default Language The default langugage setting allows you to set the default language of all UI elements of the chatbot widget like the Get Started button, Input Placeholder, and the Send button. To select a default language: 1. Navigate to the website chat widget by going to Integrations > Website

Default language dropdown

2. Select a default language to automatically change the language of UI elements.

Changing default language of UI elements

3. Default Language also presets the user profile's "Language" option with its value, so the Story Translations will work automatically. ## Toggles **Default Open** determines whether the chatbot widget window will be open by default. [**Collect Message Reactions**](/features/inbox/reactions) toggle determines whether or not the chatbot allows collecting 👍 and 👎 message reactions. [**Collect Ratings**](/features/inbox/ratings) toggle determines whether or not the chatbot allows collecting ratings. **Show Popup Message** toggle determines whether or not the chatbot will display a popup message. Upon activating the toggle, you can customise the popup message text and delay duration (in seconds) before the text bubble shows up. {% hint style="warning" %} If the **Default Open** toggle is active, the popup message will not be shown as the chatbot widget window will be open by default. {% endhint %}

Popup message

Popup message customisation

# Guest Users ## Managing Users Unlike a user messaging your bot with another messaging channel, website visitors are anonymous and cannot be identified by the chatbot. Therefore, your users who message your bot will be given a random name in format of Website Guest XXXXX. ![Users Dashboard of users of the Website Widget](/files/-M0Rbwg7062HPIW7Qqs3) Website users have 2 attributes setup as soon as they click GET STARTED | Attribute | Description | Use | | ------------ | --------------------------------------------------- | ----------------------------------------------------- | | `webchat_id` | A unique generated ID | to identify a user as long as their session is active | | `source` | The domain URL where they messaged the chatbot from | to personalise chat experiences with rules | ### A note on Website bot Users Website chat does not automatically store any identification information, as opposed to other messaging channels. Every user is a **Guest Use**r. This means after messaging your bot if a user * Clicks Reset Chat, * Closes the page on their browser, then revisits the page, or * Stays inactive on the page for more than your bot's Session Length Their profile on your bot will expire. Subsequent chats from the same person will create a 2nd User profile on your bot. {% hint style="warning" %} Please be wary of Guest Users as each one of them counts towards your plan's User Limit {% endhint %} It is recommended to make your website chat bot request every user for personally identifiable information such as their email address or phone number, so you may continue conversations with them later on. Please remember to add your Privacy Policy to the Website Chat integration before doing this. # Facebook Messenger Facebook Messenger (or simply Messenger) is used by over 1.3 billion people each month. Some of the key features and functionalities supported by Facebook Messenger bots include: 1. **Text-Based Conversations**: Messenger bots engage in text-based conversations with users, responding to messages, questions, and prompts. 2. **Rich Media Messages**: Send various types of rich media, including images, GIFs, videos, and audio clips, to make interactions more engaging and visually appealing. 3. **Quick Replies**: Provide users with quick reply buttons to guide them through predefined options or actions, making interactions more user-friendly. 4. **Persistent Menus**: Persistent menus that allow users to access specific features or functionalities at any point during the conversation. These menus are typically displayed at the bottom of the chat window. 5. **Postback Buttons**: Postback buttons allow users to trigger specific actions or functions within your bot when clicked. They are often used for tasks like making a reservation or navigating menus. 6. **Webview**: Open a webview within the Messenger app, enabling users to interact with web-based content or complete transactions without leaving the chat. 7. **Payment Integration**: Facilitate payments, allowing users to make purchases, donations, or payments for services directly within the conversation. 8. **Location Sharing**: Users can share their location with your bot, which is useful for services like finding nearby stores, restaurants, or services. 9. **Templates**: Use structured message templates to present information in a visually organized way. Examples include receipts, confirmations, and lists. 10. **User Authentication**: Integrate with Facebook's user authentication, allowing businesses to verify user identities and provide personalized services. 11. **Subscription Messaging**: Send non-promotional messages to users who have opted in to receive updates. These messages are often used for news, updates, and notifications. 12. **Broadcasting**: Send messages to a list of subscribers or segmented groups, similar to email marketing. 13. **AI and NLP Integration**: Integrate with AI and natural language processing (NLP) technologies to understand and respond to user messages more intelligently and conversationally. 14. **Analytics and Insights**: Analytics tools that allow businesses to track your bot performance, user engagement, and conversion rates. 15. **Chat Plugins**: Embed Messenger chat plugins on your websites, enabling users to initiate conversations with your bot directly from your website. 16. **Handover Protocol**: Seamlessly hand over conversations to human agents when needed, ensuring a smooth transition between automated and human support. 17. **Multilingual Support**: Programmed to support multiple languages, allowing businesses to reach a global audience. 18. **Integration with Third-Party Services**: Integrate with external services, such as CRM systems, e-commerce platforms, and databases, to provide your users with real-time information and services. 19. **Customization and Branding**: Customize the bot's appearance, name, and profile picture to align with your branding and provide a consistent user experience. These features make Facebook Messenger bots versatile tools for startups and enterprises to engage with users, provide customer support, automate tasks, and offer a wide range of services within the Messenger platform. ## Prerequisites In order to integrate Facebook Messenger with your Bot, you will need the following: * A [Facebook account](https://www.facebook.com/) * A [Facebook Page](https://www.facebook.com/pages/creation/) so your users can message your bot When a user sends a message to your Facebook Page, your BotDistrikt bot will reply to them. ## Setup From your bot account, go to **Integrations** Select **Messenger**

Integrations page

Click on **Continue with Facebook**

Continue with Facebook

Click **Continue as (yourself).**

Continue with Personal Profile

**Select the Facebook Page** you want to launch your bot on. You may select multiple pages if you manage multiple bot accounts on BotDistrikt.

Multiple bots option

Grant access to all required permissions. Click **Save.**
Click **Got it.**

Link BotDistrikt Bot to your Business Page.

You will be redirected to the BotDistrikt Messenger page. On the Facebook Page dropdown, select the page you want to launch your bot on. Your page details appear on and under the photo on the left. Click on **Link to Messenger.**
Your bot is now live on your Facebook Page

Live Bot

# Import Existing Users If your Facebook Page Inbox has existing historical conversations with your followers, you have the ability to import these users into BotDistrikt. To import existing users, you may click the button on the Messenger integration page ![Import Existing Users](/files/-MkBcyMDWTqxqbZnsh76) ## Benefits When you **Import Existing Customers** to experience your chatbot, converts non-chatbot users of your Facebook Page Inbox into your Facebook chatbot marketing strategies.

Convert Old Messages Users to Bot Users

# Facebook Chat Plugin The Chat Plugin allows you to integrate your Messenger experience directly into your website. This allows your customers to interact with your business anytime with the same personalized, rich-media experience they get in Messenger. ![Deploy Chat Plugin](/files/-MkBdHWxoKCIXeX1HC84) After you add the Facebook Chat Plugin to your website, users who message your bot on the website will be added to your Facebook Page Inbox. These users will still be categorized as Facebook users on BotDistrikt - not Website users. Follow the [**Official Facebok Chat Plugin Documentation**](https://developers.facebook.com/docs/messenger-platform/discovery/facebook-chat-plugin#steps) to set up the Chat Plugin on your website ## Benefits When you integrate a Facebook Messenger bot on a business website, you enhance user engagement, streamline customer support, and improve overall user experience. 1. **Instant Customer Support**: Users can initiate conversations with the bot directly from the website, and receive quick responses to their queries 24/7, in turn boosting customer satisfaction and quicker issue resolution. 2. **Convenient Communication**: Many users prefer chat-based interactions over phone calls or emails. 3. **Scalability**: Messenger bots handle a large volume of inquiries simultaneously, making it easier to scale your customer support operations with business growth. 4. **Cost-Efficiency**: Significantly reduce customer support costs compared to hiring and training additional staff. 5. **Improved Lead Generation**: Collect user information and qualify leads through relevant questions. Businesses can then follow up with qualified prospects more effectively. 6. **Enhanced User Engagement**: Send proactive messages, such as promotions, updates, or reminders, to website visitors, keeping them engaged and informed. 7. **Personalization**: Use user data to provide personalized recommendations and responses, creating a more tailored and relevant experience for each visitor. 8. **Data Collection and Insights**: Gather valuable user data and insights, helping businesses understand customer behavior, preferences, and pain points. 9. **Lead Nurturing**: Nurture leads by providing information, answering questions, and guiding users through the sales funnel. 10. **Customer Feedback**: Collect feedback from website visitors, helping businesses identify areas for improvement and measure customer satisfaction. 11. **Cross-Selling and Upselling**: Recommend related products or services to users based on their inquiries or browsing history, increasing the chances of additional sales. 12. **Increased Website Traffic**: Offering live chat through Messenger, and attracting more visitors to your website who prefer chat-based support, potentially reducing bounce rates. 13. **Integration with CRM and Tools**: Integrate with customer relationship management (CRM) systems and other business tools, streamlining data management and ensuring a unified customer view.

Deploy Messenger Chatbot Plugin to Website

# Facebook Checkbox Plugin {% hint style="danger" %} On May 9, 2024, you will no longer be able to access any of the functionality of the Chat Plugin. Effective immediately, Chat Plugin in guest mode is no longer available. Other features like m.me links will still be available for you to use. {% endhint %} The checkbox plugin allows you to display a checkbox in forms on your website that allows users to opt-in to receive messages from your bot in Messenger. If the person is currently logged in to Facebook, their profile photo and name will be displayed next to the checkbox. If the person is not logged in to Facebook or wants to log in as a different user, they can authenticate. ![Facebook Chatbot Plugin](/files/-MkBuM0Q8bPtuOCRZqZV) ## Benefits By using Facebook Checkbox Plugin, you will be able to convert authenticated website users into your Facebook chatbot marketing strategies.

Facebook Messenger Chatbox Plugin

# Facebook Private Replies As the owner of a Facebook Page, you may publish public posts for your current and potential followers - external Facebook users - to see on their News Feeds. Sometimes, you may want to loop these external Facebook Users to become Users of your bot. [Facebook Private Replies](https://developers.facebook.com/docs/messenger-platform/discovery/private-replies/) is a unique feature that allows you to create the connection between a Facebook user's comment on a Page post and a response from your bot. If the Facebook user replies to the response, they will become a new User on your Users Dashboard. {% hint style="info" %} Facebook users who comment on your post will only become a user when they reply to the bot's automated response. {% endhint %} {% hint style="danger" %} Ads are not supported for Facebook Private Replies {% endhint %} ## Benefits By using Facebook Private Replies, you will be able to convert Facebook users who comment on your Page posts into your Facebook chatbot marketing strategies.

Private Replies --> Chatbot users --> Customers

# Facebook Ads Manager When you have several users messaging your Facebook Page, BotDistrikt stores their targeting information. This customer data can be exported and re-used in your other Facebook Advertising Campaigns. ## Custom Audience You may create a Custom Audience for your Facebook Ads directly from your user base of people who have messaged your bot in the past. From your bot account, go to **Users** Under Filters, add a new filter with | Column | Function | Value | | ------- | -------- | --------- | | Channel | equals | Messenger | This filters your Facebook Messenger users only Under Actions, select the action **Export rows to CSV** ![Export to CSV](/files/jkjzkOiGV1he6lSJWxZo) Download the CSV File, you will be able to see your users' data including their **Facebook PSIDs** On [Facebook Ads Manager](https://www.facebook.com/business/tools/ads-manager), click on Audiences, and click on **Create a Custom Audience** Select the Source **Customer list** and click Next ![Custom Audience](/files/ekcmXyxG97mNzptU6o6H) * Follow the steps in the wizard **Prepare List** * Click Next **Select List Type** * No Customer Value * Click Next **Add Customer List** * Upload a List * Select your exported CSV file from BotDistrikt * Relevant categorization (e.g. `Messenger Users from my chatbot`) * Click Next **Map Identifiers** * Under the Mapped tab, map the column Facebook PSID to Facebook Page User ID ![](/files/HbrIpB88mdiT018veq7o) Now under the Action Needed tab, look for Facebook PSID. Click on Enter Facebook Page IDs. ![Facebook Page IDs](/files/5cOTU515qNMvRg0x3QXv) * Enter your Facebook Page ID here * You can find your Page ID on Integrations > Messenger in BotDistrikt * It should now successfully be mapped ![Map Identifier](/files/wKRSnF19TFPZQkJ6gbnL) * Click Import & Create You can now use this Custom Audience in your Facebook Ad Campaigns You may also create 'Look alike' Audiences to target users with similar interests to your Custom Audience. # Instagram With roughly one billion monthly active users, Instagram belongs to the most popular social networks worldwide. Engage your users with experiences that includes cards, quick replies, and buttons. Instagram chat supports a huge range of features. Instagram Bot Conversation Example ## Prerequisites In order to integrate Instagram with your Bot, you will need the following: * A [Facebook account](https://www.facebook.com/) * An [Instagram Business account](https://help.instagram.com/502981923235522) with Message Control access * A [Facebook Page](https://www.facebook.com/pages/creation/) connected to your Instagram Business account ### Enable Message Control You will need to allow your bot to access your Instagram messages via the Connected Tools settings in your Instagram Business account. Follow the steps below to set this up ![Deployment Process](/files/-MlULpegXKBZVrzjweH5) Once this is done and you have Linked to Instagram, when a user sends a direct message (DM) to your Instagram Business account, your BotDistrikt bot will reply to them. ## Setup From your bot account, go to **Integrations.** Select **Instagram** ![](/files/-MkMdWKALrI5QWzcyzt7) Click on **Continue with Facebook.** ![](/files/-MkMdc11N3YPBpUJuqxP) Continue as (yourself) Continue as (Yourself) **Select the Instagram Account** you want to launch your bot on. You may select multiple pages if you have multiple bot accounts on BotDistrikt. Select Business Account Select the **Facebook Page** **linked** to the Instagram Business account you just selected. Select Facebook Page Linked to Instagram Grant access to all required permissions, then click **Done.** Permissions Required {% hint style="info" %} You will see **BotDistrikt** instead of **BotDistrikt Development,** as we are just using our development environment for the above screenshots 😁 {% endhint %} Click **OK.** Notification * You will be taken back to the BotDistrikt Instagram page. * On the Instagram Business account dropdown, select the account you want to launch your bot on. * Your account details should appear on and under the photo on the left. * Click on **Link to Instagram.** ![Select Business Page](/files/-MkMfKS5XQs3pwE7YBv_) Your bot is now live on your Instagram Business Account. ![Live on Instagram Business Account](/files/-MkMfQWsaJvh4r8lgFQc) # Import Existing Users If your Instagram DMs Inbox has existing historical conversations with your followers, you have the ability to import these users into BotDistrikt. To import existing users, you may click the button on the Instagram integration page ![](/files/-MkMfhhnBMM2Yb4qb9cK) ## Benefits By using Import Existing Users, you will be able to convert non-chatbot users of your Instagram DM Inbox into your Instagram chatbot marketing strategies.

Import Existing Instagram Users to Chatbot

# Instagram Story Mentions When an Instagram user [mentions](https://about.instagram.com/blog/announcements/introducing-mentions-sharing-for-instagram-stories) your Instagram Business account in their Story, it would normally appear in your Instagram DM Inbox. When your bot is connected to your Instagram Business Account on BotDistrikt, your bot may reply to a story mention like this: Bot replies to a story mention To enable bot to respond to a story response, set up a new rule. When someone mentions your Instagram account in their story, a postback event is triggered. To make the bot respond to this event, you must add a rule with the following condition | Context | Property | Function | Value | | --------- | ---------- | -------- | -------------- | | `message` | `postback` | `equals` | `storyMention` | If the above rule is not added, the bot will respond with its default fallback story ## Benefits By replying to story mentions, you will be able to convert non-chatbot users who mention your IG business account in their stories, into your Instagram chatbot marketing strategies.

Response to a Story Mention

# Twitter {% hint style="danger" %} Twitter has temporarily discontinued Twitter integrations due to modifications made by Twitter to its APIs. This includes limitations on the number of requests raised per minute, plus substantial pricing changes. {% endhint %} ## Prerequisites In order to integrate Twitter with your Bot, you will need the following: * A [Twitter account](https://twitter.com) with Direct Messages access ### Direct Messages In order for your bot to receive direct messages from anyone (including accounts it does not follow), the option must be enabled in Twitter’s settings. Go to Twitter’s [Direct Messages](https://twitter.com/settings/direct_messages) settings and check "Allow message requests from everyone". Be sure to save your changes! ![Twitter Permissions](/files/2nZHHzFn1X6rxntaI3SL) Once this is done and you have Linked to Twitter, when a user sends a direct message (DM) to your Twitter account, your BotDistrikt bot will reply to them. ## Setup From your bot account, go to **Integrations** Select **Twitter** ![Twitter Integration](/files/MAMsQRQ7gnY4l6sKIuEu) Click on **Sign in with Twitter** ![Sign in with Twitter](/files/NZiiEVHaI3uMWJRGtK5i) Authorize BotDistrikt to access your account Authorize BotDistrikt You will be redirected to the BotDistrikt Twitter page. Your account details appear on the integration card. Click on **Link to Twitter.** ![Sample Bot Integration with Twitter](/files/wN7ZdivHrQ1WW2g3dMZV) Your bot is now live on your Twitter Account. ![Live Twitter Bot](/files/T2EPLYMZxrTaxlOk1Pgo) # Skype # WhatsApp To integrate your chatbot with WhatsApp, you are required to use a WhatsApp provider. Currently, BotDistrikt is integrated with UIB and Twilio (while onboarding more providers by the day). WhatsApp, is a cross-platform centralized messaging and voice-over-IP (VoIP) service owned by Facebook, Inc. It allows users to send text messages and voice messages, make voice and video calls, and share images, documents, user locations, and other content. It became the world's most popular messaging application by 2015 and has over 2 billion users worldwide as of February 2020. {% hint style="info" %} Once you have set up an account with the WhatsApp partner, connect it to the BotDistrikt platform and manage your inbox. {% endhint %} {% hint style="warning" %} WhatsApp API has a messaging window of 24 hours which you are allowed to reply to customers with any content when the client initiates a chat with you. After 24 hours, you will need to send a Template Message in order to send a reply to the customer. {% endhint %} ### What is a Customer Care Window? The Customer Care Window is a 24-hour time frame in which you can communicate with customers in a rich conversation using so-called Session Messages, reacting to them in a real-time and interactive chat with rich media capabilities. This means your message is not limited to the pre-approved Message Templates, though Message Templates are possible within a customer care window as well. Moreover, chatting with your customer in this 24-hour customer care window will not be charged the WhatsApp fee. The customer care window ends 24 hours after the last message is sent by the end-user. After 24 hours, you will only be able to send a notification via Message Templates. Each time the customer sends you a message, whether this is the conversation initiating message or another reply in the conversation, the 24hour customer care window will restart. So, from the last message your customer has sent you, you have 24 hours to send custom messages, free of charge unless you exceed your package. **Session Messages VS Template Messages** Session Messages: When **a user** sends an incoming message to your number, a timer is set. You have 24 hours to send outgoing messages to that user without any restrictions. Template Messages: To continue the conversation after the 24-hour window ends, you can send one single Message Template. However, this is only allowed if you have an active opt-in from the customer. Message Templates give you the opportunity to send a notification to your customer if you need more than 24 hours to solve the customer’s problem. Please see this [WhatsApp Message Template Guidelines ](https://developers.facebook.com/docs/whatsapp/message-templates/guidelines)for detailed explanations. # Twilio WhatsApp Integration By integrating Twilio WhatsApp API, the platform allows your bot to respond to WhatsApp messages directly, and automate customer care, sales, support, and other business functions. ## Prerequisites For the Twilio WhatsApp API Provider, we will need * An Account SID * Auth Token * A WhatsApp-enabled Number When a user sends a message to your WhatsApp Enabled Number, your BotDistrikt bot will reply to them ### Create a Twilio Account You can set up a new Twilio Account [here](https://www.twilio.com/try-twilio). After logging in for the first time and setting up your details, you will be taken to the Dashboard page. You will get your Account SID and the Auth Token from this page {% hint style="success" %} New accounts come with $15 worth of credits, which you can use to purchase a phone number {% endhint %}

Twilio Console

### Enable the WhatsApp Sandbox Click on the **Messaging** tab and click on **Overview > Try WhatsApp**

Twilio WhatsApp Sandbox

Follow the instructions on this page When your device is connected to the Sandbox, you will receive this message
After you have successfully completed the above steps, return to the **Twilio Messaging > Try WhatsApp**. You will see this step.
You are now ready to setup the Twilio WhatsApp API Provider on your BotDistrikt WhatsApp channel ## Setup

BotDistrikt WhatsApp Integration

We have our Account SID and Auth Token ready. We need to get the WhatsApp Enabled Number ready now. On Twilio, click **Sandbox Settings** to get your WhatsApp Enabled Number.
On BotDistrikt, fill in all 3 fields: * An Account SID * Auth Token * A WhatsApp Enabled Number {% hint style="info" %} For the WhatsApp Enabled number, make sure to remove the white spaces and add a **whatsapp:** prefix. For example, if the number you copy from Twilio is `+1 415 523 8886`, The number you will need to key into BotDistrikt is `whatsapp:+14155238886` {% endhint %}
Click **Link to WhatsApp** When it is linked, take note of the **When A Message Comes In** and **Status Callback** endpoint URLs
Go Back to **Twilio** Click **Settings > WhatsApp Sandbox Settings** and paste the respective endpoint URLs there
Click **Save** on Twilio Your BotDistrikt bot is now connected to WhatsApp through Twilio!

Whatsapp Chatbot Connected

# Telegram Integrating BotDistrikt's chatbot with the Telegram messaging channel offers numerous benefits for startups and enterprises seeking to expand their reach and provide efficient customer support and engagement. Here are some of the key benefits: 1. **700 Million Monthly Active User Base**: Telegram boasts a sizable and diverse user base, making it an attractive platform for businesses to connect with a wide audience. 2. **Automated Customer Support**: Chatbots on Telegram can efficiently handle routine customer support inquiries, such as frequently asked questions, order status checks, and basic troubleshooting. This automation frees up human agents to focus on more complex issues. 3. **Efficiency and Scalability**: Chatbots are capable of handling a large volume of conversations simultaneously. As user demand grows, chatbots can efficiently scale to accommodate increased interaction, reducing the need for additional support staff. 4. **Rich Media Sharing**: Telegram supports various media types, including images, videos, files, and links. Chatbots can leverage these capabilities to share multimedia content, product images, instructions, and more with users. 5. **Secure and Encrypted**: Telegram is known for its security features, including end-to-end encryption for messages. 6. **Feedback and Surveys**: Gather user feedback and conduct surveys on Telegram, helping businesses collect valuable insights and improve their products or services based on user responses. 7. **Promotional Campaigns**: Run promotional campaigns, send updates, and offer discounts or special offers to users, fostering customer loyalty and engagement. 8. **Integration with External Systems**: Integrate with other business systems and databases, enabling them to access and provide real-time information, such as inventory levels, order statuses, and more.

Telegram Bot Integration

## Prerequisites In order to integrate Telegram with your Bot, you will need the following: * [A Telegram Bot](https://telegram.org/blog/bot-revolution) When a user sends a message to your Telegram bot, your BotDistrikt bot will reply to them. ### Create a Telegram Bot First, you have to chat with the [BotFather](https://web.telegram.org/#/im?p=@BotFather) in Telegram. Search for "BotFather" and click on **Start**

Click on Start with BotFather

Select **/newbot** to start creating your bot.

BotFather Process

Next, choose a display name and username for your bot. You may edit the display name later on but the username is fixed. {% hint style="info" %} The username is fixed and cannot be changed. Please choose a username carefully. {% endhint %}

Gain Token Access

The BotFather will then issue an **Authorization Token**, also called *API Token*, or just *Token*. This token is like a password you will use to integrate your BotDistrikt bot. Keep it safe. ### Customise Bot Profile To customize your Telegram bot's profile, you will need to chat with the BotFather again. Type or select /mybots.

Choose your Bot from mybots

Next, you will be shown a list of your bots. Select the bot that you want to edit.

Edit your Bot

Select your bot and a menu of what you can do to the bot will appear.

Edit Bot

Select **Edit Bot**

Bot Menu

Here is the list of fields you can edit for your Telegram bot: | Field | Where a Telegram User sees it | | ------------------- | ---------------------------------------------------------------- | | Name |

On the main Telegram inbox page,

In the chat thread

| | Botpic |

On the main Telegram inbox page,

In the chat thread

| | Description | When a user clicks on your bot for the first time | | Description Picture | When a user clicks on your bot for the first time | | About | When the user clicks on "More Info" in the chat thread | | Commands | In the **Menu** of your bot, or when a user types "**/"** |

Bot Profile: Name, Description, and Botpic

Bot Profile: About

Bot Profile: Commands

## **Setup** From your bot account, go to **Integrations** Select **Telegram**

Select Telegram Channel

* Paste your bot's **Authorization Token** from the BotFather * Click on **Link to Telegram**

Enter Authorization Token

You will receive a notification from BotDistrikt stating that a new group of Rules called **TELEGRAM** will be added to your bot**.** Click **OK** And you are done! Your bot is now live as your Telegram Bot

Your Bot is Ready

## Trigger Story Upon Chat Session Expiry To send a story on a user chat session expiry, activate the toggle for **Send a story when the chat session expires**. Upon activating the toggle, select a Session Expiration Story from the dropdown menu. Once selected, click **Save**.

Session Expiration Story Selection

On session expiry, the selected story will be sent to the user. You can use this feature to collect user feedback, increase user engagement, and more!

Story Sent on Session Expiry

# Telegram Commands Telegram Bots have a special version of a [persistent menu](broken://pages/-MjJWNqbgKRgZrxTFuZn#persistent-menu) called commands. Commands allow your users to trigger specific stories from your bot. ## /start command When a user clicks into the your bot on Telegram for the first time, they are presented with the bot's description and a **START** button. Clicking the **START** button is equivalent to typing `/start` to your bot. Therefore, when your user clicks the Start button, the first message they will see that got sent to the bot was the `/start` command itself like this

The START button

becomes the "/start" command

Therefore, `/start` is a default command in every BotDistrikt bot. When the TELEGRAM group of rules is created after linking your bot to Telegram, you will also see a rule automatically generated like this ![Telegram /start command's rule](/files/-MkGoFB0_zeHx_iopAbE) This rule just checks if a sent a User sent a message with the text `/start` to the bot, and if so, triggers the bot's default **greeting** story. ## Custom commands Telegram bots are known well to work with slash commands like `/start`. On BotDistrikt, you may add your own commands and descriptions. Here is an example of how it can be used ![](/files/-MkH-cSwvYjXsFXYFRNx) The platform then identifies the Linked Story, based on which rule is selected as the Passing Rule for each command. A good practice is to create a New Rule for each command in the generated TELEGRAM group, and the story you want to trigger for it like this ![Create Telegram Rule](/files/-MkH11tjUn3n5Hh2Hm7v) From the example above, we create a new rule for each of the **/about**, **/settings**, and **/feedback** commands. # Telegram Groups Bots can work in Telegram group chats. In group chats, a bot responds when: * It is added to a group * A member joins the group * A member leaves the group * A new group is created with the bot as a member * A member replies to a bot message You may use bots to manage your groups and communities, play games, and share information amongst all the members of a group easily with scheduled or recurring Broadcasts. A group is represented as a single User on BotDistrikt, no matter how many members are in it. Groups can be identified with the word *(Group)* in their names, and User Type *group* in their profiles. ![(Group) in a user's name shows that this user is a group](/files/-MkMZ4Z_sI-hzOWwF255) ![User Type group shows that this user is a group](/files/-MkMZe_cpCrx8KOpr6NV) ## Added to a group When you add the bot to a group, a postback event is triggered. To make the bot respond to this event, you must add a rule with the following condition | Context | Property | Function | Value | | --------- | ---------- | -------- | ---------- | | `message` | `postback` | `equals` | `botAdded` | If the above rule is not added, the bot will respond with its default fallback story ## Member joins the group When a new member joins a group the bot is in, a postback event is triggered. To make the bot respond to this event, you must add a rule with the following condition | Context | Property | Function | Value | | --------- | ---------- | -------- | ------------- | | `message` | `postback` | `equals` | `memberAdded` | If the above rule is not added, the bot will respond with its default fallback story ## Member leaves the group When a member leaves a group the bot is in, a postback event is triggered. To make the bot respond to this event, you must add a rule with the following condition | Context | Property | Function | Value | | --------- | ---------- | -------- | --------------- | | `message` | `postback` | `equals` | `memberRemoved` | If the above rule is not added, the bot will respond with its default fallback story ## New group with bot When a new group is created with the bot as a member, a postback event is triggered. To make the bot respond to this event, you must add a rule with the following condition | Context | Property | Function | Value | | --------- | ---------- | -------- | ------------------ | | `message` | `postback` | `equals` | `groupChatCreated` | If the above rule is not added, the bot will respond with its default fallback story ## Reply to message Inside a group, a Telegram bot only responds when one of its previous messages is **Replied** to ![The bot only responds to "Replied to" messages](/files/-MkMQn7rRuEJXmxj0ujU) {% hint style="info" %} Tagging a bot by its username will not make the bot respond. Its message must be **Replied** to {% endhint %} When a bot provides quick replies in a group, clicking on a quick reply automatically "Replies to" the bot, thus making it easier to chat with in groups {% hint style="warning" %} Location quick replies do not work in groups {% endhint %} # Telegram Channels Bots can work in Telegram channels. In channels, a bot will respond when * It is added as administrator to a channel * Another administrator posts in the channel You may use bots to publish information to your channel followers easily with scheduled or recurring Broadcasts. A channel is represented as a single User on BotDistrikt, no matter how many followers are in it. Channels can be identified with the word *(Channel)* in their names, and User Type *channel* in their profiles. ![(Channel) in a user's name shows that this user is a channel](/files/-MkM_QyIdhDYBPHDm5hi) ![User Type channel shows that this user is a channel](/files/-MkM_boV9B9gi7REA4l8) ## Added to a channel When you add the bot as an administrator to a channel, a postback event is triggered. To make the bot respond to this event, you must add a rule with the following condition | Context | Property | Function | Value | | --------- | ---------- | -------- | ---------- | | `message` | `postback` | `equals` | `botAdded` | If the above rule is not added, the bot will respond with its default fallback story ## Admin posts in channel When another administrator of the channel publishes a post, a postback event is triggered. To make the bot respond to this event, you must add a rule with the following condition | Context | Property | Function | Value | | --------- | ---------- | -------- | ------------- | | `message` | `postback` | `equals` | `channelPost` | If the above rule is not added, the bot will respond with its default fallback story ## Channel to Individual chats Telegram channels are a great way to publish content for your followers to see, however they are restricted to one-way content from your admins to your subscribers. Sometimes you would want to publish 2-way interactive content. By doing this, you can * Personalise tailored content to each subscriber * Improve engagement amongst your channel subscribers BotDistrikt has a unique way of allowing you to do this via story-based [Buttons](broken://pages/-MjJWNqbgKRgZrxTFuZn#button). When you publish a story button-based element such as Text, Cards, Audio, or Video with buttons, any subscriber who clicks on that button will magically be taken to an individual chat with your bot to view that story. ![Publish a story with a story-based Button to a Telegram channel](/files/-MkMpdzZKF82imcnWwv8) Here's an example of what can be done with this Channel to Individual chat ### Benefits By using a story-based Button in your Telegram channel, you will be able to convert Telegram channel subscribers into individual users for your Telegram bot marketing strategies.

Convert Telegram Subscribers

# SMS # Google Assistant {% hint style="danger" %} Conversational Actions were deprecated on June 13, 2023. All Conversational Actions will be removed, and will no longer be available to users or developers. {% endhint %} ## Prerequisites In order to integrate Actions on Google with your Bot, you will need the following: * A Google Account with Actions on Google access * An Actions on Google project ### Setup From your bot account, go to **Integrations** Select **Assistant**

Actions on Google Integration

Fill in both **Project ID** and **Client ID** and click on **Link to Action on Google**

Link to Action on Google

Your bot is now linked with Action on Google

Live Action on Google Bot

# WeChat ## Prerequisites In order to integrate WeChat with your Bot, you will need the following: * A WeChat account ## Setup From your bot account, go to Integrations Select WeChat

WeChat Integration

Click on **Link to WeChat**

Link to WeChat

Authorize BotDistrikt to access your account

Authorize BotDistrikt

# Other Channels You may deploy your bot to other custom channels like * Mobile App * Raspberry Pi / Arduino * Smart Speaker ![](/files/-MkQnN__aALVVn3RS5H3) ## Prerequisites In order to connect to them, you will need to set up * The Website Chat Integration After you have created a Website Chat Integration, you must add a unique **custom domain** for each channel. Unlike domains you would use for the website chat widget, a custom domain * Does not need to be a working URL * Is like a *password* * Must not be easily guessable Examples of good custom domains are * ✅ * ✅ Examples of bad custom domains are * ❌ * ❌ ## Setup After setting up your Website Chat Integration with custom domains, you must * Register your Users * Use the Send Message API to send messages as a user You must register a new user for every person who can message your bot. You will then use the user's `webchat_id` to send messages as the user. You will be using 2 models of the BotDistrikt API: 1. [bot\_user](https://static.botdistrikt.com/api.html#tag/bot_user) 2. [bot\_user\_message](https://static.botdistrikt.com/api.html#tag/bot_user_message) ## Register User `POST` `https://flow.botdistrikt.com/api/webchat_apps/:webchat_app_id/user` Registers a new user from your other channel. Returns the bot\_user object to be used for sending messages as this user. You #### Path Parameters | Name | Type | Description | | ---------------- | ------ | ------------------------------------------------ | | webchat\_app\_id | number | Webchat App ID from the Website Integration page | #### Request Body | Name | Type | Description | | ----------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | domain | string | The external domain for this External Frontend | | webchat\_id | string | If you have your own user IDs, you can populate them here for each user. If left blank, the platform will generate one for you. For stronger security, make your user ID unguessable. | | user | object | A bot\_user object. You may use this to pre-populate some fields for each user. | {% tabs %} {% tab title="200 Successfully created a webchat user" %} ``` { webchat_id: "webchat.zbqr0d", first_name: "Webchat Guest 51033", last_name: "", active: true, is_group: false, channel: "web", last_message_at: "2020-02-27T09: 21:00.185Z", attributes: { webchat_id: "webchat.zbqr0d", source: "https://busuncle.sg" }, sessions: 0, impressions: 0, clicks: 0, delay: 0, sentiment: 0, id: 157, bot_id: 4, _isDeleted: false, created_at: "2020-02-27T09: 21:00.000Z", updated_at: "2020-02-27T09: 21:00.000Z" } ``` {% endtab %} {% tab title="401 Attempted to create a webchat user with an invalid domain not included in the Website Chat's domains" %} ``` { errors:[{ status: 401, source: {}, title:"Error", code: "AUTHORIZATION_REQUIRED", detail: "Authorization Required" }] } ``` {% endtab %} {% endtabs %} ## Send Message `POST` `https://flow.botdistrikt.com/api/webchat_apps/:webchat_app_id/message` Sends a message as a user with a valid `webchat_id` generated for a bot\_user object. On success, the bot's responses are returned, which you can use to display in your other channel #### Path Parameters | Name | Type | Description | | ---------------- | ------ | ------------------------------------------------ | | webchat\_app\_id | number | Webchat App ID from the Website Integration page | #### Headers | Name | Type | Description | | ------------- | ------ | ------------------------------------------------------ | | Authorization | string | The *webchat\_id* of the bot\_user sending the message | #### Request Body | Name | Type | Description | | ------- | ------ | ---------------------------------------------- | | domain | string | The external domain for this External Frontend | | user | object | The bot\_user object | | message | object | The bot\_user\_message object | {% tabs %} {% tab title="200 Successfully received a webchat response" %} ``` { webchat_responses: [ { channel: "web", type: "text", response_payload: { type: "text", text: "Hey! How are you?", buttons: [ { type: "postback", title: "Wassup!", payload: "__button__Pdy7aQ" } ] }, quickreplies_payload: [ { type: "text", text: "Help me" }, { type: "text", text: "Give me tips" } ], id: 2519, bot_id: 4, bot_user_id: 150, step_id: 71, _isDeleted: false, created_at: "2020-02-27T15:25:01.000Z", updated_at: "2020-02-27T15:25:01.000Z" }, { channel: "web", type: "text", response_payload: "What can I do for you today?", quickreplies_payload: [ { type: "text", text: "Help me" }, { type: "text", text: "Give me tips" } ], id: 2520, bot_id: 4, bot_user_id: 150, step_id: 65, _isDeleted: false, created_at: "2020-02-27T15:25:01.000Z", updated_at: "2020-02-27T15:25:01.000Z" } ], webchat_quickreplies: [ { type: "text", text: "Help me" }, { type: "text", text: "Give me tips" } ], user: { email: "abhilash@busuncle.sg", active: true, first_name: "Abhilash", gender: null, fb_id: null, webchat_id: "botdistrikt.1", skype_id: null, skype_service_url: null, is_group: false, channel: "web", last_message_at: "2020-02-27T09:58:19.000Z", last_click_at: null, last_name: "Murthy", locale: null, country: null, platform: null, profile_pic: "https://storage.googleapis.com/botdistrikt10/bots/1/20191217_163409_eVO9oa.png", timezone: null, phone: null, notes: null, attributes: { webchat_id: "webchat.sd8FGx" }, stats: { sessions: 3, impressions: 13, delay: 933, sentiment: 0.23076923076923078, last_message: "wqew", clicks: 0 }, sessions: 3, impressions: 13, clicks: 0, delay: 933, sentiment: "0.23", tags_string: null, id: 150, facebook_page_id: null, bot_id: 4, deletedAt: null, _isDeleted: false, created_at: "2020-02-26T14:42:37.000Z", updated_at: "2020-02-27T15:12:01.000Z", webchat_app_id: 7 } } ``` {% endtab %} {% tab title="401 Attempted to send a message with invalid Authorization header or invalid domain" %} ``` { errors:[{ status: 401, source: {}, title:"Error", code: "AUTHORIZATION_REQUIRED", detail: "Authorization Required" }] ``` {% endtab %} {% endtabs %} ## Event Webhook The Event Webhook is a webhook URL that can be configured on the Website Chat integration page. This event webhook allows you to add your own custom webhook to receives events of messages that were sent from the bot to the user.

Event Webhook

This is particularly useful if you would like to publish one-way bot-to-user messaging, as opposed to two-way interactions. Some examples of where this can be used * Live Chat Messaging * Broadcasts * Replying with Stories The headers of the request from an event webhook are as follows: ```json { 'X-Botdistrikt-Source': 'human' OR 'broadcast' OR 'bot' 'X-Botdistrikt-Source-Id': ID of the human, broadcast, or bot } ``` If X-BotDistrikt-Source is `human`, this means a team member (live agent) sent a reply in place of the bot, and the ID of the team member (live agent) is denoted in the value of X-BotDistrikt-Source-Id If X-BotDistrikt-Source is `broadcast`, this means a broadcast was published to this user from the bot, and the ID of the broadcast is denoted in the value of X-BotDistrikt-Source-Id If X-BotDistrikt-Source is `bot`, this means this was just a normal synchronous bot message. This can be ignored if the **Send Message** response output will be used in the custom channel. # Personality Edit your bot's traits, characteristics, platform availability, and shortcut responses that give your bot its unique personality. The **Personality** Dashboard includes 8 sections: 1. **About** 2. **Profile** 3. **Quick Replies** 4. **Platforms** 5. **Settings** 6. **Shortcuts** 7. **Team Members** 8. (Persistent) Bot Preview icon
## About Update your bot's 1. Display Picture 2. Name 3. Description

About Section

To preview how the **Display, Name,** and **About** appear, hover over the tooltip:

Preview Display, Name and About Bot

## Profile Add or update your bot's **Default Stories (**such as **Greeting** and **Fallback\*)** and **Persistent Menu**.

BotDistrikt Bot Profile

{% hint style="info" %} \*Fallback - the bot's default response when it is not trained to respond to the specific question. {% endhint %} To update your BotDistrikt Bot's Profile, begin with updating: 1. **Greeting** Once you click **greeting,** the dashboard navigates to a new greeting in [**Stories**](https://docs.botdistrikt.com/features/stories) on the left-hand panel. The **Story Name** is selected as the default (System) **greeting.**

Update Bot Greeting msg, Fallback and Persistent menu

Example Greeting and Persisten Menu

Greeting (in Personality) --> Update Greeting Message in Stories

1. **Story Name** is selected as the default system **greeting.** 2. **Story Language** is the language that story will be able to converse in. 3. **Send alert to** - To enter email address, click **Add Email** 4. View **Stats** - the number of times your bot greets users. To view details, click on the eye icon . You will be redirected to [**Inbox**](https://docs.botdistrikt.com/features/inbox)**.**
5. To update the **greeting** text, click on the text box. A popup appears on the right-hand side: **Select response type.** 6. **Add** (further) **response** to the chatbot's greeting message. 7. **Add quick reply** - bot's default replies for each new story. 8. **What will the user say next** - add possible user responses. 9. **Cancel** to revert to **Personality** dashboard. 10. Create a **Duplicate** story. 11. Create a [**Broadcast**](https://docs.botdistrikt.com/features/broadcasts)**.** You will be redirected to the **Broadcast** menu in the left-hand side navigation panel to update broadcast schedules. ### Fallback The process to update the **fallback** is the same as the **greeting.** ### Persistent Menu {% hint style="info" %} **Persistent Menu** is the (constant) menu that is displayed when the chatbot session is active. In the BotDistrikt chatbot, the user can access the persistent menu by clicking the hamburger icon. {% endhint %} {% hint style="info" %} For every persistent menu, create a rule in [**Rules**](https://docs.botdistrikt.com/features/rules)**.** You can only set up 3 persistent menu buttons. {% endhint %}

Launch Persistent Menu

Persistent Menu Live Preview

#### Add New Persistent Button To add new persistent button,

Persistent Menu

1. Click the **Add Button** in the **Persistent Menu.** 2. A side menu slides open to list the persistent menu types: **URL, Story, Phone, Text.** #### URL[^1]

URL as Persistent Menu

#### Story

Story as Persistent Menu

To select a story as a persistent menu, ensure the required story is set up in [**Stories**](https://docs.botdistrikt.com/features/stories): 1. Click **Add Button.** 2. Select **Story.** 3. Select a preset story from the dropdown, or click **New Story** to create a new story. You will be redirected to [**Stories**](https://docs.botdistrikt.com/features/stories)**.** **Phone**

Phone Number as Persistent Menu

To select a phone number as a persistent menu: 1. Click **Add Button.** 2. Select **Phone.** 3. Name the menu. 4. Add Phone Number in the textbox. #### Text

Text as Persistent Menu

To select **Text** as a persistent menu: 1. Click **Add Button.** 2. Select **Text.** 3. Name the menu. 4. Add the trigger title as text. ### **Quick Replies** {% hint style="info" %} Your bot's predefined quick replies for each new story. The quick replies are accessible to the user at all times so that the user can click on the quick reply instead of typing a message. {% endhint %} Each quick reply has a dropdown menu to select from * Custom **text** * **Location** * **User\_email** * **User\_phone\_number** * **< return** (to the previous menu) ![Quick Replies](/files/-MCf9qTV-6bLPVJTamjf) Click **Add Quick Reply.**

Add Quick Reply - Quick Replies Dropdown

### Platforms Platforms shortcut display the messaging channels currently available for integration with BotDistrikt. When you connect a messaging platform to your BotDistrikt bot, the icon is highlighted in the logo's (original)color. Clicking on either logo redirects you to [**Integrations**](/messaging-channels/channels-overview). ![Integrated Facebook Messenger/Live Bot](/files/-MCfAnhfazNsSG1Fd2CM) ### Parameter Settings Session parameters is a series of interactions within a given time frame. {% hint style="success" %} **Example:** If the session is set to 10 mins, the bot retains the chat memory for 10 mins. After 10 mins of inactivity, the bot will not pick up from where it had left off and start the chat anew. {% endhint %}

Parameters Settings - Tooltips Explanation

**Access Token** To create **Access Token** for the parameter feature, click **Create**, You will be redirected to a popup confirming access. Once the API Access Token is created, click **View** to view API. ### Shortcuts A shortcut is a replacement for longer text in responses and cards. Use shortcuts to quickly edit variables such as contact number, address, operational hours, etc. To add shortcuts: 1. Click **add shortcut**

Add Shortcut

Enter **Shortcut** and **Replacement** text/information**.** Click ![](/files/CbLV0BWjGNtfOr2IFqCt)to delete the shortcut.

Sample Shortcut

[^1]: # Dashboard Your dashboard monitors, controls, and helps to optimise the performance of your bot Depending on your needs, you can monitor real-time and historical data. As the bot developer, this will help you identify areas for improvement. Subsequently, it helps you customise your bot's personality, stories, responses, conditions, and user segmentation. In addition, our dashboard helps you achieve scalability with increased traffic.
StatisticDescriptionMore Info
New UsersThe number of new unique users who messaged your bot/pages/8RlfqqlKiBGg2WHi3O7R#users
Total UsersThe number of total unique users who messaged your bot/pages/8RlfqqlKiBGg2WHi3O7R#users
SessionsThe number of chat sessions with your bot/pages/8RlfqqlKiBGg2WHi3O7R#sessions
MessagesThe number of messages sent to your bot/pages/8RlfqqlKiBGg2WHi3O7R#messages
ClicksThe number of URL buttons clicked from text and cards/pages/8RlfqqlKiBGg2WHi3O7R#clicks
Average SessionThe average time spent in a single chat session/pages/8RlfqqlKiBGg2WHi3O7R#sessions
Fallback RateThe ratio of times your bot resulted in its fallback message relative to its handled messages/pages/8RlfqqlKiBGg2WHi3O7R#messages
WR RateThe Wrong Response (WR) Rate. The number of messages which triggered wrong responses from your bot/pages/8RlfqqlKiBGg2WHi3O7R#wrong-responses

Bot Channels, Sources, Top Users and Top Stories

You can view new users, total users, number of sessions, messages exchanged, clicks, average session duration, fallback rate, and wrong-response rate. Hover over the analytics to understand the analytics.

Analytics Cards

The graph chart gives a clear overview of the number of Clicks, Users, and Messages. ![Graphicsl Overview of Clicks, Users, and Messages.](/files/-MCzikOSEL7hP3m8nvq3) **Sentiments** The basic sentiment analysis pie chart displays the number of Positive, Negative, and Neutral sentiments that the bot received. {% hint style="info" %} Positive sentiment example: "Good job!", or "Thank you!" Neutral sentiment example: "OK", or "How are you?" Negative sentiment example: "You are not helping me" {% endhint %}

Sentiment Pie Chart

**Channels** The channels graph indicates the number of times your bot is activated on each of your active communication channels/integrations. Example: Website, Whatsapp, Telegram, Skype, Messenger, etc.

Channel Frequency

**Sources** Sources indicate the domain source of where your Website chatbot is coming from. Example: ,

Sources

**Top Users** Top users are your end-users who have interacted the most times with your bot. The dashboard displays the number of messages exchanged with each top user as well.

Top Users with Number of Messages

**Top Stories** Top Stories are your stories created from the **Stories** section that your user most viewed. The dashboard displays the number of stories viewed with each top stories as well.

Top Stories

{% content-ref url="/pages/-LjBoKA8jl6\_dmeiZQnR" %} [Rules](/features/rules) {% endcontent-ref %} # Forms Use the forms to ask a standard set of questions to your users. Use downloadable forms to collect a standard set of responses from your users. Examples: Daily quizzes, user introduction, feedback questionnaires (post-operative feedback questions from patients), lead generation, increased completion rate, etc. * [New Form](/features/forms#new-form) * [Form Name](/features/forms#form-name) * [Intro Message](/features/forms#intro-message) * [Questions](/features/forms#questions) * [Acknowledgment](#acknowledgment) * [Attributes](/features/forms#attributes) * [Validate](/features/forms#validate) * [Free text/Audio](/features/forms#free-text-audio) * [Audio](/features/forms#audio) * [Validate Audio](/features/forms#validate-audio) * [Completion Message](/features/forms#completion-message) * [Keywords Trigger](/features/forms#keywords-trigger) * [Retrieve and Download Responses](#retrieve-and-download-the-answers.). To access **Forms**, navigate to the side panel and click **Forms**.

Forms Dashboard

### New Form Click on the "New Form" button on the top left hand of the page to start creating a new form.

Click New Form

You will be navigated to the **New Form** window. The form editor console is on the left and the form preview is on the right.

New Form

### Form Name Start with the **Form Name**. ![Form Name](/files/-Mg57Ol2aHT3soNn4xzj) ### Intro Message The **Intro Message** introduces the users to the form's purpose. It may even include a link to your privacy policy, data processing and storage policy, etc. To trigger the **Intro Message** textbox, click **Add Intro Message.**

Add Intro Message

![Intro Message](/files/-Mg57g_wTFarlfPnOoCr) ### Questions Proceed to add questions to the form.

Add Questions

1. Add **Question** in text form. 2. Add **Question ID** - A reference word for other questions to skip to this question 3. **Store Answer to** if you choose to store the answer to a stored attribute. 3.1 Choose **Store answer to** or **Don't store** from the dropdown 4. Choose answer form 4.1 **text**, **options** (multiple choice)**, image**, **audio** 5. Select [**Validate**](#validate) if the answer is required in the mentioned format. If the user fails to provide the answer in the required format (for example, no text instead of text) then the question is repeated. 6. Select **Skip to ID** to skip to the next question 7. Choose to **Delete** ![](/files/4ymYqcpm22q8vM2E08LY), **Copy** ![](/files/0IlNvxcS0ja1RxMzLcLo), or **Move** the question position ![](/files/kUOFlSgrFGD7TA9iroV4) ### Acknowledgment Acknowledgments are optional (available in **options** as answer format) Add an acknowledgment to alert the user to incorrect and correct responses. Acknowledgement ### Attributes Attributes save user information and allow reuse in conversations. In BotDistrikt, attributes are the names you assign to collected responses. Every user's answer is stored in an attribute of that name on their user profile. If the attribute is "addition", responses against it will be stored as follows in a user's profile. ![Attributes Stored in Users Profile](/files/-Mg5VsuDPGO8zA5d1WS2) ### Validate **Validate** ensures that the user chooses one of the options provided. If they did not select any of the given options, the chatbot repeats the question until the user selects one of the given options. Validation example ### Audio **Audio** allows your users to answer the question with an audio clip or voice note. ![Audio option](/files/-Mg5WY1QLKOroULjHWG5) ### Validate Audio Audio validation enables the bot to recognize audio notes or voice clips. If the user sends anything else, the bot repeats the question until the user sends audio notes or voice clips. Audio Validation Example ### End Message **End Message** indicates quiz completion. It informs the user that the quiz is over.

End Message

### Keywords Trigger Keyword triggers are keywords that trigger the quiz. Keyword Triggers Example of how the quiz looks like to the end-user. Live Quiz Example ### Retrieve and Download the Answers. Click **Users** on the left navigation panel. 1. Select the users 2. Click Actions 3. Export All to CSV ![Export to CSV](/files/-Mg5_iL1Kj7N-ALQ0MJM) Click on the Download File button Download File Open the CSV file and search for the column that contains the word 'attributes'. ![Response File](/files/-Mg5dJH9kQPsKuu6OWgP) # Rules Rules are your users' questions. Rules are your users' questions mapped to stories (bot's answer). Rearrange rules to prioritize over others. P1 = highest priority.

Rules Dashboard

1. **Filter Rules from Message** enables you to enter a search query and automatically filter its associated Rules. Your search query may contain keywords related to the group name, rule name, or condition properties and values. With just a click or tap, **Reset** allows you to clear the search bar content.

Searching Rules using a Keyword

2. **Show System Rules** allows you to view system rules autogenerated by your bot when toggled. Please be careful when changing these rules as they might affect your chatbot’s operation. 3. **Select Action** dropdown allows you to access the **Export Rules to CSV** function that exports rules to a CSV file that can be downloaded. 4. **New Group** creates a new group in which associated rules can be created or placed under. 5. **New Rule** creates a new rule. If a rule is not created under an existing group, it will be placed in the UNASSIGNED group by default. 6. **Collapse All** enables you to collapse all expanded rule groups and rules.

Collapse all Expanded Rules

7. Shows all existing rules and rule groups. ### Creating a New Group Click on the button and then give your group a name that best represents the rules that will be placed under it. Once done, click **Save**.

Naming your Group

New Group Successfully Created

### Add a Rule There are two ways to create a new rule. * Clicking on creates a rule under the UNASSIGNED rule group. All user-created rules can move between groups by clicking on **Move to group**.
* Clicking on creates a rule under the corresponding rule group.

Rule Group

Creating a Rule in a Rule Group

1. Regardless of which method is used, created rules require a rule name. In this example, create a rule with “Who is your best friend?” as its name (the example indicates preparing rules for users to ask about Bob’s friends). 2. Add the condition. (In this case) set the condition to recognize the keyword(s) “best friend”. 3. Name your story and link the new story to the rule. The story is the *reply to the **question***.

Creating a Rule

![Story Example](/files/-LjBqEVHTI-A4wuqxyOt)

Testing a Rule

### Viewing Rules used in a Story To view all rules used in a particular story, navigate to that story and all the nonlinear and linear rules used will be displayed.

View all Rules used in a Story

To edit a rule used in a story, click on the rule you wish to edit and the rule will automatically be filtered and expanded.

Filtered Rule from a Story

# Conditions A condition is a true/false check on the user’s question. A condition is a TRUE or FALSE check on the user’s question. A rule has many conditions. The rule’s story is selected as the Passing Rule, and if **all** the conditions are met, it's Story is returned as the bot's response. ![](/files/-LjFBwGL2jbdqSL9RYb9) ### **Types of User Context** ![User Context options](/files/-LjFISl1GeolTtDrkBhi) The user context is the data that is specifically assigned to a **Rule.** It determines the context of the message that the users might ask. * **Message** - what a user sends directly to the bot * **Memory** - what a bot remembers previously about the current chat session * **User attribute** - what a bot remembers about a user * **Natural language Processing (NLP)** - what the bot’s NLP engines evaluate a message with. ### Memory At times, a rule does not respond to user's direct message, rather it responds from the interaction history. Example: If we go to the "hey!" story, we can add an "action" response to make the bot remember this. Let's set the action as follows: ``` ACTION type: memory property: said-hey funtion: set to value: true ``` Now when the bot replies to a user with "hey!", the bot actually set a property called "said-hey" to true on chat's session memory. ``` CHAT User: hello there Bot: hey! Bot: (secretly, without telling the user, sets *said-hey* to true in the session) ``` Add a NEW rule with a NEW condition: ``` CONDITION type: memory property: said-hey function: equals value: true ``` and let's assign this to a new story called "You Just Said Hello" Now, the chat will go as follows: ``` CHAT User: hello there Bot: hey! Bot: (secretly, without telling the user, sets *said-hey* to true in the session) User: how are you? Bot: (saw that the property said-hey equals true in the user's chat session) Bot: you just said hello ``` ### Attribute With every **User Context** chosen, there will be an attribute (text, image, video, etc.). The first step to implementing a condition is to select an attribute. The next step is to select a condition that complements the attribute.
### Functions complementing the attribute Every attribute comes with complementing functions.
Below will be a list of the the functions that are available as well as examples of the complementing functions that is available when setting conditions.
FunctionDescription
has keywordThis function checks if the message contains a specific keyword or phrase.
does not have keywordThis checks if a specific keyword or phrase is not present in the message.
equalsThis checks if the message exactly matches a specific value or keyword.
does not equalThis checks if the message does not match a specific value or keyword.
matches regexThis checks if the message matches a regular expression pattern.
existsThis checks if a specific property or value exists in the user’s data.
does not existThis checks if a property or value does not exist in the user’s data.
less thanThis checks if a number is less than another value.
greater thanThis checks if a number is greater than another value.
has tagsThis checks if the user's message has tagged entities.
does not have tagsThis checks if the user's message does not have tagged entities.
is exactlyThis checks if the message exactly matches a specific keyword, as opposed to containing it.
is not exactlyThis checks if the user's message does not exactly match a given keyword or phrase.
has exact tagThis checks if the user's message "is exactly" a tagged entity.
does not have exact tagThis checks if the user's message is not "is exactly" a tagged entity.
is emojiThis checks if the user's message is exactly an emoji.
{% hint style="info" %} For **has tags, does not have tags, has exact tag,** and **does not have exact tag** it is dependant on the tags created under the **Tags Dashboard**. You may visit [**Tags**](https://docs.botdistrikt.com/features/settings/tags) to learn more about the properties of tagging. {% endhint %} ### Examples #### ***has keyword*** "has keyword" is one of the most commonly used functions for the text attribute. It is extremely helpful in FAQs. {% hint style="info" %} 'has keyword' is the only function that supports multiple values. (more than 1 keyword) {% endhint %} ``` "What is the cost of shipping" has keyword "shipping" // true "What are the opening and closing hours of your shop" has keyword "opening,closing" // true "I need help with my account" has keyword "help,account" // true "Can I get a refund for my purchase?" has keyword "refund" // true "Do you offer discounts on bulk orders?" has keyword "discounts,bulk" // true "What is the cost of shipping" has keyword "payment" // false "What are the opening and closing hours of your shop" has keyword "pricing" // false "I need help with my account" has keyword "support" // false "Can I get a refund for my purchase?" has keyword "exchange" // false "Do you offer discounts on bulk orders?" has keyword "single" // false ``` #### ***does not have keyword*** The opposite of the has keyword function. Checks if a property does not have a keyword from the list of declared keywords. ``` "What is the cost of shipping" does not have keyword "payment" // true "What are the opening and closing hours of your shop" does not have keyword "pricing" // true "I need help with my account" does not have keyword "support" // true "Can I get a refund for my purchase?" does not have keyword "exchange" // true "Do you offer discounts on bulk orders?" does not have keyword "single" // true "What is the cost of shipping" does not have keyword "shipping" // false "What are the opening and closing hours of your shop" does not have keyword "opening,closing" // false "I need help with my account" does not have keyword "help,account" // false "Can I get a refund for my purchase?" does not have keyword "refund" // false "Do you offer discounts on bulk orders?" does not have keyword "discounts,bulk" // false ``` #### ***equals*** Equals function prompts the chatbot to find the exact match of the word input. It checks an EXACT match. Used for direct checks. ``` "hello" equals "hello" // true "12345" equals "12345" // true "goodbye" equals "goodbye" // true "openai" equals "openai" // true "2024" equals "2024" // true "hello" equals "HELLO" // false "12345" equals "1234" // false "goodbye" equals "hello" // false "openai" equals "OpenAI" // false "2024" equals "2023" // false ``` #### ***does not equal*** The opposite of the equals function. Checks if a property does not equal a value ``` "hello" does not equal "HELLO" // true "12345" does not equal "1234" // true "goodbye" does not equal "hello" // true "openai" does not equal "OpenAI" // true "2024" does not equal "2023" // true "hello" does not equal "hello" // false "12345" does not equal "12345" // false "goodbye" does not equal "goodbye" // false "openai" does not equal "openai" // false "2024" does not equal "2024" // false ``` #### ***matches regex*** This is the most powerful check. Knowledge of [regular expressions](https://medium.com/factory-mind/regex-tutorial-a-simple-cheatsheet-by-examples-649dc1c3f285) is required to use this function. Used for pattern-matching checks. ``` "hello world" matches regex hello(?=\sworld) // true "hello everyone" matches regex hello(?=\sworld) // false "hello everyone" matches regex hello(?!\sworld) // true "hello world" matches regex hello(?!\sworld) // false "world hello" matches regex (?<=world\s)hello // true "everyone hello" matches regex (?<=world\s)hello // false "everyone hello" matches regex (?

Stories Dashboard

1. ID 2. Story 3. Unique Users who interacted with the story 4. Number of viewers who viewed the story 5. Time spent interacting with the story 6. Average sentiment 7. Links to this (specific) Story 8. Created At 9. View/Duplicate/Delete story ### Add New Story To add a new story, click on the add **new story** button on the top right corner of the page.

New Story button

Add New Story

1. **Story Name** - The name you would give your Story. Example " Greetings", "Seafood Menu", "List of Schools". This is required and important in identifying the story in other parts of the platform. 2. **Story Language** is the language that story will be able to converse in. 3. **Send alert to -** This can be a set to a list of email addresses for notification. 4. **Stats** - Descriptive statistics including total impressions, average sentiment and total time spent in minutes from your users on this story. 5. **Add Response** - Add a [response type ](https://docs.botdistrikt.com/~/changes/0vKpeYfH1kU14HbdearJ/features/responses)to the story. 6. **Add Quick Reply.** 7. **What will they say next?** - Anticipate response and add to the flow in the form of conversation. 8. **Cancel/Duplicate/Broadcast/Delete** story. 9. **Preview/Save** story. ### **Add Response** ![Add Response](/files/-MDnav13GDT0jF4AEj_R) Click on **+add response** to add **text, image, action, webhook, cards,** and **document** responses**.** ![Add Response ](/files/-MDUB_RCx7waPs__JR1E) {% hint style="info" %} Click[ here](https://docs.botdistrikt.com/responses) to find out more about **text, image, action, webhook, cards** and **document.** {% endhint %} **Quick Replies** Quick replies provide a way to present a set of up to 13 buttons in conversation. You can also use quick replies to request a person's location, email address, and phone number. These are like “suggestions” or “autocomplete” tips to help the user decide what to reply. These are dynamic inputs for BotDistrikt. Clicking on a quick reply is the same as typing the text inside.
Click here to add a quick reply
![Example of Quick Replies](/files/-MDnzaAFTsbUsrrfjff8) ![How Quick Replies look like in chats. ](/files/-MDnzh_orEp57wDayiLU) ### Add a Button You may add buttons only to a **text** and **card** response. A button can be linked to the following: * **Website URL** * **Story** * **Phone number** * **Text** ☑️ ***URL*** ![Add a Button](/files/-MDo2qhyHKd94auiK7fP) You may add a URL to the button and when users click on the button, they will be redirected to the URL in a web browser. If you encounter an error, please check that the website starts with HTTP or HTTPS. ️️☑️ ***Story*** ![Story Button](/files/-MDo88OQtWLr__myFOWY) You may link the button to a Story. When the user clicks the button, the story triggers. You may also create a new story here by typing a story name. **☑️ *****Phone*** ![Add Phone](/files/-MDo8HZOKDBkV2S-X3Rn) You may link the button to a phone number. Once the user clicks on the button, they will trigger a phone call to the listed number. Depending on which messaging app is used, the phone call will use the app's phone functionality. The phone number must begin with + followed by the country code. Example +65/+1/+44, etc. **☑️ *****Text*** ![Text Response](/files/-MDo8QEUaPrkpCMDZmQ3) The Text button mimics the quick replies. It is an alternative method of providing quick replies but is tied down to its text or card response. This is beneficial to messaging apps that do not support quick replies but only support buttons. # Update Greeting and Fallback from Personality To update your BotDistrikt Bot's Profile, begin with updating: 1. **Greeting** Once you click **greeting,** the dashboard navigates to a new greeting in [**Stories**](https://docs.botdistrikt.com/features/stories) on the left-hand panel. The **Story Name** is selected as the default (System) **greeting.**

Update Bot Greeting msg, Fallback and Persistent menu

Greeting (in Personality) --> Update Greeting Message in Stories

1. **Story Name** is selected as default system **greeting.** 2. **Send alert to** - To enter email address, click **Add Email.** 3. View **Stats** - the number of times your bot greets users. To view details, click on the eye icon . You will be redirected to [**Inbox**](https://docs.botdistrikt.com/features/inbox)**.** 4. Sample response. 5. **Add Response** - Add a [**response type**](https://docs.botdistrikt.com/features/responses) to the story. 6. **Add Quick Reply.** 7. **What will they say next?** - Anticipate response and add to the flow in the form of conversation. 8. **Cancel/Duplicate/Broadcast** story. The system story (such as greeting and fallback) cannot be deleted. 9. **Preview/Save** story. # Responses There are 7 response types: text, image, action, webhook, cards, document, audio. Responses help you manage all the content your bot can ever message its users - A central CMS of all possible responses from your bot. * To update the **greeting** text, click on the text box or sample text. * A popup appears on the right-hand side: [**Select response type**](https://app.gitbook.com/o/-LirATQOzKxnmLBKTs5a/s/-LirAdLo22OkAW9w3tvY/~/changes/180/overview/personality/select-response-type)**.**

Select Response Type

* To change the **response type**, click on the dropdown. * The dropdown includes the types of greeting messages you can include: **text, image, action, webhook, cards, document,** and **audio.** # Text Your bot's text responses.

Responses - Text

Under the Text tab: * Add a **New Text Response** * Edit existing test response * Delete text response To add New Text Response click **New Text Response**

Add New Text Response

To edit an existing response, click on the story in the **Appears in Stories** column ![](/files/-M0vg1ZC2ySUrPYFKFfK) To delete a response click on ![](/files/25z9X6bu0VIjOGRwzlv8) the row's right-hand side. # Cards Your bot's card responses

Card Responses

Under the Cards tab on the Response page, you will be able to: * Add **New Card** * Edit existing cards * Delete cards To add New Card click on **New Card** ![Add New Card](/files/-M150KY5HD28ylxKwy30) ![Fill in the fields and click "Save"](/files/-M150wy-OE226x0IaAIT) To edit an existing card, click on the card. ![](/files/-M151mZCk_aRLeR2KhXF) To delete a card click on ![](/files/4TF0P9mvGd0hpbwiamGh)on the row's right-hand side. ![click on the trash can icon on the right to delete the card. ](/files/-M152dzdcPOhFewciYPq) # Images All the images that your bot sends.

Add an Image

You can: * Add **New Image** * Delete images To add a new image click on **New Image.**

Add New Image

To delete an image click on ![](/files/v6J3RzrAHOX9rZ3J5gvw) the row's right-hand side. # Videos BotDistrikt bots can send videos, as responses, to your users. Video responses allow your chatbots to provide multimodal communication channels and to demonstrate concepts visually, making it easier for users to understand complex information or instructions. You can incorporate visual aids (diagrams, charts, and animations) to provide clear and concise explanations. Moreover, you can set up your bot to guide your users through processes (setting up a device, using software, or assembling furniture, with easy-to-follow visual instructions. In addition, make your videos accessible with closed captions and transcripts, ensuring that users with disabilities access and understand the content smoothly. This inclusivity is a significant benefit for a diverse user base. To set up video responses, navigate to **Responses** and select **Video.**

Navigate to Responses --> Video

To add new videos, click **New Video**

Add New Video

Add a New Video Process

In the **Videos** tab: 1. Upload the video from your local drive or drop a video in the box. 2. Enter a title for your video. 3. Select tags or add new tags. **New Tag** redirects you to [**Tags**](/features/settings/tags)**.** 4. Click **Save.** # Audios Audio responses enhance the user experience while interacting with your chatbot. While text-based responses are still predominant, incorporating audio responses offers several advantages that significantly benefit end users. Audio responses provide an accessible alternative for users with visual impairments or who prefer auditory content. Moreover, users can consume audio responses while performing other tasks, allowing them to access information and assistance without needing to focus on a screen. It enables your chatbot to convey information using natural language and tone of voice making the interactions feel more human-like and engaging. Whether it is Virtual Assistants, healthcare, educational, informational, or update-based applications, businesses and organizations can create more engaging and inclusive user experiences. To set up video responses, navigate to **Responses** and select **Audio.**

Navigate to Audio

To add new audio, click **New Audio**

Add New Audio

In the **Audios** tab: 1. Upload the audio from your local drive or drop an audio in the box. 2. Enter a title for your audio. 3. Select tags or add new tags. **New Tag** redirects you to [**Tags**](/features/settings/tags)**.** 4. Click **Save.** # Documents All the documents that your bot sends to your users. Sending documents as responses in an AI chatbot offers several advantages to end users. Documents allow chatbots to provide in-depth and comprehensive information on a wide range of topics. Users can access detailed guides, reports, manuals, and more, ensuring they have access to all the necessary details. It enables the presentation of information in a structured format, making it easier for users to navigate and find specific details. Moreover, documents include visual elements such as images, charts, diagrams, and tables, enhancing the understanding of complex information and data. Users can then easily print documents for reference or documentation purposes, making it convenient for tasks that require physical copies and compliance. Chatbots in e-commerce or tech support can provide user manuals, product guides, and troubleshooting documents to help users understand and use products effectively, for educational purposes, or corporate training. It can be used as a versatile tool for disseminating information, assisting with tasks, and enhancing the overall user experience. To set up documents as responses, navigate to **Responses** and select **Documents.**

Navigate to Responses --> Documents

Under the Documents tab on the Response page, you will be able to: * Add new documents * Tag documents * Delete documents To add new documents click on **New Document**

Add New Document

Add New Document

In the **Documents** tab: 1. Upload the document from your local drive or drop a document in the box. 2. Enter a title for your document. 3. Select tags or add new tags. **New Tag** redirects you to [**Tags**](/features/settings/tags)**.** 4. Click **Save.** # Webhooks Webhooks allow your bot to send and receive data to external internet APIs. Webhooks allow you to connect your chatbot to your web services. Pass information from interactions and retrieve the result. Your bot is able to send and receive information from your external internet-connected systems with REST APIs. ![Webhooks](/files/-M0WvoXE-rsUIZJCiWbv) Webhooks empower your chatbot to integrate with numerous external internet-connected systems (emails, business software, ERP and CRM platforms, and helpdesk software.) ## Webhooks Page

Webhooks Dashboard

Your bot uses these webhooks in its stories to: * Send information (generated leads, signups, queries, and emails) * Receive information (status updates, alerts, weather information, and bus timings.) ### Creating a New Webhook To create a new webhook, click on **New Webhook.**

Add New Webhook

Just like any other API definition, a webhook has a request and a response. * The request should be configured on the BotDistrikt platform * The response should be configured on your API server ### **Webhook Request** The webhook's request is configured on the BotDistrikt platform. These are the following fields you have to configure for every webhook. | Field | Description | | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Name** | A unique name to describe what the webhook does | | **Method** | GET or POST | | **URL** | The URL of your API to be called | | **Query Params** | The data parameters to send to your URL. In a GET request, these are sent as *query parameters* directly on the URL, while a POST request, these are sent as *body parameters* in JSON | Here is an example of a webhook configuration that gets a random number

random number webhook

The example above shows a simple webhook that calls the URL with the query params **min=10\&max=20.** ### **Webhook Response** The webhook's response has to be generated by your API server. Every webhook response should be in JSON format, and should contain **at least one** of the following keys: ```json { "responses": [], "memory": {}, "user_attributes": {}, "quickreplies": [], } ``` #### responses `responses` can be an array of strings. These strings add to your bot's response to your user. Take a look at how it is done in this example {% tabs %} {% tab title="Story" %} Let's create a story with a webhook that returns `responses`
{% endtab %} {% tab title="API" %} ![](/files/-M0Ry90RqTz6QMSqK5W8) {% endtab %} {% tab title="Webhook Response" %} ```json { "responses": [ "Here's your random number: 20" ] } ``` {% endtab %} {% tab title="Execution" %} Let's see how the response is displayed to the user
{% endtab %} {% endtabs %} **memory** `memory` should be an object of key-value pairs that are assigned to the user session's memory. Use these keys to remember the user's current session (product or topic they were talking about) or use the memory merge tags in responses. For example: {% tabs %} {% tab title="Story" %} Let's create a story with a webhook that returns `memory`. Notice the merge tag {{memory.favourite-thing}}.
{% endtab %} {% tab title="API" %} ![](/files/-M0S-HMNacFb0zvQIHDL) {% endtab %} {% tab title="Webhook Response" %} ```json { "memory": { "favourite-thing": "cars" } } ``` {% endtab %} {% tab title="Execution" %} Let's see how the response is displayed to the user. Notice the merge tag {{memory.favourite-thing}} is replaced with **cars.**
{% endtab %} {% endtabs %} **user\_attributes** `user_attributes` should be an object of key-value pairs that are assigned to the user's profile. These keys can then be used to segment users in the **Users** dashboard and to create targeted groups for personalized stories and broadcasts. Take a look at this example: {% tabs %} {% tab title="Story" %} Let's create a story with a webhook that returns `memory`. Notice the merge tag {{user.age}}.
{% endtab %} {% tab title="API" %} ![](/files/-M0S3ZYWHEtJhjlZyY1p) {% endtab %} {% tab title="Webhook Response" %} ```json { "user_attributes": { "age": "28" } } ``` {% endtab %} {% tab title="Execution" %} Let's see how the response is displayed to the user. Notice the merge tag {{user.age}} is replaced with **28.**
{% endtab %} {% endtabs %} #### quickreplies `quickreplies` can be an array of strings. These quick replies display as options to your user. Take a look at how it is done in this example {% tabs %} {% tab title="Story" %} Let's create a story with a webhook that returns `quickreplies`. These display as quick replies to the user
{% endtab %} {% tab title="API" %} ![](/files/-M0S5ohBaFtyRKU_PDbM) {% endtab %} {% tab title="Webhook Response" %} ```json { "quickreplies": [ "Chicken", "Fish", "Vegetarian", "Vegan" ] } ``` {% endtab %} {% tab title="Execution" %} Let's see how the response is displayed to the user.
{% endtab %} {% endtabs %} ### Rich Responses You may return rich responses from your webhooks for better user engagement. These responses can include rich components such as buttons, images, cards, documents, audios, and videos. For this, `responses` must be an array of JSON objects instead of an array of strings. The following data structures can be used for rich responses. #### Image response For an image response, use the following data structure ```json { "type": "image", "url": "" } ``` {% tabs %} {% tab title="Story" %}
{% endtab %} {% tab title="API" %}
{% endtab %} {% tab title="Webhook Response" %} ```json { "responses": [ { "type": "image", "url": "https://www.worldatlas.com/upload/6b/40/33/community-development-councils-map-of-singapore.png" } ] } ``` {% endtab %} {% tab title="Execution" %}
{% endtab %} {% endtabs %} #### Text with Buttons response To include buttons within your text response, use the following data structure ```json { "type": "text", "text": "", "buttons": [ { "type": "", "title": "", "payload": "", // required if type is "postback" "url": "" // required if type is "web_url" } ] } ``` {% hint style="info" %} To support most messaging apps, use a maximum of **3 buttons** per text response {% endhint %} {% tabs %} {% tab title="Story" %}
{% endtab %} {% tab title="API" %}
{% endtab %} {% tab title="Webhook Response" %} ```json { "responses": [ { "type": "text", "text": "How would you rate your experience with us?", "buttons": [ { "type": "postback", "title": "👍 Like", "payload": "rating_like_user_227323" }, { "type": "postback", "title": "👍 Dislike", "payload": "rating_dislike_user_227323" }, { "type": "web_url", "title": "🌐 Learn More", "url": "https://mywebsite.com/about-our-rating-system" } ] } ] } ``` {% endtab %} {% tab title="Execution" %}
{% endtab %} {% endtabs %} #### Cards response To display a carousel of cards, use the following data structure ```json { "type": "cards", "elements": [ { "image_url": "", "title": "", "subtitle": "<SUBTITLE>", "buttons": [ { "type": "<postback|web_url>", "title": "<BUTTON_TITLE>", "payload": "<POSTBACK_PAYLOAD>", // required if type is "postback" "url": "<WEBSITE_URL>" // required if type is "web_url" } ] } ], "image_aspect_ratio": "<original|horizontal|square>", // If a messaging app supports it, display cards in a different aspect ratio "page_limit": 8 // defaults to 8 } ``` Cards are paginated by default at 8 cards. If you would like to increase or reduce the number of cards to show per page, change the value of `page_limit` in the webhook response {% hint style="info" %} To support most messaging apps, use a maximum of **3 buttons** per card {% endhint %} {% tabs %} {% tab title="Story" %} <figure><img src="/files/ET6nLsueppUd5Hoh73rF" alt=""><figcaption></figcaption></figure> {% endtab %} {% tab title="API" %} <figure><img src="/files/BHUoTSXPVDN3EBSNlNpe" alt=""><figcaption></figcaption></figure> {% endtab %} {% tab title="Webhook Response" %} ```json { "responses": [ { "type": "cards", "elements": [ { "image_url": "https://www.foodandwine.com/thmb/R29hsuwfvCakNb9E7htyI8fgfrc=/750x0/filters:no_upscale():max_bytes(150000):strip_icc():format(webp)/florentine-butter-chicken-ft-recipe0919-3fef0bddd6614a70b2fe450c11298acb.jpg", "title": "Florentine Butter Chicken", "subtitle": "Butter Chicken from Florence with a twist 🐓", "buttons": [ { "type": "postback", "title": "Order", "payload": "addcart_florentinebutterchicken" }, { "type": "web_url", "title": "Learn More", "url": "https://www.foodandwine.com/travel/europe/italy/italian-main-dishes/florentine-butter-chicken" } ] }, { "image_url": "https://www.foodandwine.com/thmb/g-2_63IdHag2p5Ayhcw2KI04svI=/750x0/filters:no_upscale():max_bytes(150000):strip_icc():format(webp)/farro-mafaldine-with-black-truffle-butter-and-mushrooms-FT-RECIPE1220-71c4d864d58f42b1a1addd91572c9e47.jpg", "title": "Truffle Faro Pasta", "subtitle": "Pair creamy butter, nutty farro pasta, and a fortifying mix of wild mushrooms 🍄", "buttons": [ { "type": "postback", "title": "Order", "payload": "addcart_trufflefaropasta" }, { "type": "web_url", "title": "Learn More", "url": "https://www.foodandwine.com/travel/europe/italy/italian-main-dishes/truffle-faro-pasta" } ] } ] } ] } ``` {% endtab %} {% tab title="Execution" %} <figure><img src="/files/vYBewuLrQrVnOzgA1mYw" alt=""><figcaption></figcaption></figure> {% endtab %} {% endtabs %} #### Document Response To display a document response that a user can download, use the following data structure ```json { "type": "document", "url": "<DOCUMENT_URL>", "name": "<DOCUMENT_NAME>.<FILE_EXTENSION>" } ``` Remember to include the file extension within the document's name to allow the user to open it using the intended file format, e.g. pdf, docx, pptx, txt {% tabs %} {% tab title="Story" %} <figure><img src="/files/7X3SLXTeL8xAAtr7JaU0" alt=""><figcaption></figcaption></figure> {% endtab %} {% tab title="API" %} <figure><img src="/files/fwmc0PZHqerVUO9uyITe" alt=""><figcaption></figcaption></figure> {% endtab %} {% tab title="Webhook Response" %} ```json { "responses": [ { "type": "document", "url": "https://worldofwarships.eu/dcont/fb/document/e7d8b942-142f-11ef-9f3c-b49691e6ead0.pdf", "name": "Contest Conditions.pdf" } ] } ``` {% endtab %} {% tab title="Execution" %} <figure><img src="/files/MfvNy5XBQvf48cbILQzQ" alt=""><figcaption></figcaption></figure> {% endtab %} {% endtabs %} #### Audio response To show a playable audio file to the user, use the following data structure ```json { "type": "audio", "url": "<AUDIO_URL>", "name": "<AUDIO_NAME>.<FILE_EXTENSION>" } ``` Remember to include the file extension within the audio's name to allow the user to open it using the intended file format, e.g. wav, mp3 {% tabs %} {% tab title="Story" %} <figure><img src="/files/qp2FokWdeivlKEsogcji" alt=""><figcaption></figcaption></figure> {% endtab %} {% tab title="API" %} <figure><img src="/files/wlnCWwKCaJhmAr0J0Lwz" alt=""><figcaption></figcaption></figure> {% endtab %} {% tab title="Webhook Response" %} ```json { "responses": [ { "type": "audio", "url": "https://science.nasa.gov/wp-content/uploads/2024/03/48520_E1-PIA26041-The_Sound_of_MOXIE_at_Work_on_Mars.wav", "name": "Secret Code.wav" } ] } ``` {% endtab %} {% tab title="Execution" %} <figure><img src="/files/XvnaF2VUAkv1gO0baQp6" alt=""><figcaption></figcaption></figure> {% endtab %} {% endtabs %} #### Video response To display a playable video file to the user, use the following data structure ```json { "type": "video", "url": "<VIDEO_URL>", "name": "<VIDEO_NAME>.<FILE_EXTENSION>" } ``` Remember to include the file extension within the video's name to allow the user to open it using the intended file format, e.g. mp4, mpg {% tabs %} {% tab title="Story" %} <figure><img src="/files/70BNvJjXHetTETcLMrQh" alt=""><figcaption></figcaption></figure> {% endtab %} {% tab title="API" %} <figure><img src="/files/HGvDipAz9XTMoupSqTIj" alt=""><figcaption></figcaption></figure> {% endtab %} {% tab title="Webhook Response" %} ```json { "responses": [ { "type": "video", "url": "https://i.imgur.com/UDWU7r7.mp4", "name": "Unboxing Camera.mp4" } ] } ``` {% endtab %} {% tab title="Execution" %} <figure><img src="/files/tX4XZq8ArTs6BUxIRZzk" alt=""><figcaption></figcaption></figure> {% endtab %} {% endtabs %} ## Testing Webhooks You may test your webhooks using the Test Webhook button within the webhook editor <figure><img src="/files/Kxf1RYdKsUjHc2DoSKAj" alt=""><figcaption><p>Test Webhook button</p></figcaption></figure> When you click the button, a window will pop up with two panes. The left pane allows you to edit the inputs of the webhook directly, and the right pane shows you the output - the preview of what the webhook's response will look like within the chatbot's response. You can click the **Retest** button below the right pane to refresh the output from the webhook <figure><img src="/files/GQPC3aC8KV50soC6EY1r" alt=""><figcaption></figcaption></figure> Remember to substitute variables within your URL, Headers, Query Params, and JSON Body Params with string values while testing. E.g. if you are sending a variable `{{user.first_name}}` in any of the webhook fields, remember to change it to the user's actual first name, e.g. `John`. The Webhook Tester assumes the strings sent in the request are the final values. # Javascript Functions JavaScript function responses represent a unique and powerful feature in AI chatbots. From e-commerce to travel, healthcare, and finance, you can address an array of use cases and provide valuable solutions to end users. To navigate to set up JavaScript functions as **Responses:** 1. Select between **Condition Functions** and **Action Functions** <figure><img src="/files/yG6iaMdGCILzugWeBh8f" alt=""><figcaption><p>Choose between Condition Functions and Action Functions</p></figcaption></figure> {% hint style="info" %} **Condition functions** and **Action functions** refer to specific function types that allow your chatbot to evaluate conditions and perform actions accordingly. These functions are used to create dynamic and context-aware responses. **Condition functions** typically return a Boolean value (true or false) based on the evaluation. Common use cases for condition functions in AI chatbots include: * **Intent Recognition**: Checking the user's intent. * **Context Awareness**: Evaluating the conversation context. * **Validation**: Verifying user input to ensure it meets certain criteria or constraints. * **Routing**: Deciding which conversation path to follow based on specific conditions. * **User Authentication**: Checking user authentication/specific permissions to perform certain actions. **Action functions** perform specific operations based on the outcome of condition functions or as part of the chatbot's response. These functions execute tasks, update data, or trigger external processes to fulfill the user's request or provide a response. Common use cases for action functions in chatbots include: * **Sending Messages**: Sending text, images, files, or other media as responses to the user. * **API Calls**: Making API requests to external services or databases. * **Database Operations**: Storing or retrieving data from a database. * **Form Submission**: Handling form submissions or user input. * **Calculations**: Data processing. * **Navigation**: Redirecting users to specific sections or pages within the chatbot interface. {% endhint %} 1. Once you choose **Condition** from the template, the description and code sample is updated accordingly: <figure><img src="/files/vWXTwfdqpu9q8DXx5xsi" alt=""><figcaption><p>Example: Condition - Exists</p></figcaption></figure> Depending upon the choice of condition (exists, equals, or matches regex) or action javascript response (enable, delete), test your function according to the conditions set up. <figure><img src="/files/hBvVJ1DCnh8pvFxSXs9v" alt=""><figcaption><p>Test Javascript Response</p></figcaption></figure> **Exists:** For example, if a user inquires about whether X exists on the menu, your bot will use the *exist* function to check. **Equals:** For example, if a user inquires about software updates/weather updates/policy updates, your bot will use the *equal* function to check updates to the said database. **Matches Regex:** For example, when your user introduces themselves with a certain name pattern, then your bot uses *matches regex* to compare name patterns and respond with the name in context. **Enable:** For example, if your user requests your chatbot to *enable* weather forecasts or monthly email notifications for banking statements, then your bot responds with a respective feature enabling it. **Delete:** Similar to the above use case, if the user requests to *delete* a specific file/associated account, then your bot responds with a respective feature deleting it. # Sources Unlock the full potential of your chatbot by integrating external sources such as websites and documents with an external LLM (Large Language Model) engine. This section guides you on how to effortlessly add sources to complement your chatbot's knowledge and capabilities. Whether you want your chatbot to access real-time data, reference academic documents, or stay up-to-date with the latest news, our step-by-step instructions help you seamlessly connect these external resources to your chatbot. You'll be able to harness the vast knowledge of the LLM engine and make your chatbot an even more valuable asset to your users. By the end of this guide, you will have a chatbot that not only understands user queries but can also provide accurate and up-to-date information from the web and various documents. Elevate your chatbot's capabilities with BotDistrikt and start delivering even more personalized and relevant responses. To add a source: 1. Navigate to **Sources** on the left-hand navigation panel 2. Click **OpenAI** in "Link an LLM engine such as [OpenAI](https://flow.botdistrikt.com/bots/722/integrations/openai) to proceed." 3. The Dashboard navigates to **Integrations --> Artificial Intelligence --> OpenAI** 4. Add a valid OpenAI API and **Save.** <figure><img src="/files/x4ZSTo3JuuJBHMglCA6e" alt=""><figcaption><p>Add OpenAI API key</p></figcaption></figure> 5. Ensure **Generate Embeddings for Text Responses** is toggled on. 6. Navigate (again) to **Sources** and the **Sources Dashboard** now includes the ability to add training websites/landing pages and document sources, specific to your bot. # Websites ### **Websites** <figure><img src="/files/eTPhudxOwrnlqcCs0oE2" alt=""><figcaption><p>Add Website and Document Sources</p></figcaption></figure> To add a website, click on **Websites --> New Source Website** <figure><img src="/files/df7gLmzJU59SY2QwvIoe" alt=""><figcaption><p>Add New Source Website</p></figcaption></figure> 1. Enter a **Crawl Base URL** (base URL that the chatbot will crawl to find responses) 2. Click **Crawl** 3. Or enter your website's **Sitemap** 4. Click **Load Sitemap** - you will see a list of the URLs available on the website: <figure><img src="/files/UnOjBn5RsgYRkqaaqbES" alt=""><figcaption><p>List of Sample Sitemap</p></figcaption></figure> Some URLs have viewable responses that you can inspect. Click ![](/files/RtlksLApmpfqnwnA7NLl)beside each URL to inspect. You can view the configuration below the list: <figure><img src="/files/9PU2ic70Z1jjb4iFJqZ3" alt=""><figcaption><p>Sample Configuration of Each URL</p></figcaption></figure> 5. Click **Add** to add individual resources, or 6. **Bulk Add** to add resources in bulk. Click on **Train Added Resources** at the end of the list to add the current loaded URLs to your bot's knowledge base. You will be redirected to your **Sources** dashboard. The added resources are viewable as a list under **Websites.** <figure><img src="/files/oCQuEFcX5xSXsFY8hwep" alt=""><figcaption><p>Added Website Resources</p></figcaption></figure> You can toggle the resource as **Active**, view the current **Training** status, view **Responses, Update** a resource, or **Delete** a URL**.** **Troubleshooting**: * If a file is stuck at queued, ensure that your account has not exceeded the respective tier Response Repo limit. * If a file is stuck at the training phase, click on **Resync Source** <img src="/files/psv4kOM4sjnjgLoPXlUo" alt="" data-size="line"> * If embeddings are not created, ensure that your AI integrated account has not exceeded its token limit. # Documents ### **Documents** To view the documents dashboard, click **Sources --> Documents** (tab) <figure><img src="/files/ADzMd2hZfUGGOBYOtPGi" alt=""><figcaption><p>Documents as Sources</p></figcaption></figure> Click **New Source Document** to add a training document and title. BotDistrikt parses the document into the following information: <figure><img src="/files/79auVE2NLDxrg9WzgevN" alt=""><figcaption><p>Uploaded Training Document</p></figcaption></figure> 1. Specifies **Document Type.** 2. Number of characters in the document. 3. Adjusting the **Chunk Size** changes the character count in a chunk. You can toggle chunk size from the slider or the **Use Recommended** button. A large chunk size retains more context while a small chunk size captures more granular semantic data. 4. **Chunk Overlap** from one chunk to another. You get improved context, a better training model for longer documents, and enhanced coherence. You can increase chunk size if the document consists of numerous unrelated topics. 5. The Output shows the number of responses that will be generated based on the **Chunk Size** and **Chunk Overlap** settings. 6. Click **Show Example Responses** to view sample extracted responses. 7. Click **Train AI** to train your bot with the document. The screen redirects to the main **Sources (Documents)** dashboard. <figure><img src="/files/6YM0MIGiPLiPHm5eLtSi" alt=""><figcaption><p>Uploaded Training Document Dashboard</p></figcaption></figure> To ensure the embeddings are created, go to **Responses** --> **Text** and confirm whether the embeddings are created. The **Embeddings** column displays the LLM name (OpenAI, Vertex AI, etc.). A tick signifies successfully created embedding and a cross signifies no embedding creation for that response. The **Tags** column indicate the source (document/website) <figure><img src="/files/KjyA9K3y5eYFranfi1Ut" alt=""><figcaption><p>Successful Embeddings as Response from OpenAI</p></figcaption></figure> **Troubleshooting**: * If a file is stuck at queued, ensure that your account has not exceeded the respective tier Response Repo limit. * If a file is stuck at the training phase, click on **Resync Source** <img src="/files/psv4kOM4sjnjgLoPXlUo" alt="" data-size="line"> * If embeddings are not created, ensure that your AI integrated account has not exceeded its token limit. # Google Docs ### **Google Docs** <img src="/files/KRT0tzWbH9b8dlZHbC8q" alt="" data-size="line"> To use Google Docs as sources, you must [link your Google Docs account](/business-tools/google-docs). <figure><img src="/files/FrAExZv5JrLO1CN9XZVq" alt=""><figcaption><p>Unlinked Google Docs Dashboard</p></figcaption></figure> 1. After linking your Google Docs account, you can add a Google Doc source by clicking on **New Google Doc**. <figure><img src="/files/0PpNLXLQTKtzgIC9iQX1" alt=""><figcaption><p>Google Docs as Sources</p></figcaption></figure> 2. Search for your document and a dropdown field will appear allowing you to select a document. Click on **Select Doc** once a sheet has been chosen. <figure><img src="/files/lSF9a6y7c0XXWucONTTx" alt=""><figcaption><p>Google Docs Dropdown</p></figcaption></figure> 3. Similarly, you will be able to view the uploaded Google Doc chunking settings and output. <figure><img src="/files/Fe4rN7hkqpwHqKl0Sc5J" alt=""><figcaption><p>Google Docs Chunk Settings</p></figcaption></figure> 4. Click on **Train AI** to use that Google Doc as a source. **Troubleshooting**: * If a file is stuck at queued, ensure that your account has not exceeded the respective tier Response Repo limit. * If a file is stuck at the training phase, click on **Resync Source** <img src="/files/psv4kOM4sjnjgLoPXlUo" alt="" data-size="line"> * If embeddings are not created, ensure that your AI integrated account has not exceeded its token limit. ## GWS Label Lock The GWS Label Lock feature secures and facilities the approval process by ensuring that only files with the designated labels are used for knowledge sourcing. Feature available on request. ### **How to use the label lock** 1. On <img src="/files/hEAP1qMPpwYQzFwWlRzs" alt="" data-size="line">, ensure that you have the necessary admin privileges to utilise the Labels feature, see [Drive Label Admin](https://support.google.com/a/answer/9292382?hl=en). 2. Create a [Google Drive Label](https://support.google.com/a/answer/13127870?hl=en). This is required for the "Label Lock" field to appear. Next, designate **one** **label option** to indicate that the file is ready to be used as a knowledge source. In this example, the designated label option is <img src="/files/E56oktdvvODDPB83JWNz" alt="" data-size="line">. {% hint style="info" %} For the **Apply Label Lock** feature to show, the label type on Google Drive must be a Badged label. <img src="/files/z9R2kCbv8WUhV0YAKkJS" alt="" data-size="original"> {% endhint %} <figure><img src="/files/jx4aEYYHNCAdkkaSPOun" alt=""><figcaption><p>Badged Label Title</p></figcaption></figure> <figure><img src="/files/BBBtCDUsM6kb7upKWHTu" alt=""><figcaption><p>Badged Label Options </p></figcaption></figure> 3. [Apply the Label](https://support.google.com/drive/answer/13495216?hl=en\&co=GENIE.Platform=Desktop) on Google Doc. If the selected file has a label other than the designated label for syncing, i.e. <img src="/files/mh6BnUAm9fHhzJrFfk0p" alt="" data-size="line"> then the file cannot be synced so the current sources of the chatbot won't change. 4. If the GWS Label Lock feature is enabled, you will see the **Apply Label Lock** checkbox when [creating a new Google Doc](/features/sources). Enabling this would allow the file to be used as a knowledge source as long as the label on the file is <img src="/files/E56oktdvvODDPB83JWNz" alt="" data-size="line">. <figure><img src="/files/9k4EA1Ntq9BnSEMn6V0b" alt=""><figcaption><p>Apply Label Lock Checkbox</p></figcaption></figure> **Troubleshooting**: * If the initial labels are not applied, you will get a Sync error and the new content will not be synced for embeddings on the chatbot. <figure><img src="/files/ylaFFLgaHtStUeiAvR7s" alt=""><figcaption><p>Sync Error</p></figcaption></figure> # Google Sheets ### **Google Sheets** <img src="/files/h3CiqUC7VDNXFoZpBx4S" alt="" data-size="line"> To use Google Sheets as sources, you must [link your Google Sheets account](/business-tools/google-sheets). <figure><img src="/files/mvrp2N4oRcI5gRu9QPda" alt=""><figcaption><p>Unlinked Google Sheets Dashboard</p></figcaption></figure> 1. After linking your Google Sheets account, you can add a Google Sheets source by clicking on **New Google Sheet**. <figure><img src="/files/skibX66mYwafQFupxhAY" alt=""><figcaption><p>Google Sheets as Sources</p></figcaption></figure> 2. Search for your spreadsheet and a dropdown field will appear allowing you to select a sheet to be used from that spreadsheet. Click on **Select Sheet** once a sheet has been chosen. <figure><img src="/files/TyFRvE686UjC2cXLH8ab" alt=""><figcaption><p>Google Sheets Dropdown</p></figcaption></figure> 3. Similarly, you will be able to view the uploaded Google Sheet chunking settings and output. <figure><img src="/files/8mGDxiZk9L9dDJOyDYvy" alt=""><figcaption><p>Google Sheets Chunk Settings</p></figcaption></figure> 4. Click on **Train AI** to use that Google Sheet as a source. **Troubleshooting**: * If a file is stuck at queued, ensure that your account has not exceeded the respective tier Response Repo limit. * If a file is stuck at the training phase, click on **Resync Source** <img src="/files/psv4kOM4sjnjgLoPXlUo" alt="" data-size="line"> * If embeddings are not created, ensure that your AI integrated account has not exceeded its token limit. ## GWS Label Lock The GWS Label Lock feature secures and facilities the approval process by ensuring that only files with the designated labels are used for knowledge sourcing. Feature available on request. ### **How to use the label lock** 1. On <img src="/files/hEAP1qMPpwYQzFwWlRzs" alt="" data-size="line">, ensure that you have the necessary admin privileges to utilise the Labels feature, see [Drive Label Admin](https://support.google.com/a/answer/9292382?hl=en). 2. Create a [Google Drive Label](https://support.google.com/a/answer/13127870?hl=en). This is required for the "Label Lock" field to appear. Next, designate **one** **label option** to indicate that the file is ready to be used as a knowledge source. In this example, the designated label option is <img src="/files/E56oktdvvODDPB83JWNz" alt="" data-size="line">. {% hint style="info" %} For the **Apply Label Lock** feature to show, the label type on Google Drive must be a Badged label. <img src="/files/z9R2kCbv8WUhV0YAKkJS" alt="" data-size="original"> {% endhint %} <figure><img src="/files/jx4aEYYHNCAdkkaSPOun" alt=""><figcaption><p>Badged Label Title</p></figcaption></figure> <figure><img src="/files/BBBtCDUsM6kb7upKWHTu" alt=""><figcaption><p>Badged Label Options </p></figcaption></figure> 3. [Apply the Label](https://support.google.com/drive/answer/13495216?hl=en\&co=GENIE.Platform=Desktop) on a Google Sheet. If the selected file has a label other than the designated label for syncing, i.e. <img src="/files/mh6BnUAm9fHhzJrFfk0p" alt="" data-size="line"> then the file cannot be synced so the current sources of the chatbot won't change. 4. If the GWS Label Lock feature is enabled, you will see the **Apply Label Lock** checkbox when [creating a new Google Sheet](/features/sources). Enabling this would allow the file to be used as a knowledge source as long as the label on the file is <img src="/files/E56oktdvvODDPB83JWNz" alt="" data-size="line">. <figure><img src="/files/DMHjSGNH79rYZcQu5x2V" alt=""><figcaption><p>Apply Label Lock Checkbox</p></figcaption></figure> **Troubleshooting**: * If the initial labels are not applied, you will get a Sync error and the new content will not be synced for embeddings on the chatbot. <figure><img src="/files/dcD47NPTduLXxCU2e6DK" alt=""><figcaption><p>Sync Error</p></figcaption></figure> # Users The Users page allows you to manage all the people chatting with your bot. This is BotDistrikt's own Customer Relationship Management (CRM) tool. On this page, filter users by their fields, export user data to CSV, and edit users' attributes and tags in bulk. ![Users Dashboard](/files/-MeTtkEk82GyGUcNoKZI) ### Filters and Actions ![Add Filters](/files/-MERcK8Ry4SbaLT1KYJM) #### Filters ![Filters](/files/-MERmy3ghIaGDUZ1wfaR) To create a filter, you'll need to fill up the **Column, Function** and the **Value** field. **Column** ![Filter Specification](/files/-MERrNTeruwPr4G6W_1u) When you click on the column field, select Profile filters or Attribute filters from dropdown. **Function** ![Filter Dropdown](/files/-MERuRi8HEweSwSWygdi) The function determines the logical expression of the column. **Value** The value depends on the input of the Column and Function field. ![](/files/-MESvEGGUaMvnws-kpLj) In the above example, we have filtered for **First Name, Contains,** Yin Yin. In this case, the **Value** is Yin Yin. ![User Details Filtered](/files/-MESvc0s4-bBM1zWIxf0) This is the result of the filter. The user with the first name Yin Yin is shown. **Actions** <img src="/files/-MESyKnZkDEgJ1zbt7My" alt="Actions Dropdown" width="188"> **Unselect All / Select All** - Used to select or unselect the line items on the page. **Refresh Stats** - Refresh the user's data to get their latest standard fields from the messaging channel, and their updated stats such as messages, sessions, clicks, and time spent. **Add Tags** - You may use this function to add a new tag or select multiple line items and add a tag to all the selected items. ![Tags](/files/-MET5PPOc-LOYKbrMgoc) **Remove Tags** - You may use this function to mass remove tags by selecting multiple line items and clicking the remove button. ![Tags Dropdown](/files/-MET6ridwEbTmHt7RDBS) **Add Attribute** - You may use this function to add an attribute or select multiple line items and add attributes to all the selected items. Attributes are similar to tags. However, with attributes, you can add a tag with a value. For example, email = <johnsmith@gmail.com> means "email" is the tag "<johnsmith@gmail.com>" is the value. It allows you to store custom extended information about your users specific to your chatbot's use cases. For example, if you have users from all over the world, you can have an attribute "country = Malaysia" to filter the subset of users who are from Malaysia. Attributes are great for personalization of a user's chatbot experience with rules, and segmenting subsets of users with broadcasts. ![Attribute](/files/-METHg91blxOH72CAsHk) ![](/files/-MEWksVq56WzmcXu3-x9) **Remove Attribute** - You may use this function to mass remove attributes by selecting multiple line items and clicking the remove button. ![](/files/-MEWuZbzm1AebOo3I_XT) **Delete** - You may use this function to mass delete users by selecting multiple users and confirming the delete action. ![](/files/-MEWvnRvshsrbFj_-CUL) **Export CSV** - You may export your user details in a CSV format, The below notification displays when the export is ready for download. Right-click the "Download File" link and save it to your computer. ![](/files/-MEvT4Gaz9unQNvvyl37) When a live user is selected, an additional action option becomes available called **End Session**. Once clicked, a popup appears confirming whether to end the user's chat session. <figure><img src="/files/fZSKczarzewjQE9U5uGP" alt=""><figcaption><p>Ending a live user chat session</p></figcaption></figure> ### Explanation of the Headers ![](/files/-MEvUMl39WI76qe7m946) ![](/files/-MEvUQBUoOBUvVMPdQ_6) **Name -** You may edit this field for each user. In this column, you can view users' names and edit their profiles. **Channel -** This column represents which channel your users are using to communicate with your bot. Examples of channels are Web chat, Facebook Messenger, and Telegram, etc. ![](/files/-MEvsoqMvbAWC8d2Hnjg) **Sessions -** A session is a group of user interactions with your chatbot that take place within a given time frame. {% hint style="info" %} Every session is limited to 10 minutes. Once there is a period of inactivity beyond 10 mins the session ends. The session time limit can be edited from the [Personality page](https://docs.botdistrikt.com/personality). {% endhint %} **Messages sent** - The number of messages the user sends to your bot. **Clicks -** Total number of URL button clicks **Time Spent** - The amount of time the user has spent on your bot. **Average Sentiment** - The sentiment is derived from words and emojis people send to the chatbot. For example "hahaha" is a positive sentiment, "hello" is a neutral sentiment, and " so slow!" is a negative sentiment. It is translated into a score to help you understand the general sentiment towards your bot. You may view each individual's score to determine what worked and what made them upset. **Last Message At** - The last message that the user sent to the bot. # Edit Users ![Users](/files/-MeVpH50gCo1-zfURTTI) From the Users dashboard, click on the user's name to see this page below. This page contains standard fields that are collected from the users. Such as First and Last name, Contact Details, Notes and Tags. ## Standard Fields ![](/files/-MeVnfYlR0PYkoeI79X_) On the Edit Users page, you will be able to see the standard fields: **Profile Picture**, **Channel**, **Group**, **Created At**, **First Name**, **Last Name**, **Email**, **Phone**, **Timezone**, **Tags**, **Notes,** and the **Pause bot** and **Infinite Session** toggles. **Profile Picture -** A profile picture is the user's profile picture derived from the messaging channel they are using the bot in. This field is automatically populated with the Facebook Messenger and Telegram integrations. You may edit this image for each user. **Channel -** This icon represents which channel your users are using to communicate with your bot. Examples of channels are Web chat, Facebook Messenger, and Telegram, etc. **Group -** It indicates if the user is in a chat group. **Created At** - It shows when the user first started messaging your chatbot. **First Name -** User's first name. This field is automatically populated with the Facebook Messenger and Telegram integrations. You may edit this field for each user. **Last Name -** User's last name. This field is automatically populated with the Facebook Messenger and Telegram integrations. You may edit this field for each user. **Email -** User's email. You may edit this field for each user. **Phone -** User's phone number. This field is automatically populated with the Whatsapp integration. You may edit this field for each user. **Timezone -** The timezone that the user is in. This field is automatically populated with the Skype integration. You may edit this field for each user. **Tags -** A list of tags that are assigned to the user. You may edit this field for each user. **Notes** - Notes that are assigned to this user. You may edit this field for each user. **Pause bot** toggle - This toggle allows you to pause the bot to allow a human to take over the chat. The default pause time is 10 minutes. However, you can edit it on the Personality page. **Infinite Session** toggle - This toggle allows you to extend a user's session with your chatbot indefinitely, bypassing its session length from the Personality page. This is useful for keeping a user's context in memory, such as when letting them fill out a form, or when sending them a survey via a broadcast. ## Custom Fields On the next section of the page, you will see the **Attributes** box. The attributes are Custom Fields you set for your users. ![](/files/-MeVWNO-Zmv_G5-dMGtt) **Attributes** - Attributes are similar to tags. However, with attributes, you will be able to add a tag with a value. For example, email = <johnsmith@gmail.com> means "email" is the tag "<johnsmith@gmail.com>" is the value. It allows you to store custom extended information about your users specific to your chatbot's use cases. For example, if you have users from all over the world, you can have an attribute "country = Malaysia" to filter the subset of users who are from Malaysia. Attributes are great for personalization of a user's chatbot experience with rules, and segmenting subsets of users with broadcasts. ## Stats ![User Stats](/files/-MeVfglFOle3T-nzfYRp) **Sessions -** A session is a group of user interactions with your chatbot that take place within a given time frame. **Messages** - The number of messages the user sent to your bot. **Clicks** - The total number of times the user clicks on any link sent by the bot. **Time Spent -** Total amount of time spent engaging the bot. **emojisAverage Sentiment** - The sentiment is derived from words and emoji people send to the chatbot. For example "hahaha" is a positive sentiment, "hello" is a neutral sentiment while " so slow!" is a negative sentiment. It is translated into a score to help you understand the general sentiment towards your bot. You may view each individual's score to determine what worked and what made them upset. **Last Message -** The last message that the user sent to the bot. **Last Message At** - It shows when the user sent his/her last message to the chatbot. # Delete Users You may delete users directly from the Users Dashboard ![Deleting Users](/files/-MGDDyCtjaU8OxhC--bo) When you delete a user, the following takes place: * The user's `active` attribute gets changed to `false` * The user's past messages get deleted from the Inbox. * The user's past tracked clicks get deleted from Inbox. ## Restricting Content ### Message Activity When a deleted user tries to message your chatbot, they will still be able to access its content. If you would like to prevent deleted users from using your chatbot, it is advisable to add a rule that checks if a deleted user is messaging your bot, and directs them to a story, such as this: ![P1 Rule to check if a deleted user messaged your bot](/files/-MGDEwdCZslXH0CXKEzV) ![Story that responds to the deleted user](/files/-MGDF0aHj9qin6fikGAY) ### Click Activity Furthermore, when a deleted user tries to click on a URL button from a card or text response, they will be redirected to a blank page with this message {% hint style="info" %} Please contact your admin to access this link. {% endhint %} ## Restoring Deleted Users To view all deleted users, you may go to the Users Dashboard, and filter users with `Active equals false` ![Viewing all deleted users](/files/-MGDGLbWL3ITSoAsTaNs) Do note that you will not be able to enter the user's profile once they are deleted. In order to restore a deleted user, you may select the user with the checkbox, and on the top right, go to Select Action > Restore Deleted. When you restore a deleted user, the following takes place: * The user's `active` attribute gets changed to `true` * The user's past messages get restored in the Inbox * The user's past tracked clicks get restored in Inbox After a user has been restored, their messages and clicks will not be restricted anymore. # Dear User A **Dear User** is an incomplete user on your Users dashboard. They are incomplete because the platform is not able to retrieve their profile information from their respective channel. They are identifiable by their first name as **Dear User** ![A Dear User's profile](/files/CeMlwaODPkPuZDpxYFPf) BotDistrikt calls them Dear User by default because when your bot references their first name in a story, the user receives a friendly, non-artificial-looking message anyway. A story referencing a user's name like this: ![Story referencing user's name](/files/Ey4bUlfQBcUGy87PUH57) appears in a generic (friendly) manner like this, even if the bot cannot retrieve their first name. ![A Dear User receives a message like this](/files/uf4CXYc7xmJDCIg13sfN) ## Why They exist for various reasons on different channels. The reasons are listed below ### Telegram A user without a name becomes a **Dear User**, because names are optional on Telegram. ### Instagram A user without a name becomes a **Dear User**, because names are optional on Instagram. ### Facebook Messenger The Facebook Messenger channel includes several plugins which each function on the basis that a user **opts in** to receive automated responses from the bot. A user who opts in via a plugin becomes a Dear User. Facebook does not allow a bot to retrieve a user's public profile information without their consent. #### How to get a user's consent A user consents to give their public profile information when they **send** **a reply** to any of the bot's responses. When a user replies, the platform automatically **upgrades** them from a Dear User to a normal user, allowing you to fetch these fields by refreshing their profile * Profile Picture * First Name * Last Name * Gender (if this feature is [approved](https://developers.facebook.com/docs/messenger-platform/identity/user-profile#requesting-feature-access-to-user-fields-for-the-page) for your page) * Locale (if this feature is [approved](https://developers.facebook.com/docs/messenger-platform/identity/user-profile#requesting-feature-access-to-user-fields-for-the-page) for your page) * Timezone (if this feature is [approved](https://developers.facebook.com/docs/messenger-platform/identity/user-profile#requesting-feature-access-to-user-fields-for-the-page) for your page) The upgrade processes or each plugin is described below | Plugin | A Dear User appears | They are upgraded | | ---------------------------- | --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | | Facebook Chat Plugin | when a user clicks the "Continue as \[NAME]" or "Continue as Guest" button your Chat widget | when they reply, or click on a quick reply or story button from your bot's responses | | Facebook Checkbox Plugin | when a user checks the checkbox on on your website form | when they reply, or click on a quick reply or story button from your bot's responses | | Facebook Private Replies | when a user replies to any of your page's Facebook Posts marked for Comment-to-Messenger | when they reply, or click on a quick reply or story button from your bot's responses | | Login Connect with Messenger | when a user clicks on the Login with Facebook button your website, and allows your page to contact them via Messenger | when they reply, or click on a quick reply or story button from your bot's responses | {% hint style="info" %} Quick replies and buttons are a great way to entice a reply, and therefore an upgrade. {% endhint %} #### Multiple Dear Users for the same person When using multiple Facebook plugins, it is possible for multiple Dear Users to coexist for the same person. It is also possible for one person to be a normal user and a Dear User simultaneously. The fix? Entice your users to reply to your bot, because older Dear Users of the same person automatically get hard-deleted during an upgrade. {% hint style="warning" %} It is **highly encouraged** to entice your users to reply to your bot. This ensures that your billing plan accounts for exactly the same number of persons actually using your bot. {% endhint %} ### Skype When your bot is added to a group on Skype, it becomes a Dear User. However, they will be called a different name - "Channel by \[NAME]", where \[NAME] is the name of the member who added your bot to their group. ## Manual Upgrade It is possible for you to upgrade users from a Dear User to a normal user manually if you have their profile information readily available yourself. You may upgrade users via ### User Profile You may enter a user profile page and edit their first name, last name, and upload their profile picture manually ![](/files/oFmgMS228M8H1AxecfZx) ### Forms You may create a [Form](#undefined) that asks a user to set their *first\_name*, *last\_name*, and upload their *profile\_pic* like this ![Form for Member Details](/files/YGdqM580Aikn4L34LUbp) {% hint style="info" %} If you prefer not to use Forms, you may also set these fields manually in your own stories {% endhint %} ### API You may use the [patchAttributes](https://static.botdistrikt.com/api.html#operation/bot_user.prototype.patchAttributes) or the [upsertWithWhere](https://static.botdistrikt.com/api.html#operation/bot_user.prototype.patchAttributes) bot user API endpoints to upgrade a user in an automated workflow from your own external systems. # Inbox **Inbox** lets you view all the activity happening between your bot and its users. Whether they are sending messages, clicking buttons, or receiving broadcasts, **Inbox** allows you to watch or participate in their conversations. The **Console** is the hub for all your communications. You can filter the **Inbox** with: * **Console** * **Messages** * **Reactions** * **Ratings** * **Clicks** * **Broadcast Records** * **Wrong Responses** <figure><img src="/files/fQQxbll5ECFnDuy9022H" alt=""><figcaption><p>Inbox Dashboard</p></figcaption></figure> # Console Console is where you can watch all of your bot's live chat logs with its users on all messaging channels, and take over the conversation as a live agent. Your bot can handover conversations to live agents, or your live agents can manually jump in and takeover bot conversations any time. <figure><img src="/files/lvqGM4aN2T4IG2WVV5Qv" alt=""><figcaption><p>Console Dashboard</p></figcaption></figure> ## 1) Users Pane In the Console tab, there are 3 panes. The left pane - also called **Users**, is where you can see all the users who are messaging your bot in real time. You can see their * Name * Profile Picture * Time of Last Message * Channel * Online Status marked by a green dot ## 2) Activity Pane When you click into a user, the middle pane (**Activity**), is where you can see all the messages and responses between the selected user and your bot. Under each response from a bot, choose between marking an interaction *correct* or *wrong.* All wrong responses are populated in the [Wrong Responses](/features/inbox/wrong-responses) dashboard. At the bottom of the Activity pane, a text box lets you reply to the user with Text or a Story. ### Enter Text The textbox at the bottom of the middle pane allows you to send a message to the user. At the top left hand corner of the textbox, the dropdown shows available messaging options, Reply with Text, Reply with Story, and Reply with WhatsApp Template if WhatsApp integration is set up. <figure><img src="/files/PkfIOoOI0pEQ0jsdCi1D" alt=""><figcaption><p>Activity Pane (Responding Live)</p></figcaption></figure> In **Reply with Text** mode, enter a message and hit Send. A Takeover Conversation popup will appear giving you two options to: * Send Message and Pause Bot * Send Message Once You can also **Assign an Agent** to the conversation with the dropdown selector. <figure><img src="/files/ebLbAPWBMmCFLPAvVnz1" alt=""><figcaption></figcaption></figure> Once sent, the selected user receives the text you sent inside their chat with your bot. Although the Inbox shows that the response was authored by you, your end users may not. {% hint style="warning" %} Depending on the Messaging Channel, a user may or may not know if a reply came from a human. Therefore, it is a good practice to sign off every message with e.g. " - Admin" {% endhint %} When many team members use the Inbox to reply to your users, BotDistrikt starts recommending your team members' replies as suggestions in the dropdown, if they are similar. More frequently-used suggestions move to the top of the list. ### Send Story <figure><img src="/files/r4kaplPMc0SPYftcj86e" alt=""><figcaption><p>Send Story</p></figcaption></figure> On **Send Story** mode, select an existing story from your bot's stories and hit **Send** to reply to a user with the content of the story. Preview the story as you hover over it in the dropdown. ## 3) User Profile Pane Finally, on the right pane of the Inbox - also called **Profile**, you can get a quick summary of their profile page. <figure><img src="/files/rtb88NZp5XENHe1ClD30" alt="" width="188"><figcaption><p>User Profile</p></figcaption></figure> On this pane, you may proceed with the following: * Toggle Pause Bot for the user to pause/resume the bot. * Assign an Agent - this will assign the respective agent as well as create a Resolution Status dropdown: * Open * Pending * On Hold * Closed * Add or Edit Tags. * Add or Edit User Attributes. * Add or Edit Memory. * For users currently online: * Add or Edit Session Attributes * Reset a Session * Add Notes for any documentation related purpose. # Messages In the messages tab, you can view all conversations in a table format. Every row in the table indicates an interaction, also known as a chat log. This view is useful for * Filtering Chat Logs * Exporting to CSV or UAT * Viewing the Sources of the bot's responses ### Filtering Chat Logs Filter chat logs (on the top of the page) based on several fields. Each field has a specific filter use case. <figure><img src="/files/p0sMYwY0GOu8VFSdz6R7" alt="" width="375"><figcaption><p>Message Tab Filter Options</p></figcaption></figure> <table><thead><tr><th>Field</th><th>Use Case</th><th data-hidden></th></tr></thead><tbody><tr><td>ID</td><td>Finds all chat logs from a specific ID</td><td></td></tr><tr><td>User ID</td><td>Finds all chat logs from a specific user ID</td><td></td></tr><tr><td>Story ID</td><td>Find all chat logs that triggered a specific story ID </td><td></td></tr><tr><td>Recorded At</td><td>Find all chat logs before or after a specific date and time</td><td></td></tr><tr><td>Image</td><td>Find all chat logs that were triggered with an image message</td><td></td></tr><tr><td>Button Click</td><td>Find all chat logs that were triggered by a button click or postback event</td><td></td></tr><tr><td>Message Text</td><td>Find all chat logs containing a specific keyword</td><td></td></tr><tr><td>User Name</td><td>Find all chat logs from a specific user, filterable by the user's name</td><td></td></tr><tr><td>Channel</td><td>Find all chat logs from a specific channel</td><td></td></tr><tr><td>Widget ID</td><td>Find all chat logs with a specific widget ID</td><td></td></tr><tr><td>Story Name</td><td>Find all chat logs that triggered a specific story, filterable by the 's name</td><td></td></tr><tr><td>Sentiment</td><td>Find all chat logs from message with a positive, neutral, or negative sentiment</td><td></td></tr></tbody></table> ### Filtering and Exporting Chat Logs Filter chat logs by clicking on **add filter** and selecting the appropriate attribute and function for the search parameter. To export filtered logs, click on **Select Action** and **Export rows to CSV**. <figure><img src="/files/lNtPozbVMUafjPtw9Kpg" alt=""><figcaption><p>Example of using Message View</p></figcaption></figure> In the Example above, we are filtering all messages before 27th June 2024 containing message text 'gelato' then exporting those messages to a UAT. Export filtered messages to CSV can be done in two ways by using Action > **Export to CSV** or **Export to UAT.**\ \ **Export to CSV** will generate a .csv file with the following fields: <table><thead><tr><th width="239">Fields</th><th>Description</th></tr></thead><tbody><tr><td>ID</td><td>An identifier based on the unique Message ID.</td></tr><tr><td>Date [Timezone]</td><td>This column reflects the timezone of the user exporting the data. For example, if the export is generated in New York, the column will show 'Date [GMT-05:00]'.</td></tr><tr><td>From</td><td>The source or type of user initiating the interaction such as user or bot.</td></tr><tr><td>From ID</td><td>A unique identifier for the sender such as user ID or bot ID.</td></tr><tr><td>From Name</td><td>Displays only the sender's display name.</td></tr><tr><td>Message</td><td>The content of the message exchanged during the interaction.</td></tr><tr><td>Reached Fallback</td><td>Indicates whether the interaction triggered a fallback response where "Y" stands for yes or "N" for no.</td></tr><tr><td>Story ID</td><td>A unique identifier for the story associated with the interaction.</td></tr><tr><td>Story Name</td><td>The name or title of the story.</td></tr><tr><td>Sentiment Value</td><td>A numerical score representing the sentiment of the user's message ranging from -1 for negative, 0 for neutral, and 1 for positive.</td></tr><tr><td>Sentiment</td><td>The sentiment category derived from the sentiment value such as positive, neutral, or negative.</td></tr><tr><td>Channel</td><td>The platform or medium through which the interaction occurred.</td></tr><tr><td>Widget ID</td><td>Only applies to Website Bot Widgets and cannot be used for Messaging Apps.</td></tr><tr><td>Chat History Link</td><td>A URL or link to access the complete chat history for the interaction.</td></tr></tbody></table> **Export to UAT** will generate a .csv file with the following fields: <table><thead><tr><th width="240">Field</th><th>Description</th></tr></thead><tbody><tr><td>ID</td><td>An identifier based on the unique Message ID.</td></tr><tr><td>Description</td><td>The name or title of the story.</td></tr><tr><td>Message</td><td>The content of the message exchanged during the interaction.</td></tr><tr><td>Memory</td><td>This refers to the bot’s memory context and can be used to simulate data that the bot remembers from the user’s conversation.</td></tr><tr><td>User</td><td>This refers to the user context, enabling simulation of an existing user on BotDistrikt or a new user with attributes defined via variables.</td></tr><tr><td>Refresh</td><td>This acts as a caching identifier. When a response is retrieved, it is cached for 10 minutes. Changing this value forces the cache to clear and recomputes the response.</td></tr><tr><td>Expected Response</td><td>The anticipated output or behaviour from the bot for the given input and context.</td></tr><tr><td>Actual Response</td><td>The actual output or behaviour observed from the system during the test.</td></tr><tr><td>Actual = Expected? (Y/N):</td><td>A validation field to confirm if the actual response matches the expected response.</td></tr><tr><td>Developer Comments</td><td>Additional notes or observations from the developer regarding the test case or discrepancies found.</td></tr></tbody></table> {% hint style="info" %} This is useful for generating extensive end-to-end automated regression tests for the chatbot using the BotDistrikt Auto-UAT Feature, available to Enterprise customers only. Please get in touch with <hello@botdistrikt.com>. {% endhint %} ### Viewing the Sources of the bot's responses The viewing of sources would provides context-aware answers to user queries. To enable this feature, you must first connect an LLM integration, such as OpenAI or other supported models followed by training the LLM using relevant [**Sources**](/features/sources). Each generated response includes a **confidence level**, which indicates how certain the model is about the accuracy of the response based on the provided sources. * Higher confidence: Indicates a high similarity score between the user’s message and retrieved sources. However, this does not mean the response is relevant. * Lower confidence: Indicates a low similarity score between the user’s message and retrieved sources. However, this does not mean the response is irrelevant. You can view generated response from the Messages tab by hovering over the generated response text and clicking view responses. <figure><img src="/files/hJ5Py7Ig6vtb9VjYK5Y1" alt=""><figcaption><p>Viewing Generated Responses</p></figcaption></figure> You can also view the sources to determine how the information is being derived from. This will bring you to the source material. # Reactions User reactions refer to emoji responses, such as thumbs up (👍) or thumbs down (👎), which can be collected through BotDistrikt's Website Widget and integrations with messaging channels, including WhatsApp, Telegram, Facebook, and Instagram. This is useful for monitoring your users sentiments in terms of reactions through conversations presented through your bot. This page can also be used for * Filtering Reactions * Exporting to CSV Below each of your bot's responses, there will be a thumbs up icon to indicate a Good response, and a thumbs down icon for Bad response. These icons allow users to indicate whether the response is useful or not. <figure><img src="/files/yOPVi02pgS0UqQoi8MJr" alt="" width="375"><figcaption><p>Thumbs Up and Thumbs Down Icons</p></figcaption></figure> After clicking on a reaction icon, the user will be prompted to provide feedback for their selection. <figure><img src="/files/88QWL4P6znNRhinqmF7g" alt="" width="375"><figcaption><p>Response Feedback</p></figcaption></figure> For messaging integrations, user responses can be collected from native emoji reactions. <figure><img src="/files/Q8JtKS9SEHjrxVbfA4ec" alt="" width="375"><figcaption><p>A User Reacting to a Message on Telegram</p></figcaption></figure> All recorded reactions will appear in the Reactions dashboard under **Inbox > Reactions**. Here, you can view, filter, and export reactions for further analysis. <figure><img src="/files/nsri6kmJ3K7KynYQzy3n" alt=""><figcaption><p>Recorded User Reactions</p></figcaption></figure> To view reactions in context, click on <img src="/files/Tg0XZ6S0n2mhaNWttafO" alt="" data-size="line">. The expanded interaction cell shows the chatbot's response that got reacted to in the context of the chat history. <figure><img src="/files/RFSYGIlPegaEu3XIEOsS" alt=""><figcaption><p>View Interaction</p></figcaption></figure> ### Filtering Reactions Use the Filters on the top of the page to filter Reaction based on several fields. Each field has a specific filter use case. <figure><img src="/files/2ELBSKPVqtSqINzItVYJ" alt=""><figcaption><p>Reactions Tab Filter Options</p></figcaption></figure> <table><thead><tr><th width="211">Field</th><th>Use Case</th></tr></thead><tbody><tr><td>User ID</td><td>Finds all reactions associated with a specific user ID.</td></tr><tr><td>User Name</td><td>Find all reactions from a specific user, filterable by the user's name.</td></tr><tr><td>Channel</td><td>Finds all reactions on a specific platform.</td></tr><tr><td>Widget ID</td><td>Finds all reactions linked to a specific widget. Only applies to Website Bot Widgets and cannot be used for Messaging Apps.</td></tr><tr><td>Reaction</td><td>Finds all user reactions to filter responses specifically containing Thumbs Up (👍) or Thumbs Down (👎) emojis.</td></tr><tr><td>Emoji</td><td>Finds all emojis used to filter reactions based on specific emojis, enabling more granular analysis of user responses.</td></tr><tr><td>Feedback</td><td>Finds all user-provided feedback to filter and analyze the text content.</td></tr><tr><td>Recorded At</td><td>Find all reactions made before or after a specific date and time.</td></tr></tbody></table> ### Exporting as CSV Filter reaction logs by clicking on **add filter** and selecting the appropriate attribute and function for the search parameter. To export filtered logs, click on **Select Action** and **Export rows to CSV**. <figure><img src="/files/81NDiAjEzBHZdD5OKnrV" alt=""><figcaption><p>Example of Exporting Reactions</p></figcaption></figure> **Export to CSV** will generate a .csv file with the following fields: <table><thead><tr><th width="181">Field</th><th>Description</th></tr></thead><tbody><tr><td>ID</td><td>An identifier based on the unique Message ID.</td></tr><tr><td>Reaction</td><td>Displays the user's reaction to the bot's response.</td></tr><tr><td>Feedback</td><td>Any additional input or remarks provided by the user regarding the interaction.</td></tr><tr><td>Message</td><td>The user's message during the interaction.</td></tr><tr><td>Response</td><td>The bot's response to the user's message during the interaction.</td></tr><tr><td>User ID</td><td>A unique identifier assigned to the user.</td></tr><tr><td>User</td><td>The display name or alias of the user involved in the interaction.</td></tr><tr><td>Channel</td><td>The platform or medium through which the interaction occurred.</td></tr><tr><td>Widget ID</td><td>Only applies to Website Bot Widgets and cannot be used for Messaging Apps.</td></tr><tr><td>Date [Timezone]</td><td>This column reflects the timezone of the user exporting the data. For example, if the export is generated in New York, the column will show 'Date [GMT-05:00]'.</td></tr><tr><td>Chat History Link</td><td>A URL or link to access the complete chat history for the interaction.</td></tr></tbody></table> ### Toggling Message Reactions Collect Message Reactions can be toggled on and off at the Widget level. To access the toggle, go to **Integrations** > **Website**. If the Collect Message Reactions toggle is inactive, the reaction feature (e.g., thumbs up or thumbs down) will not be available for that specific website widget chatbot. {% hint style="info" %} This functionality is only applicable to the BotDistrikt Website Widget. Message reactions cannot be toggled on or off for messaging app integrations such as WhatsApp, Telegram, Facebook, or Instagram. {% endhint %} <figure><img src="/files/bXtXXk4iNa5asyMnki7w" alt=""><figcaption><p>Navigating to Message Reactions Toggle</p></figcaption></figure> <figure><img src="/files/Ibk3md5nHAMyQmmptMXB" alt=""><figcaption><p>Collect Message Reactions Toggle</p></figcaption></figure> # Ratings User ratings can be recorded through BotDistrikt's Website Chatbot Widget, providing valuable insights into user satisfaction. This feature is a key tool for monitoring user satisfaction and evaluating the effectiveness of conversations delivered through your bot. In this page, admins could filter through ratings as well as exporting the data in CSV. {% hint style="info" %} Note that **this functionality applies only to the Website Chatbot Widget** and i**s not available for Messaging App integrations such as WhatsApp, Telegram, Facebook Messenger, or Instagram.** {% endhint %} ### **How Ratings Are Collected** * The rating screen is displayed in the following scenarios: 1. When the user **closes the chat** by pressing the **X button**. 2. When the user **clicks "Restart"** to begin a new chat session. * At this point, the user can: * Select a star rating (1 to 5). * Provide optional text feedback about their experience. <figure><img src="/files/rCMskV9GJKHF65VIHbdH" alt="" width="375"><figcaption><p>User Rating on Session Close</p></figcaption></figure> After a rating is submitted, it will be visible in **Inbox** **> Ratings**. Recorded ratings can be filtered by all column categories and exported to CSV. <figure><img src="/files/Njh1RGVLElzf9JOx30h1" alt=""><figcaption><p>Recorded User Ratings</p></figcaption></figure> ### Filtering Ratings Use the Filters on the top of the page to filter ratings based on several fields. Each field has a specific filter use case. <figure><img src="/files/3PqzdUpLHgz22SpXFPdO" alt=""><figcaption><p>Ratings Tab Filter Options</p></figcaption></figure> <table><thead><tr><th width="210">Field</th><th>Use case</th></tr></thead><tbody><tr><td>User ID</td><td>Finds all ratings associated with a specific user.</td></tr><tr><td>User Name</td><td>Find all ratings from a specific user, filterable by the user's name.</td></tr><tr><td>Channel</td><td>Finds all ratings on a specific platform.</td></tr><tr><td>Widget ID</td><td>Finds all ratings linked to a specific widget. Only applies to Website Bot Widgets and cannot be used for Messaging Apps.</td></tr><tr><td>Rating</td><td>Finds all ratings provided by users.</td></tr><tr><td>Feedback</td><td>Finds all user-provided feedback.</td></tr><tr><td>Recorded At</td><td>Find all reactions made before or after a specific date and time.</td></tr></tbody></table> ### Exporting to CSV Filter rating logs by clicking on **add filter** and selecting the appropriate attribute and function for the search parameter. To export filtered logs, click on **Select Action** and **Export rows to CSV**. <figure><img src="/files/XBsW9JySK87b43cR9Ebk" alt=""><figcaption></figcaption></figure> **Export to CSV** will generate a .csv file with the following fields: <table><thead><tr><th width="216">Field</th><th>Description</th></tr></thead><tbody><tr><td>ID</td><td>An identifier based on the unique Message ID.</td></tr><tr><td>Rating</td><td>The score over 5 that the user provides to rate the bot's response or interaction quality.</td></tr><tr><td>Feedback</td><td>Any additional input or remarks provided by the user regarding the interaction.</td></tr><tr><td>User ID</td><td>A unique identifier assigned to the user.</td></tr><tr><td>User</td><td>The display name or alias of the user involved in the interaction.</td></tr><tr><td>Channel</td><td>The platform or medium through which the interaction occurred.</td></tr><tr><td>Widget ID</td><td>Only applies to Website Bot Widgets and cannot be used for Messaging Apps.</td></tr><tr><td>Date [Timezone]</td><td>This column reflects the timezone of the user exporting the data. For example, if the export is generated in New York, the column will show 'Date [GMT-05:00]'.</td></tr><tr><td>Chat History Link</td><td>A URL or link to access the complete chat history for the interaction.</td></tr></tbody></table> ### Toggling Ratings Collect Ratings can be toggled on and off at the Widget level. To access the toggle, go to **Integrations** **> Website**. If the Collecting Ratings toggle is inactive, users will not be prompted to rate their experience on session close. If it is turned on, the ratings feature will only apply to that website chat widget. <figure><img src="/files/shqU9VfP8NQhwt6Ysx32" alt=""><figcaption><p>Navigating to Ratings Toggle</p></figcaption></figure> <figure><img src="/files/Sdzapg08A6wAy5zWmPbI" alt=""><figcaption><p>Collect Ratings Toggle</p></figcaption></figure> # Clicks Inbox Clicks is where you can track all the URL button clicks from your chatbot users. <figure><img src="/files/JL2WQlRcurDVCQCIOl1p" alt=""><figcaption><p>Clicks Dashboard</p></figcaption></figure> Every time a user of your bot clicks on a specific URL button, BotDistrikt tracks * The identity of the user who clicked it * Their IP address * Their Browser User-Agent * Their Device * Which URL button they clicked, and chat component source. * Whether the click was made organically, or was made because of a broadcast * The URL they visited * The date and time of the click This is useful for monitoring how active your users are in terms of clicking through web content presented through your bot. This page can also be used for * Filtering Clicks * Exporting to CSV ### Filtering Clicks Use the Filters on the top of the page to filter clicks based on several fields. Each field has a specific filter use case <table><thead><tr><th width="177.7379404721177">Field</th><th>Use Case</th></tr></thead><tbody><tr><td>User ID</td><td>Finds all clicks from a specific user ID</td></tr><tr><td>Card ID</td><td>Find all clicks from a specific card ID</td></tr><tr><td>Audio ID</td><td>Find all clicks from a specific audio ID</td></tr><tr><td>Broadcast ID</td><td>Find all clicks that were made because of pushed-notifications from a broadcast ID</td></tr><tr><td>Response Text ID</td><td>Find all clicks from a response text ID</td></tr><tr><td>User Name</td><td>Find all clicks from a specific user, filterable by the user's name </td></tr><tr><td>Card Title</td><td>Find all clicks from a specific card, filterable by the card's title</td></tr><tr><td>Response Text</td><td>Find all clicks from a specific response text, filterable by the text</td></tr><tr><td>Audio Title</td><td>Find all clicks from a specific audio, filterable by the audio's name</td></tr><tr><td>Visited URL</td><td>Find all clicks that visited a specific URL or a URL that contains some keywords</td></tr><tr><td>Recorded At</td><td>Find all clicks made before or after a specific date and time</td></tr></tbody></table> ### Exporting as CSV Export filtered clicks to CSV with Actions > Export to CSV # Broadcast Records Broadcast Records let you track which users have received from your broadcasts, including the receipt status for every single user who has received it. <figure><img src="/files/HKYjFJQLk2vmMSQXFMsU" alt=""><figcaption><p>Broadcast Records Dashboard</p></figcaption></figure> Every time you publish a broadcast, BotDistrikt tracks a **receipt** - also known as a Broadcast Record, for each user. For each record, BotDistrikt tracks * The identity of the user who received it * The date and time that the user received it * The status of the receipt, whether it was **completed** or an **error** * If the broadcast status is **error** * The accompanying error message explaining why there was an error * Latency - the difference between the time the broadcast was scheduled and the time the user received it ### Receipt of what a user received <figure><img src="/files/kb7KawuZpE9epSyxDoK0" alt=""><figcaption><p>Broadcast Records Dashboard</p></figcaption></figure> Hover over a record to see what a user received during the broadcast. Each user receives a unique personalized message based on the variables you use in the message. Use the Broadcast Records page to: * Filter Broadcast Records * Export to CSV ### Filtering Broadcast Records Use the Filters on the top of the page to filter records based on several fields. Each field has a specific filter use case. <figure><img src="/files/0EiMz5NsorSUsfrSIYgm" alt=""><figcaption><p>Broadcast Tab Filter Options</p></figcaption></figure> <table><thead><tr><th width="177.7379404721177">Field</th><th>Use Case</th></tr></thead><tbody><tr><td>ID</td><td>Finds all records from a specific ID</td></tr><tr><td>Broadcast ID</td><td>Find all records a specific broadcast ID</td></tr><tr><td>User ID</td><td>Finds all records from a specific user ID</td></tr><tr><td>Story ID</td><td>Find all records publishing a broadcast of a specific story ID</td></tr><tr><td>Story Name</td><td>Find all records publishing a broadcast of a specific story, filterable by the story's name</td></tr><tr><td>User Name</td><td>Find all broadcast sent to a specific user, filterable by the user's name </td></tr><tr><td>Status</td><td>Find all broadcast records of a status <strong>completed</strong> or <strong>error</strong></td></tr><tr><td>Message</td><td>Find all broadcast records of status <strong>error</strong> with a specific of filterable error message</td></tr><tr><td>Recorded At</td><td>Find all records received before or after a specific date and time</td></tr><tr><td>Number of Responses</td><td><p>Sometimes when a broadcast publishes a story that uses only 1 webhook to get a dynamically generated response, the webhook might return no responses for a specific user. </p><p>Filter by Number of Responses greater than 0, to filter only those users who received a message</p></td></tr></tbody></table> ### Exporting as CSV Filter broadcast records by clicking on add filter and selecting the appropriate attribute and function for the search parameter. To export filtered records, click on Select Action and Export rows to CSV. <figure><img src="/files/g3eMGFy8Cy89ImTnno6D" alt=""><figcaption><p>Example of Exporting Broadcast</p></figcaption></figure> **Export to CSV** will generate a .csv file with the following fields: <table><thead><tr><th width="260">Field</th><th>Description</th></tr></thead><tbody><tr><td>ID</td><td>An identifier based on the unique Broadcast ID.</td></tr><tr><td>User ID</td><td>A unique identifier assigned to the user.</td></tr><tr><td>User</td><td>The display name or alias of the user.</td></tr><tr><td>Received Broadcast ID</td><td>The unique identifier of the broadcast received by the user.</td></tr><tr><td>Broadcast Time</td><td>The timestamp of when the broadcast was sent.</td></tr><tr><td>Story ID</td><td>A unique identifier for the story associated with the interaction.</td></tr><tr><td>Story Name</td><td>The name or title of the story.</td></tr><tr><td>Status</td><td>Indicates the current state of the interaction.</td></tr><tr><td>Message</td><td>The content of the message exchanged during the interaction.</td></tr><tr><td>Created At</td><td>The timestamp of the interaction.</td></tr></tbody></table> {% hint style="warning" %} BotDistrikt's broadcast functionality has a default push configuration of * 5 Maximum Retries * 0.1s Backoff View up to 5 Broadcast Records with errors for the same user because the platform attempted to retry a failed broadcast to the user 5 times {% endhint %} {% hint style="info" %} For **Enterprise** customers, the push configuration is customizable. {% endhint %} # Wrong Responses The *Wrong Responses* dashboard serves as an in-built issue tracker, similar to JIRA, designed for BotDistrikt chatbots. It allows you to track users who have received incorrect responses and set conditions to manage and resolve these issues accordingly. ### Marking Message as Wrong Response To mark a message as a wrong response, navigate to **Inbox** > **Console**. In the user activity window there will be a dropdown arrow with the default 'correct' text below the message. Clicking on the dropdown will allow you to mark the message as wrong. To access the **Wrong Responses** tab, click on the red arrow. <figure><img src="/files/iqhPtlMozCaK1Uu9aQfd" alt=""><figcaption><p>Marking a Message as a Wrong Response</p></figcaption></figure> <figure><img src="/files/1du4S2j3cBhCUIxhvZi8" alt=""><figcaption><p><strong>Wrong Responses D</strong>ashboard</p></figcaption></figure> Every time a user receives a wrong response, BotDistrikt tracks the message. The **Wrong Responses** dashboard includes: * Filter Wrong Responses * Mark Response Status * Acknowledge * Resolving * Resolved * Ignored * Issue Fields * Tags * Agents * Set Due Date * Write Notes * Set Priority Levels * Replay the Response * Export to CSV ### Filtering Wrong Responses Use the Filters on the top of the page to filter records based on several fields. Each field has a specific filter use case. <figure><img src="/files/K8d0ubaYVx6IvnNczPm3" alt=""><figcaption><p>Broadcast Tab Filter Options</p></figcaption></figure> <table><thead><tr><th width="249">Field</th><th>Use case</th></tr></thead><tbody><tr><td>ID</td><td>Finds all wrong responses from a specific ID</td></tr><tr><td>Assigned to</td><td>Finds all wrong responses assigned to a specific team member</td></tr><tr><td>Created by</td><td>Finds all wrong responses created by a specific team member</td></tr><tr><td>Updated by</td><td>Finds all wrong responses updated by a specific team member</td></tr><tr><td>Created At</td><td>Finds all wrong responses created at a specific time or date</td></tr><tr><td>Updated At</td><td>Finds all wrong responses updated at a specific time or date</td></tr><tr><td>Due At</td><td>Finds all wrong responses with specific deadlines</td></tr><tr><td>Status</td><td>Finds all wrong responses based on their current status</td></tr><tr><td>Priority</td><td>Finds all wrong responses categorised by urgency or importance</td></tr><tr><td>Tags</td><td>Finds all wrong responses labeled with specific tags</td></tr><tr><td>Notes</td><td>Finds all wrong responses with attached notes</td></tr></tbody></table> ### Mark Response Status Team members can update the status of a wrong response to track its resolution progress. <figure><img src="/files/FoLE5RBAMgWFDvayWmej" alt=""><figcaption><p>Marking statuses</p></figcaption></figure> The available statuses include: * **Acknowledge** * All wrong responses are automatically marked as "Acknowledged" when logged. * **Resolving** * Set this status when actions are actively being taken to fix the issue. * **Resolved** * Mark the response as resolved when the issue has been fixed and verified. * **Ignored** * Use this status for issues that do not require further action. ### Issue Fields The **Issue Fields** feature allows team members to add specific attributes to the wrong responses. The following types of fields are supported: <figure><img src="/files/E6vhHO4CP6tOFVYmrc7h" alt=""><figcaption><p>Managing Issue Fields</p></figcaption></figure> <table><thead><tr><th width="237">Issue Fields</th><th>Description</th></tr></thead><tbody><tr><td>1) Notes</td><td>This allows team members to attach detailed comments to a response. Notes can include observations, explanations, or instructions for other team members.</td></tr><tr><td>2) Tags</td><td><a href="https://docs.botdistrikt.com/features/settings/tags">Tags</a> provide a way to categorize and organize responses by assigning descriptive labels.</td></tr><tr><td>3) Assigned to</td><td>This enables the assignment of individual team members to manage specific logs or responses.</td></tr><tr><td>4) Due Date</td><td>This ensures that deadlines are established for resolution.</td></tr><tr><td>5) Priority</td><td><p>Priority levels help classify responses based on their urgency and importance ranging from P0 to P3.<br></p><p>P0 - Critical Priority<br>P1 - High Priority<br>P2 - Medium Priority<br>P3 - Low Priority</p></td></tr><tr><td>6) Actions</td><td>There are two buttons: Replay Message as well as Delete.<br><br>Replay Message - Allows team members to simulate the corrected response in the same scenario where the wrong response occurred.<br><br>Delete - Allows team members to delete the wrong response.</td></tr></tbody></table> <figure><img src="/files/qKo0LPTzV7n1ougCR2CQ" alt=""><figcaption><p>Replaying a Message Marked as a Wrong Response</p></figcaption></figure> ### Exporting to CSV Filter wrong responses by clicking on add filter and selecting the appropriate attribute and function for the search parameter. To export filtered records, click on Select Action and Export rows to CSV. <figure><img src="/files/MvBBlTMfly5putGg3SS8" alt=""><figcaption><p>Example of using Export actions</p></figcaption></figure> Export filtered messages to CSV can be done in two ways by using Action > **Export to CSV** or **Export to UAT.** **Export to CSV** will generate a .csv file with the following fields: <table><thead><tr><th width="239">Fields</th><th>Description</th></tr></thead><tbody><tr><td>ID</td><td>An identifier based on the unique Message ID.</td></tr><tr><td>Date [Timezone]</td><td>This column reflects the timezone of the user exporting the data. For example, if the export is generated in New York, the column will show 'Date [GMT-05:00]'.</td></tr><tr><td>From</td><td>The source or type of user initiating the interaction such as user or bot.</td></tr><tr><td>From ID</td><td>A unique identifier for the sender such as user ID or bot ID.</td></tr><tr><td>From Name</td><td>Displays only the sender's display name.</td></tr><tr><td>Message</td><td>The content of the message exchanged during the interaction.</td></tr><tr><td>Reached Fallback</td><td>Indicates whether the interaction triggered a fallback response where "Y" stands for yes or "N" for no.</td></tr><tr><td>Story ID</td><td>A unique identifier for the story associated with the interaction.</td></tr><tr><td>Story Name</td><td>The name or title of the story.</td></tr><tr><td>Sentiment Value</td><td>A numerical score representing the sentiment of the user's message ranging from -1 for negative, 0 for neutral, and 1 for positive.</td></tr><tr><td>Sentiment</td><td>The sentiment category derived from the sentiment value such as positive, neutral, or negative.</td></tr><tr><td>Channel</td><td>The platform or medium through which the interaction occurred.</td></tr><tr><td>Widget ID</td><td>Only applies to Website Bot Widgets and cannot be used for Messaging Apps.</td></tr><tr><td>Chat History Link</td><td>A URL or link to access the complete chat history for the interaction.</td></tr></tbody></table> **Export to UAT** will generate a .csv file with the following fields: <table><thead><tr><th width="240">Field</th><th>Description</th></tr></thead><tbody><tr><td>ID</td><td>An identifier based on the unique Message ID.</td></tr><tr><td>Description</td><td>The name or title of the story.</td></tr><tr><td>Message</td><td>The content of the message exchanged during the interaction.</td></tr><tr><td>Memory</td><td>This refers to the bot’s memory context and can be used to simulate data that the bot remembers from the user’s conversation.</td></tr><tr><td>User</td><td>This refers to the user context, enabling simulation of an existing user on BotDistrikt or a new user with attributes defined via variables.</td></tr><tr><td>Refresh</td><td>This acts as a caching identifier. When a response is retrieved, it is cached for 10 minutes. Changing this value forces the cache to clear and recompute the response.</td></tr><tr><td>Expected Response</td><td>The anticipated output or behaviour from the bot for the given input and context.</td></tr><tr><td>Actual Response</td><td>The actual output or behaviour observed from the system during the test.</td></tr><tr><td>Actual = Expected? (Y/N):</td><td>A validation field to confirm if the actual response matches the expected response.</td></tr><tr><td>Developer Comments</td><td>Additional notes or observations from the developer regarding the test case or discrepancies found.</td></tr></tbody></table> # Broadcasts Broadcasts allow you to send bot-initiated messages to several users at one go. Use the broadcast function to send messages to all users, or a targeted group of users ## Broadcasts Page On the Broadcasts page, you will be able to able to see a list of all broadcasts your bot has scheduled and completed. <figure><img src="/files/9XtAAiRcEQogqGvdL7Cy" alt=""><figcaption><p>Broadcasts</p></figcaption></figure> ### Creating a New Broadcast To create a new broadcast, click on the **New Broadcast** button on the top left corner of the page. When you click on it, the page redirects to the New Broadcast page. <figure><img src="/files/IbIrw7dnXNpK40fKdQzT" alt=""><figcaption><p>New broadcast</p></figcaption></figure> In order to create a broadcast, enter details in these fields #### Broadcast Story The story that you would like to send to all your users. When you select a story, you can preview it under the Preview Story area on the right. <figure><img src="/files/DX3bWf5FamxQfKrddKi1" alt="" width="563"><figcaption><p>Preview Story</p></figcaption></figure> #### When The time that you would like to send your broadcast. You will have these options: **Schedule:** Schedule your broadcast at a later date and time in your current time zone. A broadcast can only be scheduled at least 10 minutes in advance of the current time. The time selected will be in respect to your current timezone, which will be reflected above the Scheduled calendar <figure><img src="/files/9QDvgJbS5wVC7jRBtObC" alt="" width="563"><figcaption><p>Schedule broadcast</p></figcaption></figure> **Timewarp:** Schedule your broadcast at a later date and time in your recipients' individual time zones. A broadcast can only be time-warped at least 24 hours (1 day) in advance of the current time. The time selected will be with respect to your recipient's timezone. For example, If you send from Singapore and schedule delivery for 9 am UTC+8, your users in Jakarta would receive it at 9 am UTC+7 (translated to 10 am UTC+8). **Publish Now:** Publish your broadcast right here, right now. When you publish your broadcast now, you will get a confirmation popup before it is actually published to your recipients <figure><img src="/files/6ftnWlFeRSvYa24oizcp" alt="" width="563"><figcaption><p>Publish Broadcast Now</p></figcaption></figure> #### Target subset of users Target your broadcast to a specific audience based on their profile fields, tags, and attributes. You can make your targeting as generic or as specific as you wish ![Target your broadcast recipients](/files/-M0v_IMBBnbvxgHg4kxh) The above example targets users who are tagged with "b2c", first spoke to the chatbot on Jan 1st, 2020, and have a first name of "Abhilash". ### Previewing your Broadcast When you enter the three fields above, you will be able to preview recipients. #### Estimated Reach The Estimated Reach is the current estimated number of recipients who will receive your broadcast based on your target subset of users. If you click on the *preview* link, you will be able to see a list of all the recipients on the right side of the page ![Preview Recipients](/files/-M0vaj0twNm77GfqSEIM) You will also be able to preview the recipients by clicking the Preview Recipients button above and toggle the view from Preview Story #### Status The status of the broadcast. Every new broadcast will have a default status of UNPUBLISHED. A status can be only one of the 4 values from here: | Status | Description | | ----------- | --------------------------------------------- | | UNPUBLISHED | The broadcast is being setup | | SCHEDULED | The broadcast is scheduled to a later time | | PUBLISHING | The broadcast is being sent to its recipients | | FINISHED | The broadcast has been sent to its recipients | The status field can also be viewed on the Broadcasts page, which will show a summary of all broadcasts When you are done creating the broadcast, you can click on the red button below called **Schedule** or **Publish Now**, depending on when you scheduled your broadcast. Once done, you will get a notification that the broadcast has been scheduled and will be taken back to the Broadcasts page ### Viewing Broadcast Details <figure><img src="/files/tl3gBZ9Z3Y5nqxaPkyeU" alt=""><figcaption><p>Click on the Scheduled At field to view the broadcast's details</p></figcaption></figure> If you click on the Scheduled Time of a broadcast, you will be taken to a page where you can view your broadcast details. On this page, you will not be able to change any preset fields. You will have the option to cancel the broadcast at the bottom. ### Cancelling a Broadcast You can cancel a scheduled broadcast by clicking on <img src="/files/rWNiOc3XktKcr6mlqEKM" alt="" data-size="line"> at the bottom of the Broadcast Details page. <figure><img src="/files/qamGHCu6SRwvWOy7JpWk" alt="" width="563"><figcaption><p>Cancelling a scheduled broadcast</p></figcaption></figure> You will get a confirmation popup before the broadcast is finally canceled. Once the broadcast is canceled, it will be removed from the Broadcasts page. A broadcast can not be canceled when its status is FINISHED. You also have the option of canceling the broadcast from the Broadcasts page directly by clicking on the delete button on the right. <figure><img src="/files/BmVHlSpkoCHSabUwYvgd" alt=""><figcaption><p>Cancel broadcast directly from the Broadcasts page</p></figcaption></figure> You have the option of deleting a FINISHED broadcast this way as well. ## Broadcast Guidelines Different Messaging Channels have their own specific guidelines on the kind of content you are allowed to broadcast. The guidelines are listed below. ### Facebook Messenger {% hint style="info" %} Visit this [link](https://developers.facebook.com/docs/messenger-platform/policy/policy-overview/) to learn more about the Facebook broadcast guidelines on **Subscription Messaging** and **Sponsored Messaging**. {% endhint %} # Settings # Tags Tags help you organise your data BotDistrikt lets you analyze your chat traffic with ease with **Tags.** Tags are used classify and organize different types of content under your bot account. They are primarily used for managing and segmenting the bot's responses and the users interacting with your bot. This will allow for easy grouping, identifying, and finding content relevant to your chatbot’s operation. <figure><img src="/files/xktPTfQo7X1bW3bdYlVb" alt=""><figcaption><p>Tags Dashboard</p></figcaption></figure> Tags are only used for the bot’s responses such as **Cards, Users, Documents, Messages, Images, Text, Audio, Video, Source and Wrong Responses (WR).** ### Add New Tag <a href="#adding-new-story" id="adding-new-story"></a> To add a new Tag, click on <img src="/files/O8CR3GoebQsJ2zGPTHmi" alt="" data-size="line"> at the top right corner of the page. Then select the type of medium you would like to tag. <figure><img src="/files/FZu57sQ4EhaCnx9ITz2c" alt=""><figcaption><p>Select Tag Type</p></figcaption></figure> <figure><img src="/files/6NgMmIVHZRMYKxvIhpBc" alt=""><figcaption><p>Fields to Populate</p></figcaption></figure> Below is an explanation of the key fields and steps involved: 1. Type - Determines the response medium in which the tag will be applied to. 2. Name - Enter the name of the tag. 3. Synonyms - Add alternative names or keywords for the tag. 4. Description - Provide a detailed description of the tag's purpose or application. Once the tag is saved, it is successfully created and becomes available for use. You can begin assigning the tag to selected responses under the Tag field within the respective response settings. To review where the tag has been applied, users can click on the View button on the tags dashboard. This action navigates them to the specific response medium, such as Cards, Messages, or Documents, with the relevant filters automatically applied. <figure><img src="/files/WtcnOgtUDFR4sZ1nKqaK" alt=""><figcaption><p>Viewing Tagged Responses.</p></figcaption></figure> ### Tag Examples * [Cards](https://docs.botdistrikt.com/responses/cards) If a Tag called "sides" is created for a card; when a user searches for sides, the card will appear. ![Tagging "sides" to a card](/files/-MG9xWMUo3I1Y5PJHfyS) ![User prompting for sides will get a response with cards tagged with "sides".](/files/-MG9xhV82e0PSe3S8w3A) * [User](https://docs.botdistrikt.com/features/users) <figure><img src="/files/ZY7ORmdbK3fC381Z0tpU" alt=""><figcaption><p>Select User to Update User Tags</p></figcaption></figure> Enter specific tags for leads or broadcast list recipients. For example, whether a customer is an Enterprise, warm leads, premium customers, etc. These tags will be available in the **User** dashboard. * [Document](https://docs.botdistrikt.com/features/responses/documents) Similar to users, you can select 'document' from the tags dropdown to associate tags with a document. Documents such as menus or catalogs can be tagged to trigger it with specific keywords. * [Message](https://docs.botdistrikt.com/features/rules/conditions/message) Create tags associated with messages to help with creating conditions. * [Image](https://docs.botdistrikt.com/features/responses/images) Similar to cards, if an image is tagged with specific tags, for example, "fish", and the user mentions it during the conversation, "Does your menu include fish?" Then the bot shares the image tagged with fish with the user. * [Text](https://docs.botdistrikt.com/features/responses/text) Similar to messages, create tags for text-based responses to recognize user meanings, contexts, and intents and enable your bot to send relevant responses. * [Audio](https://docs.botdistrikt.com/features/responses/audios) Create a tags list to trigger audio responses for your bot. * [Video](https://docs.botdistrikt.com/features/responses/videos) Similar to cards and images, if a video is tagged with specific tags, for example, "cooking tutorial," and the user mentions it during the conversation, "Can you show me a cooking tutorial for pasta?" Then the bot shares the video tagged with "cooking tutorial" with the user. * [Sources](https://docs.botdistrikt.com/features/sources) Create a tags list to be assigned to sources, such as documents. * [Wrong Responses (WR)](https://docs.botdistrikt.com/features/inbox/wrong-responses) Create a tags list for validation purposes and to segment them. # Audit Logs **Audit log** in BotDistrikt records or logs all the interactions and activities that occur within the chatbot system. It serves as a chronological history of events, actions, and data related to your chatbots’ operations. Audit logs are essential for monitoring system usage, debugging issues, ensuring security compliance, and tracking changes made to chatbot configurations. ### Key Information Captured Each audit log entry contains the following fields: * **ID**: Unique identifier for each log entry * **User**: The user or system that performed the action * **Action**: The type of action performed (e.g. LOGIN, CREATED, UPDATED, DELETED) * **Entity Name**: The type of object affected (e.g. card, access, tag, text\_prompt) * **Entity ID**: Unique identifier of the affected entity * **Timestamp**: Date and time when the action occurred ### Types of Activities Logged The audit log captures a wide range of events, including: * **User interactions** (e.g. logins, access events) * **System events** (e.g. automated processes) * **Configuration changes** (e.g. updates to chatbot content or settings) * **Security-related actions** (e.g. access control changes) * **CRUD operations**: * **CREATED** * **UPDATED** * **DELETED** ### Entity Names The queryable entity names in the platform are tabulated below <table><thead><tr><th width="185.6484375">Entity Name</th><th>Description</th></tr></thead><tbody><tr><td>access</td><td>Team member user access record</td></tr><tr><td>action_prompt</td><td>LLM Agent that outputs a value or JSON schema into a user attribute </td></tr><tr><td>action</td><td>Context change response modifying memory and variables</td></tr><tr><td>alibaba_cloud_app</td><td>Alibaba Cloud integration settings</td></tr><tr><td>assistant_app</td><td>Google Assistant integration settings</td></tr><tr><td>audio</td><td>Audio response from chatbot</td></tr><tr><td>azure_openai_app</td><td>Microsoft Azure OpenAI integration settings</td></tr><tr><td>broadcast</td><td>Bulk notification to multiple users</td></tr><tr><td>button</td><td>Clickable button attached to responses</td></tr><tr><td>card</td><td>Rich element with image, title, subtitle, buttons</td></tr><tr><td>chatbase_app</td><td>Chatbase integration settings</td></tr><tr><td>condition</td><td>Evaluates incoming message against context property and value</td></tr><tr><td>csv_export</td><td>CSV Export record</td></tr><tr><td>deepseek_app</td><td>DeepSeek integration settings</td></tr><tr><td>dialogflow_app</td><td>Dialogflow integration settings</td></tr><tr><td>docs_app</td><td>Google Docs integration settings</td></tr><tr><td>document</td><td>Document response from chatbot</td></tr><tr><td>facebook_app</td><td>Facebook App integration settings</td></tr><tr><td>facebook_page</td><td>Facebook Page integration settings</td></tr><tr><td>form_question</td><td>Form question inside a form</td></tr><tr><td>form</td><td>Fillable form in a linear flow</td></tr><tr><td>function</td><td>JavaScript function to modify or evaluate message context</td></tr><tr><td>group</td><td>Set of rules organizing bot topics and functionalities</td></tr><tr><td>image</td><td>Image response from chatbot</td></tr><tr><td>instagram_page</td><td>Instagram Page integration settings</td></tr><tr><td>integration_step</td><td>Integration step response</td></tr><tr><td>langfuse_app</td><td>Langfuse integration settings</td></tr><tr><td>llm_source</td><td>Source for LLM chunks, in the form of Website, Document, Google Docs or Google Sheets</td></tr><tr><td>openai_app</td><td>OpenAI integration settings</td></tr><tr><td>persisted_menu</td><td>Always-on clickable buttons at chat screen bottom</td></tr><tr><td>quick_reply</td><td>Transient button for user to respond to story</td></tr><tr><td>response_group</td><td>Text response from chatbot with random variant selection</td></tr><tr><td>response</td><td>Text response variant for random selection</td></tr><tr><td>rule</td><td>Conditions to evaluate message and select story response</td></tr><tr><td>salesforce_app</td><td>Salesforce integration settings</td></tr><tr><td>sheets_app</td><td>Google Sheets integration settings</td></tr><tr><td>skype_app</td><td>Skype integration settings</td></tr><tr><td>sms_app</td><td>SMS integration settings</td></tr><tr><td>step</td><td>One response in a story with position order</td></tr><tr><td>sticker</td><td>Sticker response from chatbot with emoji or set</td></tr><tr><td>story</td><td>Bot response with multiple response types and steps</td></tr><tr><td>tag</td><td>Label applied to users and models for filtering</td></tr><tr><td>teams_app</td><td>Microsoft Teams integration settings</td></tr><tr><td>telegram_app</td><td>Telegram integration settings</td></tr><tr><td>template</td><td>Bot Template to create a new bot from</td></tr><tr><td>text_prompt</td><td>LLM Agent that performs RAG and outputs a response</td></tr><tr><td>thread_comment</td><td>Comments in threads</td></tr><tr><td>thread</td><td>A group of comments for an entity</td></tr><tr><td>twitter_app</td><td>Twitter integration settings</td></tr><tr><td>vertexai_app</td><td>Google Vertex AI integration settings</td></tr><tr><td>video</td><td>Video response from chatbot</td></tr><tr><td>webchat_app_placement</td><td>Website Chat Widget variant settings</td></tr><tr><td>webchat_app</td><td>Website Chat Widget settings</td></tr><tr><td>webhook_app</td><td>Webhook to notify other applications on user message</td></tr><tr><td>webhook</td><td>API call response from chatbot to external systems</td></tr><tr><td>wechat_app</td><td>WeChat integration settings</td></tr><tr><td>whatsapp_app</td><td>WhatsApp integration settings</td></tr><tr><td>wit_app</td><td>Wit.ai integration settings</td></tr><tr><td>wrong_response</td><td>Tracked issue based on a message-response pair</td></tr><tr><td>zendesk_app</td><td>Zendesk integration settings</td></tr></tbody></table> ### How to Access Audit Logs To access the audit log, navigate to the side panel **Settings → Audit Log** <figure><img src="/files/HQy5fuLQ9pFjdSSuTVm4" alt=""><figcaption><p>Audit Log Dashboard</p></figcaption></figure> ### Viewing Changes * Hover over **Entity Name** to view the code block of changes made. <figure><img src="/files/trQbTJ3Un0jSprh1VHit" alt=""><figcaption></figcaption></figure> * This allows you to inspect exactly what was modified during an update. #### Action Types and JSON Data Deltas #### 1. Action: CREATED The **CREATED** action indicates that a new record has been added to the database. * **Visual Cue:** Fields are highlighted in **Green**. * **Behavior:** Because there is no "previous state" for a new entity, the system displays the entire initial data set as an addition. * **Example:** When a user creates a new `Text` responses under "Responses", all defined attributes like `name` and `is_active` will appear in green to show they are now part of the system. <figure><img src="/files/7T2KY6FgAnrKCRsh0NwE" alt=""><figcaption></figcaption></figure> #### 2. Action: UPDATED The **UPDATED** action records modifications made to an existing record. * **Visual Cue:** **Red Strikethrough** (Old) and **Green Highlight** (New). * **Behavior:** The system performs a "delta" comparison. It shows you exactly what the value was before the change and what it became after the save. * **Example:** If a `name` is changed from `"Hello World!"` to `"Good Morning 🌞"`, the log will display: <figure><img src="/files/7vTQqrJknrsIcsaal0n3" alt=""><figcaption></figcaption></figure> #### 3. Action: DELETED The **DELETED** action tracks the removal of a record from the system. * **Visual Cue:** All fields are highlighted in **Red with a Strikethrough**. * **Behavior:** The JSON snapshot represents the "final state" of the data immediately before it was removed. The red formatting indicates that this specific data set is no longer active or reachable. * **Example:** Deleting a `Text` will show the entire object struck through in red, serving as a historical record of what was removed. <figure><img src="/files/lmI0UzH0mBCDvyC5ns4w" alt=""><figcaption></figcaption></figure> ### Filtering Logs You can use the **filter function** to refine and search for specific logs based on: * User * Action type * Entity * Date/time range This helps quickly locate relevant events for troubleshooting or audits. **Add filter(s)** to search through specific logs. ### Example An example log entry may show: * A user login event * A deleted card entity * The exact timestamp of when the action occurred ### How to Apply Filters 1. Click the **+ add filter** button. <div align="left"><figure><img src="/files/84nMixPOi9AyD9A17CX9" alt=""><figcaption></figcaption></figure></div> 2. Select category from the first dropdown. <figure><img src="/files/5LrXUC216ONvLUI9XIc6" alt=""><figcaption></figcaption></figure> 3. Choose your **Operator** (e.g., `contains`, `equals`). 4. Input the **Value** or select it from the provided list/calendar. 5. To remove a filter, click the **trash icon** 🗑️ next to the filter row. #### 1. Filter by ID Filter records based on their unique identifier. * **Operators:** `equals`, `not equals`, `greater than`, `less than`. * **Use Case:** Best for locating a specific log entry if you have the direct ID number. <figure><img src="/files/gzhul1MkyFlauSaaM4u4" alt=""><figcaption></figcaption></figure> #### 2. Filter by User Filter logs based on the person who performed the action. * **Operators:** `equals`, `not equals`. * **Use Case:** Auditing the activity of a specific team member or administrator. <figure><img src="/files/3ePpt2hWRllVzptnHJRW" alt=""><figcaption></figcaption></figure> #### 3. Filter by Action Filter by the type of action that occurred. * **Available Values:** `CREATED`, `UPDATED`, `DELETED`, `INVITED`, `ACCEPTED`, `LOGIN`, `LOGOUT`. <figure><img src="/files/ZFm434jk2UQ3kHcJGiDh" alt=""><figcaption></figcaption></figure> #### Actions on Entities / Objects Track changes to specific objects within the platform (such as story changes or user access activities). **Use Case:** Finding all instances of a specific behavior, such as seeing who has logged in recently or identifying all deleted entities. * **CREATED**: Logged when a new entity is initially added to the system. The associated JSON will show all initial values in green. * **UPDATED**: Logged whenever an existing entity is modified. The JSON delta will highlight exactly which values were changed. * **DELETED**: Logged when an entity is removed. This provides a final snapshot of the data before deletion. #### 4. Filter by Entity Name Filter based on the name of the object being modified (e.g., a specific response group name). * **Operators:** `equals`, `not equals`, `contains`, `not contains`. * **Use Case:** Searching for all changes related to access management, or if want to search actions done to a specific story (even if you only remember a part of the story name, use "contains"). <figure><img src="/files/x9E4ztmII2eCbjJR1ta6" alt=""><figcaption></figcaption></figure> #### 5. Filter by Entity ID Filter based on the unique ID of the entity itself. * **Operators:** `equals`, `not equals`, `greater than`, `less than`. * **Use Case:** Tracking the entire lifecycle (creation, updates, deletion) of one specific entity e.g. tag, card, story across different points in time. <figure><img src="/files/uLqFqWpfNriQafBusmug" alt=""><figcaption></figcaption></figure> #### 6. Filter by Timestamp Narrow down logs by a specific date and time. * **Modes:** * **Normal:** Select a specific date from the calendar and a specific time. * **Relative:** (e.g., "Last 1 hour", "Last 7 days"). * **Operators:** `greater than` (after), `less than` (before). * **Use Case:** Investigating incidents that occurred within a specific timeframe. <figure><img src="/files/6cFJaVTeCdnVdJm4cb2l" alt=""><figcaption></figcaption></figure> #### Notes * Logs are displayed in descending chronological order (most recent first). * All actions are recorded automatically and cannot be modified. # User Access Management The User Access Management page allows administrators to manage user access to the chatbot platform. This includes creating, modifying, and removing user accounts. > ⚠️ **Important** To view User Management-related audit logs, the **Entity Name must be set to `"access"`** in the filter. > > Without this filter, user creation, role changes, and access updates will not be visible. ### **Navigate to Account Settings** * From the left sidebar, click **Settings** * Select **Account** * Click on the **“Team Members”** tab at the top of the page <figure><img src="/files/PBeWuOCqddQoK2PFMaZc" alt=""><figcaption></figcaption></figure> #### 1. Create and Invite a New User * Click "Invite Team Member" <div align="left"><figure><img src="/files/5dEUbvoXL1y3OrBd5DWR" alt=""><figcaption></figcaption></figure></div> * Enter user details: * **Email** – User’s email address * **First Name** – User’s first name * **Last Name** – User’s last name * Select a **Role** i.e. **EDITOR**, **ADMIN** from the list 👉 Role determines what the user can/cannot do: **ADMIN Role** Users assigned as **Admin** will have full access, including: * ✅ May invite team members * ✅ May change roles * ✅ May assign privileges * ✅ May edit own email settings 👉 Typically used for system owners or key administrators **EDITOR Role** * ❌ Cannot invite team members * ❌ Cannot change roles * ❌ Cannot assign privileges * ✅ Can edit own email settings <figure><img src="/files/62T29oOghCMa7FSKhlrl" alt=""><figcaption></figcaption></figure> **Assign Privileges** * Select access to modules (if applicable): * Forms, Rules, Stories * Responses, Sources * Users, Inbox * Broadcasts, Integrations * Settings 👉 Note: ADMIN will have all the privileges by default * Click **Invite** to send user an invitation email (see below) <figure><img src="/files/eMH7bKQlWjk6I7PpO6RD" alt=""><figcaption></figcaption></figure> * Click the link on "Step 1" and you will see below page to set your login password <div align="left"><figure><img src="/files/k8fQWytcdBYwQaStWLHT" alt=""><figcaption></figcaption></figure></div> * Click the link on "Step 2" and you will see below that you have accepted the invitation to access the Bot <div align="left"><figure><img src="/files/EYTrG8Uh9soMWZk2k5cp" alt=""><figcaption></figcaption></figure></div> * Click on "Show me my bots" to see your chatbots on the BotDistrikt Platform * Go left panel "Settings" > "Audit Logs" - an audit entry is added when invitation has been sent out i.e. "Action" column = "INVITED" and "Entity Name" column = "access", hover to see the JSON details - green color; record added <figure><img src="/files/KfesFmd25z5BlZpFNGXg" alt=""><figcaption></figcaption></figure> #### Check Whether User Have Accepted the Invitation New user has 24 hours to accept the email invitation, you can see the list of users who have not accepted the invitation with below: * On the left panel, click **Settings > Account** * Click on the **“Team Members”** tab at the top of the page * If the user has not accepted the Invitation, you will see Status column value ie. "Pending" <figure><img src="/files/erfe5hMy6bXqAwqcwClT" alt=""><figcaption></figcaption></figure> <figure><img src="/files/vzaReJewabGo13q91gYP" alt=""><figcaption></figcaption></figure> If the user has accepted the Invitation, you will see Status column value ie. "Accepted" <figure><img src="/files/y9FCsNdcPzf2g57xaaz2" alt=""><figcaption></figcaption></figure> * Go left panel "Settings" > "Audit Logs" - an audit entry is added when invitation has been accepted i.e. "Action" column = "ACCEPTED" and "Entity Name" column = "access" <figure><img src="/files/CSlbej9n14FcHWoJiBn4" alt=""><figcaption></figcaption></figure> #### Update Existing User * Click on Name to open the user record <div align="left"><figure><img src="/files/a3ooAwgpztxntCdsO3pD" alt=""><figcaption></figcaption></figure></div> * Make the necessary changes e.g. Role, Privileges and click **Save** <figure><img src="/files/HsgpIxeFmVEvoMW6be0O" alt=""><figcaption></figcaption></figure> * You will see the "Saved successfully" green notification message at the right bottom of the page <div align="left"><figure><img src="/files/Rims7AdvOvRfOsNyltWJ" alt=""><figcaption></figcaption></figure></div> * Go left panel "Settings" > "Audit Logs" - a new audit entry is made when changes is sent out i.e. "Action" column = "UPDATED" and "Entity Name" column = "access", hover to see the JSON details - **Red Strikethrough** (Old) and **Green Highlight** (New). <figure><img src="/files/qPlsx8R5xcE3uMaz92PE" alt=""><figcaption></figcaption></figure> #### Delete (Revoke) User You can delete or revoke a user access to the Bot with 2 methods: **METHOD 1 - Delete button** 1. On the left panel, click **Settings > Account** 2. Click on the **“Team Members”** tab at the top of the page 3. To remove an user, click the **trash icon** 🗑️ on the right side of the user row <figure><img src="/files/gtyCBALrWUi0c3G4a97l" alt=""><figcaption></figcaption></figure> **METHOD 2 - Revoke button** 1. On the left panel, click **Settings > Account** 2. Click on the **“Team Members”** tab at the top of the page 3. Click on Name to open the user record <div align="left"><figure><img src="/files/t9FSTwudKUAtQFfzCYKr" alt=""><figcaption></figcaption></figure></div> 4. Click on the Revoke button at the bottom of the screen to delete the user / revoke the acess to the Bot <figure><img src="/files/SNjENPrG066nK0PzRRKJ" alt=""><figcaption></figcaption></figure> * A confirmation dialog box will appear to revoke the access to this bot, click "OK" <figure><img src="/files/SgY9YFbTtmWN1hxRY6We" alt=""><figcaption></figcaption></figure> * A green notification message will appear at the bottom right of the page to confirm that the user's acess has been revoked <div align="left"><figure><img src="/files/YDe7VrK9QU1caidU1IhS" alt=""><figcaption></figcaption></figure></div> * Go left panel "Settings" > "Audit Logs" - a new audit entry is made when changes is sent out i.e. "Action" column = "DELETED" and "Entity Name" column = "access", hover to see the JSON details - All fields are highlighted in **Red with a Strikethrough**. <figure><img src="/files/EwSjEAGZ9bLGEicnTr7U" alt=""><figcaption></figcaption></figure> # Account **Account** has four sections: * Overview * Team members * Export * Billing **Overview** <figure><img src="/files/odYZ9nH2Z1Te01ErHwfh" alt="" width="375"><figcaption><p>Settings > Account</p></figcaption></figure> Update your **Organization Name**, **Contact Email** and toggle **Public Profile** on/off **Team Members** In the **Team Members** tab, click **Invite Team Members** to invite new team members or update existing ones. <figure><img src="/files/UnI8GI31kowlHNy1XKdA" alt=""><figcaption><p>Team Members Dashboard</p></figcaption></figure> **Invite New Members** <figure><img src="/files/FveP0CfbpFKFhdn2Y1Il" alt=""><figcaption><p>Invite New Team Member</p></figcaption></figure> Enter new team member's: * **Email ID** * **First Name** * **Last Name** * **Role (Admin/Editor)** * **Privileges** * **Email Settings** for bot performance report (never/day/week/month) **Export** <figure><img src="/files/a8fhYq40oEHNw0kQVbIH" alt=""><figcaption><p>Export Bot JSON or CSV</p></figcaption></figure> To compare bot CSV, drop another bot's CSV in the drop box to compare. {% hint style="info" %} Bot CSV comparison is used to compare different CSV files versions containing training data, responses, intents, or other configuration details. {% endhint %} **Billing Status** Check your billing status in the **billing** tab. <figure><img src="/files/y1EP0vDLRMvdcYLKaE1p" alt=""><figcaption><p>Check Billing Status</p></figcaption></figure> # Interaction A user interaction with a bot is simple <figure><img src="/files/RFaEXzT4XK0W0UNZzcoL" alt=""><figcaption><p>Message/User/Response in Live Chat</p></figcaption></figure> 1. The **User** sends a **Message** 2. The **Bot** returns a **Response** <figure><img src="/files/hFqm0fINIqS1TZP0fvkk" alt=""><figcaption><p>User/Bot Interaction Demo</p></figcaption></figure> ## User A human person interacting with your bot on messaging channels connected to the platform. Their user profile is created when they send their first message through any connected messaging channels. ## Bot An automated conversational tool that you build on the platform to respond to your users. A bot is also the account that you use to manage your configurations, team, billing, and subscription on BotDistrikt. ## Message Data sent from a User to your Bot. It is available in the form of text, an image, a video, an audio clip, an event (like a button click), a sticker, and a location. ## Response Data sent from your Bot to a User. This information can be also presented in the form of text, an image, a video, an audio clip, a sticker, a location, and rich-media elements like buttons and cards. # Flow When a bot receives a message, it performs 2 tasks: 1. Identify **what to do** 2. Decide **how to respond** The platform uses **Rules** to help your bot identify *what to do*, and **Stories** to help it decide *how to respond*. When creating a flow, configuring a rule first then a story next helps avoid duplicating stories. ![Flow](/files/-MjIbh50itxkhFekFSOB) ## Rule A rule can also be considered a *question* from a user. When your bot receives a message, it tests the message against all its rules from the top rule (P1) to the bottom rule (PN). The first rule that passes the test is chosen as the **Passing Rule.** Let's create a rule called "*user is asking bank account balance"* in our bot. ![Sample Rule for Bank Account Balance Query](/files/-MjE1otJnbYF6EKrfk_O) {% hint style="info" %} Rules are tested in order of appearance. Higher rules have higher priority (P1, P2, etc.), and lower rules have lower priority. Rules can be re-ordered in any way you want them to be tested. {% endhint %} A rule must have one or more conditions. ## Condition A boolean expression that returns *true* or *false*. When **all conditions** in a rule are *true*, the rule becomes the Passing Rule. A condition tests only one context of a message-receiving interaction, either message, memory, user attributes, or NLP. Each condition has 3 parts to it: * Property * Function * Value. For our example above, we include two conditions (C1 and C2) to our rule: <table data-header-hidden><thead><tr><th width="109"></th><th width="137">Context</th><th width="202">Property</th><th>Function</th><th>Value</th></tr></thead><tbody><tr><td></td><td>Context</td><td>Property</td><td>Function</td><td>Value</td></tr><tr><td>C1</td><td><code>message</code></td><td><code>text</code></td><td><code>has keyword</code></td><td><code>balance</code></td></tr><tr><td>C2</td><td><code>memory</code></td><td><code>ask-bank-account</code></td><td><code>equals</code></td><td><code>true</code></td></tr></tbody></table> <figure><img src="/files/9fVwjmSexeG0UIMhgQq0" alt=""><figcaption></figcaption></figure> This is a sample conversation with the rule above > **User:** My account\ > **Bot**: Sure, what would you like to know? \ > `Bot uses an action to store a memory property: ask-bank-account, value: true`\ > \----------\ > **User:** What is my balance?\ > `Bot checks its rules and finds the Passing Rule: user is asking bank account balance. Bot has now IDENTIFIED WHAT TO DO` When the Passing Rule is found, the bot replies with the rule's Story. ## Story A collection of responses returned from the bot. In its simplest form, consider a story an *answer* from the bot. It may contain one or many text, image, video, audio, document, card, location, and sticker responses. It can also be used to make your bot display buttons for the user to click, and perform certain actions on a context or trigger webhooks. Let's create a story for the above example called "*user is asking about bank balance".* <figure><img src="/files/GDoSpLUpZujg1vmOwXFS" alt=""><figcaption><p>Sample Story</p></figcaption></figure> In this story, we created 2 responses and 2 quick replies. 1. Added a Webhook response to get the user's bank account information from our imaginary custom banking infrastructure, which returns a new memory property `bank-balance`. 2. Added a Text Response displaying the bank balance with a *Refresh Now* button. 3. Added 2 quick replies: 1. *How to improve* 2. *Contact Customer Support*. The interaction in our example is complete > **User:** My account\ > **Bot**: Sure, what would you like to know? \ > `Bot uses an action to store a memory property: ask-bank-account, value: true`\ > \----------\ > **User:** What is my balance?\ > `Bot checks its rules and the Passing Rule: user is asking bank account balance. Bot has now IDENTIFIED WHAT TO DO`\ > \----------\ > `Bot selects the rule's story to DECIDE HOW TO RESPOND`\ > **Bot:** Your current balance $536.12 # Context A bot sometimes needs to * **Remember** the information the user provided minutes ago. * **Personalize** the same response to 2 users differently. With contextual information like **Memory**, **User Attribute**, and **NLP Attribute**, a bot makes smarter decisions to find a Passing Rule. ![Types of Contexts - User, Memory and NLP](/files/-MjEKqthEq0LunTi54yW) ### Session {% hint style="info" %} A group of user interactions with your bot that take place within a given time frame. {% endhint %} A single session may have multiple messages, button clicks, and transactions. A single user may have multiple chat sessions with your bot, occurring on the same day or over several days, weeks, or months. By default, a session expires after **10 minutes** of inactivity. You may customize your bot's session length on the [Personality](/features/personality) page. {% hint style="warning" %} Changing Session Length affects the [Time Spent](broken://pages/-MjJWcFfChd-8hIPlUKS#time-spent) and [Sessions](broken://pages/-MjJWcFfChd-8hIPlUKS#sessions) stats. {% endhint %} ### Memory A temporary variable is used to store additional information about a chat session. It is used to **remember** topics and values that the user was talking about in the current session. Access it in the bot's responses with the merge tag `{{memory.property-name}}`. Here's an example of memory property usage > **User:** How much is the large pepperoni pizza?\ > **Bot:** The large pepperoni pizza is $29.90\ > `Bot stores a memory property: item-requested, value: pepperoni pizza`\ > \-------------\ > **User:** How about the small one?\ > `Bot remembers "pepperoni pizza" from the item-requested memory property`\ > **Bot:** The small pepperoni pizza is $19.90 {% hint style="info" %} Memory properties are ALWAYS hyphenated ([kebab-cased](https://en.wikipedia.org/wiki/Kebab_case)), so item-requested is a valid memory property ✅ but item\_requested is NOT ❌ {% endhint %} {% hint style="danger" %} When your session expires, your bot forgets its memory context (i.e. all its memory properties) {% endhint %} ### User Attribute A permanent variable used to store custom information about a user messaging your bot. Access the user context (i.e. all user attributes) in User Profiles. It is used to keep track of long-term custom fields like preferences, survey answers, access levels, and transaction activity. It is essential for customer segmentation, which in turn allows you to create personalized chat experiences and targeted broadcasts. Access it in the bot's responses with the merge tag `{{user.attribute_name}}`. {% hint style="info" %} User attributes are ALWAYS underscored ([snake\_cased](https://en.wikipedia.org/wiki/Snake_case)), so user\_address is a valid user attribute ✅ but user-address is NOT ❌ {% endhint %} <div align="right"><figure><img src="/files/8kN9QG3v3h740gT4pjT1" alt=""><figcaption><p>User attribute used in a greeting</p></figcaption></figure></div> <div data-full-width="true"><figure><img src="/files/Ohwdnk2VSH3ZfX7TYfl8" alt=""><figcaption></figcaption></figure></div> ### NLP Attribute A derived variable from connected Artificial Intelligence (AI) integrations. You may connect any number of AI integrations like Dialogflow and Wit.ai. After adding at least one AI integration, every message sent to your bot is forwarded to the AI integration. The AI integration derives intents, traits, and entities and stores them in the NLP context (i.e. all NLP attributes). Access it in your bot's responses with the merge tag `{{nlp.attribute_name}}`. {% hint style="info" %} NLP attributes are ALWAYS underscored ([snake\_cased](https://en.wikipedia.org/wiki/Snake_case)) {% endhint %} ### Shortcut A static global variable for your bot, used in any response in every chat with every user. Shortcuts are declared on the Personality page. It is useful for text replacements like on [iPhones](https://support.apple.com/en-sg/guide/iphone/iph6d01d862/ios) and [Androids](https://www.howtogeek.com/276635/how-to-add-custom-text-shortcuts-to-android/), and also for storing environment variables for Developers. Access it in a conversation with the merge tag `{{bot.shortcut_name}}`. {% hint style="info" %} Shortcuts are ALWAYS underscored ([snake\_cased](https://en.wikipedia.org/wiki/Snake_case)) {% endhint %} ### Action A way to dynamically modify contexts during a session. Once you add actions in stories, it modifies one of 4 contexts: memory, user attributes, user tags, and shortcuts. An action has 3 parts to it: * Property * Function * Value From our example above, we create a story with one action: | | Context | Property | Function | Value | | -- | -------- | ---------------- | -------- | ----------------- | | A1 | `memory` | `item-requested` | `set to` | `pepperoni pizza` | <figure><img src="/files/iqE4Uy6P5AKhRMYBA4vt" alt=""><figcaption></figcaption></figure> <figure><img src="/files/r4YeEhInTVXCiiKOSZVb" alt=""><figcaption></figcaption></figure> The interaction in our example looks like this: > **User:** How much is the large pepperoni pizza?\ > **Bot:** The large pepperoni pizza is $29.90\ > `Bot stores a memory property: item-requested, value: pepperoni pizza` An action has a lifespan. ### Lifespan The number of messages for which a new memory property from an action remains active. The default lifespan of a memory property is **1**. This means that the bot remembers that you stored the new memory property `item-requested` for 1 more message from the user. After the user replies with 1 message, `item-requested` is removed from the memory context automatically. The 3 most commonly used lifespans are | Lifespan | Description | Use | | -------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | | 1 | Remembers the property for 1 more message | Direct answers from users, e.g. Yes/No Questions | | 0 | Remembers the property for the entire period of the chat session | Session-wide topics, e.g Browsing subtopics | | -1 | Remembers the property for the current message | Intermediate values for subsequent actions or rules, e.g. Variables for Mathematical Calculations | {% hint style="info" %} Only Memory Properties have customizable lifespans. User Attributes are stored permanently. NLP Attributes have a fixed lifespan value of **-1** {% endhint %} ### Function A block of JavaScript code used in conditions and actions. It is used within a condition for comparisons, or within an action for assignments. ### Webhook An API request made to external software. There are 2 methods available - `GET` and `POST` . It is used to collect and update dynamic information in your custom technology infrastructure or integrations, and to pre-populate responses, quick replies, and modify memory and user contexts. # Engagement User engagement is key to building [product stickiness](https://en.wikipedia.org/wiki/Sticky_content). Your bot can * Send **personalized chat blasts** to all its users * **Collect** **answers** from your users * Provide a **richer user interface** than text <figure><img src="/files/b4n0cM6SOwHKUm1Jvpwz" alt=""><figcaption><p>Forms of Engagement</p></figcaption></figure> ## Broadcast A mass chat blast sent to all or a targeted user segment, based on their tags and attributes. Broadcasts are the chatbot version of [email marketing](https://en.wikipedia.org/wiki/Email_marketing). ## Form An engagement method to quickly and automatically collect information from a large volume of your users. Use the form to save qualitative answers and update user attributes. As a result, allowing you to create multiple customer segments. ## Tag A way to group and categorize information on the BotDistrikt platform. Tags can be currently used on Users, Cards, Documents, and Images. They are especially useful in the **Filter Webhook**. ## Button When a user clicks a button, it performs a certain task. Buttons help to create a *quicker* *chat flow* as users click buttons instead of typing full text to interact. Buttons perform 4 actions: * URL - Visit a website URL * Story - Start another Story * Phone - Call a phone number * Text - Send the text of the button as a message They stack vertically, and your bot displays up to 3 buttons per stack. The elements that buttons attach include: * Text response * Card response * Video response * Audio response * Persistent Menu <figure><img src="/files/gIWZ7IJo58adEpvzBWWT" alt=""><figcaption><p>3 buttons attached to a Text Response</p></figcaption></figure> {% hint style="info" %} Buttons are **permanently** **visible** after they appear on your user's chat screen {% endhint %} ## Quick Reply A special button type that can only be attached to the bottom of a Story. A quick reply performs 5 functions: * Text - Send the text of the quick reply as a message * Return - Similar to text, but shows a "❮" character to indicate "Back" (similar to a browser's "Back" button) * Location - Send the user's current location \*\* * User Email - Send the user's email \*\* * User Phone Number - Send the user's phone number \*\* Buttons stack horizontally, can be side-scrolled, and your bot may display up to 10 quick replies per Story. ![2 quick replies attached to a Story](/files/-MjYLJNQlaa8EfFQBB_9) *\*\*limited to messaging apps that support them* {% hint style="info" %} Quick Replies are **temporarily visible** once they appear in your bot's response. When the user sends a message after seeing some quick replies, the quick replies disappear. {% endhint %} ## Text A text-based response in a Story. Text can have one or many variants. When a bot has to respond with text, it will randomly choose a text response from the text itself or its variants. Text can also have up to 3 buttons for a richer user interface. <figure><img src="/files/6DrIDzyTobCTPaA7DyQX" alt=""><figcaption><p>A text response in a story</p></figcaption></figure> ## Card A card-based response in a Story. A card is a simple structured message that includes (up to 3 buttons): * Title * Subtitle * Image A single response has one or many cards, and users can browse through a horizontal carousel on most messaging apps. Cards are extremely useful to create a browsing experience in your chatbot - to browse your products, features, events, and more. Cards also have tags and can be filtered with the Filter Webhook. ![Card Response in a Story](/files/-MjTEy_A_m6Ps4ANpsSi) ## Image An image-based response in a Story. The platform accepts PNGs, JPEGs, and GIFs. An image always has a name and can be reused in multiple stories by searching for an image title. Images also have tags and can be filtered with the Filter Webhook. ![A image response in a story](/files/-MjJreuLzhWRvN2FPTMm) {% hint style="warning" %} Images have a maximum upload file size of 10 MB {% endhint %} ## Video A video-based response in a Story. The platform accepts MP4s, MOVs, and AVIs. A video always has a name and can be reused in multiple stories by searching its title. <figure><img src="/files/oU2ugFgohgO590wd8wkt" alt=""><figcaption><p>A video response in a story</p></figcaption></figure> In some messaging apps, videos can also be presented in the form of a card with a title, subtitle, and up to 3 buttons. <figure><img src="/files/ijYUxMu9K9xogHrJIpMX" alt=""><figcaption><p>A video response in a card format</p></figcaption></figure> {% hint style="warning" %} Videos have a maximum upload file size of 20 MB {% endhint %} ## Audio An audio-based response in a Story. The platform accepts MP3s and WAVs. An audio always has a name and can be re-used in multiple stories by searching its name. ![An audio response in a story](/files/-MjTGV8eL2NWPocvZY0u) In some messaging apps, audio can also be presented in the form of a card with a title, subtitle, and up to 3 buttons. ![An audio response in a card format](/files/-MjTGbTzJffuYOetTghr) {% hint style="warning" %} Audios have a maximum upload file size of 10 MB {% endhint %} ## Document A downloadable file response in a Story. Documents can be used to share digital files like PDFs, DOCs, PPTs, and XLSs from your bot. A document always has a name, and can be re-used in multiple stories by searching its name. Documents also have tags and can be filtered with the Filter Webhook. ![A document response in a story](/files/-MjTHqdhUmCApcOY---f) {% hint style="warning" %} Documents have a maximum upload file size of 10 MB {% endhint %} ## Typing A typing response in a Story. This is displayed as a typing indicator to the user in their own messaging app. Typing indicators help to control the response speed sent from the bot, especially when there is a lot of text information to be digested at once. ![A typing response in a story](/files/-MjThfKPVpXA4iU7kLyH) {% hint style="success" %} BotDistrikt automatically provides typing indicators for your bot when you connect a messaging app. You may use this Typing response for your own additional Typing indicators. {% endhint %} ## Sticker A sticker response in a Story. Stickers are limited to messaging apps that allow bots to share stickers. Each sticker is associated with an emoji, which is similar to Telegram's [emoji tooltips](https://emojipedia.org/telegram/). Emojis are useful when you want to send a certain sticker based on a certain emoji. For messaging apps that do not support stickers, an **Image** is sent instead. ![A sticker response in a story](/files/-MjTUZVpijFf5pIW0Wum) BotDistrikt uses Facebook Messenger's preset stickers based on the emojis below | # | Emoji | Sticker | Description | | -- | ---------------- | ------------------------------------------------------------ | ---------------------------- | | 1 | <p></p><p>🙂</p> | ![](/files/-MjTVBq0OlPJf3PFjf6V) | Smiley | | 2 | 😝 | ![](/files/-MjTXrXJNGUbhrbAcdtK) | Tongue out | | 3 | 😄 | ![](/files/-MjTXxC8pQo3hEexh1jC) | Happy laugh | | 4 | 😍 | ![](/files/-MjTY09_bABqPpZnMzl2) | Heart eyes | | 5 | 😂 | ![](/files/-MjTY3p-BtRy0iRxb4cu) | Laugh with tears | | 6 | 😥 | ![](/files/-MjTY7UD3bGXwJ6BzKU7) | Sad with sweat drop | | 7 | 😕 | ![](/files/-MjTYAqZKIeDIyGGfMQZ) | Confused | | 8 | 😭 | ![](/files/-MjTYEf6b89ZPB49vU_a) | Crying | | 9 | 😱 | ![](/files/-MjTYIq8ETVsUOBF5S8Z) | Wide eyes scream | | 10 | 😘 | ![](/files/-MjTYaaoo6N76vm6zo3Y) | Kissy face | | 11 | 🤩 | <p></p><p><img src="/files/-MjTYeMEN0MRbSWRy31D" alt=""></p> | Starry eyes | | 12 | 😆 | ![](/files/-MjTYhr_Cy0zlcfmz5xg) | Closed eyes open mouth laugh | | 13 | 😑 | ![](/files/-MjTYlF8sFl6Bbkov7ZF) | Expressionless | | 14 | 😁 | ![](/files/-MjTYo_xv1nxuitoFhI0) | Showing teeth smile | | 15 | 🤓 | ![](/files/-MjTYsBC1D0H4ovALicJ) | Glasses nerd | | 16 | 😰 | ![](/files/-MjTYvwFHaX68h7gaUSy) | Distraught blue forehead | Stickers are configured differently for the Telegram integration: 1. Enter a Sticker Pack URL. 2. A Telegram sticker is then selected from the sticker pack (based on the Sticker Emoji). 3. If a sticker emoji is not provided, one is randomly picked from the pack. <figure><img src="/files/qDB6xdXY7aGr2pmJT24p" alt=""><figcaption><p>Telegram sticker pack configuration</p></figcaption></figure> If a user sends your Bot a sticker message, the message will have 2 fields filled in. You may re-use these message fields as merge tags to send a response with the same sticker pack to the user. The fields are: | Context | Field | Description | | --------- | ------------------ | -------------------------------------------------------------- | | `message` | `sticker_emoji` | The emoji of the sticker in the user's message | | `message` | `sticker_set_name` | The sticker pack username of the sticker in the user's message | If you set a configuration like below <figure><img src="/files/UECSmioXk02nGpPV9TDj" alt=""><figcaption><p>Telegram Sticker configuration re-using the sticker pack of the user's message</p></figcaption></figure> You can create an experience where the bot sends a sticker from the same pack to the user, thus creating a sense of personalization and better engagement. ![Using the same sticker pack from the user's message](/files/-MjTfXBdPkT_ickzmrb9) ## [Persistent Menu](#persistent-menu) A bot's "main menu" that is always-on that can be set up under the Profile section on the Personality page. This menu is an easy way to help people discover and access the core functionality of your bot at any point in the conversation. <figure><img src="/files/zcD7H8HqAq5OcQR62mvC" alt=""><figcaption><p>Setting the bot's persistent menu</p></figcaption></figure> <figure><img src="/files/piYgt3psPXfzJdbBphjm" alt=""><figcaption><p>How the persistent menu appears to a user</p></figcaption></figure> ## Default [Quick Replies](#quick-reply) A bot's "main menu" quick replies that can be set up on the Personality page. Although these are not visible to the user at all times like the Persistent Menu, they are helpful for remembering the main-menu quick replies, and can be added with one click in a Story. ![Setting up your Default Quick Replies](/files/-MjYNaOPNH4awRA-DmoV) ![Using the Default Quick Replies in a Story](/files/-MjYO57w6ekGrN9iN6p6) # Optimization When you launch your bot, the platform tracks analytics from the usage of your bot. This enables you to make [data-driven decisions](https://en.wikipedia.org/wiki/Data_driven_marketing) to improve your bot even further. The platform tracks: * **Stats** from users, stories, and your bot itself * **Click** Performance * Broadcast **Deliverability** ![Bot Analytics](/files/-MjYd-dmNVnBuUjSrydu) ## Stats Track data points about your chatbot's usage with all of its users. There are 6 types of stats: * Messages * Sessions * Time Spent * Sentiment * Users * Fallback Rate These stats can be seen on your bot's Dashboard, as well as on the Stories and Users pages. ## Messages Total number of incoming messages from your Users to your bot. This **does not** count Responses (i.e. outgoing messages), because the number of responses does not indicate usage performance of your bot. Total Messages is visible on the Dashboard, Stories, and Users pages. Messages details are available under Messages in the Advanced View of the Inbox page. ## Sessions Total number of sessions your Users have with your bot. They are directly affected by the Session Length that you set on the Personality Page. Shorter sessions lengths naturally lead to more sessions per user, so please be aware of this when changing you bot's session length. Total Sessions is available on the Users page. ## Time Spent The amount of time Users have spent interacting with your bot. It is calculated from the time difference between any two messages from your user. The diagram below indicates how it is tracked. <figure><img src="/files/DXhZTyVtrGhoK6DPxdnO" alt=""><figcaption></figcaption></figure> Time Spent is directly proportional to your bot's Session Length that you configure on the bot's Personality page. Longer session lengths naturally lead to more time spent, so please be aware of this when changing you bot's session length. Average Time Spent per Session is available on the Dashboard. Total Time Spent is available on the Stories and Users pages. ## Sentiment The quantified emotional tone of User Messages derived from the [AFINN-111](http://www2.imm.dtu.dk/pubdb/views/publication_details.php?id=6010) wordlist and [Emoji Sentiment Ranking](http://journals.plos.org/plosone/article?id=10.1371/journal.pone.0144296). There are 3 classifications of sentiments; positive, negative, and neutral. Positive sentiments have a value of > 0, negative sentiments have a value of < 0, and a neutral sentiment has a value of 0. This is helpful for you to classify your Users' happiness levels when using your bot. <figure><img src="/files/HTD6oaxRZKOVgqZNpP6U" alt=""><figcaption><p>Sentiment graph from the Dashboard page</p></figcaption></figure> Average Sentiment is available on the Dashboard, Stories, and Users pages. ## Users Total number of Users using your bot. This is a good indicator to estimate your bot's following, growth, and virality. New Users is the number of new user accounts created within a time period, and Active Users is the number of user accounts that sent at least 1 message or 1 click through your bot within a time period. New Users and Active Users are available on the Dashboard page. Total Users per Story is available on the Stories page. ## Clicks A record of a link visited by a User who clicked on a [URL Button](broken://pages/-MjJWNqbgKRgZrxTFuZn#button) in your Bot. Clicks are useful for tracking link engagement through your chatbot and give you granular details about * The identity of the user who visited a URL * What date and time they visit the URL * Which Text, Card, Audio, Video Response, or Persisted Menu they clicked on to visit the URL All Click records are available under the Clicks tab on the Inbox page. A summary of Clicks activity is available on the Dashboard page. ## Broadcast Records A record of a broadcast being received by a user in your Bot. When a broadcast is published to all or a targeted subset of users, it is throttled over a period of time to ensure maximum deliverability. With broadcast records, you can track * The identity of a user who received a broadcast * It's latency - the difference between the user's reception time and the broadcast's publish time * Whether the broadcast was completed for a user, or whether it incurred an error There are several reasons why a broadcast could incur an error for a user - they may have removed the chatbot from their messaging app, or your bot exceeded a messaging app's rate limits before a user received it. Errors and latencies are great for logging your broadcasts' performance. ## Wrong Responses A record of a Message that triggered an incorrect Response from the bot. When you launch your bot, Users will ask questions that are outside its scope more often than you would expect. Normally, these would trigger the fallback story in the bot <figure><img src="/files/xe4bmD8G9QToUBkouOFU" alt=""><figcaption><p>Incorrect Response</p></figcaption></figure> It may not only be the fallback story - your bot might display another existing story that you did not expect it to. When this happens, as the owner of the bot you could solve it in 2 ways: 1. Make the bot answer similar questions correctly in the future 2. Ignore this user's question as it is too customized If you choose the first solution, you may change the message's correction status from "correct" to "wrong". After that, you may use the Wrong Responses tab on the Inbox page as a Product Management tool to track all unhandled messages that led to wrong responses. <figure><img src="/files/uMk0ynMB8ZJpsuAHiyK9" alt=""><figcaption><p>Wrong Responses tab in the Inbox page</p></figcaption></figure> For each unhandled message: 1. Create a rule to fix it. 2. Click **Replay Message** to test your bot against the same message again *Now* and compare it to the time it was originally sent. <figure><img src="/files/WI7gE0iGZPmRRr8d655t" alt=""><figcaption><p>Replay Message in Wrong Responses</p></figcaption></figure> Wrong Responses is a Product Management Tool built into BotDistrikt to help you optimize your bot further post-launch. It's an alternative to other tools you use to manage these tasks like Trello, Asana, or JIRA. # Artificial Intelligence You may connect an AI Integration like Wit.ai or Dialogflow to make your bot handle large volumes of messages. With AI, your bot can * Detect the message **topic.** * Detect **important values** and phrases from a message <figure><img src="/files/IzpPJTMtEZtlniYw18B4" alt=""><figcaption><p>Message flow with AI integration</p></figcaption></figure> {% hint style="info" %} BotDistrikt works with a sub-topic of AI called Natural Language Understanding (NLU) only. BotDistrikt's Rules, Stories, and Engagement tools help assist with other topics like Natural Language Processing (NLP). {% endhint %} ## Utterance In every AI integration, a text message is also called an utterance. Utterances may be used to train and test AI integrations to detect intents, entities, and traits. ## Intent The topic of an utterance. Every AI integration makes an assumption that there are several hundreds of ways of saying the same thing. With this assumption, AI integrations: * Use utterances as questions * Produce topics - or intents, as answers. An intent is trained with an initial set of utterances from the developer. After an intent is trained, the AI platform receives live utterances from Users through your bot and finds which intent value most closely answers an utterance. ![Several utterances can be answered with just 2 intents](/files/-MjjTdyTocyvOKPz9Nrr) {% hint style="success" %} Intents should only be used in Rules, but never for assignments or storage with Actions. {% endhint %} {% hint style="info" %} Every AI platform allows you to train only **1 set** of intents. {% endhint %} ## Entity Important values in an utterance. Keywords and regular expressions are a good way to pick out important values, but they sometimes can be missed when handling large volumes of messages. Entities scale better on larger volumes and can have multiple types of values - text, numbers, dates, phrases, or even geographical coordinates. Unlike an intent, an entity has 2 facets; a name and a value. Its type is a default value of the AI platform itself. ![Utterance and Entity](/files/-Mjmyn8lUpHt5ZTcR2OF) {% hint style="success" %} Entities can be used in Rules, but are better used for assignments or storage with Actions. {% endhint %} {% hint style="info" %} Every AI platform allows you to train **multiple sets** of entities. {% endhint %} ## Trait An unstructured or non-obvious entity. Traits should be used for categorical classification of utterances for which there is no direct association between the keywords of an utterance with its meaning. Traits can only be of one type - Text. ![Traits detected from utterances](/files/-Mjjbeef2Vfh3sQnGCdT) {% hint style="success" %} Traits can be used in Rules, but are better used for assignments or storage with Actions. {% endhint %} {% hint style="info" %} Every AI platform allows you to train **multiple sets** of traits. {% endhint %} ## Confidence Level A value between 0 and 1, indicates the intent probability, entity, or trait being detected correctly. When handling large volumes of utterances, AI platforms can never be perfectly right or wrong. There can sometimes be false positives. As a result, AI platforms provide confidence levels to indicate the likeliness of an intent, entity, or trait detected as correct. Confidence levels can also be used in your Rules to ensure your bot only responds to minimum confidence thresholds that you set. ![Intents are detected with confidence levels](/files/-MjjdEY4djlwOfX8MfYe) ## NLP Attributes After an AI integration detects intents, entities, and traits, the detected values are stored in your bot's [NLP context](broken://pages/-MjJVh1pSLJxumjAwcRU#nlp-attribute) in a conversation session with a User. They can then be used in your Rules to make your bot respond to Messages. For example, using the above confidence level table, let's assume we have connected the Dialogflow integration. Then we can create a Rule called "user said hello" with 2 conditions ![We set a minimum confidence threshold of 0.8 for the "greeting" intent in our Rule](/files/-MjjfEJ2ZHDpTwRiTCFm) After this, this conversation can occur with a user > **User:** Hello!\ > `Bot detected greeting intent, AND its confidence exceeds the minimum threhold`\ > **Bot:** Greetings! How are you today? However, this conversation can occur with a user as well > **User:** Yo, how you doin\ > `Bot recognizes greeting intent, but its confidence does not exceed the minimum threshold`\ > **Bot:** I'm sorry, I don't understand what that means If you use an AI integration, it is imperative to train your bot with very similar words and tonality to how you expect your users to speak with your bot. This way, it can be trained to answer questions for your ideal customer profiles, and not for any random person who will not get any value from your bot. # OpenAI OpenAI's GPT engine is a powerful language model that you can integrate into your chatbot to enhance the chatbot's conversational abilities and experience for your end users. This guide walks you through integrating OpenAI into your BotDistrikt chatbot. To integrate OpenAI into your BotDistrikt chatbot: 1. Ensure you have **Created an active Access Token** on **Personality -> Settings** 2. Go to **Integrations --> Artificial Intelligence --> OpenAI** 3. Enter a valid API key\* and click **Save** Navigate to **Trainings** to train the OpenAI model <figure><img src="/files/wAb2zYhWIfDUJmY8ggpf" alt="" width="188"><figcaption><p>OpenAI --> Trainings (After Integrating OpenAI Through Valid API)</p></figcaption></figure> 1. Select the available chat model from the dropdown. 2. Choose the appropriate temperature according to your chatbot's personality. Increased temperature indicates more random responses to the prompts. Decreased temperature ensures more stable and predictable responses. 3. Maximum tokens to generate indicates your chatbot's response length. Requests use up to 2048 to 4000 tokens (shared between prompt and completion). Your limit varies by the model you choose in 1. A token (approximately) equals 4 characters in plain English). 4. **Top P** indicates the normalcy of words within a response. A higher number indicates using more normal words and less includes the inclusion of more unique words in your chatbot's responses. The diversity is controlled through a nucleus sampling of 0.5 (consideration of half of all likelihood-weighted options). 5. Adjust the **Frequency Penalty** to control how often your chatbot repeats the same words. High-frequency penalty for less repetition and low-frequency penalty for more repetition. 6. Adjust the **Presence Penalty** to control how much your chatbot focuses on specific topics. Set a high presence penalty for more variety in responses and a low presence penalty for more focus on a topic. 7. Set the **Max Conversation Tokens** to indicate the maximum number of tokens to keep in the chatbot's conversation history. As the conversation history grows, the oldest messages are removed (if tokens exceed the specified number). 8. Toggle **Generate Embeddings for Text Responses** to retrieve the results of a similarity search of text responses (from the websites and documents in **Sources**) and the users' input message. 9. Toggle **Generate Embeddings for Cards** to retrieve the results of a similarity search of cards (from the cards tab in **Responses** and the users' input message. 10. Select the **Embedding Model** between the website and document sources. The model represents words or phrases as numerical vectors in a continuous vector space, allowing computers to process and understand textual data more effectively. 11. Adjust the **Embedding Dimensions** to control the length of the embeddings to store and query for similarity searches. 12. To optimize responses from the document or web resources, enter a number in **Embedding Top K.** This feature presents the top K most semantically related entries or documents, enabling the RAG model to use these documents as reference to generate more informed, accurate, and relevant responses to the given input. 13. Toggle **Score RAGAS Metrics** to observe RAGAS scores for generated RAG completions. 14. Enter an **Intro Prompt** to provide context, instructions, or other information relevant to the model and use case. The prompt can determine the character, behaviour, disposition and function of the chatbot. To write effective prompts, describe the task you want it to complete and provide background information. Give the model some examples of the desired output. Also note that the order of presenting information matters. 15. **Import a Story** 16. The number of tokens used is displayed in the bottom right corner of the **Intro Prompt** box. Tokens are units of text that these models process and generate which the model can turn into embeddings. Example: "I am a chatbot" utilizes 5 tokens. Click **Save.** To test your bot, navigate to **Testing** and test your bot accordingly. *** \*To generate a valid OpenAI API key: 1. Create an OpenAI account 2. Log in to your OpenAI account via API login 3. Click on API 4. In the left sidebar, select API Keys 5. Click on **+ Create new secret key** button <figure><img src="/files/pcHGQgEIDfC17DzEXITe" alt="" width="375"><figcaption><p>Create new secret key</p></figcaption></figure> 6. Name your API key (for reference) 7. Choose an appropriate project 8. Set the level of permission required 9. Click **Create secret key** 10. In the popup, copy the secret key generated 11. Enter in BotDistrikt **Integrations --> Artificial Intelligence --> OpenAI --> API key** # Vertex AI This guide will walk you through Vertex AI integration with BotDistrikt to enhance your bot's natural language understanding and generation capabilities. Before you begin the integration process, ensure the following prerequisites: 1. Ensure you have **Created an active Access Token** on **Personality -> Settings** 2. **Google Cloud Account**: You must have a Google Cloud Project account to access Vertex AI services. 3. Go to [Vertex AI](https://cloud.google.com/vertex-ai) --> **Go to console** --> ![](/files/A4WoNVW5x34sFDNOzNjZ) 4. Open your [Google Cloud Console](https://console.cloud.google.com). 5. Click **IAM and admin** under **Quick Access.** <figure><img src="/files/ASpWhMWNsZ86lnOt8GXC" alt=""><figcaption><p>Google Console --> Quick Access --> IAM and admin</p></figcaption></figure> 5. On the left-hand side navigation panel, click **Service accounts** --> **+ CREATE SERVICE ACCOUNT** <figure><img src="/files/XasmWnarLNozHx4R5JFY" alt=""><figcaption><p>Setup a Service Account in Google Console</p></figcaption></figure> 6. Under **Roles**, add role as **Vertex AI user.** <figure><img src="/files/SW4bCoNNcdpduF6boZTO" alt=""><figcaption><p>Roles --> Vertex AI user</p></figcaption></figure> 7. On the **Service accounts** dashboard, click on the three vertical dots ![](/files/sKgqIQQPBu8Ld5hmavy3) under **Action** and select **Manage keys.** 8. Click **Add key --> Create new key.** Select **key type** as **JSON** and **Create.** <figure><img src="/files/HWelagDqDhnMPpzrzLEF" alt=""><figcaption><p>Create JSON key</p></figcaption></figure> In your BotDistrikt chatbot, go to **Integrations --> Artificial Intelligence --> Vertex AI.** Drop the recently downloaded JSON file to **Vertex AI private key JSON file** drop box. Once you successfully integrate Vertex AI to your chatbot, click **Training** and toggle **Generate Embeddings for Text Responses** ON. <figure><img src="/files/Vt7LYETAagf8a0gPoct4" alt=""><figcaption><p>Toggle Generate Embeddings ON.</p></figcaption></figure> In the **Intro** prompt, enter the following Retrieval Augmented Generation (RAG) or RetrievalQA Prompt: ``` Answer the question based on the context below. If the question cannot be answered using the information provided, answer with "I am not trained to answer that question". Context: {{nlp.query_responses}} Rules: - Answer strictly with only the Context provided above - If no Context is provided, do not use Vertex to answer, just say "I am not trained to answer that question" - If no Context is provided, do not make up an answer, just say "I am not trained to answer that question" - If someone asks about who you are or what you are, you must say "I am a chatbot assistant" ``` <figure><img src="/files/goQoXa07q2zzTw5mCxVy" alt=""><figcaption><p>Retrieval Augmented Generation (RAG) or RetrievalQA Prompt to Intro Prompt</p></figcaption></figure> To add a new website in **Sources**, navigate to **Sources -->** **Websites --> New Source Website.** 1. Enter a **Crawl Base URL** (base URL that the chatbot will crawl to find responses) <figure><img src="/files/F3uFgzTSPQuC9mmMDv1h" alt=""><figcaption><p>Enter a Crawl Base URL</p></figcaption></figure> Click **Crawl.** Or enter your website's **Sitemap** Click **Load Sitemap.** <figure><img src="/files/mIrb4LXNi8QtbHO6XY9H" alt=""><figcaption><p>Load Sitemap</p></figcaption></figure> You will see a list of the URLs available on the website. Once the webpages are loaded, click ![](/files/RtlksLApmpfqnwnA7NLl)beside each URL to inspect responses. Click **Add** to add individual resources, or **Bulk Add** to add resources in bulk. Once the resources are trained, check the Vertex AI embeddings. To check, click **Responses** on the source dashboard for the associated source. <figure><img src="/files/nhtzr4iOQzOopz3d4DdK" alt=""><figcaption><p>Click associated URL <strong>Responses</strong> to check Vertex AI response. </p></figcaption></figure> Successful source setup is indicated by a tick in front of Vertex AI. Test your sources through the chatbot widget. # Wit.ai Integrating your AI chatbot with Wit.ai, a natural language processing (NLP) platform developed by Facebook, enhances your chatbot's ability to understand and respond to user input effectively. Here is a step-by-step process for integrating your AI chatbot with Wit.ai: 1. **Sign up for Wit.ai** 1. Go to [Wit.ai](https://wit.ai/) and sign up through Instagram, Facebook, or your email address. 2. You will be redirected to creating a Meta account if you choose to sign up through Facebook. <figure><img src="/files/hewd7gpeTEym7vXw6RgN" alt=""><figcaption><p>Wit.ai Signup with Meta</p></figcaption></figure> 2. **Create a new Wit.ai app** Once logged in, click on +**New App** to create a new Wit.ai app. <figure><img src="/files/m0ufymvYXQwA1No4XIHB" alt=""><figcaption><p>Create App</p></figcaption></figure> * Give your app a name * Select a language * Choose visibility - open or private * Choose the default time zone for your app. * Click "**Create App**." <figure><img src="/files/ind5RxXz33r3bui8JYEd" alt=""><figcaption><p>Setup Bot</p></figcaption></figure> You will be redirected to your bot's dashboard. <figure><img src="/files/eBLlhQ6MAYtOrx6an8Ja" alt=""><figcaption><p>Wit.ai Bot Dashboard</p></figcaption></figure> Go to **Management --> Settings** <figure><img src="/files/cIAf0vwGkvk9UWTIKeHv" alt=""><figcaption><p>Go to Settings</p></figcaption></figure> <figure><img src="/files/Y60XPqJqrvtuiOyhLhnL" alt=""><figcaption><p>Settings Dashboard</p></figcaption></figure> Copy your **Client Access Token.** Copy this token as you will need it to make API requests from your chatbot. 3. **Train Your Wit.ai Model** * Go to **Understanding** on the left-hand side navigation panel. This is where you'll train your chatbot to understand user input. * Create and define entities (pieces of information) and intents (user intentions) that your chatbot needs to recognize. For example, if your chatbot is for a weather app, create entities like "location" and "date," and intents like "getWeather." <figure><img src="/files/vaeovjF1XPLgRTgGDds8" alt=""><figcaption><p>Add Utterance and Entity to Train your Bot</p></figcaption></figure> * Train your model by providing examples of user input and labeling them with the appropriate intents and entities. Wit.ai uses these examples to learn and understand user messages better. * Continue adding training examples until you have a sufficient dataset to cover a variety of user queries. 4. **Set Up Your Chatbot Integration** On your BotDistrikt Dashboard, navigate to **Integrations --> Artificial Intelligence** --> Wit.ai <figure><img src="/files/5DoAP8Q2jnJUUO7ijWix" alt=""><figcaption><p>Integrations --> Artificial Intelligence --> Wit.AI</p></figcaption></figure> <figure><img src="/files/hDk52rd25zEeJym2gKpO" alt=""><figcaption><p>Enter APP ID and Access Token</p></figcaption></figure> Click **Link to Wit.ai** <figure><img src="/files/7eZz1uGKMRo6zG4M6mE1" alt=""><figcaption><p>Completed Integration</p></figcaption></figure> Choose your training source from - **intents, entities, and traits** <figure><img src="/files/hPz0OFd9Qt1KunDqjFBs" alt=""><figcaption><p>Training Source --> Intents/Entities/Traits</p></figcaption></figure> Select from listed entities, intents and traits and click **Train AI** Test your bot in **Testing** <figure><img src="/files/Aal9LHne5g1bcRJRTCHo" alt=""><figcaption><p>Test your Bot Integration</p></figcaption></figure> 5. **Incorporate Wit.ai Responses** * Use the recognized intents and entities from Wit.ai's response to generate appropriate responses in your chatbot. * Your chatbot should be programmed to execute specific actions or provide relevant information based on the recognized user input. * Continuously improve your Wit.ai model by regularly updating and retraining it with new examples to enhance its understanding of user input over time. 6. **Test and Iterate** * Test your chatbot's integration with Wit.ai to ensure that it accurately recognizes user intents and entities and responds appropriately. * Monitor user interactions and gather feedback to identify areas of improvement * Iterate on your Wit.ai model and chatbot code to enhance its performance. You have successfully integrated your AI chatbot with Wit.ai and leveraged its natural language processing capabilities to provide more intelligent and context-aware responses to your users' messages. # Dialogflow Integrating your chatbot with your Dialogflow Agent Integrating BotDistrikt and Dialogflow is easy. You will simply need to retrieve a JSON file from Google and upload it to the BotDistrikt Platform. ## Setting Up Dialogflow To generate the account key, you will need to have the following: * A [Google account](https://accounts.google.com/signin) to sign into Dialogflow * A Bot on the [BotDistrikt Platform](https://flow.botdistrikt.com) {% hint style="info" %} If you already have an account on Dialogflow set up and an Agent ready, you can skip directly to [connecting Dialogflow to BotDistrikt](/artificial-intelligence/dialogflow#connecting-to-dialogflow)**.** Otherwise, we will go over [getting a Dialogflow Account](/artificial-intelligence/dialogflow#getting-a-dialogflow-account) and [creating a Dialogflow Agent](/artificial-intelligence/dialogflow#creating-a-dialogflow-agent) below. {% endhint %} ### Getting a Dialogflow Account <a href="#getting-a-dialogflow-account" id="getting-a-dialogflow-account"></a> If you do not already have an account, visit the [Dialogflow homepage](https://dialogflow.com/) and press **"Go to Console"** on the top right corner of the page. From here, you will be able to login to Dialogflow using your Google account. ![Signing into Dialogflow](https://blobscdn.gitbook.com/v0/b/gitbook-28427.appspot.com/o/assets%2F-L8qsmIDw5_reabURkaE%2F-Lj_2HbZkBx3k9sbv8nA%2F-Lj_7_Kom2BqrXIwU0eC%2FLogging%20into%20Dialogflow.png?alt=media\&token=77389a72-2bae-4d80-9107-b8000975e01b) If this is your first time logging into Dialogflow, you will have to grant Dialogflow access to your Google account. ![Granting Dialogflow Access to Your Google Account](https://blobscdn.gitbook.com/v0/b/gitbook-28427.appspot.com/o/assets%2F-L8qsmIDw5_reabURkaE%2F-Lj_2HbZkBx3k9sbv8nA%2F-Lj_94DZetz03_lUt_ge%2FGrant%20Dialogflow%20Access.png?alt=media\&token=bce88616-08b9-4a1e-b176-02087bac3eec) Press the blue **"Allow"** button to grant Dialogflow access to your Google account. Before you can access your account, you will need to select your country and accept the Dialogflow terms of service. ![Setting Up a Dialogflow Account](https://blobscdn.gitbook.com/v0/b/gitbook-28427.appspot.com/o/assets%2F-L8qsmIDw5_reabURkaE%2F-Lj_2HbZkBx3k9sbv8nA%2F-Lj_A0_UngmSf4UPNI1o%2FDialogflow%20Account%20Setup.png?alt=media\&token=fdfefa81-5b5e-4286-b986-f88a8837937c) Once you have completed the required fields, press the blue **"Accept"** button at the bottom to finish creating your account. This will take you to the Dialogflow dashboard. ![Welcome to Dialogflow](https://blobscdn.gitbook.com/v0/b/gitbook-28427.appspot.com/o/assets%2F-L8qsmIDw5_reabURkaE%2F-Lj_2HbZkBx3k9sbv8nA%2F-Lj_BNOsmtqhdrdZ9M-o%2FWelcome%20to%20Dialogflow.png?alt=media\&token=c5656a39-bbe7-4bfb-ae74-c3333bc69fc0) You have now created your Dialogflow account and have logged into Dialogflow. ### Creating a Dialogflow Agent <a href="#creating-a-dialogflow-agent" id="creating-a-dialogflow-agent"></a> In Dialogflow, each NLP module is called an "Agent." The agent will act as the brain of your bot and is the component that will help your bot understand and classify human languages. Once you log in to the dashboard, you can see your existing agents. If you do not have an existing agent that you would like to use, go ahead and click on **"Prebuilt Agents"** to create a new agent. ![](/files/-MivLkUfJJ-ii_bFR1R8) You will have to give your new Dialogflow agent a name. Note that this will only be used internally on Dialogflow and will not be seen publicly. You can also select the main language that you will be using. Choose the language of your target audience. This will be used for Dialogflow's natural language processes. Other langages can be added later. Select a timezone for your Dialogflow agent. It will be will be used for analytics purposes on Dialogflow. Note that a new Google Cloud Project will be automatically created to the Dialogflow Agent when created. This will be used to connect your Agent to BotDistrikt. Once you are done filling in the information, select the blue **"Create"** button on the top right. {% hint style="success" %} You have created a Dialogflow Account now. You can proceed to any of the following: * [Connecting to Dialogflow](/artificial-intelligence/dialogflow/connecting-to-dialogflow) * [Small Talk Module](/artificial-intelligence/dialogflow/small-talk-module) {% endhint %} # Connecting to Dialogflow Connecting an existing Dialogflow account to the BotDistrikt Platform On the [BotDistrikt Platform](https://flow.botdistrikt.com), navigate to Integrations and scroll down to the Dialogflow Card ![Dialogflow Card](/files/-Ltcca9MDEKEtOBoKqgn) In order to integrate with your Dialogflow agent, you will have to retrieve the API key. ### Getting the Account Key <a href="#getting-the-account-key" id="getting-the-account-key"></a> On the [Dialogflow dashboard](https://dialogflow.cloud.google.com), navigate to the Agent Settings by pressing the gear icon button on the left navigation panel. Make sure you have the agent you wish to connect selected. ![Agent Settings > Google Project > Service Account Link](/files/-M3trjVkZ1mS0S5at6fZ) From this page, click on the Service Account link under the Google Project section. This will open up a list of service accounts for your Agent's Google Cloud Project on the Google Cloud Platform. Click on the **IAM** link on the left sidebar and this open a list of all access accounts on your Agent's Google Cloud Project on the Google Cloud Platform Look for the entry with the name "Dialogflow Integrations" and press the pencil ✏️ button on the far right of the table. ![The Pencil Button of your Dialogflow Integrations member](/files/-LtcosJyI7GcY5ukO1zp) This will open up a right-sidebar. Change the Role type from "Dialogflow API Client" to "Dialogflow API Admin" ![Change "Dialogflow API Client" to "Dialogflow API Admin"](/files/-LtcpLACx_1t3h5GJrVJ) Once done, click on **Save.** Now click on **Service Accounts** on the left sidebar and you will be shown your service accounts ![Service Accounts > Dialogflow Integrations](/files/-M3ts1Vrii3BmU4YYkFI) Look for the entry with the Name column "Dialogflow Integrations" and press the Actions button on the far right of the table. Look for the three vertical dots. ![The Create Key Option](https://blobscdn.gitbook.com/v0/b/gitbook-28427.appspot.com/o/assets%2F-L8qsmIDw5_reabURkaE%2F-Lj_2HbZkBx3k9sbv8nA%2F-Lj_LB3RL5-S5haL5rbP%2FCreate%20Key.png?alt=media\&token=2e0d7a10-c341-4d5d-bd9d-c9879caf6fbb) Under the dropdown menu, select the **"Create key"** option. This should open up a menu where you can create a private key. ![Creating a Private Key for Dialogflow Integration](https://blobscdn.gitbook.com/v0/b/gitbook-28427.appspot.com/o/assets%2F-L8qsmIDw5_reabURkaE%2F-Lj_2HbZkBx3k9sbv8nA%2F-Lj_LYBXk11nnatLmBK_%2FCreating%20a%20Private%20Key.png?alt=media\&token=41efbb68-7162-421c-9cea-ac7043d4fa56) Make sure the JSON key type is selected and press the blue **"Create"** button. Your computer should begin downloading the key as a JSON file. When the download has completed, go back to the BotDistrikt Platform and upload the API key JSON file in the Dialogflow Card to finish your integration. Your linked card should look something like this ![Linked Dialogflow Integration](/files/-LtcqEZMzoWtZBN4KaoG) {% hint style="success" %} Your Dialogflow Agent is now connected to the BotDistrikt Platform. Your Agent will now respond to messages received from any of the channels linked to your Bot. {% endhint %} # Small Talk Module The Small Talk modules allows your chatbot to answer daily small talk and chitchat questions One of the most impressive uses of a Dialogflow Agent is to integrate its Small Talk module into your bot. This is key in making your bot more personable and creating its personality for its users. After all, making a bot's user experience great is the ultimate end-goal of the BotDistrikt Platform, so we highly recommend adding Small Talk to your bot. ## Finding the Small Talk Agent Prerequisite: [Getting a Dialogflow Account](/artificial-intelligence/dialogflow#creating-a-dialogflow-agent) Once you have a Dialogflow Account, on the left sidebar click on **Prebuilt Agents** ![Prebuilt Agents](/files/-LtcjBKRAYBjvr6gcnx_) You will be taken to a page full of pre-built Dialogflow Agents. In this page, you want to search for the **Small Talk** agent ![Small Talk agent](/files/-Ltcjdx7i05LFH7fGSPb) ## Importing the Small Talk agent Go to [Service Accounts](https://console.cloud.google.com/iam-admin/serviceaccounts?_ga=2.67764757.548304108.1630922054-2128437301.1630919891) 1. Select a project. 2. Click the email address of the service account that you want to create a key for. (if you don't see the email address option you can click on "+CREATE SERVICE ACCOUNT" on the top of the screen, below the search bar.) ![After Service Account is created](/files/-MivQtR3g2ok3qUF1dxK) 3\. Click on the newly created account and select the "KEYS" tab. ![](/files/-MivRYzcadiHf0tQB8-s) 4\. Click the **Add key** drop-down menu, then select **Create new key**. 5\. Select **JSON** as the **Key type** and click **Create**. Clicking **Create** downloads a service account key file. After you download the key file, you cannot download it again. Now you have successfully created a Small Talk ready Dialogflow Agent that can be imported into your bot on BotDistrikt. All you have to do now is follow the steps in: [Connecting to Dialogflow](/artificial-intelligence/dialogflow#connecting-to-dialogflow) After you have connected to Dialogflow, follow the steps in: [Importing Responses](/artificial-intelligence/dialogflow/small-talk-module/importing-responses) to finalise the Small Talk on the BotDistrikt Platform # Importing Responses Importing your Agent's responses to make them customizable on the BotDistrikt Platform The Dialogflow Integration is useful primarily for identifying intents from users' messages. However, if we want to keep the personality of your bot consistent, we will need to manage your bot's responses in one place: the BotDistrikt platform. This is why it is imperative to import your Dialogflow Agent's Responses to BotDistrikt. Go to your BotDistrikt account and click on the Integration tab -> Dialogflow ![](/files/-MivTsrXDapciTlAyRja) To do so, just click on the green **Import Responses** button on the Dialogflow Card ![Import Responses](/files/-LtcfJVU-Eo_ym-siDgo) It may take up to 1 minute to import all the responses, but when the import is complete, you will get a notification on the bottom right. ### Checking Imported Responses When the import is complete, you can read over to the [Rules](/features/rules) section and look for the Dialogflow Group ![Dialogflow Group](/files/-Ltcg5sxuWFx0ZgC4687) When this group is visible, you have validated that your bot's responses are now imported into BotDistrikt and the copy and language can be customized directly on the BotDistrikt platform. # Multilanguage Support BotDistrikt's platform multilanguage support allows you to train the same intent in different languages. ### Accessing Multilanguage Support <a href="#creating-a-dialogflow-agent" id="creating-a-dialogflow-agent"></a> 1. Navigate to Integrations > Dialogflow > Training or Testing tab <figure><img src="/files/tRb4hM0U50YPvdqPix8V" alt=""><figcaption><p>Language dropdown in Training</p></figcaption></figure> <figure><img src="/files/sEeKJzOYCOc3SNuvNQfc" alt=""><figcaption><p>Language dropdown in Testing</p></figcaption></figure> 2. Select a language in the dropdown. The language dropdown is used to deduce intents and entities is based on the user profile's "Language" option. 3. In the Training tab, once a language is selected, you can populate the utterance field with the intents in the respective language selected. 4. In the Testing tab, you can type a message with the keyword in the language of the newly-added intent(s) to test it out. <figure><img src="/files/H9KmEUfni2zoKZKSzQum" alt=""><figcaption><p>Dialogflow Multilanguage</p></figcaption></figure> # Webhook # Zendesk # Chatbase # Google Docs You may connect your Google Docs Account with BotDistrikt. Navigate to **Integrations** and click on **Docs** <figure><img src="/files/KrKTqtpiHL3G6sjKbS6F" alt=""><figcaption></figcaption></figure> You will be presented with two options to integrate Google Docs with the BotDistrikt platform. * Use a User Account - allows you to connect to Google Docs from your personal user account. * Use a Service Account - allows you to connect to Google Docs from a [service account](https://developers.google.com/identity/protocols/oauth2/service-account). <figure><img src="/files/70VgyHUmzxhxGutxWDju" alt=""><figcaption><p>Google Docs Integration Options</p></figcaption></figure> ### Use a User Account 1. Click on the **Sign in with Google** button and allow BotDistrikt to access your Google Account. <figure><img src="/files/73UZI3P50oToNLtAHAt0" alt=""><figcaption><p>Use a User Account</p></figcaption></figure> <figure><img src="/files/nUQITSFcHhREtazMtx4d" alt="" width="188"><figcaption></figcaption></figure> 2. After successfully linking your Google account, you will be able to see all available documents in the dropdown selector. <figure><img src="/files/hEfxA4cX2IWn9zNEfqwA" alt=""><figcaption><p>Successfully Integrated a User Account</p></figcaption></figure> <figure><img src="/files/PCVikiM4LtsYU7BysZXk" alt=""><figcaption><p>Adding a Google Doc as a Source</p></figcaption></figure> ### Use a Service Account 1. To generate your Google Docs private key JSON file, you must first open the [API Library](https://console.cloud.google.com/apis/library). <figure><img src="/files/NOseHTVtG7j1FavL2nDs" alt=""><figcaption><p>Use a Service Account</p></figcaption></figure> <figure><img src="/files/y9cMqdAZjuKUDPQS5VBl" alt=""><figcaption><p>API Library</p></figcaption></figure> 2. In the search bar on the API Library page, search for Google Docs API. <figure><img src="/files/Yi9agGDVor8abwOp54Az" alt=""><figcaption><p>Search for Google Docs API</p></figcaption></figure> 3. In the Google Docs API product details, click on **Enable**. <figure><img src="/files/as2EDRl4KQkaMYGkco1A" alt=""><figcaption><p>Google Docs API</p></figcaption></figure> 4. At the APIs & Services dashboard, click on **Credentials** at the left navigation panel. Once at the Credentials tab, click on **Create Credentials** and select **Service Account** from the dropdown menu. <figure><img src="/files/cnRgrt69lJMTe8jHeZzQ" alt=""><figcaption><p>Create Credentials</p></figcaption></figure> 5. Once at the Create service account page, fill in the necessary information for the service account details and permissions, and click **Done**. <figure><img src="/files/eWWU3bfhGyKW9kSDXe3u" alt=""><figcaption><p>Create Service Account</p></figcaption></figure> 6. At the service account dashboard, click on the hyperlinked email address of the service account that was just created to access the Service account details page. <figure><img src="/files/uhxjn2RIYhnibTmefD4M" alt=""><figcaption><p>Service Accounts for a Project</p></figcaption></figure> 7. Click on the **Keys** tab to view all service account keys. Click on **Add Key** and from the dropdown menu, select **Create new key**. <figure><img src="/files/h5yZyliF3LcWXTM5Dtxs" alt=""><figcaption></figcaption></figure> 8. In the modal that appears, select the JSON key type option and click on **Create**. You will be prompted to download the JSON file. <figure><img src="/files/PBDqvxggMnK531n6usXw" alt=""><figcaption><p>Select a Key Type</p></figcaption></figure> <figure><img src="/files/sRrIdbViJhO9WMjPM3x5" alt=""><figcaption><p>Private Key Successfully Saved</p></figcaption></figure> 9. Before uploading the JSON file on BotDistrikt’s platform, please ensure that the Google Drive API is enabled. This can be done by searching for Google Drive API in the search bar on the API Library page and clicking on the **Enable** button. <figure><img src="/files/UcftnooBUeqdSKgaL3R3" alt=""><figcaption><p>Search for Google Drive API</p></figcaption></figure> <figure><img src="/files/vyrXD2n6UttRyw5rXkhP" alt=""><figcaption><p>Google Drive API</p></figcaption></figure> 10. At the Google Docs integration page on BotDistrikt’s platform, upload the JSON file containing the private key to link the service account. <figure><img src="/files/lJIt1U0M46BoRMQVEdp1" alt=""><figcaption><p>Upload JSON Containing Private Key</p></figcaption></figure> <figure><img src="/files/5SJ0tnQLp9u6yFjJTYhW" alt=""><figcaption></figcaption></figure> ### Add Sources with a Service Account 1. To add a document as a source on the BotDistrikt platform via a Service Account, share the file with the service account email address. <figure><img src="/files/fcqGg4LCi4OoJlSgkp9D" alt=""><figcaption><p>Sharing File with Service Account Email</p></figcaption></figure> 2. Once shared, the file should show up as an available document to be used as a source on the BotDistrikt platform. <figure><img src="/files/ZETXn7Vw5LXA6hn7RmZk" alt=""><figcaption><p>Shared File Showing as Available</p></figcaption></figure> You can now head on to Sources to [train your LLM to learn from your Google Docs](/features/sources/google-docs) # Google Sheets You may connect your Google Sheets Account with BotDistrikt. Navigate to **Integrations** and click on **Sheets** <figure><img src="/files/4Sxt0ua3nVaBhWiN6xe7" alt=""><figcaption></figcaption></figure> You will be presented with two options to integrate Google Sheets with the BotDistrikt platform. * Use a User Account - allows you to connect to Google Sheets from your personal user account. * Use a Service Account - allows you to connect to Google Sheets from a [service account](https://developers.google.com/identity/protocols/oauth2/service-account). <figure><img src="/files/kpAe8dOtJc6bBAaTcvjN" alt=""><figcaption><p>Google Sheets Integration Options</p></figcaption></figure> ### Use a User Account 1. Click on the **Sign in with Google** button and allow BotDistrikt to access your Google Account. <figure><img src="/files/wjMMeuYFyHkNAa9tvqEG" alt=""><figcaption><p>Use a User Account</p></figcaption></figure> <figure><img src="/files/uWXM4bdshGW3ZpR1qCQd" alt="" width="188"><figcaption></figcaption></figure> 2. After successfully linking your Google account, you will be able to see all available spreadsheets in the dropdown selector. <figure><img src="/files/SWRqEjm8sRa8oi8aXdaL" alt=""><figcaption><p>Successfully Integrated a User Account</p></figcaption></figure> <figure><img src="/files/Ze4lYDYl2ip5HVnnfceX" alt=""><figcaption><p>Adding a Google Sheet as a Source</p></figcaption></figure> ### Use a Service Account 1. To generate your Google Sheets private key JSON file, you must first open the [API Library](https://console.cloud.google.com/apis/library). <figure><img src="/files/YtgaNYPwlixrHACUVvGH" alt=""><figcaption><p>Use a Service Account</p></figcaption></figure> <figure><img src="/files/fRBr2jPYILoRDKOrrPyl" alt=""><figcaption><p>API Library</p></figcaption></figure> 2. In the search bar on the API Library page, search for Google Sheets API. <figure><img src="/files/B80mmC8XUmCUQVNGjGBH" alt=""><figcaption><p>Search for Google Sheets API</p></figcaption></figure> 3. In the Google Sheets API product details, click on **Enable**. <figure><img src="/files/QHpjl14svq8cqKIn0jVR" alt=""><figcaption><p>Google Sheets API</p></figcaption></figure> 4. At the APIs & Services dashboard, click on **Credentials** at the left navigation panel. Once at the Credentials tab, click on **Create Credentials** and select **Service Account** from the dropdown menu. <figure><img src="/files/pKvqZqRhctRMNyVnmrm2" alt=""><figcaption><p>Create Credentials</p></figcaption></figure> 5. Once at the Create service account page, fill in the necessary information for the service account details and permissions, and click **Done**. <figure><img src="/files/x2pneQ8nw8lIMa1cjtmw" alt=""><figcaption><p>Create Service Account</p></figcaption></figure> 6. At the service account dashboard, click on the hyperlinked email address of the service account that was just created to access the Service account details page. <figure><img src="/files/pL7e1Vp4qncdfgkX5heg" alt=""><figcaption><p>Service Accounts for a Project</p></figcaption></figure> 7. Click on the **Keys** tab to view all service account keys. Click on **Add Key** and from the dropdown menu, select **Create new key**. <figure><img src="/files/UnwYADLlDMqpVhokTNaq" alt=""><figcaption></figcaption></figure> 8. In the modal that appears, select the JSON key type option and click on **Create**. You will be prompted to download the JSON file. <figure><img src="/files/QCvrDCPETwCdli4MmMIh" alt=""><figcaption><p>Select a Key Type</p></figcaption></figure> <figure><img src="/files/TMcreNzwDUKHQQGgtRK3" alt=""><figcaption><p>Private Key Successfully Saved</p></figcaption></figure> 9. Before uploading the JSON file on BotDistrikt’s platform, please ensure that the Google Drive API is enabled. This can be done by searching for Google Drive API in the search bar on the API Library page and clicking on the **Enable** button. <figure><img src="/files/Q0VBABEuwQtlhikNWNqc" alt=""><figcaption><p>Search for Google Drive API</p></figcaption></figure> <figure><img src="/files/23pozCjVz3P5CTnx8j9s" alt=""><figcaption><p>Google Drive API</p></figcaption></figure> 10. At the Google Sheets integration page on BotDistrikt’s platform, upload the JSON file containing the private key to link the service account. <figure><img src="/files/RGNFOmonUKlq7Cn7u30f" alt=""><figcaption><p>Upload JSON Containing Private Key</p></figcaption></figure> <figure><img src="/files/Gc2GaRh6x0MLDRcZS9j2" alt=""><figcaption></figcaption></figure> ### Add Sources with a Service Account 1. To add a sheet as a source on the BotDistrikt platform via a Service Account, share the file with the service account email address. <figure><img src="/files/LUkbuSHx7J5KSb69gyDu" alt=""><figcaption><p>Sharing File with Service Account Email</p></figcaption></figure> 2. Once shared, the file should show up as an available document to be used as a source on the BotDistrikt platform. <figure><img src="/files/fXdyghs5i6OOI6l2CZ5D" alt=""><figcaption><p>Shared File Showing as Available</p></figcaption></figure> You can now head on to Sources to [train your LLM to learn from your Google Sheets](/features/sources/google-sheets) # Salesforce