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

Справочник API

Полная документация по API для интеграции Hanc.AI в ваши приложения. Управляйте агентами, получайте данные о звонках, совершайте звонки и управляйте любой частью платформы программно.

Каждый раздел ниже даёт вам HTTP-метод и путь, параметры (path, query и body), готовый к запуску пример запроса и репрезентативный пример ответа, чтобы вы могли выполнить интеграцию, не гадая о структуре данных.


Краткий обзор

Base URLhttps://api.hanc.ai
Префикс версииВсе маршруты имеют префикс /v1
АутентификацияКлюч API через заголовок x-api-key
ФорматJSON (запрос и ответ)

Сгенерируйте ключ API в разделе Integration → API Keys на панели управления. У вас может быть до 3 ключей на пользователя — см. раздел API Keys в Integrations с описанием настройки, прав доступа и рекомендаций по безопасности.

curl -X GET "https://api.hanc.ai/v1/agent/list" \
-H "x-api-key: YOUR_API_KEY"

Аутентификация

Передавайте свой ключ в заголовке x-api-key в каждом запросе:

x-api-key: YOUR_API_KEY

Ключ определяет пользователя-владельца, и каждый запрос автоматически ограничивается этим пользователем — вам никогда не нужно передавать ID пользователя. Отсутствующий или недействительный ключ отклоняется с 401 Unauthorized / 403 Forbidden.

подсказка

Храните ключи на стороне сервера. Никогда не встраивайте ключ API в браузер, мобильное приложение или любой клиент, который может проинспектировать конечный пользователь. Если ключ утёк, отзовите его в Integration → API Keys и выпустите новый.


Соглашения

