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.

Remember

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

Group Reference Tables

Chat box

OptionDefaultDescription
chat_enabledtrueEnable text chat.
hide_session_uifalseHide the user interface, including the top bar, side bar, and notifications.
new_urls_allowedtrueAllow participants to open new tabs. If set to false, nobody in the session can open new tabs.
invitations_allowedtrueAllow participants to invite others to an ongoing session.
host_switching_allowedtrueEnable control switching functionality
pause_enabledfalseEnable session pause. Participants can pause their tabs from syncronization. Others will see the page paused and greyed out.

Screenshots

Options below set the default screenshots settings.

OptionDefaultDescription
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.

Video

OptionDefaultDescription
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.

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

OptionDefaultDescription
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.

Session recording

OptionDefaultDescription
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

OptionDefaultDescription
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

OptionDefaultDescription
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', 'nl', 'pl', 'pt', 'ro', 'ru', 'sr', 'sv', 'tr', 'vi', 'zh-hant'
support_button_position'bottomleft'Position of the support button on the page.

Control switching

OptionDefaultDescription
anyone_can_deactivate_spacefalseAllow terminating a session from the follower's end

Opening a new tab

OptionDefaultDescription
non_hosts_can_open_tabstrueAllow all participants to open tabs. If set to false, only the host is allowed to open tabs.

Developer console

OptionDefaultDescription
verbose_consoletrueShow more messages in browser console.

Session Appearance

OptionDefaultDescription
hide_cursorsfalseHide mouse cursors inside the Space.

Enterprise options

OptionDefaultDescription
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 JS API session ends, keep the session open. 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. ["example.com", "surfly.com"]. This option works together with soft_session_end.
localhost_requests_allowedfalseAllow pages to make requests to localhost (127.0.0.1).

More information on restrictions

Audit log options

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

OptionDefaultDescription
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"https://s3.amazonaws.com/"S3 endpoint URL (Note: all S3-compatible services are supported.)

Session start

OptionDefaultDescription
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_manglingfalseModify in-session URLs to protect users from being tracked by proxy servers and routers. See our documentation for more information.

Session invitations

OptionDefaultDescription
default_invitations_enabledtrueSend session invitations based on default Surfly templates. Custom invitations can be created using webhooks.

Content manipulation

OptionDefaultDescription
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

OptionDefaultDescription
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

OptionDefaultDescription
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

OptionDefaultDescription
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.)

Cookies

OptionDefaultDescription
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 or ending a Surfly session, sync cookies between the Surfly session and the original page opened in the browser.
cookie_transfer_scopesList of the cookie scopes that need to be transferred; see our documentation for more information.
cookie_transfer_proxyingtrueSync HTTP-only cookies between the Surfly session and the original page opened in the browser. This requires extra configuration; see our documentation for more information.
cookie_transfer_urlsList of session continuation points; see our documentation for more information

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": "example.com"},
{"name": "sessionid", "httponly": false, "path": "/", "domain": ".example.com"}
]

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

More information on session continuation

Session end

OptionDefaultDescription
follower_redirect_url""When a session ends, redirect some users to a custom URL. For temporary Spaces, followers who aren't logged in are redirected. For permanent Spaces, everyone except the owner of the Space is redirected.
leader_redirect_url""When a session ends, redirect some users to a custom URL. For temporary Spaces, the leader is redirected. For permanent Spaces, the owner of the Space is redirected.
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.
leader_connect_timeout2Set a timeout for a leader to join the session. From 2 up to 15 minutes

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:

'http://mysite.com/restricted?blocked_url=https%3A%2F%2Fexample.com'

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:

Surfly.session().end(redirect_url);

endSession function will trigger the following events:

Blocklist example:

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

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

Allowlist example:

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

{
"pattern": ".*example\\.com.*",
"redirect": "https://example.com/restricted"
}

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": "john.doe@example.com",
"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.