Open in
Zmienne i kontekst dla poszczególnych połączeń
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ń.
{
"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
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:
<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
400w żądaniach połączeń i sesji; w webhooku konfiguracji powoduje niepowodzenie wymiany tak jak nieprawidłowevariables(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 połączenia.
W agencie z krokami 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:
{
"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.
{
"agent_id": 12,
"variables": {"name": "Ada", "account_id": "A-17"},
"context": "[REDACTED_LITERAL]"
}{
"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 zastępują zmienne na poziomie żądania, a pozostałe
klucze żądania pozostają bez zmian. Wartość null w odpowiedzi wybiera domyślną wartość symbolu zastępczego.
Scalony obiekt również musi mieścić się w limicie 32 KB. Odpowiedzi zapisanych agentów akceptują tylko
agent_id, variables, context, language oraz ustawianą dla każdego połączenia
timezone; zwróć konfigurację wbudowaną, gdy musisz
zastąpić prompt lub inne ustawienia. Gdy odpowiedź ustawia language dla
agenta, który nie jest Full duplex, połączenie używa również głosu właściwego dla tego języka, jeśli
agent ma dla niego ustawiony głos. Odpowiedź zawierająca prompt zawsze używa konfiguracji
wbudowanej: każde agent_id w tej odpowiedzi jest ignorowane, w tym metadane null lub
niecałkowitoliczbowe. Wbudowany prompt nadal musi przejść standardową walidację.
Wbudowane odpowiedzi webhooka mogą również zawierać variables i context. Wartość context,
która nie jest ciągiem znaków lub jest zbyt długa, powoduje niepowodzenie wymiany: połączenie telefoniczne
zostaje odrzucone, a żądanie sesji widżetu kończy się błędem 400. Odpowiedzi webhooka zapisanych agentów
używają wdrożonego podziału A/B agenta zarówno w połączeniach telefonicznych, jak i widżetu;
zmienne są renderowane po wyborze wariantu. W przypadku przychodzących połączeń telefonicznych użyj numeru bez przypisanego agenta
przychodzącego i skonfiguruj webhook numeru telefonu lub organizacji; klucze widżetu używają
mode="webhook". Przychodzące powiadomienia systemu endpointów nie dostarczają 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.
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 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.
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). 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:
{
"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:
{
"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. Mikrofon w Builderze i symulowane połączenia testowe rozwiązują
wartości domyślne oraz brakujące symbole zastępcze, ale nie mają zmiennych ani danych
kontekstowych dla poszczególnych połączeń.
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ą:
{
"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, uruchomieniach odtworzeń oraz analizach 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, konfiguracji wychodzących i czasu rzeczywistego wstawianych bezpośrednio oraz promptów zwracanych przez webhooki konfiguracji. Nieznane placeholdery {{name}} stają się pustym tekstem, nawet gdy nie podano variables. Przed wdrożeniem sprawdź istniejące prompty, w tym dostarczane zewnętrznie prompty inline i webhooki, których ThunderPhone nie może zinwentaryzować. Połączenia z mikrofonu w Kreatorze i połączenia symulacyjne stosują to samo domyślne zachowanie z pustym tekstem.