Skip to main content

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.


Changes to the code will take priority over changes to the options panel

Group Reference Tables

Chat box

chat_enabledtrueEnable text chat.

Pause functionality

pause_enabledfalseEnable session pause. Participants can pause their tabs from syncronization. Others will see the page paused and greyed out.


Options below set the default screenshots settings.

s3_screenshots_bucket""AWS S3 bucket name for screenshots
automatic_screenshots_enabledfalseEnable automatic screenshots. To use this functionality, please configure s3_screenshots_bucket, s3_access_key, and s3_access_secret appropriately
screenshot_image_size1920Width of the the screenshot. s3_screenshots_bucket is required to enable screenshots functionality.
screenshot_interval15Wait this many seconds between automatic screenshots. (Note: values lower than 15 may diminish the quality of the session.)
screenshots_on_annotationfalseTake a screenshot after each annotation or drawing. To use this functionality, please set drawing_enabled to true and configure s3_screenshots_bucket, s3_access_key, and s3_access_secret appropriately.
use_webrtc_for_screenshotsfalseUses WebRTC to make screenshots. Source of the screenshots is a session tab of the first Agent that joins. Agents are required to use Google Chrome.


videochattrueIs videochat allowed? Note that videochat functionality is disabled in browsers that don't support WebRTC, such as Internet Explorer and Chrome on iOS
start_with_videochat_onfalseStart the session with videochat on.
start_with_fullscreen_videochatfalseStart videochat in fullscreen mode.
videochat_prompttrueWhen this option is set to false and videochat is started inside a session, other participants will not be prompted to join the videochat. Instead, they will join automatically with disabled mic and camera.
video_archiving_enabledfalseEnable Vonage videochat recording.
p2p_videochat_enabledtrueUse peer-to-peer connections for videochat. If set to true, video_archiving_enabled will be disabled.
screensharing_enabledtrueAllow users to share desktop applications. Please enable videochat_enabled to use this feature.
anonymous_users_can_share_cameratrueWhen set to false, only authenticated users will have the capability to share their camera feed within video chats. Meanwhile, other users can still participate in the videochat but will be restricted to audio-only sharing.
default_videochat_fullscreen_mode'grid'Default videochat fullscreen mode. Can be either 'grid' or 'spotlight'.
default_videochat_mode'floating'Default videochat mode. Can be either 'floating' or 'sidebar'.

The Peer-to-peer (p2p) option connects all participants directly with one another. Thus, videochat recordings feature is not available when this option is enabled. With more than 5 videochat participants it is possible that video quality will decrease.

When this option is off, the Routing mode is used. It connects all participants by routing each participant through the server, which enables videochat recordings, and diminishes quality loss with large amount of videochat participants.

File sharing

filesharing_enabledtrueEnable file sharing.
original_file_download_allowedfalseAllow users to download shared files. If set to false, users can still view shared files but will not be able to download them.
document_editor_enabledtrueEnable editing in the document viewer interface.
document_viewermulti-formatSelect "pdf" for PDF file support or "multi-format" for extended document format compatibility.

Session recording

automated_session_recording_enabledfalseEnable session recording. Recordings will be stored in the S3-compatible bucket specified with s3_recordings_bucket using the credentials provided in s3_access_key and s3_access_secret.
s3_recordings_bucket""S3-like bucket name to upload the video files of recorded sessions. Requires s3 credentials: s3_access_key, s3_access_secret, s3_endpoint_url

Sounds and notifications

start_mutedfalseStart the session with muted microphones for all participants.
notifications_enabledtrueEnable in-session notifications.
sounds_enabledtrueEnable sound for in-session notifications.
notification_position"bottom-right"Position of in-session notifications on the screen.

Button appearance

hide_support_buttonfalseDo not show the default support button. This option is used in combination with shake_to_start or key_combo_to_start.
language'en'Language of the interface. Available languages are: 'cs', 'de', 'en', 'es', 'et', 'fi', 'fr', 'hi', 'it', 'ja', 'ka', 'ko', 'nb', 'nl', 'pl', 'pt', 'ro', 'ru', 'sr', 'sl', 'sv', 'tr', 'vi', 'zh-hant'
support_button_position'bottomleft'Position of the support button on the page.

Control switching

host_switching_allowedtrueEnable host switching functionality
participants_can_request_to_interacttrueEnable tab control switching functionality


new_urls_allowedtrueAllow participants to open new tabs. If set to false, nobody in the session can open new tabs.
non_hosts_can_open_tabstrueAllow all participants to open tabs. If set to false, only the host is allowed to open tabs.

Developer console

verbose_consoletrueShow more messages in browser console.


csp_report_uri""The URI of the CSP report endpoint.

