🌐

Botco.ai Webchat Customizations (Mounting Client)

Created
Feb 17, 2022 2:24 AM
Created by
Jacob Molina
Status
Not started
⛔

This is now handled by the Preview Page, Widget Configuration which will generate the snippet automatically. This is only here for reference

🔥
Do not use Google Tag Manager to load as chatbot will not appear for many clients depending on browser settings

Welcome to our Botco Webchat integration guide. In this document, you'll find comprehensive instructions to help you seamlessly integrate and optimize the Botco Webchat client on your website. We continuously strive to enhance your experience with our chat solutions, and with our latest update, you now have the ability to control various chatbot behaviors directly through URL parameters.

Testing Your Implementations

Before rolling out any changes to your live environment, we strongly recommend testing different configurations on our preview page. This allows you to observe how new settings affect chatbot behavior and user interaction without impacting your active user base. Testing on the preview page ensures that you fully understand the impact of each parameter, helping you make informed decisions about deploying these features on your production website.

How To Test In Preview Page

By appending disableKeyboard=true or any other parameter (except the Co-Pilot parameter) to your chatbot’s URL, you can streamline interactions on pages where keyboard input is unnecessary, enhancing user engagement and preventing unnecessary distractions. This feature is particularly useful in scenarios where chat interactions are designed to be more controlled or guided.

💡
For example: https://widget.botco.ai/dev/latest/index.html?apiKey=botco_api_PPbcsT49XpPKLjALxpYID_11494&disableKeyboard=true Just make sure to “&” in front of the parameter in URL for it to read it properly.

After mounting the BotCo Webchat agent onto your webpage, you can control its behavior for things like opening the bot to a particular block.

Mounting the chatbot

During the deployment process, you will see a code snippet that you can copy and paste into your website. It will look similar to

// Botco Installation
// This loads BotcoWebchat on the website
<script src="<https://widget.botco.ai/prod/VERSION/widget.js>" />

// Note: this installs the icon on the bottom right of your screen
<script>
  BotcoWebchat.mount({
    apiKey: 'YOUR_KEY'
  });
</script>

There are a few variations to the above code depending on your use case...

// Botco Installation
<script src="<https://widget.botco.ai/prod/VERSION/widget.js>" />

// Note: this installs the Botco code but does not display the icon
<script>
  BotcoWebchat.mount({
    apiKey: 'YOUR_KEY',
    open: false
  });
</script>

or...

// Botco Installation
<script src="<https://widget.botco.ai/prod/VERSION/widget.js>" />

// Note: this installs but will open to the block indicated by referral code
<script>
  BotcoWebchat.mount({
    apiKey: 'YOUR_KEY',
    referralCode: "REFERRAL_CODE"
  });
</script>

The mount command will display the icon for the chatbot at the bottom of your website.

Note: This step is required before any other step can be performed.

The unmount command will remove the icon from the website.

Opening the chatbot

Note: The close action requires small amount of work but can be added

You can programmatically open and close the chatbot based on events in your webpage. 

// Botco Installation Code
<script src="https://widget.botco.ai/prod/latest/widget.js" />

// Opens the chatbot window
<script>
  BotcoWebchat.open();
</script>


Example:

<script src="https://widget.botco.ai/prod/latest/widget.js"></script>
<script>
 BotcoWebchat.mount({
  apiKey: 'botco_api_tMlG8IE8q5ANjEi7RRelo_16719',
  open: true
 });
</script>

Or:

<script>
 BotcoWebchat.mount({
  apiKey: 'botco_api_tMlG8IE8q5ANjEi7RRelo_16719',
  open: "desktop"
 });
</script>

Or:

<script>
 BotcoWebchat.mount({
  apiKey: 'botco_api_tMlG8IE8q5ANjEi7RRelo_16719',
  open: "mobile"
 });
</script>

The open command will open the chatbot as if someone had clicked on its icon.

On the open property you can specify the “Device Type: mobile, desktop” you want your chatbot to be open on, in case you just want the chatbot to be open on “desktop” or “mobile”

The close command will close the chatbot but leave the icon on the website.

