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, чтобы агент знал стадию лида и историю
Как работает
- Платформа резолвит телефон звонящего (из SIP для входящих, из dial target для исходящих).
- Каждый активный Pre fetch action срабатывает параллельно с жёстким таймаутом 1.5 с на запрос и общим бюджетом 2 с.
- Успешные ответы конкатенируются в системный промпт агента как именованные блоки — агент читает их на самом первом ходу.
- Сбои тихие — медленный или сломанный эндпоинт никогда не блокирует приветствие. Агент просто начинает говорить без этого блока.
Конфигурация
| Поле | Описание |
|---|---|
| Name | Обязательно. Внутренний label и имя блока в промпте — держите коротким и описательным (например, crm_lookup, vip_check). |
| API URL | Обязательно. Эндпоинт для запроса. Поддерживает плейсхолдеры {phone}, {direction}, {agent_id}, {user_id}, {call_id}. |
| HTTP Method | GET — дефолт и лучший выбор. POST / PUT / PATCH / DELETE тоже работают. |
| Headers | Опционально. Статические или шаблонные (плейсхолдеры работают). |
| Query Parameters | Опционально. Для новых pre-fetch предзаполняется phone={phone}. |
Доступные переменные
Эти токены подставляются в URL, заголовки и query/body-параметры во время запроса:
| Переменная | Источник | Пример значения |
|---|---|---|
{phone} | Телефон звонящего (E.164) — для исходящих, номер назначения | +431234567890 |
{direction} | inbound или outbound | inbound |
{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"} |
Как работает:
- Во время разговора AI оценивает Trigger Condition.
- Если заданы Conditional Routing Numbers — совпадающее условие определяет, какой номер набрать.
- Иначе используется Forwarding Number.
- Агент сообщает звонящему о передаче.
- Звонок переадресуется — если не отвечают, возвращается к агенту.
Можно добавить несколько Call Forwarding tools под разные отделы — один для «Sales» и другой для «Technical Support» с разными условиями и номерами.
Google Calendar
Подключите Google Calendar, чтобы агент мог проверять доступность и записывать в звонках.
Настройка:
- Сначала Integration → Calendars и подключите Google-аккаунт.
- Добавьте tool Google Calendar на вкладку Actions агента.
- Выберите календарь.
- Настройте доступность.
| Настройка | Описание | Дефолт |
|---|---|---|
| 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.
Настройка:
- Integration → Calendars и подключите Outlook-аккаунт.
- Добавьте tool Outlook Calendar на вкладку Actions агента.
- Выберите календарь.
- Настройте доступность.
Настройки идентичны Google Calendar (timezone, рабочие часы, длительность слота, рабочие дни, буфер).
Agent Transfer
Передача звонка другому голосовому агенту вашего аккаунта. Полезно, когда есть специализированные агенты для разных отделов.
| Настройка | Описание |
|---|---|
| Target Agent | Обязательно. Какому агенту передавать |
| Trigger Condition | Когда передавать (например, «Звонящий спрашивает о технической поддержке») |
Пример: Receptionist-агент передаёт звонящих sales-агенту, если они спрашивают про цены, или support-агенту, если у них техническая проблема.
HubSpot CRM
Чтение и запись в HubSpot CRM во время звонка. Позволяет агенту логировать взаимодействия, поднимать контакт по телефону или пушить обновления сделок без скриптинга API-вызовов.
Настройка:
- Зайдите на страницу Integrations и подключите HubSpot-аккаунт.
- Добавьте tool HubSpot CRM на вкладку Actions агента.
- Выберите, какие пайплайны и свойства агент может трогать.
После добавления tool AI может мэтчить звонящего с HubSpot-контактом по телефону, получать стадию сделки и обновлять поля — всё из живого разговора.
MCP servers
Откройте tools любого MCP-совместимого сервера, подключённого к Hanc.AI. Один агент может тянуть из нескольких MCP-серверов; один MCP-сервер может обслуживать несколько агентов.
Настройка:
- Подключите MCP-сервер(ы) один раз в Integration → MCP servers. См. полные шаги регистрации на странице MCP Servers.
- Добавьте запись MCP servers на вкладку Actions агента — в Add Action она в группе Live call.
- Включите подключения, которые этот агент должен использовать.
- Добавьте короткую инструкцию «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.
Справочник полей
| Поле | Назначение |
|---|---|
type | JSON-тип значения: "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 Email | Email-резюме команде или клиенту |
| Send SMS | SMS-подтверждение звонящему |
| Send WhatsApp | WhatsApp-сообщение или шаблон (работает внутри и вне 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}} | Полная транскрипция звонка |
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 шаблонизирует
{phone}и т. д. в URL/headers/query/body. Возвращает в промпт перед звонком. - Post call API Call шлёт весь дамп звонка в теле или query. Без шаблонизации URL — эндпоинт получает статический URL + динамическое тело.
Retrieval Variables
Retrieval Variables — кастомные поля данных, которые AI автоматически извлекает из разговоров. Например, агент может зафиксировать имя звонящего, email, номер или любую другую информацию, которую вы определите.
Дефолтные переменные
Каждый новый агент создаётся с двумя дефолтными retrieval-переменными:
| Переменная | Тип | Описание |
|---|---|---|
| Email звонящего | ||
| Phone | Phone | Телефон звонящего |
Они включены по умолчанию и показываются в форме виджета звонка. Можно редактировать или удалять, добавлять свои.
Типы переменных
| Тип | Сценарий | Пример |
|---|---|---|
| Text | Имена, адреса, заметки, свободный ввод | Имя клиента, адрес доставки |
| Number | Количества, бюджеты, ID | Количество заказа, бюджет |
| Email с валидацией | 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
- Перейдите на вкладку Actions агента.
- Нажмите Add Tool.
- Выберите правильную фазу из выпадающего списка — Pre fetch, Live call или Post call.
- Настройте параметры.
- Сохраните — изменения применятся на следующем звонке.
Все записи перечислены вместе в таблице Actions. Кликните любую строку, чтобы редактировать, или иконку корзины — чтобы удалить.
Связанное
- Обзор голосовых агентов
- Prompt Engineering — ссылайтесь на tools в промпте
- База знаний — источники информации
- Интеграции — внешние системы, с которыми tools говорят