Перейти к основному содержимому

Actions & Tools

Вкладка Actions — место, где вы управляете всем, что агент умеет за пределами разговора: tools, которые агент вызывает в живом разговоре, prefetch-хуки, срабатывающие перед стартом звонка, и пост-звоночные actions, срабатывающие после окончания. Retrieval Variables (поля данных, извлекаемые агентом из каждого разговора) живут в той же вкладке.

Все тарифы

Все tools, actions и новый pre-fetch-хук доступны на всех тарифах, включая Free.


Три фазы

Каждая запись на вкладке Actions принадлежит одной из трёх фаз жизненного цикла. Выпадающий список Add Tool группирует их, чтобы было понятно, когда что срабатывает:

ФазаКогдаПримеры
Pre fetchПеред тем как агент скажет «здравствуйте»Поднять звонящего в CRM по телефону, забрать последний заказ, получить персонализированное приветствие с бэкенда
Live callВо время разговора, по триггеру AI в нужный моментПередать звонок человеку, проверить календарь, передать другому агенту, запросить внешний API
Post callПосле окончания звонкаОтправить summary email, выстрелить SMS-подтверждение, запушить payload звонка в CRM

Выпадающий список открывается с Pre fetch наверху, потому что у других фаз уже много опций — новая pre-fetch-запись скорее всего то, что вы ищете.


Pre fetch

Pre-fetch-хуки позволяют агенту начинать звонок, уже зная, кто звонит. Они выполняются параллельно с установкой звонка и инжектят ответ в системный промпт агента до первого произнесённого слова.

Когда использовать

  • Узнать возвращающегося клиента по номеру и поздороваться по имени
  • Подтянуть открытый заказ, последний приём или уровень членства
  • Заранее подгрузить бизнес-контекст в зависимости от того, на какую линию набрали
  • Инжектить заметки CRM, чтобы агент знал стадию лида и историю

Как работает

  1. Платформа резолвит телефон звонящего (из SIP для входящих, из dial target для исходящих).
  2. Каждый активный Pre fetch action срабатывает параллельно с жёстким таймаутом 1.5 с на запрос и общим бюджетом 2 с.
  3. Успешные ответы конкатенируются в системный промпт агента как именованные блоки — агент читает их на самом первом ходу.
  4. Сбои тихие — медленный или сломанный эндпоинт никогда не блокирует приветствие. Агент просто начинает говорить без этого блока.

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

ПолеОписание
NameОбязательно. Внутренний label и имя блока в промпте — держите коротким и описательным (например, crm_lookup, vip_check).
API URLОбязательно. Эндпоинт для запроса. Поддерживает плейсхолдеры {phone}, {direction}, {agent_id}, {user_id}, {call_id}.
HTTP MethodGET — дефолт и лучший выбор. POST / PUT / PATCH / DELETE тоже работают.
HeadersОпционально. Статические или шаблонные (плейсхолдеры работают).
Query ParametersОпционально. Для новых pre-fetch предзаполняется phone={phone}.

Доступные переменные

Эти токены подставляются в URL, заголовки и query/body-параметры во время запроса:

ПеременнаяИсточникПример значения
{phone}Телефон звонящего (E.164) — для исходящих, номер назначения+431234567890
{direction}inbound или outboundinbound
{agent_id}Внутренний id агента65f1a2b3c4...
{user_id}Id владельца рабочего пространства65e0b1c2d3...
{call_id}Id звонка (позволяет бэкенду коррелировать с post-call payload позже)65f1f2c4d5...

Неизвестные плейсхолдеры оставляются как есть — плохой шаблон никогда не уронит звонок.

Что попадает в промпт

Если эндпоинт https://crm.example.com/lookup?phone={phone} возвращает:

{ "name": "Sarah Johnson", "tier": "Gold", "open_orders": 1 }

Системный промпт агента дополняется XML-обёрнутым блоком, именованным как action:

<call_context>
<block name="crm_lookup">
{ "name": "Sarah Johnson", "tier": "Gold", "open_orders": 1 }
</block>
</call_context>

