---
title: "Puhelukohtaiset muuttujat ja konteksti"
description: "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.

```json
{
  "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

```text
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:

```text
<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 virheelliset `variables`-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](/fi/guides/pricing).

[vaiheet](/fi/guides/agent-steps)-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`:

```json
{
  "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.

```json
{
  "agent_id": 12,
  "variables": {"name": "Ada", "account_id": "A-17"},
  "context": "[REDACTED_LITERAL]"
}
```

```json
{
  "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](/fi/guides/dynamic-call-config); 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](/fi/webhooks/call-incoming).
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](/fi/guides/sip-addresses) 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](/fi/guides/sip-addresses).
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](/fi/guides/embed-web-widget)). 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:

```json
{
  "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:

```json
{
  "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](/fi/webhooks/call-incoming) 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:

```json
{
  "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](/api-reference/validation-sets),
[uudelleentoistoajoissa](/api-reference/replay-runs) ja
[tutkimuksissa](/api-reference/investigations) 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.
