Developer cookbook

Променливи за всяко обаждане

Персонализирайте запазен агент за всяко обаждане, без да променяте неговата внедрена подкана, инструменти или настройки.

Поставете заместители в подканата на запазения си агент, след което подайте обект 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. Контролните (Cc) знаци на Unicode с изключение на нов ред (\n), табулация (\t) и връщане в началото на реда (\r), всички форматиращи (Cf) знаци и сурогатните (Cs) кодови точки се премахват; \r\n се нормализира до \n. Всяка стойност е ограничена до 2 000 знака при визуализиране. Подадените низове се почистват и съкращават преди съхранение. Оригиналният обект трябва да се побира в 32 KB UTF-8 JSON; по-големите обекти получават 400 при заявки за обаждане/сесия, докато импортите на кампании отчитат невалидните редове поотделно. Масиви и вложени обекти не се приемат като стойности. Несъвпадащите ключове за метаданни (например заглавка на CSV с интервал) се запазват и връщат, но не могат да бъдат реферирани чрез заместител.

Откъде идват стойностите#

Изходящ API#

Изпратете variables заедно с agent_id при POST /v1/call:

{
  "from_number": "+15551234567",
  "to_number": "+14155550199",
  "agent_id": 12,
  "variables": {
    "name": "Ada",
    "account_id": "A-17",
    "appointment_slot": "Tuesday at 10 AM"
  }
}

Работи и с изходящия агент по подразбиране на телефонния номер, или с вградена config.prompt. Ключ за идемпотентност не може да се използва повторно с различни променливи.

CSV за кампания#

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

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

По пътя на блокиращия webhook за конфигурация върнете запазен агент във вашата организация плюс всички стойности за конкретното обаждане:

{"agent_id": 12, "variables": {"name": "Ada", "account_id": "A-17"}}

Ключовете в отговора заместват променливите на ниво заявка, докато другите ключове на заявката се запазват. Стойност null в отговора избира стойността по подразбиране на заместителя. Обединеният обект също трябва да е в рамките на 32 KB. Отговорите за запазен агент приемат само agent_id и variables; върнете вградена конфигурация, когато трябва да замените подканата или настройките. Отговор, съдържащ prompt, винаги използва вградена конфигурация: всеки agent_id в този отговор се игнорира, включително null или метаданни, които не са цели числа. Вградената подкана все пак трябва да премине стандартното валидиране. Вградените webhook отговори също могат да включват variables. Webhook отговорите за запазен агент използват внедреното A/B разделяне на агента както при телефонни обаждания, така и при обаждания от уиджета; променливите се визуализират след избора на вариант. При входящи телефонни обаждания използвайте номер без назначен входящ агент и конфигурирайте webhook на телефонния номер или на организацията; ключовете за уиджета използват mode="webhook". Входящите известия от системата за крайни точки не предоставят блокиращи отговори за конфигурация.

API за сесии на уиджета и Realtime#

POST /v1/widget/session приема обект variables от най-горно ниво. Неговият публичен ключ избира запазения агент. Ключовете в режим webhook препращат тези стойности към webhook за конфигурация и обединяват отговора, както е описано по-горе. Предоставените от браузъра variables за уиджета/Realtime се контролират от клиента, препращат се дословно в web.incoming след описаните по-горе валидиране и почистване на низове и се повтарят в webhook събитията за завършване и историята на обажданията. Не ги третирайте като надеждни данни за идентичност или оторизация.

POST /v1/realtime/sessions приема variables заедно с agent_id (или вградена config). Това са полета на API за създаване на сесия. Мостът Realtime WebSocket не препраща опция за променливи; подайте я директно към API за създаване на сесия. Клиентите на уиджета трябва да включат variables в изпратения полезен товар на сесията; препращането чрез SDK не е част от тази промяна в API. Тестовите обаждания с микрофон в конструктора и симулираните тестови обаждания разрешават стойностите по подразбиране и липсващите заместители, но нямат вход за променливи за конкретно обаждане.

Стойности, върнати след обаждането#

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"]
}

Съхранявайте идентификатора на вашата CRM система или задача в обекта с променливи, за да свържете завършеното обаждане обратно с неговия изходен запис. Тези полета се съхраняват със записа за обаждането; изпращайте само информация, която е подходяща за съхранение в историята на обажданията и webhook събитията.

Съвместимост със съществуващи подкани#

Рендирането се прилага и към съществуващи подкани за запазени агенти и A/B варианти, вградени изходящи конфигурации и конфигурации в реално време, както и към подкани, върнати от уебхукове за конфигурация. Непознатите заместители {{name}} стават празен текст, дори когато не са предоставени variables. Проверете съществуващите подкани преди внедряване, включително външно предоставени вградени подкани и подкани от уебхукове, които ThunderPhone не може да инвентаризира. Обажданията с микрофон в Builder и симулационните обаждания прилагат същото поведение по подразбиране/празно.