Opening chatbot with image

If you have an image on your website that you want to use to open the chatbot instead of our icon.

First add an image to your website with an HTML id (for example image ), then modify your snippet to the following..

// Botco Installation Code
<script src="https://widget.botco.ai/prod/latest/widget.js" />

// Example with jQuery, button clicked
<script>
$("#image").click(() => {
  BotcoWebchat.mount({
    apiKey: 'YOUR_KEY'
  });
});
</script>

Opening chatbot with a delay

If you want to open on your website but not immediately

// Botco Installation Code
<script src="https://widget.botco.ai/prod/latest/widget.js" />

// delay loading
<script>
setTimeout(() => {
  BotcoWebchat.mount({
    apiKey: 'YOUR_KEY'
  });
}, 5000); // 5000 milliseconds = 5 seconds
</script>

Closing icon permanently when clicking “x”

// Botco Installation
<script src="https://widget.botco.ai/prod/latest/widget.js" />


// Note: minimize chatbot will remove the icon as well
<script>
  BotcoWebchat.mount({
    apiKey: 'YOUR_KEY',
    closeOnClick: true // add this option
  });
</script>

Copilot widget

ticket: 

// Botco Installation
<script src="https://widget.botco.ai/prod/latest/widget.js"></script>
<script>

// Note: this installs the Botco code but does not display the icon
<script>
  BotcoWebchat.mount({
    apiKey: 'YOUR_KEY',
    copilot: {
      enabled: true,
      cta: 'Ask CoPilot', // Carlton CoPilot, Ask Ana, etc...
      questions: [ // Customers can add whatever they want
        "What are your locations?",
        "What is your pricing?",
        "What is your refund policy?",
        "What are your hours of operation?",
      ],
    }
  });
</script>
‣

Pulse Animation

The color of the pulse animation reflect the one picked for the header when deploying the chatbot.

BotcoWebchat.mount({
	apiKey:"botco_api_key",
	pulseAnimation: true, // Add this prop
});

you can also config for how long the pulse animation run

BotcoWebchat.mount({
	apiKey:"botco_api_key",
	pulseAnimation: {
		enabled: true,
		maxPulseSeconds: 10, <- means after 10 seconds the puls animation will stop
	}
});

Change Close Chat Icon

By default the chatbot shows a arrow down as the default for closing the chat window, you can change that to a cross (”X”):

BotcoWebchat.mount({
	apiKey:"botco_api_key",
	closeChatIcon: "cross"
});

Full Screen Chatbot

Used to make the chatbot take the fullScreen available.

// Botco Installation
<script src="https://widget.botco.ai/prod/latest/widget.js" />


// Note: minimize chatbot will remove the icon as well
<script>
  BotcoWebchat.mount({
    apiKey: 'YOUR_KEY',
    fullScreen: true // add this option
  });
</script>

Widget transparency

Used to make the chatbot window transparent, the value are between 1 (no transparent) and 0 (completely transparent)

<script src="https://widget.botco.ai/prod/latest/widget.js" />

<script>
  BotcoWebchat.mount({
    apiKey: 'YOUR_KEY',
    chatWindowOpacity: 0.6 // add this option
  });
</script>

Customizable font sizes

We have the following two properties to specify the font size inside the chatbot, both accepts a string value that represents the CSS font size property. If not provided, the default font size set by the chat interface will be used.

  • fontSize: This setting controls the size of the text within the widget.
  • carouselButtonFontSize: This setting controls the size of the text on the buttons within a carousel.
<script src="<https://widget.botco.ai/prod/latest/widget.js>" />
<script>
  BotcoWebchat.mount({
		apiKey:"botco_api_key",

		fontSize: "16px",
		carouselButtonFontSize:"2rem"
	});
</script>

Change the size of the Image of the chatbot

to change the image dimensions you'll have to pass in the mount the attributes height and width , if you don't pass any attribute the image will display as always with the default attributes:

<script src="<https://widget.botco.ai/prod/latest/widget.js>" />
<script>
  BotcoWebchat.mount({
		apiKey:"botco_api_key",
		height:"90px",
		width:"90px"
	});
