Ugrás a fő tartalomhoz
DocumentationAPI ReferenceVideo Tutorials

API-referencia

Teljes API-dokumentáció a Hanc.AI alkalmazásaidba való integrálásához. Kezelj ügynököket, kérj le hívásadatokat, indíts hívásokat, és üzemeltesd a platform minden részét programozottan.

Az alábbi minden szakasz megadja a HTTP-metódust és -útvonalat, a paramétereket (útvonal, lekérdezés és törzs), egy futásra kész példakérést és egy reprezentatív példaválaszt, így integrálhatsz anélkül, hogy a payload alakját találgatnod kellene.

Gyors áttekintés​

Alap-URLhttps://api.hanc.ai
Verzió-előtagMinden útvonal /v1 előtaggal rendelkezik
HitelesítésAPI-kulcs az x-api-key fejlécen keresztül
FormátumJSON (kérés és válasz)

Generálj egy API-kulcsot az irányítópulton az Integration → API Keys menüpontból. Felhasználónként legfeljebb 3 kulcsod lehet — a beállításhoz, jogosultságokhoz és biztonsági útmutatáshoz lásd az API-kulcsok szakaszt az Integrációkban.

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

Hitelesítés​

Küldd el a kulcsodat az x-api-key fejlécben minden kérésen:

x-api-key: YOUR_API_KEY

A kulcs feloldódik az őt birtokló felhasználóra, és minden kérés automatikusan az adott felhasználóra van korlátozva — soha nem adsz át felhasználói azonosítót. A hiányzó vagy érvénytelen kulcsot 401 Unauthorized / 403 Forbidden hibával utasítja el a rendszer.

tanács

Tartsd a kulcsokat a szerveroldalon. Soha ne ágyazz be API-kulcsot böngészőbe, mobilalkalmazásba vagy bármilyen kliensbe, amelyet a végfelhasználó megvizsgálhat. Ha egy kulcs kiszivárog, vond vissza az Integration → API Keys menüpontban, és adj ki egy újat.

Konvenciók​

Néhány szabály érvényes az egész API-ra. Ezek egyszeri elolvasása hibakeresési időt takarít meg neked:

  • Verzió-előtag — minden útvonal /v1-gyel kezdődik (pl. https://api.hanc.ai/v1/agent/list).
  • Az azonosítók Mongo ObjectId-k — bármely :id (és :agentActionId, :agentToolId stb.) egy 24 karakteres hexadecimális karakterlánc kell hogy legyen. A hibás azonosítók 400 Bad Request hibát adnak.
  • Az ismeretlen törzsmezőket eltávolítja a rendszer — az API validálja a kérés törzsét, és csendben eldobja azokat a tulajdonságokat, amelyeket nem ismer fel, így egy elgépelt mezőnév figyelmen kívül marad, nem pedig tárolódik.
  • Dátumok — az analitikai/exportáló végpontok a date_from / date_to értéket YYYY-MM-DD formátumban veszik. A date_to beleértve az adott nap végéig.
  • Tömb-lekérdezésparaméterek — ahol egy szűrő több értéket fogad el (pl. agent_ids, direction), megismételheted a kulcsot (?direction=inbound&direction=outbound), vagy vesszővel elválaszthatod (?direction=inbound,outbound).
  • Az időbélyegek a válaszokban epoch-ezredmásodpercek, kivéve ha ISO‑8601 karakterláncként jelennek meg.

Végpontok jegyzéke​

Egy gyors térkép mindenről, ami elérhető. Az egyes végpontok részletes dokumentációja lentebb következik.

Hívások​

MűveletMetódusVégpont
Hívások listázásaGET/v1/call/list
Hívás részletei (átirat, hangulat, összefoglaló)GET/v1/call/:id
Általános analitika (összegek egy tartományra)GET/v1/call/general-metrics
Napi analitikaGET/v1/call/daily-metrics
Hangulati statisztikákGET/v1/call/sentiment-stats
KöltségbontásGET/v1/call/costs-breakdown
Hívások exportálása (CSV)GET/v1/call/list/export
Költségek exportálása (CSV)GET/v1/call/costs-breakdown/export
Telefonhívás indításaPOST/v1/call/make-phone-call
Webes hívás indításaPOST/v1/call/make-web-call

Ügynökök​

MűveletMetódusVégpont
Ügynökök listázásaGET/v1/agent/list
Ügynök részleteiGET/v1/agent/:id
Ügynök létrehozásaPOST/v1/agent
Ügynök frissítésePATCH/v1/agent/:id
Ügynök törléseDELETE/v1/agent/:id
Ügynök hívásstatisztikáiGET/v1/agent/:id/call-stats
Ügynöksablonok listázásaGET/v1/agent/agent_template/list
Műveletek listázásaGET/v1/agent/:id/actions
Művelet hozzáadásaPOST/v1/agent/:id/actions
Művelet frissítésePATCH/v1/agent/:id/actions/:agentActionId
Művelet törléseDELETE/v1/agent/:id/actions/:agentActionId
Eszközök listázásaGET/v1/agent/:id/tools
Eszköz hozzáadásaPOST/v1/agent/:id/tools
Eszköz frissítésePATCH/v1/agent/:id/tools/:agentToolId
Eszköz törléseDELETE/v1/agent/:id/tools/:agentToolId

Tudásbázis​

MűveletMetódusVégpont
Tudásbázisok listázásaGET/v1/knowledge-base/list
Létrehozás (első fájllal)POST/v1/knowledge-base
Egyetlen fájl hozzáadásaPOST/v1/knowledge-base/:id/file
Több fájl hozzáadásaPOST/v1/knowledge-base/:id/files
Fájl(ok) törléseDELETE/v1/knowledge-base/:id/file
Ügynökök hozzárendelésePUT/v1/knowledge-base/:id/agents

Telefonszámok​

MűveletMetódusVégpont
Számok listázásaGET/v1/phone-number/list
Elérhető számok (ország szerint)GET/v1/phone-number/available
Szám vásárlásaPOST/v1/phone-number/buy
Importálás TwilióbólPOST/v1/phone-number/import-twilio
Csatlakoztatás SIP-hezPATCH/v1/phone-number/connect-to-sip

Hangok · Előfizetés · Ügyfelek · Munkaterületek​

MűveletMetódusVégpont
Hangok listázásaGET/v1/voice/list
Előfizetés részleteiGET/v1/subscription
Automatikus feltöltés konfigurálásaPATCH/v1/subscription/auto-top-up
Feltöltési összeg beállításaPATCH/v1/subscription/top-up-amount
Ügyfelek listázásaGET/v1/customer/list
Ügyfél részleteiGET/v1/customer/:id
Ügyfél létrehozásaPOST/v1/customer
Ügyfél frissítésePATCH/v1/customer/:id
Ügyfél törléseDELETE/v1/customer/:id
Munkaterületek listázásaGET/v1/workspaces/list
Munkaterület létrehozásaPOST/v1/workspaces
Munkaterület részleteiGET/v1/workspaces/:id
Munkaterület frissítésePATCH/v1/workspaces/:id
Munkaterület törléseDELETE/v1/workspaces/:id
Tag meghívásaPOST/v1/workspaces/:workspace_id/invite-member
Tag eltávolításaDELETE/v1/workspaces/:workspace_id/remove-member

Hívások

Kezeld és elemezd a hanghívásokat: listázd és vizsgáld meg a hívásokat (átirat, hangulat, összefoglaló), kérj le összesített mutatókat, exportálj CSV-jelentéseket, és indíts kimenő telefon- és webes hívásokat.

Hívások listázása​

GET /v1/call/list

Listázd a fiókod hívásait szűréssel, rendezéssel és lapozással.

Lekérdezésparaméterek

NévTípusKötelezőLeírás
agent_idsstring[]NemSzűrés egy vagy több ügynökazonosítóra (ismételd vagy vesszővel válaszd el).
agent_idstringNemSzűrés egyetlen ügynökre (örökölt; részesítsd előnyben az agent_ids-t).
directionenum[]Neminbound és/vagy outbound.
call_statusenum[]Nemstarted, success, failed, pending.
call_typeenum[]Nemphone, web.
customer_idstringNemSzűrés ügyfél szerint.
workspace_idstringNemSzűrés munkaterület szerint.
date_from / date_tostringNemTartományszűrő (YYYY-MM-DD).
sort_orderenumNemasc vagy desc.
limitnumberNemA visszaadott eredmények maximális száma.
skipnumberNemAz átugrandó eredmények száma (lapozási eltolás).

Példakérés

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"

Példaválasz — 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
  }
]

Hívás részleteinek lekérése​

GET /v1/call/:id

Kérd le egy hívás teljes részleteit — átirat, hangulat, összefoglaló, kreditek és teljesítménymutatók.

Útvonalparaméterek

NévTípusKötelezőLeírás
idstringIgenA hívás azonosítója.

Példakérés

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

Példaválasz — 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-et ad vissza, ha a hívás nem létezik, vagy nem a fiókod tulajdonában van.

Általános mutatók​

GET /v1/call/general-metrics

Összesített összegek (hívásszám, teljes és átlagos időtartam) egy dátumtartományra.

Lekérdezésparaméterek

NévTípusKötelezőLeírás
date_fromstringIgenKezdődátum (YYYY-MM-DD).
date_tostringIgenZárónap (YYYY-MM-DD, beleértve).
agent_id / agent_idsstring(s)NemKorlátozás egy vagy több ügynökre.
customer_idstringNemSzűrés ügyfél szerint.
workspace_idstringNemSzűrés munkaterület szerint.
direction / call_status / call_typeenum[]NemUgyanazok a szűrők, mint a Hívások listázása esetén.

A date_from vagy a date_to elhagyása 400 Bad Request hibát ad vissza.

Példakérés

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"

Példaválasz — 200 OK

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

Napi mutatók​

GET /v1/call/daily-metrics

Naponkénti teljes hívásidőtartam egy dátumtartományon — ideális a trendek diagramozásához.

Lekérdezésparaméterek — ugyanaz, mint az Általános mutatók (date_from/date_to kötelező, valamint az opcionális ügynök/ügyfél/munkaterület/irány/állapot/típus szűrők).

Példakérés

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"

Példaválasz — 200 OK

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

Hangulati statisztikák​

GET /v1/call/sentiment-stats

Hívások száma hangulat szerint egy ügynökre egy dátumtartományon.

Lekérdezésparaméterek

NévTípusKötelezőLeírás
agent_idstringIgenAz ügynök, amelyről a jelentés készül.
date_fromstringIgenKezdődátum.
date_tostringIgenZárónap (beleértve).

Példakérés

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"

Példaválasz — 200 OK

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

Költségbontás​

GET /v1/call/costs-breakdown

Költség-/használatbontás (hívások, percek, kreditek, tokenek, modellenkénti részlet) felhasználó, ügynök vagy munkaterület szerint csoportosítva.

Lekérdezésparaméterek

NévTípusKötelezőLeírás
date_fromstringIgenKezdődátum.
date_tostringIgenZárónap (beleértve).
group_byenumNemuser (alapértelmezett), agent vagy workspace.
customer_idstringNemSzűrés ügyfél szerint (ügynökségi hozzáférés).
workspace_idstringNemSzűrés munkaterület szerint.

Példakérés

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"

Példaválasz — 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 }
}

Hívások exportálása (CSV)​

GET /v1/call/list/export

Töltsd le egy dátumtartomány összes hívását CSV-fájlként (hívásonkénti, modellenkénti tokenrészlettel).

Lekérdezésparaméterek

NévTípusKötelezőLeírás
date_fromstringIgenKezdődátum.
date_tostringIgenZárónap (beleértve).

Válasz — egy CSV-fájl (Content-Type: text/csv), mellékletként kiszolgálva call-details_<date_from>_<date_to>.csv néven.

Példakérés

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

Költségek exportálása (CSV)​

GET /v1/call/costs-breakdown/export

Töltsd le a költségbontást CSV-fájlként.

Lekérdezésparaméterek — ugyanaz, mint a Költségbontás (date_from/date_to kötelező; opcionális group_by, customer_id, workspace_id).

Válasz — egy CSV-fájl costs-breakdown_<date_from>_<date_to>.csv néven kiszolgálva.

Példakérés

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

Telefonhívás indítása​

POST /v1/call/make-phone-call

Indíts egy kimenő telefonhívást az egyik ügynököddel.

Kéréstörzs

MezőTípusKötelezőLeírás
agent_idstringIgenAz ügynök, amely a hívást indítja.
from_numberstringIgenHívóazonosító E.164 formátumban (pl. +1234567890).
to_numberstringIgenA címzett telefonszáma.
custom_dataobjectNemA híváshoz csatolt tetszőleges adat.
dynamic_contextobjectNemA beszélgetésbe átadott kontextus (pl. ügyfélnév).

Példakérés

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

Példaválasz — 201 Created

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

Webes hívás indítása​

POST /v1/call/make-web-call

Hozz létre egy böngészős/WebRTC hívási munkamenetet az egyik ügynököd számára.

Kéréstörzs

MezőTípusKötelezőLeírás
agent_idstringIgenAz ügynök, amely a webes hívást kezeli.
custom_dataobjectNemA híváshoz csatolt tetszőleges adat.
dynamic_contextobjectNemA beszélgetésbe átadott kontextus.

Példakérés

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

Példaválasz — 201 Created

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

Ügynökök

Hozz létre és kezelj hangügynököket, azok műveleteit (amit hívás közben végeznek — e-mail/SMS/WhatsApp küldése, az API-d hívása) és eszközeit (képességek, mint a RAG-keresés, időpontfoglalás, hívástovábbítás, naptár-/CRM-integrációk).

Ügynökök listázása​

GET /v1/agent/list

Adja vissza a fiókod tulajdonában lévő összes ügynököt.

Lekérdezésparaméterek

NévTípusKötelezőLeírás
customer_idstringNemKorlátozás egy ügyfélre.
workspace_idstringNemKorlátozás egy munkaterületre.

Példakérés

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

Példaválasz — 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"]
  }
]

Ügynök lekérése​

GET /v1/agent/:id

Adjon vissza egyetlen ügynököt.

Útvonalparaméterek

NévTípusKötelezőLeírás
idstringIgenÜgynökazonosító.

Példakérés

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

Visszaadja az ügynökobjektumot (ugyanolyan alakú, mint a Ügynökök listázása egy eleme), vagy 404-et, ha nem található.

Ügynök létrehozása​

POST /v1/agent

Hozz létre egy új ügynököt. Csak az agent_name és az llm_id kötelező — minden más opcionális, és értelmes alapértékekre esik vissza.

Lekérdezésparaméterek — opcionális customer_id, workspace_id az új ügynök társításához.

Kéréstörzs

MezőTípusKötelezőLeírás
agent_namestringIgenMegjelenítendő név.
llm_idstringIgenAz ügynököt hajtó LLM azonosítója.
voiceobjectNem{ "voice_id": "<id>" }.
interruption_sensitivitynumberNemMilyen könnyen enged az ügynök, ha félbeszakítják (pl. 0.5).
call_settingsobjectNemNyelv, emlékeztetők, csendidőtúllépés, hangulatelemzés, hívásösszefoglaló, max_call_duration_minutes (1–15).
data_retrievalobject[]NemMezők, amelyeket az ügynök egy hívás során gyűjt.
webhook_urlstringNemAz ügynökeseményekről értesített URL.
is_data_collection_activebooleanNemAz adatgyűjtő űrlap engedélyezése.

Példakérés

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

Példaválasz — 201 Created (a létrehozott ügynökobjektum).

Ügynök frissítése​

PATCH /v1/agent/:id

Egy ügynök részleges frissítése. Minden törzsmező opcionális — csak azt küldd, amit módosítani szeretnél.

Útvonalparaméterek — id (ügynökazonosító).

Kéréstörzs — a létrehozási mezők bármely részhalmaza, valamint folder, status (pl. active), is_customer_memory_active, widget_settings, callback_settings. A call_settings-en belül beállíthatod a recording_enabled, stt_languages (legfeljebb 4 BCP‑47 kód) és max_call_duration_minutes értéket is.

Példakérés

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

Példaválasz — 200 OK (a frissített ügynökobjektum).

Ügynök törlése​

DELETE /v1/agent/:id

Töröld az ügynököt.

Példakérés

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

Példaválasz — 204 No Content (üres törzs).

Ügynök hívásstatisztikái​

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

Naponkénti hívásszámok egy ügynökre egy dátumtartományon.

Útvonalparaméterek — id (ügynökazonosító).

Lekérdezésparaméterek

NévTípusKötelezőLeírás
date_fromstringIgenKezdődátum (YYYY-MM-DD).
date_tostringIgenZárónap (YYYY-MM-DD).

Példakérés

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"

Példaválasz — 200 OK

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

Ügynöksablonok listázása​

GET /v1/agent/agent_template/list

Adja vissza a klónozható, előre elkészített ügynöksablonok katalógusát. Nincsenek paraméterek.

Példakérés

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

Példaválasz — 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?" }
  }
]

Ügynökműveletek​

A műveletek olyan dolgok, amelyeket egy ügynök egy hívás során végez. Támogatott action_type értékek: send_email, send_sms, send_whatsapp, api_call. A settings objektum alakja a típustól függ.

Műveletek listázása​

GET /v1/agent/:id/actions

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

Visszaad egy műveletobjektumokból álló tömböt.

Művelet hozzáadása​

POST /v1/agent/:id/actions

Kéréstörzs

MezőTípusKötelezőLeírás
action_typeenumIgensend_email, send_sms, send_whatsapp vagy api_call.
settingsobjectIgenTípusspecifikus konfiguráció.
is_activebooleanNemAlapértéke true.

Példakérés

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

Példaválasz — 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
}

Művelet frissítése​

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

Frissítsd egy csatolt művelet settings és/vagy is_active értékét. Mindkét törzsmező opcionális.

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-t ad vissza a frissített műveletobjektummal.

Művelet törlése​

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-et ad vissza.

Ügynökeszközök​

Az eszközök extra képességeket adnak egy ügynöknek. Támogatott tool_type értékek: api_rag, appointment_booking, call_forwarding, end_call, google_calendar, outlook_calendar, etermin, resmio, hubspot_crm, agent_transfer, mcp. A settings objektum alakja a típustól függ.

Az etermin és a resmio élő időpont-/asztalfoglaló eszközök: az ügynök ellenőrzi az elérhetőséget, és közvetlenül a csatlakoztatott eTermin vagy resmio fiókban foglal, ütemez át vagy mond le. Mindkettőhöz először csatlakoztatni kell a megfelelő integrációt a fiókon.

Eszközök listázása​

GET /v1/agent/:id/tools

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

Visszaad egy eszközobjektumokból álló tömböt.

Eszköz hozzáadása​

POST /v1/agent/:id/tools

Kéréstörzs

MezőTípusKötelezőLeírás
tool_typeenumIgenA fenti támogatott eszköztípusok egyike.
settingsobjectIgenTípusspecifikus konfiguráció.
is_activebooleanNemAlapértéke true.

Példakérés

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

Példaválasz — 201 Created

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

Eszköz frissítése​

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

Frissítsd egy csatolt eszköz settings és/vagy is_active értékét (mindkettő opcionális).

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-t ad vissza a frissített eszközobjektummal.

Eszköz törlése​

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-et ad vissza.

Tudásbázis

Tölts fel dokumentumokat, amelyeket az ügynökeid hívás közben kereshetnek, és szabályozd, mely ügynökök használják az egyes tudásbázisokat. A fájlfeltöltések multipart/form-data formátumot használnak.

Tudásbázisok listázása​

GET /v1/knowledge-base/list

Lekérdezésparaméterek — opcionális customer_id, workspace_id.

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

Példaválasz — 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"]
  }
]

Tudásbázis létrehozása​

POST /v1/knowledge-base

Hozz létre egy tudásbázist az első fájljával együtt. Ez egy multipart/form-data kérés — nincs csak törzsből álló „létrehozás".

Lekérdezésparaméterek — opcionális customer_id, workspace_id.

Űrlapmezők

MezőTípusKötelezőLeírás
filefileIgenAz első dokumentum (pl. egy PDF).
namestringIgenTudásbázis neve (1–100 karakter).
descriptionstringIgenLeírás (1–300 karakter).
folderstringNemMappa-/kategóriacímke (0–50 karakter).

Példakérés

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"

Példaválasz — 200 OK (a létrehozott tudásbázis, ugyanolyan alakú, mint egy listaelem).

Egyetlen fájl hozzáadása​

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

Adj hozzá egy fájlt egy meglévő tudásbázishoz. Multipart mezőnév: 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-t ad vissza a frissített tudásbázissal.

Több fájl hozzáadása​

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

Adj hozzá több fájlt egyszerre. Multipart mezőnév: files (ismételd meg minden fájlhoz). Opcionális customer_id, workspace_id lekérdezésparaméterek.

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-t ad vissza a frissített tudásbázissal.

Fájl(ok) törlése​

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

Távolíts el egy vagy több fájlt azonosító szerint. Az egyes számú útvonal ellenére a törzs egy tömböt vesz.

Kéréstörzs

MezőTípusKötelezőLeírás
file_idsstring[]IgenA törlendő fájlazonosítók nem üres tömbje.
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-t ad vissza.

Ügynökök hozzárendelése​

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

Állítsd be (cseréld le) az ezt a tudásbázist használó ügynökök teljes listáját.

Kéréstörzs

MezőTípusKötelezőLeírás
agent_idsstring[]IgenAz ügynökazonosítók, amelyeknek ezt a tudásbázist kell használniuk.
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-t ad vissza.

Telefonszámok

Listázd a számaidat, keress megvásárolható számokat, vásárolj egyet, importálj számokat egy csatlakoztatott Twilio-fiókból, vagy csatlakoztass egy számot egy SIP-trönkhöz.

Számok vásárlása az irányítópulton

A számvásárlás az irányítópulton túlmutat azon, amit ezek a végpontok tesznek elérhetővé. Azonnali, papírmunka nélküli számok érhetők el Ausztriában, Németországban, Svájcban, az USA-ban és Kanadában; minden más ország egy vezetett önkiszolgáló folyamatot használ, ahol te nyújtod be a saját szabályozási dokumentumaidat (és vázlatként mentheted őket a későbbi folytatáshoz). A vásárlási képernyő helyi, mobil, nemzeti és díjmentes típusokat kínál — plusz speciális számokat (+€2/hó) és WhatsApp-hívószámokat. A BYO SIP gyártófüggetlen (sipgate, Placetel, TENIOS, easybell, Zadarma, Telnyx, egyéni trönkök — nem csak Twilio-import). A teljes folyamathoz lásd Telefonszámok.

Telefonszámok listázása​

GET /v1/phone-number/list

Lekérdezésparaméterek — mind opcionális: inbound_agent_id, outbound_agent_id, customer_id, workspace_id (és user_id, alapértelmezetten te).

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

Példaválasz — 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"
  }
]

Elérhető számok​

GET /v1/phone-number/available

Listázd egy országban megvásárolható számokat.

Lekérdezésparaméterek

NévTípusKötelezőLeírás
country_codestringNemISO-országkód (alapértelmezett US), pl. DE, AT, CH.
area_codestringNemNumerikus körzetszám-szűrő.
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"

Példaválasz — 200 OK

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

Szám vásárlása​

POST /v1/phone-number/buy

Vásárolj meg egy adott számot. Opcionális customer_id, workspace_id lekérdezésparaméterek.

Kéréstörzs

MezőTípusKötelezőLeírás
phone_numberstringIgenA megvásárolandó szám (E.164).
country_codestringIgenA szám országa (pl. 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" }'

Példaválasz — 200 OK

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

Importálás Twilióból​

POST /v1/phone-number/import-twilio

Importálj számokat egy csatlakoztatott Twilio-fiókból. Opcionális customer_id, workspace_id lekérdezésparaméterek.

Kéréstörzs

MezőTípusKötelezőLeírás
sidstringIgenTwilio 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" }'

Példaválasz — 200 OK (az importált telefonszám-rekord).

Csatlakoztatás SIP-hez​

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

Csatlakoztass egy meglévő számot egy SIP-trönkhöz.

Kéréstörzs

MezőTípusKötelezőLeírás
phone_numberstringIgenA csatlakoztatandó szám (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-t ad vissza (üres törzs).

Hangok

Hangok listázása​

GET /v1/voice/list

Listázd az elérhető hangokat. Szűrj nyelv vagy szolgáltató szerint, és vedd bele egy ügyfél privát klónjait.

Lekérdezésparaméterek

NévTípusKötelezőLeírás
languagestringNemSzűrés nyelv szerint, pl. ?language=de.
providerstringNem11-Labs, openai, qwen vagy azure.
customer_idstringNemVedd bele ennek az ügyfélnek a privát hangklónjait is.
curl -G "https://api.hanc.ai/v1/voice/list" \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode "language=de"

Példaválasz — 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"
  }
]

Előfizetés

Előfizetés részletei​

GET /v1/subscription

Adja vissza az aktuális előfizetésedet, beleértve a kreditegyenlegeket és a feltöltési beállításokat.

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

Példaválasz — 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-et ad vissza, ha nincs előfizetési rekord.

Automatikus feltöltés konfigurálása​

PATCH /v1/subscription/auto-top-up

Engedélyezd vagy tiltsd le az automatikus kreditfeltöltést.

Kéréstörzs

MezőTípusKötelezőLeírás
enabledbooleanIgenAz automatikus feltöltés be- vagy kikapcsolása.
amountnumberNemA feltöltés összege (20–1000). Engedélyezéskor állítsd be.
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-t ad vissza a frissített előfizetéssel.

Feltöltési összeg beállítása​

PATCH /v1/subscription/top-up-amount

Frissítsd a beállított feltöltési összeget.

Kéréstörzs

MezőTípusKötelezőLeírás
top_up_amountnumberIgenÚj összeg (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-t ad vissza a frissített előfizetéssel.

Ügyfelek

Kezeld az ügynökséged alá tartozó ügyfeleket. Ezek a végpontok megkövetelik, hogy a fiókod egy ügynökséghez tartozzon.

Ügyfelek listázása​

GET /v1/customer/list

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

Példaválasz — 200 OK

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

Ügyfél részletei​

GET /v1/customer/:id

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

Visszaadja az ügyfélobjektumot, vagy 404-et, ha nem található.

Ügyfél létrehozása​

POST /v1/customer

Kéréstörzs

MezőTípusKötelezőLeírás
emailstringIgenÜgyfél bejelentkezési e-mail-címe.
initial_passwordstringIgenKezdeti jelszó (8–128 karakter).
namestringIgenFiók-/cégnév.
user_full_namestringIgenAz ügyfél-felhasználó teljes neve.
visibilityobjectNemSzakaszonkénti láthatósági jelzők.
opt_out_promotionsbooleanNemAz ügyfél leiratkoztatása a promóciós üzenetekről.
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-et ad vissza az új ügyféllel. 400-at ad vissza, ha az e-mail már létezik, vagy a fiókod nem része egy ügynökségnek.

Ügyfél frissítése​

PATCH /v1/customer/:id

Kéréstörzs — mind opcionális: 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-t ad vissza a frissített ügyféllel.

Ügyfél törlése​

DELETE /v1/customer/:id

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

Példaválasz

{ "message": "Customer deleted successfully" }

Munkaterületek

Csoportosítsd az ügynököket, számokat és tudásbázisokat munkaterületekbe, és kezeld a tagjaikat.

Munkaterületek listázása​

GET /v1/workspaces/list

Opcionális customer_id lekérdezésparaméter.

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

Példaválasz — 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" }
    ]
  }
]

Munkaterület létrehozása​

POST /v1/workspaces

Kéréstörzs

MezőTípusKötelezőLeírás
namestringIgenMunkaterület neve (2–100 karakter).
descriptionstringNemLeírás (0–500 karakter).
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-et ad vissza a munkaterülettel.

Munkaterület részletei​

GET /v1/workspaces/:id

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

Visszaadja a munkaterület-objektumot.

Munkaterület frissítése​

PATCH /v1/workspaces/:id

Kéréstörzs — name (2–100) és/vagy 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-t ad vissza a frissített munkaterülettel.

Munkaterület törlése​

DELETE /v1/workspaces/:id

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

Példaválasz

{ "message": "Workspace deleted successfully" }

Tag meghívása​

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

Kéréstörzs

MezőTípusKötelezőLeírás
emailstringIgenA meghívandó felhasználó e-mail-címe.
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-et ad vissza a munkaterülettel (az új tag megjelenik a members alatt).

Tag eltávolítása​

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

Kéréstörzs

MezőTípusKötelezőLeírás
emailstringIgenAz eltávolítandó tag e-mail-címe.
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-t ad vissza a frissített munkaterülettel.

Ami nem érhető el az API-n keresztül​

Egyes műveletek csak az irányítópulton keresztül érhetők el:

FunkcióOk
API-kulcsok kezeléseBiztonság — a kulcsok nem hozhatnak létre más kulcsokat
Telefonszám beállításaInteraktív beállítást igényel
Google Naptár integrációInteraktív engedélyezést igényel
Számlázás és fizetésekAz irányítópulton keresztül kezelve

Segítségre van szükséged?​

Az API-val kapcsolatos kérdésekkel fordulj támogatói csapatunkhoz a support@hanc.ai címen.