Ugrás a fő tartalomhoz

Webhookok és kézbesítés

Minden hívás után az összefoglaló, az átirat és a kinyert mezőid a saját rendszeredbe kerülnek — újrapróbálkozással, ha nem elérhető, kézbesítési naplóval és e-maillel, ha valami nem sikerül.

Minden csomag, a próbaidőszakkal együttSaját végpont

A Hanc.AI minden hívás után el tudja küldeni a hívást – összefoglaló, átirat, kinyert mezők – az Ön saját rendszerébe: jegykezelő rendszerbe, CRM-be, ERP-be vagy bármely HTTPS-végpontra. Ez az oldal azt írja le, pontosan hogyan viselkedik ez a kézbesítés: mi történik, ha a szervere nem érhető el, milyen gyakran próbálkozunk újra, mit kell átengednie a tűzfalának, és hogyan néz ki a kérés.

Minden csomag

A hívás utáni kézbesítés az újrapróbálkozásokkal és a kézbesítési naplóval együtt minden csomagban elérhető, az ingyenes próbaidőszakot is beleértve.

Mit tehetsz​

  • Minden hívás elküldése a rendszeredbe — jegykezelő rendszerbe, CRM-be, ERP-be vagy bármilyen HTTPS-végpontra, amint a hívás és az elemzése befejeződött.
  • A kérés alakítása — saját JSON-törzs, fejlécek és lekérdezési paraméterek, a hívás változóival kitöltve.
  • Csak bizonyos hívások küldése — egy köznyelvi feltétel dönti el, mely hívások indítják a kérést.
  • Egy hívás se vesszen el — a sikertelen kézbesítéseket nagyjából 3,4 napig újrapróbálja, naplózza, és újra elküldhetők.
  • Értesülés a hibákról — e-mail, ha egy kérés nem kézbesíthető.

Beállítás​

  1. Adj hozzá egy hívás utáni API-hívást

    Nyisd meg az ügynököt → Műveletek → Eszköz hozzáadása → A hívás után → API-hívás. Workflow-ban ehelyett egy Eszköz csomópontot használj API-hívás típussal és Mikor fut: A hívás után beállítással.

  2. Írd le a kérést

    Adj neki nevet, opcionális feltételt, a végpontod URL-jét és a HTTP-metódust. Add hozzá azokat a fejléceket, amelyekből a végpontod felismer minket (lásd Hitelesítés), és ha a rendszered saját struktúrát vár, a Törzs (JSON) mezőt változókkal (lásd A kérés alakítása).

    Az API-hívás művelet létrehozása ablak: név, feltétel, API-végpont URL, HTTP-metódus, fejlécek, lekérdezési paraméterek, törzs és Csak a saját mezőim küldése
  3. Állítsd be az újrapróbálkozást és a hibaértesítő e-mailt

    Tartsd meg az alapértelmezett ütemezést, vagy állíts be sajátot az Újrapróbálkozások hiba esetén alatt, és az Értesítés hiba esetén alatt válaszd ki, ki kapjon e-mailt.

    Újrapróbálkozások hiba esetén az alapértelmezett ütemezéssel, Értesítés hiba esetén és Címzett, valamint az API konfiguráció tesztelése gomb
  4. Teszteld

    Nyomd meg az API konfiguráció tesztelése gombot, majd indíts egy teszthívást. Lásd Tesztelés.

Példaforgatókönyvek​

Jegy minden hibabejelentéshez A hívó elromlott routert jelent → az ügynök kitölti az ügyfélszám, jegykategória és prioritás mezőidet → a hívás után a jegykezelő rendszered a saját struktúrájában kap egy jegyet, bekapcsolt Csak a saját mezőim küldése beállítással.

Csak a fontos hívások Teljesül a „csak ha a hívó hibát jelent” feltétel → a kérés a támogatási rendszeredbe megy; a többi hívás sehova nem megy, vagy egy második, a CRM-edre mutató művelethez.