</script>

Dimensions (Width & Height):

<script src="<https://widget.botco.ai/prod/latest/widget.js>" />
<script>
  BotcoWebchat.mount({
    apiKey: 'YOUR_KEY',
		height: '700px', // any valid css for height allowed
    width: '30rem' // up to customer to make sure this works on their website
  });
</script>

Positioning Properties & Z-Index:

  1. rightOffset: to set the horizontal position.
  2. bottomOffset: to set the vertical position
  3. zIndex: is used to set the vertical stacking order of elements in a page. Elements with higher zIndex values are stacked above elements with lower values. Numbers define the stacking order. Elements with higher z-index values will appear visually in front of elements with lower z-index values.
  4. relativeElement : CSS selector () for a relative element element to position the chatbot to, e.g: cookie banner
<script src="<https://widget.botco.ai/prod/latest/widget.js>" />
<script>
  BotcoWebchat.mount({
    apiKey: 'YOUR_KEY',
	  // the string can be any CSS selector( id: #yourId, class: .className, prop: div[data=""], ... )
		relativeElement: "#sliding-popup"
  });
</script>

Grouping:

These properties can be grouped together since they are commonly used in combination to achieve specific layout and layering effects on web pages. For example, you might use rightOffset: 0;, and bottomOffset: 0; to position an element in the bottom right corner. The zIndex property then helps control its layering if there are other positioned elements overlapping it.

BotcoWebchat.mount({
	apiKey:"botco_api_key", 
	rightOffset:"100px", 
	bottomOffset:"100px",
	zIndex: 999999
});

Save History

By default the chatbot save the history of the conversation if this isn't the desire behavior you can change it to false, using the saveHistory property:

BotcoWebchat.mount({
	apiKey:"botco_api_key", 
	saveHistory: false
});

Subscribing to events

Currently our chatbot dispatch events when:

  • BotcoWebchat.Events.Load: triggers when the chatbot load on the page
    • Note: BotcoWebchat will probably not be available BEFORE the script is loaded so you will need to use the text BOTCO:WIDGET_LOAD
    • Also this must be added BEFORE the script is loaded.
  • BotcoWebchat.Events.Open: triggers when the user click on the chatbot to start talking
  • BotcoWebchat.Events.Close: triggers when the user closes chat window
  • BotcoWebchat.Events.Goal: triggers when the user hit a goal card
  • BotcoWebchat.Events.UrlClick: triggers when the user click on button with an URL

So in order to subscribe to these events, just need to used the native browser api as below:

<script>
// Must happen before the load of the script or you will miss the load of the script event.
	document.addEventListener("BOTCO:WIDGET_LOAD", () => console.log("chatbot has been loaded"))
</script>


<script src="<https://widget.botco.ai/prod/latest/widget.js>" />

<script>
  BotcoWebchat.mount({ apiKey: 'YOUR_KEY' });
	
	document.addEventListener(BotcoWebchat.Events.Open, () => console.log("chatbot has been open"))
	document.addEventListener(BotcoWebchat.Events.Close, () => console.log("chatbot has been close"))

	/**
	* The event contains information of the goal that has been hit, in order to
	* see it you just need to access: `event.detail` and it will has a property
	* named `goal` that has the goal name
	*/
	document.addEventListener(BotcoWebchat.Events.Goal, (event) => {
		console.log(`user has hit goal ${event.detail.goal}`);
	})


	/**
	* The event contains information of the url that has been clicked, in order to
	* see it you just need to access: `event.detail` and it will has a property
	* named `url` that has the url name
	*/
	document.addEventListener(BotcoWebchat.Events.UrlClick, (event) => {
		console.log(`user clicked url: ${event.detail.url}`);
	})
</script>

Time based Chatbot opening

🔥
We have time based SET ATTRIBUTES in the chatbot so controlling the loading and not loading of chatbot in this manner is not recommended

Attributes at mount time

If the user is logged in or we have another way of getting attributes, passing them into the script will be set them in the chatbot

Anything in the attributes section will become an attribute.

