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

Заместители и стойности по подразбиране

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. Контролни Unicode (Cc) знаци с изключение на нов ред (\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

Изпращайте variables и context чрез 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."
}

И двете работят и с изходящия агент по подразбиране на телефонния номер, или с вграден config.prompt. При вградена конфигурация context може да бъде и в config — същото поле, което връща webhook за конфигурация; ако изпратите и двете, те трябва да съдържат един и същ текст. Ключът за идемпотентност не може да се използва повторно с различни променливи или различен контекст.

CSV за кампания

Колоните в CSV файла, различни от телефонния номер, вече се съхраняват като променливи за контакт. Всяко набиране вече ги използва автоматично. Използвайте заглавки като name, account_id и appointment_slot, за да съвпадат с вашите заместители. Съществуващото съпоставяне на име може да комбинира колоните за собствено и фамилно име в променливата name. Контактите от кампании нямат контекст за отделен контакт.

Webhook за динамична конфигурация

В пътя на webhook за блокираща конфигурация върнете запазен агент от вашата организация, както и всички стойности за конкретното обаждане. При агент с 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 за агент без Full duplex, обаждането използва и гласа за съответния език, ако за агента е зададен такъв. Отговор, съдържащ 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 или webhook има предимство. Вижте Предаване на контекста на обаждане в 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 е самият подканващ текст, както преди. Тестовите разговори с микрофона в Builder и симулираните разговори разрешават стойностите по подразбиране и липсващите заместители, но нямат променливи или вход за контекст за конкретен разговор.

След обаждането

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 варианти, вградени изходящи конфигурации и конфигурации в реално време, както и към подкани, върнати от уебхукове за конфигурация. Непознатите заместители {{name}} стават празен текст, дори когато не са предоставени variables. Проверете съществуващите подкани преди внедряване, включително външно предоставени вградени подкани и подкани от уебхукове, които ThunderPhone не може да инвентаризира. Обажданията с микрофон в Builder и симулационните обаждания прилагат същото поведение по подразбиране/празно.