# API Agentów AI

**Agent AI** to mózg Twojego bota: jego instrukcje, osobowość, język, wiedza i narzędzia. Budujesz Agenta raz, a następnie kierujesz do niego ruch. Ten przewodnik obejmuje wszystko, co możesz zrobić z Agentem za pośrednictwem API — tworzenie, konfigurowanie, nadawanie mu wiedzy i narzędzi, przeglądanie jego wersji roboczych oraz kierowanie do niego rozmów.

- **Podstawowy adres URL** — `https://api.dmchamp.com/v1`
- **Uwierzytelnianie** — Twój klucz API (zobacz [Uwierzytelnianie](authentication.md))
- **Błędy i stronicowanie** — zobacz [Błędy i stronicowanie](errors-and-pagination.md)

Wszystkie poniższe przykłady pokazują formularz zapytania `?apiKey=` w cURL oraz nagłówek `X-API-Key` w JavaScript i Pythonie — oba działają w każdym punkcie końcowym.

Jeśli koncepcja Agentów jest dla Ciebie nowa, najpierw przeczytaj [Agenci AI](../ai-agents/ai-agents.md).

::: master-only
> **Agencje:** każdy punkt końcowy na tej stronie akceptuje `sub_account_id`, dzięki czemu możesz budować i konfigurować Agenta klienta za pomocą swojego klucza agencji. Wyślij go jako parametr zapytania. Zobacz [API dla agencji](../agency/api-for-agencies.md).
:::

---

## Jak zbudowany jest Agent

Cztery elementy są zarządzane oddzielnie i warto wiedzieć, który jest który, zanim zaczniesz:

| Element | Czym jest | Gdzie go ustawić |
|---|---|---|
| **Konfiguracja** | Instrukcje, zasady, cel, osobowość, język, poziom AI, zachowanie podczas rezerwacji i działań następczych | `PUT /agents/{agentId}` lub węższy `PUT /agents/{agentId}/bot-config` |
| **Wiedza** | FAQ i źródła wiedzy (strony i dokumenty, które platforma przeczytała za Ciebie) | [API FAQ](faqs.md) oraz `POST /agents/{agentId}/kb-sources` |
| **Narzędzia** | Niestandardowe funkcje i serwery MCP, które Agent może wywołać w trakcie rozmowy | `POST /agents/{agentId}/custom-functions` oraz `POST /agents/{agentId}/mcp-servers` |
| **Routing** | Które kanały i rozmowy faktycznie docierają do tego Agenta | Punkty wejścia — `PUT /entry-points/channel-defaults` oraz `POST /agents/{agentId}/entry-points` |

