Embedding Visitor Dialog

Introduction¶

Welcome to the Giosg visitor dialog embedding tutorial!

This guide will show you how to embed the Giosg visitor chat dialog directly into an element on your webpage, rather than having it appear as a floating window. This is useful when you want to integrate the chat experience seamlessly into your page layout, such as in a sidebar, footer, or dedicated chat section.

What is Dialog Embedding?¶

Dialog embedding allows you to display the Giosg visitor chat dialog inside a specific HTML element on your webpage. The embedded dialog provides the full chat functionality while appearing as a native part of your page design.

Example of embedded dialog

Key features:

Full chat functionality within your page layout
Dialog automatically uses all available space in the target element
Can coexist with the floating dialog if desired
Responsive to the target element's size
Optional fixed room via the JavaScript API by passing a room ID as the second argument to embedDialog

Embedding Methods¶

There are two ways to embed the Giosg visitor dialog into your webpage:

Method 1: Automatic Embedding with CSS Class¶

The simplest way is to add a div element with the class name giosg-chat-embed-placeholder-v2 to your page. The Giosg script will automatically detect this element and embed the dialog into it.

<!DOCTYPE html>
<html>
<head>
    <title>My Website</title>
    <style>
        .chat-container {
            width: 400px;
            height: 600px;
            border: 1px solid #ccc;
            border-radius: 8px;
        }
    </style>
</head>
<body>
    <h1>Welcome to My Website</h1>

    <!-- Chat will automatically embed here -->
    <div class="giosg-chat-embed-placeholder-v2 chat-container"></div>

    <!-- giosg tag -->
    <script>
    (function(w, t, f) {
    var s='script',o='_giosg',h='https://service.giosg.com',e,n;e=t.createElement(s);e.async=1;e.src=h+'/live2/'+f;
    w[o]=w[o]||function(){(w[o]._e=w[o]._e||[]).push(arguments)};w[o]._c=f;w[o]._h=h;n=t.getElementsByTagName(s)[0];n.parentNode.insertBefore(e,n);
    })(window,document,"<Organization ID>");
    </script>
    <!-- giosg tag -->
</body>
</html>

Note

Pinning the embedded dialog to a specific room is only supported through the JavaScript API (Method 2). Method 1 does not support passing a room ID.

Method 2: JavaScript API¶

For more control over when and where the dialog is embedded, you can use the JavaScript API. This method is useful when you need to dynamically embed the dialog based on user actions or specific conditions.

<!DOCTYPE html>
<html>
<head>
    <title>My Website</title>
    <style>
        #my-chat-container {
            width: 400px;
            height: 600px;
            border: 1px solid #ccc;
            border-radius: 8px;
        }
    </style>
</head>
<body>
    <h1>Welcome to My Website</h1>

    <!-- Target element for embedding -->
    <div id="my-chat-container"></div>

    <!-- giosg tag -->
    <script>
    (function(w, t, f) {
    var s='script',o='_giosg',h='https://service.giosg.com',e,n;e=t.createElement(s);e.async=1;e.src=h+'/live2/'+f;
    w[o]=w[o]||function(){(w[o]._e=w[o]._e||[]).push(arguments)};w[o]._c=f;w[o]._h=h;n=t.getElementsByTagName(s)[0];n.parentNode.insertBefore(e,n);
    })(window,document,"<Organization ID>");
    </script>
    <!-- giosg tag -->

    <script>
        // Wrap the embedDialog call in _giosg() to ensure the script is fully loaded
        _giosg(function() {
            giosg.embedDialog("#my-chat-container");
        });
    </script>
</body>
</html>

embedDialog accepts a CSS selector as the first argument. You can pass an optional second argument: the room ID as a UUID string. When provided, the embedded dialog is forced to that room only. If you omit the second argument, the embedded dialog joins the room the visitor is currently in.

To embed the dialog into a specific room, use two arguments (replace the example UUID with your real room ID from Giosg):

_giosg(function() {
    giosg.embedDialog("#my-chat-container", "8ba6a6118-3407-11f1-929b-000000000000");
});

Important

Always wrap your giosg.embedDialog(selector[, roomId]) call inside the _giosg() function. This ensures that the Giosg script has fully loaded before attempting to embed the dialog.

Controlling Dialog Size¶

The embedded dialog will automatically fill all available space in its container element. You can control the size and appearance of the dialog by styling the target element.

Fixed Size Example¶

<style>
    .chat-fixed {
        width: 320px;
        height: 350px;
        border: 2px solid #0066cc;
        border-radius: 10px;
        box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);
    }
</style>