Не нужно объяснять агенту, как использовать — LLM подхватывает контекст естественно. Опционально упомяните pre-fetch в системном промпте: "Если <call_context> содержит имя клиента, поздоровайтесь по имени."

Важные ограничения

  • Только телефонные звонки. Pre-fetch не работает для виджет-звонков (web) — нет номера для подстановки.
  • Лимит 8 КБ на тело ответа — больше обрезается перед инжектом. Лимит защищает токен-бюджет промпта и ограничивает зону поражения вредоносного эндпоинта.
  • Нет вычисления condition — pre-fetch всегда срабатывает, когда активен. Транскрипции пока нет, чтобы по ней оценивать.
подсказка

Используйте GET с лукап-эндпоинтом по телефону. Держите ответы маленькими и структурированными (JSON-объект с 3–5 полями). Агенту не нужна вся карточка клиента — только биты, меняющие разговор.


Live Call Tools

Срабатывают во время разговора. AI решает, когда вызвать каждый tool, на основе его описания и текущего диалога.

Доступные tools

ToolНазначениеКогда использовать
Call ForwardingПередача операторуКлиент просит человека, сложные вопросы
Google CalendarПроверить доступность и записатьКлиент хочет назначить встречу
Outlook CalendarТо же, через Microsoft OutlookКлиент хочет назначить встречу
API Tool RAGПолучить live-данные из внешнего APIНужна реал-тайм инфо (заказы, остатки, состояние аккаунта)
Agent TransferПередать другому голосовому агентуЗвонящему нужен другой отдел или специалист
HubSpot CRMЧтение/запись контактов и сделок в HubSpotЛог звонка в HubSpot, поднятие лида
MCP serversОткрыть tools любого зарегистрированного MCP-сервераУ вас MCP-совместимый tool-сервер, и хочется, чтобы агент использовал его tools в разговоре

Call Forwarding

Передача звонков человеку при выполнении условий.

НастройкаОписаниеПример
NameОбязательно. Имя человека или отдела"Sales Manager"
Forwarding NumberДефолтный номер для передачи"+49 123 456 789"
Trigger ConditionКогда агент должен передать"Клиент просит менеджера или вопрос не решается"
Conditional Routing NumbersМаппинг условие-номер для маршрутизации{"billing": "+49 111 222", "technical": "+49 333 444"}

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

  1. Во время разговора AI оценивает Trigger Condition.
  2. Если заданы Conditional Routing Numbers — совпадающее условие определяет, какой номер набрать.
  3. Иначе используется Forwarding Number.
  4. Агент сообщает звонящему о передаче.
  5. Звонок переадресуется — если не отвечают, возвращается к агенту.
подсказка

Можно добавить несколько Call Forwarding tools под разные отделы — один для «Sales» и другой для «Technical Support» с разными условиями и номерами.

Google Calendar

Подключите Google Calendar, чтобы агент мог проверять доступность и записывать в звонках.

Настройка:

  1. Сначала IntegrationCalendars и подключите Google-аккаунт.
  2. Добавьте tool Google Calendar на вкладку Actions агента.
  3. Выберите календарь.
  4. Настройте доступность.
НастройкаОписаниеДефолт
CalendarОбязательно. Какой календарьОсновной
TimezoneЧасовой пояс (IANA-формат)Автоопределение
Work Start TimeНачало рабочих часов9:00
Work End TimeКонец рабочих часов18:00
Slot DurationДлительность слота в минутах30
Working DaysРабочие дни неделиПн–Пт
Buffer Between AppointmentsБуфер между записями (0–60 мин)0

Поддерживаемые длительности слотов: 15, 30, 45, 60, 75, 90, 105, 120 минут.

подсказка

Точно настройте рабочие часы и дни — агент предложит только слоты внутри вашей доступности.

Outlook Calendar

Подключите Outlook Calendar для записи в звонках. Работает так же, как Google Calendar.

