Open in
Переменные и контекст для каждого звонка
Добавляйте к каждому звонку его собственные сведения: именованные переменные для промпта или краткое описание в свободной форме — без изменения агента.
Каждый звонок может содержать два вида входных данных для конкретного звонка. Используйте один из них или оба вместе:
variables: именованные значения, которые подставляются в{{placeholders}}в промпте. Используйте их для полей, на которые промпт ссылается по имени, например имени звонящего, номера аккаунта или времени записи.context: текст произвольной формы, добавляемый после промпта. Используйте его для краткого описания, которое не подходит для шаблона, например описания задачи для этого звонка или собранных ранее заметок.
Оба варианта работают с сохранённым агентом и с встроенной конфигурацией при любом из описанных ниже способов начать звонок. Ни один из них не изменяет сохранённого агента, историю его версий или другие настройки.
{
"agent_id": 12,
"variables": {"name": "Ada", "appointment_slot": "Tuesday at 10 AM"},
"context": "Ada rescheduled twice last month. She prefers mornings and asked us not to call her work number."
}Переменные
Добавьте заполнители в промпт сохранённого голосового агента, затем передайте
объект 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), кроме символов соединения и отсутствия соединения нулевой ширины (U+200C, U+200D, которые используются для написания слов в языках с индийской и арабской письменностью), а также суррогатные (Cs) кодовые точки удаляются; \r\n
нормализуется до \n. При отображении длина каждого значения
ограничена 2 000 символами. Перед сохранением переданные строки также очищаются и
усекаются. Исходный объект должен помещаться в 32 КБ UTF-8 JSON; для
более крупных объектов возвращается 400 в запросах вызова/сеанса, а при импорте кампаний недопустимые строки указываются отдельно. Массивы и вложенные объекты не
принимаются в качестве значений. Несоответствующие ключи метаданных (например, заголовок CSV с
пробелом) сохраняются и возвращаются, но не могут использоваться в подстановке.
Контекст
context — это строка длиной до 20 000 символов. ThunderPhone добавляет её после
промпта, после подстановки переменных промпта, в виде блока с разделителями:
<your prompt, with its variables filled in>
Details for this call:
<call_context>
Ada rescheduled twice last month. She prefers mornings and asked us not to call her work number.
</call_context>Агент читает его вместе со своими инструкциями, поэтому составляйте его так,
как если бы вводили коллегу в курс дела перед звонком. Контекст не является шаблоном:
{{name}} внутри него остаётся без изменений. Если тексту требуется значение, добавьте его
самостоятельно перед отправкой.
null, пустая строка или только пробельные символы означают отсутствие контекста.- Значение, не являющееся строкой или превышающее 20 000 символов, отклоняется с кодом
400в запросах к звонкам и сессиям; из webhook конфигурации оно приводит к сбою обмена, как недопустимыеvariables(см. ниже). - Начальные и конечные пробельные символы удаляются, также удаляются те же управляющие символы и символы форматирования, что и в значениях переменных.
- Контекст является частью промпта звонка, поэтому он учитывается в размере промпта звонка.
В агенте с этапами контекст следует за промптом каждого агента в звонке, а не за инструкциями каждого этапа.
Источники значений
Исходящий API
Передавайте variables и context в POST /v1/call:
{
"from_number": "+15551234567",
"to_number": "+14155552671",
"agent_id": 12,
"variables": {
"name": "Ada",
"account_id": "A-17",
"appointment_slot": "Tuesday at 10 AM"
},
"context": "Ada asked to be called back about the late fee on her March invoice."
}Оба параметра также работают с исходящим голосовым агентом по умолчанию для телефонного номера или со встроенным config.prompt. При встроенной конфигурации context также можно передать внутри config — в том же поле, которое возвращает вебхук конфигурации; если передаёте оба варианта, текст должен совпадать. Ключ идемпотентности нельзя повторно использовать с другими переменными или другим контекстом.
CSV кампании
Столбцы CSV, не связанные с номером телефона, уже сохранены как переменные контакта. Каждый звонок теперь автоматически использует их. Используйте заголовки, такие как name, account_id и appointment_slot, чтобы они соответствовали вашим заполнителям. Существующее сопоставление имени может объединять столбцы с именем и фамилией в переменную name. У контактов кампании нет контекста для каждого отдельного контакта.
Вебхук динамической конфигурации
В блокирующем маршруте вебхука конфигурации верните сохранённого агента из вашей организации и любые значения для конкретного звонка. Для агента Full duplex звонок сохраняет голос агента, даже если начинается на другом поддерживаемом языке: сопоставления голосов для отдельных языков и нативное переключение голоса не применяются к этому звонку.
{
"agent_id": 12,
"variables": {"name": "Ada", "account_id": "A-17"},
"context": "[REDACTED_LITERAL]"
}{
"agent_id": 12,
"variables": {"name": "Ada", "account_id": "A-17"},
"context": "Ada called yesterday about a leak in unit 4B; a plumber is booked for Friday."
}Переменные в ответе перезаписывают переменные на уровне запроса, а остальные
ключи запроса сохраняются. Значение null в ответе выбирает значение заполнителя по умолчанию.
Объединённый объект также должен помещаться в 32 КБ. Ответы сохранённого агента принимают только
agent_id, variables, context, language и часовой пояс для каждого звонка
timezone; возвращайте встроенную конфигурацию, если нужно
заменить промпт или другие настройки. Ответы вебхука сохранённого агента
используют опубликованное A/B-распределение агента как для телефонных звонков, так и для вызовов через виджет;
переменные обрабатываются после выбора варианта. Если ответ задаёт language для
агента без полного дуплекса, для звонка также используется собственный голос этого языка, если
для него задан голос агента. Ответ, содержащий prompt, всегда использует встроенную
конфигурацию: любой agent_id в таком ответе игнорируется, включая метаданные со значением null или
нецелочисленные метаданные. Встроенный промпт всё равно должен пройти обычную проверку.
Встроенные ответы вебхука также могут содержать variables и context. context,
который не является строкой или слишком длинный, завершает обмен с ошибкой: телефонный звонок
отклоняется, а запрос сеанса виджета завершается с 400. Ответы вебхука сохранённого агента
используют опубликованное A/B-распределение агента как для телефонных звонков, так и для вызовов через виджет;
переменные обрабатываются после выбора варианта. Для входящих телефонных звонков используйте номер, к которому не назначен агент для входящих
звонков, и настройте вебхук номера телефона или организации; ключи виджета используют
mode="webhook". Входящие уведомления системы конечных точек не предоставляют блокирующие
ответы конфигурации.
Вебхук настройки звонка агента
Чтобы сохранить номер назначенным своему агенту и заполнять только значения вызова, предоставьте агенту вебхук настройки вызова.
Перед каждым входящим вызовом, на который агент отвечает по номеру, вебхук получает вызов, а также идентификатор, имя и версию агента, и отвечает теми же variables, context, language и timezone для конкретного вызова, что и выше, без необходимости указывать agent_id. Агенту, в настройках которого используется заполнитель без значения по умолчанию, этот вебхук необходим для ответа на телефонный номер: при сбое вебхука вызов не начинается. Заполнители со значением по умолчанию, например {{name|there}}, позволяют агенту отвечать без него.
SIP-заголовки
Вызовы, поступающие к агенту через SIP (на SIP-адрес или
на номер через ручное SIP-подключение), могут передавать контекст в заголовках
X-* и User-to-User. Каждый из них становится переменной sip_, например
{{sip_x_amzn_connectcontactid}} или {{sip_uui}}, с самым низким
приоритетом: значение с тем же именем из API или вебхука имеет приоритет. См.
Передача контекста вызова в SIP-заголовках.
Значения заголовков задаёт отправитель, поэтому считайте их недоверенными, как и
любые значения, переданные браузером.
API сеанса виджета
POST /v1/widget/session принимает variables и language верхнего уровня. Его публичный
ключ выбирает сохранённого агента. Ключи в режиме вебхука передают эти значения в
вебхук конфигурации и объединяют ответ, как описано выше.
Переданные браузером variables виджета контролируются на стороне клиента, дословно
пересылаются в web.incoming после описанных выше проверки и очистки строк, а также
дублируются в вебхуках завершения и истории звонков. Не считайте их доверенными данными
для идентификации или авторизации.
Собственное поле браузерного context виджета отличается: оно содержит текст со
страницы, открытой у посетителя, который агент воспринимает как содержимое веб-сайта (см.
Встраивание веб-виджета). Контекст для конкретного звонка виджета
поступает из вебхука конфигурации ключа в режиме вебхука, как описано выше. Если у
звонка есть оба контекста, сначала добавляется контекст конкретного звонка, затем содержимое страницы.
API сеанса реального времени
POST /v1/realtime/sessions принимает variables, context и language верхнего уровня вместе с agent_id или встроенным config:
{
"agent_id": 12,
"variables": {"name": "Ada"},
"context": "Ada is calling from the front desk about a guest's lost key card."
}context указывается только на верхнем уровне; встроенный config отклоняет его как
неизвестное поле.
Realtime WebSocket
При использовании сохранённого агента развернутый промпт сохранённого агента остаётся его промптом.
session.instructions становится контекстом звонка, session.prompt.variables
(или session.config.variables) — его переменными, а session.language
— языком для конкретного звонка. Выберите агента с помощью
session.prompt.id в первом session.update, который запускает сессию после
получения этого обновления:
{
"type": "session.update",
"session": {
"type": "realtime",
"prompt": {"id": "12", "variables": {"name": "Ada"}},
"instructions": "Ada asked for a callback about her delivery window."
}
}?agent_id=12 в URL подключения запускает агента сразу после подключения
сокета, до любого session.update, поэтому он не получает входных данных для
конкретного звонка. Добавьте &wait_for_session_update=1, чтобы дождаться
первого session.update и использовать его инструкции и переменные.
Во встроенной сессии (без сохранённого агента) session.instructions, как и прежде, является самим промптом. Тестовые звонки в браузере и симуляции подставляют значения по умолчанию и отсутствующие заполнители. Чтобы протестировать со значениями, сохраните на агенте пример настройки звонка и выберите его при запуске теста; звонок выполняется так, как если бы ваш вебхук настройки звонка ответил этим примером.
После звонка
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"]
}prompt_snapshot звонка (GET /v1/calls/{call_id}) показывает промпт агента
с подставленными переменными и добавленным блоком контекста.
Сохраните идентификатор CRM или задачи в объекте переменных, чтобы связать завершённый звонок с исходной записью. Переменные и контекст сохраняются вместе с записью звонка; отправляйте только информацию, которую допустимо хранить в истории звонков и вебхуках.
Повторные воспроизведения звонка в наборах валидации, запусках воспроизведения и расследованиях используют переменные и контекст этого звонка вместе с тестируемым промптом, поэтому воспроизведение проверяет, что было бы сообщено агенту во время этого звонка.
Совместимость с существующими промптами
Рендеринг также применяется к существующим промптам сохранённых агентов и вариантов A/B, встроенным конфигурациям исходящих и realtime-звонков, а также к промптам, возвращаемым вебхуками конфигурации. Неизвестные заполнители {{name}} становятся пустым текстом, даже если variables не переданы. Перед запуском проверьте существующие промпты, включая встроенные промпты и промпты вебхуков, предоставленные внешними системами, которые ThunderPhone не может выявить.
Тестовые звонки в браузере и симуляции используют такое же поведение по умолчанию с пустыми значениями, если только вы не выберете сохранённый пример настройки звонка.