# Chatwoot AI translation implementation

Date: 2026-08-21

## EKSRelay endpoints

Browser/operator-facing endpoints are separate from Flowise tool endpoints and admin endpoints:

```text
GET  /chatwoot-ai-tools.js
POST /agent-tools/translate-message
POST /agent-tools/translate-draft
```

Auth:

```http
Authorization: Bearer <AGENT_UI_TOKEN>
```

`AGENT_UI_TOKEN` is intentionally separate from `ADMIN_TOKEN`; do not use the full admin/ops token in daily operator UI.

CORS allows `CHATWOOT_BASE_URL` automatically and optional extra origins from:

```text
AGENT_UI_ALLOWED_ORIGINS
```

## Translation flow

A separate Flowise chatflow was created:

```text
name: EK Agent UI Translation
id: 47ea6bda-1be4-4c11-96f6-ea0187ea8a75
predict URL: https://botek.easyklima.com/api/v1/prediction/47ea6bda-1be4-4c11-96f6-ea0187ea8a75
```

Smoke test returned:

```text
Hello, when will my order #123 arrive?
→ Witam, kiedy dotrze moje zamówienie nr 123?
```

Production EKSRelay should set:

```text
FLOWISE_TRANSLATION_PREDICT_URL=https://botek.easyklima.com/api/v1/prediction/47ea6bda-1be4-4c11-96f6-ea0187ea8a75
AGENT_UI_TOKEN=<separate operator token>
```

## JS overlay/injection asset

EKSRelay serves:

```html
<script src="https://eks-relay.easyklima.com/chatwoot-ai-tools.js" defer></script>
```

The script:

- adds a floating `AI tłumacz` panel in Chatwoot,
- stores only the operator UI token in browser `localStorage`,
- lets the operator translate selected/pasted message text,
- lets the operator translate a draft to the customer language,
- attempts to add small inline `AI→PL` buttons to detected message bubbles,
- never sends automatically to the customer; result is shown/copied only.

## Payload examples

Message translation:

```json
{
  "conversationId": 1604,
  "messageId": "12345",
  "targetLanguage": "pl",
  "sourceLanguage": "auto",
  "sourceText": "Hello, when will my order arrive?"
}
```

Draft translation:

```json
{
  "conversationId": 1604,
  "targetLanguage": "de",
  "draftText": "Dzień dobry, proszę podać numer zamówienia."
}
```

## Persistence/cache

Translations are cached in EKSRelay SQLite table `TranslationCache`, keyed by:

```text
sha256(sourceText.trim()) + targetLanguage
```

The raw source text is not stored as a lookup key. The translated text is stored so repeated operator requests do not call Flowise/OpenAI again.

## Injection options still pending

The JS is ready and served by EKSRelay. To make it appear automatically in Chatwoot, use one of:

1. reverse-proxy HTML injection sidecar, or
2. minimal Chatwoot custom image / host-mounted layout override that adds the script tag.

For production, prefer reverse-proxy injection or a documented minimal override instead of editing files inside the running Chatwoot container.