Несколько правил действуют для всего API. Прочитав их один раз, вы сэкономите время на отладке:

  • Префикс версии — каждый путь начинается с /v1 (например, https://api.hanc.ai/v1/agent/list).
  • ID — это Mongo ObjectId — любой :id (а также :agentActionId, :agentToolId и т. д.) должен быть 24-символьной шестнадцатеричной строкой. Некорректные ID возвращают 400 Bad Request.
  • Неизвестные поля тела запроса отбрасываются — API валидирует тела запросов и молча отбрасывает свойства, которые не распознаёт, поэтому опечатка в имени поля игнорируется, а не сохраняется.
  • Даты — эндпоинты аналитики/экспорта принимают date_from / date_to в формате YYYY-MM-DD. date_to включительно до конца этого дня.
  • Массивы в query-параметрах — там, где фильтр принимает несколько значений (например, agent_ids, direction), вы можете повторить ключ (?direction=inbound&direction=outbound) или перечислить через запятую (?direction=inbound,outbound).
  • Временны́е метки в ответах — это миллисекунды эпохи, если не показаны в виде строки ISO-8601.

Индекс эндпоинтов

Краткая карта всего доступного. Подробная документация по каждому следует ниже.

Calls

ДействиеМетодЭндпоинт
Список звонковGET/v1/call/list
Детали звонка (транскрипт, тональность, сводка)GET/v1/call/:id
Общая аналитика (итоги за диапазон)GET/v1/call/general-metrics
Ежедневная аналитикаGET/v1/call/daily-metrics
Статистика тональностиGET/v1/call/sentiment-stats
Разбивка расходовGET/v1/call/costs-breakdown
Экспорт звонков (CSV)GET/v1/call/list/export
Экспорт расходов (CSV)GET/v1/call/costs-breakdown/export
Совершить телефонный звонокPOST/v1/call/make-phone-call
Совершить веб-звонокPOST/v1/call/make-web-call

Agents

ДействиеМетодЭндпоинт
Список агентовGET/v1/agent/list
Детали агентаGET/v1/agent/:id
Создать агентаPOST/v1/agent
Обновить агентаPATCH/v1/agent/:id
Удалить агентаDELETE/v1/agent/:id
Статистика звонков агентаGET/v1/agent/:id/call-stats
Список шаблонов агентовGET/v1/agent/agent_template/list
Список действийGET/v1/agent/:id/actions
Добавить действиеPOST/v1/agent/:id/actions
Обновить действиеPATCH/v1/agent/:id/actions/:agentActionId
Удалить действиеDELETE/v1/agent/:id/actions/:agentActionId
Список инструментовGET/v1/agent/:id/tools
Добавить инструментPOST/v1/agent/:id/tools
Обновить инструментPATCH/v1/agent/:id/tools/:agentToolId
Удалить инструментDELETE/v1/agent/:id/tools/:agentToolId

Knowledge Base

ДействиеМетодЭндпоинт
Список баз знанийGET/v1/knowledge-base/list
Создать (с первым файлом)POST/v1/knowledge-base
Добавить один файлPOST/v1/knowledge-base/:id/file
Добавить несколько файловPOST/v1/knowledge-base/:id/files
Удалить файл(ы)DELETE/v1/knowledge-base/:id/file
Назначить агентовPUT/v1/knowledge-base/:id/agents

Phone Numbers

ДействиеМетодЭндпоинт
Список номеровGET/v1/phone-number/list
Доступные номера (по стране)GET/v1/phone-number/available
Купить номерPOST/v1/phone-number/buy
Импортировать из TwilioPOST/v1/phone-number/import-twilio
Подключить к SIPPATCH/v1/phone-number/connect-to-sip

Voices · Subscription · Customers · Workspaces

ДействиеМетодЭндпоинт
Список голосовGET/v1/voice/list
Детали подпискиGET/v1/subscription
Настроить авто-пополнениеPATCH/v1/subscription/auto-top-up
Задать сумму пополненияPATCH/v1/subscription/top-up-amount
Список клиентовGET/v1/customer/list
Детали клиентаGET/v1/customer/:id
Создать клиентаPOST/v1/customer
Обновить клиентаPATCH/v1/customer/:id
Удалить клиентаDELETE/v1/customer/:id
Список рабочих пространствGET/v1/workspaces/list
Создать рабочее пространствоPOST/v1/workspaces
Детали рабочего пространстваGET/v1/workspaces/:id
Обновить рабочее пространствоPATCH/v1/workspaces/:id
Удалить рабочее пространствоDELETE/v1/workspaces/:id
Пригласить участникаPOST/v1/workspaces/:workspace_id/invite-member
Удалить участникаDELETE/v1/workspaces/:workspace_id/remove-member

Calls

Управляйте голосовыми звонками и анализируйте их: получайте список звонков и инспектируйте их (транскрипт, тональность, сводка), извлекайте агрегированные метрики, экспортируйте CSV-отчёты и совершайте исходящие телефонные и веб-звонки.

Список звонков

GET /v1/call/list

Получить список звонков вашего аккаунта с фильтрацией, сортировкой и постраничной навигацией.

Query-параметры

ИмяТипОбязательныйОписание
agent_idsstring[]НетФильтр по одному или нескольким ID агентов (повтор или перечисление через запятую).
agent_idstringНетФильтр по одному агенту (устаревший; предпочтительнее agent_ids).
directionenum[]Нетinbound и/или outbound.
call_statusenum[]Нетstarted, success, failed, pending.
call_typeenum[]Нетphone, web.
customer_idstringНетФильтр по клиенту.
workspace_idstringНетФильтр по рабочему пространству.
date_from / date_tostringНетФильтр по диапазону (YYYY-MM-DD).
sort_orderenumНетasc или desc.
limitnumberНетМаксимальное число возвращаемых результатов.
skipnumberНетСколько результатов пропустить (смещение для пагинации).

Пример запроса

curl -G "https://api.hanc.ai/v1/call/list" \
-H "x-api-key: YOUR_API_KEY" \
--data-urlencode "agent_ids=507f1f77bcf86cd799439042" \
--data-urlencode "direction=inbound" \
--data-urlencode "sort_order=desc" \
--data-urlencode "limit=10"

Пример ответа200 OK

[
{
"_id": "507f1f77bcf86cd799439011",
"call_type": "phone",
"agent_id": "507f1f77bcf86cd799439042",
"agent_name": "Customer Support Agent",
"call_status": "success",
"call_from": "+12345678900",
"call_to": "+12345678911",
"direction": "inbound",
"start_timestamp": 1703302407333,
"end_timestamp": 1703302428855,
"recording_url": "https://recordings.example.com/12345",
"disconnection_reason": "user_hangup",
"sentiment": { "sentiment": "positive", "explanation": "Friendly, helpful tone." },
"call_summary": "Customer issue resolved.",
"task_achieved": true
}
]

Получить детали звонка

GET /v1/call/:id

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

Path-параметры

ИмяТипОбязательныйОписание
idstringДаID звонка.

Пример запроса

curl "https://api.hanc.ai/v1/call/507f1f77bcf86cd799439011" \
-H "x-api-key: YOUR_API_KEY"

Пример ответа200 OK

{
"_id": "507f1f77bcf86cd799439011",
"call_type": "phone",
"agent_id": "507f1f77bcf86cd799439042",
"agent_name": "Customer Support Agent",
"call_status": "success",
"call_from": "+12345678900",
"call_to": "+12345678911",
"direction": "inbound",
"start_timestamp": 1703302407333,
"end_timestamp": 1703302428855,
"recording_url": "https://recordings.example.com/12345",
"transcription": [
{ "speaker": "agent", "content": "Hello, how can I help?", "timestamp": 1703302407333 },
{ "speaker": "user", "content": "I need help with my order.", "timestamp": 1703302410000 }
],
"sentiment": { "sentiment": "positive", "explanation": "Friendly, helpful tone." },
"call_summary": "Customer issue resolved.",
"task_achieved": true,
"call_credits_details": {
"phone_call_credits": 1,
"web_call_credits": 0,
"text_message_credits": 0,
"call_forwarding_credits": 0
}
}

Возвращает 404, если звонок не существует или не принадлежит вашему аккаунту.

Общие метрики

GET /v1/call/general-metrics

Агрегированные итоги (количество звонков, суммарная и средняя длительность) за диапазон дат.

Query-параметры

ИмяТипОбязательныйОписание
date_fromstringДаНачальная дата (YYYY-MM-DD).
date_tostringДаКонечная дата (YYYY-MM-DD, включительно).
agent_id / agent_idsstring(s)НетОграничить одним или несколькими агентами.
customer_idstringНетФильтр по клиенту.
workspace_idstringНетФильтр по рабочему пространству.
direction / call_status / call_typeenum[]НетТе же фильтры, что и в Список звонков.

Пропуск date_from или date_to возвращает 400 Bad Request.

Пример запроса

curl -G "https://api.hanc.ai/v1/call/general-metrics" \
-H "x-api-key: YOUR_API_KEY" \
--data-urlencode "date_from=2026-05-01" \
--data-urlencode "date_to=2026-05-31"

Пример ответа200 OK

{ "total_calls": 128, "total_duration": 45230, "average_duration": 353 }

Ежедневные метрики

GET /v1/call/daily-metrics

Суммарная длительность звонков по дням за диапазон дат — идеально для построения графиков трендов.

Query-параметры — те же, что и в Общие метрики (date_from/date_to обязательны, плюс необязательные фильтры по агенту/клиенту/рабочему пространству/направлению/статусу/типу).

Пример запроса

curl -G "https://api.hanc.ai/v1/call/daily-metrics" \
-H "x-api-key: YOUR_API_KEY" \
--data-urlencode "date_from=2026-05-01" \
--data-urlencode "date_to=2026-05-07"

Пример ответа200 OK

[
{ "date": "2026-05-01", "total_duration": 5400 },
{ "date": "2026-05-02", "total_duration": 7320 },
{ "date": "2026-05-03", "total_duration": 0 }
]

Статистика тональности

GET /v1/call/sentiment-stats

Количество звонков по тональности для одного агента за диапазон дат.

Query-параметры

ИмяТипОбязательныйОписание
agent_idstringДаАгент, по которому строится отчёт.
date_fromstringДаНачальная дата.
date_tostringДаКонечная дата (включительно).

Пример запроса

curl -G "https://api.hanc.ai/v1/call/sentiment-stats" \
-H "x-api-key: YOUR_API_KEY" \
--data-urlencode "agent_id=507f1f77bcf86cd799439042" \
--data-urlencode "date_from=2026-05-01" \
--data-urlencode "date_to=2026-05-31"

Пример ответа200 OK

{ "positive": 84, "negative": 12, "neutral": 32 }

Разбивка расходов

GET /v1/call/costs-breakdown

Разбивка расходов/использования (звонки, минуты, кредиты, токены, детализация по моделям), сгруппированная по пользователю, агенту или рабочему пространству.

Query-параметры

ИмяТипОбязательныйОписание
date_fromstringДаНачальная дата.
date_tostringДаКонечная дата (включительно).
group_byenumНетuser (по умолчанию), agent или workspace.
customer_idstringНетФильтр по клиенту (доступ агентства).
workspace_idstringНетФильтр по рабочему пространству.

Пример запроса

curl -G "https://api.hanc.ai/v1/call/costs-breakdown" \
-H "x-api-key: YOUR_API_KEY" \
--data-urlencode "date_from=2026-05-01" \
--data-urlencode "date_to=2026-05-31" \
--data-urlencode "group_by=agent"

Пример ответа200 OK

{
"breakdown": [
{
"agent_id": "507f1f77bcf86cd799439042",
"agent_name": "Customer Support Agent",
"total_calls": 64,
"total_duration_minutes": 380,
"credits": { "phone_call": 60, "web_call": 4, "text_message": 0, "call_forwarding": 1, "total": 65 },
"tokens": { "input": 920000, "output": 120000, "total": 1040000 }
}
],
"totals": { "total_calls": 64, "total_duration_minutes": 380, "total_credits": 65, "total_tokens": 1040000 },
"period": { "from": 1746057600000, "to": 1748735999999 }
}

Экспорт звонков (CSV)

GET /v1/call/list/export

Скачать все звонки за диапазон дат в виде CSV-файла (с детализацией токенов по каждому звонку и каждой модели).

Query-параметры

ИмяТипОбязательныйОписание
date_fromstringДаНачальная дата.
date_tostringДаКонечная дата (включительно).

Ответ — CSV-файл (Content-Type: text/csv), отдаваемый как вложение с именем call-details_<date_from>_<date_to>.csv.

Пример запроса

curl -G "https://api.hanc.ai/v1/call/list/export" \
-H "x-api-key: YOUR_API_KEY" \
--data-urlencode "date_from=2026-05-01" \
--data-urlencode "date_to=2026-05-31" \
-o call-details.csv

Экспорт расходов (CSV)

GET /v1/call/costs-breakdown/export

Скачать разбивку расходов в виде CSV-файла.

Query-параметры — те же, что и в Разбивка расходов (date_from/date_to обязательны; необязательные group_by, customer_id, workspace_id).

Ответ — CSV-файл, отдаваемый как costs-breakdown_<date_from>_<date_to>.csv.

Пример запроса

curl -G "https://api.hanc.ai/v1/call/costs-breakdown/export" \
-H "x-api-key: YOUR_API_KEY" \
--data-urlencode "date_from=2026-05-01" \
--data-urlencode "date_to=2026-05-31" \
--data-urlencode "group_by=agent" \
-o costs-breakdown.csv

Совершить телефонный звонок

POST /v1/call/make-phone-call

Совершить исходящий телефонный звонок от одного из ваших агентов.

Тело запроса

ПолеТипОбязательныйОписание
agent_idstringДаАгент, который совершит звонок.
from_numberstringДаИдентификатор звонящего в формате E.164 (например, +1234567890).
to_numberstringДаТелефонный номер получателя.
custom_dataobjectНетПроизвольные данные, прикреплённые к звонку.
dynamic_contextobjectНетКонтекст, передаваемый в разговор (например, имя клиента).

Пример запроса

curl -X POST "https://api.hanc.ai/v1/call/make-phone-call" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"agent_id": "507f1f77bcf86cd799439042",
"from_number": "+1234567890",
"to_number": "+19876543210",
"dynamic_context": { "customer_name": "Jane", "order_id": "12345" }
}'

