Webchat Plugin

A tool for webchat widget customization and easy implementation into your website, app and mobile channels.

Adding a chat widget to your website, app, and mobile channels has become even easier. Now, you can customize the widget's appearance with a few clicks, preview its look, and publish it seamlessly.

The platform enables you to create a personalized webchat solution that perfectly matches your brand identity, ensuring a dynamic user experience.

This step-by-step guide will walk you through the process of customizing and adding a webchat widget from Syntphony CAI’s Cockpit.

To access the customization page, access the Channels page on the side menu and then choose the channel.

Customization

Name and description

Start the customization by providing a name for your virtual agent, along with a description and the message that will appear in the customer's text box. As you fill out the fields, you can already preview on the left how it’ll look. 🤩

Color scheme

Explore the wide variety of color options and find the perfect fit for your brand. For that, just click the color picker icon to see the options. You're able to select your preferred theme for:

Header
Background
Texts
Buttons
Minimized icon
Footer

Syntphony CAI supports hundreds of colors using the HEX notation (a six-digit combination of numbers and letters defined by its mix of red, green and blue, or RGB). You can use the color pick to choose between solid or gradient.

You can check sites like https://www.color-hex.com/ to copy the HEX code and paste it into the corresponding field.

Upload image

Now it’s time to upload an image. Syntphony CAI allows you to upload an image for your avatar or background.

Click on the “link” icon and paste the URL into the designated field. Make sure the image format is one of the accepted types: JPG, JPEG, PNG, SVG, or GIF, with a maximum size of 1MB. The recommended dimensions are 40x40px.

However, you have the option to skip this step. In this case, the default image displayed for the avatar will be this adorable little robot icon (as seen below) and a solid light blue background.

Fonts

The customization also covers 27 different types of fonts and 6 different sizes for:

Header
Dialog texts
Buttons
Footer

Embedding

Once you’ve finished the customization, simply copy the generated script into your HTML to easily integrate it into your website or app.

The generated script will remain the same even if you change the settings, so you may edit it without the need to update your HTML again.

Don’t forget to save the changes. 😊

Customize the webchat

Adding a chat widget to a website, application, or mobile channel is a simple process that enables the integration of an AI-based conversational agent without leaving the page.

The implementation is done by inserting a JavaScript script and configuring initialization parameters, contexts, and chat behavior. The platform includes customization options that allow you to adjust the widget’s appearance, preview changes before publishing, and apply them instantly.

This functionality makes it easier to create a chat experience that aligns with the visual identity of the digital environment and enhances interaction between the user and the conversational agent.

Add the chat script

The chat script is the core element of the Webchat Plugin. This script loads the library that enables the display and interaction of the chat widget on the website.

Procedure Insert the chat script into the HTML file. It can be placed inside the <head> tag or right before the closing </body> tag.

<script src="https://****.eva.bot/eva-chat.js"></script>

Replace **** with the corresponding URL of the EVA or Agents instance.
Once added, the script will download the necessary resources to initialize the chat component.
Save the changes and reload the site. The browser will then be ready to start the chat with the bot’s parameters.

Example

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Site with Webchat</title>
    <script src="https://example.eva.bot/eva-chat.js"></script>
  </head>
  <body>
    <!-- Site content -->
  </body>
</html>

The chat

Once the component script has been added, the next step is the chat itself. During this process, the main connection parameters are defined (bot identifiers, environment, and channel), and the initial behavior of the widget on the site is configured.

This enables the conversational component and controls its availability, ensuring that the chat loads correctly when accessing the page. In addition, this configuration is required for the widget to interact with AI services and maintain session context.

Procedure

Add the initialization code right after the chat script.
Use the initializeChat() method or the <eva-chat> tag with the required attributes:

<eva-chat
  instance-url="https://**********.eva.bot"
  org-id="your-org-id"
  env-id="your-env-id"
  bot-id="your-bot-id"
  channel-id="your-channel-id">
</eva-chat>

<script>
  initializeChat(
    "https://**********.eva.bot", // instance-url
    "your-org-id",                // org-id
    "your-env-id",                // env-id
    "your-bot-id",                // bot-id
    "your-channel-id"             // channel-id
  );
