ThunderPhone v3 је сада доступан.Почните самостално, већ од 2 ¢/мин.Прочитајте објаву

Developer cookbook

Променљиве и контекст по позиву

Сваком позиву додајте сопствене детаље, као именоване променљиве за упит или кратак слободно формулисан опис, без измене агента.

Сваки позив може да садржи две врсте уноса за појединачни позив. Користите једну или обе заједно:

  • variables: именоване вредности које попуњавају {{placeholders}} у упиту. Користите их за поља на која се упит позива по имену, као што су име позиваоца, број налога или термин заказивања.
  • context: текст слободног облика који се додаје након упита. Користите га за сажетак који се не уклапа у шаблон, као што су опис задатка за овај позив или раније прикупљене белешке.

Обе опције раде са сачуваним агентом и са уметнутом конфигурацијом, при сваком начину покретања позива описаном у наставку. Ниједна не мења сачуваног агента, његову историју верзија нити друга подешавања.

{
  "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."
}

Променљиве

У промпт сачуваног агента уметните чуваре места, а затим при покретању позива проследите објекат variables. ThunderPhone приказује текст пре слања конфигурације позива гласовном окружењу за извршавање.

Када вредности нису потребне, изоставите variables; немојте слати null (одбија се са 400).

Čuvari mesta i podrazumevane vrednosti

You are calling {{name|Friend}} about account {{account_id}}.
The available appointment is {{ appointment_slot }}.

