Documentor Guide

Introduction #

ChatBull is a php live chat plugin developed with latest technologies to solve the problem of communication in the business. It helps entrepreneurs, business owners, service providers or anybody who want to connect with their customers and understand their need.

ChatBull uses best frameworks CodeIgniter and Angular JS to serve an amazing real time chat experience.

You can use it on multiple sites, create unlimited departments, operators and unlock the limitless possibilities to connect with your potential customers. Its out of the box interface gives you an insight knowledge about your website visitors and their needs.

Trust in us, after having ChatBull, you will not only understand your customers but also your business which will help you grow it with a good pace.

Yes No

System Requirement #

To have ChatBull installed on your server, your server must fulfil following requirements:

  • PHP 5.6 or higher is recommended
    It should work on 5.3.7 as well, but we strongly advise NOT to run such old versions of PHP, because of potential security and performance issues, as well as missing features.

  • MySQL 5.1 or higher

Both of the above requirements are very basic and mostly available on all popular hostings like GoDaddy, BlueHost etc.

Yes No

Installation #

In this section, you will learn how to install Chatbull on all platforms. Which covers web app, desktop app (for both Mac & Windows) and mobile app. 

Yes No

Web Installation #

Step 0
Copying Files to Your Server

You must have got a main zip file named “chatbull-pro-x.x.x.zip” with your purchase. You will need to extract this file. Extracting this file will create a folder “chatbull-pro-x.x.x”.

Now, Go inside “chatbull-pro-x.x.x” and you will find a folder “chatbull-pro-installer”.

You need to upload this folder in the root directory of your server. Usually the root directories are called “public_html” on a linux based hosting or “httpdocs” on windows based hosting.

You can change the folder name “chatbull-pro-installer” to any appropriate name you prefer. For example, livechat, support-chat etc.

Now, you can easily access the installer with the URL http://yourdomain.com/livechat (in case, you named the chatbull-pro-installer folder to livechat) and replace yourdomain.com to the domain where you have uploaded the Chatbull to.

ChatBull installs in three easy steps. All these steps are self explanatory but here is a detailed information about each of the step.

Step 1
Create & Integrate Database

step-1

It requires following details to complete the step:

  1. Hostname
    This is usually “localhost� in most of the cases but could vary based on your hosting.
  2. Database Name
    Name of the database you have created on your server.
  3. Database Username
    Username of the user account on database server who has access to the above database.
  4. Database Password
    Password of the user account on database server who has access to above database.

Special Notes
But before you complete above steps, please go through with following notes.

  • We recommend you to create a separate database for ChatBull
  • If you are installing ChatBull in an existing database. Make sure that you have a full backup of your existing database and none of tables has prefix _chatbull

Fill all the detail and hit the CONTINUE button, this will connect your database if all the details you have entered is correct and will take you to the next step.

Step 2
Admin Account Setup

This step is to setup the administrator account for your ChatBull Admin Panel.

step-2

You will need to fill following detail on this step:

  1. Name – you can put name of the administrator person here.
  2. Display Name – this name will appear to your visitors when admin user will be chatting with them.
  3. Email – email address of the administrator.
  4. Password – password for the administrator.

Both email & passwords you set here will be used for the login purpose.

After filling all the detail here. You will need to click the “CONTINUE” button. If everything is good, it will take you to the final step as given below.

Step 3
Configuration Info

Congratulations!!!

You have installed ChatBull successfully on your server and it gives you all the information you need to login into the ChatBull admin panel.

Experience the excellence 🙂

step-3

Under the Here is what you can do next section you can find helpful articles which will make the rest necessary tasks easy for you to setup chatbull on all of the platforms.

Yes No

Verify Purchase Code #

verify-purchase-code

Go to  Settings   >   Global Settings  

Enter your purchase code in the input box labeled with “Purchase Code� and hit the VERIFY button.

Here is how you can find your purchase code

Yes No

Managing Sites #

