ThunderPhone v3 er live.Selvbetjening fra 2 cent pr. minut.Læs mere om lanceringen

Developer cookbook

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 400 ved opkalds- og sessionsanmodninger. Fra en konfigurationswebhook fejler udvekslingen på samme måde som ugyldige variables (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.