Називи разликују велика и мала слова и прате образац [A-Za-z_][A-Za-z0-9_]*. Размаци око назива су дозвољени; размак после | је део подразумеване вредности и задржава се. {{name|Friend}} користи Friend када name недостаје или је null; празан ниска је изричито наведена вредност. Недостајуће вредности без подразумеване вредности постају празне ниске, а њихови називи се појављују у unresolved_variables. Текст између двоструких витичастих заграда који није важеће резервисано место се уклања. Текст у двоструким витичастим заградама унутар сваке наведене вредности уклања се независно; вредност не може уклонити окружујући текст упита или другу вредност. Неусклађени раздвајачи са двоструким витичастим заградама такође се уклањају. JSON примери у упитима не смеју користити {{. Вредности су обичан текст и никада се не извршавају као код нити се рекурзивно проширују као шаблони.

Променљиве се такође могу појавити у упитима за потврду, одлазним порукама говорне поште и тексту обавештења о пристанку када се то поље шаље за телефонски позив. Агент нема засебно поље first_message: уводна упутства ставите у упит. Постојећа резервисана места за говорну пошту {agent_name} и {org_name} настављају да раде.

Вредности и ограничења

Вредности могу бити ниске, бројеви, логичке вредности или null; логичке вредности се приказују као true и false. Контролни (Cc) Unicode знакови осим новог реда (\n), табулатора (\t) и повратка курсора (\r), знакови формата (Cf) осим неспајајућег знака нулте ширине и спајајућег знака нулте ширине (U+200C, U+200D, који састављају речи у индијским језицима и језицима који користе арапско писмо), као и сурогатне (Cs) кодне тачке се уклањају; \r\n се нормализује у \n. Свака вредност је при приказивању ограничена на 2.000 знакова. Достављене ниске се такође чисте и скраћују пре чувања. Оригинални објекат мора да стане у 32 KB UTF-8 JSON-а; већи објекти добијају 400 у захтевима за позиве/сесије, док увози кампања појединачно пријављују неважеће редове. Низови и угнежђени објекти се не прихватају као вредности. Неодговарајући кључеви метаподатака (на пример, CSV заглавље са размаком) се задржавају и враћају, али се не могу референцирати помоћу резервисаног места.

Контекст

context је ниска од највише 20.000 знакова. ThunderPhone га додаје после промпта, када се попуне променљиве промпта, као разграничени блок:

<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>

Агент га чита заједно са својим упутствима, зато га напишите онако како бисте колеги дали информације пре позива. Контекст није шаблон: {{name}} у њему остаје написано како јесте. Ако је тексту потребна вредност, сами унесите вредност пре слања.

  • null, празан стринг или само празнине значе да нема контекста.
  • Вредност која није стринг или је дужа од 20.000 знакова одбија се са 400 у захтевима за позив и сесију; из webhook-а за конфигурацију размена не успева као и за неважеће variables (погледајте у наставку).
  • Уклањају се почетне и завршне празнине, као и исти контролни и форматирајући знакови као у вредностима променљивих.
  • Контекст је део упита позива, па се рачуна у величину упита позива.

Код агента са корацима, контекст следи после промпта сваког агента у позиву, а не после упутстава сваког корака.

Одакле потичу вредности

Одлазни API

Pošaljite variables i context putem 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."
}

Oba rade i sa podrazumevanim odlaznim agentom telefonskog broja ili sa ugrađenim config.prompt. Sa ugrađenom konfiguracijom, context može biti i unutar config, istog polja koje vraća webhook za konfiguraciju; ako pošaljete oba, moraju sadržati isti tekst. Ključ idempotentnosti ne može se ponovo koristiti sa različitim promenljivama ili drugačijim kontekstom.

CSV кампање

Колоне CSV-а које нису бројеви телефона већ су сачуване као променљиве контакта. Сваки позив их сада користи аутоматски. Користите заглавља као што су name, account_id и appointment_slot да би се подударала са вашим чуварима места. Постојеће мапирање имена може да обједини колоне имена и презимена у променљиву name. Контакти кампање немају контекст по контакту.

Вебхук за динамичку конфигурацију

На путањи блокирајућег вебхука за конфигурацију вратите сачуваног агента у вашој организацији, као и све вредности по позиву. За Full duplex агента, позив задржава глас агента чак и када позив започне на другом подржаном језику: мапирања гласова по језику и изворно пребацивање гласа не примењују се на тај позив.

{
  "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."
}

Променљиве из одговора замењују променљиве на нивоу захтева, док остали кључеви захтева остају. Вредност null у одговору бира подразумевану вредност чувара места. Обједињени објекат такође мора да стане у 32 KB. Одговори сачуваног агента прихватају само agent_id, variables, context, language и временску зону за сваки позив timezone; вратите уграђену конфигурацију када треба да замените упит или друга подешавања. Вебхук одговори сачуваног агента користе расподелу A/B распоређену за агента и за телефонске позиве и за позиве из виџета; променљиве се приказују након избора варијанте. Када одговор постави language за агента који није у режиму пуног дуплекса, позив користи и глас тог језика ако га је агент подесио за тај језик. Одговор који садржи prompt увек користи уграђену конфигурацију: сваки agent_id у том одговору се занемарује, укључујући вредност null или метаподатке који нису цели бројеви. Уграђени упит и даље мора да прође уобичајену валидацију. Уграђени вебхук одговори могу да садрже и variables и context. context који није ниска или је предугачак доводи до неуспеха размене: телефонски позив се одбија, а захтев за сесију виџета не успева са 400. Вебхук одговори сачуваног агента користе расподелу A/B распоређену за агента и за телефонске позиве и за позиве из виџета; променљиве се приказују након избора варијанте. За долазне телефонске позиве користите број без додељеног долазног агента и конфигуришите његов вебхук броја телефона или организације; кључеви виџета користе mode="webhook". Обавештења система крајњих тачака о долазним позивима не пружају блокирајуће одговоре за конфигурацију.

Веб-хук за подешавање позива агента

Да би број остао додељен свом агенту и да бисте попунили само вредности позива,
доделите агенту веб-хук за подешавање позива.
Пре сваког долазног позива на број на који агент одговара, веб-хук прима
позив и ИД, име и верзију агента, а затим одговара истим вредностима
variables, context, language и timezone за сваки позив као горе, без потребе за agent_id. Агент
чија подешавања користе чувар места без подразумеване вредности мора имати овај веб-хук да би одговорио
на телефонски број: позив се не покреће када веб-хук не успе. Чувари места
са подразумеваном вредношћу, као што је {{name|there}}, омогућавају агенту да одговори и без њега.

SIP заглавља

Позиви који до агента стигну преко SIP-а (на SIP адресу или на број на ручној SIP вези) могу да пренесу контекст у заглављима X-* и User-to-User. Свако од њих постаје sip_ променљива, као што су {{sip_x_amzn_connectcontactid}} или {{sip_uui}}, са најнижим приоритетом: вредност истог назива из API-ја или веб-куке има предност. Погледајте Проследите контекст позива у SIP заглављима. Вредности заглавља поставља пошиљалац, па их сматрајте непоузданим, као и сваку вредност коју доставља прегледач.

API сесије виџета

POST /v1/widget/session прихвата variables и language на највишем нивоу. Његов јавни кључ бира сачуваног агента. Кључеви у режиму вебхука прослеђују ове вредности вебхуку за конфигурацију и спајају одговор како је горе описано. Вредности variables виџета које доставља прегледач контролише клијент, прослеђују се дословно у web.incoming након горе описане валидације и чишћења стрингова, и понављају се у вебхуковима о завршетку и историји позива. Немојте их третирати као поуздане податке за идентификацију или ауторизацију.

Поље context сопственог прегледача виџета је другачије: оно преноси текст са странице на којој се посетилац налази, који агент третира као садржај веб-сајта (погледајте Уградите веб-виџет). Контекст по позиву за позив виџета долази из конфигурационог вебхука кључа у вебхук режиму, као горе. Када позив има оба, прво долази контекст по позиву, а затим садржај странице.

API сесије у реалном времену

POST /v1/realtime/sessions прихвата variables, context и language на највишем нивоу, заједно са agent_id или уграђеним config:

{
  "agent_id": 12,
  "variables": {"name": "Ada"},
  "context": "Ada is calling from the front desk about a guest's lost key card."
}

context може бити само на највишем нивоу; уграђени config га одбија као непознато поље.

Realtime WebSocket

Са сачуваним агентом, примењено упутство сачуваног агента остаје његово упутство. session.instructions постаје контекст позива, session.prompt.variables (или session.config.variables) постају његове променљиве, а session.language постаје његов језик по позиву. Изаберите агента помоћу session.prompt.id у првом session.update, који покреће сесију када то ажурирање стигне:

{
  "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 у URL-у везе покреће агента чим се сокет повеже, пре било ког session.update, па не садржи унос по позиву. Додајте &wait_for_session_update=1 да бисте сачекали први session.update и користили његова упутства и променљиве.

У уграђеној сесији (без сачуваног агента), session.instructions је сам упит, као и раније. Тест позиви преко микрофона у градитељу и симулирани тест позиви разрешавају подразумеване вредности и недостајуће чуваре места, али немају променљиве по позиву нити унос контекста.

Након позива

GET /v1/calls, GET /v1/calls/{call_id}, telephony.complete и web.complete укључују коначне обједињене variables и unresolved_variables. Застарели терети по завршетку који укључују data.history такође их садрже:

{
  "variables": {"name": "Ada", "account_id": "A-17"},
  "unresolved_variables": ["appointment_slot"]
}

prompt_snapshot позива (GET /v1/calls/{call_id}) приказује упит агента са попуњеним променљивама и додатим блоком контекста.

Сачувајте идентификатор CRM система или задатка у објекту променљивих да бисте довршени позив повезали са изворним записом. Променљиве и контекст се чувају уз запис позива; шаљите само информације које је прикладно задржати у историји позива и веб-закачкама.

Поновна репродукција позива, у скуповима за валидацију, покретањима репродукције и истрагама, користи променљиве и контекст тог позива са упитом који се тестира, тако да репродукција тестира оно што би агенту у том позиву било саопштено.

Компатибилност са постојећим упитима

Приказивање се примењује и на постојеће упите сачуваних агената и A/B варијанти, уметнуте одлазне конфигурације и конфигурације у реалном времену, као и на упите враћене путем webhook-ова за конфигурацију. Непознати чувари места {{name}} постају празан текст, чак и када није наведено variables. Проверите постојеће упите пре увођења, укључујући спољно достављене уметнуте/webhook упите које ThunderPhone не може да евидентира. Позиви преко микрофона у Builder-у и симулациони позиви примењују исто подразумевано/празно понашање.