Back to top

Co-Browsing session options

Here, you can find the reference tables for each of the Surfly session options. You can choose the aspects of Surfly’s functionality you want to integrate into your website and personalize your co-browsing sessions. These parameters can be set in the options panel or used in the Javascript or REST API.

Note: Changes to the code will take priority over changes to the options panel.

Reference Tables

Chat box

Option Default Description
chat_box_color #eb777f Color of UI (chatbox) elements inside the session
dock_top_position false By default we place the dock at the bottom-left, with this option you can put it on top
docked_only false Only show the control options, do not show a video / textchat box
ui_off false Just co-browsing, no user interface (enterprise only)
newurl true Should we show the ‘newurl button’ in the widget?
store_chat_logs false If enabled, chat logs will be available for download in Surfly dashboard
sharing_button true Should we show the ‘sharing button’ in the widget?
allow_control_switching true Enable control switching functionality
allow_pause false If enabled, leader will be available to pause session


Options below set the default drawing settings. Note that you can change them during a session using JS API.

Option Default Description
drawing_color “default” “Magic marker” color. Possible values: default, red, yellow, blue, green, purple, magenta
drawing_mode “temporary” “Magic marker” mode. Possible values: temporary, permanent, disabled
drawing_width 15 “Magic marker” width
drawing_timeout 3 “Magic marker” timeout


Option Default Description
videochat true Is videochat allowed?
videochat_autostart false Start videochat automatically after a session loads

File sharing

Option Default Description
filesharing true Allow file sharing
allow_original_file_download false Allow users to download shared files (when set to false, users can only view them)


Option Default Description
start_muted false All participants start with muted microphone
enable_sounds true Enable sound notifications

Button appearance

Option Default Description
hidden false Do not show the button
language ‘en’ Language of the interface
position ‘bottomleft’ Positions the Surfly Support Button. The options are: ‘bottomleft’, ‘bottomright’, ‘middleright’

Control switching

Option Default Description
agent_can_request_control false A follower can request control, after which it can be granted by the leader
agent_can_take_control false A follower can switch control without an explicit leader consent
agent_can_end_session true Allow terminating a session from the follower’s end

Developer console

Option Default Description
verbose_console true When set to false, non-important console messages will be silenced

Screen options/viewport

Option Default Description
max_height 0 Restrict max height of the viewport
max_width 0 Restrict max width of the viewport
min_height 0 Restrict min height of the viewport
min_width 0 Restrict min width of the viewport
set_to_smallest false By default the page, as the leader has it, is scaled to fit follower’s screen. Set the option to ‘true’ to resize the active viewport to the viewport size of the participant with the smallest screen

Session Appearance

Option Default Description
show_cursors false Show mouse cursors of the users not in control

Enterprise options

Option Default Description
white_label false Do not show a Surfly logo (enterprise only)
blacklist “[]” (enterprise only) Restrict access to the specific resources.
whitelist “[]” (enterprise only) Allow access only to the specific resources.

More information on restrictions

Session start

Option Default Description
auto_restore true (JS API only) automatically restores a session after a page reload
autohide_button true Hide the Surfly button when no agent is available
block_until_agent_joins true If using the Surfly button, block the screen until a follower joins
chat_integration "disabled" Enables integration with popular chat solutions. If enabled, you can type ^surfly in a chat to start a cobrowsing session. Currently supported: disabled, intercom, olark, and zendesk
enhanced_ios_scrolling true Improves scrolling expierence in iOS. Might affect styles on the page
format_session_id true Change the session id to something easy to communicate over the phone (eg, 123-123-123)
language "en" Language of the interface
shake_to_start false On mobile, shake the device 3 times to start a session
show_loading_screen true Show the loading screen when starting a session
splash true Do we need to show the splash screen on session start?
start_docked false starts the chat box in docked mode, but can be expanded during the session
stealth_mode true When enabled, users can use CTRL + ENTER to start a Surfly session
url current page Initial URL that will be opened inside the session. Only available in REST API at the moment
url_mangling false Enable url mangling. Enable it if you want to hide original url from users

File downloads

Option Default Description
share_downloads true Allow users to share downloaded files. If this option is disabled, you can still use the file_download event in JS API


Option Default Description
only_embedded_sessions false By default, if 3rd-party cookies are disabled, we will start the session in a new browser tab. If this option is set to true, Surfly will not start session when 3rd-party cookies are disabled.
cookie_transfer_enabled true Enable cookie transfer between original- and Surfly sessions
cookie_transfer_scopes Allows to specify a detailed cookie configuration (see below). This option is required if cookie_transfer_proxying is enabled
cookie_transfer_proxying true Enable transfering httpOnly cookies (requires a continuation point set up).
cookie_transfer_urls List of the session continuation points