<div class="giosg-chat-embed-placeholder-v2 chat-fixed"></div>

Responsive Example¶

<style>
    .chat-responsive {
        width: 100%;
        max-width: 500px;
        height: 600px;
        margin: 0 auto;
    }

    @media (max-width: 768px) {
        .chat-responsive {
            height: 400px;
        }
    }
</style>

<div class="giosg-chat-embed-placeholder-v2 chat-responsive"></div>

Full Height Example¶

<style>
    .sidebar-chat {
        width: 320px;
        height: 100vh; /* Full viewport height */
        position: fixed;
        right: 0;
        top: 0;
        border-left: 1px solid #e0e0e0;
    }
</style>

<div class="giosg-chat-embed-placeholder-v2 sidebar-chat"></div>

Using Multiple Dialogs¶

You can have both the embedded dialog and the floating dialog open simultaneously on your website. This can be useful for providing multiple chat access points for your visitors.

With this setup:

The embedded chat dialog appears within the page content
The floating chat button remains available in the corner
Visitors can use either interface based on their preference

Best Practices¶

Set explicit dimensions: Always define width and height for your container element to ensure proper display.
Use the _giosg() wrapper: When using the JavaScript API, always wrap your code in the _giosg() function to ensure the script is loaded.
Consider mobile responsiveness: Use responsive CSS units and media queries to ensure the embedded dialog works well on all devices.
Test visibility: Ensure your container element is visible and properly positioned in your layout.
Avoid z-index conflicts: If using fixed or absolute positioning, ensure your z-index values don't conflict with other page elements.
Room targeting: Pass the room ID as the second argument to embedDialog when the embed must always use a specific room; omit it when the embed should follow the visitor’s current room. Remember that fixed-room embedding is only available via the JavaScript API, not Method 1.

Troubleshooting¶

Dialog Not Appearing¶

Check that the Giosg script is loading correctly
Verify your container element exists in the DOM before calling the embed function
Verify your container element has explicit dimensions (width and height)
Ensure the container element is visible (not display: none or visibility: hidden)
Check browser console for any JavaScript errors

When the Giosg dialog is embedded directly into a page, the chat is no longer an external, standalone service that the visitor navigates to — it is a functional, integral part of the page itself. This distinction matters for cookie and consent handling.

Why cookies can be enabled on the embedding page¶

Regulatory guidance (for example, the Finnish Transport and Communications Agency Traficom's interpretation of the ePrivacy rules) treats external chat widgets as third-party services that typically require explicit consent before any non-essential cookies may be set. An embedded dialog is different: because the chat has been intentionally integrated into the page as part of its primary functionality, the cookies required to make that chat work are considered necessary for the service the visitor has come to use on that page.

In practice this means that on a page where the Giosg dialog is embedded as a core feature of the page, it is permissible to allow the cookies that the chat needs in order to function, even before a general site-wide consent for giosg has been given. The visitor is using the chat as the purpose of the page, so the cookies supporting that chat are tied to a service the visitor has actively engaged with.

Important

This reasoning applies only when the embedded dialog is genuinely an integral part of the page's purpose (for example, a dedicated support page or a product search-/recommendation page). If the chat is merely a floating widget added on top of unrelated content, the standard external-chat consent rules still apply. Traficom's current guidance does not explicitly cover this use case, as embedding the chat as an integral part of a page is a newer pattern that emerged after the guidance was written.

Consent management for Giosg follows the mechanism documented in Transparency & Consent. Two scenarios are common:

Site-level consent is already granted. If the visitor has already given consent for Giosg cookies through your site's consent management platform, no additional action is needed — the embedded dialog will work as usual.
Site-level consent is not granted (or not applicable). If Giosg consents have not been given at the site level, you should enable them specifically for the page that hosts the embedded dialog. Because the embedded chat is essential to that page's function, it is acceptable to grant the required Giosg consent on this page even if the rest of the site withholds it by default.

If consent is not granted, the embedded chat can still be opened and used, but it falls back to using a temporary visitor ID. This has a visible side effect: because the visitor ID is not persisted between page loads, each page load creates a new identity, and any ongoing chat conversation is lost as soon as the visitor navigates or reloads the page.

For the embedded chat to retain its conversation across page loads, the Giosg consent must be granted so that the visitor ID can be stored.

Granting the required consent does not have to be done through the site's main consent management platform. The same rule that enables the embedded chat on a page can also set the giosg consent for that page. This means you can ship the embedded chat without any changes to the existing site-wide consent management — the consent needed for the embed is configured together with the embed itself.

Follow the API described in the Transparency & Consent documentation to signal consent for Giosg on pages where the dialog is embedded.