Настройка:

  1. IntegrationCalendars и подключите Outlook-аккаунт.
  2. Добавьте tool Outlook Calendar на вкладку Actions агента.
  3. Выберите календарь.
  4. Настройте доступность.

Настройки идентичны Google Calendar (timezone, рабочие часы, длительность слота, рабочие дни, буфер).

Agent Transfer

Передача звонка другому голосовому агенту вашего аккаунта. Полезно, когда есть специализированные агенты для разных отделов.

НастройкаОписание
Target AgentОбязательно. Какому агенту передавать
Trigger ConditionКогда передавать (например, «Звонящий спрашивает о технической поддержке»)

Пример: Receptionist-агент передаёт звонящих sales-агенту, если они спрашивают про цены, или support-агенту, если у них техническая проблема.

HubSpot CRM

Чтение и запись в HubSpot CRM во время звонка. Позволяет агенту логировать взаимодействия, поднимать контакт по телефону или пушить обновления сделок без скриптинга API-вызовов.

Настройка:

  1. Зайдите на страницу Integrations и подключите HubSpot-аккаунт.
  2. Добавьте tool HubSpot CRM на вкладку Actions агента.
  3. Выберите, какие пайплайны и свойства агент может трогать.

После добавления tool AI может мэтчить звонящего с HubSpot-контактом по телефону, получать стадию сделки и обновлять поля — всё из живого разговора.

MCP servers

Откройте tools любого MCP-совместимого сервера, подключённого к Hanc.AI. Один агент может тянуть из нескольких MCP-серверов; один MCP-сервер может обслуживать несколько агентов.

Настройка:

  1. Подключите MCP-сервер(ы) один раз в IntegrationMCP servers. См. полные шаги регистрации на странице MCP Servers.
  2. Добавьте запись MCP servers на вкладку Actions агента — в Add Action она в группе Live call.
  3. Включите подключения, которые этот агент должен использовать.
  4. Добавьте короткую инструкцию «When to use it», чтобы агент знал, когда тянуться к этим tools.

Агент переоткрывает набор tools каждого включённого MCP-сервера в начале каждого звонка — изменения на стороне сервера видны автоматически на следующем звонке. Tools переименовываются с префиксом label подключения, чтобы похожие имена с разных серверов не сталкивались.

API Tool RAG

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

НастройкаОписаниеПример
NameОбязательно. Имя tool"Order Lookup"
Description / When to UseОбязательно. Когда запрашивать API"Клиент спрашивает про статус заказа"
API URLОбязательно. URL эндпоинта. Может включать {placeholder}-токены, подставляемые из Body Parameters Schema (см. ниже)."https://api.yourshop.com/orders/{order_id}"
HTTP MethodОбязательно. HTTP-методGET, POST, PUT, DELETE, PATCH
Loading MessageЧто говорит агент в ожидании"Сейчас проверю..."
TimeoutМаксимум ожидания (мс)5000 (дефолт)
HeadersСтатические HTTP-заголовки на каждый запрос{"Authorization": "Bearer KEY"}
Query ParametersСтатические query-параметры на каждый запрос{"apiVersion": "v2"}
Body Parameters SchemaОбязательно. JSON Schema, описывающая аргументы, которые AI должен извлечь из разговора и передать tool. См. Написание Body Parameters Schema.JSON Schema
подсказка

Всегда задавайте Loading Message — тишина во время API-вызовов кажется звонящему сломанной.

примечание

Старый чекбокс «Run on call start» на API Tool RAG заменён выделенной записью Pre fetch. Используйте Pre fetch, когда хотите данные до начала разговора; API Tool RAG — когда агент должен решать во время звонка, нужно ли тянуть.

Написание Body Parameters Schema

Несмотря на название, Body Parameters Schema — это не сырое тело запроса. Это JSON Schema, описывающая, что AI должен извлечь из разговора и передать tool. В зависимости от HTTP-метода и шаблона URL значения попадают в URL, query-строку или JSON-тело:

HTTP-методКуда попадают извлечённые значения
URL содержит {name}Совпадающее значение подставляется в URL
GET, DELETEОставшиеся добавляются к URL как ?key=value
POST, PUT, PATCHОставшиеся отправляются JSON-телом
Минимальная структура
{
"type": "object",
"properties": {
"param_name": {
"type": "string",
"description": "Что это и как AI должен это выбирать"
}
},
"required": ["param_name"]
}

Корневой type всегда "object". properties перечисляет каждый аргумент. required помечает обязательные — если клиент ещё не назвал, AI спросит перед вызовом tool.

Справочник полей
ПолеНазначение
typeJSON-тип значения: "string", "number", "integer", "boolean", "array", "object"
descriptionСамое важное. Говорит AI, что значит значение, какой формат использовать и когда передавать. Добавляйте примеры всегда.
enumОграничивает значение фиксированным списком. AI мапит естественную речь в ближайшую опцию (например, "синий""blue").
minimum, maximumЧисловые границы. AI откажется/обрежет вне диапазона.
defaultЗначение по умолчанию, если AI не передал. Не обязательно, но документирует неявное значение.
formatПодсказка валидации, например, "email", "date" (YYYY-MM-DD), "uri".
Примеры

Поиск продукта (только keyword):

{
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Keyword поиска продукта — например, \"phone\", \"laptop\", \"Apple\", \"Samsung\""
}
},
"required": ["query"]
}

Используется с URL https://dummyjson.com/products/search?q={query}&limit=5 и GET: значение query идёт в плейсхолдер URL. В тело ничего не уходит.

Поднятие заказа по ID:

{
"type": "object",
"properties": {
"order_id": {
"type": "string",
"description": "ID заказа, о котором спрашивает клиент, обычно 6–10 цифр. Спросить клиента, если не дал."
}
},
"required": ["order_id"]
}

Используется с URL https://api.example.com/orders/{order_id} и GET.

Бронирование с несколькими обязательными полями:

{
"type": "object",
"properties": {
"product_id": {
"type": "string",
"description": "ID продукта, возвращённый предыдущим вызовом search_products."
},
"quantity": {
"type": "integer",
"minimum": 1,
"maximum": 10,
"description": "Сколько единиц зарезервировать. Дефолт 1."
},
"delivery_method": {
"type": "string",
"enum": ["pickup", "home_delivery", "locker"],
"description": "Как клиент хочет получить товар."
},
"customer_email": {
"type": "string",
"format": "email",
"description": "Email клиента для подтверждения заказа. Спросить, если не дал."
}
},
"required": ["product_id", "delivery_method", "customer_email"]
}

Используется с POST https://api.example.com/reservations: четыре значения идут в JSON-тело. AI спросит клиента про недостающие required-поля перед вызовом tool.

Tool без параметров:

{
"type": "object",
"properties": {}
}

Используйте, когда эндпоинт полностью статический (например, GET /store/hours) и AI не нужно ничего передавать.

Лучшие практики для голосовых агентов
  • Держите схему плоской. Вложенные объекты и массивы работают, но AI может сбиться, говоря по телефону. Предпочтительно — максимум 3–5 топ-левел полей.
  • Всегда пишите description для каждого поля. Включайте примеры (например, "phone", "laptop") — примеры направляют AI надёжнее абстрактных определений.
  • Используйте enum, когда есть фиксированный список значений. Это убирает риск, что AI придумает значения или пошлёт "Electronics" вместо "electronics".
  • Помечайте поле required, только если tool без него не работает. Всё остальное опционально, AI пропустит, если клиент не упомянул, — без неловких лишних вопросов.
  • Используйте snake_case и точно совпадайте с {placeholder}-токенами в URL.
  • Документируйте поведение для отсутствующих значений в description — например, "Не передавать, если нет лимита бюджета", "Дефолт 5".

Пост-звоночные actions

Пост-звоночные actions срабатывают после окончания звонка и того, как цепочка анализа выдала summary, sentiment и извлечённые переменные. Они потребляют данные звонка — не разговаривают с клиентом.

Доступные actions