With ChatBull, you can manage your multiple sites and for each site, you can manage different chatbox theme, departments, operators/agents etc.

Go to  Settings   >   Sites  

Here you can see a list of created sites as shown in following screenshot.

sites-listing

 

Yes No

Create a New Site #

Now, supposing that your are on  Settings   >   Sites Now, you should see a + button in right bottom corner of your window.

Clicking this + button will open a new popup as given in below screenshot.

create-new-site

Now, you need to fill following information to create a new site:

  • Site Title (Required)
    This is a title of your website or business.
  • Site URL (Required)
    The domain name or URL of your website where you want visitor chatbox to be placed.
  • Email (Required)
    This is the email address which will be used as “From� email header to send any email to visitor. Like transcript email upon completion of a chat session.

    ** We recommend that you use the same domain name based email address where you have installed chatbull to stop going these emails into spam or junk folder.
    For example, if you have installed chatbull on example.com then your email must be hello@example.com  or so.
  • Site Logo (Optional)
    Here you can upload logo of your website. This logo could be used (if uploaded) in the emails templates sent to visitors.

After filling the above information, hit the “SAVE� button and a new site will be created.

Yes No

Display Chatbox Widget on Your Site #

Go to  Settings   >   Sites  

Here you can see a list of created sites as shown in following screenshot.

chatbox-widget-code-icon-highlight

Click the highlighted icon under the “Action� column in above screenshot.

This will open a popup as shown in following screenshot and here you can find the chatbox widget code for the selected site. Clicking this text will make the whole chatbox widget code selected.

chatbox-widget-code-popup

Now, copy this code with Ctrl+C (on Widows) and Cmd+C (on Mac) and paste this on the website’s HTML. Right before the end of body (</body>) tag.

Yes No

Customize Chatbox Theme #

You can customize the look & feel for individual chatbox.

For that, go to Settings   >   Sites

And click the settings icon for the site you want to customize the chatbox of. See the screenshot below for reference.

site-setting-icon-highlight

Here you will find four tabs and one of them is Theme as shown in below screenshot.

site-theme-tab-selected

 

Clicking this tab will show all the options you can change the look & feel of the chatbox window on your site. Here is explanation on each of these options.

  • Choose Theme
    You can choose a theme (or we can say style) for your chatbox widget. The default theme is “Bubbles Boom�

  • Widget Type
    There are two type of widget types “Chat Icon� and “Chat Bar�. Choose the one which you like.

    In case you choose “Chat Icon�, You will see two more options. “Chat Icon Size� and “Enable/Disable Online Animation�.

    Under “Chat Icon Size�, you can choose one from three different sizes (large, medium and small) of the chatbox circle.

    Choosing Yes for “Enable/Disable Online Animation� will show a pulse effect on the Chat Icon and choosing NO will basically not apply that pulse animation.

  • Background Color
    This is the background color of the title bar as given in below screenshot.

  • Title Color
    This is the text color of the title bar.

  • Position
    If choosen Left then the Chatbox will appear in left bottom corner and if Right then in the right bottom corner of your website.

** This position can only change on desktop screens. Not on mobile devices.

Yes No

Site Settings #

This section details all the available setting options for an individual site. Here are these settings classified in their sections.

Yes No

General #

