Довідник API

Повна документація API для інтеграції Hanc.AI у ваші застосунки. Керуйте агентами, отримуйте дані про дзвінки, здійснюйте дзвінки та керуйте кожною частиною платформи програмно.

Кожен розділ нижче надає вам HTTP-метод і шлях, параметри (шлях, запит і тіло), готовий до запуску приклад запиту та репрезентативний приклад відповіді, щоб ви могли інтегруватися, не гадаючи щодо структури payload.

Швидкий огляд


Base URL	`https://api.hanc.ai`
Version prefix	Усі маршрути мають префікс `/v1`
Authentication	API-ключ через заголовок `x-api-key`
Format	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. Прочитавши їх один раз, ви заощадите час на налагодженні:

Version prefix — кожен шлях починається з /v1 (наприклад, https://api.hanc.ai/v1/agent/list).
IDs are Mongo ObjectIds — будь-який :id (а також :agentActionId, :agentToolId тощо) має бути 24-символьним шістнадцятковим рядком. Некоректні ID повертають 400 Bad Request.
Unknown body fields are stripped — API перевіряє тіла запитів і мовчки відкидає властивості, які не розпізнає, тому одрук у назві поля ігнорується, а не зберігається.
Dates — endpoint-и аналітики/експорту приймають date_from / date_to у форматі YYYY-MM-DD. date_to є включно до кінця цього дня.
Array query params — де фільтр приймає кілька значень (наприклад, agent_ids, direction), ви можете повторити ключ (?direction=inbound&direction=outbound) або розділити його комами (?direction=inbound,outbound).
Timestamps у відповідях є epoch у мілісекундах, якщо не показано як рядок ISO‑8601.

Індекс endpoint-ів

Швидка мапа всього доступного. Детальна документація для кожного йде нижче.

Calls

Дія	Метод	Endpoint
List calls	GET	`/v1/call/list`
Call details (transcript, sentiment, summary)	GET	`/v1/call/:id`
General analytics (totals over a range)	GET	`/v1/call/general-metrics`
Daily analytics	GET	`/v1/call/daily-metrics`
Sentiment statistics	GET	`/v1/call/sentiment-stats`
Cost breakdown	GET	`/v1/call/costs-breakdown`
Export calls (CSV)	GET	`/v1/call/list/export`
Export costs (CSV)	GET	`/v1/call/costs-breakdown/export`
Make a phone call	POST	`/v1/call/make-phone-call`
Make a web call	POST	`/v1/call/make-web-call`

Agents

Дія	Метод	Endpoint
List agents	GET	`/v1/agent/list`
Agent details	GET	`/v1/agent/:id`
Create agent	POST	`/v1/agent`
Update agent	PATCH	`/v1/agent/:id`
Delete agent	DELETE	`/v1/agent/:id`
Agent call statistics	GET	`/v1/agent/:id/call-stats`
List agent templates	GET	`/v1/agent/agent_template/list`
List actions	GET	`/v1/agent/:id/actions`
Add action	POST	`/v1/agent/:id/actions`
Update action	PATCH	`/v1/agent/:id/actions/:agentActionId`
Delete action	DELETE	`/v1/agent/:id/actions/:agentActionId`
List tools	GET	`/v1/agent/:id/tools`
Add tool	POST	`/v1/agent/:id/tools`
Update tool	PATCH	`/v1/agent/:id/tools/:agentToolId`
Delete tool	DELETE	`/v1/agent/:id/tools/:agentToolId`

Knowledge Base

Дія	Метод	Endpoint
List knowledge bases	GET	`/v1/knowledge-base/list`
Create (with first file)	POST	`/v1/knowledge-base`
Add a single file	POST	`/v1/knowledge-base/:id/file`
Add multiple files	POST	`/v1/knowledge-base/:id/files`
Delete file(s)	DELETE	`/v1/knowledge-base/:id/file`
Assign agents	PUT	`/v1/knowledge-base/:id/agents`

Phone Numbers

Дія	Метод	Endpoint
List numbers	GET	`/v1/phone-number/list`
Available numbers (by country)	GET	`/v1/phone-number/available`
Buy a number	POST	`/v1/phone-number/buy`
Import from Twilio	POST	`/v1/phone-number/import-twilio`
Connect to SIP	PATCH	`/v1/phone-number/connect-to-sip`

Voices · Subscription · Customers · Workspaces

Дія	Метод	Endpoint
List voices	GET	`/v1/voice/list`
Subscription details	GET	`/v1/subscription`
Configure auto top‑up	PATCH	`/v1/subscription/auto-top-up`
Set top‑up amount	PATCH	`/v1/subscription/top-up-amount`
List customers	GET	`/v1/customer/list`
Customer details	GET	`/v1/customer/:id`
Create customer	POST	`/v1/customer`
Update customer	PATCH	`/v1/customer/:id`
Delete customer	DELETE	`/v1/customer/:id`
List workspaces	GET	`/v1/workspaces/list`
Create workspace	POST	`/v1/workspaces`
Workspace details	GET	`/v1/workspaces/:id`
Update workspace	PATCH	`/v1/workspaces/:id`
Delete workspace	DELETE	`/v1/workspaces/:id`
Invite member	POST	`/v1/workspaces/:workspace_id/invite-member`
Remove member	DELETE	`/v1/workspaces/:workspace_id/remove-member`

Calls

Керуйте голосовими дзвінками та аналізуйте їх: переглядайте список дзвінків і вивчайте їх (транскрипт, тональність, резюме), отримуйте агреговані метрики, експортуйте CSV-звіти та здійснюйте вихідні телефонні й веб-дзвінки.

List calls

GET /v1/call/list

Перегляньте список дзвінків для вашого акаунту з фільтруванням, сортуванням і посторінковою навігацією.

Query parameters

Назва	Тип	Обовʼязково	Опис
`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 call details

GET /v1/call/:id

Отримайте повні деталі одного дзвінка — транскрипт, тональність, резюме, кредити та метрики продуктивності.

Path parameters

Назва	Тип	Обовʼязково	Опис
`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, якщо дзвінок не існує або не належить вашому акаунту.

General metrics

GET /v1/call/general-metrics

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

Query parameters

Назва	Тип	Обовʼязково	Опис
`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[]	Ні	Ті самі фільтри, що й у List calls.

Пропуск 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 }

Daily metrics

GET /v1/call/daily-metrics

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

Query parameters — такі самі, як у General metrics (date_from/date_to обов'язкові, плюс необов'язкові фільтри agent/customer/workspace/direction/status/type).

Приклад запиту

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 }
]

Sentiment statistics

GET /v1/call/sentiment-stats

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

Query parameters

Назва	Тип	Обовʼязково	Опис
`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 }