A szervered hétvégén nem működött Az első próbálkozások sikertelenek → a kérést az ütemezés szerint újrapróbálja → amikor a szervered helyreáll, a hívás magától megérkezik; ha az ütemezés kifut, e-mailt kapsz, és a kézbesítési naplóból újra elküldheted.

Mit küldünk, és mikor​

A kérés akkor indul el, amikor a hívás véget ért, és az elemzése elkészült (összefoglaló, hangulat, a kinyert mezői) – jellemzően néhány másodperccel a vonal bontása után.

ForrásHol állítható be
API hívás műveletÜgynök → Műveletek → Post call → API hívás
Munkafolyamat-lépésMunkafolyamat-szerkesztő → Eszköz csomópont (Eszköz beállítása ablak) → API-hívás Mikor fut: A hívás után beállítással. Lásd Munkafolyamatok → Eszköz
Ügynök-webhookAz ügynök webhook_url mezője (API-referencia)

Azok a kérések, amelyeket az ügynök a beszélgetés közben indít (élő eszközök), nem tartoznak ide: ezekre abban a pillanatban van szükség, és később soha nem ismétlődnek meg.

Ha a szervere nem érhető el​

Semmi sem vész el. A kérés már az első próbálkozás előtt bekerül egy kézbesítési sorba, és ott marad, amíg a szervere el nem fogadja, vagy az ütemezés le nem jár.

  • A kézbesítés akkor számít sikeresnek, ha a végpontja 30 másodpercen belül bármilyen 2xx státusszal válaszol.
  • Minden más esetben újrapróbálkozunk: elutasított kapcsolat, DNS- vagy TLS-hiba, időtúllépés és bármely más státusz esetén – 5xx, 429, sőt 4xx esetén is. Ha lejárt egy API-kulcs, és megújítja, a függőben lévő hívások maguktól megérkeznek.
  • Minden próbálkozás ugyanazt a kérést küldi, ugyanazzal a kézbesítési azonosítóval.

Az újrapróbálkozások ütemezése​

PróbálkozásSzünet előtteA hívás vége óta eltelt idő
1– (azonnal)~0
21 perc~1 perc
35 perc~6 perc
430 perc~36 perc
52 óra~2 óra 36 perc
66 óra~8 óra 36 perc
724 óra~1 nap 8 óra
848 óra~3 nap 8 óra

Ez 8 próbálkozás körülbelül 3,4 nap alatt – elegendő egy hétvégi kiesés áthidalásához.

Saját ütemezés​

Az API hívás műveletben (és a munkafolyamat hívás után futó, API-hívás típusú Eszköz lépésében) az Újrapróbálkozások hiba esetén alatt lecserélheti az ütemezést:

  • legfeljebb 10 újrapróbálkozás,
  • minden szünet 1 perc és 7 nap közötti,
  • ha minden sort eltávolít, a kérés egyszer megy ki, újrapróbálkozás nélkül.

Az a művelet, amelyhez soha nem nyúlt, a fenti alapértelmezett ütemezést követi.

Az utolsó próbálkozás után​

A kézbesítés Nincs kézbesítve jelölést kap, Önt e-mailben értesítjük – hacsak ezt ki nem kapcsolta –, a kérést pedig 30 napig megőrizzük. Ez idő alatt újraküldheti – egyetlen kattintással a kézbesítési naplóban vagy egyetlen API-hívással. Az újraküldés már sikeres kézbesítésnél is lehetséges, például az Ön oldalán végzett visszaállítás után.

Minden webhooktól függetlenül maga a hívás megmarad a Hanc.AI-fiókjában – az átirat, az összefoglaló, a felvétel és a kinyert mezők a Hívások alatt és az API-n keresztül is elérhetők. Egy hosszabb kiesés késlelteti az átadást a rendszerének; a beszélgetést nem törli.

Legalább egyszer