These obviously need to be set up by customer since it’s their data they are passing in.

🔥
Note: This ^ means that if you pass in a literal value like “mike@email.com”, that will set the attribute ALWAYS to that exact email. It needs to be DYNAMICALLY added through code
// Botco Installation
// This loads BotcoWebchat script on the website
<script src="https://widget.botco.ai/prod/latest/widget.js" />

// This actually starts the widget on the website
// Attributes passed in to `attributes` key will be set and useable within the chatbot
<script>
  BotcoWebchat.mount({
    apiKey: 'YOUR_API_KEY', 
    attributes: {
        source: "CUSTOMER_STATIC_VALUE",
        userAccessToken: "<%= code_from_server_html >",
        userName: window.user.username,
				email: window.user.email,
        botTime: new Date(),
        ip: "Harder but possible perhaps better with IP/Physical Location Card"
    }
  });
</script>

See this page for more details….

GeoLocation Attributes

In order to collect the geolocation attributes (”_latitude” & “_longitude”) attributes the enableLocation flag needs to be add it. This will trigger a popup in the browser asking for the user permissions in order to collection the location info.

<script src="https://widget.botco.ai/prod/latest/widget.js"></script>
<script>
	BotcoWebchat.mount({
		apiKey: 'botco_api_key',
		enableLocation: true
	});
</script>

Hide the Close Button on mobile only

In order to hide the Close button on mobile devices only, the hideCloseButtonOnMobile flag has been added.

BotcoWebchat.mount({
	apiKey:"botco_api_key",
	hideCloseButtonOnMobile: true
});

Convert avatar + greeting and/or closing of widget to side flag

In order to turn a widget session to a side flag when closed, use closeToSide flag has been added.

BotcoWebchat.mount({
	apiKey:"botco_api_key",
	closeToSide: true
});

Chat with us post-minimizing chatbot

If the customer wants the chatbot widget to appear minimally after closing it, this option provides just that. DISCLAIMER: We don’t recommend it because engagement will drop significantly.

<script src="https://widget.botco.ai/prod/latest/widget.js"></script>
<script>
	BotcoWebchat.mount({
		apiKey: 'botco_api_key',
		closeToSide: true
	});
</script>

Keeping chatbot minimized throughout session

Once the greeting message is minimized once, when the user visits a new page, the chatbot greeting message won’t appear.

<script src="https://widget.botco.ai/prod/latest/widget.js"></script>
<script>
	BotcoWebchat.mount({
		apiKey: 'botco_api_key',
		keepGreetingMinimize: true
	});
</script>

Disabled Keyboard for all card types except questions

Disable the keyboard for all card/blocks received on the client and only enable it when answering a form question.

<script src="https://widget.botco.ai/prod/latest/widget.js"></script>
<script>
	BotcoWebchat.mount({
		apiKey: 'botco_api_key',
		disableKeyboard: true
	});
</script>

This is deprecated because these settings now exist on deployment screen.

🔥
However, if these exist, they will overwrite what is in the deployment screen

Different Greeting Message and Starting Block per URL

In order to use this feature, you must configure it using the "rules" property.

  • The value of each key is another object with properties:
    • key representing the URL matcher quoted
    • "referralCode", which must be a referral code configured in the deployment screen of the Authoring Tool
    • "greetingMessage", which is optional and overwrites the default greeting message.
BotcoWebchat.mount({
  apiKey: 'botco_api_my_api_id',
  rules: {
    '/index.html': {
      referralCode: 'TEST_REFERRAL',
      greetingMessage: 'HELLO THERE!'
    },
    '/contacts': {
      referralCode: 'CONTACTS_REFERAL_TESTS',
      greetingMessage: 'HELLO THERE CONTACT!'
    },
    '/blog/:id': {
      referralCode: 'BLOG_ID_REFERAL_TESTS',
      greetingMessage: 'HELLO THERE BLOG!'
    },
	    '/customer/*/details': {
      referralCode: 'BLOG_ID_REFERAL_TESTS',
      greetingMessage: 'HELLO THERE CUSTOMER!'
    }
  },
})

How it works with examples