Получение данных перед звонком

Получение данных перед звонком позволяет обогащать контекст звонка внешними данными до того, как голосовой агент начнет говорить. Когда функция включена на узле «Начало звонка», Агентика отправляет HTTP-запрос в ваш API сразу после инициации звонка. Пока ответ загружается, абонент слышит гудок вызова. Когда данные приходят, они объединяются с начальным контекстом звонка и становятся доступны как переменные шаблона в промптах и приветствиях.

Как это работает

Звонок приходит (входящий) или инициируется (исходящий).
Агентика отправляет POST-запрос на настроенный эндпоинт со стандартизированной полезной нагрузкой.
Абонент слышит гудок вызова, пока ожидается ответ.
Ваш API отвечает JSON-объектом с объектом initial_context.
Переменные объединяются с начальным контекстом звонка.
Голосовой агент стартует с полным доступом к полученным данным через синтаксис {{variable_name}}.

Конфигурация

Откройте редактор узла «Начало звонка» и раскройте Дополнительные настройки. Включите Получение данных перед звонком и настройте:

Поле	Описание
URL эндпоинта	URL, на который Агентика отправит POST-запрос.
Аутентификация	Необязательные учётные данные для аутентификации запроса. Поддерживаются API-ключ, Bearer-токен, basic-аутентификация и пользовательский заголовок.

URL должен указывать на публичный адрес: localhost, приватные и link-local адреса (включая 169.254.169.254) и имена внутренних сервисов отклоняются при сохранении агента и повторно проверяются перед каждой отправкой. Редиректы не выполняются. В self-hosted установке, где получатель живёт в локальной сети или в соседнем compose-сервисе (например, n8n), оператор может снять это ограничение переменной окружения TOOL_TEST_ALLOW_PRIVATE_TARGETS=true — она действует и на HTTP-инструменты.

Формат запроса

Агентика отправляет POST-запрос со следующим JSON-объектом:

{
  "event": "call_inbound",
  "call_inbound": {
    "agent_id": 123,
    "from_number": "+12137771234",
    "to_number": "+12137771235"
  }
}

Поле	Описание
`event`	Всегда `"call_inbound"`.
`call_inbound.agent_id`	ID воркфлоу (агента).
`call_inbound.from_number`	Номер звонящего (`caller_number` из начального контекста).
`call_inbound.to_number`	Номер, на который позвонили (`called_number` из начального контекста).

Заголовок Content-Type установлен в application/json. Если вы настроили учётные данные, соответствующий заголовок аутентификации будет добавлен.

Ожидаемый формат ответа

Ваш API должен вернуть JSON-объект со статусом 2xx. Переменные, которые нужно добавить в контекст звонка, должны находиться внутри ключа initial_context:

{
  "call_inbound": {
    "initial_context": {
      "customer_name": "Jane Doe",
      "account_status": "active",
      "loyalty_tier": "gold",
      "open_tickets": 2
    }
  }
}

Также можно поместить initial_context на верхний уровень:

{
  "initial_context": {
    "customer_name": "Jane Doe",
    "account_status": "active"
  }
}

Устаревший ключ dynamic_variables по-прежнему принимается как полная замена (drop-in alias) для initial_context, поэтому существующие интеграции продолжают работать без изменений. Для новых интеграций используйте initial_context. Если в ответе есть оба ключа, приоритет у initial_context.

После получения ответа эти значения можно использовать везде, где поддерживаются переменные шаблона:

Приветствие: Hello {{customer_name}}, thank you for calling!
Промпт: The customer is a {{loyalty_tier}} member with {{open_tickets}} open support tickets.

Если ответ не является корректным JSON-объектом, не содержит initial_context или устаревший dynamic_variables, либо запрос завершается ошибкой или по таймауту, звонок продолжается без дополнительного контекста. Получение данных перед звонком никогда не блокирует и не прерывает звонок.

Вложенные переменные

Если initial_context содержит вложенные объекты, обращайтесь к ним через точечную нотацию:

{
  "call_inbound": {
    "initial_context": {
      "customer": {
        "name": "Jane Doe",
        "address": {
          "city": "Los Angeles"
        }
      }
    }
  }
}

В промптах используйте {{customer.name}} и {{customer.address.city}}.

Таймаут

У запроса есть таймаут 10 секунд. Если ваш API не ответит за это время, звонок продолжится без полученных данных. Проектируйте эндпоинт так, чтобы он отвечал как можно быстрее и сокращал длительность гудка вызова. Когда приходит настоящий телефонный звонок, переменные контекста caller_number и called_number автоматически задаются провайдером телефонии и включаются в запрос получения данных перед звонком как from_number и to_number. Но когда вы делаете тестовый звонок — веб-звонок (WebRTC) или телефонный тестовый звонок из редактора воркфлоу — эти переменные по умолчанию недоступны. Чтобы имитировать данные телефонии во время тестирования:

Откройте воркфлоу и перейдите в Настройки.
В Переменные контекста добавьте:
- caller_number — номер, который нужно имитировать как номер звонящего, например +12137771234.
- called_number — номер, на который как будто позвонили, например +12137771235.
Сохраните настройки.

Теперь при любом тестовом звонке — веб или телефонном — эти значения будут отправляться в запросе получения данных перед звонком на ваш эндпоинт, позволяя проверить весь сценарий как при реальном входящем звонке.

Эти переменные контекста используются только во время тестовых звонков из редактора воркфлоу. В производственных входящих звонках и исходящих звонках кампаний используются реальные данные телефонии, а эти значения игнорируются.

Пример интеграции

Простой эндпоинт на Node.js, который ищет клиента по номеру телефона:

app.post("/agentika/pre-call", async (req, res) => {
  const { call_inbound } = req.body;

  const customer = await db.customers.findOne({
    phone: call_inbound.from_number,
  });

  if (!customer) {
    return res.json({});
  }

  res.json({
    call_inbound: {
      initial_context: {
        customer_name: customer.name,
        account_status: customer.status,
        loyalty_tier: customer.tier,
      },
    },
  });
});

Начало работы

Основные понятия

Конфигурации

Конструктор голосовых агентов

Телефония

Интеграции

Получение данных перед звонком

Как это работает

Конфигурация

Формат запроса

Ожидаемый формат ответа

Вложенные переменные

Таймаут

Пример интеграции

​Как это работает

​Конфигурация

​Формат запроса

​Ожидаемый формат ответа

​Вложенные переменные

​Таймаут

​Пример интеграции

Как это работает

Конфигурация

Формат запроса

Ожидаемый формат ответа

Вложенные переменные

Таймаут

Пример интеграции