KolossusAI Chat for Django

Add a Kolossus AI assistant to your Django site, as a chat bubble on every page or as a button wherever you place a template tag.

• Set up with one command: the chat bubble then shows on every page, with no template changes.
• Or chat buttons only where you want them, with a template tag.
• Bubble, sidebar or bottom-bar layout, light / dark / automatic theme and accent colour: set in your Kolossus dashboard, or overridden in settings.
• Bubble on the bottom right or left, its distance from the edges, and its size.
• What happens on page load: remember each visitor's last state, always open, or start minimized.
• Optional: logged-in users chat under their own name with their history kept. The widget secret stays on your server; only an HMAC signature reaches the browser.

You need a Kolossus account and a widget created in the Kolossus dashboard.

Install with one command

In Kolossus, open your widget's Plugins → Django → Copy command. Then, in your project folder (the one with manage.py) and with your project's virtualenv active, paste and run it. It looks like this, with your own widget token:

pip install kolossus-chat-django && kolossus-chat-setup wt_YOUR_WIDGET_TOKEN

Restart your site, and the chat bubble shows on every page. (In Windows PowerShell 5, which has no &&, run the two commands one after the other.)

The Host URL defaults to the Kolossus cloud (https://engine.kolossus.ai). For another Kolossus server, add --host https://your-kolossus-server; the copied command already has it when you need it.

You can also download the plugin as a zip from the same Plugins sheet; it holds your Host URL and widget token, so there the command is pip install kolossus-chat-django.zip && kolossus-chat-setup.

kolossus-chat-setup (also python -m kolossus_chat) never changes your existing lines. It saves a backup (settings.py.kolossus-backup) and adds one marked block to the end of your settings file:

• kolossus_chat in INSTALLED_APPS and KolossusChatMiddleware in MIDDLEWARE, each only if missing;
• your Host URL and widget token in KOLOSSUS_CHAT, so they are kept when you later upgrade (pip install -U kolossus-chat-django). Values you set yourself win, except empty ones.

Running it again changes nothing, except with another widget token or host (or a newer zip from the dashboard): then it updates the Host URL and widget token in the block. kolossus-chat-setup --undo removes the block. If your project keeps settings in several files (for example settings/prod.py), run it for each one: kolossus-chat-setup --settings mysite.settings.prod.

The middleware adds the chat just before </body> of every full HTML page. It leaves alone Django admin sites, the Django REST framework browsable API, API docs pages (drf-spectacular, drf-yasg, django-ninja), non-HTML responses (JSON, files, downloads), error pages, and any page that already uses a kolossus_chat template tag or has a data-kolossus element or the widget script. To leave out more pages, list their URL prefixes in "EXCLUDE_PATHS", for example ["/checkout/"]. To turn the site-wide bubble off and place the chat only with template tags, set "SITEWIDE": False.

Install by hand

pip install kolossus-chat-django

Add the app and make sure the request context processor is enabled (it is in Django's default project template). Add the middleware for a bubble on every page, or leave it out and use the template tags below:

INSTALLED_APPS = [
    # ...
    "kolossus_chat",
]

MIDDLEWARE = [
    # ...
    "kolossus_chat.middleware.KolossusChatMiddleware",  # optional: bubble on every page
]

TEMPLATES = [
    {
        "BACKEND": "django.template.backends.django.DjangoTemplates",
        "APP_DIRS": True,
        "OPTIONS": {
            "context_processors": [
                "django.template.context_processors.request",
                # ...
            ],
        },
    },
]

Settings

1. In your Kolossus dashboard, create a widget for your assistant and add your site's domain (for example example.org) to its allowed domains.
2. Add its Host URL and public widget token to settings.py:

KOLOSSUS_CHAT = {
    "HOST_URL": "https://app.kolossus.ai",  # your Kolossus server; https:// only
    "WIDGET_TOKEN": "wt_...",               # the public token, starts with wt_

    # Optional
    "WIDGET_SECRET": os.environ.get("KOLOSSUS_WIDGET_SECRET", ""),  # ws_..., verified chat
    "THEME": "",              # "" = follow the visitor's device, "light", "dark"
    "PRIMARY_COLOR": "",      # "" = dashboard colour, or "#rrggbb"
    "LAYOUT": "",             # "" = dashboard layout, "bubble", "sidebar", "bottom_bar"
    "OPEN_ON_LOAD": "remember",  # "remember", "open", "closed"
    "SITEWIDE": True,         # False = the middleware adds nothing; use the template tags
    "EXCLUDE_PATHS": [],      # URL prefixes without the bubble, e.g. ["/checkout/"]
    "POSITION": "",           # bubble corner: "" = bottom right, "right", "left"
    "OFFSET_X": "",           # bubble distance from the side edge, 0-1000 px ("" = 24)
    "OFFSET_Y": "",           # bubble distance from the bottom edge, 0-1000 px ("" = 24)
    "BUBBLE_SIZE": "",        # "" = medium, "small", "medium", "large"
}

Anything left empty uses the look set for the widget in your Kolossus dashboard. POSITION, OFFSET_X, OFFSET_Y and BUBBLE_SIZE apply to the bubble layout. http:// is accepted only for a Kolossus server on localhost (local testing). Invalid values are ignored with a logged warning, and manage.py check reports them (kolossus_chat.W001 to W015).

Clicking a chat button always opens the chat.

The widget secret

WIDGET_SECRET is optional. When it is set, each logged-in user's email is signed with it (HMAC-SHA256) and the signature is passed to the chat. Kolossus checks the signature, so those users get a verified chat under their own name and keep their history. Visitors who are not logged in chat anonymously.

Keep the secret on the server: load it from an environment variable, never commit it, and never put it in a template or WIDGET_TOKEN. The tags only ever output the public token and the signature.

Use in templates

Not needed with the middleware. Use them to place the chat yourself:

{% load kolossus_chat %}

{# Chat bubble: put it in your base template, before </body> #}
{% kolossus_chat_widget %}

{# A button that opens the chat #}
{% kolossus_chat_button "Ask our assistant" class="btn btn-primary" %}

{# Only the widget script, if you write your own data-kolossus trigger elements #}
{% kolossus_chat_script %}

The widget script is output once per request, however many tags a page uses. Without a valid HOST_URL and WIDGET_TOKEN the tags output nothing.

To hide the bubble on some pages, list them in "EXCLUDE_PATHS". Or set "SITEWIDE": False and leave {% kolossus_chat_widget %} out of those templates (for example with a {% block %} that the page overrides).

Content Security Policy

If your site sends a CSP header, allow your Kolossus host in script-src and in connect-src, both https:// and wss:// (the chat uses a WebSocket):

script-src 'self' https://app.kolossus.ai;
connect-src 'self' https://app.kolossus.ai wss://app.kolossus.ai;

Privacy

This package connects your site to the Kolossus service. The chat script (widget.js) loads from your Kolossus Host URL. When the page loads, the visitor's browser sends your widget token to load the chat settings. When the visitor chats, it sends their messages, any files they attach, their IP address and approximate location (city and country) to the Kolossus server so the assistant can reply. With WIDGET_SECRET set, logged-in users' email, name and signature are sent too. Answers are generated by AI and may be inaccurate. Mention this in your privacy policy.

Kolossus terms of service: https://kolossus.ai/terms. Privacy policy: https://kolossus.ai/privacy.

Development

python runtests.py

Licence

BSD 3-Clause. See LICENSE.