Пример ответа201 Created

{
"_id": "507f1f77bcf86cd799439011",
"call_type": "phone",
"agent_id": "507f1f77bcf86cd799439042",
"call_status": "started",
"call_from": "+1234567890",
"call_to": "+19876543210",
"direction": "outbound",
"start_timestamp": 1703302407333
}

Совершить веб-звонок

POST /v1/call/make-web-call

Создать сессию браузерного/WebRTC-звонка для одного из ваших агентов.

Тело запроса

ПолеТипОбязательныйОписание
agent_idstringДаАгент, который обработает веб-звонок.
custom_dataobjectНетПроизвольные данные, прикреплённые к звонку.
dynamic_contextobjectНетКонтекст, передаваемый в разговор.

Пример запроса

curl -X POST "https://api.hanc.ai/v1/call/make-web-call" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "agent_id": "507f1f77bcf86cd799439042", "dynamic_context": { "topic": "billing" } }'

Пример ответа201 Created

{
"_id": "507f1f77bcf86cd799439077",
"call_type": "web",
"agent_id": "507f1f77bcf86cd799439042",
"call_status": "started",
"start_timestamp": 1703302407333
}

Agents

Создавайте голосовых агентов и управляйте ими, их действиями (что они делают во время звонка — отправляют email/SMS/WhatsApp, вызывают ваш API) и их инструментами (возможности, такие как RAG-поиск, запись на приём, переадресация звонков, интеграции с календарём/CRM).

