Developer ForumDeveloper BlogAtlas
Guides

Web Widget

Suggest Edits

Flow provides an easy-to-use web widget that can be placed on a website. This allows visitors to the website to directly chat with a chatbot or human agent.

Capabilities

The web widget supports a wide variety of reply actions as seen in the messaging capabilities grid. Below is a detailed view of each capability.

Text

Web widget displays any plain text messages.

Text docs - JS template docs

Emojis
Web widget displays any unicode emoji sent in text messages. Mobile users can use the emoji keyboard on their device to send them.

Emojis docs - JS template docs

Image

Web widget displays static images.

Image docs - JS template docs

File

Web widget displays files and allows users to download them.

File docs - JS template docs

Video

Web widget displays videos and allows users to play them.

Video docs - JS template docs

Audio

Web widget provides audios and allows users to play them.

Audio docs - JS template docs

Location

Web widget displays Google Maps link of the location. Location messages include longitude and latitude coordinates.

Location docs - JS template docs

Card

Web widget displays cards. Cards must include title and optionally can include subtitle, media, action and buttons.

Card docs - JS template docs

Carousel

Web widget displays carousels that contain cards.

Carousel docs - JS template docs

List

Web widget displays lists that contain cards.

List docs - JS template docs

Buttons

Web widget displays buttons.

Buttons docs - JS template docs

Quick replies

Web widget displays quick replies. They are ideal for yes / no type of questions.

Quick replies docs - JS template docs

Configuration

To get started, first add a Web widget integration to your project

  1. Choose the project to which you would like to connect WhatsApp using the top left drop-down menu:
  1. Go to the “Integrations” section and press the “+” sign:
  1. Select the Web widget integration
  2. Copy and paste the embed code within the HTML of your web page.

Here is a simple example showing the embed code:

<html>
    <head>
    </head>
    <body>
        <script src="https://widget.flow.ai/w/[your token]==/flow-webclient-1.1.2.min.js"></script>
    </body>
</html>

Customization

There are various customization options for the web widget that can be applied within the dashboard settings

Language

Specify the language of the web widget. This will update button labels etc to the specific language.

Opening message

The message displayed in the center when opening the chat widget

Tint color

Specify the color used for the background of the header and button

Widget position

Adjust the location on the screen where the button will be displayed

Button type

Choose the type of button to use. The default is a message balloon icon colored by the tint color.

You can also change the button appearance by uploading a custom image. This must be a square image with a 256x256 pixel resolution.

Disable upload button

This option allows you to prevent users to upload and send any files using the upload functionality.

Header

Change the default title and description that are shown in the header section of the widget

Avatar

By default we show a bot avatar for each message sent by the chatbot. You can disable this entirely or upload a custom avatar image. Make sure the image is square. Preferred size is 228x228 pixels.

Character limits

Users are limited by 140 characters for a message intentionally There is an option to disable this behavior and allow text of any length to be send.

📘

Note

Note: Having a 140 character limit makes it impossible for users to copy and paste long texts like the content of an e-mail.

Client nonce

This security setting is turned on by default and reduces the risk of another party trying to send messages by using just a threadId.

We recommend leaving it on for client side connections. If you make use of the flowai-js SDK we'll store and track the client nonce automatically. If you just connect using the Socket API you'll need to make sure you store and send the nonce with each HTTP request.

📘

Note

This setting prevents sharing a threadId between clients. For use cases where this is required, we you can disable this setting.

Embed settings

There are additional settings and functionality you can use to customize how the web widget behaves on your website.

Pro-active messages

You can configure a pro-active message to be displayed using the dashboard settings. If you want more control you can also do this using the following on-page settings:

<script type="text/javascript">
var userName = "Jane";
__flowai_webclient_proActive = {
  message: "Hi " + userName + ". Let me know if I can help",
  delay: 10,
  autoHide: 0
}
</script>
<script src="https://widget.flow.ai/w/[your token]..."></script>

Trigger event

Automatically triggering an event is especially useful for showing a welcome message or pushing a dialog into a specific flow when a user opens the web widget.

An event can be triggered by adding a global javascript variable called __flowai_webclient_autoTriggerEvent. The following example will automatically trigger the event SHOW_WELCOME whenever a user opens the web widget for the first time.

Example

<script type="text/javascript">
window.__flowai_webclient_autoTriggerEvent = 'SHOW_WELCOME';
</script>
<script src="https://widget.flow.ai/w/[your token]..."></script>

📘

Note

Opening events are not considered as a new session. Read how we measure sessions.

Security settings

Khoros Flow has improved the security mechanism for the web widgets by incorporating Socket Security Layer (SSL). SSL helps to validate the one-time token for the customer web requests.

