ThunderPhone v3 już działa.Uruchom samodzielnie, od 2¢/min.Przeczytaj komunikat

Developer cookbook

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 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 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 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; 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. 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. 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 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ą:

{
  "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, 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.