Справочник API
Полная документация по API для интеграции Hanc.AI в ваши приложения. Управляйте агентами, получайте данные о звонках, совершайте звонки и управляйте любой частью платформы программно.
Каждый раздел ниже даёт вам HTTP-метод и путь, параметры (path, query и body), готовый к запуску пример запроса и репрезентативный пример ответа, чтобы вы могли выполнить интеграцию, не гадая о структуре данных.
Краткий обзор
| Base URL | https://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 |
| Импортировать из Twilio | POST | /v1/phone-number/import-twilio |
| Подключить к SIP | PATCH | /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_ids | string[] | Нет | Фильтр по одному или нескольким ID агентов (повтор или перечисление через запятую). |
agent_id | string | Нет | Фильтр по одному агенту (устаревший; предпочтительнее agent_ids). |
direction | enum[] | Нет | inbound и/или outbound. |
call_status | enum[] | Нет | started, success, failed, pending. |
call_type | enum[] | Нет | phone, web. |
customer_id | string | Нет | Фильтр по клиенту. |
workspace_id | string | Нет | Фильтр по рабочему пространству. |
date_from / date_to | string | Нет | Фильтр по диапазону (YYYY-MM-DD). |
sort_order | enum | Нет | asc или desc. |
limit | number | Нет | Максимальное число возвращаемых результатов. |
skip | number | Нет | Сколько результатов пропустить (смещение для пагинации). |
Пример запроса
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-параметры
| Имя | Тип | Обязательный | Описание |
|---|---|---|---|
id | string | Да | 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_from | string | Да | Начальная дата (YYYY-MM-DD). |
date_to | string | Да | Конечная дата (YYYY-MM-DD, включительно). |
agent_id / agent_ids | string(s) | Нет | Ограничить одним или несколькими агентами. |
customer_id | string | Нет | Фильтр по клиенту. |
workspace_id | string | Нет | Фильтр по рабочему пространству. |
direction / call_status / call_type | enum[] | Нет | Те же фильтры, что и в Список звонков. |
Пропуск
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_id | string | Да | Агент, по которому строится отчёт. |
date_from | string | Да | Начальная дата. |
date_to | string | Да | Конечная дата (включительно). |
Пример запроса
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_from | string | Да | Начальная дата. |
date_to | string | Да | Конечная дата (включительно). |
group_by | enum | Нет | user (по умолчанию), agent или workspace. |
customer_id | string | Нет | Фильтр по клиенту (доступ агентства). |
workspace_id | string | Нет | Фильтр по рабочему пространству. |
Пример запроса
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_from | string | Да | Начальная дата. |
date_to | string | Да | Конечная дата (включительно). |
Ответ — 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_id | string | Да | Агент, который совершит звонок. |
from_number | string | Да | Идентификатор звонящего в формате E.164 (например, +1234567890). |
to_number | string | Да | Телефонный номер получателя. |
custom_data | object | Нет | Произвольные данные, прикреплённые к звонку. |
dynamic_context | object | Нет | Контекст, передаваемый в разговор (например, имя клиента). |
Пример запроса
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_id | string | Да | Агент, который обработает веб-звонок. |
custom_data | object | Нет | Произвольные данные, прикреплённые к звонку. |
dynamic_context | object | Нет | Контекст, передаваемый в разговор. |
Пример запроса
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_id | string | Нет | Ограничить клиентом. |
workspace_id | string | Нет | Ограничить рабочим пространством. |
Пример запроса
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-параметры
| Имя | Тип | Обязательный | Описание |
|---|---|---|---|
id | string | Да | 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_name | string | Да | Отображаемое имя. |
llm_id | string | Да | ID LLM, на которой работает агент. |
voice | object | Нет | { "voice_id": "<id>" }. |
interruption_sensitivity | number | Нет | Насколько легко агент уступает при прерывании (например, 0.5). |
call_settings | object | Нет | Язык, напоминания, таймаут молчания, анализ тональности, сводка звонка, max_call_duration_minutes (1–15). |
data_retrieval | object[] | Нет | Поля, которые агент собирает во время звонка. |
webhook_url | string | Нет | URL, уведомляемый о событиях агента. |
is_data_collection_active | boolean | Нет | Включить форму сбора данных. |
Пример запроса
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_from | string | Да | Начальная дата (YYYY-MM-DD). |
date_to | string | Да | Конечная дата (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_type | enum | Да | send_email, send_sms, send_whatsapp или api_call. |
settings | object | Да | Конфигурация для конкретного типа. |
is_active | boolean | Нет | По умолчанию 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_type | enum | Да | Один из поддерживаемых типов инструментов выше. |
settings | object | Да | Конфигурация для конкретного типа. |
is_active | boolean | Нет | По умолчанию 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.
Поля формы
| Поле | Тип | Обязательный | Описание |
|---|---|---|---|
file | file | Да | Первый документ (например, PDF). |
name | string | Да | Имя базы знаний (1–100 символов). |
description | string | Да | Описание (1–300 символов). |
folder | string | Нет | Метка папки/категории (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_ids | string[] | Да | Непустой массив 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_ids | string[] | Да | 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_id (и user_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_code | string | Нет | ISO-код страны (по умолчанию US), например DE, AT, CH. |
area_code | string | Нет | Числовой фильтр по коду региона. |
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_number | string | Да | Номер для покупки (E.164). |
country_code | string | Да | Страна номера (например, 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.
Тело запроса
| Поле | Тип | Обязательный | Описание |
|---|---|---|---|
sid | string | Да | 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_number | string | Да | Номер для подключения (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-параметры
| Имя | Тип | Обязательный | Описание |
|---|---|---|---|
language | string | Нет | Фильтр по языку, например ?language=de. |
provider | string | Нет | 11-Labs, openai, qwen или azure. |
customer_id | string | Нет | Также включить приватные голосовые клоны этого клиента. |
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
Включить или выключить автоматическое пополнение кредитов.
Тело запроса
| Поле | Тип | Обязательный | Описание |
|---|---|---|---|
enabled | boolean | Да | Включить или выключить авто-пополнение. |
amount | number | Нет | Сумма пополнения (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_amount | number | Да | Новая сумма (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
Тело запроса
| Поле | Тип | Обязательный | Описание |
|---|---|---|---|
email | string | Да | Email клиента для входа. |
initial_password | string | Да | Начальный пароль (8–128 символов). |
name | string | Да | Название аккаунта/компании. |
user_full_name | string | Да | Полное имя пользователя-клиента. |
visibility | object | Нет | Флаги видимости по разделам. |
opt_out_promotions | boolean | Нет | Отписать клиента от промо-рассылок. |
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
Тело запроса
| Поле | Тип | Обязательный | Описание |
|---|---|---|---|
name | string | Да | Имя рабочего пространства (2–100 символов). |
description | string | Нет | Описание (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
Тело запроса
| Поле | Тип | Обязательный | Описание |
|---|---|---|---|
email | string | Да | 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
Тело запроса
| Поле | Тип | Обязательный | Описание |
|---|---|---|---|
email | string | Да | 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.