What's my plan?
Add-on AI agents - Advanced
This article describes legacy functionality and should be used only by customers who’ve already installed the Ultimate Chat Widget and need information about its maintenance. New customers should implement AI agents through the Web Widget instead.

With just a few minutes of your time, the Ultimate Chat Widget can be up and running on your website. You'll be able to provide top-notch customer support in no time! The widget is highly customizable to match your brand's unique look and feel - it is designed for optimal performance: its compact size won't slow down your page load times.

In this article:

  • Embedding the Widget
  • Loading the Widget
  • Capturing Metadata
  • Conversation History
  • Internationalization and localization
  • Generative replies configuration
  • Notifications
  • Methods
  • Forms
  • Localization
  • Data Privacy
  • FAQ

Supported platforms:

  • Desktop
  • Mobile (web)

Supported content types:

  • Text messages, including HTML formatting
  • Generative replies
  • Buttons
  • Cards & Carousels
  • Links
  • Images & GIF support

Escalations

  • Email escalation
  • Ticket creation (requires simple API integration)

Embedding the Widget

To add the widget, embed the script into your website or via a tag manager.

Make sure to swap out botID with your unique AI agent identifier. Find your botID in the URL: https://dashboard.ultimate.ai/bot/{botID}/ or https://dashboard.ultimate.ai/ultimategpt/{botID}.

Embedding Script - in HTML file

The script should be inserted before closing the body tag: </body>

<script type="module"> import UltimateChat from 'https://widget.ultimate.ai/sdk/index.mjs'; const chat = UltimateChat.Initialize({ botId: 'YOUR_BOT_ID_HERE', theme: {

'actions-hover': '#4A48B0',

'actions': '#5D5ADC',

'header-text': '#ECECF9',

'chat-button': '#15142d',

'chat-border-radius': 12px,

'header': '#000'

}, navbar: { avatarUrl: 'https://www.ultimate.ai/hubfs/raw_assets/public/ultimate/favicon/apple-touch-icon-152x152.png', title: 'Ultimate.ai', subtitle: 'Our bot will reply instantly', longSubtitle: 'I\'m an AI agent and here to answer your questions.' }, recoverConversation: true, metadata: [ { key: 'name', value: 'John Doe' }, { key: 'email', value: 'john@ultimate.ai', sanitize: true } ] }); </script>

Embedding Script - Tag Manager (GTM or similar services) 

<script> function _onUltimateChatLoad() { var chat = UltimateChat.Initialize({ botId: 'YOUR_BOT_ID', theme: {

'actions-hover': '#4A48B0',

'actions': '#5D5ADC',

'header-text': '#ECECF9',

'chat-button': '#15142d',

'chat-border-radius': 12px,

'header': '#000'

}, navbar: { avatarUrl: 'https://www.ultimate.ai/hubfs/raw_assets/public/ultimate/favicon/apple-touch-icon-152x152.png', title: 'Ultimate.ai', subtitle: 'Our bot will reply instantly', longSubtitle: "I'm an AI agent and here to answer your questions." }, recoverConversation: true, metadata: [ { key: 'name', value: 'John Doe' }, { key: 'email', value: 'john@ultimate.ai', sanitize: true } ] }); } </script> <script> (function () { var s = document.createElement('script'); s.type = 'text/javascript'; s.async = true; s.src = 'https://widget.ultimate.ai/sdk/index.iife.js'; s.onload = _onUltimateChatLoad; var x = document.getElementsByTagName('script')[0]; x.parentNode.insertBefore(s, x); })(); </script>

Style Customizations

Within the widget script, you have various options of colours you can adapt to the theme of the widget.

theme: { 
'actions-hover': '#4A48B0', 
'actions': '#5D5ADC', 
'header-text': '#ECECF9', 
'chat-button': '#15142d', 
'chat-border-radius': 12px, 
'header': '#000' 
},

Asset specifications:

Avatar - 172x172 px

Loading the Widget

Open on Load

This configuration option controls the behavior of the widget upon loading. When set to true, the widget automatically opens as soon as it's fully loaded. By default, this option is set to false meaning the chat widget remains closed until manually opened by the user.

Opening the widget will only be possible programmatically (see Methods - open widget) or via the openOnLoad configuration option. By default, this option is set to false.

 

Show/Hide widget button

This configuration option controls the visibility of the widget's 'welcome button'. When set to true, the button does not show at all, not on the initial load, and not after closing the widget.

 

Chat Position

This configuration allows you to control where you would like to see the chat widget on the screen. You can set it to Bottom-right or Bottom-leftdepending on where it suits your brand best. If undefined, the widget will default to Bottom-right.

Capturing Metadata

