Developer cookbook

Variabile pentru fiecare apel

Personalizați un agent salvat pentru fiecare apel, fără să îi modificați promptul implementat, instrumentele sau setările.

Introduceți substituenți în promptul agentului salvat, apoi furnizați un obiect variables când inițiați un apel. Configurația salvată și istoricul versiunilor rămân neschimbate. ThunderPhone redă textul înainte de a trimite configurația apelului către mediul de execuție vocal.

Când nu sunt necesare valori, omiteți variables; nu trimiteți null (respins cu 400).

Substituenți și valori implicite#

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

Numele sunt sensibile la majuscule și minuscule și respectă [A-Za-z_][A-Za-z0-9_]*. Spațiile albe din jurul numelui sunt permise; spațiile albe de după | fac parte din valoarea implicită și sunt păstrate. {{name|Friend}} utilizează Friend când lipsește name sau are valoarea null; un șir gol este o valoare furnizată explicit. Valorile lipsă fără o valoare implicită devin șiruri goale, iar numele lor apar în unresolved_variables. Textul dintre acolade duble care nu este un substituent valid este eliminat. Textul dintre acolade duble din fiecare valoare furnizată este eliminat independent; o valoare nu poate elimina textul din jur din prompt sau o altă valoare. Delimitatorii de acolade duble nepereche sunt, de asemenea, eliminați. Exemplele JSON din prompturi nu trebuie să utilizeze {{. Valorile sunt text simplu, nu sunt niciodată evaluate ca cod și nu sunt extinse recursiv ca șabloane.

Variabilele pot apărea și în prompturile de confirmare, mesajele vocale trimise și textul anunțului de consimțământ atunci când acel câmp este trimis pentru un apel telefonic. Agentul nu are un câmp first_message separat: includeți instrucțiunile de deschidere în prompt. Substituenții existenți pentru mesageria vocală {agent_name} și {org_name} continuă să funcționeze.

Valorile pot fi șiruri, numere, valori booleene sau null; valorile booleene sunt redate ca true și false. Caracterele de control Unicode (Cc), cu excepția liniei noi (\n), tabulatorului (\t) și revenirii la începutul rândului (\r), toate caracterele de formatare (Cf) și punctele de cod surogat (Cs) sunt eliminate; \r\n este normalizat la \n. Fiecare valoare este limitată la 2.000 de caractere la redare. Șirurile furnizate sunt curățate și trunchiate și înainte de stocare. Obiectul original trebuie să încapă în 32 KB de JSON UTF-8; obiectele mai mari primesc 400 în cererile de apel/sesiune, iar importurile de campanii raportează rândurile nevalide individual. Matricele și obiectele imbricate nu sunt acceptate ca valori. Cheile de metadate neconforme (de exemplu, un antet CSV cu un spațiu) sunt păstrate și retransmise, dar nu pot fi referite de un substituent.

De unde provin valorile#

API pentru apeluri ieșite#

Trimiteți variables împreună cu agent_id în 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"
  }
}

Funcționează și cu agentul implicit pentru apeluri ieșite al numărului de telefon sau cu un config.prompt inline. O cheie de idempotență nu poate fi reutilizată cu variabile diferite.

CSV de campanie#

Coloanele CSV care nu sunt numere de telefon sunt deja stocate ca variabile de contact. Fiecare apelare le utilizează acum automat. Folosiți anteturi precum name, account_id și appointment_slot pentru a corespunde substituenților dumneavoastră. Maparea existentă pentru nume poate combina coloanele pentru prenume și nume de familie în variabila name.

Webhook de configurare dinamică#

Pe ruta webhookului de configurare blocant, returnați un agent salvat din organizația dumneavoastră, împreună cu orice valori per apel:

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

Cheile din răspuns suprascriu variabilele de la nivelul cererii, iar celelalte chei ale cererii rămân neschimbate. O valoare de răspuns null selectează valoarea implicită a substituentului. Obiectul fuzionat trebuie să se încadreze și în 32 KB. Răspunsurile pentru agenți salvați acceptă doar agent_id și variables; returnați o configurație inline atunci când trebuie să înlocuiți promptul sau setările. Un răspuns care conține prompt utilizează întotdeauna configurația inline: orice agent_id din acel răspuns este ignorat, inclusiv metadatele nule sau care nu sunt numere întregi. Promptul inline trebuie totuși să treacă validarea obișnuită. Răspunsurile inline ale webhookului pot include și variables. Răspunsurile webhook pentru agenți salvați utilizează împărțirea A/B implementată a agentului atât pentru apelurile telefonice, cât și pentru cele din widget; variabilele sunt randate după selectarea variantei. Pentru apelurile telefonice primite, utilizați un număr fără agent atribuit pentru apeluri primite și configurați webhookul numărului de telefon sau al organizației; cheile widgetului utilizează mode="webhook". Notificările primite ale sistemului de endpointuri nu furnizează răspunsuri de configurare blocante.

API-uri de sesiune Widget și Realtime#

POST /v1/widget/session acceptă un obiect variables de nivel superior. Cheia sa publicabilă selectează agentul salvat. Cheile în modul webhook redirecționează aceste valori către webhookul de configurare și fuzionează răspunsul conform descrierii de mai sus. Valorile variables furnizate de browser pentru widget/realtime sunt controlate de client, redirecționate neschimbate în web.incoming după validarea și curățarea șirurilor descrise mai sus și incluse în webhookurile de finalizare și istoricul apelurilor. Nu le tratați ca date de identitate sau autorizare de încredere.

POST /v1/realtime/sessions acceptă variables împreună cu agent_id (sau cu un config inline). Acestea sunt câmpuri ale API-ului de creare a sesiunii. Puntea WebSocket Realtime nu redirecționează o opțiune pentru variabile; furnizați-o direct către API-ul de creare a sesiunii. Clienții Widget trebuie să includă variables în încărcătura utilă a sesiunii trimise; redirecționarea prin SDK nu face parte din această modificare a API-ului. Apelurile de test cu microfonul din Builder și cele simulate rezolvă valorile implicite și substituenții lipsă, dar nu au o intrare pentru variabile per apel.

Valorile returnate după apel#

GET /v1/calls, GET /v1/calls/{call_id}, telephony.complete și web.complete includ valorile finale fuzionate variables și unresolved_variables. Încărcăturile utile vechi de finalizare care includ data.history le includ și pe acestea:

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

Stocați identificatorul CRM sau al sarcinii în obiectul de variabile pentru a asocia apelul finalizat înapoi cu înregistrarea sursă. Aceste câmpuri sunt păstrate împreună cu înregistrarea apelului; trimiteți doar informații adecvate pentru păstrare în istoricul apelurilor și webhookuri.

Compatibilitate cu prompturile existente#

Redarea se aplică și prompturilor existente pentru agenți salvați și variante A/B, configurațiilor inline pentru apeluri outbound și în timp real, precum și prompturilor returnate de webhookurile de configurare. Substituenții necunoscuți {{name}} devin text gol, chiar și atunci când nu sunt furnizate variables. Verificați prompturile existente înainte de lansare, inclusiv prompturile inline/webhook furnizate extern pe care ThunderPhone nu le poate inventaria. Apelurile de microfon și simulare din Builder aplică același comportament implicit/gol.