A kézbesítés legalább egyszer megtörténik. Ritka esetben – például ha a szervere feldolgozott egy kérést, de a válasz nem ért el hozzánk időben – ugyanaz a hívás kétszer érkezik meg. Az X-Hanc-Delivery-Id alapján felismerheti és kihagyhatja az ismétlést.

Értesítések hiba esetén​

Nem kell figyelnie a naplót: egy művelet e-mailben jelezheti, ha a kérését nem sikerült kézbesíteni. A műveletben (vagy a munkafolyamat-lépésben) az Értesítés hiba esetén alatt választhat:

BeállításMikor megy ki az e-mail
Az utolsó próbálkozás után (alapértelmezett)Egyszer, amikor az újrapróbálkozások ütemezése kimerült, és a kérés Nincs kézbesítve jelölést kap
Minden sikertelen próbálkozás utánMinden sikertelen próbálkozás után, a következő időpontjával – és az utolsó után is
Ne értesítsenSoha; a hibák csak a naplóban láthatók

Az e-mail megnevezi a műveletet és az ügynököt, a szervere gazdagépnevét, azt, hogy a szerver mit válaszolt (például HTTP 503 vagy timeout after 30s), és hogy ez az összesből hányadik próbálkozás volt, továbbá hivatkozást ad a kézbesítési naplóra. Az utolsó e-mail azt is közli, meddig őrizzük meg a kérést, és hogy újra elküldhető.

A Címzett mező adja meg, ki kapja az e-mailt – jellemzően az, aki a fogadó rendszert üzemelteti. Ha üresen marad, az e-mail a fiók tulajdonosának megy. Az e-mail a fiók nyelvén készül.

Hogy egy kiesés ne árassza el a postafiókját, az értesítések száma műveletenként óránként 10-re és naponta 30-ra van korlátozva; a szüneteltetés előtti utolsó értesítés közli, meddig tart a szüneteltetés. Minden hiba továbbra is bekerül a naplóba. A kézzel újraküldött kérésről nem megy értesítés.

Kézbesítési napló​

Minden próbálkozást rögzítünk: az időpontot, a HTTP-státuszt vagy a hálózati hibát, az időtartamot és a szervere válaszának elejét.

Az alkalmazásban: CRM → Kommunikáció → nyisson meg egy API-hívás típusú bejegyzést. Itt látható az állapot (Kézbesítve, Újrapróbálkozás, Nincs kézbesítve), az összes próbálkozás, a következő időpontja és a Küldés újra gomb.

Az API-n keresztül (hitelesítés az API-kulcsával az x-api-key fejlécben):

KérésEredmény
GET /v1/webhook-deliveriesA kézbesítései, a legújabbal kezdve. Szűrők: status (pending, delivered, failed), agent_id, call_id, limit, offset
GET /v1/webhook-deliveries/{id}Egy kézbesítés az összes próbálkozással és a kérés törzsével
POST /v1/webhook-deliveries/{id}/resendAzonnal újraküldi, és visszaadja az eredményt
{
"id": "6ac71fb82e4f72e709a4a566",
"delivery_id": "0b0f2f0e-6c0f-4f0b-9c55-3c6a3a1f8a11",
"kind": "api_call",
"name": "Create ticket",
"call_id": "6ac71f9d2e4f72e709a4a4f0",
"status": "pending",
"attempts_made": 2,
"attempts_max": 8,
"next_attempt_at": "2026-10-09T11:36:04.000Z",
"attempts": [
{ "n": 1, "at": "2026-10-09T11:30:03.512Z", "duration_ms": 212, "error": "connection refused" },
{ "n": 2, "at": "2026-10-09T11:31:04.007Z", "duration_ms": 187, "status_code": 503, "error": "HTTP 503", "response_preview": "Service Unavailable" }
]
}

A tárolt kérés fejlécértékeit (az Ön kulcsait) soha nem adjuk vissza.

