Chat Widget Integration

The Chat Widget allows you to embed your SipPulse AI Agent directly into web pages with minimal code. This guide covers creation, installation, customization and programmatic control of the widget.

1. Create the Widget on Platform

1. Open ⋮ → Deploy in the Agents list and click + Create on the Chat Widget card.
2. Fill in the initial configuration fields:

Field	Description
Allowed Origins	Domains authorized to load the widget (e.g., example.com, *.your-company.com). Separate multiple domains with commas. Requests from other origins will be blocked with a 403 error.
Welcome Message	Initial greeting displayed when user opens the widget.
Widget Color	Primary color for icon and header, helping align the widget with your site's visual identity.

3. Click Create. The card will display the widgetKey (unique identifier) and status will change to Online.

What is the widgetKey?

The widgetKey is the public key that connects the widget on your site to your specific Agent. It's essential for initialization and should be treated as a unique identifier.

2. Installation and Mounting

2.1 Via CDN (Static HTML)

This method is ideal for static sites or systems where you don't manage JavaScript packages.

<!-- 1. Create a container for the widget -->
<div id="sippulse-chat-widget"></div>

<!-- 2. Add the widget script before closing the </body> tag -->
<script src="https://cdn.jsdelivr.net/npm/@sippulseai/chat-widget/browser/chat-widget.latest.js" defer></script>

<!-- 3. Initialize the widget when DOM is ready -->
<script type="module">
  document.addEventListener("DOMContentLoaded", () => {
    const { ChatWidget } = SipPulseChat;

    const myWidget = new ChatWidget({
      widgetKey: "<YOUR_WIDGET_KEY>",
      options: {
        color: "pulse",
        greetingMessage: "Hello! How can I help you today?",
        theme: "light",
        language: "en",
        openOnLoad: false
      }
    });

    myWidget.mount("#sippulse-chat-widget");
  });
</script>

2.2 Via NPM (Frameworks like React, Vue, etc.)

Install the package in your project:

npm install @sippulseai/chat-widget
# or
yarn add @sippulseai/chat-widget

React

// filepath: src/components/ChatWidgetComponent.jsx
import { useEffect, useRef } from "react";
import { ChatWidget } from "@sippulseai/chat-widget";

export default function ChatWidgetComponent() {
  const widgetRef = useRef(null);

  useEffect(() => {
    if (widgetRef.current) {
      const widget = new ChatWidget({
        widgetKey: "<YOUR_WIDGET_KEY>",
        options: { color: "pulse", openOnLoad: false }
      });
      widget.mount(widgetRef.current);

      // Optional: Clean up instance when component unmounts
      return () => widget.destroy();
    }
  }, []);

  return <div ref={widgetRef} />;
}

Vue 3

<!-- filepath: src/components/ChatWidget.vue -->
<template>
  <div ref="widgetContainer"></div>
</template>

<script setup>
import { onMounted, onUnmounted, ref } from "vue";
import { ChatWidget } from "@sippulseai/chat-widget";

const widgetContainer = ref(null);
let widgetInstance = null;

onMounted(() => {
  if (widgetContainer.value) {
    widgetInstance = new ChatWidget({
      widgetKey: "<YOUR_WIDGET_KEY>",
      options: { theme: "dark", language: "en" }
    });
    widgetInstance.mount(widgetContainer.value);
  }
});

onUnmounted(() => {
  if (widgetInstance) {
    widgetInstance.destroy();
  }
});
</script>

3. Configuration Options

You can customize the widget by passing an options object during instantiation. These options override the settings saved on the platform.

Option	Type	Default	Description
color	string	"pulse"	Theme color. Values: "blue", "green", "red", "yellow", "purple", "orange", "tomato", "indigo", "pulse".
greetingMessage	string	(Defined in UI)	Welcome message.
theme	"light" | "dark"	"light"	Widget visual theme.
language	"en" | "pt"	"pt"	Widget interface language (does not affect Agent responses).
openOnLoad	boolean	false	If true, widget loads already expanded.

4. Enable or Disable Widget

Use the toggle on the Chat Widget card in the SipPulse AI platform to quickly pause or resume service without needing to remove the code from your site.

• On: Widget functions normally.
• Off: Widget doesn't load and doesn't respond to new conversations.

5. Debugging and Troubleshooting

Symptom	Likely Cause	Corrective Action
403 Origin not allowed error in console	Your site's domain is not in the Allowed Origins list.	Add the exact domain (e.g., mysite.com) in the widget configuration on the SipPulse AI platform.
ChatWidget is not defined error	CDN script didn't load or was blocked.	Check if the script URL is correct and there are no blocks by security policies (CSP) or ad-blockers.
Widget doesn't appear on screen	The mount() selector didn't find the container or container doesn't exist in DOM at call time.	Ensure the container <div> exists in HTML and the mounting script runs after DOM loads (DOMContentLoaded).
Widget renders but doesn't connect	Invalid widgetKey or widget is disabled on platform.	Confirm the widgetKey is correct and widget status is Online.

6. Costs

Using the Chat Widget generates no additional costs. Billing is only associated with Agent token consumption during conversations, according to the contracted plan.