[Intum](https://intum.fr/aide.md) / [WebChat](https://intum.fr/aide/webchat.md)

# [Support Chat Widget](https://intum.fr/aide/webchat/support-chat-widget.md) | [API](#api)

## Widget czatu na stronie

Support Chat Widget to komponent JavaScript osadzany na Twojej stronie internetowej. Wyświetla okno czatu, przez które klienci mogą pisać do Twojego zespołu w czasie rzeczywistym.

## Jak osadzić widget

1. Utwórz widget w module [WebChat](webchat) (`/webchat/admin`)
2. Skopiuj kod osadzenia z ustawień widgetu
3. Wklej go na swoją stronę przed zamykającym tagiem `</body>`

## Możliwości

- **Czat w czasie rzeczywistym** — wiadomości dostarczane natychmiast przez WebSocket
- **Załączniki** — klient może wysyłać pliki (jeśli włączone)
- **Historia rozmów** — klient widzi wcześniejsze wiadomości po powrocie na stronę
- **Powiadomienia dźwiękowe** — o nowych wiadomościach
- **Formularz kontaktowy** — opcjonalnie wymagaj imienia i e-maila przed rozpoczęciem rozmowy

## Personalizacja

- **Nazwa** — wyświetlana w nagłówku czatu
- **Tytuł** — tekst w oknie czatu
- **Opis** — dodatkowy tekst pod tytułem
- **Kolor** — kolor widgetu dopasowany do marki
- **Placeholder** — tekst zastępczy w polu wiadomości
- **Pozycja** — orientacja widgetu na stronie
- **Avatar** — zdjęcie operatora lub logo
- **Własny CSS** — możliwość dodania własnych stylów
- **Język** — widget obsługuje wiele języków

## Godziny pracy

Widget obsługuje harmonogram godzin pracy — można ustawić godziny dla każdego dnia tygodnia. Poza godzinami pracy:

- Widget może być ukryty lub wyświetlać komunikat offline
- Opcjonalnie można zezwolić na wysyłanie wiadomości poza godzinami
- Konfigurowalna treść komunikatu offline i wiadomości powitalnej

## Wymaganie danych klienta

Można wymusić podanie imienia i adresu e-mail przed rozpoczęciem rozmowy — ułatwia to identyfikację klienta i dalszy kontakt.

## Automatyczne przydzielanie

Gdy operator odpowie na rozmowę, system może automatycznie przypisać ją do niego. Tę opcję można włączyć w ustawieniach widgetu.

## Attention grabber

Można dodać graficzny element przyciągający uwagę (np. animacja) wyświetlany obok ikony czatu — zachęca klientów do rozpoczęcia rozmowy.

---

## API

### Ogólne API

# Intum API

Dokumentacja API platformy [Intum](https://intum.pl) - system operacyjny firmy.

## Host

Host jest zawsze taki sam jak adres konta: `xxxx.intum.com` lub `xxx.intum.pl` (w zależności od ustawień konta)

## Autoryzacja

Wszystkie requesty API wymagają `api_token`:
- header: `Authorization: Bearer TOKEN`

Token możesz wygenerować w **Ustawienia Konta** → **Tokeny API**

## Endpointy widgetów

| Metoda | Ścieżka | Opis |
|--------|---------|------|
| GET | `/webchat/widgets.json` | Lista widgetów |
| GET | `/webchat/widgets/:id.json` | Pojedynczy widget |
| POST | `/webchat/widgets.json` | Utworzenie widgetu |
| PATCH | `/webchat/widgets/:id.json` | Aktualizacja widgetu |
| DELETE | `/webchat/widgets/:id.json` | Usunięcie widgetu |

**Autoryzacja:** `Authorization: Bearer TOKEN` (uprawnienie: **webchat**)

## Pola widget

| Pole | Typ | Opis |
|------|-----|------|
| `name` | string | Nazwa widgetu (wymagane) |
| `title` | string | Tytuł wyświetlany w czacie |
| `description` | text | Opis pod tytułem |
| `color` | string | Kolor HEX |
| `active` | boolean | Czy aktywny (domyślnie `true`) |
| `orientation` | string | Pozycja widgetu |
| `placeholder` | string | Tekst zastępczy w polu wiadomości |
| `user_name` | string | Wyświetlane imię operatora |
| `locale` | string | Język widgetu |
| `email` | string | E-mail kontaktowy |
| `own_css` | text | Własny CSS |
| `introduce` | boolean | Czy wymagać przedstawienia się |
| `any_user` | boolean | Czy wszyscy użytkownicy obsługują |
| `offline_messages` | boolean | Czy przyjmować wiadomości offline |
| `offline_messages_welcome` | string | Wiadomość powitalna offline |
| `offline_messages_reply` | string | Tekst po wysłaniu wiadomości offline |
| `poke` | text | Tekst attention grabbera |
| `selected_responsible_id` | string | ID domyślnej grupy/zespołu |
| `department_id` | integer | ID działu |
| `opening_time` | object | Harmonogram godzin pracy |

### Pola w fields (JSONB)

| Klucz | Typ | Opis |
|-------|-----|------|
| `sound_notifications` | boolean | Powiadomienia dźwiękowe |
| `use_avatar` | boolean | Wyświetlaj avatar |
| `avatar_option` | string | `widget` lub `user` |
| `just_name` | boolean | Tylko imię (bez nazwiska) |
| `require_client_data` | boolean | Wymagaj imienia/e-maila |
| `allow_client_attachments` | boolean | Zezwól na załączniki |
| `allow_auto_assign` | boolean | Auto-przydzielanie do operatora |

## Publiczny endpoint (bez autoryzacji)

### GET /webchat/widget_data

Pobiera dane widgetu i wiadomości dla sesji czatu.

| Parametr | Opis |
|----------|------|
| `token` | Token sesji (space_token) |
| `widget_id` | ID widgetu |

Odpowiedź:
```json
{
  "messages": [...],
  "description": "Opis widgetu",
  "user_name": "Jan",
  "title": "Pomoc",
  "active": true,
  "open": true,
  "messages_after_hours": true,
  "closed_message": "Jesteśmy offline",
  "widget_avatar": "https://...",
  "require_client_data": false,
  "allow_client_attachments": true
}
```

## Godziny pracy (opening_time)

```json
{
  "opening_time": {
    "timezone": "Europe/Warsaw",
    "monday": { "from": "08:00", "to": "17:00" },
    "tuesday": { "from": "08:00", "to": "17:00" },
    "wednesday": { "from": "08:00", "to": "17:00" },
    "thursday": { "from": "08:00", "to": "17:00" },
    "friday": { "from": "08:00", "to": "16:00" }
  }
}
```

## Kod osadzenia

```html
<link rel="stylesheet" href="STYLESHEET_URL">
<div class="sugester-widget" id="intum-webchat-widget"></div>
<script>
  var intumEchoOrigin = "wss://echo.intum.net";
  var intumChatConfig = {
    accountUrl: "https://konto.intum.pl",
    account_id: 123,
    widget_id: 1,
    widget_token: "TOKEN",
    email: "",
    checksum: "SHA256_HASH",
    sound_notifications: true,
    locale: "pl"
  };
</script>
<script src="WIDGET_URL"></script>
<script>webChatWidget = new IntumWebchatWidget(intumChatConfig, intumEchoOrigin);</script>
```

## Komunikacja WebSocket

Widget łączy się z serwerem echo przez Phoenix Channels:

- **Kanał:** `webchat:user/{widget_token}/{room_token}`
- **Wysyłanie:** `push("new_msg", { message, widget_id, ... })`
- **Odbieranie:** event `new_msg` z wiadomością operatora