Hálózat és tűzfal​

A Hanc.AI az Ön végpontját hívja meg – a kapcsolat mindig a mi oldalunkról nyílik az Ön oldala felé.

IrányKimenő a Hanc.AI felől → bejövő az Ön oldalán
Forrás IP-címek178.104.10.47 (kézbesítési szolgáltatás) és 128.140.65.92 (hívásszolgáltatás, tartalék útvonalként)
ProtokollHTTPS (TLS 1.2 vagy újabb). A titkosítatlan HTTP működik, de nem ajánlott
Port443, vagy az URL-jében megadott port
IP-verzióIPv4
TanúsítványÉrvényesnek kell lennie, és nyilvános hitelesítésszolgáltatónak kell kiállítania; az önaláírt tanúsítványokat elutasítjuk
VálaszidőVálaszoljon 30 másodpercen belül – a legjobb azonnal nyugtázni, és a háttérben feldolgozni
ÁtirányításokKövetjük őket, legfeljebb 5-öt

Engedélyezőlista: ha a tűzfala vagy a WAF forráscím szerint szűr, engedélyezze a fenti két címet a webhook útvonalához. E címek változását előre bejelentjük.

Nem lehetséges: magánhálózaton belüli címek (10.x, 172.16–31.x, 192.168.x, localhost). A végpontnak az internetről elérhetőnek kell lennie – közvetlenül vagy a reverse proxyján / API-átjáróján keresztül.

Böngésző: a webhookok szerverek között futnak. Böngészőbeállítások, bővítmények vagy a munkatársak munkaállomásain megnyitott portok nem játszanak szerepet.

A kérés formátuma​

A POST, a PUT és a PATCH kérés JSON-törzset visz (Content-Type: application/json, UTF-8).

{
"id": "6ac7ea6eca60c6024b465c70",
"agent_id": "6ac2a93e36bad261cf088684",
"call_from": "+431234567890",
"call_to": "+439876543210",
"direction": "inbound",
"call_type": "phone",
"call_status": "success",
"start_timestamp": 1730000000000,
"end_timestamp": 1730000187000,
"duration": 187000,
"call_summary": "Customer reports a broken router and asks for a callback…",
"transcription": [
{ "speaker": "agent", "content": "Hello…", "timestamp": 1730000001000 },
{ "speaker": "user", "content": "Hi…", "timestamp": 1730000003000 }
],
"task_achieved": true,
"sentiment": { "sentiment": "neutral", "explanation": "…" },
"custom_analysis_data": {
"customer_number": "K-20417",
"ticket_category": "Hardware",
"priority": "high"
},
"collected_data": { },
"transfer_history": [ ],
"recording_url": "https://…",
"disconnection_reason": "user_hangup",
"is_anonymous": false,
"is_simulation": false,
"created_at": 1730000000000,
"updated_at": 1730000187000
}
MezőTartalom
id, agent_idA hívás és az azt lebonyolító ügynök
call_summaryA beszélgetés összefoglalója
transcriptionA teljes beszélgetés megszólalásonként, időbélyegekkel
call_from, call_to, directionHívó, hívott szám, bejövő vagy kimenő
call_type, call_statusphone vagy web; success vagy failed
start_timestamp, end_timestamp, durationUnix-idő és időtartam ezredmásodpercben
custom_analysis_dataAz Ön saját mezői, a beszélgetésből kinyerve – lásd: Lekérdezési változók
collected_dataAz ügynök által a hívás közben gyűjtött adatok
sentiment, task_achievedA beszélgetés hangulata, és hogy teljesült-e a célja
recording_urlA felvétel hivatkozása, ha a felvétel be van kapcsolva
transfer_historyA hívás közben történt átadások
disconnection_reasonHogyan ért véget a hívás, például user_hangup, agent_hangup, call_transfer, voicemail
is_anonymous, is_simulationA hívó elrejtette a számát; a hívás szimulált teszt volt
created_at, updated_atA hívásrekord létrehozásának és utolsó frissítésének időpontja (Unix-idő, ms)