Список агентов

GET /v1/agent/list

Вернуть всех агентов, принадлежащих вашему аккаунту.

Query-параметры

ИмяТипОбязательныйОписание
customer_idstringНетОграничить клиентом.
workspace_idstringНетОграничить рабочим пространством.

Пример запроса

curl "https://api.hanc.ai/v1/agent/list" \
-H "x-api-key: YOUR_API_KEY"

Пример ответа200 OK

[
{
"_id": "60d21b4667d0d8992e610c85",
"agent_name": "Customer Support Agent",
"llm_id": "60d21b4667d0d8992e610c86",
"voice": { "voice_id": "60d21b4667d0d8992e610c87" },
"interruption_sensitivity": 1.0,
"call_settings": { "language": "en-US", "sentiment_analysis": false, "call_summary": false },
"status": "active",
"workspace_id": "60d21b4667d0d8992e610c87",
"knowledge_base": ["60d21b4667d0d8992e610c89"]
}
]

Получить агента

GET /v1/agent/:id

Вернуть одного агента.

Path-параметры

ИмяТипОбязательныйОписание
idstringДаID агента.

Пример запроса

curl "https://api.hanc.ai/v1/agent/60d21b4667d0d8992e610c85" \
-H "x-api-key: YOUR_API_KEY"

Возвращает объект агента (та же структура, что и один элемент из Список агентов), или 404, если не найден.

Создать агента

POST /v1/agent

Создать нового агента. Обязательны только agent_name и llm_id — всё остальное необязательно и использует разумные значения по умолчанию.

Query-параметры — необязательные customer_id, workspace_id для привязки нового агента.

Тело запроса

ПолеТипОбязательныйОписание
agent_namestringДаОтображаемое имя.
llm_idstringДаID LLM, на которой работает агент.
voiceobjectНет{ "voice_id": "<id>" }.
interruption_sensitivitynumberНетНасколько легко агент уступает при прерывании (например, 0.5).
call_settingsobjectНетЯзык, напоминания, таймаут молчания, анализ тональности, сводка звонка, max_call_duration_minutes (1–15).
data_retrievalobject[]НетПоля, которые агент собирает во время звонка.
webhook_urlstringНетURL, уведомляемый о событиях агента.
is_data_collection_activebooleanНетВключить форму сбора данных.

Пример запроса

curl -X POST "https://api.hanc.ai/v1/agent" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"agent_name": "Customer Support Agent",
"llm_id": "507f1f77bcf86cd799439033",
"voice": { "voice_id": "507f1f77bcf86cd799439035" },
"interruption_sensitivity": 0.5,
"call_settings": { "language": "en-US", "max_call_duration_minutes": 10 }
}'

Пример ответа201 Created (созданный объект агента).

Обновить агента

PATCH /v1/agent/:id

Частично обновить агента. Все поля тела необязательны — отправляйте только то, что хотите изменить.

Path-параметрыid (ID агента).

Тело запроса — любое подмножество полей создания, плюс folder, status (например, active), is_customer_memory_active, widget_settings, callback_settings. Внутри call_settings также можно задать recording_enabled, stt_languages (до 4 кодов BCP-47) и max_call_duration_minutes.

Пример запроса

curl -X PATCH "https://api.hanc.ai/v1/agent/60d21b4667d0d8992e610c85" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "agent_name": "Support Agent v2", "call_settings": { "language": "en-GB", "recording_enabled": false } }'

Пример ответа200 OK (обновлённый объект агента).

Удалить агента

DELETE /v1/agent/:id

Удалить агента.

Пример запроса

curl -X DELETE "https://api.hanc.ai/v1/agent/60d21b4667d0d8992e610c85" \
-H "x-api-key: YOUR_API_KEY"

Пример ответа204 No Content (пустое тело).

Статистика звонков агента

GET /v1/agent/:id/call-stats

Количество звонков по дням для одного агента за диапазон дат.

Path-параметрыid (ID агента).

Query-параметры

