Skip to main content
Отримання даних перед дзвінком дозволяє збагатити контекст дзвінка зовнішніми даними ще до того, як голосовий агент почне говорити. Коли ця опція увімкнена на вузлі Початок дзвінка, платформа надсилає HTTP-запит до вашого API одразу після ініціації дзвінка. Поки триває очікування відповіді, абонент чує гудки виклику. Щойно дані надходять, вони додаються до initial_context дзвінка і стають доступні як шаблонні змінні у промптах і привітанні.

Як це працює

  1. Дзвінок надходить (вхідний) або ініціюється (вихідний).
  2. Платформа надсилає POST-запит на налаштований ендпоінт зі стандартизованим тілом.
  3. Абонент чує гудки виклику, поки триває очікування відповіді.
  4. Ваш API повертає JSON-об’єкт з полем initial_context.
  5. Змінні додаються до початкового контексту дзвінка.
  6. Голосовий агент починає розмову з повним доступом до отриманих даних через синтаксис {{назва_змінної}}.

Налаштування

Відкрийте редактор вузла Початок дзвінка і розгорніть додаткові налаштування. Увімкніть Отримання даних перед дзвінком і налаштуйте:

Формат запиту

Платформа надсилає POST-запит з таким JSON-тілом:
Заголовок Content-Type встановлюється як application/json. Якщо налаштовано облікові дані, додається відповідний заголовок автентифікації.

Очікуваний формат відповіді

Ваш API має повернути JSON-об’єкт зі статусом 2xx. Змінні, які потрібно додати в контекст дзвінка, розмістіть у ключі initial_context:
initial_context також можна розмістити на верхньому рівні:
Застарілий ключ dynamic_variables досі приймається як синонім initial_context, тож наявні інтеграції продовжують працювати без змін. Для нових інтеграцій використовуйте initial_context. Якщо відповідь містить обидва ключі, пріоритет має initial_context.
Після отримання відповіді ці значення доступні всюди, де підтримуються шаблонні змінні:
  • Привітання: Вітаю, {{customer_name}}, дякуємо за дзвінок!
  • Промпт: Клієнт має статус {{loyalty_tier}} і {{open_tickets}} відкритих звернень.
Якщо відповідь не є коректним JSON-об’єктом, не містить initial_context (чи застарілого dynamic_variables), або запит завершується помилкою чи таймаутом, дзвінок продовжується у звичайному режимі без додаткового контексту. Отримання даних перед дзвінком ніколи не блокує й не зриває дзвінок.

Вкладені змінні

Якщо initial_context містить вкладені об’єкти, звертайтесь до них через крапкову нотацію:
Доступ у промптах: {{customer.name}} і {{customer.address.city}}.

Таймаут

Запит має 10-секундний таймаут. Якщо ваш API не відповідає в цей час, дзвінок продовжується без отриманих даних. Проєктуйте ендпоінт так, щоб він відповідав якомога швидше — це мінімізує тривалість гудків очікування.

Тестування тестовими дзвінками

Коли надходить реальний телефонний дзвінок, контекстні змінні caller_number і called_number автоматично встановлюються провайдером телефонії та передаються в запиті отримання даних як from_number і to_number. Однак під час тестового дзвінка — веб-дзвінка (WebRTC) або тестового телефонного дзвінка з редактора сценарію — ці змінні за замовчуванням недоступні. Щоб симулювати дані телефонії під час тестування:
  1. Відкрийте сценарій і перейдіть у Налаштування.
  2. У розділі Контекстні змінні додайте:
    • caller_number — номер, який симулює абонента (наприклад, +380501234567).
    • called_number — номер, на який ніби здійснюється дзвінок (наприклад, +380671234567).
  3. Збережіть налаштування.
Тепер при тестовому дзвінку (веб чи телефонному) ці значення надсилатимуться в запиті отримання даних на ваш ендпоінт, дозволяючи протестувати весь потік так, ніби це реальний вхідний дзвінок.
Ці контекстні змінні використовуються лише під час тестових дзвінків з редактора сценарію. У продакшн-дзвінках (вхідних і вихідних кампаніях) використовуються реальні дані телефонії, а ці значення ігноруються.

Приклад інтеграції

Простий ендпоінт на Node.js, що шукає клієнта за номером телефону: