---
title: "Zmienne i kontekst dla poszczególnych połączeń"
description: "Nadaj każdemu połączeniu własne szczegóły jako nazwane zmienne dla promptu lub swobodny opis, bez zmieniania agenta."
---

Każde połączenie może zawierać dwa rodzaje danych wejściowych dla danego połączenia. Użyj jednego z nich lub obu jednocześnie:

- **`variables`**: nazwane wartości, które wypełniają `{{placeholders}}` w prompcie. Używaj ich dla pól, do których prompt odwołuje się po nazwie, takich jak imię rozmówcy, numer konta lub termin wizyty.
- **`context`**: tekst dowolnej formy dodawany po prompcie. Używaj go dla instrukcji, które nie pasują do szablonu, takich jak opis zadania dla tego połączenia lub wcześniej zebrane notatki.

Oba działają z zapisanym agentem i z konfiguracją wbudowaną, przy każdym opisanym poniżej sposobie rozpoczęcia połączenia. Żaden z nich nie zmienia zapisanego agenta, jego historii wersji ani innych ustawień.

```json
{
  "agent_id": 12,
  "variables": {"name": "Ada", "appointment_slot": "Tuesday at 10 AM"},
  "context": "Ada rescheduled twice last month. She prefers mornings and asked us not to call her work number."
}
```

## Zmienne

Umieść symbole zastępcze w prompcie zapisanego agenta, a następnie podczas rozpoczynania połączenia przekaż obiekt `variables`. ThunderPhone renderuje tekst przed wysłaniem konfiguracji połączenia do środowiska wykonawczego agenta głosowego.

Gdy wartości nie są potrzebne, pomiń `variables`; nie wysyłaj `null` (jest odrzucane z kodem `400`).

### Symbole zastępcze i wartości domyślne

```text
You are calling {{name|Friend}} about account {{account_id}}.
The available appointment is {{ appointment_slot }}.
```

Nazwy rozróżniają wielkość liter i są zgodne z `[A-Za-z_][A-Za-z0-9_]*`. Białe znaki wokół
nazwy są dozwolone; biały znak po `|` jest częścią wartości domyślnej i jest
zachowywany. `{{name|Friend}}` używa `Friend`, gdy brakuje `name` lub ma ono wartość
`null`; pusty ciąg znaków jest wartością podaną jawnie. Brakujące wartości bez
wartości domyślnej stają się pustymi ciągami znaków, a ich nazwy pojawiają się w
`unresolved_variables`. Tekst między podwójnymi nawiasami klamrowymi, który nie jest prawidłowym symbolem zastępczym, jest usuwany. Tekst w podwójnych nawiasach klamrowych
wewnątrz każdej podanej wartości jest usuwany niezależnie; wartość nie może usunąć
otaczającego tekstu promptu ani innej wartości. Niedopasowane ograniczniki podwójnych nawiasów klamrowych są
również usuwane. Przykłady JSON w promptach nie mogą używać `{{`.
Wartości są zwykłym tekstem, nigdy nie są wykonywane
jako kod ani rekurencyjnie rozwijane jako szablony.

Zmienne mogą również występować w promptach potwierdzenia, wychodzących wiadomościach poczty głosowej
oraz w tekście komunikatu zgody, gdy to pole jest wysyłane dla
połączenia telefonicznego. Agent nie ma osobnego pola `first_message`: umieść
jego instrukcje otwierające w prompcie. Istniejące symbole zastępcze poczty głosowej `{agent_name}` i `{org_name}`
nadal działają.

### Wartości i limity

Wartości mogą być ciągami znaków, liczbami, wartościami logicznymi lub `null`; wartości logiczne są renderowane jako `true`
i `false`. Znaki kontrolne Unicode (`Cc`) z wyjątkiem znaku nowego wiersza (`\n`), tabulatora (`\t`)
i powrotu karetki (`\r`), znaki formatu (`Cf`) z wyjątkiem łącznika i niełącznika o zerowej szerokości (U+200C, U+200D, które służą do zapisu słów w językach indyjskich i językach zapisywanych pismem
arabskim) oraz punkty kodowe surogatów (`Cs`) są usuwane; `\r\n`
jest normalizowane do `\n`. Każda wartość
jest ograniczona do 2 000 znaków po wyrenderowaniu. Dostarczone ciągi znaków są również czyszczone i
skracane przed zapisaniem. Oryginalny obiekt musi mieścić się w **32 KB kodu JSON w UTF-8**; większe obiekty otrzymują `400` w żądaniach połączeń/sesji, natomiast importy kampanii zgłaszają nieprawidłowe wiersze indywidualnie. Tablice i zagnieżdżone obiekty nie są
akceptowane jako wartości. Niepasujące klucze metadanych (na przykład nagłówek CSV ze
spacją) są zachowywane i zwracane, ale nie można odwoływać się do nich za pomocą symbolu zastępczego.

## Kontekst

`context` to ciąg znaków o długości do **20 000 znaków**. ThunderPhone dodaje go po
poleceniu, po uzupełnieniu zmiennych polecenia, jako blok z ogranicznikami:

```text
<your prompt, with its variables filled in>

Details for this call:
<call_context>
Ada rescheduled twice last month. She prefers mornings and asked us not to call her work number.
</call_context>
```

Agent odczytuje go razem z instrukcjami, dlatego zapisz go tak, jak
przekazałbyś informacje współpracownikowi przed połączeniem. Kontekst nie jest szablonem:
`{{name}}` w jego treści pozostaje bez zmian. Jeśli tekst wymaga wartości, wstaw ją
samodzielnie przed wysłaniem.

- `null`, pusty ciąg znaków lub wyłącznie białe znaki oznaczają brak kontekstu.
- Wartość, która nie jest ciągiem znaków lub jest dłuższa niż 20 000 znaków, jest odrzucana z kodem `400` w żądaniach połączeń i sesji; w webhooku konfiguracji powoduje niepowodzenie wymiany tak jak nieprawidłowe `variables` (patrz poniżej).
- Początkowe i końcowe białe znaki są przycinane, a te same znaki sterujące i formatowania co w wartościach zmiennych są usuwane.
- Kontekst jest częścią promptu połączenia, więc wlicza się do [rozmiaru promptu](/pl/guides/pricing) połączenia.

W agencie z [krokami](/pl/guides/agent-steps) kontekst następuje po poleceniu
każdego agenta w połączeniu, a nie po instrukcjach każdego kroku.

## Skąd pochodzą wartości

### Wychodzące API

Wyślij `variables` i `context` w żądaniu `POST /v1/call`:

```json
{
  "from_number": "+15551234567",
  "to_number": "+14155552671",
  "agent_id": 12,
  "variables": {
    "name": "Ada",
    "account_id": "A-17",
    "appointment_slot": "Tuesday at 10 AM"
  },
  "context": "Ada asked to be called back about the late fee on her March invoice."
}
```

Oba pola działają również z domyślnym agentem wychodzącym numeru telefonu lub z wbudowanym
`config.prompt`. W przypadku wbudowanej konfiguracji pole `context` może również znaleźć się w `config`,
czyli w tym samym polu, które zwraca webhook konfiguracji; jeśli wyślesz oba, muszą zawierać
ten sam tekst. Klucza idempotencji nie można użyć ponownie z innymi zmiennymi lub innym kontekstem.

### CSV kampanii

Kolumny CSV inne niż numer telefonu są już przechowywane jako zmienne kontaktu. Każde połączenie wykorzystuje je teraz automatycznie. Użyj nagłówków takich jak `name`, `account_id` i `appointment_slot`, aby dopasować je do swoich symboli zastępczych. Istniejące mapowanie imienia może połączyć kolumny imienia i nazwiska w zmienną `name`. Kontakty kampanii nie mają kontekstu przypisanego do poszczególnych kontaktów.

### Webhook dynamicznej konfiguracji

W ścieżce blokującego webhooka konfiguracji zwróć zapisanego agenta w swojej organizacji wraz z wartościami dla danego połączenia. W przypadku agenta Full duplex połączenie zachowuje głos agenta, nawet gdy rozpoczyna się w innym obsługiwanym języku: mapowania głosu dla poszczególnych języków i natywne przełączanie głosu nie mają zastosowania w tym połączeniu.

```json
{
  "agent_id": 12,
  "variables": {"name": "Ada", "account_id": "A-17"},
  "context": "[REDACTED_LITERAL]"
}
```

```json
{
  "agent_id": 12,
  "variables": {"name": "Ada", "account_id": "A-17"},
  "context": "Ada called yesterday about a leak in unit 4B; a plumber is booked for Friday."
}
```

