Creating a Web Messenger
The Flow XO Web Messenger is a bot interface that can be embedded in any website, landing page or web app. It can be accessed through a website control, directly via it's own URL, or can be embedded within the body of a webpage.
Installing the Web Messenger
The web messenger can be installed on your website, landing page or web app. The final step when creating/editing your web messenger will give you some code to display a control that opens the web messenger.
You should paste this code just before the closing </body> tag on your web page. The web messenger is designed not to slow down your page.
This video demonstrates all the options available to embed your web messenger:
Follow these steps to create a web messenger:
- In Flow XO, click Bots on the left menu bar, then choose + New.
- Now choose Web as the platform.
- Type in a descriptive name for the messenger.
- In the Welcome Text field, you can optionally provide some welcome text. If you leave this blank default welcome text will be used.
- Select the Language and enter a Custom Prompt Message as required. View the guide on International Language support for more information.
- Select if you want to Forget conversation history when the user closes the messenger.
- Select if you want to Disable text input in the messenger. This removes the text composer and limits the user to the choices you've defined.
- Select if you want to Disable attachments. This removes the 'paperclip' upload button on the text composer.
- Select if you want the web messenger to send IP address and location information in the metadata. If your bot is governed by GDPR, only check this box if you are confident you will meet the consent requirements as IP address is considered personal information under the GDPR.
- You can change the Theme Color if you wish, which is the main color that will be used on the messenger window.
- Add an Icon if required.
- For Header Text, provide the text that you want to display on the widget label and as the title of the messenger control. You can leave it blank to use the default text, 'Message Us'.
- For Widget Popup Message, provide the text that you want to show up alongside the widget icon to attract your visitor's attention. (Shows after a short delay of 5 seconds, once every 30 days per visitor).
- For Popup Height, leave blank if you want a full height chat window, or a specific value otherwise. Be careful to use a height that will work well on mobile and desktop. You can use absolute pixels or percentages.
- Click Next to save your bot.
- The final step allows you to test the messenger (you'll see a test widget in the bottom right corner of the screen), and to copy and paste code to display on your website.
- Click Done to finish.
Welcoming a New User
When the user opens the web messenger for the first time, the message 'start' will be sent to it. You can look for the presence of this and welcome the user if you like.
Web Messenger API
You can control the web messenger from within the page using the Web Messenger API. This JavaScript API lets you open/close the messenger, send a message as the user, and receive events about the state of the messenger.
Customizing the Look and Feel
If you have some web development experience or access to a web developer, you can learn how to completely customize the look and feel of the web messenger here: https://support.flowxo.com/article/263-web-actions
Web Specific Features
The Web Messenger has a few powerful features that are unique, such as the ability to execute custom client-side JavaScript code as part of a flow or disable the text input dynamically. Because Flow XO supports many channels, not just the Web, our standard flow building tools cannot take advantage of many of these features. However, if you are building Web specific flows you can take advantage of these from within Flow XO by using our Web Actions integration, which provides easy access to most Web bot functionality.
Available Metadata
The Web Messenger makes several useful data points available by default in the Metadata field of any flows that it executes. Which fields get included partially depends on whether or not you have opted to send the users IP address, which will also cause a few additional location related fields to be sent as well.
| Field | Description | Notes |
| firstTimeUser | Whether or not the current user is a new user, i.e. has never interacted with your bot before | |
| browserName | The name of the users browser, for example "Chrome" | |
| mobile | If the browser is a mobile browser, the metadata field 'mobile' will equal true. Otherwise it will be missing. | |
| tablet | If the user is browsing from a tablet, the 'tablet' metadata field will equal true. Otherwise it will be missing. | |
| operatingSystem | The OS of the user, for example "OS X" | |
| operatingSystemVersion | The specific version of the users operating system, such as "10.16.1" | |
| timeZone | The timezone of the users browser, in IANA format. Example: "America/Los_Angeles" | |
| country | The country of the user, for example "United States" | |
| hostUrl | The URL of the page that is hosting the Web Messenger widget. For example: "https://mysites.com/thisPageHasABot?pageid=12" | This is only useful when using embedding the widget into a webpage. It will not work if you are using an iFrame to embed your chatbot. |
| externalUserId | If you have used the Web Messenger SDK to set an external user identifier, this will show up in the metadata. Note that this is in addition to the users primary identifier being set to this value, instead of a random set of characters. | |
| ip | The IP address of the user | This will only be populated when 'Collect Users IP Address' is selected in the channel configuration |
| region | The geographical region of the user. Varies by country. In the US, this will be the state, such as 'California' | This will only be populated when 'Collect Users IP Address' is selected in the channel configuration |
| latitude | The rough latitude as determined from the users IP. This will NOT be an accurate location of the user, but can be useful for plotting general user locations on a map with more precision than the country or region. | This will only be populated when 'Collect Users IP Address' is selected in the channel configuration |
| longitude | The rough longitude as determined from the users IP. This will NOT be an accurate location of the user, but can be useful for plotting general user locations on a map with more precision than the country or region. | This will only be populated when 'Collect Users IP Address' is selected in the channel configuration |
NOTE: When using the direct URL (sending users to the hosted chatbot page) or when embedding a chatbot into a page using an iFrame, any query string parameters appended to the embed URL will also be included as metadata elements. For example, if you are directing users to a host bot at a url like this:
https://flowxo.com/m/jgdz3xxx?myParam=5&anotherParam=6
then the metadata field will include properties for myParam and anotherParam. If you are embedding your bot as a widget and you want to add additional metadata you can do so using the Web Messenger API.
Embedding Options
The web messenger can be embedded on your site in several ways:
- As a chat widget that pops open as a sidebar when the user clicks the talk bubble. You can also have the sidebar appear when the user clicks on of your own buttons/links.
- As an overlay(modal dialog) that opens when the user clicks a button on your page
- Loaded into a specific element you have positioned on your page
- Embedded as an iframe on your page
- As a standalone web page with a URL you can direct your users to
For examples of how to embed the widget using these various options, please click here.
FAQ's
Does the web messenger maintain state?
The first time a unique visitor opens the messenger, a session is stored in their browser (they'll also see the bot's welcome message too, if configured). When they return to your site, they'll see all their message history. Select Forget conversation history when the user closes the messenger if you want to load the web messenger with an empty conversation at the start of the next session. This may be useful if your users share PCs, for exchanging confidential information or on compliance grounds.
A Reset conversation option is also given to the user in the top right corner of the web messenger. This will clear all conversation content from the web messenger and will end the current conversation and restart it.
If you select the option to Disable text input in the messenger, then the the web messenger is loaded with an empty conversation at the start of each new session.
No option above deletes any data from the database. If the browser's storage is reset, the history will be lost.
What is the user's name and handle set to?
The web messenger is anonymous, and so the user name and user handle properties will be empty when you interact with a web visitor. You can always ask the user for their name.
Can the visitor send a file/location/image?
Yes, the visitor can send files and images. It's not possible to send a location just yet, sorry.
Can I broadcast to the web messenger?
Yes, the web messenger works like any other platform. If you broadcast to a web messenger user, the next time the user visits your site and opens the messenger, they'll see the message(s).
Is it possible to control how/when the messenger is displayed?
Yes, you can use the Web Messenger API to control the messenger from any page that it's installed on.
Can I send metadata?
Yes, either by using the Web Messenger API or by adding parameters to the query string when you use the web messenger's direct URL (for example, &foo=bar).
Metadata will be available inside the metadata output when you receive a new message through the bot.
Let us know how we can improve Flow XO on our feedback site.
Can I execute different flows based on the current page on my site that the user is chatting on?
Yes. If you are embedding your chatbot as a widget, you can combine a trigger filter with the hostUrl property in the metadata to select which flow(s) you want to execute based on the current page your user is on. If you are embedding the chatbot using an iFrame, then you would need to manually append the current URL to the bots URL when embedding the iFrame in your page. This would be an advanced procedure.
The Widget Popup Message is only shown once and I never see it again. Is this correct?
The default is to show the widget popup message one time per unique visitor per 30 days. However, you can customize this when you embed the widget on your page using the following data attribute. You can also customize when the popup is shown, and for how long:
<script src="https://widget.flowxo.com/embed.js?callback=messengerReady" data-fxo-widget="...my widget code..." data-hide-welcome-message-days="0" data-reveal-welcome-message-seconds="1" data-hide-welcome-message-seconds="5" async defer> </script>