Metadata-Version: 2.4
Name: kolossus-chat-django
Version: 1.3.1
Summary: Add a KolossusAI chat assistant to your Django site with one command.
Author: Kolossus AI
License-Expression: BSD-3-Clause
Project-URL: Homepage, https://kolossus.ai
Keywords: django,chatbot,ai,chat,assistant,kolossus
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Framework :: Django :: 4.2
Classifier: Framework :: Django :: 5.0
Classifier: Framework :: Django :: 5.1
Classifier: Framework :: Django :: 5.2
Classifier: Framework :: Django :: 6.0
Classifier: Framework :: Django :: 6.1
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Django>=4.2
Dynamic: license-file

# 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:

```sh
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, and only while the package is installed in the Python that
  runs your site: if it is not (installed into another virtualenv, or uninstalled),
  the site still starts, just without the chat;
* 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.
After upgrading from 1.3.0 (`pip install -U kolossus-chat-django`), run
`kolossus-chat-setup` once more: it brings the block up to date and keeps your token.
`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

```sh
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:

```python
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`:

```python
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`).

| `OPEN_ON_LOAD` | On page load or refresh |
|---|---|
| `remember` (default) | As the visitor last left it (open or minimized); open on a first visit |
| `open` | Always open |
| `closed` | Only the bubble or tab shows until the visitor clicks it |

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:

```django
{% 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

```sh
python runtests.py
```

## Licence

BSD 3-Clause. See `LICENSE`.
