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. Символи керування Unicode (Cc), крім нового рядка (\n), табуляції (\t) та повернення каретки (\r), усі символи форматування (Cf) і сурогатні (Cs) кодові точки видаляються; \r\n нормалізується до \n. Кожне значення обмежене 2 000 символами після відтворення. Передані рядки також очищуються та обрізаються перед зберіганням. Початковий об’єкт має вміщатися в 32 КБ JSON у UTF-8; для більших об’єктів повертається 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.

Вебхук динамічної конфігурації#

На шляху блокувального вебхука конфігурації повертайте збереженого агента у вашій організації разом із будь-якими значеннями для конкретного дзвінка:

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

Ключі відповіді перезаписують змінні на рівні запиту, тоді як інші ключі запиту зберігаються. Значення відповіді null вибирає значення заповнювача за замовчуванням. Об’єднаний об’єкт також має вміщатися в 32 КБ. Відповіді зі збереженим агентом приймають лише agent_id і variables; повертайте вбудовану конфігурацію, коли потрібно замінити промпт або налаштування. Відповідь, що містить prompt, завжди використовує вбудовану конфігурацію: будь-який agent_id у такій відповіді ігнорується, зокрема null або нецілочисельні метадані. Вбудований промпт усе одно має пройти звичайну перевірку. Вбудовані відповіді вебхука також можуть містити variables. Відповіді вебхука зі збереженим агентом використовують розгорнутий A/B-розподіл агента як для телефонних дзвінків, так і для викликів віджета; змінні обробляються після вибору варіанта. Для вхідних телефонних дзвінків використовуйте номер без призначеного вхідного агента та налаштуйте його вебхук номера телефону або організації; ключі віджета використовують mode="webhook". Вхідні сповіщення системи кінцевих точок не надають блокувальних відповідей конфігурації.

API сесій віджета та Realtime#

POST /v1/widget/session приймає об’єкт variables верхнього рівня. Його публічний ключ вибирає збереженого агента. Ключі в режимі вебхука передають ці значення до вебхука конфігурації та об’єднують відповідь, як описано вище. Надані браузером variables віджета/realtime контролюються клієнтом, передаються без змін у web.incoming після описаних вище перевірки та очищення рядків, а також дублюються у вебхуках завершення та історії дзвінків. Не вважайте їх надійними даними для ідентифікації або авторизації.

POST /v1/realtime/sessions приймає variables разом із agent_id (або вбудованим config). Це поля API створення сесії. Міст Realtime WebSocket не передає параметр variables; надавайте його безпосередньо API створення сесії. Клієнти віджета мають включати variables до надісланого корисного навантаження сесії; передавання через SDK не є частиною цієї зміни API. Тестові виклики з мікрофона в 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"]
}

Зберігайте ідентифікатор CRM або завдання в об’єкті змінних, щоб пов’язати завершений дзвінок із його вихідним записом. Ці поля зберігаються разом із записом дзвінка; надсилайте лише інформацію, яку доречно зберігати в історії дзвінків і вебхуках.

Сумісність із наявними промптами#

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