> **Nowy Agent nikomu nie odpowiada, dopóki nie skierujesz do niego ruchu.** Utworzenie Agenta nie umieszcza go na żadnym kanale. To krok, który pomija większość integracji — zobacz [Kierowanie rozmów do Agenta](#routing-conversations-to-an-agent) na końcu tej strony.

---

## Obiekt Agent

Pełny dokument Agenta jest duży — zajmuje kilkaset kilobajtów, głównie ze względu na listę FAQ, źródła wiedzy i treść stron przeczytanych z Twojej witryny. Z tego powodu lista zwraca krótki **wiersz podsumowania** dla każdego Agenta, gdy o to poprosisz:

```json
{
  "id": "ag7HkQ2ZpLxR3mNb",
  "name": "Listing assistant",
  "active": true,
  "language": "en",
  "goal": "Book a viewing",
  "tags": [],
  "anthropic_model": "standard",
  "ai_speed": "balanced",
  "enable_bookings": false,
  "enable_follow_ups": true,
  "faq_refs_count": 42,
  "kb_source_refs_count": 3,
  "created_at": 1700000000000,
  "last_modified_at": 1700000000000
}
```

| Pole | Typ | Opis |
|---|---|---|
| `id` | string | Unikalny identyfikator Agenta. |
| `name` | string \| null | Nazwa Agenta, widoczna w panelu nawigacyjnym. |
| `active` | boolean \| null | Czy Agent ma obecnie uprawnienia do odpowiadania. |
| `language` | string \| null | Język, w którym odpowiada Agent. |
| `goal` | string \| null | Cel pracy Agenta, skrócony do pierwszych 200 znaków (wielokropek na końcu oznacza skrócenie). |
| `tags` | array \| null | Zasady tagowania Agenta. |
| `anthropic_model` | string \| null | Poziom jakości AI: `standard`, `economy`, `max` lub `mini`. |
| `ai_speed` | string \| null | Poziom rozumowania stosowany przez Agenta przed udzieleniem odpowiedzi: `fast`, `fast_thinker`, `balanced` lub `thorough`. |
| `enable_bookings` | boolean \| null | Czy Agent może dokonywać rezerwacji spotkań. |
| `enable_follow_ups` | boolean \| null | Czy Agent wysyła wiadomości następcze. |
| `faq_refs_count` | integer | Liczba FAQ w bazie wiedzy tego Agenta. |
| `kb_source_refs_count` | integer | Liczba źródeł wiedzy powiązanych z Agentem. |
| `created_at` | integer \| null | Czas utworzenia, milisekundy epoki. |
| `last_modified_at` | integer \| null | Ostatnia zmiana, milisekundy epoki. |

Pełny dokument dodaje wszystko inne: `instructions`, `rules`, `personality`, `availability`, `follow_up_config`, listy powiązanych FAQ i źródeł wiedzy, wygenerowane bloki tekstu oraz wszelkie stany uruchomienia (`tag_generation`, `optimize_run`).

> Niektóre odpowiedzi zawierają również `substrate_campaign_id`. Jest to wewnętrzny rekord przechowywany na starszych kontach; nigdy nie musisz na nim polegać, a na nowszych kontach jest on `null` lub nieobecny.

---

## Lista Agentów

`GET /agents` — każdy Agent na koncie, najnowsze jako pierwsze.

Ten punkt końcowy **nie jest stronicowany**. Domyślnie każdy Agent jest zwracany z pełną konfiguracją, co jest obciążające: pojedynczy Agent może zajmować 580 KB, a konto z 64 Agentami ponad 3 MB. Przekaż `view=summary`, aby uzyskać krótki wiersz dla każdego Agenta, a następnie odczytaj wybrany przez siebie za pomocą [Pobierz Agenta](#get-an-agent).

**Parametry zapytania**

| Parametr | Opis |
|---|---|
| `view` | Ustaw na `summary`, aby uzyskać krótkie wiersze. Każda inna wartość zwraca `400`. Pomiń, aby uzyskać pełne dokumenty. |
| `fields` | Ma zastosowanie tylko razem z `view=summary`. Rozdzielona przecinkami lista kluczy podsumowania do zachowania, na przykład `id,name,active`. `id` jest zawsze uwzględniany; nieznane nazwy są ignorowane. |

**cURL**

```bash
curl "https://api.dmchamp.com/v1/agents?apiKey=YOUR_API_KEY&view=summary&fields=id,name,active"
```

**JavaScript**

```javascript
const res = await fetch("https://api.dmchamp.com/v1/agents?view=summary", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const { agents } = await res.json();
```

**Python**

```python
import requests

res = requests.get(
    "https://api.dmchamp.com/v1/agents",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"view": "summary"},
)
agents = res.json()["agents"]
```

**Odpowiedź** (`200`)

```json
{
  "success": true,
  "agents": [
    { "id": "ag7HkQ2ZpLxR3mNb", "name": "Listing assistant", "active": true }
  ]
}
```

---

## Utwórz Agenta

`POST /agents` — tylko `name` jest naprawdę wymagane; wyślij wraz z nim każdą konfigurację, którą już znasz. Nowy Agent jest domyślnie aktywny.

**Pola żądania** (wszystkie opcjonalne z wyjątkiem `name`)

| Pole | Typ | Opis |
|---|---|---|
| `name` | string | Nazwa Agenta. |
| `active` | boolean | Czy może odpowiadać od razu. Domyślnie `true`. |
| `language` | string | Język, w którym odpowiada Agent. |
| `instructions` | string | Główne instrukcje, które kierują sposobem rozmowy z kontaktami. |
| `rules` | string | Sztywne zasady, których musi zawsze przestrzegać. |
| `goal` | string | Wynik, do którego powinien dążyć. |
| `personality` | string | Ton głosu i osobowość. |
| `availability` | object | Godziny aktywności w poszczególne dni tygodnia — zobacz [Ustaw godziny aktywności](#set-active-hours). |
| `ai_speed` | string | `fast`, `fast_thinker`, `balanced` lub `thorough`. |
| `anthropic_model` | string | `standard`, `economy`, `max` lub `mini`. |
| `scrape_urls` | string[] | Strony do odczytania, na podstawie których zostaną zbudowane instrukcje Agenta. |

**Budowanie Agenta na podstawie Twojej witryny.** Dołącz `scrape_urls`, a platforma odczyta te strony i napisze instrukcje za Ciebie. Odpowiedź informuje, czy generowanie się rozpoczęło, dzięki czemu wiesz, czy odpytywać Agenta o postępy.

**cURL**

```bash
curl -X POST "https://api.dmchamp.com/v1/agents?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Listing assistant",
    "language": "en",
    "instructions": "Answer questions about our listings and book viewings.",
    "goal": "Book a viewing"
  }'
```

**JavaScript**

```javascript
const res = await fetch("https://api.dmchamp.com/v1/agents", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({
    name: "Listing assistant",
    scrape_urls: ["https://example.com", "https://example.com/faq"],
  }),
});
const data = await res.json();
console.log(data.agent_id);
```

**Python**

```python
res = requests.post(
    "https://api.dmchamp.com/v1/agents",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"name": "Listing assistant", "scrape_urls": ["https://example.com"]},
)
print(res.json()["agent_id"])
```

**Odpowiedź** (`201`)

```json
{
  "success": true,
  "agent_id": "ag7HkQ2ZpLxR3mNb",
  "substrate_campaign_id": null,
  "agent_generation_queued": true
}
```

`agent_generation_queued` to `true`, gdy platforma rozpoczęła pisanie instrukcji na podstawie dostarczonych stron.

Kod `400` oznacza, że treść nie była obiektem JSON, pole zostało odrzucone lub Agent przekracza rozmiar konfiguracji dozwolony w Twoim planie. Kod `403` oznacza, że konto nie ma uprawnień do korzystania z jednego z wysłanych ustawień — na przykład poziomu AI, którego nie przyznał dostawca konta.

---

## Pobierz Agenta

`GET /agents/{agentId}`

Przekaż `fields` z rozdzieloną przecinkami listą, aby otrzymać tylko to, czego potrzebujesz, na przykład `fields=name,active,goal`. Pole `id` jest zawsze uwzględniane, a nazwy, które nie istnieją w Agencie, są ignorowane, a nie odrzucane. Pomiń to, aby otrzymać cały dokument.

**cURL**

```bash
curl "https://api.dmchamp.com/v1/agents/ag7HkQ2ZpLxR3mNb?apiKey=YOUR_API_KEY&fields=name,active,goal"
```

**JavaScript**

```javascript
const res = await fetch("https://api.dmchamp.com/v1/agents/ag7HkQ2ZpLxR3mNb?fields=name,active", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const { agent } = await res.json();
```

**Python**

```python
res = requests.get(
    "https://api.dmchamp.com/v1/agents/ag7HkQ2ZpLxR3mNb",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"fields": "name,active"},
)
agent = res.json()["agent"]
```

Agent, który nie istnieje na Twoim koncie, zwraca `404`.

---

## Zaktualizuj Agenta

`PUT /agents/{agentId}` — wyślij tylko te pola, które chcesz zmienić; wszystko inne pozostaje bez zmian.

Zagnieżdżone ustawienia można modyfikować pojedynczo za pomocą klucza z kropką, więc `"availability.monday"` zmienia tylko poniedziałek, pozostawiając resztę tygodnia bez zmian.

**Uwagi**

- Aby zmienić typ wydarzenia z możliwością rezerwacji, do którego Agent dokonuje rezerwacji, wyślij `event_id` (identyfikator wydarzenia lub `null`, aby go wyczyścić). Wyślij `event_ids` z tablicą, aby powiązać kilka naraz — pierwszy z nich stanie się głównym, a `[]` odłączy wszystko. `event_id` i `event_ids` wykluczają się wzajemnie, a pola `event` nie można zapisać bezpośrednio.
- `enable_bookings` musi być wartością logiczną (boolean), a `booking_provider` musi być jedną z `default`, `zenchef`, `formitable`, `opentable`, `thefork`.
- Pola własności i tożsamości są ignorowane, podobnie jak wewnętrzny stan uruchomienia (postęp generowania i optymalizacji).
- **Routing nie jest tutaj ustawiany.** Użyj `PUT /entry-points/channel-defaults`, aby uczynić Agenta osobą odpowiadającą za kanał, `POST /agents/{agentId}/entry-points` dla reguł słów kluczowych i komentarzy oraz `PATCH /agents/{agentId}/active`, aby wstrzymać lub wznowić jego działanie.

**cURL**

```bash
curl -X PUT "https://api.dmchamp.com/v1/agents/ag7HkQ2ZpLxR3mNb?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instructions": "Answer questions about our listings and always offer a viewing.",
    "anthropic_model": "standard"
  }'
```

**JavaScript**

```javascript
await fetch("https://api.dmchamp.com/v1/agents/ag7HkQ2ZpLxR3mNb", {
  method: "PUT",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ "availability.monday": { start_time: "09:00", end_time: "17:00" } }),
});
```

**Python**

```python
requests.put(
    "https://api.dmchamp.com/v1/agents/ag7HkQ2ZpLxR3mNb",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"goal": "Book a viewing within three messages"},
)
```

**Odpowiedź** (`200`)

```json
{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb" }
```

Puste ciało żądania zwraca `400` z `"No fields to update"`.

---

## Aktualizacja ustawień bota

`PUT /agents/{agentId}/bot-config` — zawężony sposób zmiany tylko ustawień konwersacji.

Agent nie posiada oddzielnej sekcji bota: jego ustawienia znajdują się bezpośrednio w obiekcie Agenta, więc nazwy pól są tutaj takie same, jak te, które wysłałbyś do `PUT /agents/{agentId}`. Ten punkt końcowy istnieje jako bezpieczny, ukierunkowany sposób na zmianę kilku z nich. Wymagane jest co najmniej jedno pole.

| Pole | Opis |
|---|---|
| `instructions` | Główne instrukcje, które kierują sposobem rozmowy Agenta z kontaktami. |
| `rules` | Sztywne zasady, których musi zawsze przestrzegać. |
| `goal` | Wynik, do którego powinien dążyć w każdej konwersacji. |
| `personality` | Opis tonu głosu i osobowości. |
| `language` | Język, w którym Agent odpowiada. |
| `ai_speed` | `fast`, `fast_thinker`, `balanced` lub `thorough`. |
| `anthropic_model` | `standard`, `economy`, `max` lub `mini`. |
| `max_messages` | Maksymalna liczba wiadomości Agenta w konwersacji. |
| `alert_human_when` | Kiedy Agent powinien powiadomić członka zespołu. |
| `ai_transparency` | Czy Agent ujawnia, że jest sztuczną inteligencją. |

> **Nazwy pól muszą być tutaj prostymi nazwami** — litery, cyfry, podkreślniki i myślniki. Ścieżki z kropkami nie są akceptowane w tym punkcie końcowym (w przeciwieństwie do `PUT /agents/{agentId}`), więc `bot.goal` zostanie odrzucone z `400`.

```bash
curl -X PUT "https://api.dmchamp.com/v1/agents/ag7HkQ2ZpLxR3mNb/bot-config?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "goal": "Book a viewing within three messages", "ai_speed": "thorough" }'
```

Długi tekst wpływa na rozmiar konfiguracji dozwolony w Twoim planie, więc bardzo duży zestaw instrukcji może zostać odrzucony z `400`.

---

## Ustawianie godzin aktywności

`PUT /agents/{agentId}/active-hours` — godziny, w których Agent odpowiada automatycznie. Poza tymi oknami pozostaje nieaktywny.

Wyślij obiekt `availability` z kluczami odpowiadającymi dniom tygodnia (`monday` do `sunday`). Każdy dzień przyjmuje pojedyncze okno czasowe lub listę okien w formacie 24-godzinnym `HH:MM`. Dni, które pominiesz, zachowają poprzednie ustawienia, a każdy klucz, który nie jest dniem tygodnia, zostanie odrzucony — dzięki temu literówka nie spowoduje cichego braku działania.

```bash
curl -X PUT "https://api.dmchamp.com/v1/agents/ag7HkQ2ZpLxR3mNb/active-hours?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "availability": {
      "monday": { "start_time": "09:00", "end_time": "17:00" },
      "tuesday": [
        { "start_time": "09:00", "end_time": "12:00" },
        { "start_time": "13:00", "end_time": "17:00" }
      ]
    }
  }'
```

**Odpowiedź** (`200`)

```json
{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb" }
```

Błędny klucz dnia tygodnia zwraca `400`: `"Invalid availability keys: funday. Allowed keys: monday through sunday."`

---

## Wstrzymywanie lub wznawianie Agenta

`PATCH /agents/{agentId}/active` — włącza lub wyłącza Agenta. Wstrzymany Agent zachowuje całą swoją konfigurację, ale natychmiast przestaje odpowiadać; wznowienie działania następuje od razu.

```bash
curl -X PATCH "https://api.dmchamp.com/v1/agents/ag7HkQ2ZpLxR3mNb/active?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "active": false }'
```

```javascript
await fetch("https://api.dmchamp.com/v1/agents/ag7HkQ2ZpLxR3mNb/active", {
  method: "PATCH",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ active: false }),
});
```

**Odpowiedź** (`200`)

```json
{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb", "active": false }
```

`active` musi być wartością logiczną (boolean) — każda inna wartość spowoduje zwrócenie `400` wraz z `"active (boolean) is required"`.

---

## Powielanie Agenta

`POST /agents/{agentId}/duplicate` — tworzy kopię z zachowaniem konfiguracji. Kopia nie wysyła żadnych danych, dopóki nie zostanie do niej przypisany kanał lub punkt wejścia (Entry Point).

```bash
curl -X POST "https://api.dmchamp.com/v1/agents/ag7HkQ2ZpLxR3mNb/duplicate?apiKey=YOUR_API_KEY"
```

**Odpowiedź** (`201`)

```json
{ "success": true, "agent_id": "ag9WsX3cRfV6tGyH", "source_agent_id": "ag7HkQ2ZpLxR3mNb" }
```

Duplikat wlicza się do limitu Agentów w Twoim planie dokładnie tak samo, jak utworzenie nowego od podstaw, dlatego operacja zostanie odrzucona z komunikatem `403`, jeśli konto osiągnęło swój limit.

---

## Skopiuj Agenta do subkonta (agencje)

`POST /subaccounts/agents/copy` — kopiuje Agenta z Twojego konta agencji (lub jednego z Twoich subkont) do innego subkonta, wykonując głęboką kopię wszystkich zależności, dzięki czemu kopia działa samodzielnie na koncie docelowym. Jest to wywołanie dla głównego Agenta, od którego chcesz, aby każdy nowy klient rozpoczynał pracę. Zastępuje ono przestarzałe `POST /subaccounts/campaigns/copy`.

Ten punkt końcowy sam wskazuje oba konta, więc nie przyjmuje `sub_account_id`. Wymaga klucza API agencji z uprawnieniami do edycji w obszarze zarządzania zespołem.

| Pole | Wymagane | Opis |
|---|---|---|
| `agentId` | Tak | Agent do skopiowania. Musi należeć do Twojego konta agencji lub jednego z Twoich subkont. |
| `targetUserId` | Tak | Subkonto, do którego ma zostać skopiowany. |
| `newName` | Nie | Nazwa kopii. Domyślnie przyjmuje nazwę źródłowego Agenta. |
| `copyFaqs` | Nie | Skopiuj również FAQ i źródła bazy wiedzy. Domyślnie `true`. |
| `copyCustomFunctions` | Nie | Skopiuj również funkcje niestandardowe i serwery MCP. Domyślnie `false`. |

Biblioteka mediów jest zawsze kopiowana. Kontakty konta źródłowego, szablony WhatsApp oraz połączone posty w mediach społecznościowych nigdy nie są kopiowane.

```bash
curl -X POST "https://api.dmchamp.com/v1/subaccounts/agents/copy" \
  -H "X-API-Key: YOUR_AGENCY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "ag7HkQ2ZpLxR3mNb",
    "targetUserId": "abc123def456",
    "newName": "Inbound Instagram Leads",
    "copyFaqs": true
  }'
```

**Odpowiedź** (`200`)

```json
{
  "success": true,
  "data": {
    "agent_id": "ag9WsX3cRfV6tGyH",
    "shell_campaign_id": null,
    "message": "Agent copied successfully",
    "counts": { "agents": 1, "faqs": 12, "kbSources": 2, "customFunctions": 0, "mcpServers": 0, "mediaItems": 3 }
  }
}
```

`data.agent_id` to nowy Agent na koncie docelowym. Kopia dociera w stanie **wstrzymanym** (`active: false`) i bez routingu, więc nie może nikomu odpowiedzieć, dopóki nie wznowisz jej za pomocą [`PATCH /agents/{agentId}/active`](#pause-or-resume-an-agent) i nie skierujesz na nią kanałów klienta za pomocą [`PUT /entry-points/channel-defaults`](entry-points.md#point-a-channel-at-an-agent). Strona [API dla agencji](../agency/api-for-agencies.md#worked-example-ship-a-template-agent-into-every-new-client) przeprowadzi Cię przez wszystkie trzy wywołania. Jeśli cokolwiek nie powiedzie się w trakcie, wszystko, co zostało już utworzone na koncie docelowym, zostanie wycofane.

| Status | Kiedy |
|---|---|
| `400` | Brak `agentId` lub `targetUserId`. |
| `403` | Klucz nie należy do agencji lub konto docelowe nie jest jednym z jej subkont. |
| `404` | Agent nie istnieje lub należy do konta spoza Twojej agencji. |

---

## Usuwanie Agenta

`DELETE /agents/{agentId}`

Usunięcie zostało odrzucone, ponieważ Agent jest nadal powiązany z elementem, który przestałby działać bez niego — transmisją, punktem wejścia (Entry Point) lub (w starszych kontach) kampanią. Odpowiedź zawiera listę elementów blokujących, dzięki czemu można je najpierw odłączyć i spróbować ponownie.

```bash
curl -X DELETE "https://api.dmchamp.com/v1/agents/ag7HkQ2ZpLxR3mNb?apiKey=YOUR_API_KEY"
```

**Odpowiedź** (`200`)

```json
{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb" }
```

**Zablokowano** (`409`)

```json
{
  "success": false,
  "error": "Agent is still attached to one or more broadcast(s). Detach it first.",
  "blocking_campaign_ids": [],
  "blocking_broadcast_ids": ["bc5TgYhUj8IkOlPm"],
  "blocking_entry_point_ids": []
}
```

---

## Wersje robocze: przeglądaj zmiany przed ich opublikowaniem

Edycje wprowadzone w edytorze oraz wszelkie poprawki wygenerowane przez [Optymalizację z AI](#optimize-an-agent-with-ai) są przechowywane jako **nieopublikowana wersja robocza** do momentu ich opublikowania. Do tego czasu aktywny Agent nadal odpowiada zgodnie z bieżącą konfiguracją.

### Opublikuj wersję roboczą

`POST /agents/{agentId}/publish-draft` — przenosi wersję roboczą do aktywnej konfiguracji i jednocześnie usuwa wersję roboczą.

```bash
curl -X POST "https://api.dmchamp.com/v1/agents/ag7HkQ2ZpLxR3mNb/publish-draft?apiKey=YOUR_API_KEY"
```

**Odpowiedź** (`200`)

```json
{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb", "published_keys": ["instructions", "goal"] }
```

`published_keys` wyświetla listę ustawień, które zostały przeniesione z wersji roboczej do aktywnego Agenta, dzięki czemu można sprawdzić, co uległo zmianie.

> **Przed wywołaniem tej funkcji sprawdź, czy istnieje wersja robocza.** Publikowanie Agenta, który nie posiada wersji roboczej, nie jest obsługiwanym wywołaniem i obecnie zwraca `500` z ogólnym komunikatem, a nie szczegółowym. Aby zamiast tego odrzucić wersję roboczą, użyj poniższej funkcji odrzucania (discard).

### Odrzuć wersję roboczą

`POST /agents/{agentId}/discard-draft` — odrzuca wersję roboczą i pozostawia bieżącą konfigurację bez zmian. Można bezpiecznie wywołać, gdy nie ma wersji roboczej; nic się nie stanie.

```bash
curl -X POST "https://api.dmchamp.com/v1/agents/ag7HkQ2ZpLxR3mNb/discard-draft?apiKey=YOUR_API_KEY"
```

---

## Optymalizacja Agenta za pomocą AI

`POST /agents/{agentId}/optimize` — przepisuje konfigurację Agenta na podstawie Twoich opinii („nadal oferuje zniżki”, „odpowiedzi są zbyt długie”) i zapisuje poprawioną wersję **jako wersję roboczą**, zamiast od razu ją publikować.

Wyślij `user_feedback` (zwykłą instrukcję) lub, w przypadku reakcji na konkretną błędną odpowiedź, `thumbs_down_feedback` wraz z błędną `thumbs_down_message`. Przynajmniej jeden z tych dwóch elementów musi zawierać tekst.

```bash
curl -X POST "https://api.dmchamp.com/v1/agents/ag7HkQ2ZpLxR3mNb/optimize?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "user_feedback": "Keep replies under three sentences." }'
```

**Odpowiedź** (`202`)

```json
{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb" }
```

Praca wykonywana jest w tle, a wywołanie zwraca wynik natychmiast. Odczytaj Agenta za pomocą `GET /agents/{agentId}` i obserwuj `optimize_run.status`; gdy status zmieni się na `Draft`, poprawiona wersja będzie czekać jako wersja robocza Agenta. Przejrzyj ją, a następnie opublikuj lub odrzuć.

Tylko jedno zadanie na raz dla każdego Agenta — drugie wywołanie w trakcie trwania pierwszego zwróci `409`. To zużywa kredyty AI.

---

## Reguły tagowania

Reguła tagowania to tag oraz opis sytuacji, w której ma on zastosowanie. Podczas rozmowy Agent czyta ten opis i taguje kontakt, gdy sytuacja do niego pasuje; w ten sposób uruchamiane są automatyzacje oparte na tagach.

**Obiekt reguły**

| Pole | Wymagane | Opis |
|---|---|---|
| `name` | Tak | Tag do zastosowania, na przykład `hot-lead`. |
| `description` | Nie | Kiedy Agent powinien go zastosować, zapisane jako instrukcja, której ma przestrzegać. |
| `webhook` | Nie | Adres URL wywoływany, gdy Agent zastosuje ten tag. |
| `ai_can_remove` | Nie | Czy Agent może również usunąć tag. Domyślnie `false`. |
| `tag_id` | Nie | Identyfikator istniejącego tagu na Twoim koncie, z którym ma zostać powiązana reguła. Bez niego reguła łączy się z tagiem o tej samej nazwie, tworząc go, jeśli nie istnieje — dzięki temu każdą regułę można później zaadresować za pomocą identyfikatora tagu. |

### Dodaj regułę tagowania

`POST /agents/{agentId}/tags`

```bash
curl -X POST "https://api.dmchamp.com/v1/agents/ag7HkQ2ZpLxR3mNb/tags?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tag": {
      "name": "hot-lead",
      "description": "Apply when the contact asks about pricing or wants to book a call.",
      "ai_can_remove": false
    }
  }'
```

**Odpowiedź** (`200`)

```json
{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb", "tag": { "name": "hot-lead", "...": "..." } }
```

### Zastąp regułę tagowania

`PUT /agents/{agentId}/tags/{tagId}` — reguła jest wyszukiwana według identyfikatora tagu w ścieżce i **zastępowana w całości**, a nie scalana, dlatego należy przesłać pełną regułę, a nie tylko zmienianą część. Tag, na który wskazuje, jest zachowywany nawet w przypadku pominięcia `tag_id`, więc edycja nie może odłączyć reguły od jej tagu.

```bash
curl -X PUT "https://api.dmchamp.com/v1/agents/ag7HkQ2ZpLxR3mNb/tags/tg8YuIoP2aSdF3gH?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "tag": { "name": "hot-lead", "description": "Apply only when the contact asks to book a call." } }'
```

### Usuwanie reguły tagowania

`DELETE /agents/{agentId}/tags/{tagId}` — Agent przestaje stosować dany tag. Sam tag oraz wszyscy kontakty, którzy już go posiadają, pozostają nienaruszeni.

```bash
curl -X DELETE "https://api.dmchamp.com/v1/agents/ag7HkQ2ZpLxR3mNb/tags/tg8YuIoP2aSdF3gH?apiKey=YOUR_API_KEY"
```

Oba punkty końcowe zwracają `404`, gdy Agent nie istnieje **lub** gdy nie posiada reguły dla danego tagu.

### Generowanie zestawu tagów za pomocą AI

`POST /agents/{agentId}/tags/generate` — projektuje cały zestaw reguł (nazwy tagów oraz sformułowania „zastosuj, gdy…” dla każdej z nich) poprzez odczytanie instrukcji i celu samego Agenta.

| Pole | Opis |
|---|---|
| `mode` | `merge` (wartość domyślna) zachowuje reguły już przypisane do Agenta i dodaje do nich nowe. `replace` projektuje zestaw od podstaw. |

```bash
curl -X POST "https://api.dmchamp.com/v1/agents/ag7HkQ2ZpLxR3mNb/tags/generate?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "mode": "merge" }'
```

**Odpowiedź** (`202`)

```json
{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb", "mode": "merge" }
```

Praca wykonywana jest w tle. Przeczytaj dokumentację Agenta i obserwuj `tag_generation.status`; same reguły trafiają do `tags` Agenta. Na jednego Agenta przypada tylko jedno uruchomienie w danym momencie (w przeciwnym razie `409`) i zużywa ono kredyty AI.

---

## Źródła wiedzy

Źródła wiedzy to strony i dokumenty, które platforma przeczytała dla Ciebie. Dołączenie źródła do Agenta pozwala mu odpowiadać na podstawie tej zawartości.

**Skąd pochodzą identyfikatory źródeł.** Dodaj zawartość za pomocą punktów końcowych bazy wiedzy — `POST /kb-sources/url` dla strony, `POST /kb-sources/file` dla dokumentu, `POST /kb-sources/bulk-import` dla całej witryny. Zwracają one `source_id`, który należy odpytywać za pomocą `GET /kb-sources/{sourceId}`, aż będzie gotowy. `POST /kb-sources/url` przyjmuje również `autoLinkToAgentId`, co dołącza źródło do Agenta natychmiast po zakończeniu importu, dzięki czemu można pominąć poniższe wywołanie dołączenia.

### Dołączanie źródeł wiedzy

`POST /agents/{agentId}/kb-sources` — wyślij `kb_source_ids` z listą, aby dołączyć cały zestaw w jednym wywołaniu (co jest przydatne po zaindeksowaniu witryny), lub `kb_source_id` dla pojedynczego źródła. Wyślij jedno lub drugie. Dołączenie czegoś, co jest już dołączone, nic nie zmienia.

```bash
curl -X POST "https://api.dmchamp.com/v1/agents/ag7HkQ2ZpLxR3mNb/kb-sources?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "kb_source_ids": ["kb2QwErTyUi9OpAs", "kb6ZxCvBnM4kLjHg"] }'
```

**Odpowiedź** (`200`)

```json
{
  "success": true,
  "agent_id": "ag7HkQ2ZpLxR3mNb",
  "kb_source_id": "kb2QwErTyUi9OpAs",
  "kb_source_ids": ["kb2QwErTyUi9OpAs", "kb6ZxCvBnM4kLjHg"]
}
```

### Odłączanie źródeł wiedzy

`DELETE /agents/{agentId}/kb-sources/{kbSourceId}` dla jednego lub `POST /agents/{agentId}/kb-sources/bulk-remove` z `kb_source_ids` dla kilku. Masowe usuwanie to `POST`, ponieważ lista identyfikatorów jest przesyłana w treści żądania.

```bash
curl -X POST "https://api.dmchamp.com/v1/agents/ag7HkQ2ZpLxR3mNb/kb-sources/bulk-remove?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "kb_source_ids": ["kb2QwErTyUi9OpAs"] }'
```

Same źródła nie są usuwane i pozostają dostępne dla innych Twoich Agentów. Odłączenie czegoś, co nie jest podłączone, niczego nie zmienia.

### FAQ

FAQ są zarządzane we własnych punktach końcowych i stamtąd przypisywane do Agenta: `POST /faqs/{faqId}/link` za pomocą `{ "agent_id": "ag7HkQ2ZpLxR3mNb" }`, a `POST /faqs/{faqId}/unlink`, aby je usunąć. FAQ może być współdzielone przez dowolną liczbę Agentów. Zobacz [API FAQ](faqs.md).

> FAQ jest używane tylko przez Agentów, do których jest przypisane — samo utworzenie go nie wystarczy.

---

## Narzędzia

### Funkcje niestandardowe

`POST /agents/{agentId}/custom-functions` pozwala Agentowi wywoływać jedną z Twoich funkcji niestandardowych podczas rozmów. Można dołączać tylko funkcje należące do tego samego konta, a dołączenie funkcji, która jest już dołączona, niczego nie zmienia.

```bash
curl -X POST "https://api.dmchamp.com/v1/agents/ag7HkQ2ZpLxR3mNb/custom-functions?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "custom_function_id": "cf7Hk2ZpLxR3mNbV" }'
```

`DELETE /agents/{agentId}/custom-functions/{customFunctionId}` odłącza ją. Sama funkcja nie jest usuwana i pozostaje dostępna dla innych Twoich Agentów.

Zarządzaj samymi funkcjami w `/custom-functions` — zobacz [Funkcje niestandardowe](../ai-automation/custom-functions.md), aby dowiedzieć się, czym są.

### Serwery MCP

Serwer MCP to gotowy pakiet narzędzi, które Twój Agent może samodzielnie wykryć i wywołać — zobacz [Podłączanie serwerów MCP do Twojego bota](../ai-automation/mcp-servers.md). Serwery są rejestrowane raz na koncie, a następnie przypisywane do Agentów, którzy mają z nich korzystać.

> Serwery MCP wymagają funkcji **funkcji niestandardowych** w Twoim planie. Bez niej punkty końcowe `/mcp-servers` na poziomie konta zwracają `403`. Przypisywanie już zarejestrowanego serwera do Agenta nie jest ograniczone.

#### Rejestracja serwera

`POST /mcp-servers`

| Pole | Wymagane | Opis |
|---|---|---|
| `name` | Tak | Etykieta serwera. |
| `url` | Tak | Adres serwera. Musi być osiągalny przez publiczny internet. |
| `auth_type` | Nie | `header` (domyślnie) dla statycznego nagłówka autoryzacji lub `oauth2`. |
| `auth_header_name` | Nie | Nagłówek, w którym przesyłane są dane uwierzytelniające. Domyślnie `Authorization`. |
| `auth_header_value` | Nie | Same dane uwierzytelniające. Nigdy nie są zwracane w żadnej odpowiedzi. |
| `enabled` | Nie | Czy serwer jest dostępny dla Agentów. Domyślnie `true`. |
| `enabled_tools` | Nie | Lista dozwolonych nazw narzędzi. `null` oznacza, że każde narzędzie oferowane przez serwer jest włączone. |
| `tool_policies` | Nie | Limity dla poszczególnych narzędzi, kluczowane nazwą narzędzia — jak często narzędzie może być wywoływane, buforowanie wyników i nadpisanie tylko do odczytu. Przekaż `null`, aby wyczyścić je wszystkie. |

```bash
curl -X POST "https://api.dmchamp.com/v1/mcp-servers?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Inventory",
    "url": "https://tools.example.com/mcp",
    "auth_header_value": "Bearer sk_live_xxx"
  }'
```

**Odpowiedź** (`201`)

```json
{
  "success": true,
  "server_id": "ms4TgBnH7yUj2kLp",
  "tools": [{ "name": "check_stock", "description": "Look up stock for a SKU." }],
  "last_error": null,
  "server": { "server_id": "ms4TgBnH7yUj2kLp", "name": "Inventory", "...": "..." }
}
```

Podczas zapisu platforma łączy się z serwerem i buforuje listę oferowanych przez niego narzędzi. **Serwer, którego nie można osiągnąć, nadal zostanie zapisany**, z przyczyną w `last_error` i pustą listą narzędzi — dzięki temu możesz najpierw zarejestrować serwer, a później naprawić połączenie.

`auth_type` o wartości `oauth2` zapisuje rejestrację z `oauth_connected: false` i bez narzędzi: token jeszcze nie istnieje. Autoryzacja serwera OAuth wymaga logowania przez przeglądarkę i odbywa się z poziomu pulpitu nawigacyjnego, a nie przez API.

#### Wyświetlanie, aktualizacja i usuwanie serwerów

- `GET /mcp-servers` — każdy zarejestrowany serwer, od najnowszego, w `servers`.
- `PUT /mcp-servers/{serverId}` — wyślij tylko to, co chcesz zmienić. Zmiana adresu URL lub pól autoryzacji powoduje ponowne przetestowanie połączenia i odświeżenie buforowanej listy narzędzi.
- `DELETE /mcp-servers/{serverId}` — usuwa rejestrację i odłącza ją od każdego Agenta i kampanii, w których była włączona.

```bash
curl "https://api.dmchamp.com/v1/mcp-servers?apiKey=YOUR_API_KEY"
```

**Sekrety nigdy nie wracają.** Odpowiedzi zawierają `auth_header_value_set` (flagę `true`/`false` informującą, że wartość jest zapisana) zamiast danych uwierzytelniających, a tokeny OAuth i sekrety klienta pozostają po stronie serwera. Wszystko inne jest zwracane: `name`, `url`, `enabled`, `auth_type`, `auth_header_name`, `tools`, `enabled_tools`, `tool_policies`, `oauth_connected`, `tools_cached_at`, `last_connected_at`, `last_error`, `created_at`, `updated_at`.

#### Testowanie połączenia

`POST /mcp-servers/test-connection` — łączy się z serwerem i wyświetla listę jego narzędzi. Można go wywołać na dwa sposoby:

- za pomocą `server_id` — testuje **zapisaną** konfigurację i odświeża listę narzędzi w pamięci podręcznej;
- za pomocą wbudowanego `url` (oraz `auth_header_name` / `auth_header_value`) — test przed zapisem, który niczego nie przechowuje.

```bash
curl -X POST "https://api.dmchamp.com/v1/mcp-servers/test-connection?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://tools.example.com/mcp", "auth_header_value": "Bearer sk_live_xxx" }'
```

**Odpowiedź** (`200`)

```json
{
  "success": true,
  "server_name": "Inventory tools",
  "tools": [{ "name": "check_stock", "description": "Look up stock for a SKU." }]
}
```

Awaria połączenia **nie jest** błędem HTTP — otrzymujesz `200` z `success: false` oraz `error` opisującym przyczynę problemu, dzięki czemu możesz go wyświetlić obok pola edytowanego przez operatora.

#### Przypisz serwer do Agenta

Rejestracja serwera nie zapewnia do niego dostępu żadnemu Agentowi. Przypisz go:

```bash
curl -X POST "https://api.dmchamp.com/v1/agents/ag7HkQ2ZpLxR3mNb/mcp-servers?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "mcp_server_id": "ms4TgBnH7yUj2kLp" }'
```

**Odpowiedź** (`200`)

```json
{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb", "mcp_server_id": "ms4TgBnH7yUj2kLp" }
```

`DELETE /agents/{agentId}/mcp-servers/{mcpServerId}` odłącza go ponownie. Sam serwer nie jest usuwany i pozostaje dostępny dla innych Twoich Agentów. Przypisywanie lub odłączanie czegoś, co już znajduje się w tym stanie, niczego nie zmienia.

---

## Biblioteka mediów

Biblioteka mediów przechowuje pliki, które Agent może wysłać podczas rozmowy — menu, cennik, zdjęcie produktu. Agent może przechowywać maksymalnie **50 elementów**.

### Lista mediów

`GET /agents/{agentId}/media-library`

```bash
curl "https://api.dmchamp.com/v1/agents/ag7HkQ2ZpLxR3mNb/media-library?apiKey=YOUR_API_KEY"
```

**Odpowiedź** (`200`)

```json
{
  "success": true,
  "agent_id": "ag7HkQ2ZpLxR3mNb",
  "media_items": [
    {
      "id": "mi4RtY7uIoP1aSdF",
      "item_id": "mi4RtY7uIoP1aSdF",
      "media_home": "agent",
      "title": "Spring menu",
      "description": "Send when someone asks what is on the menu.",
      "ai_description": "A one-page menu listing seasonal dishes and prices.",
      "type": "document",
      "media_content_type": "application/pdf",
      "media_url": "https://storage.googleapis.com/...",
      "max_sends_per_conversation": 1,
      "created_at": 1700000000000
    }
  ]
}
```

Elementy przechowywane na Agencie znajdują się na początku, a następnie starsze elementy nadal przechowywane w kampanii, na podstawie której zbudowano Agenta; `media_home` (`agent` lub `campaign`) wskazuje, który jest który. W obrębie każdej grupy najnowsze elementy znajdują się na początku.

> **`media_url` wygasa po 7 dniach.** Jest to link do pobrania utworzony w momencie przesłania pliku — traktuj stary link jako nieaktualny, a nie uszkodzony, i odczytaj listę ponownie, aby uzyskać świeży link.

### Prześlij media

`POST /agents/{agentId}/media-library` — plik jest przesyłany w treści żądania jako base64, do **10 MB**. Wywołanie kończy się po zapisaniu pliku, więc należy przewidzieć nieco więcej czasu niż w przypadku zwykłego żądania. Pamiętaj, że to ciało żądania używa nazw pól w formacie camelCase.

| Pole | Wymagane | Opis |
|---|---|---|
| `base64Data` | Tak | Zawartość pliku, zakodowana w base64, bez prefiksu data-URL. |
| `mimeType` | Tak | Typ MIME pliku. |
| `fileName` | Tak | Oryginalna nazwa pliku, używana do nazwania zapisanego pliku. |
| `title` | Nie | Krótka etykieta wyświetlana w bibliotece. |
| `description` | Nie | Instrukcja „kiedy Agent powinien to wysłać”. |
| `sendMessage` | Nie | Preferowane sformułowanie, które Agent wypowiada podczas wysyłania elementu. Przycięte do 500 znaków. |
| `maxSendsPerConversation` | Nie | Ile razy może zostać wysłany do tego samego kontaktu w jednej konwersacji. Domyślnie `1`. |
| `sendAsVoiceNote` | Nie | Tylko przesyłanie dźwięku — zapisz plik jako notatkę głosową WhatsApp. Ignorowane dla innych typów plików. |

```bash
curl -X POST "https://api.dmchamp.com/v1/agents/ag7HkQ2ZpLxR3mNb/media-library?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "base64Data": "JVBERi0xLjQKJcfs...",
    "mimeType": "application/pdf",
    "fileName": "spring-menu.pdf",
    "title": "Spring menu",
    "description": "Send when someone asks what is on the menu.",
    "maxSendsPerConversation": 1
  }'
```

Dwie rzeczy dzieją się automatycznie: animowany plik GIF jest konwertowany na wideo, aby odtwarzał się na każdym kanale, a platforma tworzy krótkie podsumowanie tego, co faktycznie znajduje się w pliku, aby Agent wiedział, kiedy pasuje.

Błąd `400` obejmuje brakujące pola, nieobsługiwany typ pliku, pusty lub zbyt duży plik oraz osiągnięcie limitu 50 elementów. Błąd `403` oznacza, że biblioteka mediów jest wyłączona dla tego konta.

### Aktualizacja elementu multimedialnego

`PATCH /agents/{agentId}/media-library/{itemId}` — tylko metadane. Samego pliku nie można zastąpić; prześlij nowy element i usuń stary. To ciało żądania używa formatu snake_case: `title`, `description`, `send_message`, `max_sends_per_conversation` (nieujemna liczba całkowita lub `null`, aby wyczyścić limit).

```bash
curl -X PATCH "https://api.dmchamp.com/v1/agents/ag7HkQ2ZpLxR3mNb/media-library/mi4RtY7uIoP1aSdF?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Summer menu", "max_sends_per_conversation": 2 }'
```

**Odpowiedź** (`200`)

```json
{
  "success": true,
  "agent_id": "ag7HkQ2ZpLxR3mNb",
  "item_id": "mi4RtY7uIoP1aSdF",
  "campaign_id": "",
  "media_home": "agent"
}
```

### Usuwanie elementu multimedialnego

`DELETE /agents/{agentId}/media-library/{itemId}` — usuwa element i jego zapisany plik. Usunięcie elementu, który już nie istnieje, kończy się powodzeniem i zwraca `deleted: false`, więc wywołanie można bezpiecznie ponowić.

```bash
curl -X DELETE "https://api.dmchamp.com/v1/agents/ag7HkQ2ZpLxR3mNb/media-library/mi4RtY7uIoP1aSdF?apiKey=YOUR_API_KEY"
```

---

## Generowanie wiadomości uzupełniających

`POST /agents/{agentId}/template-generation` — pisze dla Ciebie wiadomości uzupełniające Agenta (przypomnienia, które wysyła, gdy konwersacja cichnie), w oparciu o cel, do którego służy Agent.

| Pole | Opis |
|---|---|
| `type` | `all` (domyślnie) zapisuje cały zestaw. `cold_only` zapisuje tylko wiadomości dla kontaktów, które nigdy nie odpowiedziały. |

```bash
curl -X POST "https://api.dmchamp.com/v1/agents/ag7HkQ2ZpLxR3mNb/template-generation?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "type": "all" }'
```

Istnieją dwa sposoby powrotu tej informacji, a pole `target` informuje, który z nich wystąpił:

- **`target: "agent"` z `200`** — wiadomości zostały zapisane podczas połączenia, a wynik znajduje się w `data`. Odczytaj je z `follow_up_config` Agenta. Jest to typowy przypadek.
- **`target: "campaign"` z `202`** — praca została dodana do kolejki w kampanii o nazwie `campaign_id`. Obserwuj `template_generation_status` tej kampanii, aż do jej zakończenia.

`cold_only` wymaga wychodzącej kampanii i jest odrzucane z błędem `409` (`reason: "cold_only_requires_campaign"`) w przypadku Agenta, który jej nie posiada. `403` oznacza, że automatyczne działania następcze nie są włączone dla tego konta. Funkcja ta wykorzystuje kredyty AI, a `400` z `"Insufficient credits."` oznacza, że konto je wyczerpało.

---

## Kierowanie konwersacji do Agenta

Agent odpowiada tylko na konwersacje przesyłane przez **Punkt wejścia** (Entry Point). Dopóki kanał go nie posiada, pierwsza wiadomość od osoby, z którą nigdy nie rozmawiałeś, jest przechowywana, ale nikt jej nie odbiera i żaden asystent nie odpowiada.

| Co chcesz zrobić | Wywołanie |
|---|---|
| Uczynić Agenta osobą odpowiadającą dla całego kanału | `PUT /entry-points/channel-defaults` z `{ "channel": "instagram", "agent_id": "AGENT_ID" }` |
| Dodać węższą regułę (słowa kluczowe, komentarze, nowi obserwujący) | `POST /agents/{agentId}/entry-points` |
| Zobaczyć reguły wskazujące na jednego Agenta | `GET /agents/{agentId}/entry-points` |
| Pozostawić kanał bez osoby odpowiadającej | `DELETE /entry-points/channel-defaults?channel=instagram` |

### Wyświetlanie punktów wejścia Agenta

`GET /agents/{agentId}/entry-points` — reguły routingu, które wysyłają konwersacje do tego Agenta, od najnowszych. Zwracane są zarówno bieżące, jak i wycofane reguły; wycofana reguła posiada `enabled: false`.

```bash
curl "https://api.dmchamp.com/v1/agents/ag7HkQ2ZpLxR3mNb/entry-points?apiKey=YOUR_API_KEY"
```

Aby uzyskać domyślne ustawienia kanałów dla całego konta, w tym kanału celowo ustawionego na brak obsługi, odczytaj zamiast tego `GET /entry-points/channel-defaults`.

### Tworzenie punktu wejścia

`POST /agents/{agentId}/entry-points` — Agent w ścieżce zawsze wygrywa, więc reguła nigdy nie może zostać utworzona dla innego Agenta niż ten znajdujący się w adresie URL.

| `type` | Co to robi |
|---|---|
| `channel_default` | Agent odpowiada na każdy nowy kontakt na wymienionych kanałach. Preferuj `PUT /entry-points/channel-defaults` w tym celu — wycofuje to poprzedniego odbiorcę, czego utworzenie drugiego domyślnego ustawienia tutaj nie robi. |
| `keyword` | Agent przejmuje konwersację, gdy pierwsza wiadomość zawiera jedno z `match_config.keywords`. Wymagane jest co najmniej jedno słowo kluczowe. |
| `instagram_comment` / `facebook_comment` | Agent odpowiada na komentarze pod Twoimi postami. Pasujący kanał musi być wymieniony w `channels`. |
| `instagram_follower` | Agent wita nowych obserwujących. |

`channels` jest wymagane i określa, które kanały obejmuje reguła — na przykład `whatsapp`, `whatsapp_web`, `instagram`, `messenger`, `telegram`, `sms`, `email`, `chat_widget` lub `custom_channel`. Nowe reguły są włączone, chyba że określisz inaczej.

```bash
curl -X POST "https://api.dmchamp.com/v1/agents/ag7HkQ2ZpLxR3mNb/entry-points?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "keyword",
    "channels": ["whatsapp", "instagram"],
    "match_config": { "keywords": ["pricing", "quote"] }
  }'
```

**Odpowiedź** (`201`)

```json
{ "success": true, "entry_point_id": "ep3KmQ8vTzXr5nWd" }
```

**Która reguła wygrywa, gdy kilka może mieć zastosowanie:** trwająca konwersacja lub ręczne przypisanie zachowuje Agenta, którego już posiada; w przeciwnym razie reguły słów kluczowych przeważają nad regułami komentarzy, które przeważają nad regułami obserwujących, a domyślne ustawienie kanału jest ostatecznością. Informacja o tym, czy te reguły już o czymkolwiek decydują na koncie, jest raportowana przez `GET /entry-points/routing-status`.

To jest wersja skrócona. Przewodnik po [Entry Points API](entry-points.md) zawiera pełne zasady dotyczące drabinki, komentarzy i obserwujących, jednego Agenta na numer WhatsApp oraz zmiany lub usuwania reguły. Zobacz [Entry Points](../ai-agents/entry-points.md), aby poznać koncepcję, oraz [Channels API](channels.md), aby dowiedzieć się, jak połączyć sam kanał.

---

## Błędy API agentów AI

Punkty końcowe agenta zwracają standardową kopertę błędu:

```json
{
  "success": false,
  "error": "Agent not found"
}
```

| Status | Kiedy występuje w punkcie końcowym agenta |
|---|---|
| `400` | Brakuje wymaganego pola lub jest ono nieprawidłowe — pusta treść aktualizacji, wartość spoza dozwolonej listy (`ai_speed`, `anthropic_model`, `booking_provider`, `mode`, `type`), klucz inny niż dzień tygodnia w `availability`, nazwa pola z kropką w `bot-config` lub błędny identyfikator w ścieżce. |
| `403` | Konto nie ma uprawnień do użycia wysłanego ustawienia, osiągnięto limit agentów w planie lub funkcja wymagana przez ten punkt końcowy (biblioteka mediów, działania następcze, funkcje niestandardowe dla serwerów MCP) jest wyłączona. Zmiana przekraczająca rozmiar konfiguracji dozwolony w planie jest odrzucana z `400`. |
| `404` | Agent, reguła tagowania, element multimedialny lub serwer MCP nie zostały znalezione — albo nie istnieją, albo należą do innego konta. |
| `409` | Coś jest już w toku lub blokuje działanie: trwa optymalizacja lub generowanie tagów, agent jest nadal przypisany do transmisji, punktu wejścia lub kampanii, albo zażądano `cold_only` bez wychodzącej kampanii. |

Wspólne kody, które może zwrócić każdy punkt końcowy — `401`, `403` (Twój plan nie obejmuje dostępu do API), `429` (limit szybkości) oraz `500` — zostały wymienione wraz ze wskazówkami dotyczącymi ponawiania prób w sekcji [Błędy i stronicowanie](errors-and-pagination.md).

> **Uwaga dotycząca eksploratora.** Punkty końcowe `/agents` znajdują się w opublikowanej specyfikacji OpenAPI, więc możesz przeglądać ich dokładne pola i uruchamiać żądania na żywo w [Dokumentacji API](reference.md). Punkty końcowe `/mcp-servers` na poziomie konta również znajdują się w specyfikacji, więc tam również możesz je eksplorować.

::: master-only
Obecność w specyfikacji oznacza również, że punkty końcowe agenta — oraz punkty końcowe `/mcp-servers` — pojawiają się jako narzędzia dla każdego asystenta AI, którego [połączysz przez MCP](../integrations/connect-ai-clients.md).
:::

---

## Powiązane

- [Agenci AI](../ai-agents/ai-agents.md) — czym jest agent, wyjaśnione prostym językiem.
- [Punkty wejścia](../ai-agents/entry-points.md) — w jaki sposób rozmowy są kierowane do agenta.
- [API FAQ](faqs.md) — budowanie i łączenie wiedzy, na podstawie której odpowiada agent.
- [API kanałów](channels.md) — łączenie kanałów, na których odpowiada agent.
- [Łączenie serwerów MCP z botem](../ai-automation/mcp-servers.md) · [Funkcje niestandardowe](../ai-automation/custom-functions.md)
- [Dokumentacja API](reference.md) — pełny interaktywny eksplorator punktów końcowych.