Open in
Mainīgie un konteksts katram zvanam
Piešķiriet katram zvanam tā unikālo informāciju kā nosauktus mainīgos uzvednei vai brīvas formas kopsavilkumu, nemainot balss aģentu.
Katram zvanam var būt divu veidu ievade katram zvanam. Izmantojiet vienu no tām vai abas kopā:
variables: nosauktas vērtības, kas uzvednē aizpilda{{placeholders}}. Izmantojiet tās laukiem, uz kuriem uzvedne atsaucas pēc nosaukuma, piemēram, zvanītāja vārdam, konta numuram vai pieraksta laikam.context: brīvas formas teksts, kas tiek pievienots pēc uzvednes. Izmantojiet to īsam aprakstam, kas neietilpst veidnē, piemēram, šī zvana uzdevuma aprakstam vai iepriekš apkopotām piezīmēm.
Abas darbojas ar saglabātu balss aģentu un iekļauto konfigurāciju visos tālāk aprakstītajos zvana sākšanas veidos. Neviena no tām nemaina saglabāto balss aģentu, tā versiju vēsturi vai citus iestatījumus.
{
"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."
}Mainīgie
Ievietojiet vietturus sava saglabātā balss aģenta uzvednē, pēc tam, sākot zvanu, norādiet objektu variables. ThunderPhone atveido tekstu pirms zvana konfigurācijas nosūtīšanas uz balss izpildlaiku.
Ja vērtības nav nepieciešamas, izlaidiet variables; nesūtiet null (tiek noraidīts ar 400).
Vietturi un noklusējuma vērtības
You are calling {{name|Friend}} about account {{account_id}}.
The available appointment is {{ appointment_slot }}.Nosaukumi ir reģistrjutīgi un atbilst [A-Za-z_][A-Za-z0-9_]*. Atstarpes ap
nosaukumu ir atļautas; atstarpe pēc | ir noklusējuma vērtības daļa un tiek
saglabāta. {{name|Friend}} izmanto Friend, ja name nav norādīts vai ir
null; tukša virkne ir skaidri norādīta vērtība. Trūkstošās vērtības bez
noklusējuma vērtības kļūst par tukšām virknēm, un to nosaukumi tiek parādīti
unresolved_variables. Teksts starp divkāršajām figūriekavām, kas nav derīgs
vietturis, tiek noņemts. Divkāršajās figūriekavās ietvertais teksts katrā
norādītajā vērtībā tiek noņemts neatkarīgi; vērtība nevar noņemt apkārtējo
uzvednes tekstu vai citu vērtību. Tiek noņemti arī nesaskaņoti divkāršo
figūriekavu atdalītāji. JSON piemēros uzvednēs nedrīkst izmantot {{.
Vērtības ir vienkāršs teksts, tās nekad netiek izpildītas
kā kods vai rekursīvi izvērstas kā veidnes.
Mainīgie var būt arī apstiprinājuma uzvednēs, izejošo balss pasta ziņojumos
un piekrišanas paziņojuma tekstā, ja šis lauks tiek nosūtīts tālruņa zvanam.
Aģentam nav atsevišķa lauka first_message: tā sākuma norādījumus ievietojiet
uzvednē. Esošie balss pasta vietturi {agent_name} un {org_name}
turpina darboties.
Vērtības un ierobežojumi
Vērtības var būt virknes, skaitļi, Būla vērtības vai null; Būla vērtības tiek attēlotas kā true
un false. Unicode vadības (Cc) rakstzīmes, izņemot jaunrindu (\n), tabulēšanu (\t)
un rindas pārnesi (\r), formāta (Cf) rakstzīmes, izņemot nulles platuma
nesavienotāju un savienotāju (U+200C, U+200D, kas veido vārdus indiešu un
arābu rakstības valodās), kā arī aizstājējrakstzīmju (Cs) koda punkti tiek noņemti; \r\n
tiek normalizēts uz \n. Katra vērtība
attēlošanas laikā ir ierobežota līdz 2 000 rakstzīmēm. Iesniegtās virknes tiek arī attīrītas un
saīsinātas pirms saglabāšanas. Sākotnējam objektam jāietilpst 32 KB UTF-8 JSON; lielākiem objektiem
zvanu/sesiju pieprasījumos tiek atgriezts 400, savukārt
kampaņu importēšanas laikā nederīgās rindas tiek norādītas atsevišķi. Masīvi un ligzdoti objekti netiek
pieņemti kā vērtības. Neatbilstošas metadatu atslēgas (piemēram, CSV galvene ar
atstarpi) tiek saglabātas un atgrieztas, taču uz tām nevar atsaukties ar vietturi.
Konteksts
context ir virkne līdz 20 000 rakstzīmēm. ThunderPhone to pievieno aiz
uzvednes, kad uzvednes mainīgie ir aizpildīti, kā norobežotu bloku:
<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>Balss aģents to lasa kopā ar saviem norādījumiem, tāpēc rakstiet to tā,
it kā pirms zvana informētu kolēģi. Konteksts nav veidne:
tajā ietvertais {{name}} paliek rakstīts nemainīts. Ja tekstam nepieciešama vērtība, ievietojiet to
paši pirms nosūtīšanas.
null, tukša virkne vai tikai atstarpes nozīmē, ka konteksta nav.- Vērtība, kas nav virkne vai ir garāka par 20 000 rakstzīmēm, tiek noraidīta ar
400zvanu un sesiju pieprasījumos; konfigurācijas tīmekļa aizķerī tā izraisa apmaiņas kļūdu, tāpat kā nederīgsvariables(skatiet tālāk). - Sākuma un beigu atstarpes tiek apgrieztas, un tiek noņemtas tās pašas vadības un formāta rakstzīmes kā mainīgo vērtībās.
- Konteksts ir daļa no zvana uzvednes, tāpēc tas tiek ieskaitīts zvana uzvednes apjomā.
soļu balss aģentam konteksts seko katra zvanā esošā balss aģenta uzvednei, nevis katra soļa norādījumiem.
No kurienes tiek iegūtas vērtības
Izejošā API
Nosūtot POST /v1/call, iekļaujiet variables un context:
{
"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."
}Abi darbojas arī ar tālruņa numura noklusējuma izejošo balss aģentu vai ar iekļautu
config.prompt. Izmantojot iekļautu konfigurāciju, context var būt arī config
iekšpusē — tajā pašā laukā, ko atgriež konfigurācijas tīmekļa aizķere; ja nosūtāt abus, tiem jābūt vienādam tekstam. Idempotences atslēgu nevar izmantot atkārtoti ar atšķirīgiem mainīgajiem vai atšķirīgu kontekstu.
Kampaņas CSV
CSV kolonnas, kas nav tālruņa numuri, jau tiek glabātas kā kontaktu mainīgie. Katrs zvans tās tagad izmanto automātiski. Izmantojiet galvenes, piemēram, name, account_id un appointment_slot, lai tās atbilstu jūsu vietturiem. Esošā vārda kartēšana var apvienot vārda un uzvārda kolonnas mainīgajā name. Kampaņas kontaktiem nav katram kontaktam specifiska konteksta.
Dinamiskās konfigurācijas tīmekļa aizķere
Bloķējošās konfigurācijas tīmekļa aizķeres ceļā atgrieziet savā organizācijā saglabātu balss aģentu un visas zvana līmeņa vērtības. Full duplex balss aģentam zvans saglabā aģenta balsi pat tad, ja zvans sākas citā atbalstītā valodā: šim zvanam netiek piemērota balsu piesaiste katrai valodai un vietējā balss pārslēgšana.
{
"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."
}Atbildes mainīgie pārraksta pieprasījuma līmeņa mainīgos, bet pārējās pieprasījuma
atslēgas paliek nemainīgas. Atbildes vērtība null atlasa viettura noklusējuma vērtību.
Apvienotajam objektam arī jāietilpst 32 KB. Saglabātā aģenta atbildes pieņem tikai
agent_id, variables, context, language un katram zvanam atsevišķu
timezone; atgrieziet iekļautu konfigurāciju, ja nepieciešams
aizstāt uzvedni vai citus iestatījumus. Ja atbilde iestata language
aģentam, kas nav Full duplex aģents, zvanā tiek izmantota arī attiecīgās valodas balss,
ja aģentam tā ir iestatīta. Atbilde, kurā ir prompt, vienmēr izmanto iekļautu
konfigurāciju: jebkurš šajā atbildē esošais agent_id tiek ignorēts, tostarp nulles vai
nevesela skaitļa metadati. Iekļautajai uzvednei joprojām jāiztur standarta validācija.
Iekļautās tīmekļa aizķeres atbildes var ietvert arī variables un context. Ja context
nav virkne vai ir pārāk garš, apmaiņa neizdodas: tālruņa zvans tiek
noraidīts, un logrīka sesijas pieprasījums neizdodas ar 400. Saglabātā aģenta tīmekļa aizķeres
atbildēs gan tālruņa, gan logrīka zvaniem tiek izmantots aģenta izvietotais A/B sadalījums;
mainīgie tiek atveidoti pēc varianta atlases. Ienākošajiem tālruņa zvaniem izmantojiet numuru bez piešķirta ienākošā
aģenta un konfigurējiet tā tālruņa numura vai organizācijas tīmekļa aizķeri; logrīka atslēgās izmantojiet
mode="webhook". Galapunktu sistēmas ienākošie paziņojumi nesniedz bloķējošas
konfigurācijas atbildes.
Balss aģenta zvana iestatīšanas tīmekļa āķis
Lai numurs paliktu piesaistīts savam balss aģentam un tiktu aizpildītas tikai zvana vērtības, piešķiriet balss aģentam zvana iestatīšanas tīmekļa aizķeri.
Pirms katra ienākošā zvana, uz kuru balss aģents atbild numurā, tīmekļa aizķere saņem zvanu un balss aģenta ID, nosaukumu un versiju, un atbild ar tām pašām iepriekš minētajām variables, context, language un katra zvana timezone vērtībām, bez nepieciešamības norādīt agent_id. Balss aģentam,
kura iestatījumos tiek izmantots vietturis bez noklusējuma vērtības, šī tīmekļa aizķere ir nepieciešama, lai atbildētu uz tālruņa numuru: ja tīmekļa aizķere neizdodas, zvans nesākas. Vietturi ar noklusējuma vērtību, piemēram, {{name|there}}, ļauj balss aģentam atbildēt arī bez tās.
SIP galvenes
Zvani, kas sasniedz balss aģentu, izmantojot SIP (izmantojot SIP adresi vai
numuru manuālā SIP savienojumā), var ietvert kontekstu X-* un
User-to-User galvenēs. Katra no tām kļūst par sip_ mainīgo, piemēram,
{{sip_x_amzn_connectcontactid}} vai {{sip_uui}}, ar viszemāko
prioritāti: uzvar tāda paša nosaukuma vērtība no API vai tīmekļa aizķeres. Skatiet
Zvanu konteksta nodošana SIP galvenēs.
Galveņu vērtības nosaka sūtītājs, tāpēc uzskatiet tās par neuzticamām, tāpat kā jebkuru
pārlūkprogrammas nodrošinātu vērtību.
Logrīka sesijas API
POST /v1/widget/session pieņem augstākā līmeņa variables un language. Tās publicējamā
atslēga atlasa saglabāto balss aģentu. Tīmekļa aizķeres režīma atslēgas pārsūta šīs vērtības uz
konfigurācijas tīmekļa aizķeri un sapludina atbildi, kā aprakstīts iepriekš.
Pārlūka nodrošinātie logrīka variables tiek kontrolēti klienta pusē, pēc iepriekš
aprakstītās validācijas un virkņu tīrīšanas tiek burtiski pārsūtīti sadaļā web.incoming
un tiek atspoguļoti pabeigšanas tīmekļa aizķerēs un zvanu vēsturē. Neuzskatiet tos
par uzticamiem identitātes vai autorizācijas datiem.
Logrīka pārlūkprogrammas context lauks atšķiras: tas satur tekstu no
lapas, kurā atrodas apmeklētājs un kuru balss aģents uzskata par vietnes saturu (skatiet
Iegult tīmekļa logrīku). Logrīka zvana katra zvana
konteksts, kā norādīts iepriekš, nāk no webhook režīma atslēgas konfigurācijas webhook. Ja
zvanam ir abi, vispirms tiek izmantots katra zvana konteksts, pēc tam lapas saturs.
Reāllaika sesijas API
POST /v1/realtime/sessions pieņem augstākā līmeņa variables, context un language
kopā ar agent_id vai iekļautu config:
{
"agent_id": 12,
"variables": {"name": "Ada"},
"context": "Ada is calling from the front desk about a guest's lost key card."
}context tiek norādīts tikai augstākajā līmenī; iekļauta config to noraida kā
nezināmu lauku.
Reāllaika WebSocket
Ar saglabātu balss aģentu saglabātā balss aģenta izvietotā uzvedne paliek tā uzvedne.
session.instructions kļūst par zvana kontekstu, session.prompt.variables
(vai session.config.variables) kļūst par tā mainīgajiem, bet session.language
kļūst par tā valodu katram zvanam. Atlasiet balss aģentu ar
session.prompt.id pirmajā session.update, kas sāk sesiju, tiklīdz
tiek saņemts šis atjauninājums:
{
"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 savienojuma URL sāk aģentu, tiklīdz tiek izveidots ligzdas
savienojums, pirms jebkāda session.update, tāpēc tam nav katram zvanam paredzētas ievades. Pievienojiet
&wait_for_session_update=1, lai gaidītu pirmo session.update un izmantotu tā
instrukcijas un mainīgos.
Iekļautā sesijā (bez saglabāta aģenta) session.instructions ir pati uzvedne,
kā iepriekš. Mikrofons sadaļā Builder un simulētie testa zvani nosaka noklusējuma vērtības un
trūkstošos vietturus, taču tiem nav katram zvanam paredzētu mainīgo vai konteksta ievades.
Pēc zvana
GET /v1/calls, GET /v1/calls/{call_id}, telephony.complete un web.complete ietver
galīgos apvienotos variables un unresolved_variables. Mantotās pabeigšanas kravas,
kurās ir data.history, tās arī ietver:
{
"variables": {"name": "Ada", "account_id": "A-17"},
"unresolved_variables": ["appointment_slot"]
}Zvanu prompt_snapshot (GET /v1/calls/{call_id}) parāda balss aģenta
uzvedni ar aizpildītiem mainīgajiem un pievienotu konteksta bloku.
Saglabājiet savu CRM vai uzdevuma identifikatoru mainīgo objektā, lai pabeigto zvanu sasaistītu ar tā avota ierakstu. Mainīgie un konteksts tiek saglabāti kopā ar zvana ierakstu; sūtiet tikai tādu informāciju, kuru ir pieņemami saglabāt zvanu vēsturē un tīmekļa aizķerēs.
Zvanu atkārtojumi validācijas kopās, atkārtojumu izpildēs un izmeklēšanās izmanto attiecīgā zvana mainīgos un kontekstu ar testējamo uzvedni, lai atkārtojums pārbaudītu, kāda informācija būtu sniegta šī zvana balss aģentam.
Saderība ar esošajām uzvednēm
Atveidošana attiecas arī uz esošajām saglabāto aģentu un A/B variantu uzvednēm, iekļautajām
izejošo un reāllaika konfigurācijām, kā arī uzvednēm, kas tiek atgrieztas no konfigurācijas
tīmekļa aizķerēm. Nezināmi vietturi {{name}} kļūst par tukšu tekstu pat tad, ja nav
norādīti variables. Pirms ieviešanas pārbaudiet esošās uzvednes, tostarp ārēji nodrošinātas iekļautās/tīmekļa aizķeru uzvednes, kuras ThunderPhone nevar inventarizēt.
Veidotāja mikrofona un simulācijas zvaniem tiek piemērota tā pati noklusējuma/tukšuma darbība.