</script>

The example values must be replaced with those corresponding to your organization. When the page is reloaded, the chat will initialize and become available to visitors.

<script src="https://example.eva.bot/eva-chat.js"></script>
<eva-chat
  instance-url="https://example.eva.bot"
  org-id="org123"
  env-id="prod"
  bot-id="agentic-001"
  channel-id="webchat">
</eva-chat>

<script>
  initializeChat(
    "https://example.eva.bot",
    "org123",
    "prod",
    "agentic-001",
    "webchat"
  );
</script>

Manipulate context

In addition to adding context, the Webchat Plugin allows you to query, modify, or delete information using the following built-in functions:

SyntphonyConversationalAIChat.context;               // Get full context
SyntphonyConversationalAIChat.context = { name: "John Doe" }; // Replace context
SyntphonyConversationalAIChat.getContextByKey("key"); // Get a specific value
SyntphonyConversationalAIChat.hasContext("key");      // Check if a key exists
SyntphonyConversationalAIChat.clearContext();         // Clear all context
SyntphonyConversationalAIChat.removeContext("key");   // Remove a specific key

Example:

window.addEventListener("SCAIChatInitialized", (event) => 
{
  SyntphonyConversationalAIChat.context = { name: "Laura" };
  console.log(SyntphonyConversationalAIChat.hasContext("name")); // true
  console.log(SyntphonyConversationalAIChat.getContextByKey("name")); // "Laura"
});

Open and close the chat

The Webchat Plugin provides functions to control opening, closing, or minimizing the chat from anywhere in the application.

Available methods

SyntphonyConversationalAIChat.openChat();     // Opens the chat
SyntphonyConversationalAIChat.closeChat();    // Closes the chat
SyntphonyConversationalAIChat.minimizeChat(); // Minimizes the chat

To open the chat automatically when the page loads, you can invoke openChat() after initialization. Example:

<script>
  window.addEventListener("load", function () {
    SyntphonyConversationalAIChat.openChat();
  });
</script>

Handling chat events

The Webchat Plugin emits events that can be listened to using window.addEventListener. These events allow you to execute custom actions based on the state of the chat or session.

Example events:

window.addEventListener("SCAIChatInitialized", (event) => {
  console.log("Chat initialized", event);
});
window.addEventListener("SCAIChatOpened", (event) => {
  console.log("Chat opened", event);
});
window.addEventListener("SCAIChatMinimized", (event) => {
  console.log("Chat minimized", event);
});
window.addEventListener("SCAIChatClosed", (event) => {
  console.log("Chat closed", event);
});
window.addEventListener("SCAIContextUpdated", (event) => {
  console.log("Context updated", event);
});
window.addEventListener("SCAIChatError", (event) => {
  console.error("Chat error", event);
});

Implementation example:

<script>
  window.addEventListener("SCAIChatOpened", () => {
    console.log("User opened the chat");
  });

  window.addEventListener("SCAIChatError", (e) => {
    alert("An error occurred while starting the chat");
    console.error(e);
  });
</script>

Use cases and behavior management

During chat integration, user context may be lost if it is added at the wrong time. Context includes relevant session information, such as identification data, preferences, or any other variable necessary to maintain conversation continuity.

When the chat is closed, the session and its context may be reset, causing this information to be lost. To prevent this, context should be added every time the chat is opened.

The recommended way to do this is via the SCAIChatOpened event. This event is automatically emitted when the chat component is initialized and displayed. Defining context within this event ensures that values are correctly restored each time the chat is reopened.

Example:

<script>
  window.addEventListener("SCAIChatOpened", function () {
    SyntphonyConversationalAIChat.addContext({
      userId: "12345",
      userName: "John"
    });
  });
</script>

In this example, when the chat opens, the userId and userName values are added to the conversation context.

Context manipulation is performed exclusively through openContext, and it should be accessed in the Cockpit via $openContext in fields like Responses. Example: $openContext.name

The Webchat is designed for single-page applications (SPA). Reloading the page or navigating in non-SPA applications will close the session.

PreviousIntegrating Existing Channels NextParameters

Last updated 9 days ago