Open in
Variabile și context pentru fiecare apel
Oferiți fiecărui apel propriile detalii, ca variabile denumite pentru prompt sau ca rezumat în format liber, fără a modifica agentul.
Fiecare apel poate include două tipuri de date de intrare pentru apel. Folosiți unul dintre ele sau ambele împreună:
variables: valori denumite care completează{{placeholders}}din prompt. Folosiți-le pentru câmpurile la care promptul se referă după nume, cum ar fi numele apelantului, un număr de cont sau un interval pentru programare.context: text liber adăugat după prompt. Folosiți-l pentru un rezumat care nu se potrivește într-un șablon, cum ar fi o descriere a sarcinii pentru acest apel sau note colectate anterior.
Ambele funcționează cu un agent salvat și cu o configurație inline, pentru toate modalitățile de inițiere a unui apel descrise mai jos. Niciunul nu modifică agentul salvat, istoricul versiunilor acestuia sau celelalte setări ale sale.
{
"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."
}Variabile
Introduceți substituenți în promptul agentului salvat, apoi furnizați un obiect variables
când inițiați un apel. ThunderPhone redă textul înainte de a trimite
configurația apelului către timpul 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.
Valori și limite
Valorile pot fi șiruri de caractere, 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 returului de car (\r), caracterele de formatare (Cf), cu excepția caracterelor de nealipire și alipire cu lățime zero (U+200C, U+200D, care scriu cuvinte în limbile indică și în limbile cu scriere arabă), precum ș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, de asemenea, curățate și
trunchiate înainte de stocare. Obiectul original trebuie să încapă în 32 KB de
JSON UTF-8; obiectele mai mari primesc 400 la solicitările de apel/sesiune, iar
importurile de campanii raportează individual rândurile nevalide. 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 printr-un substituent.
Context
context este un șir de până la 20.000 de caractere. ThunderPhone îl adaugă după
prompt, după ce sunt completate variabilele promptului, ca bloc delimitat:
<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>Agentul îl citește împreună cu instrucțiunile sale, așa că scrieți-l așa cum
ați informa un coleg înainte de apel. Contextul nu este un șablon:
{{name}} din interiorul lui rămâne exact cum este scris. Dacă textul necesită o valoare, introduceți valoarea
dumneavoastră înainte de trimitere.
null, un șir gol sau doar spații albe înseamnă că nu există context.- O valoare care nu este un șir sau care depășește 20.000 de caractere este respinsă cu
400în solicitările de apel și sesiune; dintr-un webhook de configurare, eșuează schimbul de date la fel cavariablesnevalid (vedeți mai jos). - Spațiile albe de la început și de la sfârșit sunt eliminate, iar aceleași caractere de control și de formatare ca din valorile variabilelor sunt eliminate.
- Contextul face parte din promptul apelului, așadar este luat în calcul în dimensiunea promptului apelului.
Pentru un agent cu pași, contextul urmează promptul fiecărui agent din apel, nu instrucțiunile fiecărui pas.
De unde provin valorile
API pentru apeluri ieșite
Trimiteți variables și context în 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."
}Ambele funcționează și cu agentul vocal implicit pentru apeluri efectuate al numărului de telefon sau cu un config.prompt integrat. Cu o configurație integrată, context poate fi inclus și în config, același câmp returnat de un webhook de configurare; dacă le trimiteți pe ambele, acestea trebuie să conțină același text. O cheie de idempotentizare nu poate fi reutilizată cu variabile diferite sau cu un context diferit.
CSV de campanie
Coloanele CSV care nu conțin numere de telefon sunt deja stocate ca variabile de contact. Fiecare apelare le utilizează acum automat. Folosiți antete precum name, account_id și appointment_slot pentru a corespunde substituenților dumneavoastră. Maparea existentă a numelui poate combina coloanele pentru prenume și nume de familie în variabila name. Contactele din campanii nu au context per contact.
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. Pentru un agent Full duplex, apelul păstrează vocea agentului chiar și atunci când apelul începe într-o altă limbă acceptată: mapările vocilor pe limbă și comutarea nativă a vocii nu se aplică acelui apel.
{
"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."
}Variabilele din răspuns suprascriu variabilele de la nivelul cererii, în timp ce celelalte
chei ale cererii rămân neschimbate. O valoare de răspuns null selectează valoarea implicită a substituentului.
Obiectul combinat trebuie, de asemenea, să se încadreze în 32 KB. Răspunsurile pentru agenți salvați acceptă numai
agent_id, variables, context, language și un
timezone per apel; returnați o configurație inline atunci când trebuie să
înlocuiți promptul sau alte setări. Răspunsurile webhook pentru agenți salvați
folosesc î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. Când răspunsul setează language pentru un
agent care nu este Full duplex, apelul folosește și vocea proprie a limbii respective, dacă
agentul are una configurată pentru aceasta. Un răspuns care conține prompt folosește î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 în continuare să treacă validarea normală.
Răspunsurile webhook inline pot include și variables și context. Un context
care nu este un șir de caractere sau este prea lung face ca schimbul să eșueze: un apel telefonic este
respins, iar o cerere de sesiune widget eșuează cu 400. Răspunsurile webhook pentru agenți salvați
folosesc î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 căruia nu îi este atribuit niciun
agent pentru apeluri primite și configurați webhook-ul numărului de telefon sau al organizației; cheile widget folosesc
mode="webhook". Notificările primite de la sistemul de endpointuri nu furnizează răspunsuri de configurare blocante.
Webhook de configurare a apelului pentru agent
Pentru a păstra un număr atribuit agentului său și a completa numai valorile apelului, configurați pentru agent un webhook de configurare a apelului.
Înainte ca agentul să răspundă la fiecare apel de intrare pe un număr, webhookul primește apelul și ID-ul, numele și versiunea agentului și răspunde cu aceleași variables, context, language și timezone pentru fiecare apel ca mai sus, fără a necesita un agent_id. Un agent
ale cărui setări utilizează un substituent fără valoare implicită are nevoie de acest webhook pentru a răspunde la un număr de telefon: apelul nu începe dacă webhookul eșuează. Substituenții cu o valoare implicită, cum ar fi {{name|there}}, permit agentului să răspundă fără acesta.
Antete SIP
Apelurile care ajung la un agent vocal prin SIP (o adresă SIP sau
un număr într-o conexiune SIP manuală) pot include context în antetele X-* și
User-to-User. Fiecare devine o variabilă sip_, precum
{{sip_x_amzn_connectcontactid}} sau {{sip_uui}}, cu cea mai mică
prioritate: prevalează o valoare cu același nume din API sau dintr-un webhook. Consultați
Transmiterea contextului apelului în antete SIP.
Valorile antetelor sunt setate de expeditor, așa că tratați-le ca nefiabile, la fel ca orice
valoare furnizată de browser.
API pentru sesiuni widget
POST /v1/widget/session acceptă variables și language la nivel superior. Cheia sa publicabilă
selectează agentul salvat. Cheile în modul webhook redirecționează aceste valori către
webhookul de configurare și îmbină răspunsul conform descrierii de mai sus.
variables ale widgetului furnizate de browser sunt controlate de client, redirecționate
verbatim în web.incoming după validarea și curățarea șirurilor descrise
mai sus și replicate în webhookurile de finalizare și în istoricul apelurilor. Nu le tratați
ca date de identitate sau autorizare de încredere.
Câmpul context al browserului propriului widget este diferit: acesta transportă text de pe
pagina pe care se află vizitatorul, pe care agentul îl tratează ca conținut de site web (vedeți
Integrarea widgetului web). Contextul per apel al unui apel din widget
provine din webhookul de configurare al unei chei în modul webhook, conform celor de mai sus. Când un
apel le are pe ambele, contextul per apel este primul, urmat de conținutul paginii.
API pentru sesiuni în timp real
POST /v1/realtime/sessions acceptă variables, context și language la nivel superior, alături de agent_id sau de o config integrată:
{
"agent_id": 12,
"variables": {"name": "Ada"},
"context": "Ada is calling from the front desk about a guest's lost key card."
}context este permis numai la nivel superior; un config inline îl respinge ca
câmp necunoscut.
WebSocket în timp real
Cu un agent salvat, promptul implementat al agentului salvat rămâne promptul său.
session.instructions devine contextul apelului, session.prompt.variables
(sau session.config.variables) devin variabilele sale, iar session.language
devine limba sa pentru fiecare apel. Selectați agentul cu
session.prompt.id în primul session.update, care pornește sesiunea odată ce
sosește acea actualizare:
{
"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 în URL-ul conexiunii pornește agentul imediat ce socketul se
conectează, înainte de orice session.update, astfel încât nu include date de
intrare pentru fiecare apel. Adăugați &wait_for_session_update=1 pentru a aștepta primul session.update și a utiliza instrucțiunile și variabilele acestuia.
Într-o sesiune inline (fără agent salvat), session.instructions este promptul propriu-zis, ca înainte. Apelurile de test din browser și simulările rezolvă valorile implicite și substituenții lipsă. Pentru a testa cu valori, salvați un
exemplu de configurare a apelului în agent și selectați-l când porniți testul; apelul rulează ca și cum webhookul dumneavoastră de configurare a apelului ar fi răspuns cu acesta.
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"]
}prompt_snapshot al apelului (GET /v1/calls/{call_id}) afișează promptul
agentului, cu variabilele completate și blocul de context adăugat.
Stocați identificatorul CRM sau al sarcinii în obiectul de variabile pentru a asocia apelul finalizat cu înregistrarea sa sursă. Variabilele și contextul sunt păstrate împreună cu înregistrarea apelului; trimiteți doar informații adecvate pentru păstrarea în istoricul apelurilor și în webhookuri.
Reluările unui apel, în seturi de validare, execuții de reluare și analize, utilizează variabilele și contextul acelui apel împreună cu promptul testat, astfel încât o reluare testează ce i s-ar fi transmis agentului în acel apel.
Compatibilitate cu prompturile existente
Redarea se aplică și prompturilor existente pentru agenți salvați și variante A/B, configurațiilor inline pentru apeluri efectuate ș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 test din browser și simulările aplică același comportament implicit/de text gol, cu excepția cazului în care alegeți un eșantion de configurare a apelului salvat.