Zmienne z odpowiedzi nadpisują zmienne na poziomie żądania, a pozostałe klucze żądania pozostają bez zmian. Wartość `null` w odpowiedzi wybiera wartość domyślną symbolu zastępczego.
Scalony obiekt również musi mieścić się w 32 KB. Odpowiedzi zapisanego agenta akceptują tylko
`agent_id`, `variables`, `context`, `language` oraz strefę czasową dla pojedynczego połączenia
[`timezone`](/pl/guides/dynamic-call-config); zwróć konfigurację inline, gdy musisz
zastąpić prompt lub inne ustawienia. Odpowiedzi webhooka zapisanego agenta
używają wdrożonego podziału A/B agenta zarówno w połączeniach telefonicznych, jak i w widżecie;
zmienne są renderowane po wyborze wariantu. Gdy odpowiedź ustawia `language` dla
agenta niebędącego Full duplex, połączenie używa również głosu przypisanego do tego języka, jeśli
agent ma dla niego ustawiony głos. Odpowiedź zawierająca `prompt` zawsze używa
konfiguracji inline: każde `agent_id` w tej odpowiedzi jest ignorowane, w tym wartość null lub
metadane niebędące liczbami całkowitymi. Prompt inline nadal musi przejść standardową walidację.
Odpowiedzi webhooka inline mogą również zawierać `variables` i `context`. Element `context`,
który nie jest ciągiem znaków lub jest zbyt długi, powoduje błąd wymiany: połączenie telefoniczne
zostaje odrzucone, a żądanie sesji widżetu kończy się błędem `400`. Odpowiedzi webhooka zapisanego agenta
używają wdrożonego podziału A/B agenta zarówno w połączeniach telefonicznych, jak i w widżecie;
zmienne są renderowane po wyborze wariantu. W przypadku przychodzących połączeń telefonicznych użyj numeru bez przypisanego
agenta przychodzącego i skonfiguruj jego webhook numeru telefonu lub organizacji; klucze widżetu używają
`mode="webhook"`. Przychodzące powiadomienia systemu punktów końcowych nie udostępniają blokujących
odpowiedzi konfiguracji.

### Webhook konfiguracji połączenia agenta

Aby zachować numer przypisany do agenta i uzupełniać tylko wartości połączenia,  
udostępnij agentowi [webhook konfiguracji połączenia](/pl/webhooks/call-incoming).
Przed każdym połączeniem przychodzącym, które agent odbiera pod danym numerem, webhook otrzymuje
połączenie oraz identyfikator, nazwę i wersję agenta, a następnie odpowiada tymi samymi wartościami
`variables`, `context`, `language` i `timezone` dla danego połączenia, jak powyżej, bez konieczności podawania `agent_id`. Agent,
którego ustawienia używają symbolu zastępczego bez wartości domyślnej, potrzebuje tego webhooka, aby odbierać połączenia
na numerze telefonu: połączenie nie rozpocznie się, gdy webhook zawiedzie. Symbole zastępcze z wartością domyślną, takie jak `{{name|there}}`, pozwalają agentowi odbierać połączenia bez niego.

### Nagłówki SIP

Połączenia docierające do agenta przez SIP (na [adres SIP](/pl/guides/sip-addresses) lub
numer w ręcznym połączeniu SIP) mogą zawierać kontekst w nagłówkach `X-*` i
`User-to-User`. Każdy z nich staje się zmienną `sip_`, taką jak
`{{sip_x_amzn_connectcontactid}}` lub `{{sip_uui}}`, o najniższym
priorytecie: wartość o tej samej nazwie z interfejsu API lub webhooka ma pierwszeństwo. Zobacz
[Przekazywanie kontekstu połączenia w nagłówkach SIP](/pl/guides/sip-addresses).
Wartości nagłówków są ustawiane przez nadawcę, dlatego traktuj je jako niezaufane, podobnie jak każdą
wartość dostarczoną przez przeglądarkę.

### API sesji widżetu

`POST /v1/widget/session` akceptuje najwyższego poziomu `variables` i `language`. Jego klucz publikowalny
wybiera zapisanego agenta. Klucze w trybie webhook przekazują te wartości do
webhooka konfiguracji i scalają odpowiedź zgodnie z opisem powyżej.
Dostarczane przez przeglądarkę widgetu `variables` są kontrolowane przez klienta, przekazywane
dosłownie w `web.incoming` po opisanej powyżej walidacji i oczyszczeniu ciągów znaków
oraz odzwierciedlane w webhookach zakończenia i historii połączeń. Nie traktuj ich
jako zaufanych danych tożsamości ani autoryzacji.