Session Appearance

hide_cursorsfalseHide cursors and disable drawing for everyone but the in-control participant.
hide_session_uifalseHide the user interface, including the top bar, side bar, and notifications.

Enterprise options

white_labelfalseHide Surfly branding in the interface of the session.
blocklist"[]"Restrict access to the specific resources. Example: [{"pattern": ".*example\\.com.*"}]
allowlist"[]"Allow access only to the specific resources. Example: [{"pattern": ".*example\\.com.*"}]
soft_session_endfalseWhen a session ends, keep the session open for the active tab's owner. This is used with soft_end_filter.
soft_end_filter[]For Surfly sessions started with JS API that persist even after they end, specify which domains a user can access from within the completed session. Specify a JSON array, e.g. ["", ""]. This option works together with soft_session_end.
localhost_requests_allowedfalseAllow pages to make requests to localhost (

More information on restrictions

Audit log options

See our audit log documentation for more information about this functionality.

chat_logs_enabledfalseKeep a log of messages sent in the text chat during a session. (Note: text chat logs are stored in a .txt file.)
audit_logs_enabledfalseEnable session (audit) logs. Files are stored in the S3 compatible bucket. Permanent spaces will have one file per session. s3 access key and access secret must also be provided.
s3_access_key""S3 access key (Note: all S3-compatible services are supported.)
s3_access_secret""S3 secret access key (Note: all S3-compatible services are supported.)
s3_audit_log_bucket""AWS S3 bucket name for session logs
s3_endpoint_url""S3 endpoint URL. When setting up AWS S3, make sure to accurately specify the endpoint URL for the S3 API, ensuring it points to the region of the bucket. For example Please refer to the official AWS documentation here. (Note: all S3-compatible services are supported.)

Session start

session_autorestore_enabledtrueAutomatically try to restore sessions started with JS API on page reload.
hide_support_button_when_unavailabletrueHide the support button when no agent is available
block_until_agent_joinstrueWhen a session is started using JS API, show the session URL and PIN until another participant joins. (Note: this option does not affect permanent Spaces.)
chat_integration"disabled"Enable Surfly integrations within the selected 3rd-party chat solution.
session_start_confirmationfalseAsk users for their consent before starting a session using JS API.
format_session_idtrueUse a series of three three-digit numbers (e.g. 123-456-789) as a session ID for temporary Spaces. (Note: this option does not affect permanent Spaces.)
hide_until_agent_joinsfalseWhen a session is started using JS API, hide the session interface until another participant joins. (Note: this option does not affect permanent Spaces.)
language"en"Language of the interface
private_sessionfalseOnly followers who are logged in and belong to the company which initiated the session can join
password_requiredfalseRequire a password to join the session. The password can be found in the invite modal or in an invitation email.
admission_enabledfalsePrevent users from joining sessions until the host admits them. If set to false, users can join the session without admission. (Note: users can never join permanent Spaces without being admitted.)
region""Use servers in this region to start sessions. If no servers are available in this region, the session will start in the next closest region.
selected_regions"[]"Use servers in these regions to start sessions. If no servers are available in these region, the session will not start. If none are selected, the session will start in any available region. To de-select a region, click while holding Ctrl.
shake_to_startfalseAllow users to start a session on pages with the support button, by shaking their mobile device.
start_with_loading_screentrueShow a loading screen after a session is started.
start_with_invite_modaltrueWhen a session is started, show a modal that lets users invite participants to the session. Even if this option is false, sessions started from the dashboard will always show this modal. If block_until_agent_joins is set to true, sessions will never show this modal. The invite modal is always shown on outbound sessions, and never shown if block_until_agent_joins is enabled.
start_with_chat_openfalseStart sessions with the right sidebar open. (Note: the right sidebar contains text chat.)
key_combo_to_starttrueAllow users to start a session on pages with the support button by pressing Ctrl+Enter.
urlcurrent pageInitial URL that will be opened inside the session. Only available in REST API at the moment
url_manglingfalseGenerate unique in-session domains per session. This feature is typically used to enhance user privacy by generating unique cookie storage for each session on each domain, preventing user tracking.
alternative_proxy_enabledfalseRoute all session traffic through a specific forward proxy. The proxy uses volatile storage and mimicks the behavior of a real web browser to bypass bot protection measures. This experimental option may decrease performance and cause issues.

Session invitations

default_invitations_enabledtrueSend session invitations based on default Surfly templates. Custom invitations can be created using webhooks.
invitations_allowedtrueAllow participants to invite others to an ongoing session.

Content manipulation

native_selectstrueUse the browser's native implementation for <select> elements. If set to false, Surfly's own implementation will be used.
hide_element_by_selector""Hide elements matching this CSS selector from others. You can use ' *' to include all nested elements.

File downloads

download_trigger_enabledtrueWhen a user downloads a file in a Surfly session, offer to let others download the file. If set to false, downloaded files will not be available to other participants.

Canvas synchronisation

follower_drawing_selector""Allow participants to draw on a canvas element with this CSS selector. This is used for electronic signatures (e-sign). (Note: to use this feature, participant needs to have permission to control the tab.)

Browser native override

native_dialogs_enabledfalseEnable native dialogs—such as alert, confirm and prompt—during the session. (Note: unless a user dismisses these dialogues, sessions in temporary Spaces will automatically end after a period of time.)


embedded_sessions_onlyfalseWhen a user has 3rd-party cookies disabled in their browser, forbid them from starting a session using JS API. If set to false, sessions will open in a separate tab when 3rd-party cookies are disabled. (Note: this option does not affect permanent Spaces.)
cookie_transfer_enabledtrueWhen starting a Surfly session, transfer cookies (does not include httponly cookies), local storage, session storage and form fields from the original page opened in the browser into the Surfly session. When the Surfly session is ended everything (js cookies, local storage and session storage (except form fields)) is transferred back to the original webpage.
cookie_transfer_proxyingtrueWhen starting a Surfly session, transfer httponly cookies between the Surfly session and the original page opened in the browser. This requires extra configuration; see our session-continuation guide for more information.
cookie_transfer_scopesList of the cookie scopes that need to be transferred; see our session-continuation guide for more information.
cookie_transfer_urlsList of session continuation points; see our session-continuation guide for more information
enable_cookie_backtransferfalseTransfer session cookies (including httponly cookies) back from the Surfly session to the original webpage. Enabling this option takes effect only when session-continuation is already set up and also requires to run Surfly from a domain that is same-site with the domain of the cookies intended to be transferred back. Check this article for more information on how to run Surfly from your own domain

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


Privacy options allow to hide information which is exposed on a client side, i.e. by a browser.

privacy_user_agentfalseMask data about the user's browser located in the Navigator object. This helps to protect against some malicious websites which abuse this feature to track users.
privacy_canvasfalsePrevent sites from reading the result of canvas drawing operations. This helps to protect against some malicious websites which identify users by drawing shapes and text on a user's webpage and noting the minor differences in the way they are rendered. Note: this can cause problems on sites which use Canvas elements legitimately.
privacy_datefalsePrevent sites from checking the local time on the user's computer or phone. This helps to protect against some malicious websites which abuse this information to uniquely identify users. Note: this can cause problems on sites which use Date legitimately.
privacy_devicesfalsePrevent sites from reading detailed information about a client's devices, such as CPUs, memory, displays, battery and others. This helps to protect against some malicious websites which abuse this information to uniquely identify users.
privacy_embedfalseWhen this option is enabled, the "type" attribute of any of these elements will be changed to "text/surfly-blocked" if it is "application/x-shockwave-flash" or starts with "application/java-" or "application/x-java-". Additionally, the following attributes will be reset:
<object>"code", "codebase", "data"
<applet>"archive", "code"
privacy_ip_addressfalseHide a user's public ip address. This helps preserve user anonymity. If set to true, then the surfly-forwarded HTTP header is not added to requests, and WebRTC is disabled. Note: this can cause problems on sites which use WebRTC legitimately, like videochat applications.
privacy_beaconfalsePrevents sendBeacon POST request from being sent. This helps to protect against some malicious websites which abuse this feature to track users. Note: this can cause problems on sites which use this feature legitimately.
privacy_http_headersfalseWhen this option is enabled, the following headers will be set to a generic value:
  • Accept
  • Accept-Encoding
  • Accept-Language
  • User-Agent
  • Sec-CH-UA-*
The following headers will be sent unchanged:
  • Host
  • Content-Length
  • Cookie
  • Referer
  • Origin
  • Content-Type
  • Cache-Control
  • Range
Finally, any other headers will be removed from the request.

Session end

follower_redirect_url""When a session ends, redirect followers, who are not logged in to a custom URL.
leader_redirect_url""When a session ends, redirect leaders to a custom URL.
end_of_session_popup_url""URL of the page that will open in a popup window after the session ends.
end_redirect_enabledtrueEnable automatic redirects for sessions started with JS API.
anyone_can_deactivate_spacefalseAllow terminating a session from the follower's end

Group Option details

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

Blocklist and Allowlist 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 - A url to redirect the user to. You can also specify the special {{referer}} pattern in the beginning of a redirect link, and that will be replaced by the Referer value at the moment of redirect. 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

Blocklist 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.*"

Allowlist 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 'surfly-forwarded' 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.