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 KB. Ответы с сохранённым агентом принимают только 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. Вызовы с микрофона в конструкторе и имитированные тестовые звонки подставляют значения по умолчанию и отсутствующие заполнители, но не имеют входных переменных для конкретного звонка.

Значения, возвращаемые после звонка#

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 и симуляции используют такое же поведение по умолчанию и для пустых значений.