ThunderPhone v3 ir klāt.Sāciet patstāvīgi — no 2 ¢/min.Lasīt paziņojumu

Developer cookbook

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 400 zvanu un sesiju pieprasījumos; konfigurācijas tīmekļa aizķerī tā izraisa apmaiņas kļūdu, tāpat kā nederīgs variables (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.