# Customer chat and support inbox

A "Chat with us" button for visitors and an inbox where the owner replies. Visitors keep their conversation when they
move between pages (it is stored in their browser) and see replies within seconds. Everything is stored in the
website's own database; no third-party chat service is involved.

Requires the `base` package. The inbox uses the base admin password.

## Install

Use the verified installer in the website container. It installs dependencies, checks checksums, and refuses to replace customer changes:

```sh
python /opt/runalio/catalog_install.py support-chat
python /opt/runalio/catalog_install.py --status
```

Review the preview and click Publish to promote backend code and pages. Production data remains separate.

To undo the last installation before publishing: `python /opt/runalio/catalog_install.py --rollback`.

## Settings

The customer enters these in Runalio, Settings → Website modules → this module (never in files or chat):

| Name | Required | Secret | Purpose |
|---|---|---|---|
| `OWNER_EMAIL` | no | no | Receives a notice for each new conversation (needs the base email settings). |
| `CHAT_WELCOME` | no | no | The first message visitors see. |

## Add it to pages

Copy `site/chat-widget.js` and `site/chat-widget.css` into `/workspace/site` and add to every page that should show
the chat button:

```html
<link rel="stylesheet" href="chat-widget.css">
<script src="chat-widget.js" defer></script>
```

Adjust the colours in `chat-widget.css` to match the website.

## The owner's inbox

`<website>/api/admin/chat` (open through Runalio’s business admin link): conversations with unread ones first, replies, and
closing. It refreshes every 10 seconds. The admin area also lists conversations with CSV export. Closed conversations
are deleted after a year.

## API

| Request | Purpose |
|---|---|
| `GET api/chat/config` | Welcome message |
| `POST api/chat/conversations` | `{name?, email?, message}`, returns `{id, token}` |
| `GET api/chat/conversations/<id>/messages?token=&after=` | New messages |
| `POST api/chat/conversations/<id>/messages` | `{token, message}` |

## What the customer needs to do

1. Open Settings → Website backend → Open business admin, then choose Chat. The account’s current team members can reply; removing a teammate revokes access. `ADMIN_PASSWORD` is only for standalone installs.
2. Optional: set up the base email settings and `OWNER_EMAIL` to receive an email for each new conversation.
3. Optional: `CHAT_WELCOME` for the greeting.
4. A paid Runalio package keeps the chat available around the clock.

Replies appear only while the visitor's page is open; if they leave an email address, the owner can also reply by email.