Firefly API v1.1.3

1. Introduction

Firefly co-browsing can be added programmatically to your web application via our API.

2. Use Cases

Firefly's co-browsing API is intended for deploying Firefly at scale across many websites. Primary use cases include adding Firefly to chat applications, customer support software, or enterprise software deployments.

3. Requiring Files

Firefly co-browsing loads all of its JavaScript dependencies through this script tag:

<script type="text/javascript">
(function() {
window.fireflyAPI = {};
fireflyAPI.token="Your Token Here";
var script = document.createElement("script");
script.type = "text/javascript";
script.src = "";
script.async = true;
var firstScript = document.getElementsByTagName("script")[0];
firstScript.parentNode.insertBefore(script, firstScript);

This tag must be added to all pages where co-browsing is desired in one of two ways:

  1. Add the tag to your application’s JavaScript loader and dynamically build that tag OR
  2. Explicitly add the tag to the JavaScript your customers must copy into their HTML pages when installing your software

Note: Firefly's JavaScript dependencies are loaded asynchronously, meaning they will not slow down your application's load time or your customer's page load time.

4. Using fireflyAPI.ready()

Since our script loads in our other scripts asynchonously, the fireflyAPI object may not be fully ready when the document's ready event is triggered. Therefore, we have our own function called firelfyAPI.ready(). This function takes either a function or an array of functions that are called when our scripts load.

To avoid a race condition, wrap any function calls by the fireflyAPI object in a function which is passed to fireflyAPI.ready().


Note: To use fireflyAPI.ready, insert the line of code below into your script tag. If it is not inserted, the function will not work.

fireflyAPI.ready=function(x){if(typeof x=="function")x=[x];fireflyAPI.onLoaded=fireflyAPI.onLoaded||[];for(var i=0;i<x.length;i++){if(fireflyAPI.isLoaded){x[i]();}else{fireflyAPI.onLoaded.push(x[i]);}}};

5. Setting Options

Firefly lets you set user-specific options prior to starting a co-browsing session. You can set an option with the following command:


The options are:

  1. Styling Theme

    This option lets you specify the styling theme of our notification modal.


    fireflyAPI.set('theme', 'black');

    Option name: theme


    default - Top of the modal is blue.

    black - Top of the modal is black.

  2. Starting Message

    This option lets you specify the message that appears for the customer when they start a browser sharing session. If you're using a session code, the message will appear below the code. If you are not using a session code (using the 'startAPI' function) it will be the sole message the customer sees. It's a great place to prompt your customer to call your support hotline, to engage in a chat session with a support rep, or to simply give them feedback that they started a session.


    fireflyAPI.set('message', 'Please call 917-344-3322 and give the code above to your support representative');  

    Option name: message

    Values: Can be any string

  3. Whitelabling

    This option lets you specify whether you would like to remove Firefly branding from the modal.


    fireflyAPI.set('whitelabel', true);

    Option name: whitelabel


    true (keyword, not string) - Remove Firefly branding from the modal.

    false (keyword, not string) - Keep Firefly branding on the modal.

6. Making Requests

  1. Include the Firefly dependencies as specified above in Step 3: Requiring Files
  2. Call our API from the customer's page with the following function:
  3. fireflyAPI.start(key,[options],callback);


    • key is the API key provided in your Dashboard. This can be found at
    • callback is the function you will write in the next step (Step C)
  4. Define a callback function to handle our API response. This function should be passed into the "fireflyAPI.startAPI(key, callback)" function above:
  5. function callback(co_browsing_url) { console.log(co_browsing_url) };


    • co-browsing_url is the parameter passed into your callback by our application
  6. Firefly will ask the customer if they would like to start co-browsing via a modal prompt
  7. If yes, Firefly will call your function "callback" and pass in "co-browsing_url", a unique public URL, as the parameter. This is the correct response. An incorrect response will return "null".
  8. Your callback function should prompt your representative with the returned URL. You might consider opening up a new tab automatically for the representative.
  9. After following the URL, the representative will be connected to the customer's page.

7. Technical Support

If you're having difficulties, we want to help! Our team can be reached via email at, or during normal business hours (Eastern Standard Time) by calling (213) 784-0273.