Go to Settings   >   Sites and click the settings icon for the site you want to access the site settings for.

    • Enable/Disable Chat
      This setting is to either display the chatbox to visitors on website or hide that.

    • Time Duration
      This setting is to set the frequency of calls to chat API. The value entered here is in seconds.
      NOTE: We recommend the default value entered 3.

    • Chat Mode
      You can change the chat mode to either online and offline.

      If this is online, it will keep tracking any live agents and will show the live chat window as online to visitors.

      If offline is selected, doesn’t matter if agents are online or offline. The system will keep showing the offline form/message to website visitors.

    • Bypass pre-chat form
      This option could be used to either bypass the pre-chat form which appear to take some basic visitor’s information. Like name, email address etc.

      If selected yes, then user will directly start the chat with agents rather than filling a required pre-chat form to input his/her information.

      If selected No, then a required pre-chat form will appear to ask the visitor’s information before starting the chat.

    • Send Chat Transcript
      This option is to allow to send the chat transcript after a chat session ends between website visitor and agent.

      There are three different selections available for this option:
      Yes – It will send the chat transcript to the visitor right after session completion.
      No – Chat transcript will not be sent
      Ask the Visitor – When visitor ends a chat session, a popup will appear to ask them if they want to receive the chat transcript to their email address.
      Note: This option will appear and work if and only if No is selected for Bypass pre-chat form.

    • Trigger Chatbox Automatically
      This option is to trigger the chatbox and bring the website visitor’s attention.

      If Yes selected for this, then under Trigger After you can set after how many seconds the chatbox should trigger.

      If No, then chatbox will not trigger.

      Note: This option will appear and work if and only if No is selected for Bypass pre-chat form.

    • Trigger After
      This option will appear if and only if you have selected Yes for above option “Trigger Chatbox Automatically�.

      Here you can set after how many seconds the chatbox should trigger automatically.

    • Show Feedback Form
      This option is to show a feedback form to the visitors when the chat session is completed. So that they can leave feedback for the agent they had communication with.

      Yes – If you want to show the feedback form
      No – if you do not want to show the feedback form to visitors

    • Show a department selection box to the visitor
      This option is to either show or hide a dropdown of department selection on pre-chat/offline form.

      Yes – then the dropdown box with department list will appear
      No – then the dropdown box will not show

    • Suggest agent in Chatbox Randomly to the visitor
      This option is to show the online agent’s profile (pic and name)  appear randomly to the visitors rather than the default chat symbol.

      Here is how this option’s values work:
      Yes – then agent’s profile info will appear randomly.
      No – the default chat symbol or chatbar will appear.

      NOTE: This option will appear and work if and only if “Show a department selection box to the visitor� option is set to No.

    • Enable / Disable File Sharing
      This option is to allow website visitors to send files to agents during the chat.

      Yes – Visitor can send file to agents
      No – Visitor can’t send file

    • Allowed file types
      Under this option, you can set file types by their extensions seperated by pipe ( | ) symbol to allow visitors to send files.

      NOTE: This option will appear and work if and only if option “Enable/Disable File Sharing� is set to Yes.

    • File Upload Size
      This is to set the maximum file upload size (in KB) to limit the visitors to how big file they can send.

      Note:
      The default size set to is 5000 KB (~5MB). This size also depends on the max upload size of your php configuration on server.

      This option will appear and work if and only if option “Enable/Disable File Sharing� is set to Yes.

    • Hide Powered By
      This option is to either show the powered by option (you can set it to anything you want) to your visitors or you can hide that.

Yes – Powered By will not show.
No – The text entered in “Powered By Textâ€�  will appear on chatbox widget.

Yes No

Text & Info #

Go to Settings   >   Sites and click the settings icon for the site you want to access the site settings for.

Now, click Text & Info.

    • Choose Default Avatar
      Under this option you can upload an avatar image to show when no agent is selected to chat. This avatar image will show on offline form when chatbar style is enabled.

    • Chatbox Title
      The text you set here is a default title for the Chatbar when it appears on page load.

    • Online Widget Title
      The text you set here will appear for the online pre-chat form as a title.

    • Welcome Message
      The paragraph text you set here is a welcome message shows right at the top of the online pre-chat form.

    • Waiting Message
      The paragraph text you set here will show to website visitors when they fill the pre-chat online form and are waiting for an agent to respond.

    • Offline Widget Title
      The text you set here will appear for the offline form/message as a title.

    • On Offline Show
      There are two options here to select from:

      Form – To show the offline form. If this option is selected then you can set a message in Offline Form Message option and this message will appear right at the top of the offline form fields.
      Message – If this option is selected. Then you can set a message in Offline Message option. This message will appear to visitors if all of the agents are offline.
      For a good practice, if you have a different ticket support system or so. You can link that here in this message.

    • Offline Request Success Message
      In this option you can set a text message which will show to users when they successfully submit an offline request.

      NOTE: This option will appear and work if and only if On Offline Show option the value selected is Form.

    • Request for Feedback
      In this option you can set a text message which will appear in chatbox right above the feedback form fields.

    • Set Feedback Success Message
      In this option you can set a text message which will show after successful submission of the feedback given by visitor.
