# Endpointy API

> Endpointy API widżetu: sesja, wiadomości z odpowiedzią strumieniową, historia, lead i workspace.

API widżetu pozwala zbudować własny interfejs czatu na asystencie ProseCaptain. Z tych samych endpointów korzysta widżet.

Bazowy adres: `https://widget-api.prosecaptain.com/api/v2/widget`

## Uwierzytelnianie

Przekaż token widżetu w nagłówku:

```text
Authorization: Bearer TWOJ_TOKEN
```

Możesz też dodać go jako parametr `?token=`. Konkretny widżet wskazujesz parametrem `widget_id` (w zapytaniu albo w treści żądania).

## Nowa sesja czatu

```text
POST https://widget-api.prosecaptain.com/api/v2/widget/thread
```

Tworzy sesję i zwraca jej identyfikator oraz historię z wiadomością powitalną.

Treść żądania (JSON, wszystkie pola opcjonalne):

- `widget_id`: identyfikator widżetu
- `session_id`: istniejąca sesja, do której chcesz wrócić
- `context`: [kontekst użytkownika](/dokumentacja/kontekst-uzytkownika/)

Odpowiedź:

```json
{
  "session_id": "session_xyz789",
  "history": [
    { "role": "assistant", "content": "Dzień dobry! W czym mogę pomóc?", "timestamp": "2026-10-19T09:00:00Z" }
  ]
}
```

## Wysłanie wiadomości

```text
POST https://widget-api.prosecaptain.com/api/v2/widget/message
```

Wysyła wiadomość użytkownika i zwraca odpowiedź asystenta.

Treść żądania (JSON):

- `session_id` (wymagane): identyfikator sesji
- `message` (wymagane): treść wiadomości, maksymalnie 4000 znaków
- `widget_id`: identyfikator widżetu
- `page_context`: kontekst strony, na której jest użytkownik
- `stream`: `true`, jeśli chcesz dostać odpowiedź strumieniowo

Przy `stream: true` odpowiedź przychodzi jako Server-Sent Events: zdarzenia `delta` z kolejnymi fragmentami tekstu, `status` z informacją o postępie, na końcu `done` z pełną odpowiedzią albo `error`.

## Historia czatu

```text
GET https://widget-api.prosecaptain.com/api/v2/widget/chat-history?session_id=SESSION_ID
```

Zwraca wiadomości sesji:

```json
{
  "messages": [
    { "role": "user", "content": "Ile trwa wdrożenie?" },
    { "role": "assistant", "content": "Zwykle jeden dzień…" }
  ]
}
```

## Zapisanie kontaktu (lead)

```text
POST https://widget-api.prosecaptain.com/api/v2/widget/save-lead
```

Zapisuje dane kontaktowe z rozmowy. Wymagany jest e-mail albo telefon (7–15 cyfr).

```json
{
  "session_id": "session_xyz789",
  "lead_data": {
    "lead_email": "anna@firma.pl",
    "lead_phone": "+48 600 000 000",
    "lead_first_name": "Anna",
    "lead_last_name": "Kowalska"
  }
}
```

## Informacje o widżecie

```text
GET https://widget-api.prosecaptain.com/api/v2/widget/workspace?widget_id=ID_WIDZETU
```

Zwraca ustawienia widżetu potrzebne do zbudowania interfejsu: nazwę, wiadomość powitalną, tytuł, podtytuł, sugerowane pytania, kolory i język.

```json
{
  "name": "Twoja firma",
  "welcome_message": "Dzień dobry! W czym mogę pomóc?",
  "widget_title": "Masz pytanie?",
  "widget_subtitle": "Odpowiadamy od razu",
  "widget_questions": [{ "question": "Ile trwa wdrożenie?", "prompt": "Ile trwa wdrożenie?" }],
  "widget_color": "#63AD61",
  "widget_language": "pl-pl"
}
```