Metadata is data that provides additional context for the AI agent. Metadata can be used to enrich a chat by providing additional information about the customer, their behavior, and their previous interactions with the company.

By leveraging metadata, AI agents can provide a more personalized and efficient experience for customers, which can lead to increased customer satisfaction and loyalty. Additionally, metadata can help support teams analyze and improve their support processes over time.

At any time a website can set and update metadata available during the conversation.

This is done by adding to the widget code what values you would like to collect.

We can advise you on how to adapt the widget code if you would like to utilize this functionality.

Example use cases:

Customer information: Metadata can provide information about the customer, such as their name, email address, phone number, location, and other details. This information can help the AI agent personalize the conversation and provide more relevant assistance.

Purchase history: If the customer has made previous purchases from the company, metadata can provide information about their purchase history, such as the products they've bought, the date of purchase, and the price paid. This information can help the AI agent understand the customer's needs and provide targeted assistance.

Interaction history: Metadata can also provide information about the customer's previous interactions with the company, such as their previous chats, emails, or phone calls. This information can help the AI agent understand the context of the current conversation and provide a more seamless experience for the customer.

Device information: Metadata can provide information about the device the customer is using to chat, such as the device type, operating system, and browser. This information can help the AI agent troubleshoot technical issues and provide more targeted assistance.

Metadata

To provide additional context for the AI agent use:

setMetadata(Array<{
key: string;
value: string;
sanitize: boolean;
}> metadata)

If sanitize is set to true the value won't be available in the conversation logs, it appears with a placeholder

Example:

            setTimeout(() => {
                chat.setMetadata([
                    { key: 'orderName', value: 'Jane Doe' },
                    { key: 'orderEmail', value: 'jane@ultimate.ai', sanitize: true }
                ]);
            }, 2000);

Automatic metadata collection

The Ultimate Chat Widget can automatically collect metadata related to the user device.

How to set it up?

This functionality is active by default.

You can deactivate it by setting autoMetadataCollection to false

Details of the collected metadata.

This functionality is working based on the device configuration and it is not requiring cookies and user IP to function correctly.

Metadata Description
Language {{systemLanguage}}

The default language of a user device.

ie. en-GB, en-US

You can find a full list of language codes here.

(Using standard BCP 47)
Timezone {{systemTimezone}}

The timezone/region the user is currently in.

ie. Europe/Berlin,

A complete list of timezones can be found here in the column Zone ID.
Device Type {{deviceName}}

The type of device used by a user. The devices we are detecting are:

Mobile Devices: iPad, iPhone, Android, Windows Phone

Desktop Devices: Mac, Windows, Linux

Starting URL

{{url}}

The URL of the page, where the user opened the widget.

ie. https://www.google.com
Browser Name {{browserName}}

The name of the user browser.

ie. Chrome, Firefox, Opera, etc
Browser Version {{browserVersion}}

The version of the user browser.

ie. 111, 113 etc

 

Conversation History

Every conversation with the widget is stored directly in the Conversation Logs.

For a seamless conversation, we suggest enabling chat history. This lets users pick up where they left off, even after reloading the page or reopening the browser tab.

To make this happen, we utilize the browser's local storage to save the conversation ID. This way, we can retrieve the conversation data whenever needed.

Activation

To retrieve previous conversation change recoverConversation parameter to true.

Deactivation

When you deactivate conversation history (changing recoverConversation parameter to false), the lastReadMessageId_{botId} and platformConversationId_{botId} are removed from the user's Browser's Local Storage (LS). More details about the usage of the Local Storage can be found here.

recoverConversation was previously named isConversationPersistanceEnabled

 

Generative replies configuration

AI answer label

From now on, every AI-generated answer will display a label above it. This means users can easily distinguish between AI-generated content and other message inputs. It’s a step towards making the user experience more clear and informed, keeping a user in the loop about the nature of the content a user is interacting with.

Configuration:

Show / Hide info icon messageGeneratedAdditionalInfo (default  false)

Sources of messages

Every AI-generated response will now display the sources of the information, allowing you to trace back the origins of the response. This not only fosters credibility but also empowers a user to explore the topic further with credible references at their fingertips.

Configuration:

Show / Hide AI sources using parameter showLlmSources (default  true)

Notifications

Visual Notifications

These notifications act as a visual representation of incoming messages. Any time the widget is closed or minimized and a new message is received, a red notification will show the number of messages that have been received but not opened. 

Sound Notification

Sound notifications serve as audible alerts that enhance user awareness and are activated under the following conditions:
  1. Agent Escalation: When an agent joins an escalation request.
  2. Background Tab Alert: When a message arrives while the user is viewing a different browser tab.
  3. Minimized Widget Alert: When a new message arrives and the widget is minimized.