Yes No

Departments #

Go to Settings   >   Sites and click the settings icon for the site you want to access the site settings for.

Now click the Departments Tab.

Here you can see a list of all the departments added and you can choose the departments which you want to enable for this particular site.

site-settings-department

 

Yes No

Global Settings #

Global settings are settings which will apply to the whole system and all of the sites added.

Go to Settings > Global Settings

  • Purchase Code
    Enter your purchase code you have received from envato when you purchased the product ChatBull.

    Here is a link to article on how to find your purchase code

  • Google Map API Key
    In this input box you can set your Google Map API Key to work that in Google Maps showing on the dashboard.

    You can get your API Key from here

  • Zoom Google Map
    Set the zoom level for the Google Map. The default value set here is 2. You can set it as per your need.

  • Time Duration in Operator Requests
    The value you put here in this text box is a frequency in number of seconds to call the operator APIs.

  • Notify All Requests to Admin
    There could be one of two option selected for this setting.

    Yes – Then administrator will get notified for any online request generated by visitors.
    No – Administrator will simply be considered as an agent and will be notified for his/her relative online requests.

  • Can Operators See Potential Visitors and Can initiate Chats?
    There could be one of two option selected for this setting.

    Yes – Then agent can see online visitors visiting the website along with their location information and pages they are visiting. Even if they haven’t initiated chat with support staff yet. In addition, operator can initiate chat with them.

    No – Then no online visitors will appear to operator and they can only see the visitors who has generated chat requests.

  • Enable/Disable Canned Messages
    There could be one of two option selected for this setting.

    Yes – Then agents will have option of canned messages. They can choose a canned message to send to visitors and can add or modify their own canned message templates.
    No – Then canned message will be disabled for the agents.

  • Can Operator Share Files?
    This option is to allow operators/agents to send files to visitors during the chat.

    Yes – Operators can send file to visitors
    No – Operators cannot have an option to send files

  • Allowed file types
    Under this option, you can set file types by their extensions separated by pipe ( | ) symbol to allow visitors to send files.

    NOTE: This option will appear and work if and only if option “Can Operator Share Files?� is set to Yes.

  • File Upload Size
    This is to set the maximum file upload size (in KB) to limit the operators to how big file they can send.

    Note:
    The default size set to is 5000 KB (~5MB). This size also depends on the max upload size of your php configuration on server.

    This option will appear and work if and only if option “Can Operator Share Files?� is set to Yes.

  • Admin Panel Logo
    Using this option, you can upload your own logo to update that in the ChatBull admin panel.

    Note:
    This will not change logo in desktop and mobile apps because of the license restriction.

  • Admin Panel Name
    The text you set here in this option will appear if no logo image is uploaded under Admin Panel Logo option. Also, this could be used in transcript and other emails throughout the system.

  • Admin Panel Email
    The email address set here will be used throughout the system to send email from.

    Note: It is recommended that the email address must of same domain where the Chatbull is installed and must be a valid email address created on server.
    For example, if Chatbull is installed at www.example.com then the email must be something@example.com

  • Choose Operator Chat Theme
    There are two types of themes available (Bubbles Boom, Classic) for the operator and administrator can set the type of theme they want to enable for operator’s chat panel.
Yes No

Departments #

To manage departments, go to Departments menu item.

Here you can see a list of all the created departments along with their assigned operators and status.

Yes No

Create a New Department #

To create a new department, click the + button given in bottom right corner of the screen as shown in following figure.

