# OpenAI

Integracja OpenAI z Ritevo: klucz API, model, prompt systemowy i limit tokenów, automatyczne odpowiedzi AI w wiadomościach, ponowne połączenie.

Integracja z OpenAI pozwala odpowiadać klientom w wiadomościach tekstem napisanym przez model OpenAI. Podłączasz ją własnym kluczem API z OpenAI Platform - za użycie płacisz bezpośrednio u dostawcy.

> **Wymagana integracja:** Potrzebujesz konta w OpenAI Platform z doładowanym saldem i klucza API.

Integracji OpenAI możesz dodać dowolnie wiele, także kilka z tym samym kluczem API - na przykład z innym modelem albo innym promptem systemowym dla różnych kanałów. Każda działa osobno.

Unikalność nie jest sprawdzana, celowo: każde utworzenie integracji tworzy nową, także dla tego samego `externalId`, żeby jedno konto mogło mieć kilka integracji z różnymi danymi albo ustawieniami.

Nowy klucz podasz przez `PATCH /integrations/ai/openai/{id}/token` - w każdym stanie integracji. Wysyła do dostawcy zapytanie próbne i ustawia `authError=false` i `active=true`. Błędny klucz przy tworzeniu albo zmianie klucza zwraca `INVALID_TOKEN`, inny błąd dostawcy `EXTERNAL_EXCEPTION`.

## Jak wygenerować klucz API

Klucz tworzysz w OpenAI Platform. Skopiuj go od razu - klucz jest pokazywany tylko raz.

1. Zaloguj się na platform.openai.com.
2. Przejdź do **API Keys** i kliknij **Create new secret key**.
3. Skopiuj klucz.

## Podłączenie konta

Zacznij w Ritevo:

1. Wejdź w **Integracje** w lewym panelu i kliknij **Dodaj integrację** w prawym górnym rogu.
2. W sekcji **Sztuczna inteligencja** wybierz kafelek **OpenAI**.
3. W polu **Nazwa konta** wpisz własną nazwę integracji, wklej **API Token** i wybierz **Model**.
4. W karcie **Ustawienia Zaawansowane** wpisz **Prompt systemowy** i ustaw **Maks. ilość tokenów** - opis niżej.
5. Kliknij **Utwórz integrację**. Od razu wysyłamy do OpenAI krótkie zapytanie próbne z tym kluczem i modelem: jeśli się uda, integracja zostaje dodana i otworzą się jej ustawienia. Jeśli nie - zobaczysz błąd i nic nie zostanie zapisane.