For a secured channel, you need to enable Secure Token validation for the session. Without a valid Token, a session is not established or communication will go not through the secured channel. Configure the Secure Token validation Webhook for the channel, validate and enforce HTTPS protocol to establish the session.

Enable Web Widget Security

  • You need a backend environment to validate One-Time Token (OTT) requests.
  • Update the widget code to generate the OTT and embed the code on the client-side before the widget gets uploaded.

Example

//Generate and set up a One-Time Token
    window.__flowai_ott = "3587acb9aba75972b8f9280c2187e037d27e99e17a6c6cd27b15c7a45496d91c"
    const widget = document.createElement('script')
    widget.src="https://flow.dev.aws.lcloud.com/channel-webclient/w/YTl2WTYyeDVPfGNFNk4xMzlwUA==/flow-webclient-1.1...."
    document.body.append(widget)

Follow the below steps to enable the security settings for the Flow:

  1. In a Flow, click Integration from the left panel.
  2. Click + to integrate the web widget.
  3. Click the Customize tab.
  4. Select the applicable options for the session security.
  5. Enter the webhook URL in the Secure Token Validation field for token verification.
  6. Enter the generated token in the Authorization token for validating the OTT field.
  7. Click SOFT MODE.

📘

Note

If you enable SOFT MODE, the validated result is accessible via isAuthenticated param. You can provide access to secure flows only. The session will be established even though the token is unauthorized.

  1. Click Save.

Test the Flow Design

You can test the secured session status using the Flow condition trigger.

Attach widget to specific HTML element

You can attach the widget to some specific HTML element on your page by setting __flowai_webclient_embed to your_element_id. This allows you to run the widget full screen or embedded within an element on your page.

Example

<div id="my-div"></div>
<script type="text/javascript">
window.__flowai_webclient_embed = 'my-div';
</script>
<script src="https://widget.flow.ai/w/[your token]..."></script>

Auto send message

This works pretty similar like the triggering of an event. The big difference is that a message would be send as if the user did it him or herself.

Example

<script type="text/javascript">
window.__flowai_webclient_autoMessage = '3 pizza hawaii please';
</script>
<script src="https://widget.flow.ai/w/[your token]..."></script>

Auto open

Automatically open the web widget when it's loaded on the page by setting __flowai_webclient_autoOpen to true.

Example

<script type="text/javascript">
window.__flowai_webclient_autoOpen = true;
</script>
<script src="https://widget.flow.ai/w/[your token]..."></script>

Alternative button

We have an option you can use a custom button in HTML to open or close the web widget. Provide a query selector that matches the button you want to use to toggle the widget.

Example

<script type="text/javascript">
window.__flowai_webclient_triggerSelector = '#alternativeButton';
</script>
<a href="#" id="alternativeButton">Click me!</a>
<script src="https://widget.flow.ai/w/[your token]..."></script>

The example above shows a HTML <a/> link with an id attribute alternativeButton. The corresponding query selector is #alternativeButton. You can specify any valid selector with the window.__flowai_webclient_triggerSelector option.

Hide default button

You can hide the default button by setting the __flowai_webclient_hideButton to true.

Example

<script type="text/javascript">
window.__flowai_webclient_hideButton = true;
</script>

Hide download button

You can hide the download button by setting the __flowai_webclient_hideDownloadButton to true.

Example

<script type="text/javascript">
window.__flowai_webclient_hideDownloadButton = true;
</script>

Hide header close button

You can hide the header close button by setting the __flowai_webclient_hideHeaderCloseButton to true (works only after hiding default button).

Example

<script type="text/javascript">
window.__flowai_webclient_hideHeaderCloseButton = true;
</script>

Hide header

You can hide the header itself by setting the __flowai_webclient_hideHeader to true.

Example

<script type="text/javascript">
window.__flowai_webclient_hideHeader = true;
</script>

Hide opening message

You can hide the opening message by setting the __flowai_webclient_hideOpening to true.

Example

<script type="text/javascript">
window.__flowai_webclient_hideOpening = true;
</script>

Custom font

It’s possible to use a custom web font within the web widget. We support Google Fonts, Adobe Fonts (Typekit) and custom hosted fonts.

Example of using a Google font:

<script type="text/javascript">
 window.__flowai_webclient_font = {
   family: 'Crimson Pro',
   url: 'https://fonts.googleapis.com/css2?family=Crimson+Pro'
 }
 </script>
 <script src="https://widget.flow.ai/w/[your token]..."></script>

You can also use your own hosted web font but providing an absolute URL to a CSS file.