ActionНазначение
Send EmailEmail-резюме команде или клиенту
Send SMSSMS-подтверждение звонящему
Send WhatsAppWhatsApp-сообщение или шаблон (работает внутри и вне 24-часового окна)
API CallПушит полный payload звонка во внешний API (CRM, вебхук, ваш data warehouse)

Send Email

НастройкаОписание
NameОбязательно. Идентификатор action
SubjectОбязательно. Тема письма
Message BodyОбязательно. Тело — можно с retrieval-переменными
Trigger ConditionКогда отправлять (пусто = всегда)
RecipientsОбязательно. Email-адреса, всегда получающие письмо
Conditional RecipientsМаппинг условие-получатель

Использование переменных в email:

Новый лид со звонка:

Имя: {{customer_name}}
Email: {{customer_email}}
Интересует: {{selected_plan}}
Заметки: {{call_notes}}

Send SMS

НастройкаОписание
NameОбязательно. Идентификатор
Sender NameОтображаемое имя отправителя
MessageОбязательно. Контент (можно с переменными)
Trigger ConditionКогда отправлять
RecipientsОбязательно. Номера, всегда получающие SMS
Conditional RecipientsМаппинг условие-номер

Send WhatsApp

WhatsApp на HANC использует предварительно одобренные шаблоны из централизованного Twilio Content-аккаунта — вы не вставляете Template SID вручную. Редактор action показывает выпадающий список всех активных и одобренных шаблонов, и вы выбираете один. Плейсхолдеры шаблона ({{1}}, {{2}}, …) заполняются inline из переменных звонка или статического текста, которые вы маппите в редакторе.

НастройкаОписание
NameОбязательно. Идентификатор
Trigger ConditionКогда отправлять
RecipientsОбязательно. Номера, всегда получающие сообщение
Conditional RecipientsМаппинг условие-номер
TemplateОбязательно. Выпадающий список предодобренных WhatsApp-шаблонов, синхронизируемых из централизованного Twilio Content-аккаунта. Каждая запись показывает имя шаблона, язык и превью тела.
Template VariablesДля выбранного шаблона редактор перечисляет каждый плейсхолдер ({{1}}, {{2}}, …) и позволяет смапить на переменную звонка (см. ниже) или статическую строку.

Доступные переменные звонка для маппинга в плейсхолдеры:

ПеременнаяОписание
{{call_from}}Номер звонящего
{{call_to}}Номер, на который звонили
{{call_summary}}AI-резюме звонка
{{call_sentiment}}Sentiment (positive/neutral/negative)
{{call_task_achieved}}Достигнута ли задача звонка
{{call_transcription}}Полная транскрипция звонка
Почему picker, а не свободный текст

WhatsApp требует, чтобы каждое business-initiated сообщение вне 24-часового customer-service окна использовало предодобренный шаблон. HANC синхронизирует список одобренных шаблонов из общего Twilio Content-аккаунта, так что выпадающий список всегда показывает ровно то, что прямо сейчас разрешено отправлять — нельзя случайно выбрать черновик, отклонённый шаблон или несуществующий SID. Чтобы добавить новый шаблон, свяжитесь с поддержкой; после одобрения WhatsApp он появится в списке автоматически.

API Call

Пост-звоночный API Call action — ваш универсальный вебхук в остальной стек. Выберите метод, задайте URL — и мы отправим весь payload звонка. Ваш эндпоинт получает структурированный JSON-объект, описывающий, что произошло.

НастройкаОписание
NameОбязательно. Идентификатор
Trigger ConditionКогда срабатывать (пусто = каждый звонок). Оценивается LLM по транскрипции.
API URLОбязательно. URL эндпоинта
HTTP MethodОбязательно. GET, POST, PUT, DELETE, PATCH
HeadersОпциональные заголовки
Query ParametersОпциональные query-параметры

Что получает ваш эндпоинт

Для POST / PUT / PATCH эндпоинт получает JSON-объект в теле. Ваши body-параметры мёрджатся с полным payload звонка:

{
"call_from": "+431234567890",
"call_to": "+439876543210",
"direction": "inbound",
"call_type": "phone",
"call_status": "ended",
"start_timestamp": 1730000000000,
"end_timestamp": 1730000187000,
"duration": 187000,
"transcription": [
{ "speaker": "agent", "content": "Hello…", "timestamp": 1730000001000 },
{ "speaker": "user", "content": "Hi…", "timestamp": 1730000003000 }
],
"call_summary": "Клиент спрашивал про цены…",
"task_achieved": true,
"sentiment": { "sentiment": "positive", "explanation": "…" },
"custom_analysis_data": {
"name": "John",
"email": "john@example.com"
},
"collected_data": { /* отправки in-call форм */ },
"transfer_history": [ /* если был agent transfer */ ],
"recording_url": "https://…",
"disconnection_reason": "user_hangup",
"is_anonymous": false,
"is_simulation": false,
"created_at": 1730000000000,
"updated_at": 1730000187000
}

Для GET / DELETE те же поля разворачиваются в query-строку — но вложенные значения вроде transcription, sentiment и custom_analysis_data отбрасываются (URL не несут структурированные данные адекватно). Используйте POST/PUT/PATCH, если нужен транскрипт.

Каждый запрос также получает заголовок X-Correlation-Id для трейсинга и таймаут 30 секунд.

Pre-fetch vs Post-call API Call
  • Pre fetch шаблонизирует {phone} и т. д. в URL/headers/query/body. Возвращает в промпт перед звонком.
  • Post call API Call шлёт весь дамп звонка в теле или query. Без шаблонизации URL — эндпоинт получает статический URL + динамическое тело.

Retrieval Variables

Retrieval Variables — кастомные поля данных, которые AI автоматически извлекает из разговоров. Например, агент может зафиксировать имя звонящего, email, номер или любую другую информацию, которую вы определите.

Дефолтные переменные

Каждый новый агент создаётся с двумя дефолтными retrieval-переменными:

ПеременнаяТипОписание
EmailEmailEmail звонящего
PhonePhoneТелефон звонящего

Они включены по умолчанию и показываются в форме виджета звонка. Можно редактировать или удалять, добавлять свои.

Типы переменных

ТипСценарийПример
TextИмена, адреса, заметки, свободный вводИмя клиента, адрес доставки
NumberКоличества, бюджеты, IDКоличество заказа, бюджет
EmailEmail с валидациейEmail клиента
PhoneТелефоны с валидациейТелефон клиента
SelectorВыбор из предопределённыхТариф (Basic/Pro/Enterprise)
CheckboxДа/нет согласие или подтверждение«Согласен на маркетинговые письма»

Настройка переменной

ПолеОписаниеПример
Variable NameОбязательно. Идентификаторcustomer_email
Instructions for AIОбязательно. Инструкции AI, когда и как извлекать"Email клиента. Спросить, если не дал."
Example Format(Опц.) Пример ожидаемого формата"john@example.com"
Options (для Selector)(Только Selector) Список разрешённых опций["Basic", "Pro", "Enterprise"]
Show in FormПоказывать ли поле в форме виджетаВключено по умолчанию

Show in Form

Когда Show in Form включено, переменная появляется как видимое поле в веб-виджете до и во время звонка. Это позволяет звонящим заполнять информацию напрямую, дополнительно к извлечению AI из разговора.

подсказка

AI естественно спросит недостающую информацию в разговоре. Задайте чёткое описание вроде «Email клиента, вежливо спросить, если не дал» — и агент разберётся.


Добавление Tools & Actions

  1. Перейдите на вкладку Actions агента.
  2. Нажмите Add Tool.
  3. Выберите правильную фазу из выпадающего списка — Pre fetch, Live call или Post call.
  4. Настройте параметры.
  5. Сохраните — изменения применятся на следующем звонке.

Все записи перечислены вместе в таблице Actions. Кликните любую строку, чтобы редактировать, или иконку корзины — чтобы удалить.


Связанное