ИмяТипОбязательныйОписание
date_fromstringДаНачальная дата (YYYY-MM-DD).
date_tostringДаКонечная дата (YYYY-MM-DD).

Пример запроса

curl -G "https://api.hanc.ai/v1/agent/60d21b4667d0d8992e610c85/call-stats" \
-H "x-api-key: YOUR_API_KEY" \
--data-urlencode "date_from=2026-05-01" \
--data-urlencode "date_to=2026-05-31"

Пример ответа200 OK

[
{ "date": "2026-05-28", "total_calls": 10 },
{ "date": "2026-05-29", "total_calls": 4 }
]

Список шаблонов агентов

GET /v1/agent/agent_template/list

Вернуть каталог готовых шаблонов агентов, которые вы можете клонировать. Без параметров.

Пример запроса

curl "https://api.hanc.ai/v1/agent/agent_template/list" \
-H "x-api-key: YOUR_API_KEY"

Пример ответа200 OK

[
{
"_id": "60d21b4667d0d8992e610c85",
"icon_url": "https://example.com/icon.png",
"description": "A ready-made receptionist agent.",
"agent": { "agent_name": "Receptionist", "call_settings": { "language": "en-US" } },
"llm": { "model": "gpt-4o-mini", "begin_message": "Hello, how can I assist you today?" }
}
]

Действия агента

Действия — это то, что агент выполняет во время звонка. Поддерживаемые значения action_type: send_email, send_sms, send_whatsapp, api_call. Структура объекта settings зависит от типа.

Список действий

GET /v1/agent/:id/actions

curl "https://api.hanc.ai/v1/agent/60d21b4667d0d8992e610c85/actions" \
-H "x-api-key: YOUR_API_KEY"

Возвращает массив объектов действий.

Добавить действие

POST /v1/agent/:id/actions

Тело запроса

ПолеТипОбязательныйОписание
action_typeenumДаsend_email, send_sms, send_whatsapp или api_call.
settingsobjectДаКонфигурация для конкретного типа.
is_activebooleanНетПо умолчанию true.

Пример запроса

curl -X POST "https://api.hanc.ai/v1/agent/60d21b4667d0d8992e610c85/actions" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"action_type": "send_email",
"settings": {
"name": "Welcome Email",
"subject": "Welcome!",
"message": "Thank you for joining us.",
"direct_recipients": ["user@example.com"]
}
}'

Пример ответа201 Created

{
"_id": "60f5b1a8d1b9f7c1d0c0a6c6",
"agent_id": "60d21b4667d0d8992e610c85",
"action_type": "send_email",
"settings": { "name": "Welcome Email", "subject": "Welcome!", "message": "Thank you for joining us.", "direct_recipients": ["user@example.com"] },
"is_active": true
}

Обновить действие

PATCH /v1/agent/:id/actions/:agentActionId

Обновить settings и/или is_active прикреплённого действия. Оба поля тела необязательны.

curl -X PATCH "https://api.hanc.ai/v1/agent/60d21b4667d0d8992e610c85/actions/60f5b1a8d1b9f7c1d0c0a6c6" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "is_active": false }'

Возвращает 200 OK с обновлённым объектом действия.

Удалить действие

DELETE /v1/agent/:id/actions/:agentActionId

curl -X DELETE "https://api.hanc.ai/v1/agent/60d21b4667d0d8992e610c85/actions/60f5b1a8d1b9f7c1d0c0a6c6" \
-H "x-api-key: YOUR_API_KEY"

Возвращает 204 No Content.

Инструменты агента

Инструменты дают агенту дополнительные возможности. Поддерживаемые значения tool_type: api_rag, appointment_booking, call_forwarding, end_call, google_calendar, outlook_calendar, etermin, resmio, hubspot_crm, agent_transfer, mcp. Структура объекта settings зависит от типа.

etermin и resmio — это инструменты живой записи на приём/бронирования: агент проверяет доступность и бронирует, переносит или отменяет запись напрямую в подключённом аккаунте eTermin или resmio. Оба требуют, чтобы соответствующая интеграция сначала была подключена к аккаунту.

Список инструментов

GET /v1/agent/:id/tools

curl "https://api.hanc.ai/v1/agent/60d21b4667d0d8992e610c85/tools" \
-H "x-api-key: YOUR_API_KEY"

Возвращает массив объектов инструментов.

Добавить инструмент

POST /v1/agent/:id/tools

Тело запроса

ПолеТипОбязательныйОписание
tool_typeenumДаОдин из поддерживаемых типов инструментов выше.
settingsobjectДаКонфигурация для конкретного типа.
is_activebooleanНетПо умолчанию true.

Пример запроса

curl -X POST "https://api.hanc.ai/v1/agent/60d21b4667d0d8992e610c85/tools" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"tool_type": "call_forwarding",
"settings": { "name": "Transfer to human", "phone_number": "+1234567890" }
}'

Пример ответа201 Created

{
"_id": "60f5b1a8d1b9f7c1d0c0a6c6",
"agent_id": "60d21b4667d0d8992e610c85",
"tool_type": "call_forwarding",
"settings": { "name": "Transfer to human", "phone_number": "+1234567890" },
"is_active": true
}

Обновить инструмент

PATCH /v1/agent/:id/tools/:agentToolId

Обновить settings и/или is_active прикреплённого инструмента (оба необязательны).

curl -X PATCH "https://api.hanc.ai/v1/agent/60d21b4667d0d8992e610c85/tools/60f5b1a8d1b9f7c1d0c0a6c6" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "is_active": false }'

