[Intum](https://intum.fr/aide.md) / [Helpdesk](https://intum.fr/aide/helpdesk.md)

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

## Widget dla klientów

Support Widget to komponent JavaScript, który osadzasz na swojej stronie internetowej. Pozwala klientom wysyłać [zgłoszenia](obsluga-zgloszen) i śledzić ich status bez wychodzenia z Twojej aplikacji.

## Jak to działa

1. Tworzysz [desk](desk) w module Helpdesk
2. Kopiujesz kod widgetu z ustawień desku
3. Wklejasz go na swoją stronę internetową
4. Klienci mogą wysyłać zgłoszenia bezpośrednio z Twojej strony

## Osadzenie widgetu na stronie

Aby dodać widget na swoją stronę, wklej poniższy kod przed zamknięciem `</body>`:

```html
<div id="intum-helpdesk-widget"></div>
<script>
  var IntumHelpdeskWidget = {
    account_url: "https://twojekonto.intum.pl",
    desk_token: "TOKEN_DESKU",
    locale: "pl"
  };
</script>
<script src="WIDGET_URL"></script>
```

`account_url` i `desk_token` znajdziesz w ustawieniach [desku](desk), w zakładce Widget.

### Dane klienta

Jeśli Twoja aplikacja zna dane zalogowanego użytkownika, przekaż je w konfiguracji - widget automatycznie wypełni formularz i powiąże zgłoszenie z klientem:

```html
<script>
  var IntumHelpdeskWidget = {
    account_url: "https://twojekonto.intum.pl",
    desk_token: "TOKEN_DESKU",
    locale: "pl",
    client_external_id: "CRM-123",
    client_email: "jan@firma.pl",
    client_name: "Jan Kowalski",
    client_url: "https://klient.fakturownia.pl",
    client_plan: "Premium",
    user_external_id: "USR-456",
    user_email: "user@firma.pl",
    user_name: "Użytkownik",
    user_phone: "+48123456789",
    signature: "HMAC_SIGNATURE"
  };
</script>
```

Pole `client_external_id` jest kluczowe - bez niego klient nie zobaczy listy swoich wcześniejszych zgłoszeń.

## Parametry URL

Widget reaguje na parametry w adresie strony. Dzięki temu możesz tworzyć linki, które od razu otwierają widget z wypełnionym formularzem lub konkretnym zgłoszeniem.

### Otwarcie konkretnego zgłoszenia

Parametr `n` otwiera zgłoszenie o podanym numerze:

```
https://twoja-strona.pl/pomoc?n=2616-2
```

Widget załaduje się i od razu pokaże szczegóły zgłoszenia #2616-2 (jeśli należy do danego klienta). Przydatne np. w powiadomieniach e-mail - link prowadzi prosto do zgłoszenia.

### Wstępne wypełnienie formularza

Parametry `title`, `content`, `priority` i `c` pozwalają otworzyć widget z gotowym formularzem nowego zgłoszenia:

| Parametr | Opis |
|----------|------|
| `title` | Tytuł zgłoszenia |
| `content` | Treść zgłoszenia |
| `priority` | Priorytet: `low`, `normal`, `high`, `urgent` |
| `c` | Kod kategorii - ustawia kategorię zgłoszenia |

Jeśli którykolwiek z tych parametrów jest podany, widget od razu otwiera formularz nowego zgłoszenia (zamiast listy).

Przykład - link do zgłoszenia błędu z wypełnionym tytułem i kategorią:

```
https://twoja-strona.pl/pomoc?title=Problem+z+logowaniem&c=bugs&priority=high
```

Parametry można łączyć dowolnie. Np. sam `c=billing` otworzy formularz z ustawioną kategorią rozliczeń, a `title=Pytanie` otworzy formularz z wypełnionym tytułem.

## Możliwości widgetu

- **Formularz zgłoszenia** - klient podaje tytuł, treść, priorytet i opcjonalnie kategorię
- **Lista zgłoszeń** - klient widzi swoje wcześniejsze zgłoszenia i ich statusy
- **Szczegóły zgłoszenia** - klient może przeglądać odpowiedzi zespołu
- **Komentarze** - klient może odpowiadać na zgłoszenie
- **Załączniki** - możliwość dodawania plików (do 10 MB)

## Identyfikacja klienta

Widget może automatycznie identyfikować klienta na podstawie danych przekazanych w kodzie osadzenia:

- **E-mail i imię** - wstępne wypełnienie formularza
- **ID klienta** - powiązanie z klientem w CRM
- **Plan** - informacja o pakiecie klienta

Jeśli dane klienta nie są przekazane, widget wyświetli formularz identyfikacji.

## Bezpieczeństwo

Widget obsługuje weryfikację HMAC-SHA256 - gdy desk ma włączony poziom bezpieczeństwa "signature", każde żądanie musi zawierać prawidłowy podpis wyliczony z klucza tajnego desku. Zapobiega to podszywaniu się pod klientów.

## Sterowanie widocznością widgetu

W ustawieniach [desku](desk) (zakładka Widget) możesz kontrolować, na których stronach widget się wyświetla. Dzięki temu nie musisz modyfikować kodu na stronie - wszystko konfigurujesz z poziomu panelu Intum.

### Reguły pokazywania (URL Show Rules)

Lista wzorców URL, na których widget **ma się wyświetlać**. Jeśli podane - widget pojawi się **tylko** na stronach pasujących do wzorców. Każdy wzorzec w osobnej linii.

Przykład:
```
https://example.com/dashboard*
*/app/*
```

Widget wyświetli się tylko na stronach zaczynających się od `/dashboard` lub zawierających `/app/` w ścieżce.

### Reguły ukrywania (URL Hide Rules)

Lista wzorców URL, na których widget **nie będzie wyświetlany**. Każdy wzorzec w osobnej linii.

Przykład:
```
*/admin/*
*/settings*
*/login
```

Widget będzie ukryty na stronach administracyjnych, w ustawieniach i na stronie logowania.

### Jak działają wzorce

- `*` zastępuje dowolny ciąg znaków
- Wzorce dopasowywane są do pełnego URL strony
- Reguły ukrywania mają priorytet nad regułami pokazywania
- Jeśli nie podasz żadnych reguł, widget wyświetla się na wszystkich stronach

## Personalizacja

- **Kolor** - dostosuj kolor widgetu do swojej marki (ustawiany w [desku](desk))
- **Treść pomocy** - dodaj tekst informacyjny wyświetlany nad formularzem
- **Kategorie** - klient może wybrać kategorię zgłoszenia (każda może mieć własny tekst pomocy)
- **Język** - widget obsługuje: polski, angielski, ukraiński, niemiecki, francuski, hiszpański, czeski, słowacki

## Publiczny link do zgłoszenia

Każde zgłoszenie ma unikalny token i publiczny URL - można go wysłać klientowi w e-mailu. Klient może przez niego przeglądać zgłoszenie i dodawać komentarze bez logowania.

---

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

Widget komunikuje się z serwerem przez publiczne endpointy JSON. Nie wymagają autoryzacji Bearer — identyfikacja odbywa się przez token desku.

## Endpointy widgetu

| Metoda | Ścieżka | Opis |
|--------|---------|------|
| GET | `/helpdesk/widget/data.json?token=DESK_TOKEN` | Dane desku (nazwa, kolor, kategorie) |
| POST | `/helpdesk/widget/create_ticket.json?token=DESK_TOKEN` | Utworzenie zgłoszenia |
| GET | `/helpdesk/widget/show_ticket.json?token=DESK_TOKEN&ticket_token=TT` | Szczegóły zgłoszenia z komentarzami |
| GET | `/helpdesk/widget/client_tickets.json?token=DESK_TOKEN` | Lista zgłoszeń klienta |
| POST | `/helpdesk/widget/add_comment.json?token=DESK_TOKEN&ticket_token=TT` | Dodanie komentarza |

## Publiczny widok zgłoszenia

| Metoda | Ścieżka | Opis |
|--------|---------|------|
| GET | `/helpdesk/ticket/:token` | Widok HTML zgłoszenia |
| POST | `/helpdesk/ticket/:token/comments` | Dodanie komentarza (formularz HTML) |

## GET /helpdesk/widget/data

Zwraca konfigurację desku:

```json
{
  "name": "Support",
  "description": "Pomoc techniczna",
  "color": "#3b82f6",
  "active": true,
  "locale": "pl",
  "help_content": "Opisz swój problem...",
  "attachments_enabled": true,
  "categories": [
    { "id": 1, "name": "Błąd", "color": "red", "help_content": "..." }
  ]
}
```

## POST /helpdesk/widget/create_ticket

| Pole | Typ | Opis |
|------|-----|------|
| `title` | string | Tytuł zgłoszenia (wymagane) |
| `content` | text | Treść |
| `priority` | string | `low`, `normal`, `high`, `urgent` |
| `category_id` | integer | ID kategorii |
| `client_email` | string | E-mail klienta |
| `client_name` | string | Imię klienta |
| `client_external_id` | string | Zewnętrzne ID klienta |
| `client_url` | string | URL klienta |
| `client_plan` | string | Plan klienta |
| `user_external_id` | string | ID użytkownika końcowego |
| `user_email` | string | E-mail użytkownika |
| `user_name` | string | Imię użytkownika |
| `user_phone` | string | Telefon użytkownika |
| `attachment_signed_ids` | array | ID załączników (DirectUpload) |
| `signature` | string | Podpis HMAC (jeśli wymagany) |

## GET /helpdesk/widget/client_tickets

Wymaga `client_external_id` lub `email` + `signature` (jeśli desk wymaga).

Odpowiedź:
```json
[
  {
    "id": 123,
    "token": "xyz",
    "number": "#T-001",
    "title": "Problem",
    "status": "open",
    "priority": "normal",
    "read": true,
    "waiting_for_client": false,
    "created_at": "2026-03-05T09:00:00Z",
    "updated_at": "2026-03-05T09:15:00Z"
  }
]
```

## Podpis HMAC-SHA256

Gdy desk ma `security_level: "signature"`, żądania muszą zawierać podpis.

Algorytm:
1. Zbierz parametry tożsamości: `client_email`, `client_external_id`, `client_name`, `client_plan`, `client_url`, `user_email`, `user_external_id`, `user_name`, `user_phone`
2. Usuń puste wartości
3. Posortuj alfabetycznie po kluczu
4. Połącz jako `key1=value1&key2=value2`
5. Oblicz HMAC-SHA256 z `secret_key` desku

```ruby
data = params.compact_blank.sort_by { |k, _| k.to_s }.map { |k, v| "#{k}=#{v}" }.join("&")
signature = OpenSSL::HMAC.hexdigest("sha256", desk.secret_key, data)
```

## Kod osadzenia

```html
<div id="intum-helpdesk-widget"></div>
<script>
  var IntumHelpdeskWidget = {
    account_url: "https://konto.intum.pl",
    desk_token: "TOKEN_DESKU",
    client_external_id: "CRM-123",
    client_email: "jan@firma.pl",
    client_name: "Jan Kowalski",
    locale: "pl",
    signature: "HMAC_SIGNATURE"
  };
</script>
<script src="WIDGET_URL"></script>
```

---

## Powiązane

- [Automatyczne odpowiedzi AI w Widgecie Helpdesk](https://intum.fr/aide/helpdesk/automatyczna-obsluga-uzytkownikow-z-ai.md)