Web Widget Options

Configuration options can be changed in the Advanced Config Editor of the Web Widget integration in Web1on1, or via the initilaziation call of the widget as exampled here

The following options are available:

Suported Languages

The widget supported languages are nl, fr, de, en or pt. If no language is configured, it will use English (en).


Set language hard (do not look at browser language) to one of our supported languages.

    "language": "fr",


if set to one of our supported languages, set widget language to the browser language if it is one of our supported languages. If the browsers language is not supported, us this fallbackLanguage.

    "fallbackLanguage": "fr",


If set to true, will try to get language from the website url.

For example: https://site.com/nl/bla/ would match nl and set the language to nl. if nl is in the list of supported languages.

    "languageFromUrl": true,


All strings can be adjusted via the customText node. There are so many of them that there is a whole chapter on them.

    "customText": { "headerText": "Open me for help" },

would change the headerText for all languages


Per supported language you can overrule text.

    "customText": { "pt": { "headerText": "Olá, abra-me para ajuda" } },

would change the headerText for Portugues.


customColors can be used to change the default colors brandColor, conversationColor and actionColor

    "customColors": {
        "brandColor": "65758e",
        "conversationColor": "0099ff",
        "actionColor": "0099ff",

All values Must be a 3 or 6-character hexadecimal color.


This json structure can be used to add some css to the customers website and is used to adjust the widget position and size to the pixel or changing the shoutout (the chat bubble above the widget when closed) colors. The json object is transformed into css and injected into the main document of the website, For example, to change the shoutout colors, you could do this:

"style": {
    "body": {
        "#web-messenger-shoutout": {
            "border":"1px solid #C3002F"

the comma at the end is for copy and paste convenience.

Or changing css for a certain media query:

"style": {
    "body": {
        "@media (max-width: 1200px)": {
            "#web-messenger-shoutout.smooch_button": {
                "z-index": "1000",


This json object is transformed to css injected in the widget's iframe. It can be used to adjust any css within the widget If you would like to remove the header (with the company info) completely from the widget, you could use this style.frame setup:

    "style": {
        "frame": {
            ".intro-pane": {
                "display" "none"

You can find which css element you need with the inspector mode of chrome or firefox, etc.

    "style": {
        "frame": {
            "url": "https://yourdomain.com/styles/widgetframe.css"

You can even combine both examples above...


If set to true, removes the text '....is my code, I want to continue my conversation on WhatsApp' from wa and facebook connect page.

    "patchChannels": true,


Text to appear in carousel card after clicking it to. This will profide some feedback that you have clicked it already to prevent poeple clicking it many times.

    "cardClickText": "you choice",


Company url of organization in Web1on1| Used as image in header + everywhere agentImageUrl is used but missing. If left untouched it will use the url of the icon configured in the organization.

    "companyImageUrl": "https://some.domain/some/image.png",


Change/Set the disclaimer text shown at the bottom of the widget. Set to an empty string "" to disable (defaults to the text disclaimer)

    "disclaimerText": "our disclaimer",


Change the link behind the disclaimer text.

    "disclaimerUrl": "https://some.domain/some/webpage.html",


Change Messaging by Web1on1 at bottom of Chat Window.

    "poweredByText": "Magic Messaging",


Change the link behind the poweredByText text.

    "poweredByUrl": "https://some.domain/some/webpage.html",


Change image of button. Should be a http link to a jpg/png or svg.

    "buttonImage": "https://some.domain/some/image.png",


When the displayStyle is button, you have the option of specifying the button width.

    "buttonWidth": 150,


When the displayStyle is button, you have the option of specifying the button height.

    "buttonHeight": 150,


Force width of the bar/tab

    "barWidth": 300,


Force height of the bar/tab

    "barHeight": 80,


Used to place the bar/button. bottom right, bottom left, top left and top right. defaults to bottom right

    "orientation": "bottom left",


When widget opens, it opens fullscreen.

    "fullscreen": true,


When a contact starts a conversation, the system can invite the contact to connect to other channels. Is not show by default.

    "showConnectNotification": false,

shoutout options:


Shoutout works on mobile (button) after openAfter has passed. On desktop if set to true, will open the shoutout immidiately and open the widget after openAfter has passed.

    "shoutout": true,


Shoutout text to use (overruling default text)

    "customText": { "shoutoutText": "Need help?" },


Shoutout agent icon can be set to "male smiling-number between 1 and 40" or "female smiling-number between 1 and 39"

    "shoutoutAgent": "female smiling-23",


The number that will appear in the shoutout. Defaults to 1.

    "shoutoutNumber": "2",


Shoutout circle number color

    "shoutoutCircleColor": "#efd",

theme (depricated, use style.body instead)

Shoutout close icon can be set by setting theme to dark or light

    "theme": "2",


Instead of having the normal header in the conversation window, you will see fake agents. they shift every minute to mimick activity

    "fakeAgents": true,


replaces the default shoutout

Url of the image that is used as eye catcher above the widget.

    "eyeCatcher": "https://some.domain/some/image.png",


offsetTop for the eyeCatcher

    "eyecatcherOffsetTop": "10",


offsetLeft for the eyeCatcher

    "eyecatcherOffsetLeft": "10",


animation to use (see [Animate CSS](https://daneden.github.io/animate.css/ for all available animations)) defaults to fadeIn.

    "eyecatcherAnimation": "fadeIn",

or just design the widget button yourself

You can also as a company choose to design a completely different look for the widget bar or button and just use hide and rehide and open the widget yourself by using the widget api like this: window.chatshipper.api.openWidget()

Other settings


The amount of minutes the cookies are stored on the client. After this time they will be removed and if a customer returns after that time, the widget will start a new session. Any previous conversation is lost. If in the new conversation the consumer again is asket for their phone nr or email, Web1on1 will recognise that it is the same consumer talking and will offer the Agent that is talking to to consumer to merge both conversations into one conversation. accepted values are 5, 15, 30, 60, 720, 1440 and 43200

    "cookieLivetime": 60,


Sometimes you want the widget to load a bit later to give the customers website time to load. https://developers.google.com/speed/pagespeed/insights will show that our widget loads a substantial amount of data. Altought we cannot prevent the data from being loaded and executed, we can postpone it a bit. This way insights is happy (and the customer) and the widget gets loaded a bit later. It might even give it more attention this way as the rest of the site is passive at the point.

    "initAfter": 5000,


Automatically open the widget after x seconds. setting to false will disable it. defaults to 15 seconds. This is used to give the widget extra attention.

    "openAfter": "5",


In button mode, the animation to show after the openAfter period. find all animations here

    "openAfterAnimation": "bounceInDown",


When this text is configured (in any language as explained here), when the widget auto opens after the configured seconds, we will insert this welkom text as an agent. This will give the impression the agent is there already.

    "customText": { "agentWelkomMessage": "Hi there, how can we help?" },


Name of the agent to use when sending the welcome message after auto opening the widget

    "agentName": "john",


Used this agent icon http url for all Agents messages. If not configured the Web1on1 system will provide a icon.

    "agentImageUrl": "https://some.domain/some/john.png",


Disable sending Widget Errors to our Error reporting system.

    "disableErrorHandling": true

touchpoints (depricated, use desktop.hide or mobile.hide or tablet.hide instead)

Where will the bundle be active (['web', 'mobile', 'tablet']), defaults to all platforms.

    "touchpoints": ['mobile']


Show connect notification bubble (not the header, but the bubble text after first message). defaults to false

    "showConnectNotification": true,


if set to true hides the widget until it is opened by clicking a button/div (see openByIds/openByClass)

    "hide": true,

or hide on mobile (also have a look here

    "mobile": { "hide": true },


if set to true, in combination with above hide setting rehides the widget when it is closed by the customer.

    "rehide": true,

spa (Single Page Applications)

if set to true, it will detect page changes in a different way and remerge and reapply the settings on a change.

    "spa": true,


By default this is not set and means the widget can run on any web site. (this is the save default). If you want to restrict where the widget can be loaded you can use originWhitelist.

    "originWhitelist": ["https://yourdomain.com", "https://yourotherdomain.com"],


Monkey patch all elements with the configured id's on the customers site so that when a consumer clicks on the element, the widget will open and a bot will be started immidiately. In the example below the element on the customers website that has the id buttonId, will be patched and when clicked, the widget will open, the message Loading the bot... will appear as the agent with the name Jorge and the botmock bot named welcomebot

  "openByIds": {
    "buttonId": {
      "data-chatshipper-bot": "welcomebot",
      "data-chatshipper-agent-text": "Loading the bot...",
      "data-chatshipper-agent-name": "Jorge",
      "data-chatshipper-preventdefault": "true"

The preventdefault can be used to stop any other click that might have been configured by the website builder to trigger.

This means that now, if the customer has any element in their website with the id buttonId, this will be trigggering the bot in the widget.

Example DOM elements could be:

<div id="buttonId">Start the bot</div> or <button id="buttonId">Start the bot</button>

You could also just open the widget on button click with this example:

  "openByIds": {
    "buttonId": {
      "data-chatshipper-agent-text": "Hi there, how can we help you...",
      "data-chatshipper-agent-name": "Jorge"

Example DOM elements could be:

<div id="buttonId">Chat with us!</div> or <button id="buttonId">Chat with us!</button>


Monkey patch all elements on the customers website that have a certain class attribute set on it (can be many many elements if you are not careful) so that when a consumer clicks on the element, the widget will open and a bot will be started immidiately.

In the example below the elements on the customers website that have the class startbot, will be patched and when clicked, the widget will open, the message Loading the bot... will appear as the agent with the name Jorge and the botmock bot named welcomebot

  "openByClass": {
    "startbot": {
      "data-chatshipper-bot": "welcomebot",
      "data-chatshipper-agent-text": "loading the bot...",
      "data-chatshipper-agent-name": "Jorge",
      "data-chatshipper-preventdefault": "true"

Example DOM elements could be:

<div class="action startbot other">Start the bot</div> or <button class="startbot great large">Start the bot</button>

Which whould you use?

openByClass or openByIds. Look at the customers website and inspect the element on their site that you want to patch. Does it have an id set on it? user openByIds, do you see a unique class on it? used openByClass. Otherwise ask the website builder to add an id on it and use openByIds. openByClass can be dangerous as every element on the site that has that class set will be patched, so use openByClass with care.


This string will be send to the contact as agent message immidiately after opening the widget and before starting the bot. It's like the data-chatshipper-agent-text mentioned above, but this time set separatly.

    "preBotText": "Lets start the bot for you, hold on...",

Overruling settings for mobile, tablet, desktop

You can set overrule any setting mentioned above for mobile or tablet by specifying the same setting under settings.mobile.<setting> or settings.tablet.<setting>

Example changing header text on mobile:

    "mobile": { "customText" : { "headerText": "hello mobile user, how can we help" } },

Example disabling the widget on mobile:

    "mobile": { "hide" : true },

Example changing from bar to button on mobile:

    "mobile": {
        "displayStyle": "button",
        "buttonWidth": "40px",
        "buttonHeight": "40px",
        "buttonImage": "https://icons-for-free.com/iconfiles/png/512/chat+icon-1320184411998302345.png",
        "style": {
            "frame": {
                "#messenger-button > img": {
                    "width": "40px",
                    "height": "40px"

Overruling settings for specific webpages of customer

You can overrule settings for a customer by defining an urls array setting with an url that can be a full or partial match (regexp) and all settings you wish to overrule for that page (or all pages that match the partial string or regexp)

Example config file with urls key to match specific customer url:

    "urls": [
            "url": "/cars/",
            "shoutout": true,
            "customText": {
                "shoutoutText": "Chat about cars with us"

Prechat Capture

Prechat Capture is explained here.


Consumer Satisfaction will make the widget show a webview to rate the conversation. This happens when there are messages in the conversation and the widget is manually closed by the customer. The csat settings look like this:

csat: {
    header: 'header text before icons', //
    title: 'webview name', // optional: defaults to Rating
    type: 'font awsome icon to use for rating', // optional: defaults to fa-star, see all icons
    remarkheader: 'text before textinput', // if set, text input is activated
    sendbutton: 'text on send button' // defaults to 'Send'

example of settings



You can active CSAT by only setting the header: CSAT


  • setting header is enought to enable the rating (it will be submitted immidately on click on the dating)
  • setting remarkheader enables the remark input field and send button.
  • type can be used to use any font awesome font as rating icon
  • title can be used to change the webview title
  • sendbutton can be used to change the send button text