Возвращает 200 OK с обновлённым объектом инструмента.

Удалить инструмент

DELETE /v1/agent/:id/tools/:agentToolId

curl -X DELETE "https://api.hanc.ai/v1/agent/60d21b4667d0d8992e610c85/tools/60f5b1a8d1b9f7c1d0c0a6c6" \
-H "x-api-key: YOUR_API_KEY"

Возвращает 204 No Content.


Knowledge Base

Загружайте документы, по которым ваши агенты могут выполнять поиск во время звонка, и управляйте тем, какие агенты используют каждую базу знаний. Загрузка файлов использует multipart/form-data.

Список баз знаний

GET /v1/knowledge-base/list

Query-параметры — необязательные customer_id, workspace_id.

curl "https://api.hanc.ai/v1/knowledge-base/list" \
-H "x-api-key: YOUR_API_KEY"

Пример ответа200 OK

[
{
"_id": "60d21b4667d0d8992e610c85",
"knowledge_base_name": "Company Policies",
"knowledge_base_description": "Refund, shipping and warranty policies.",
"files": [
{ "_id": "60d21b4667d0d8992e610c90", "file_name": "policies.pdf", "file_size": 2048000, "uploaded_at": "2026-05-24T07:34:23.980Z" }
],
"agent_names": ["Sales Agent", "Support Bot"]
}
]

Создать базу знаний

POST /v1/knowledge-base

Создать базу знаний вместе с её первым файлом. Это запрос multipart/form-data — «создания» только на основе тела не существует.

Query-параметры — необязательные customer_id, workspace_id.

Поля формы

ПолеТипОбязательныйОписание
filefileДаПервый документ (например, PDF).
namestringДаИмя базы знаний (1–100 символов).
descriptionstringДаОписание (1–300 символов).
folderstringНетМетка папки/категории (0–50 символов).

Пример запроса

curl -X POST "https://api.hanc.ai/v1/knowledge-base" \
-H "x-api-key: YOUR_API_KEY" \
-F "file=@./policies.pdf" \
-F "name=Company Policies" \
-F "description=Refund, shipping and warranty policies." \
-F "folder=Sales"

Пример ответа200 OK (созданная база знаний, та же структура, что и элемент списка).

Добавить один файл

POST /v1/knowledge-base/:id/file

Добавить один файл в существующую базу знаний. Имя multipart-поля: file.

curl -X POST "https://api.hanc.ai/v1/knowledge-base/60d21b4667d0d8992e610c85/file" \
-H "x-api-key: YOUR_API_KEY" \
-F "file=@./addendum.pdf"

Возвращает 200 OK с обновлённой базой знаний.

Добавить несколько файлов

POST /v1/knowledge-base/:id/files

Добавить несколько файлов сразу. Имя multipart-поля: files (повторить для каждого файла). Необязательные query-параметры customer_id, workspace_id.

curl -X POST "https://api.hanc.ai/v1/knowledge-base/60d21b4667d0d8992e610c85/files" \
-H "x-api-key: YOUR_API_KEY" \
-F "files=@./doc1.pdf" \
-F "files=@./doc2.pdf"

Возвращает 200 OK с обновлённой базой знаний.

Удалить файл(ы)

DELETE /v1/knowledge-base/:id/file

Удалить один или несколько файлов по ID. Несмотря на единственное число в пути, тело принимает массив.

Тело запроса

ПолеТипОбязательныйОписание
file_idsstring[]ДаНепустой массив ID файлов для удаления.
curl -X DELETE "https://api.hanc.ai/v1/knowledge-base/60d21b4667d0d8992e610c85/file" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "file_ids": ["60c72b2f9b1e8b001c8e4d3a", "60c72b2f9b1e8b001c8e4d3b"] }'

Возвращает 200 OK.

Назначить агентов

PUT /v1/knowledge-base/:id/agents

Задать (заменить) полный список агентов, использующих эту базу знаний.

Тело запроса

ПолеТипОбязательныйОписание
agent_idsstring[]ДаID агентов, которые должны использовать эту базу знаний.
curl -X PUT "https://api.hanc.ai/v1/knowledge-base/60d21b4667d0d8992e610c85/agents" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "agent_ids": ["60d21b4667d0d8992e610c85"] }'

Возвращает 200 OK.


Phone Numbers

Получайте список ваших номеров, находите номера, доступные для покупки, покупайте номер, импортируйте номера из подключённого аккаунта Twilio или подключайте номер к SIP-транку.

Покупка номеров на панели управления

Покупка номеров на панели управления выходит за рамки того, что предоставляют эти эндпоинты. Мгновенные номера без оформления документов доступны в Австрии, Германии, Швейцарии, США и Канаде; для любой другой страны используется пошаговый процесс в режиме самообслуживания, где вы подаёте собственные регуляторные документы (и можете сохранить их как черновик, чтобы продолжить позже). Экран покупки предлагает типы local, mobile, national и toll-free — плюс advanced numbers (+€2/месяц) и номера с поддержкой звонков WhatsApp. BYO SIP не привязан к вендору (sipgate, Placetel, TENIOS, easybell, Zadarma, Telnyx, произвольные транки — не только импорт из Twilio). Полный процесс см. в Phone Numbers.

Список телефонных номеров

GET /v1/phone-number/list

Query-параметры — все необязательные: inbound_agent_id, outbound_agent_id, customer_id, workspace_iduser_id, по умолчанию вы).

