Developer cookbook

Zmienne dla poszczególnych połączeń

Personalizuj zapisanego agenta dla każdego połączenia bez zmieniania wdrożonego promptu, narzędzi ani ustawień.

Umieść symbole zastępcze w prompcie zapisanego agenta, a następnie podaj obiekt variables podczas rozpoczynania połączenia. Zapisana konfiguracja i historia wersji pozostają niezmienione. ThunderPhone renderuje tekst przed wysłaniem konfiguracji połączenia do środowiska uruchomieniowego głosu.

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 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), wszystkie znaki formatu (Cf) oraz punkty kodowe surogatu (Cs) są usuwane; \r\n jest normalizowane do \n. Każda wartość jest ograniczona do 2 000 znaków po renderowaniu. Podane ciągi znaków są również czyszczone i obcinane przed zapisaniem. Oryginalny obiekt musi mieścić się w 32 KB danych 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 obiekty zagnieżdżone 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.

Skąd pochodzą wartości#

Wychodzące API#

Wyślij variables wraz z agent_id w żądaniu POST /v1/call:

{
  "from_number": "+15551234567",
  "to_number": "+14155550199",
  "agent_id": 12,
  "variables": {
    "name": "Ada",
    "account_id": "A-17",
    "appointment_slot": "Tuesday at 10 AM"
  }
}

Działa to również z domyślnym agentem wychodzącym numeru telefonu lub z wbudowanym config.prompt. Klucza idempotencji nie można użyć ponownie z innymi zmiennymi.

CSV kampanii#

Kolumny CSV inne niż numer telefonu są już przechowywane jako zmienne kontaktu. Każde połączenie automatycznie ich używa. Używaj nagłówków takich jak name, account_id i appointment_slot, aby dopasować je do swoich symboli zastępczych. Istniejące mapowanie nazwy może łączyć kolumny imienia i nazwiska w zmienną name.

Webhook dynamicznej konfiguracji#

W blokującej ścieżce webhooka konfiguracji zwróć zapisanego agenta w swojej organizacji wraz z wartościami dla poszczególnych połączeń:

{"agent_id": 12, "variables": {"name": "Ada", "account_id": "A-17"}}

Klucze odpowiedzi nadpisują zmienne na poziomie żądania, podczas gdy pozostałe klucze żądania pozostają bez zmian. Wartość null w odpowiedzi wybiera wartość domyślną symbolu zastępczego. Scalony obiekt musi również mieścić się w limicie 32 KB. Odpowiedzi zapisanych agentów akceptują tylko agent_id i variables; zwróć konfigurację wbudowaną, gdy musisz zastąpić prompt lub ustawienia. Odpowiedź zawierająca prompt zawsze używa konfiguracji wbudowanej: każdy agent_id w tej odpowiedzi jest ignorowany, w tym metadane null lub niecałkowite. Wbudowany prompt nadal musi przejść standardową walidację. Wbudowane odpowiedzi webhooka również mogą zawierać variables. 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 jego webhook numeru telefonu lub organizacji; klucze widżetu używają mode="webhook". Przychodzące powiadomienia systemu endpointów nie dostarczają blokujących odpowiedzi konfiguracji.

API sesji widżetu i Realtime#

POST /v1/widget/session akceptuje obiekt variables na najwyższym poziomie. Jego publikowalny klucz wybiera zapisanego agenta. Klucze trybu webhook przekazują te wartości do webhooka konfiguracji i scalają odpowiedź zgodnie z opisem powyżej. Dostarczane przez przeglądarkę zmienne variables widżetu/Realtime są kontrolowane przez klienta, przekazywane dosłownie w web.incoming po opisanej powyżej walidacji i oczyszczeniu ciągów oraz powielane w webhookach zakończenia i historii połączeń. Nie traktuj ich jako zaufanych danych identyfikacyjnych lub autoryzacyjnych.

POST /v1/realtime/sessions akceptuje variables wraz z agent_id (lub wbudowanym config). Są to pola API tworzenia sesji. Most WebSocket Realtime nie przekazuje opcji variables; podaj ją bezpośrednio do API tworzenia sesji. Klienci widżetu muszą uwzględniać variables w wysyłanym ładunku sesji; przekazywanie przez SDK nie jest częścią tej zmiany API. Połączenia mikrofonowe w kreatorze i symulowane połączenia testowe rozwiązują wartości domyślne i brakujące symbole zastępcze, ale nie mają danych wejściowych zmiennych dla poszczególnych połączeń.

Wartości zwracane po połączeniu#

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"]
}

Przechowuj identyfikator CRM lub zadania w obiekcie zmiennych, aby połączyć zakończone połączenie z powrotem z jego rekordem źródłowym. Te pola są zachowywane wraz z rekordem połączenia; wysyłaj tylko informacje odpowiednie do przechowywania w historii połączeń i webhookach.

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.