Open in
Puhelukohtaiset muuttujat ja konteksti
Anna jokaiselle puhelulle omat tiedot nimettyinä muuttujina kehotetta varten tai vapaamuotoisena tiivistelmänä muuttamatta agenttia.
Jokaisella puhelulla voi olla kahdenlaisia puhelukohtaisia syötteitä. Käytä jompaakumpaa tai molempia yhdessä:
variables: nimettyjä arvoja, jotka täyttävät kehotteen{{placeholders}}-paikkamerkit. Käytä niitä kentille, joihin kehote viittaa nimellä, kuten soittajan nimelle, tilinumerolle tai varausajalle.context: vapaamuotoista tekstiä, joka lisätään kehotteen jälkeen. Käytä sitä tiivistelmään, joka ei sovi mallipohjaan, kuten tämän puhelun tehtävän kuvaukseen tai aiemmin kerättyihin muistiinpanoihin.
Molemmat toimivat tallennetun agentin ja sisäisen määrityksen kanssa kaikilla alla kuvatuilla tavoilla aloittaa puhelu. Kumpikaan ei muuta tallennettua agenttia, sen versiohistoriaa tai muita asetuksia.
{
"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."
}Muuttujat
Lisää paikkamerkit tallennetun agenttisi kehotteeseen ja anna sitten variables-
objekti puhelua aloittaessasi. ThunderPhone hahmontaa tekstin ennen
puhelukokoonpanon lähettämistä puheaikaiselle suoritusympäristölle.
Kun arvoja ei tarvita, jätä variables pois. Älä lähetä arvoa null (hylätään koodilla 400).
Paikkamerkit ja oletusarvot
You are calling {{name|Friend}} about account {{account_id}}.
The available appointment is {{ appointment_slot }}.Nimet erottelevat kirjainkoon ja noudattavat muotoa [A-Za-z_][A-Za-z0-9_]*. Välilyönnit
nimen ympärillä ovat sallittuja; |-merkin jälkeinen välilyönti on osa oletusarvoa ja
säilytetään. {{name|Friend}} käyttää arvoa Friend, kun name puuttuu tai sen arvo on
null; tyhjä merkkijono on nimenomaisesti annettu arvo. Puuttuvat arvot ilman
oletusarvoa muuttuvat tyhjiksi merkkijonoiksi, ja niiden nimet näkyvät kentässä
unresolved_variables. Kaksoisaaltosulkeiden välissä oleva teksti, joka ei ole
kelvollinen paikkamerkki, poistetaan. Kussakin annetussa arvossa olevat
kaksoisaaltosulkeissa olevat tekstit poistetaan itsenäisesti; arvo ei voi poistaa
ympäröivää kehotetekstiä tai toista arvoa. Myös täsmäämättömät kaksoisaaltosulkeiden
erottimet poistetaan. Kehotteissa olevissa JSON-esimerkeissä ei saa käyttää merkintää {{.
Arvot ovat pelkkää tekstiä, eikä niitä koskaan arvioida
koodina tai laajenneta rekursiivisesti malleina.
Muuttujia voi esiintyä myös kuittauskehotteissa, lähtevissä vastaajaviesteissä
ja suostumusilmoituksen tekstissä, kun kyseinen kenttä lähetetään puhelua varten.
Agentilla ei ole erillistä first_message-kenttää: lisää sen aloitusohjeet
kehotteeseen. Nykyiset vastaajaviestin {agent_name}- ja {org_name}-
paikkamerkit toimivat edelleen.
Arvot ja rajoitukset
Arvot voivat olla merkkijonoja, lukuja, totuusarvoja tai null; totuusarvot esitetään
muodossa true ja false. Unicode-ohjausmerkit (Cc) rivinvaihtoa (\n), sarkainta (\t)
ja rivinvaihtopalautusta (\r) lukuun ottamatta, muotoilumerkit (Cf) nollaleveää
ei-yhdistäjää ja yhdistäjää (U+200C, U+200D, joilla muodostetaan sanoja intialaisia
kirjoitusjärjestelmiä ja arabialaista kirjoitusta käyttävissä kielissä) lukuun ottamatta sekä
surrogaattikoodipisteet (Cs) poistetaan; \r\n
normalisoidaan muotoon \n. Kukin arvo
on renderöitäessä rajoitettu 2,000 merkkiin. Toimitetut merkkijonot puhdistetaan ja
katkaistaan myös ennen tallennusta. Alkuperäisen objektin on mahduttava 32 KB:n
UTF-8 JSONiin; suuremmat objektit saavat 400-virheen puhelu-/istuntopyynnöissä,
kun taas kampanjatuonnit ilmoittavat virheellisistä riveistä erikseen. Taulukoita ja sisäkkäisiä objekteja ei
hyväksytä arvoiksi. Vaatimuksia vastaamattomat metatietoavaimet (esimerkiksi välilyönnin sisältävä CSV-otsikko)
säilytetään ja palautetaan, mutta niihin ei voi viitata paikkamerkillä.
Konteksti
context on enintään 20,000 merkin merkkijono. ThunderPhone lisää sen kehotteen jälkeen,
kun kehotteen muuttujat on täytetty, rajattuna lohkona:
<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>Agentti lukee sen yhdessä ohjeidensa kanssa, joten kirjoita se kuten
ohjeistaisit kollegaa ennen puhelua. Konteksti ei ole malli:
sen sisällä oleva {{name}} säilyy kirjoitetussa muodossa. Jos teksti tarvitsee arvon, lisää arvo
itse ennen lähettämistä.
null, tyhjä merkkijono tai pelkkä välilyönti tarkoittaa, ettei kontekstia ole.- Arvo, joka ei ole merkkijono tai on yli 20 000 merkkiä pitkä, hylätään
400-virheellä puhelu- ja istuntopyynnöissä; määrityswebhookista se epäonnistuu vaihdon tavoin kuin virheellisetvariables-arvot (katso alla). - Alussa ja lopussa oleva tyhjä tila poistetaan, samoin kuin muuttuja-arvoissa käytetyt ohjaus- ja muotoilumerkit.
- Konteksti on osa puhelun kehotetta, joten se lasketaan mukaan puhelun kehotteen kokoon.
vaiheet-agentissa konteksti seuraa puhelun jokaisen agentin kehotetta, ei yksittäisen vaiheen ohjeita.
Mistä arvot tulevat
Lähtevien puhelujen API
Lähetä variables ja context pyynnössä 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."
}Molemmat toimivat myös puhelinnumeron oletuslähtevän puheagentin kanssa tai upotetun
config.prompt-määrityksen kanssa. Upotetussa määrityksessä context voi olla myös config-objektin sisällä,
samassa kentässä, jonka määrityswebhook palauttaa. Jos lähetät molemmat, niiden on oltava
samaa tekstiä. Idempotenssiavainta ei voi käyttää uudelleen eri muuttujien tai eri kontekstin kanssa.
Kampanjan CSV
Muut kuin puhelinnumeroa sisältävät CSV-sarakkeet tallennetaan jo yhteystietomuuttujiksi. Jokainen soitto käyttää niitä nyt automaattisesti. Käytä otsikoita, kuten name, account_id ja appointment_slot, vastaamaan paikkamerkkejäsi. Nykyinen nimikartoitus voi yhdistää etu- ja sukunimisarakkeet muuttujaan name. Kampanjan yhteystiedoilla ei ole yhteystietokohtaista kontekstia.
Dynaamisen määrityksen webhook
Estävää määritystä käyttävässä webhook-polussa palauta organisaatioosi tallennettu agentti sekä mahdolliset puhelukohtaiset arvot. Full duplex -agentilla puhelu säilyttää agentin äänen, vaikka puhelu alkaisi toisella tuetulla kielellä: kielikohtaisia äänimäärityksiä ja natiivia äänien vaihtoa ei käytetä kyseisessä puhelussa.
{
"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."
}Vastauksen muuttujat korvaavat pyyntötason muuttujat, kun taas muut pyynnön
avaimet säilyvät. Vastauksen arvo null valitsee paikkamerkin oletusarvon.
Yhdistetyn objektin on myös mahduttava 32 kilotavuun. Tallennetun agentin vastaukset hyväksyvät vain
agent_id-, variables-, context-, language-avaimet sekä kutsukohtaisen
timezone-asetuksen; palauta sisäinen määritys, kun sinun täytyy
korvata kehote tai muita asetuksia. Tallennetun agentin webhook-vastaukset
käyttävät agentin käyttöönotettua A/B-jakoa sekä puheluissa että widget-kutsuissa;
muuttujat hahmonnetaan variantin valinnan jälkeen. Kun vastaus asettaa language-asetuksen
muulle kuin Full duplex -agentille, puhelu käyttää myös kyseisen kielen omaa ääntä, jos
agentille on määritetty sellainen. prompt-kentän sisältävä vastaus käyttää aina sisäistä
määritystä: kaikki vastauksen agent_id-arvot ohitetaan, mukaan lukien null- tai
ei-kokonaislukumetadatat. Sisäisen kehotteen on silti läpäistävä tavallinen validointi.
Sisäiset webhook-vastaukset voivat sisältää myös variables- ja context-kentät. context,
joka ei ole merkkijono tai on liian pitkä, epäonnistaa vaihdon: puhelu
hylätään ja widget-istuntopyyntö epäonnistuu koodilla 400. Tallennetun agentin webhook-vastaukset
käyttävät agentin käyttöönotettua A/B-jakoa sekä puheluissa että widget-kutsuissa;
muuttujat hahmonnetaan variantin valinnan jälkeen. Saapuvissa puheluissa käytä numeroa, jolle ei ole määritetty saapuvaa
agenttia, ja määritä sen puhelinnumeron tai organisaation webhook; widget-avaimet käyttävät
mode="webhook"-asetusta. Päätepistejärjestelmän saapuvat ilmoitukset eivät tarjoa estäviä
määritysvastauksia.
Agentin puhelun määrityswebhook
Jotta numero pysyy määritettynä agentilleen ja täytät vain puhelun arvot,
anna agentille puhelun alustuswebhook.
Ennen jokaista saapuvaa puhelua, johon agentti vastaa numerossa, webhook vastaanottaa
puhelun sekä agentin tunnuksen, nimen ja version ja vastaa samoilla
variables-, context-, language- ja puhelukohtaisilla timezone-arvoilla kuin yllä ilman agent_id-tunnusta. Agentti,
jonka asetuksissa käytetään oletusarvotonta paikkamerkkiä, tarvitsee tämän webhookin vastatakseen
puhelinnumeroon: puhelu ei ala, jos webhook epäonnistuu. Oletusarvon sisältävät paikkamerkit,
kuten {{name|there}}, antavat agentin vastata ilman sitä.
SIP-otsakkeet
Puheagentin SIPin kautta tavoittaviin puheluihin (käyttäen SIP-osoitetta tai numeroa manuaalisessa SIP-yhteydessä) voidaan liittää kontekstitietoa X-*- ja User-to-User-otsakkeissa. Jokaisesta tulee sip_-muuttuja, kuten {{sip_x_amzn_connectcontactid}} tai {{sip_uui}}, jolla on alhaisin prioriteetti: API:sta tai webhookista saatu samanniminen arvo ohittaa sen. Katso Välitä puhelukonteksti SIP-otsakkeissa.
Lähettäjä asettaa otsakearvot, joten käsittele niitä epäluotettavina, kuten mitä tahansa selaimen toimittamaa arvoa.
Widget-istunnon API
POST /v1/widget/session hyväksyy ylimmän tason variables- ja language-kentät. Sen julkaistava
avain valitsee tallennetun agentin. Webhook-tilan avaimet välittävät nämä arvot
määrityswebhookille ja yhdistävät vastauksen yllä kuvatulla tavalla.
Selaimen toimittamat widgetin variables-arvot ovat asiakkaan hallitsemia, ja ne välitetään
sellaisenaan kentässä web.incoming yllä kuvatun validoinnin ja merkkijonojen puhdistuksen
jälkeen sekä sisällytetään valmistumiswebhookeihin ja puheluhistoriaan. Älä käsittele niitä
luotettavina identiteetti- tai valtuutustietoina.
Widgetin oma selaimen context-kenttä on erilainen: se sisältää tekstiä
sivulta, jolla kävijä on, ja agentti käsittelee sitä verkkosivuston sisältönä (katso
Upota verkkowidget). Widget-puhelun puhelukohtainen
konteksti tulee verkkokoukkutilan avaimen määritysverkkokoukusta, kuten yllä. Kun
puhelussa on molemmat, puhelukohtainen konteksti tulee ensin ja sitten sivun sisältö.
Reaaliaikaisen istunnon API
POST /v1/realtime/sessions hyväksyy ylimmällä tasolla variables, context ja language
agent_id:n tai sisäisen config:n rinnalla:
{
"agent_id": 12,
"variables": {"name": "Ada"},
"context": "Ada is calling from the front desk about a guest's lost key card."
}context kuuluu vain ylätasolle; sisäinen config hylkää sen
tuntemattomana kenttänä.
Reaaliaikainen WebSocket
Tallennetun agentin julkaistu kehote säilyy sen kehotteena.
session.instructions toimii puhelun kontekstina, session.prompt.variables
(tai session.config.variables) toimii sen muuttujina ja session.language
toimii puhelukohtaisena kielenä. Valitse agentti ensimmäisessä
session.update-päivityksessä session.prompt.id-kentällä, mikä käynnistää istunnon,
kun päivitys saapuu:
{
"type": "session.update",
"session": {
"type": "realtime",
"prompt": {"id": "12", "variables": {"name": "Ada"}},
"instructions": "Ada asked for a callback about her delivery window."
}
}Yhteys-URL-osoitteessa oleva ?agent_id=12 käynnistää agentin heti, kun socket
yhdistyy, ennen mitään session.update-päivitystä, joten sillä ei ole puhelukohtaista syötettä. Lisää
&wait_for_session_update=1, jos haluat odottaa ensimmäistä session.update-päivitystä ja käyttää sen
ohjeita ja muuttujia.
Inline-istunnossa (ilman tallennettua agenttia) session.instructions on itse kehote, kuten aiemmin. Selaimen testipuhelut ja simulaatiot ratkaisevat oletusarvot ja puuttuvat paikkamerkit. Testaa arvoilla tallentamalla agentille
puhelun määritysesimerkki ja valitsemalla sen, kun aloitat testin; puhelu suoritetaan ikään kuin puhelun määrityswebhookisi olisi vastannut sillä.
Puhelun jälkeen
GET /v1/calls, GET /v1/calls/{call_id}, telephony.complete ja web.complete sisältävät
lopulliset yhdistetyt variables- ja unresolved_variables-kentät. Vanhat valmistumisen hyötykuormat,
jotka sisältävät data.history, sisältävät myös ne:
{
"variables": {"name": "Ada", "account_id": "A-17"},
"unresolved_variables": ["appointment_slot"]
}Puhelun prompt_snapshot (GET /v1/calls/{call_id}) näyttää agentin kehotteen,
johon sen muuttujat on täytetty ja kontekstilohko lisätty.
Tallenna CRM- tai tehtävätunnisteesi muuttujaobjektiin, jotta voit yhdistää valmistuneen puhelun takaisin sen lähdetietueeseen. Muuttujat ja konteksti säilytetään puhelutietueen yhteydessä; lähetä vain tietoja, jotka on asianmukaista säilyttää puheluhistoriassa ja webhookeissa.
Puhelun uudelleentoistot validointijoukoissa, uudelleentoistoajoissa ja tutkimuksissa käyttävät kyseisen puhelun muuttujia ja kontekstia testattavan kehotteen kanssa, joten uudelleentoisto testaa, mitä kyseisen puhelun agentille olisi kerrottu.
Yhteensopivuus olemassa olevien kehotteiden kanssa
Renderöinti koskee myös olemassa olevia tallennettujen agenttien ja A/B-varianttien kehotteita, upotettuja lähtevien puhelujen ja reaaliaikaisia määrityksiä sekä määrityswebhookeista palautettuja kehotteita. Tuntemattomista {{name}}-paikkamerkeistä tulee tyhjää tekstiä, vaikka variables-arvoja ei annettaisi. Tarkista olemassa olevat kehotteet ennen käyttöönottoa, mukaan lukien ulkoisesti toimitetut upotetut/webhook-kehotteet, joita ThunderPhone ei voi luetteloida. Selainpohjaiset testipuhelut ja simulaatiot käyttävät samaa oletus-/tyhjää toimintatapaa, ellet valitse tallennettua puheluasetusten mallia.