![Lista integracji w Ritevo z zaznaczonym przyciskiem Dodaj integrację w prawym górnym rogu](https://ritevo.com/docs/integrations/pl-integrations-list.webp)

![Ekran Dodaj integrację z zaznaczonym kafelkiem OpenAI w sekcji Sztuczna inteligencja](https://ritevo.com/docs/integrations/openai/pl-catalogue.webp)

![Ekran dodawania integracji OpenAI z polami Nazwa konta, API Token, Model, Prompt systemowy i Maks. ilość tokenów](https://ritevo.com/docs/integrations/openai/pl-add.webp)

## Ustawienia integracji

Na stronie integracji znajdziesz poniższe pola. Zmiany zapisujesz przyciskiem **Zaktualizuj integrację**:

- **Nazwa konta** - Twoja własna nazwa integracji. Pod nią wybierasz integrację w akcji automatycznej.
- **Model** - model OpenAI, który pisze odpowiedzi: gpt-4o, gpt-4o-mini, gpt-4-turbo, gpt-4 albo gpt-3.5-turbo.
- **Prompt systemowy** - instrukcja dla AI dołączana do każdej odpowiedzi: kim jesteś, jakim tonem odpisywać, godziny pracy, zasady zwrotów, w jakim języku odpowiadać. To jedyne miejsce, w którym przekazujesz AI wiedzę o firmie.
- **Maks. ilość tokenów** - górny limit długości odpowiedzi. Domyślnie 1000. Za niski limit utnie odpowiedź w połowie i klient dostanie ją uciętą.
- **Zaktualizuj token** - podajesz nowy klucz API.

![Szczegóły integracji OpenAI: nazwa konta, model, prompt systemowy, maks. ilość tokenów oraz przyciski Zaktualizuj token i Zaktualizuj integrację](https://ritevo.com/docs/integrations/openai/pl-details.webp)

Pola integracji: `accountName`, `apiToken` (tylko przy tworzeniu), `model` = `gpt-4o`, `gpt-4o-mini`, `gpt-4-turbo`, `gpt-4`, `gpt-3.5-turbo`, `systemPrompt` (do 10000 znaków) i `maxTokens`. Zmiana ustawień: `PUT /integrations/ai/openai/{id}` z tymi polami bez `apiToken` - zapis ustawia też `active=true`.

## Odpowiedzi AI w wiadomościach

Integracja AI działa w akcjach dla wiadomości, w kroku **Wyślij wiadomość AI do wątku**. Szczegóły kroku i gotowy przykład znajdziesz w [Akcjach dla wiadomości](https://ritevo.com/pl/docs/automations/message-actions#ai-reply-example).

- **Co dostaje AI** - treść ostatniej wiadomości w wątku oraz **Prompt systemowy**. Nie dostaje wcześniejszej historii rozmowy ani danych zamówienia.
- **Wysyłka** - odpowiedź od razu trafia do klienta, bez zatwierdzania.
- **Błąd** - gdy dostawca AI zwróci błąd, nic nie jest wysyłane, a akcja się zatrzymuje. Błąd zobaczysz w audycie wiadomości.
- **Koszty** - każda odpowiedź rozlicza się na Twoim koncie u dostawcy AI. Dodanie integracji i zmiana klucza wysyłają jedno krótkie zapytanie próbne.

> **Warto wiedzieć:** W akcji z krokiem **Wyślij wiadomość AI do wątku** ustaw warunek **Odebrano wiadomość od klienta**. AI odpowiada na ostatnią wiadomość w wątku, więc bez tego warunku mogłoby odpowiadać na własne odpowiedzi.

Akcje dla wiadomości: krok **Wyślij wiadomość AI do wątku** to `AI_SEND_MESSAGE_TO_THREAD` w `actionSteps[].action.type`, z `uuidValue` = id integracji AI (`GET /integrations/ai`). Wyzwalacz **Odpowiedź AI w wątku** to `triggerType` = `AI_MESSAGE_RESPONSE`, a warunek **Odebrano wiadomość od klienta** to `MESSAGE_FROM_INTERLOCUTOR`. Do modelu trafia tekst ostatniej wiadomości w wątku (niezależnie od autora) jako jedyna wiadomość użytkownika oraz `systemPrompt` integracji. Pełny opis: [Akcje dla wiadomości](https://ritevo.com/pl/docs/automations/message-actions).

## Wymaga ponownego połączenia

Ten stan pojawia się, gdy OpenAI odrzucił klucz API podczas pisania odpowiedzi - na przykład po jego usunięciu. Do czasu podania nowego klucza AI nie odpowie klientom.

1. Utwórz nowy klucz API w OpenAI Platform.
2. Na stronie integracji kliknij **Zaktualizuj token**, wklej klucz w polu **API Token** i zatwierdź. Sprawdzamy go krótkim zapytaniem próbnym - poprawny odświeży połączenie, a ustawienia zostają bez zmian.

![Okno Zaktualizuj token w integracji OpenAI z polem API Token](https://ritevo.com/docs/integrations/openai/pl-update-token.webp)

> **Warto wiedzieć:** Ponowne połączenie od razu zdejmuje stan **Wymaga ponownego połączenia** i włącza integrację - także wtedy, gdy wcześniej została usunięta. Nie musisz jej osobno przywracać.

W API ponowne połączenie ustawia na integracji `authError=false` i `active=true`, także gdy integracja była usunięta (`active=false`). Jaki endpoint to robi w danej integracji, opisuje notatka o unikalności na początku strony.

## Usunięcie integracji

**Usuń integrację** wyłącza integrację w Ritevo: przestaje pobierać i wysyłać dane, ale to, co pobrała wcześniej, zostaje. **Przywróć integrację** włącza ją z powrotem.

## Czego integracja nie robi

- Nie podpowiada odpowiedzi do ręcznego wstawienia - odpowiada tylko przez akcję automatyczną.
- Nie czyta historii rozmowy ani danych zamówienia.
- Nie zapisuje odpowiedzi jako szkicu do zatwierdzenia.
- Nie ogranicza wydatków - limity ustawiasz na swoim koncie u dostawcy AI.

## Integracja przez API

Endpointy tej integracji są pod `/integrations/ai/openai`, a wspólne dla całego typu (lista, pobranie jednej, usunięcie, przywrócenie) pod `/integrations/ai`. Aktualne ścieżki, pola, typy i kody odpowiedzi są zawsze w Swaggerze: https://api.ritevo.com/api/v1/api-docs.


---

Cała pomoc w jednym pliku: https://ritevo.com/llms-full.txt. Mapa pomocy z linkami do wszystkich stron: https://ritevo.com/llms.txt.