Example Using a Custom hosted web font:

<script type="text/javascript">
 window.__flowai_webclient_font = {
   family: 'Gilroy-Regular',
   url: 'https://flow.ai/assets/fonts/widget.css'
 }
 </script>
 <script src="https://widget.flow.ai/w/[your token]..."></script>

Example of the loaded CSS file

@font-face {
 font-family: 'Gilroy-Regular';
 src: url("https://flow.ai/assets/fonts/31BF8D_6_0.eot");
 src: url("https://flow.ai/assets/fonts/31BF8D_6_0.eot?#iefix") format("embedded-opentype"), url("https://flow.ai/assets/fonts/31BF8D_6_0.woff2") format("woff2"), url("https://flow.ai/assets/fonts/31BF8D_6_0.woff") format("woff"), url("https://flow.ai/assets/fonts/31BF8D_6_0.ttf") format("truetype")
 }

Session storage

By default the widget stores messages accross browser sessions. By setting __flowai_webclient_storage to session you can change this behavior. When set to session all messages are removed when a user closes the web browser.

Example

<script type="text/javascript">
window.__flowai_webclient_storage = 'session';
</script>
<script src="https://widget.flow.ai/w/[your token]..."></script>

Sending params

The Flow.ai contextual AI engine will find and use entities within flows. Sometimes you might already have certain information available inside the front end the AI could use. You can send this data by setting __flowai_webclient_params.

The format of the params is identical to the way you receive data within cloud code or a webhook.

Example

<script type="text/javascript">
window.__flowai_webclient_params = {
  departure_city: [{
    value: 'Amsterdam'
  }],
  destination_city: [{
    value: 'NYC'
  }]
}
</script>
<script src="https://widget.flow.ai/w/[your token]..."></script>

Custom originator

We call the sender of a message the originator.

By default anyone using the web widget has an anonymous originator. You can however send information that allows you to identify a user. This is useful if you are using the web widget in a secure environment where you have identified the user.

Example

<script type="text/javascript">
window.__flowai_webclient_originator = {
  name: "Jane",
  profile: {
    fullName: 'Jane Doe',
    picture: 'https://my-user-images.com/jane.png',
    email: '[email protected]'
  },
  metadata: {
    userName: 'janedoe21',
    userRole: 'admin'
  }
}
</script>
<script src="https://widget.flow.ai/w/Aasdasdada132424234..."></script>

Event handlers

We provide a __flowai_webclient_events.addListener method to add custom event handlers.

The events that are triggered are similar to the Flow.ai JavaScript SDK.

Reply messages

Whenever Flow.ai sends a reply to the web widget you can subscribe to handle these reply messages.

<script type="text/javascript">
__flowai_webclient_events.addListener('received', function(reply){
  // Called when a reply is received
  // Do anything with the reply
})
</script>
<script src="https://widget.flow.ai/w/[your token]..."></script>

Sent messages

You can also subscribe to messages that are send by the user. Whenever Flow.ai has received the message it will trigger a delivered handler.

<script type="text/javascript">
__flowai_webclient_events.addListener('send', function(message){
  // Called when a message was sent
})

__flowai_webclient_events.addListener('delivered', function(message){
  // Called when a message was delivered
})
</script>
<script src="https://widget.flow.ai/w/[your token]..."></script>

Other events

__flowai_webclient_events.addListener('error', function(err){
  // Called on error events
})

__flowai_webclient_events.addListener('connected', function(){
  // Handle connected event
})

__flowai_webclient_events.addListener('reconnecting', function(){
  // Handle reconnecting event
})

__flowai_webclient_events.addListener('disconnected', function(){
  // Handle disconnected event
})

Other

Fullscreen mode

Flow.ai allows you to open web widget in a fullscreen mode. Simply add fullscreen=true to your web widget's query parameters. For example

https://widget.flow.ai/try/Y2IwOGE4OGItOGU2My00MGE0LTkyMDAtYmM1N2Y0ZWIzMzcxfDVmMmZhNDk2LWNjMDQtNDA4Ni04YTA2LWY3MDcxMzYxMzMzYQ==?fullscreen=true

Non-rounded bot avatar

Flow.ai allows you to remove rounding from bots avatar. Simply add nonRounded=true as a query parameter to the URL of your web widget.

For example:

https://widget.flow.ai/try/Y2IwOGE4OGItOGU2My00MGE0LTkyMDAtYmM1N2Y0ZWIzMzcxfDVmMmZhNDk2LWNjMDQtNDA4Ni04YTA2LWY3MDcxMzYxMzMzYQ==?nonRounded=true

Updated about 1 year ago