The cookie_transfer_scopes setting allows a fine-grained tuning of which cookies should be transferred. If specified, it should contain a list of JSON objects, each of them describing a single cookie using name, path, domain, and httponly properties:

cookie_transfer_scopes: [
   {"name": "shoppingcart", "httponly": true, "path": "/cart", "domain": ""},
   {"name": "sessionid", "httponly": false, "path": "/", "domain": ""}

The example above describes two cookies: shoppingcart, which is available on all pages under, and sessionid, which is set for all subdomains of

More information on session continuation

Session end

Option Default Description
follower_redirect_url “” After the session ends, redirect the follower to a custom URL
leader_redirect_url “” After the session ends, redirect the leader to a custom URL
on_end_redirect_follower_to_queue false After the session ends, return the follower to the Surfly Queue page
end_of_session_popup_url “” If this parameter is set, after the session ends the user will see a popup window with contents from the specified URL
disable_end_redirect false For sessions started with JS API, disable automatic redirect to the last co-browsed page

Option details

Here, you can find more detailed examples of the widget options that require specific syntax.

Blacklist and Whitelist format

A string representation of the JSON array is expected. Every element of the array is an object with the following properties:

  • pattern - regular expression. The requested url will be matched to this regular expression

  • (optional) redirect - an url to redirect the user to. You can also specify the special {% raw %}{{referer}}{% endraw %} pattern in the beginning of a redirect link, and that will be replaced by the Referer value at the moment of redirect. Basically, the user will be redirected to the page where they clicked the restricted link.

  • (optional) type - restriction type. If present, and set to "all", restriction will be applied to all requests (otherwise restrictions affect only requests to top-level pages)

A blocked url is always added as a query parameter to the redirect url:

If a session was started with the Surfly button, and you want to end the session when a user requests a restricted page, redirect them to the page that includes widget.js and execute the following code:


endSession function will trigger the following events:

  • session continuation

  • end of the session

  • leader is redirected to the page specified in redirect_url

Note: Surfly uses PDF.JS from Mozilla to load PDFs through our widget. If you enable whitelisting and still want your users to be able to open PDF files through our chat widget, please add this regex to your whitelist:

  "pattern": ".*mozilla.github\\.*"

Blacklist example: Restrict access to the website When the user tries to access they will be redirected to the default page provided by Surfly

    "pattern": ".*example\\.com.*"

Whitelist example: Allow access only to the When the user tries to access any other website they will be redirected to the provided redirect url

    "pattern": ".*example\\.com.*",
    "redirect": ""

Detecting a Surfly Session

You might want to change the behaviour of the website depending on whether it is a Surfly session or not. Example use cases are, for example, hiding a customized ‘session start’ button within the Surfly session, or to remove certain toolbars for a more aesthetic integration.

From within Javascript:

To detect a Surfly session from the client side, you can simply check for the existence of a global variable called __surfly

For example, to hide a button within a Surfly session, you could implement the following:

if (window.__surfly) {
    document.getElementById('session_start_button').display = "none";

At the backend:

As all Surfly sessions will originate from our proxy servers, this could be used as a way to identify whether the request comes from Surfly or a client directly. However, we use different IP ranges for our proxy servers, and they also change over time, so we recommend a different way to do this.

On each session that comes through our proxy, we will add an ‘X-Forwarded-For’ header that points to the original IP of the ‘leader’.

When creating a request, you can also set the ‘headers’ option (in both the Javascript call and the REST call) to add additional headers. These headers can be used to, for example, add an “Authorization” header to allow to user to be logged in on your own backend or a custom header which can be used as an identifier. We will send these headers with each request made during the session.

Queue Behaviour Customization

Surfly comes with a relatively straightforward dashboard. We not only allow you to enrich the information presented on this dashboard but you can also completely build your own dashboard and integrate it in your own web application.

For example, if you have the widget added to a section of your web application where the user is required to be logged in, you probably have some knowledge about the user which might be useful to pass along to the agent. Information such as the user’s name, email or even their phonenumber.

To make sure that this information becomes available in the dashboard you can set userData to an object that provides these values as key, value pairs. For example:

    "name": "John Doe",
    "email": "",
    "phone": "+123123123123"

You can then pass this variable to the SurflySession.startLeader() function:

Surfly.session().startLeader(null, userData);

Of these key,value pairs, name and email will also be provided to the Surfly session so that the session can display the name of the user in the chatbox and make sure that the accompanying gravatar matches his email address.

Tracking queue status

You can also provide a Javascript function in the QUEUE_CALLBACK option to trace the status of the queue on the client side. We will call this function every time a user is being queue’d, rejoins, or leaves the queue.

It will be called with two arguments:

  • status (true or false)

    • true (on successful join or rejoin)
    • false (after cancel, close)
  • session - a JSON Response object describing the session (this is received from QUEUE_HANDLER or QUEUE_ENDPOINT)

Generated by aglio on 24 May 2018