Configuration Options
Enabling/Disabling Sound NotificationsClients can configure the default state of sound notifications by using the allowSoundNotifications option within the widget script:
  • To enable sound notifications by default, set allowSoundNotifications to true.
  • To disable sound notifications by default, set allowSoundNotifications to false.
Once configured, users retain the ability to manually toggle sound notifications on or off as per their preference.

Open/Close the widget

You can easily control the widget from any place on your website by using these simple commands:

  • To show the widget openWidget()
  • To hide widget closeWidget()

Remove widget

Example use-case:

Provide access to the widget only for the users that are logged in and make sure that widget is closed after a user is logged out.

Implementation:

Call a method destroy()

Behavior:

  • Removes chat widget iframe from the DOM (Document Object Model)

  • Disconnect the WebSocket connection

 

Forms 

Form messages are a type of structured message that allows you to capture user data in an ongoing conversation by displaying a form that can contain text inputs as well as select dropdowns. 

Using Forms with AI agents - Advanced

Forms are a great way to collect customer data without having the AI agent ask multiple questions. Typical use cases include security, identification questions, or data change requests.

To create a form go to Settings / Ultimate Chat Widget / Forms and create a form based on the instructions on the page.

It is possible to create form fields like:

  • Text
  • Email
  • Select

Once your form is created, go to your respective Dialogue where you would like to add the form and follow the below steps. 

Steps:

  1. Add an AI agent message with the shorthand code to capture the form and insert it. In the picture below we are adding our lead_capture form. However, you will add the name of your form in between template: and ))% in the snippet below.

    %((template: nameOfTemplate))%

  2. Add a visitor message (Free Text Written) block right after the AI agent message. This captures the user's responses.

  3. Add another AI agent message block following the visitor message with some kind of acknowledgment of the customers' completion of the form, such as a thank you.

  4. The user's answers are locked in the metadata. If you want to use them later in the chat, you will want to retrieve them - this is completely optional. We do this with Actions.

Sanitize Customer Responses

Sanitizing responses is something you will want to do if you are asking for any PII data from your customers. This is something you will be familiar with from Content Entities, for example, we by default sanitize email addresses and IBAN numbers. To understand more about Sanitizing check out the below articles.

AI agents - Advanced data processing explained

Recipe: Sanitize Personal Identifiable Information (PII) data with content entities

How to sanitize form data

Depending on the use case you have for the forms, you may want to sanitize the information. This is easy to do. 

  1. Click the blue bar where it says "if..." to open the details panel.
  2. Click the "Sanitize the user's answer" box to have the details hidden within AI agents - Advanced

The result of this means that when you review the conversation within AI agents - Advanced, it will look as shown below.

 

Localization

It is possible to adjust the Widget locale in the runtime. To change the localization of the widget call method: setLocale(<string>)

Default value: en_US

Other supported languages: nl_NL

Testing Localization

Use the test parameter to switch the widget's language. https://widget.ultimate.ai/demo/?botId={Your.Bot.ID}&locale={Your.Locale}
ie. https://widget.ultimate.ai/demo/?botId=65da6df65ab8b465b87222586&locale=nl_NL

Example use-case: Synchronize the language of the widget interface with the website language. Call a method to update widget language when the website language changes.

Data Privacy

Our widget is SOC2 & GDPR Compliant

  • Cookies are not used.
  • Local storage is used to provide the best conversational experience.

Custom Privacy Policy URL

It is possible to add your own privacy policy accessible through our widget by adding it to the navbar section.

privacyPolicyUrl: URL

ie. privacyPolicyUrl: https://www.ultimate.ai/security-privacy

Local Storage

Our widget does not store cookies on a user's device, but there is user-side storage required to support the functionality of the widget. These are outlined below:

Parameter Name Description
platformConversationId_{botId} We store the conversation id, in order to restore the conversation on the page reload. (it is possible to deactivate it - see this section)
lastReadMessageId_{botId}

We store the id of the last read message by the user. Later this is used to calculate the notifications counter.

FAQ

  1. Do I have to connect to a CRM to test the widget? No, CRM connection is not necessary, you can implement it on a sandbox website or ask us to provide an environment if this isn't possible.
    We will be adding our widget to our platform to supplement our test AI agent functionality. 

  2. Can we track if a link was clicked? Unfortunately tracking if a link was clicked is not possible at the moment. We will evaluate adding this functionality in the future.

  3. Do we have HTML formatting in the dialogue builder? Unfortunately not at the moment. You could try using an online editor, such as - HTML5 Editor - Free Online Content Composer

  4. Can we have multiple conversations? This feature is not currently supported

  5. Does the Ultimate Chat Widget use cookies? No, our widget does not store cookies on a user's device. Please see above for details of client-side storage requirements.

Powered by Zendesk