plus-icon

This will open a popup where you can enter the department name and hit the SAVE button to create the department.

Yes No

Modify a Department #

To modify a department, click the pencil icon under ACTION column of the specific row in the list of the departments.

This will open a popup box where you can change the name of the department and save it.

Yes No

Change Status #

A status of the department could be changed by clicking their current status for the individual row of the department under STATUS column.

If this is Active then it means, the department is currently active and clicking on this will turn it to disabled.

If this is Disabled then it means, the department is currently disabled and clicking on this will turn it to active.

Yes No

Delete a Department #

To delete a department, click the delete icon under ACTION column of the specific row in the list of the departments.

This will open a confirmation popup box with YES and No options to confirm before deleting a department. If chosen YES, then the department will be deleted from list.

NOTE: Deleting a department will permanently delete that from database. This cannot be recovered later. So, be careful when you perform this operation.

Yes No

Users #

To manage users of the system which includes admin, agents and visitors.

Here you can see a list of all the users.

 

Yes No

Create a New User #

To add a new agent, click the + button given in bottom right corner of the screen.

This will open a popup where user can fill the information about agent and can select sites (and then departments) from a checkbox list which the admin want that agent to be available to receive chat requests for.

Finally, hitting the Submit button will save all the information and create this new agent account.

Yes No

Modify User Account #

Administrator can modify agent & him/herselfs account. Clicking the PENCIL icon under ACTION tab for the individual record (as shown in below screenshot) will open a popup  where administrator can modify the user information and submit that again to save in database.

modify-account-pencil-icon

Yes No

Change Password #

Administrator can change agent & him/herself’s password. Clicking the LOCK icon under ACTION tab for the individual record (as given in below screenshot) will open a popup to set the new password.

change-password-icon

Yes No

Delete User Account #

Clicking the DELETE icon under ACTION tab for the individual record (as given in below screenshot) will open a confirmation box to confirm about the delete operation.

If selected YES, then that user account will be deleted from system.

delete-account-icon

 

NOTE: Deleting a user will delete all the chat history and other relational data of that user.

Yes No

Canned Messages #

Canned messages is a cool feature for agents to reply faster the visitors during the chat. These are cut & dry message templates which could be selected with a single click and send across.

Go to More > Canned Messages

Here all the created canned message will appear along with the name of the creator of that canned message under the NAME column.

Each canned message can be modified and deleted by clicking the PENCIL icon and DELETE icon respectively under ACTION column. Check the following figure for reference.

edit-delete-canned-message

 

Here all the created languages will appear in a list format. If you have installed a fresh Chatbull, then a default language English will be there

Yes No

Add New Canned Message #

Clicking the bottom right corner + button will open a popup where user can fill the title of the Canned Message and the text which will be sent in the chat upon selection.

NOTE:
Both title and message fields are used during the quick search while sending a canned message in chat panel.

Yes No

Language Settings #

With Chatbull, you can enable the chat in your own language. You can easily add labels, change messages and all the texts via an easy to use UI.

Go to More > Languages

Here all the created languages will appear in a list format. If you have installed a fresh Chatbull, then a default language English will be there.

Yes No

Add New Language #

To add a new language, you need to click the + button given in bottom right corner of the screen. This will open a popup (as shown in following figure). Here you can enter name of the language and a machine name. You can also upload a flag image.

Now, clicking the SAVE button will create this new language and will save in database. And this will start showing in the list of the languages.

Note:
By default the newly added language will have copy given in English language.

Yes No

Translate all Text & Labels #

Now, to translate all the labels & text messages, you need to click the TRANSLATE icon under ACTION column of that individual language record. Check the following figure for reference.

translate-lang-icon

Clicking this TRANSLATE icon will open a popup with a list of all the files to change those labels and text messages. Check the following screenshot for reference.

translation-files-list

Now, click individual file and it will list all the labels given in that file to translate them in your newly added language. Check the following screenshot for reference.

change-label-text

Yes No