Csak ezeket a mezőket küldjük el. A hívásról semmi más nem hagyja el a platformot.

A GET és a DELETE esetén ugyanezek a mezők a lekérdezési karakterláncban utaznak; a beágyazott értékek, például a transcription, kimaradnak.

Fejlécek​

FejlécJelentés
X-Hanc-Delivery-IdA kézbesítést azonosítja. Minden próbálkozásnál azonos – ezzel szűrhetők ki az ismétlődések
X-Hanc-AttemptA próbálkozás sorszáma, 1-től kezdve
User-AgentHANC-Webhooks/1.0
az Ön fejléceiMinden, amit a műveletben beállított

Hitelesítés​

Ön dönti el, miről ismer fel minket a végpontja:

  • API-kulcs vagy token – adjon a művelethez egy fejlécet, pl. Authorization: Bearer <token> vagy X-API-Key: <key>. A fejléceket minden próbálkozással elküldjük.
  • Basic auth – Authorization: Basic <base64(user:password)>.
  • Lekérdezési paraméter – olyan rendszerekhez, amelyek a kulcsot az URL-ben várják.
  • Forráscím – csak a fent felsorolt IP-címeket engedélyezze.

A módszerek kombinálhatók; a szokásos beállítás egy kulcs és egy IP-engedélyezőlista együtt.

A kérés igazítása a saját rendszerhez​

Alapértelmezés szerint a kérés a hívás mezőit tartalmazza (lásd: A kérés formátuma). Olyan rendszer esetén, amely a saját szerkezetét várja – a legtöbb jegykezelő rendszer ilyen –, ezt a szerkezetet Ön írja le, és a hívás adataival tölti ki.

Változók​

A hívás utáni API hívás műveletben és a munkafolyamat API-hívás típusú Eszköz lépésében az URL, a fejlécek, a lekérdezési paraméterek és a törzs dupla kapcsos zárójelbe írt változókat fogadnak. Ezeket közvetlenül a kérés elküldése előtt töltjük ki a hívás adataival.

VáltozóÉrték
{{call_id}}A hívás azonosítója
{{call_from}}, {{call_to}}A hívó és a hívott szám
{{customer_phone}}, {{customer_email}}A másik fél telefonszáma és e-mail-címe, a hívás irányától függetlenül
{{call_direction}}, {{call_type}}inbound / outbound, phone / web
{{call_start}}, {{call_end}}Kezdés és befejezés, ISO 8601 (UTC)
{{call_duration}}Időtartam másodpercben
{{call_summary}}A beszélgetés összefoglalója
{{call_transcription}}A teljes beszélgetés szövegként
{{call_sentiment}}, {{call_task_achieved}}A hangulat, és hogy teljesült-e a cél
{{call_recording_url}}A felvétel hivatkozása
{{agent_id}}Az ügynök azonosítója
az Ön mezőiMinden lekérdezési változó a saját nevén, pl. {{customer_number}}, {{priority}} – valamint minden változó, amelyet egy munkafolyamat a hívás közben gyűjtött

Amit érdemes tudni:

  • Az a törzsmező, amely egyetlen változóból áll, megtartja a változó típusát: a "priority": "{{priority}}" a 3 számként, az "urgent": "{{urgent}}" pedig true értékként megy ki. Ha a változó körül szöveg is áll, az érték szöveg lesz.
  • Az URL-be helyezett értéket automatikusan százalékkódoljuk (a +43… helyett %2B43… lesz).
  • Az a változó, amelyhez a hívásban nincs érték, üresen megy ki – soha nem a szó szerinti {{name}} formában.