Własne pole przeglądarkowego `context` widżetu jest inne: przenosi tekst ze
strony, na której znajduje się odwiedzający, a agent traktuje go jako treść witryny (zobacz
[Osadzanie widżetu internetowego](/pl/guides/embed-web-widget)). Kontekst pojedynczego połączenia widżetu
pochodzi z webhooka konfiguracji klucza w trybie webhooka, jak opisano powyżej. Gdy
połączenie ma oba rodzaje kontekstu, najpierw używany jest kontekst pojedynczego połączenia, a następnie treść strony.

### API sesji czasu rzeczywistego

`POST /v1/realtime/sessions` akceptuje pola najwyższego poziomu `variables`, `context` i `language`
obok `agent_id` lub wbudowanego `config`:

```json
{
  "agent_id": 12,
  "variables": {"name": "Ada"},
  "context": "Ada is calling from the front desk about a guest's lost key card."
}
```

`context` może znajdować się wyłącznie na najwyższym poziomie; wbudowany `config` odrzuca go jako
nieznane pole.

### WebSocket w czasie rzeczywistym

W przypadku zapisanego agenta wdrożony prompt zapisanego agenta pozostaje jego promptem.
`session.instructions` staje się kontekstem połączenia, `session.prompt.variables`
(lub `session.config.variables`) stają się jego zmiennymi, a `session.language`
staje się językiem dla danego połączenia. Wybierz agenta za pomocą
`session.prompt.id` w pierwszym `session.update`, który uruchamia sesję po
otrzymaniu tej aktualizacji:

```json
{
  "type": "session.update",
  "session": {
    "type": "realtime",
    "prompt": {"id": "12", "variables": {"name": "Ada"}},
    "instructions": "Ada asked for a callback about her delivery window."
  }
}
```

`?agent_id=12` w adresie URL połączenia uruchamia agenta natychmiast po połączeniu
gniazda, przed jakimkolwiek `session.update`, dlatego nie zawiera danych wejściowych
dla poszczególnych połączeń. Dodaj `&wait_for_session_update=1`, aby zaczekać na
pierwsze `session.update` i użyć jego instrukcji oraz zmiennych.

W sesji inline (bez zapisanego agenta) `session.instructions` jest samym promptem, tak jak wcześniej. Testowe połączenia w przeglądarce i symulacje rozwiązują wartości domyślne oraz brakujące symbole zastępcze. Aby testować z wartościami, zapisz
[przykład konfiguracji połączenia](/pl/webhooks/call-incoming) w agencie i wybierz go podczas uruchamiania testu; połączenie działa tak, jakby webhook konfiguracji połączenia zwrócił tę odpowiedź.

## Po zakończeniu połączenia

`GET /v1/calls`, `GET /v1/calls/{call_id}`, `telephony.complete` i `web.complete` zawierają
końcowe scalone `variables` i `unresolved_variables`. Starsze ładunki zakończenia,
które zawierają `data.history`, również je obejmują:

```json
{
  "variables": {"name": "Ada", "account_id": "A-17"},
  "unresolved_variables": ["appointment_slot"]
}
```

`prompt_snapshot` połączenia (`GET /v1/calls/{call_id}`) pokazuje prompt agenta
z uzupełnionymi zmiennymi i dodanym blokiem kontekstu.

Zapisz identyfikator CRM lub zadania w obiekcie zmiennych, aby powiązać zakończone
połączenie z rekordem źródłowym. Zmienne i kontekst są przechowywane wraz z rekordem
połączenia; wysyłaj tylko informacje, które można przechowywać w historii połączeń
i webhookach.

Odtworzenia połączenia w [zestawach walidacyjnych](/api-reference/validation-sets),
[uruchomieniach odtworzeń](/api-reference/replay-runs) oraz
[analizach](/api-reference/investigations) używają zmiennych i kontekstu tego
połączenia wraz z testowanym promptem, więc odtworzenie sprawdza, co zostałoby
przekazane agentowi w tym połączeniu.

## Zgodność z istniejącymi promptami

Renderowanie dotyczy również istniejących promptów zapisanych agentów i wariantów A/B, wbudowanych konfiguracji połączeń wychodzących i w czasie rzeczywistym oraz promptów zwracanych przez webhooki konfiguracji. Nieznane placeholdery `{{name}}` stają się pustym tekstem, nawet gdy nie podano żadnych `variables`. Przed wdrożeniem sprawdź istniejące prompty, w tym dostarczane zewnętrznie prompty wbudowane i webhooków, których ThunderPhone nie może zinwentaryzować. Testowe połączenia i symulacje w przeglądarce stosują to samo zachowanie domyślne/puste, chyba że wybierzesz zapisany przykład konfiguracji połączenia.
