How do you let your website's visitors contact you?
There are 2 strategies to add a chat button:

• Use Butterflive Incite: using this feature, you can add a chat button without a single line of code. The chat button can appear only when the score reaches a threshold you can specify. This is the easiest way.
• Or use custom code to add your chat button yourself. You must of course be proficient in Javascript to code your own button. Using this technique, you can have a full control over your chat button styling and behaviour.

Note: This page explains how to add a "chat" button on your website.
For the chat button to work you first need to install the Butterflive Tracking Code on your website.

In this document, we will first introduce you to the Butterflive Incite approach and then we will discuss the custom code approach in depth.

Butterflive Incite

Butterflive Incite is a slider that appears at the right bottom of browser window, when the visitor's score reaches a threshold.
Note: Butterflive Incite appears only if at least one agent is available.

Enabling Butterflive Incite is done from your Butterflive account. Log into your account and then access the Butterflive Incite page.

1. Score threshold: The visitor will see the Butterflive Incite window when the threshold is reached.
2. Default / Custom contact area: Butterflive proposes a standard popup for Incite. Use the custom option if you want to code the Incite popup yourself, using your Javascript code. This will completely disable the default behaviour.
3. Title: by default, « Need help? » is printed as a title of the Butterflive Incite window. The title is the only thing the visitors can read when the window is reduced.
4. Popup text: here, you can enter the main text of the popup.
5. Button text: The text of the contact button. « Contact us », by default.
6. By default, the Incite window is displayed only if the visitor's score reaches the threshold. However, you can decide to display the Incite window all the time, in reduced mode by clicking the "Show the popup title by default". It will still maximise when the threshold is reached.

Using custom code

Requesting a chat with an agent

Requesting a chat with an agent is easy. All you have to do is calling a single line of code:

  Butterflive.requestChat();

So if you want to add a chat button, you just need to write:

  <button onclick="Butterflive.requestChat();">Chat with an agent</button>

At your convenience, you can use a collection of image-buttons provided by Butterflive.
For instance:

    <button onclick="Butterflive.requestChat();" style="padding:0; border: none; background-color: white">
      <img src="http://www.butterflive.com/sites/default/files/chat_120_60_green.png" alt="Contact an agent" />
    </button>
 

This is enough to get started, but you will soon want more.
Indeed, your chat button will always be visible, but what if there are no agents connected to answer your visitor?
We will see how to cope with this case in the next chapter.

Detecting agents availability

We will improve our button. The button we will design will automatically appear when an agent is available, and automatically disappear if there are no agents available.
To do this, change the code of the button this way:

      <div id="butterflive_button_agent" style="display:none">
        <button onclick="Butterflive.requestChat();" style="padding:0; border: none; background-color: white">
          <img src="http://www.butterflive.fr/sites/default/files/chat_120_60_green.png" alt="Chat with an agent" />
        </button>
      </div>
      <div id="butterflive_button_noagent" style="display:none">
        <button onclick="Butterflive.requestChat();" style="padding:0; border: none; background-color: white">
          <img src="http://www.butterflive.fr/sites/default/files/contact_120_60_green.png" alt="Send a mail to an agent" />
        </button>
      </div>
 

If you use Butterflive in asynchronous mode

Modify the startup options this way:

    <script type="text/javascript">
      bflOptions = {
        ...,
        onCanChat : function() {
        document.getElementById("butterflive_button_agent").style.display = "";
        document.getElementById("butterflive_button_noagent").style.display = "none";
      },
        onCannotChat : function() {
          document.getElementById("butterflive_button_agent").style.display = "none";
          document.getElementById("butterflive_button_noagent").style.display = "";
        }
      }
    </script>
 

If you use Butterflive in synchronous mode

Add the following snippet of code in the <head> tag:

    <script type="text/javascript">
      Butterflive.onCanChat(function() {
        document.getElementById("butterflive_button_agent").style.display = "";
        document.getElementById("butterflive_button_noagent").style.display = "none";
      })
        Butterflive.onCannotChat(function() {
          document.getElementById("butterflive_button_agent").style.display = "none";
          document.getElementById("butterflive_button_noagent").style.display = "";
        })
    </script>
 

If you are a Javascript guru, you probably already know what this code is doing.
In the HTML part of the code, we define 2 div elements. One will be displayed when there is an agent available (butterflive_button_agent), and one when no agent is available (butterflive_button_noagent).

The Javascript part is registering 2 callback functions.
The onCanChat startup parameter (or the Butterflive.onCanChat function) registers a function that will be called when the visitor can request a chat.
The onCannotChat startup parameter (or the Butterflive.onCannotChat function) registers a function that will be called when the visitor cannot request a chat.

Using this code, the "Chat" button will appear only when agents are connected and available.
Of course, you will need to adapt this code to match the design of your website. Do not hesitate to use the callbacks to add effects when displaying the button, etc... You are only limited by your imagination.

Advanced features

Butterflive can give you more information than simply letting you know if you can chat or not.
Actually, at any time, you can use these variables:

• Butterflive.nbAgents: contains the number of agents currently connected to Butterflive.
• Butterflive.nbAgentsInChat: contains the number of agents that are currently involved in a chat. Therefore, (Butterflive.nbAgents - Butterflive.nbAgentsInChat) represents the number of agents that are free to chat.
• Butterflive.nbVisitorsWaiting: contains the number of visitors that are waiting to chat with an agent. This is very useful to estimate the waiting time of a visitor.

Furthermore, you can register callbacks to track the value of these variables.

• Using the onNbAgentsOnlineChange startup parameter or the Butterflive.onNbAgentsOnlineChange, you can register callbacks called when the number of agents is changing.
• Using the onNbAgentsAvailableChange startup parameter or the Butterflive.onNbAgentsAvailableChange, you can register callbacks called when the number of agents available to chat is changing.
• Using the onNbVisitorsWaitingChange startup parameter or the Butterflive.onNbVisitorsWaitingChange, you can register callbacks called when the number of visitors waiting for a chat is changing.

An example is provided below:

Asynchronous mode

      <script type="text/javascript">
        // Displays an alert box each time the number of connected agents changes
        // The number of agents is passed in parameter of the callback function.
        // This code must be inserted just after the declaration of the bflOpsions variable.
        bflOptions.onNbAgentsOnlineChange = function(nbAgents) {
          alert("Number of agents connected changed: "+nbAgents);
        } ;
      </script>
 

Synchronous mode

      <script type="text/javascript">
        // Displays an alert box each time the number of connected agents changes
        // The number of agents is passed in parameter of the callback function.
        Butterflive.onNbAgentsOnlineChange(function(nbAgents) {
          alert("Number of agents connected changed: "+nbAgents);
        })
      </script>