Costs breakdown

GET /v1/call/costs-breakdown

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

Query parameters

Назва	Тип	Обовʼязково	Опис
`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 }
}

Export calls (CSV)

GET /v1/call/list/export

Завантажте кожен дзвінок у діапазоні дат у вигляді CSV-файлу (з деталізацією токенів за дзвінком і за моделлю).

Query parameters

Назва	Тип	Обовʼязково	Опис
`date_from`	string	Так	Початкова дата.
`date_to`	string	Так	Кінцева дата (включно).

Response — 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

Export costs (CSV)

GET /v1/call/costs-breakdown/export

Завантажте розбивку витрат у вигляді CSV-файлу.

Query parameters — такі самі, як у Costs breakdown (date_from/date_to обов'язкові; необов'язкові group_by, customer_id, workspace_id).

Response — 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

Make a phone call

POST /v1/call/make-phone-call

Здійсніть вихідний телефонний дзвінок від одного з ваших агентів.

Request body

Поле	Тип	Обовʼязково	Опис
`agent_id`	string	Так	Агент, який здійснить дзвінок.
`from_number`	string	Так	Caller ID у форматі 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
}

Make a web call

POST /v1/call/make-web-call

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

Request body

Поле	Тип	Обовʼязково	Опис
`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).

List agents

GET /v1/agent/list

Повертає всіх агентів, що належать вашому акаунту.

Query parameters

Назва	Тип	Обовʼязково	Опис
`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 an agent

GET /v1/agent/:id

Повертає одного агента.

Path parameters

Назва	Тип	Обовʼязково	Опис
`id`	string	Так	ID агента.

Приклад запиту

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

Повертає об'єкт агента (тієї самої структури, що й один елемент з List agents), або 404, якщо не знайдено.

Create an agent

POST /v1/agent

Створіть нового агента. Обов'язковими є лише agent_name та llm_id — усе інше необов'язкове і повертається до розумних значень за замовчуванням.

Query parameters — необов'язкові customer_id, workspace_id, щоб пов'язати нового агента.

Request body

Поле	Тип	Обовʼязково	Опис
`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 (створений об'єкт агента).

Update an agent

PATCH /v1/agent/:id

Частково оновіть агента. Усі поля тіла необов'язкові — надсилайте лише те, що хочете змінити.

Path parameters — id (ID агента).

Request body — будь-яка підмножина полів створення, плюс 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 an agent

DELETE /v1/agent/:id

Видаліть агента.

Приклад запиту

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

Приклад відповіді — 204 No Content (порожнє тіло).

Agent call statistics

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

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

Path parameters — id (ID агента).

Query parameters

Назва	Тип	Обовʼязково	Опис
`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 }
]

List agent templates

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?" }
  }
]

Agent actions

Дії — це те, що агент виконує під час дзвінка. Підтримувані значення action_type: send_email, send_sms, send_whatsapp, api_call. Структура об'єкта settings залежить від типу.

List actions

GET /v1/agent/:id/actions

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

Повертає масив об'єктів дій.

Add an action

POST /v1/agent/:id/actions

Request body

Поле	Тип	Обовʼязково	Опис
`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
}

Update an action

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 an action

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.

Agent tools

Інструменти надають агенту додаткові можливості. Підтримувані значення 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. Обидва спочатку потребують підключення відповідної інтеграції на акаунті.

List tools

GET /v1/agent/:id/tools

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

Повертає масив об'єктів інструментів.

Add a tool

POST /v1/agent/:id/tools

Request body

Поле	Тип	Обовʼязково	Опис
`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
}

Update a tool

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 a tool

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.

List knowledge bases

GET /v1/knowledge-base/list

Query parameters — необов'язкові 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"]
  }
]

Create a knowledge base

POST /v1/knowledge-base

Створіть базу знань разом із її першим файлом. Це запит multipart/form-data — немає створення лише за тілом.

Query parameters — необов'язкові customer_id, workspace_id.

Form fields

Поле	Тип	Обовʼязково	Опис
`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 (створена база знань, тієї самої структури, що й елемент списку).

Add a single file

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 з оновленою базою знань.

Add multiple files

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 file(s)

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

Видаліть один або кілька файлів за ID. Попри однину в шляху, тіло приймає масив.

Request body

Поле	Тип	Обовʼязково	Опис
`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.

Assign agents

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

Задайте (замініть) повний список агентів, які використовують цю базу знань.

Request body

Поле	Тип	Обовʼязково	Опис
`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-транку.

Купівля номерів на дашборді

Купівля номерів на дашборді виходить за межі того, що надають ці endpoint-и. Миттєві номери без паперової тяганини доступні в Австрії, Німеччині, Швейцарії, США та Канаді; кожна інша країна використовує керований self-serve флоу, де ви подаєте власні регуляторні документи (і можете зберегти їх як чернетку, щоб продовжити пізніше). Екран купівлі пропонує типи local, mobile, national та toll-free — плюс advanced numbers (+€2/місяць) і номери для дзвінків WhatsApp. BYO SIP є вендор-нейтральним (sipgate, Placetel, TENIOS, easybell, Zadarma, Telnyx, власні транки — не лише імпорт із Twilio). Див. Phone Numbers для повного флоу.

List phone numbers

GET /v1/phone-number/list

Query parameters — усі необов'язкові: 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"
  }
]

Available numbers

GET /v1/phone-number/available

Перегляньте список номерів, доступних для купівлі, для країни.

Query parameters

Назва	Тип	Обовʼязково	Опис
`country_code`	string	Ні	ISO-код країни (за замовчуванням `US`), наприклад `DE`, `AT`, `CH`.
`area_code`	string	Ні	Числовий фільтр за area-code.

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" }
]

Buy a number

POST /v1/phone-number/buy

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

Request body

Поле	Тип	Обовʼязково	Опис
`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" }
}

Import from Twilio

POST /v1/phone-number/import-twilio

Імпортуйте номери з підключеного акаунту Twilio. Необов'язкові query-параметри customer_id, workspace_id.

Request body

Поле	Тип	Обовʼязково	Опис
`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 (імпортований запис телефонного номера).

Connect to SIP

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

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

Request body

Поле	Тип	Обовʼязково	Опис
`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

List voices

GET /v1/voice/list

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

Query parameters

Назва	Тип	Обовʼязково	Опис
`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

Subscription details

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, якщо запису про підписку не існує.

Configure auto top‑up

PATCH /v1/subscription/auto-top-up

Увімкніть або вимкніть автоматичне поповнення кредитів.

Request body

Поле	Тип	Обовʼязково	Опис
`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 з оновленою підпискою.

Set top‑up amount

PATCH /v1/subscription/top-up-amount

Оновіть налаштовану суму поповнення.

Request body

Поле	Тип	Обовʼязково	Опис
`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

Керуйте клієнтами у вашому агентстві. Ці endpoint-и вимагають, щоб ваш акаунт належав агентству.

List 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
  }
]

Customer details

GET /v1/customer/:id

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

Повертає об'єкт клієнта, або 404, якщо не знайдено.

Create a customer

POST /v1/customer

Request body

Поле	Тип	Обовʼязково	Опис
`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 вже існує або ваш акаунт не є частиною агентства.

Update a customer

PATCH /v1/customer/:id

Request body — усі необов'язкові: 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 a customer

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

Групуйте агентів, номери та бази знань у робочі простори та керуйте їхніми учасниками.

List 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" }
    ]
  }
]

Create a workspace

POST /v1/workspaces

Request body

Поле	Тип	Обовʼязково	Опис
`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 з робочим простором.

Workspace details

GET /v1/workspaces/:id

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

Повертає об'єкт робочого простору.

Update a workspace

PATCH /v1/workspaces/:id

Request body — 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 a workspace

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" }

Invite a member

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

Request body

Поле	Тип	Обовʼязково	Опис
`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).

Remove a member

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

Request body

Поле	Тип	Обовʼязково	Опис
`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.

Швидкий огляд​

Автентифікація​

Домовленості​

Індекс endpoint-ів​

Calls​

Agents​

Knowledge Base​

Phone Numbers​

Voices · Subscription · Customers · Workspaces​

Calls

List calls​

Get call details​

General metrics​

Daily metrics​

Sentiment statistics​

Costs breakdown​

Export calls (CSV)​

Export costs (CSV)​

Make a phone call​

Make a web call​

Agents

List agents​

Get an agent​

Create an agent​

Update an agent​

Delete an agent​

Agent call statistics​

List agent templates​

Agent actions​

List actions​

Add an action​

Update an action​

Delete an action​

Agent tools​

List tools​

Add a tool​

Update a tool​

Delete a tool​

Knowledge Base

List knowledge bases​

Create a knowledge base​

Add a single file​

Add multiple files​

Delete file(s)​

Assign agents​

Phone Numbers

List phone numbers​

Available numbers​

Buy a number​

Import from Twilio​

Connect to SIP​

Voices

List voices​

Subscription

Subscription details​

Configure auto top‑up​

Set top‑up amount​

Customers

List customers​

Customer details​

Create a customer​

Update a customer​

Delete a customer​

Workspaces

List workspaces​

Create a workspace​

Workspace details​

Update a workspace​

Delete a workspace​

Invite a member​

Remove a member​

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

Потрібна допомога?​

Швидкий огляд

Автентифікація

Домовленості

Індекс endpoint-ів

Calls

Agents

Knowledge Base

Phone Numbers

Voices · Subscription · Customers · Workspaces

List calls

Get call details

General metrics

Daily metrics

Sentiment statistics

Costs breakdown

Export calls (CSV)

Export costs (CSV)

Make a phone call

Make a web call

List agents

Get an agent

Create an agent

Update an agent

Delete an agent

Agent call statistics

List agent templates

Agent actions

List actions

Add an action

Update an action

Delete an action

Agent tools

List tools

Add a tool

Update a tool

Delete a tool

List knowledge bases

Create a knowledge base

Add a single file

Add multiple files

Delete file(s)

Assign agents

List phone numbers

Available numbers

Buy a number

Import from Twilio

Connect to SIP

List voices

Subscription details

Configure auto top‑up

Set top‑up amount

List customers

Customer details

Create a customer

Update a customer

Delete a customer

List workspaces

Create a workspace

Workspace details

Update a workspace

Delete a workspace

Invite a member

Remove a member

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

Потрібна допомога?