curl "https://api.hanc.ai/v1/phone-number/list" \
-H "x-api-key: YOUR_API_KEY"

Пример ответа200 OK

[
{
"_id": "60d21b4667d0d8992e610c85",
"phone_number": "+1234567890",
"formatted_number": "+1 (234) 567-8900",
"country": "US",
"provider": "twilio",
"status": "active",
"inbound_agent_id": "64bfb7b3f3d9ab3f1e2c109c",
"inbound_agent_name": "Receptionist"
}
]

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

GET /v1/phone-number/available

Список номеров, доступных для покупки в стране.

Query-параметры

ИмяТипОбязательныйОписание
country_codestringНетISO-код страны (по умолчанию US), например DE, AT, CH.
area_codestringНетЧисловой фильтр по коду региона.
curl -G "https://api.hanc.ai/v1/phone-number/available" \
-H "x-api-key: YOUR_API_KEY" \
--data-urlencode "country_code=US" \
--data-urlencode "area_code=415"

Пример ответа200 OK

[
{ "phone_number": "+14155550100", "formatted_number": "+1 (415) 555-0100", "country": "US", "area_code": "415", "setup_fee": 2, "subscription": 2, "currency": "EUR" }
]

Купить номер

POST /v1/phone-number/buy

Купить конкретный номер. Необязательные query-параметры customer_id, workspace_id.

Тело запроса

ПолеТипОбязательныйОписание
phone_numberstringДаНомер для покупки (E.164).
country_codestringДаСтрана номера (например, US).
curl -X POST "https://api.hanc.ai/v1/phone-number/buy" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "phone_number": "+14155550100", "country_code": "US" }'

Пример ответа200 OK

{
"message": "Phone number purchased successfully!",
"phone_number": { "_id": "507f1f77bcf86cd799439011", "phone_number": "+14155550100", "country": "US", "provider": "twilio", "status": "active" }
}

Импортировать из Twilio

POST /v1/phone-number/import-twilio

Импортировать номера из подключённого аккаунта Twilio. Необязательные query-параметры customer_id, workspace_id.

Тело запроса

ПолеТипОбязательныйОписание
sidstringДаTwilio Account SID (AC…).
curl -X POST "https://api.hanc.ai/v1/phone-number/import-twilio" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" }'

Пример ответа200 OK (импортированная запись телефонного номера).

Подключить к SIP

PATCH /v1/phone-number/connect-to-sip

Подключить существующий номер к SIP-транку.

Тело запроса

ПолеТипОбязательныйОписание
phone_numberstringДаНомер для подключения (E.164).
curl -X PATCH "https://api.hanc.ai/v1/phone-number/connect-to-sip" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "phone_number": "+1234567890" }'

Возвращает 200 OK (пустое тело).


Voices

Список голосов

GET /v1/voice/list

Список доступных голосов. Фильтруйте по языку или провайдеру и включайте приватные клоны клиента.

Query-параметры

ИмяТипОбязательныйОписание
languagestringНетФильтр по языку, например ?language=de.
providerstringНет11-Labs, openai, qwen или azure.
customer_idstringНетТакже включить приватные голосовые клоны этого клиента.
curl -G "https://api.hanc.ai/v1/voice/list" \
-H "x-api-key: YOUR_API_KEY" \
--data-urlencode "language=de"

Пример ответа200 OK

[
{
"_id": "60d21b4667d0d8992e610c85",
"voice_id": "voice_12345",
"name": "Emma",
"gender": "female",
"accent": "British",
"languages": ["english", "spanish"],
"provider": "11-Labs",
"sample_url": "https://example.com/sample.mp3"
}
]

Subscription

Детали подписки

GET /v1/subscription

Вернуть вашу текущую подписку, включая балансы кредитов и настройки пополнения.

curl "https://api.hanc.ai/v1/subscription" \
-H "x-api-key: YOUR_API_KEY"

Пример ответа200 OK

{
"_id": "507f191e810c19729de860ea",
"payment_plan_id": "507f191e810c19729de860ec",
"currency": "EUR",
"package_credits": 1000,
"package_credits_used": 100,
"auto_top_up_enabled": false,
"top_up_amount": 50,
"extra_credits_payed": 1000,
"extra_credits_used": 100,
"billing_cycle": "monthly",
"next_credit_reset": "2026-06-15T03:00:00.000Z",
"is_cancelled": false
}

Возвращает 404, если записи о подписке не существует.

Настроить авто-пополнение

PATCH /v1/subscription/auto-top-up

Включить или выключить автоматическое пополнение кредитов.

Тело запроса

ПолеТипОбязательныйОписание
enabledbooleanДаВключить или выключить авто-пополнение.
amountnumberНетСумма пополнения (20–1000). Задаётся при включении.
curl -X PATCH "https://api.hanc.ai/v1/subscription/auto-top-up" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "enabled": true, "amount": 50 }'

Возвращает 200 OK с обновлённой подпиской.

Задать сумму пополнения

PATCH /v1/subscription/top-up-amount

Обновить настроенную сумму пополнения.

Тело запроса

ПолеТипОбязательныйОписание
top_up_amountnumberДаНовая сумма (1–100).
curl -X PATCH "https://api.hanc.ai/v1/subscription/top-up-amount" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "top_up_amount": 10 }'

Возвращает 200 OK с обновлённой подпиской.


Customers

Управляйте клиентами вашего агентства. Эти эндпоинты требуют, чтобы ваш аккаунт принадлежал агентству.

Список клиентов

GET /v1/customer/list

curl "https://api.hanc.ai/v1/customer/list" \
-H "x-api-key: YOUR_API_KEY"

Пример ответа200 OK

[
{
"_id": "60d21b4667d0d8992e610c85",
"email": "customer@example.com",
"name": "John Doe",
"account_status": "active",
"agents_count": 3
}
]

Детали клиента

GET /v1/customer/:id

curl "https://api.hanc.ai/v1/customer/60d21b4667d0d8992e610c85" \
-H "x-api-key: YOUR_API_KEY"

Возвращает объект клиента, или 404, если не найден.

Создать клиента

POST /v1/customer

Тело запроса

ПолеТипОбязательныйОписание
emailstringДаEmail клиента для входа.
initial_passwordstringДаНачальный пароль (8–128 символов).
namestringДаНазвание аккаунта/компании.
user_full_namestringДаПолное имя пользователя-клиента.
visibilityobjectНетФлаги видимости по разделам.
opt_out_promotionsbooleanНетОтписать клиента от промо-рассылок.
curl -X POST "https://api.hanc.ai/v1/customer" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"email": "customer@example.com",
"initial_password": "Password123!",
"name": "Acme Co.",
"user_full_name": "John Doe"
}'

Возвращает 201 Created с новым клиентом. Возвращает 400, если email уже существует или ваш аккаунт не является частью агентства.

Обновить клиента

PATCH /v1/customer/:id

Тело запроса — все необязательные: name, email, phone, address.

curl -X PATCH "https://api.hanc.ai/v1/customer/60d21b4667d0d8992e610c85" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "name": "Acme Corporation", "phone": "+1234567890" }'

Возвращает 200 OK с обновлённым клиентом.

Удалить клиента

DELETE /v1/customer/:id

curl -X DELETE "https://api.hanc.ai/v1/customer/60d21b4667d0d8992e610c85" \
-H "x-api-key: YOUR_API_KEY"

Пример ответа

{ "message": "Customer deleted successfully" }

Workspaces

Группируйте агентов, номера и базы знаний в рабочие пространства и управляйте их участниками.

Список рабочих пространств

GET /v1/workspaces/list

Необязательный query-параметр customer_id.

curl "https://api.hanc.ai/v1/workspaces/list" \
-H "x-api-key: YOUR_API_KEY"

Пример ответа200 OK

[
{
"_id": "64b1f2d2f3d92c5b8c5e1e22",
"name": "Workspace A",
"description": "For the A team.",
"owner_user_id": "64b1f2d2f3d92c5b8c5e1e10",
"members": [
{ "user_id": "64b1f2d2f3d92c5b8c5e1e11", "full_name": "John Doe", "email": "john.doe@example.com" }
]
}
]

Создать рабочее пространство

POST /v1/workspaces

Тело запроса

ПолеТипОбязательныйОписание
namestringДаИмя рабочего пространства (2–100 символов).
descriptionstringНетОписание (0–500 символов).
curl -X POST "https://api.hanc.ai/v1/workspaces" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "name": "Development Team", "description": "For the dev team." }'

Возвращает 201 Created с рабочим пространством.

Детали рабочего пространства

GET /v1/workspaces/:id

curl "https://api.hanc.ai/v1/workspaces/64b1f2d2f3d92c5b8c5e1e22" \
-H "x-api-key: YOUR_API_KEY"

Возвращает объект рабочего пространства.

Обновить рабочее пространство

PATCH /v1/workspaces/:id

Тело запросаname (2–100) и/или description (0–500).

curl -X PATCH "https://api.hanc.ai/v1/workspaces/64b1f2d2f3d92c5b8c5e1e22" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "name": "Renamed Workspace" }'

Возвращает 200 OK с обновлённым рабочим пространством.

Удалить рабочее пространство

DELETE /v1/workspaces/:id

curl -X DELETE "https://api.hanc.ai/v1/workspaces/64b1f2d2f3d92c5b8c5e1e22" \
-H "x-api-key: YOUR_API_KEY"

Пример ответа

{ "message": "Workspace deleted successfully" }

Пригласить участника

POST /v1/workspaces/:workspace_id/invite-member

Тело запроса

ПолеТипОбязательныйОписание
emailstringДаEmail пользователя для приглашения.
curl -X POST "https://api.hanc.ai/v1/workspaces/64b1f2d2f3d92c5b8c5e1e22/invite-member" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "email": "teammate@example.com" }'

Возвращает 201 Created с рабочим пространством (новый участник появляется в members).

Удалить участника

DELETE /v1/workspaces/:workspace_id/remove-member

Тело запроса

ПолеТипОбязательныйОписание
emailstringДаEmail участника для удаления.
curl -X DELETE "https://api.hanc.ai/v1/workspaces/64b1f2d2f3d92c5b8c5e1e22/remove-member" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "email": "teammate@example.com" }'

Возвращает 200 OK с обновлённым рабочим пространством.


Что недоступно через API

Некоторые операции доступны только через панель управления:

ВозможностьПричина
Управление ключами APIБезопасность — ключи не могут создавать другие ключи
Настройка телефонного номераТребует интерактивной настройки
Интеграция с Google CalendarТребует интерактивной авторизации
Биллинг и платежиУправляются через панель управления

Нужна помощь?

Свяжитесь с нашей командой поддержки по адресу support@hanc.ai по вопросам, связанным с API.