Az alkalmazásban egy mező {x} gombja felsorolja az elérhető változókat; a törzsben a {{ beírására megjelennek a javaslatok.

Törzs​

A művelet Törzs (JSON) mezőjébe azt a JSON-objektumot írja, amelyet a rendszere vár, tetszőleges mélységben egymásba ágyazva:

{
"ticket": {
"subject": "Call from {{customer_phone}}: {{ticket_category}}",
"comment": { "body": "{{call_summary}}" },
"priority": "{{priority}}",
"custom_fields": [
{ "id": 360001, "value": "{{customer_number}}" },
{ "id": 360002, "value": "{{call_recording_url}}" }
],
"tags": ["phone-agent"]
}
}

Csak a saját mezők​

Ha a Csak a saját mezőim küldése be van kapcsolva, a kérés kizárólag az Ön törzsét és lekérdezési paramétereit tartalmazza – a hívásadatok nem kerülnek bele. Ha kikapcsolva hagyja, a mezőit a hívás mezőivel együtt küldjük el.

Szelektív küldés​

Egy hétköznapi nyelven megfogalmazott feltétel („csak ha a hívó hibát jelent be”) dönti el, mely hívások váltják ki a kérést. Több művelet különböző rendszerekre vagy végpontokra is mutathat.

Jegykezelő rendszer csatlakoztatása​

Bármely jegykezelő rendszer fogadhat hívásokat, amelynek van HTTP API-ja vagy bejövő webhookja – közvetlenül, közbeiktatott szoftver nélkül. Az Ön oldalán a következőkre van szükség:

  1. Egy végpont, amely az internetről HTTPS-en keresztül elérhető, és JSON-t fogad.
  2. Egy hitelesítő adat hozzá (API-kulcs, token vagy basic auth), a műveletben fejlécként megadva.
  3. Ha cím szerint szűr – a fenti két IP-cím az engedélyezőlistáján.

Ezután a műveletben:

  1. Határozza meg a mezőit. Vegyen fel lekérdezési változókat, például ügyfélszám, jegykategória, prioritás, visszahívást kér. Az ügynök a beszélgetés alapján tölti ki őket.
  2. Írja meg a törzset a jegykezelő API-ja szerkezetében, és helyezze a változókat a megfelelő helyre.
  3. Kapcsolja be a Csak a saját mezőim küldése kapcsolót.
  4. Kattintson az API konfiguráció tesztelése gombra, majd indítson egy teszthívást.

A rendszeréhez illő törzset szívesen előkészítjük Önnel közösen.

Tesztelés​

Kapcsolatteszt. A művelet API konfiguráció tesztelése gombja azonnal elküld egy mintakérést, és megmutatja, sikerült-e elérni a végpontját.

Az újrapróbálkozások tesztje – hogy a saját szemével lássa a mechanizmust:

  1. A műveletben az Újrapróbálkozások hiba esetén alatt állítson be rövid ütemezést, például három 1 perces szünetet.
  2. Állítsa le a végpontját, vagy tiltsa le a címeinket a tűzfalon.
  3. Indítson teszthívást az ügynökhöz.
  4. Nyissa meg a CRM → Kommunikáció oldalt: a bejegyzésnél az Újrapróbálkozás állapot, a sikertelen próbálkozás a hibájával és a következő próbálkozás időpontja látható.
  5. Indítsa el újra a végpontot (vagy oldja fel a tiltást). A következő próbálkozás kézbesíti a hívást, és a bejegyzés Kézbesítve állapotra vált – vagy kattintson a Küldés újra gombra az azonnali kézbesítéshez.

Ellenőrzőlista a végpontjához​

  • Válaszoljon 2xx státusszal, amint a kérést eltárolta; a nehezebb munkát utána végezze el.
  • Kezelje az X-Hanc-Delivery-Id értéket idempotenciakulcsként.
  • Válaszoljon 4xx/5xx státusszal, ha nem tudta átvenni a kérést – újra jelentkezünk.
  • Tartsa érvényesen a tanúsítványt, és hagyja engedélyezve a két forráscímet.