Skip to main content

Basic Integration

In this quick start section, we'll discuss three common use cases that you can implement out of the box with our JavaScript API. The code examples below can be copy-pasted into your html, what is left for you is to add your Surfly widget key. If you want to customize your co-browsing flow, go to Settings -> Options to easily enable or disable features from there.

Quick Start

Surfly can be integrated in many different ways to become a part of your desired flow, but first let's start with the basics.

You can easily offer Co-browsing sessions to visitors on your website by adding our default 'Get live help' button. The setup is simple, just add a button and script (see the snippet below) to your page, then add your domain to the domain list in the dashboard settings. Now you're ready to use our 'Get live help' button to better assist your customers.

When a customer sees the button, they can click on it to request help from an agent. By default, the button will only appear when you have an available agent, so don't worry about missing requests!

After clicking the button a Co-browsing session starts, and the user can share the session link. Your agent will see this request in the Surfly dashboard, and can then start a Co-browsing session by taking the call from their queue page.

Default button example

// this is a surfly snippet

Surfly.init({widget_key:"**your widget key here**"}, function(initResult) {
if (initResult.success) {
// display the default Surfly button
if (!Surfly.isInsideSession) {
else {
console.log("Surfly was unable to initialize properly.")

It is important to keep in mind that Surfly needs to be able to reach the server over the network. You can use tools such as or to allow Surfly access to your local machine whilst you are developing locally. However, if you really want to work on an isolated LAN, we can set up a special server for you. If you want to have your own local solution, please feel free to contact us at

State transfer

When a Surfly session is started using the JavaScript API the state of the website will be transferred into the session.

This means that the JavaScript API will atempt to retrieve everything from your website's storage and make it available inside the collaborative session in order to make the co-browsed version of the website be in the exact same state as it was before the session was started.


If you need to transfer httponly cookies to, for example, keep the login state of the website, see the Session-Continuation guide.

In addition, there could be cases when the Surfly session is started while the user is in the middle of filling a form. That's why the JavaScript API will also retrieve all information it can find in <input>, <select> and <textarea> elements and transfer them inside the session too.

More precisely, the JavaScript API will atempt to transfer:

  1. Local storage
  2. Session storage
  3. Cookies available in document.cookie (be aware that metadata such as path or domain might not be maintained)
  4. Form fields values

Session end

When the Surfly session is ended, the JavaScript API will by default navigate the browser's tab to the url where the session ended in order to give the user a feeling of continuity. This behavior may be disabled with end_redirect_enabled session option. The navigation url can be also configured with leader_redirect_url or specified in SurflySession.end(url).

Custom button

With Surfly you can completely customize the look and feel of your co-browsing session, let's start by creating your own 'Get live help' button! Just create a custom button and add an onclick handler to it:

<button onclick= "Surfly.session().startLeader()">Start a session</button>

Custom button example

Stealth mode

Our stealth mode setting enables you to start co-browsing from your website by pressing Ctrl and Enter on your keyboard. This can be useful when you want to make Surfly invisible to your users.

To enable stealth mode, you need to enable key_combo_to_start option on the Settings page, and use the same script as shown above. If you don't want to have a Surfly button on your website you can simply remove Surfly.button(); from the script.

Integrate with custom chat solutions

There are two different ways to use Surfly together with other chat solutions:

  • Through our built-in integration for Intercom, Olark, LiveChat and Zendesk
  • Simple integration with other chat solutions

Intercom, Olark, LiveChat and Zendesk

If you make use of Intercom, Olark, LiveChat or Zendesk, we already have a chat feature ready for you that allows you to start co-browsing directly from your chat widget, by simply typing ^surfly.

Example with Intercom

Let's say your agent is talking to a customer through your Intercom chat widget. The customer is stuck on the website and needs help filling in a form. The agent suggests to join the customer in their browser and the agent starts the co-browsing session by typing ^surfly. The co-browse session starts on the customer's side, on the exact same webpage. A four number session ID is displayed to the customer, which can be communicated to the agent in order for them to identify the correct co-browse session from the Surfly queue.

To enable this feature, just add the above script from the "Basic integration" section to the page you want to be able to co-browse from, and enable the “Chat integration” option from your Surfly dashboard, or add it to the script by setting chat_integration to “intercom”, “olark”, “livechat” or “zendesk”. Click here for our video tutorial.

Other chat solutions

If you make use of a different chat solution, you have to make sure that you load their snippet within the Surfly script to avoid loading their chat widget twice (both on the original page and again within the Surfly session).

We add a condition to the end of the below script to make sure that a second chat window doesn't open when a Surfly session starts.

Then simply add the snippet of your chat solution in the script.

Now you'll be able to communicate with your customers without any disturbance, both inside and out of your co-browsing session.


When you integrate Surfly with another chat solution, the Z-index of the chat window might be lower than that of the Surfly co-browsing iframe. The Surfly iframe has a Z-index of 2147483547

You can use below example to integrate Surfly together with your third-party chat solution:


Surfly.init({widget_key:'**your widget key here**'}, init => {
if (init.success) {
// display the default Surfly button

// Add your chat solution's snippet below
// ...
// End of chat snippet

UI customization options

The basic integration script above comes with default settings. When you log in to your Surfly account and go to "Settings" >> "Options" you can see which options are enabled or disabled. You can adjust these settings from the dashboard, but you can also update them by adding them to the above script.

Options priority

When you set settings through the JS API, these will take priority over the value in the Options page of the Surfly dashboard

The most common UI elements that you might want to dive into further are:

Overall branding: The overall branding colors, logo, and dashboard background image can be modified to suit your brand. These options can be found under "Settings" >> "Options" >> "Company settings".

Please ensure that each of your chosen text colors significantly contrasts with the respective background color. White is usually a good choice for text on dark backgrounds; black is usually a good choice for text on light backgrounds.

Branding primary colorSurfly redThe main color for menus and buttons
Branding primary text colorWhiteThe color for text on top of the primary color
Branding secondary colorReddish brownThe hover color for menus and buttons, and for unselected text and icons
Branding secondary text colorWhiteThe color for text on top of the secondary color
Branding logoSurfly logoA URL for a custom image to load in the top-left corner of the dashboard
Branding logo linkSurfly homepageA custom URL that the user will be sent to when clicking the logo in the top-left corner of the dashboard
Dashboard background imageA mountain lakeA URL for a custom image to show in the background of the dashboard

The dock: The dock contains buttons which you can use to control the co-browsing session. There are three ways in which you can customize the functionality of the dock. By default, the Surfly chat widget is visible at the start of the session, and the dock only appears when you minimize the chat.

start_with_chat_openfalseStart sessions with the right sidebar open. (Note: the right sidebar contains text chat.)

Switching control: there are three ways to customize the flow of how control over the session can be switched between the users.

host_switching_allowedtrueAllow any participant to ask for host rights. Space Owner can take the Host rights at any time.

Navigating to a new URL: this button allows your users to navigate to other websites.

new_urls_allowedtrueAllow participants to open new tabs. If set to false, nobody in the session can open new tabs.

Inviting other users to the session: by clicking this button, you would open a popup window that allows you to send a co-browse invite to others, or you can copy the co-browsing link instead.

invitations_allowedtrueAllow participants to invite others to an ongoing session.

Popup at the end of the session: it can be very useful to add a popup at the end of the co-browsing session. It's a great way to get feedback from your users through a survey for instance.

end_of_session_popup_url""URL of the page that will open in a popup window after the session ends.

Confirmation modal body: Customize the body of the confirmation pop up that is displayed when session_start_confirmation is set to true and the user wants to start the session.


You've requested assistance and a secure co-browsing session will be prepared to facilitate this request.

The agent that will assist you will not be able to see any open tabs in your browser or sensitive information such as passwords.

Do you want to proceed to connect with the agent?

the body of the confirmation pop up

A reference of all customizable options can be found in the Docs on the Session Options page.

Basic landing page

In the previous examples a customer would click on a button and then be placed in a queue. Alternatively, you can also create a landing page to start co-browsing from. You can guide your website visitors to this page, or you can easily send the URL to your clients. When someone visits this page, a co-browsing session automatically starts and the agent can join by taking the call from the queue. After the session starts, you can redirect to an existing page on your website, or you could for instance, also add this landing page functionality to a product demo page.

You can easily turn any page on your website into a landing page. Just implement the Surfly initialization script on the page, and start sessions directly by adding #surflystart to the end of the URL like this: