Implementacja Prose Captain

Dodaj asystenta AI do swojej strony w kilku prostych krokach.

1. Konfiguracja

Zanim zainstalujesz Prose Captain na swojej stronie, powinieneś skonfigurować swoje konto i uzyskać niezbędne informacje. Poniżej znajdziesz instrukcje krok po kroku.

Uzyskaj token

Aby uzyskać unikalny token dla swojej strony:

Zaloguj się do swojego konta na prosecaptain.com
Przejdź do Profilu użytkownika
W sekcji "Tokeny API" znajdziesz swój unikalny Token ID
Skopiuj token i zapisz go - będzie potrzebny podczas instalacji widgetu

Ustawienia AI

Możesz dostosować zachowanie asystenta AI, dodając własne instrukcje i prompty. Aby to zrobić:

Zaloguj się do panelu administracyjnego Prose Captain
Przejdź do sekcji "Artificial Intelligence Settings"
W sekcji "Prompt Template" możesz dostosować instrukcje dla swojego asystenta
Wprowadź swoje instrukcje, określając jakie informacje asystent powinien znać i jak powinien się komunikować
Zapisz zmiany, klikając przycisk "Zapisz"

Porada

Dobrze napisany prompt może znacząco poprawić jakość odpowiedzi asystenta. Upewnij się, że prompt zawiera konkretne instrukcje dotyczące charakteru, tonu i zakresu wiedzy asystenta.

Preferencje językowe

Prose Captain obsługuje różne języki, które możesz skonfigurować w panelu administracyjnym. Aby ustawić preferowany język:

Zaloguj się do panelu administracyjnego
Przejdź do sekcji "Widget Settings"
Wybierz preferowany język z dostępnych opcji (np. polski, angielski)
Zapisz swoje preferencje

Wybrany język będzie używany w interfejsie widgetu oraz wpłynie na domyślny język odpowiedzi asystenta.

2. Instalacja

Po skonfigurowaniu konta i uzyskaniu tokenu możesz przejść do instalacji widgetu na swojej stronie. Poniżej znajdziesz instrukcje, jak to zrobić.

Jak dodać skrypt

Umieść poniższy kod w sekcji <head> swojej strony:

<script
    src="https://widget-api.prosecaptain.com/embed.js"
    data-widget-token="YOUR_TOKEN_HERE"
    data-theme="light" 
></script>

Konfiguracja parametrów

data-widget-token

Twój unikalny token dostępu do widgetu. Wstaw token uzyskany z panelu administracyjnego.

data-theme

Motyw widgetu: "light" lub "dark"

data-api-url

URL do API Prose Captain

3. Konfiguracja zaawansowana

Dla zaawansowanych użytkowników, Prose Captain oferuje możliwość integracji z własnymi aplikacjami za pomocą API oraz dodatkowe opcje personalizacji. Poniżej znajdziesz dodatkowe możliwości dostosowania i integracji.

3.1. Kontekst użytkownika

Podczas tworzenia nowej sesji czatu możesz przekazać kontekst użytkownika, który pomoże asystentowi lepiej zrozumieć jego potrzeby i dostosować odpowiedzi. Kontekst może zawierać informacje takie jak:

Dane użytkownika (np. imię, identyfikator)
Informacje o aktualnej stronie lub kategorii
Preferencje i zainteresowania
Historia przeglądania
Inne niestandardowe dane

Aby przekazać kontekst użytkownika, dodaj obiekt context w ciele żądania przy tworzeniu nowej sesji:

// Przykład kontekstu użytkownika
const userContext = {
  user_id: "user_12345",         // ID zamiast pełnych danych osobowych
  first_name: "Jan",             // Samo imię zamiast pełnego imienia i nazwiska
  viewed_categories: ["obuwie", "sport", "elektronika"],
  current_page: "Kategoria: Sport",
  preferences: {
    favorite_colors: ["niebieski", "zielony"],
    interests: ["bieganie", "rowery górskie", "fotografia"]
  },
  visit_history: {
    last_visit: "2023-09-15T14:30:00Z",
    visit_count: 12
  }
};

Aby wykorzystać kontekst przy tworzeniu nowej sesji, dołącz go do body żądania:

// Utworzenie nowej sesji z kontekstem użytkownika
fetch('https://widget-api.prosecaptain.com/api/widget/thread?token=YOUR_TOKEN_HERE', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    context: userContext
  })
})
.then(response => response.json())
.then(data => {
  console.log('Utworzono sesję:', data.session_id);
});

Prywatność danych

Nie przekazuj wrażliwych danych osobowych, takich jak pełne imię i nazwisko, adres email, numer telefonu czy adres. Używaj identyfikatorów, pseudonimów lub częściowych danych.

3.2. API Endpoints

Poniżej znajdują się wszystkie endpointy, które możesz wykorzystać do zaawansowanej integracji Prose Captain z Twoją aplikacją:

POST

Tworzenie nowego czatu

https://widget-api.prosecaptain.com/api/widget/thread?token=YOUR_TOKEN_HERE

Tworzy nowy czat i zwraca identyfikator sesji oraz historię wiadomości, zawierającą pierwszą wiadomość powitalną od asystenta.

Parametry

token (query) - Token widgetu

Odpowiedź

{
  "session_id": "session_xyz789",
  "history": [
    {
      "role": "assistant",
      "content": "Witaj! Jestem Twoim asystentem AI. W czym mogę Ci dzisiaj pomóc?"
    }
  ]
}

Widget Message Endpoint

Wysyła wiadomość użytkownika i zwraca odpowiedź od asystenta AI. Jeśli podany session_id nie istnieje, API automatycznie utworzy nową sesję i zwróci jej identyfikator w odpowiedzi wraz z pierwszą wiadomością powitalną w historii.

https://widget-api.prosecaptain.com/api/widget/message?token=YOUR_TOKEN_HERE

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

Body (JSON)

{
  "session_id": "session_xyz789",
  "message": "Twoja wiadomość tutaj"
}

Odpowiedź dla istniejącej sesji

{
  "response": "Odpowiedź asystenta na twoją wiadomość"
}

Odpowiedź dla nieistniejącej sesji

{
  "response": "Odpowiedź asystenta na twoją wiadomość",
  "session_id": "nowa_sesja_abc123",
  "history": [
    {
      "role": "assistant",
      "content": "Witaj! Jestem Twoim asystentem AI. W czym mogę Ci dzisiaj pomóc?"
    },
    {
      "role": "user",
      "content": "Twoja wiadomość tutaj"
    },
    {
      "role": "assistant",
      "content": "Odpowiedź asystenta na twoją wiadomość"
    }
  ]
}

GET

Historia czatu

https://widget-api.prosecaptain.com/api/widget/chat-history?token=YOUR_TOKEN_HERE&session_id=SESSION_ID

Pobiera historię wiadomości dla danej sesji czatu.

Parametry

token (query) - Token widgetu

session_id (query) - Identyfikator sesji

page (query, opcjonalne) - Numer strony (domyślnie 1)

limit (query, opcjonalne) - Limit wiadomości na stronę (domyślnie 50)

Odpowiedź

{
  "messages": [
    {
      "id": "msg_123abc",
      "role": "user",
      "content": "Cześć, jak się masz?",
      "timestamp": "2023-03-30T14:30:45Z"
    },
    {
      "id": "msg_456def",
      "role": "assistant",
      "content": "Dzień dobry! Mam się dobrze, dziękuję za pytanie. W czym mogę Ci dzisiaj pomóc?",
      "timestamp": "2023-03-30T14:30:50Z"
    }
  ],
  "meta": {
    "total": 2,
    "page": 1,
    "limit": 50
  }
}

GET

Informacje o przestrzeni roboczej

https://widget-api.prosecaptain.com/api/widget/workspace?token=YOUR_TOKEN_HERE

Pobiera podstawowe informacje o przestrzeni roboczej (workspace).

Parametry

token (query) - Token widgetu

Odpowiedź

{
  "name": "Nazwa workspace",
  "organisation": "Nazwa organizacji"
}

LIMITS

3.4. Ograniczenia API i obsługa błędów

Poniżej znajdują się ograniczenia API oraz typowe komunikaty błędów, które możesz napotkać podczas integracji.

Ograniczenia

Maksymalna długość wiadomości

500 znaków

Wymagania dotyczące sesji

Endpoint /message wymaga podania prawidłowego session_id. Jeśli podany session_id nie istnieje, zostanie utworzona nowa sesja.

Typowe błędy

Status	Błąd	Opis
400	Session ID is required	Brak identyfikatora sesji w żądaniu
400	Message is required	Brak treści wiadomości w żądaniu
400	Message is too long	Przekroczono maksymalną długość wiadomości (500 znaków)
404	Workspace not found	Nieprawidłowy token widgetu
429	Rate limit exceeded	Przekroczono limit zapytań
500	Server error occurred	Wewnętrzny błąd serwera

Przykład odpowiedzi z błędem

{
  "error": "Message is too long. Maximum allowed length is 500 characters."
}

3.3. Przykładowa integracja

Poniżej znajduje się przykład integracji Prose Captain z Twoją aplikacją za pomocą JavaScript, wraz z wykorzystaniem kontekstu użytkownika:

// Przykładowy kontekst użytkownika
const userContext = {
  user_id: "user_12345",
  first_name: "Jan",
  current_page: "Kategoria: Sport",
  viewed_categories: ["obuwie", "sport", "elektronika"],
  preferences: {
    interests: ["bieganie", "rowery górskie"]
  }
};

// Inicjalizacja czatu z kontekstem
const initChat = async (context = null) => {
  const options = {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    }
  };
  
  // Dodaj kontekst do body, jeśli istnieje
  if (context) {
    options.body = JSON.stringify({ context });
  }
  
  const response = await fetch('https://widget-api.prosecaptain.com/api/widget/thread?token=YOUR_TOKEN_HERE', options);
  const data = await response.json();
  return data.session_id;
};

// Wysyłanie wiadomości
const sendMessage = async (sessionId, message) => {
  const response = await fetch('https://widget-api.prosecaptain.com/api/widget/message?token=YOUR_TOKEN_HERE', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      session_id: sessionId,
      message: message
    })
  });
  return await response.json();
};

// Przykład użycia
(async () => {
  // Utworzenie nowej sesji z kontekstem użytkownika
  const sessionId = await initChat(userContext);
  console.log('Utworzono sesję z kontekstem:', sessionId);
  
  // Wysłanie wiadomości
  const response = await sendMessage(sessionId, 'Pokaż mi dostępne modele butów do biegania');
  console.log('Odpowiedź asystenta:', response.response);
})();

Wskazówka

W środowisku produkcyjnym zalecamy obsługę błędów oraz implementację mechanizmu ponownych prób w przypadku problemów z połączeniem. Kontekst użytkownika powinien być dostosowany do specyfiki Twojej aplikacji i rodzaju informacji, które mogą pomóc asystentowi lepiej odpowiadać na pytania.