Open in
Variabler og kontekst pr. opkald
Giv hvert opkald sine egne oplysninger som navngivne variabler til prompten eller en kort, frit formuleret briefing uden at ændre agenten.
Hvert opkald kan indeholde to typer input pr. opkald. Brug enten den ene eller begge sammen:
variables: navngivne værdier, der udfylder{{placeholders}}i prompten. Brug dem til felter, som prompten henviser til ved navn, f.eks. opkalderens navn, et kontonummer eller et aftaletidspunkt.context: fri tekst, der tilføjes efter prompten. Brug den til en briefing, der ikke passer i en skabelon, f.eks. en beskrivelse af opgaven for dette opkald eller noter indsamlet tidligere.
Begge fungerer med en gemt agent og med en integreret konfiguration, uanset hvordan du starter et opkald som beskrevet nedenfor. Ingen af dem ændrer den gemte agent, dens versionshistorik eller dens øvrige indstillinger.
{
"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."
}Variabler
Indsæt pladsholdere i din gemte agents prompt, og angiv derefter et variables-
objekt, når du starter et opkald. ThunderPhone gengiver teksten, før det sender
opkaldskonfigurationen til stemmekørselstiden.
Når der ikke er behov for værdier, skal du udelade variables og ikke sende null (afvises med 400).
Pladsholdere og standardværdier
You are calling {{name|Friend}} about account {{account_id}}.
The available appointment is {{ appointment_slot }}.Navne skelner mellem store og små bogstaver og følger [A-Za-z_][A-Za-z0-9_]*. Mellemrum omkring
navnet er tilladt; mellemrum efter | er en del af standardværdien og
bevares. {{name|Friend}} bruger Friend, når name mangler eller er
null; en tom streng er en eksplicit angivet værdi. Manglende værdier uden
en standardværdi bliver til tomme strenge, og deres navne vises i unresolved_variables.
Tekst mellem dobbelte krøllede parenteser, der ikke er en gyldig pladsholder, fjernes. Tekst med dobbelte krøllede
parenteser i hver angivet værdi fjernes uafhængigt; en værdi kan ikke fjerne
omgivende prompttekst eller en anden værdi. Umatchede afgrænsere med dobbelte krøllede parenteser
fjernes også. JSON-eksempler i prompter må ikke bruge {{.
Værdier er ren tekst og evalueres aldrig
som kode eller udvides rekursivt som skabeloner.
Variabler kan også forekomme i bekræftelsesprompter, udgående voicemail-
beskeder og teksten til samtykkeerklæringen, når dette felt sendes for et
opkald. Agenten har ikke et separat first_message-felt: angiv dens indledende
instruktioner i prompten. Eksisterende voicemail-pladsholdere {agent_name} og {org_name}
fungerer fortsat.
Værdier og grænser
Værdier kan være strenge, tal, booleske værdier eller null; booleske værdier gengives som true
og false. Unicode-kontroltegn (Cc) undtagen linjeskift (\n), tabulator (\t)
og vognretur (\r), formattegn (Cf) undtagen nulbredde-ikke-sammenføjning og sammenføjning
(U+200C, U+200D, som staver ord i sprog med indisk og arabisk skrift), samt surrogatkodepunkter
(Cs) fjernes; \r\n normaliseres til \n. Hver værdi
er begrænset til 2.000 tegn, når den gengives. Angivne strenge renses og
afkortes også før lagring. Det oprindelige objekt må højst fylde 32 KB UTF-8 JSON;
større objekter modtager 400 ved opkalds-/sessionsanmodninger, mens
kampagneimporter rapporterer ugyldige rækker enkeltvis. Arrays og indlejrede objekter accepteres ikke
som værdier. Metadata-nøgler, der ikke matcher (for eksempel en CSV-overskrift med et
mellemrum), bevares og sendes tilbage, men kan ikke refereres af en pladsholder.
Kontekst
context er en streng på op til 20.000 tegn. ThunderPhone tilføjer den efter
prompten, når promptens variabler er udfyldt, som en afgrænset blok:
<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>Agenten læser den sammen med sine instruktioner, så skriv den på samme måde,
som du ville orientere en kollega før opkaldet. Kontekst er ikke en skabelon:
{{name}} i den forbliver skrevet som den er. Hvis teksten har brug for en værdi, skal du selv indsætte værdien
før afsendelse.
null, en tom streng eller kun mellemrum betyder, at der ikke er nogen kontekst.- En værdi, der ikke er en streng, eller som er længere end 20.000 tegn, afvises med
400ved opkalds- og sessionsanmodninger. Fra en konfigurationswebhook fejler udvekslingen på samme måde som ugyldigevariables(se nedenfor). - Indledende og afsluttende mellemrum fjernes, og de samme kontrol- og formateringstegn som i variabelværdier fjernes.
- Kontekst er en del af opkaldets prompt og tæller derfor med i opkaldets promptstørrelse.
For en steps-agent følger konteksten prompten for hver agent i opkaldet, ikke instruktionerne for hvert trin.
Hvor værdier kommer fra
Udgående API
Send variables og context på 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."
}Begge fungerer også med telefonnummerets standardagent til udgående opkald eller med en integreret
config.prompt. Med en integreret konfiguration kan context også placeres i config,
det samme felt, som en webhook til konfiguration returnerer. Hvis du sender begge, skal de være
den samme tekst. En idempotensnøgle kan ikke genbruges med andre variabler eller
en anden kontekst.
Kampagne-CSV
CSV-kolonner, der ikke er telefonnumre, gemmes allerede som kontaktvariabler. Hvert opkald bruger dem nu automatisk. Brug overskrifter som name, account_id og appointment_slot til at matche dine pladsholdere. Den eksisterende navnetilknytning kan kombinere kolonner med for- og efternavn i variablen name. Kampagnekontakter har ingen kontekst pr. kontakt.
Webhook til dynamisk konfiguration
På den blokerende konfigurationswebhooksti skal du returnere en gemt agent i din organisation samt eventuelle værdier pr. opkald. For en Full duplex-agent bevarer opkaldet agentens stemme, selv når opkaldet starter på et andet understøttet sprog: stemmekoblinger pr. sprog og indbygget stemmeskift gælder ikke for det pågældende opkald.
{
"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."
}Responsens variabler overskriver variabler på anmodningsniveau, mens andre
anmodningsnøgler bevares. En responsværdi på null vælger pladsholderens standardværdi.
Det flettede objekt skal også være under 32 KB. Svar for gemte agenter accepterer kun
agent_id, variables, context, language og en pr. opkald
timezone; returner en integreret konfiguration, når du skal
erstatte prompten eller andre indstillinger. Når responsen angiver language for en
ikke-Full duplex-agent, bruger opkaldet også det pågældende sprogs egen stemme, hvis
agenten har en indstillet til det. En respons, der indeholder prompt, bruger altid
integreret konfiguration: Ethvert agent_id i responsen ignoreres, herunder null eller
metadata, der ikke er heltal. Den integrerede prompt skal stadig bestå den normale validering.
Integrerede webhook-svar kan også indeholde variables og context. En context,
der ikke er en streng eller er for lang, får udvekslingen til at fejle: Et telefonopkald
afvises, og en anmodning om widgetsessions fejler med 400. Webhook-svar for gemte
agenter bruger agentens implementerede A/B-opdeling for både telefon- og widgetopkald;
variabler gengives efter valg af variant. Ved indgående telefonopkald skal du bruge et nummer
uden en tildelt indgående agent og konfigurere webhooks for telefonnummeret eller organisationen;
widgetnøgler bruger mode="webhook". Indgående meddelelser fra Endpoint-systemet leverer ikke blokerende
konfigurationssvar.
Webhook til opsætning af agentopkald
For at bevare et nummer tilknyttet dets agent og kun udfylde opkaldets værdier,
skal du give agenten en webhook til opsætning af opkald.
Før hvert indgående opkald, som agenten besvarer på et nummer, modtager webhooken
opkaldet samt agentens id, navn og version og svarer med de samme
variables, context, language og den opkaldsspecifikke timezone som ovenfor uden behov for et agent_id. En agent,
hvis indstillinger bruger en pladsholder uden standardværdi, har brug for denne webhook for at besvare
et telefonnummer: opkaldet starter ikke, hvis webhooken fejler. Pladsholdere
med en standardværdi, som {{name|there}}, lader agenten svare uden den.
SIP-headere
Opkald, der når en agent via SIP (en SIP-adresse eller
et nummer på en manuel SIP-forbindelse), kan indeholde kontekst i X-*- og
User-to-User-headere. Hver af dem bliver til en sip_-variabel, såsom
{{sip_x_amzn_connectcontactid}} eller {{sip_uui}}, med den laveste
prioritet: En værdi med samme navn fra API'et eller en webhook har forrang. Se
Send opkaldskontekst i SIP-headere.
Headerværdier angives af afsenderen, så behandl dem som upålidelige, ligesom
enhver værdi leveret af en browser.
Widget-sessions-API
POST /v1/widget/session accepterer variables og language på øverste niveau. Dens publicerbare
nøgle vælger den gemte agent. Nøgler i webhooktilstand videresender disse værdier til
konfigurationswebhooken og fletter svaret som beskrevet ovenfor.
Browserleverede widget-variables styres af klienten, videresendes
ordret i web.incoming efter valideringen og oprydningen af strenge beskrevet
ovenfor og gentages i fuldførelseswebhooks og opkaldshistorikken. Behandl dem ikke
som pålidelige identitets- eller autorisationsdata.
Widgetens eget browserfelt context er anderledes: det indeholder tekst fra den
side, den besøgende befinder sig på, som agenten behandler som webstedsindhold (se
Integrer webwidgetten). En widgets kontekst pr. opkald
kommer fra konfigurationswebhooken for en nøgle i webhooktilstand, som ovenfor. Når et
opkald har begge dele, kommer konteksten pr. opkald først og derefter sideindholdet.
Realtime-sessions-API
POST /v1/realtime/sessions accepterer variables, context og language på øverste niveau sammen med agent_id eller en indlejret config:
{
"agent_id": 12,
"variables": {"name": "Ada"},
"context": "Ada is calling from the front desk about a guest's lost key card."
}context må kun være på øverste niveau; en indlejret config afviser det som et
ukendt felt.
Realtime WebSocket
Med en gemt agent forbliver den gemte agents implementerede prompt dens prompt.
session.instructions bliver opkaldets kontekst, session.prompt.variables
(eller session.config.variables) bliver dens variabler, og session.language
bliver sproget pr. opkald. Vælg agenten med
session.prompt.id i den første session.update, som starter sessionen, når
opdateringen modtages:
{
"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 i forbindelses-URL'en starter agenten, så snart socketforbindelsen
oprettes, før nogen session.update, så den har ingen input pr. opkald. Tilføj
&wait_for_session_update=1 for at vente på den første session.update og bruge
dens instruktioner og variabler.
I en integreret session (ingen gemt agent) er session.instructions selve
prompten, som før. Builder-mikrofonen og simulerede testopkald løser standarder
og manglende pladsholdere, men har ingen variabler eller kontekstinput pr. opkald.
Efter opkaldet
GET /v1/calls, GET /v1/calls/{call_id}, telephony.complete og web.complete indeholder de
endelige flettede variables og unresolved_variables. Ældre nyttelaster for fuldførelse,
der indeholder data.history, inkluderer dem også:
{
"variables": {"name": "Ada", "account_id": "A-17"},
"unresolved_variables": ["appointment_slot"]
}Opkaldets prompt_snapshot (GET /v1/calls/{call_id}) viser agentens
prompt med variablerne udfyldt og kontekstblokken tilføjet.
Gem dit CRM- eller opgave-id i variabelobjektet for at knytte det afsluttede opkald tilbage til den oprindelige post. Variabler og kontekst gemmes sammen med opkaldsposten. Send kun oplysninger, der er egnede til at blive gemt i opkaldshistorik og webhooks.
Genafspilninger af et opkald i valideringssæt, genafspilningskørsler og undersøgelser bruger opkaldets variabler og kontekst sammen med prompten, der testes, så en genafspilning tester, hvad agenten i det pågældende opkald ville være blevet fortalt.
Kompatibilitet med eksisterende prompter
Rendering gælder også for eksisterende gemte agent- og A/B-variantprompter, integrerede
udgående konfigurationer og realtidskonfigurationer samt prompter, der returneres af
konfigurationswebhooks. Ukendte {{name}}-pladsholdere bliver til tom tekst, også når der ikke
angives variables. Gennemgå eksisterende prompter før udrulning, herunder
eksternt leverede integrerede webhook-prompter, som ThunderPhone ikke kan registrere.
Builder-mikrofon- og simuleringsopkald anvender den samme standard-/tom-adfærd.