Webhooky a doručování

Po každém hovoru může Hanc.AI odeslat hovor – souhrn, přepis, extrahovaná pole – do vašeho vlastního systému: tiketovacího systému, CRM, ERP nebo na libovolný HTTPS endpoint. Tato stránka popisuje přesně, jak se toto doručování chová: co se stane, když váš server neběží, jak často pokus opakujeme, co musí povolit váš firewall a jak požadavek vypadá.

Všechny tarify

Doručování po hovoru s opakováním a protokolem doručení je dostupné v každém tarifu, včetně tarifu Free.

Co se odesílá a kdy

Požadavek se odešle, jakmile hovor skončí a jeho analýza je hotová (souhrn, sentiment, vaše extrahovaná pole) – obvykle několik sekund po zavěšení.

Zdroj	Kde jej nastavíte
Akce „API volání“	Agent → Akce → Post call → API volání
Krok workflow	Workflow Builder → krok nástroje Volání API s nastavením Kdy se spustí: Po hovoru
Webhook agenta	Pole `webhook_url` agenta (API Reference)

Požadavky, které agent posílá během konverzace (živé nástroje), sem nepatří: jsou potřeba právě v té vteřině a později se nikdy neopakují.

Když váš server není dostupný

Nic se neztratí. Požadavek se před prvním pokusem uloží do fronty doručování a zůstane v ní, dokud jej váš server nepřijme nebo dokud se rozvrh nevyčerpá.

Doručení se považuje za úspěšné, když váš endpoint do 30 sekund odpoví libovolným stavem 2xx.
Všechno ostatní se opakuje: odmítnuté spojení, chyby DNS nebo TLS, vypršení časového limitu a jakýkoli jiný stav – 5xx, 429 a také 4xx. Pokud vypršela platnost API klíče a vy jej obnovíte, čekající hovory dorazí samy.
Každý pokus odesílá tentýž požadavek se stejným ID doručení.

Rozvrh opakování

Pokus	Pauza před ním	Čas od konce hovoru
1	– (ihned)	~0
2	1 minuta	~1 min
3	5 minut	~6 min
4	30 minut	~36 min
5	2 hodiny	~2 h 36 min
6	6 hodin	~8 h 36 min
7	24 hodin	~1 den 8 h
8	48 hodin	~3 dny 8 h

To je 8 pokusů během přibližně 3,4 dne – dost na to, aby se překlenul i víkendový výpadek.

Váš vlastní rozvrh

V akci API volání (a v kroku workflow Volání API, který se spouští po hovoru) můžete rozvrh nahradit v poli Opakování při chybě:

až 10 opakování,
každá pauza od 1 minuty do 7 dní,
odeberete-li všechny řádky, požadavek se odešle jednou, bez opakování.

Akce, kterou jste nikdy neupravovali, se řídí výchozím rozvrhem uvedeným výše.

Po posledním pokusu

Doručení se označí jako Nedoručeno, dostanete oznámení e-mailem, pokud jste je nevypnuli, a požadavek se uchová 30 dní. Během této doby jej můžete odeslat znovu – jedním kliknutím v protokolu doručení nebo jedním voláním API. Opětovné odeslání je možné i u doručení, které už proběhlo úspěšně, například po obnově dat na vaší straně.

Nezávisle na jakémkoli webhooku zůstává samotný hovor ve vašem účtu Hanc.AI – přepis, souhrn, nahrávka a extrahovaná pole jsou k dispozici v sekci Hovory a přes API. Dlouhý výpadek předání do vašeho systému zdrží; konverzaci nesmaže.

Alespoň jednou

Doručení probíhá alespoň jednou. Ve vzácných případech – například když váš server požadavek zpracoval, ale odpověď k nám nedorazila včas – dorazí stejný hovor dvakrát. Podle hlavičky X-Hanc-Delivery-Id opakování poznáte a přeskočíte.

Oznámení o selhání

Protokol nemusíte hlídat: akce vám může dát e-mailem vědět, když se její požadavek nepodaří doručit. Zvolte v poli Oznámení o selhání v akci (nebo v kroku workflow):

Nastavení	Kdy se e-mail odešle
Po posledním pokusu (výchozí)	Jednou, když je rozvrh opakování vyčerpán a požadavek se označí jako Nedoručeno
Po každém neúspěšném pokusu	Po každém neúspěšném pokusu, s časem dalšího – a po posledním
Neoznamovat	Nikdy; selhání jsou vidět jen v protokolu

E-mail uvádí akci a agenta, hostitele vašeho serveru, jeho odpověď (například HTTP 503 nebo timeout after 30s), o kolikátý pokus z kolika šlo, a odkazuje na protokol doručení. Poslední e-mail navíc uvádí, do kdy se požadavek uchovává a že jej lze odeslat znovu.

Pole Odeslat na určuje příjemce – obvykle toho, kdo provozuje přijímající systém. Zůstane-li prázdné, e-mail dostane vlastník účtu. Je napsán v jazyce účtu.

Aby výpadek nezahltil vaši schránku, jsou oznámení omezena pro každou akci na 10 za hodinu a 30 za den; poslední před pauzou uvádí, do kdy pauza trvá. Každé selhání se dál zaznamenává do protokolu. O požadavku, který znovu odešlete ručně, se oznámení neposílá.

Protokol doručení

Každý pokus se zaznamená: čas, stav HTTP nebo síťová chyba, doba trvání a začátek odpovědi vašeho serveru.

V aplikaci: CRM → Komunikace → otevřete záznam typu API volání. Uvidíte stav (Doručeno, Opakuje se, Nedoručeno), všechny pokusy, čas dalšího a tlačítko Odeslat znovu.

Přes API (ověření vaším API klíčem v hlavičce x-api-key):

Požadavek	Výsledek
`GET /v1/webhook-deliveries`	Vaše doručení, od nejnovějších. Filtry: `status` (`pending`, `delivered`, `failed`), `agent_id`, `call_id`, `limit`, `offset`
`GET /v1/webhook-deliveries/{id}`	Jedno doručení se všemi pokusy a tělem požadavku
`POST /v1/webhook-deliveries/{id}/resend`	Odešle je znovu hned a vrátí výsledek

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

Hodnoty hlaviček uloženého požadavku (vaše klíče) se nikdy nevracejí.

Síť a firewall

Hanc.AI volá váš endpoint – spojení se vždy navazuje z naší strany na vaši.


Směr	Odchozí z Hanc.AI → příchozí na vaší straně
Zdrojové IP adresy	`178.104.10.47` (služba doručování) a `128.140.65.92` (služba hovorů, používá se jako záloha)
Protokol	HTTPS (TLS 1.2 nebo novější). Nešifrované HTTP funguje, ale nedoporučuje se
Port	`443`, nebo port uvedený ve vaší URL
Verze IP	IPv4
Certifikát	Musí být platný a vydaný veřejnou certifikační autoritou; certifikáty podepsané samy sebou (self-signed) jsou odmítány
Doba odezvy	Odpovězte do 30 sekund – ideálně požadavek ihned potvrďte a zpracujte jej na pozadí
Přesměrování	Následujeme je, nejvýše 5

Seznam povolených adres: pokud váš firewall nebo WAF filtruje podle zdrojové adresy, povolte obě výše uvedené adresy pro cestu vašeho webhooku. Změnu těchto adres oznamujeme předem.

Není možné: adresy uvnitř privátní sítě (10.x, 172.16–31.x, 192.168.x, localhost). Endpoint musí být dosažitelný z internetu – přímo, nebo přes vaši reverzní proxy či API bránu.

Prohlížeč: webhooky běží mezi servery. Nehrají v nich roli žádná nastavení prohlížeče, rozšíření ani otevřené porty na pracovních stanicích zaměstnanců.

Formát požadavku

Požadavky POST, PUT a PATCH nesou tělo ve formátu JSON (Content-Type: application/json, UTF-8).

{
  "call_from": "+431234567890",
  "call_to":   "+439876543210",
  "direction": "inbound",
  "call_type": "phone",
  "call_status": "ended",
  "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"
}

Pole	Obsah
`call_summary`	Souhrn konverzace
`transcription`	Celá konverzace, promluvu po promluvě, s časovými značkami
`call_from`, `call_to`, `direction`	Volající, volané číslo, příchozí nebo odchozí hovor
`start_timestamp`, `end_timestamp`, `duration`	Unixový čas a doba trvání v milisekundách
`custom_analysis_data`	Vaše vlastní pole extrahovaná z konverzace – viz Proměnné pro získávání dat
`collected_data`	Data, která agent během hovoru nasbíral
`sentiment`, `task_achieved`	Nálada konverzace a to, zda bylo dosaženo jejího cíle
`recording_url`	Odkaz na nahrávku, pokud je nahrávání zapnuto
`transfer_history`	Přepojení, ke kterým během hovoru došlo

U metod GET a DELETE se stejná pole přenášejí v query stringu; vnořené hodnoty, jako je transcription, se vynechávají.

Hlavičky

Hlavička	Význam
`X-Hanc-Delivery-Id`	Identifikuje doručení. Při každém pokusu stejná – použijte ji k přeskočení duplicit
`X-Hanc-Attempt`	Číslo pokusu, počínaje `1`
`X-Correlation-Id`	Interní trasovací ID; uveďte je, když kontaktujete podporu
`User-Agent`	`HANC-Webhooks/1.0`
vaše hlavičky	Vše, co jste v akci nastavili

Ověřování

Sami rozhodujete, podle čeho nás váš endpoint pozná:

API klíč nebo token – přidejte do akce hlavičku, např. Authorization: Bearer <token> nebo X-API-Key: <key>. Hlavičky se odesílají při každém pokusu.
Basic auth – Authorization: Basic <base64(user:password)>.
Query parametr – pro systémy, které očekávají klíč v URL.
Zdrojová adresa – povolte pouze výše uvedené IP adresy.

Metody lze kombinovat; obvyklým nastavením je klíč spolu se seznamem povolených IP adres.

Přizpůsobení požadavku vašemu systému

Ve výchozím nastavení požadavek nese celý hovor (viz Formát požadavku). Pro systém, který očekává vlastní strukturu – což je většina tiketovacích systémů – tuto strukturu popíšete sami a naplníte ji daty z hovoru.

Proměnné

V akci API volání po hovoru a v kroku workflow Volání API přijímají URL, hlavičky, query parametry a tělo proměnné ve dvojitých složených závorkách. Vyplní se z hovoru těsně před odesláním požadavku.

Proměnná	Hodnota
`{{call_id}}`	ID hovoru
`{{call_from}}`, `{{call_to}}`	Volající a volané číslo
`{{customer_phone}}`, `{{customer_email}}`	Číslo a e-mail protistrany bez ohledu na směr hovoru
`{{call_direction}}`, `{{call_type}}`	`inbound` / `outbound`, `phone` / `web`
`{{call_start}}`, `{{call_end}}`	Začátek a konec, ISO 8601 (UTC)
`{{call_duration}}`	Doba trvání v sekundách
`{{call_summary}}`	Souhrn konverzace
`{{call_transcription}}`	Celá konverzace jako text
`{{call_sentiment}}`, `{{call_task_achieved}}`	Nálada a to, zda bylo dosaženo cíle
`{{call_recording_url}}`	Odkaz na nahrávku
`{{agent_id}}`	ID agenta
vaše pole	Každá Proměnná pro získávání dat pod svým názvem, např. `{{customer_number}}`, `{{priority}}` – a každá proměnná, kterou během hovoru nasbíralo workflow

Pravidla, která je dobré znát:

Pole těla, které se skládá pouze z jedné proměnné, si zachová její typ: "priority": "{{priority}}" se odešle jako číslo 3, "urgent": "{{urgent}}" jako true. Text kolem proměnné z ní udělá text.
Hodnota vložená do URL se automaticky zakóduje procentovým kódováním (+43… se změní na %2B43…).
Proměnná, pro kterou hovor nemá hodnotu, se odešle prázdná – nikdy ne jako doslovné {{name}}.

V aplikaci tlačítko {x} v poli zobrazí seznam dostupných proměnných; v těle se nabídnou po napsání {{.

Tělo

V poli Tělo (JSON) v akci napíšete objekt JSON, který váš systém očekává, vnořený tak hluboko, jak je potřeba:

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

Jen vaše pole

Je-li zapnuta volba Odesílat jen moje pole, požadavek nese pouze vaše tělo a vaše query parametry – data o hovoru se nepřidávají. Necháte-li ji vypnutou, odešlou se vaše pole společně s kompletními daty o hovoru.

Výběrové odesílání

Podmínka zapsaná běžným jazykem („jen pokud volající hlásí poruchu“) rozhoduje, které hovory požadavek spustí. Několik akcí může směřovat na různé systémy nebo endpointy.

Připojení tiketovacího systému

Hovory může přijímat jakýkoli tiketovací systém s HTTP API nebo příchozím webhookem – přímo, bez softwarového mezičlánku. Na vaší straně je potřeba:

Endpoint dosažitelný z internetu přes HTTPS, který přijímá JSON.
Přístupové údaje k němu (API klíč, token nebo basic auth), zadané v akci jako hlavička.
Pokud filtrujete podle adresy – obě výše uvedené IP adresy na vašem seznamu povolených.

Poté v akci:

Definujte svá pole. Přidejte Proměnné pro získávání dat, například zákaznické číslo, kategorie tiketu, priorita, žádost o zpětné zavolání. Agent je vyplní z konverzace.
Napište tělo ve struktuře API vašeho tiketovacího systému a umístěte proměnné tam, kam patří.
Zapněte Odesílat jen moje pole.
Klikněte na Otestovat konfiguraci API a poté uskutečněte testovací hovor.

Tělo pro váš systém rádi připravíme společně s vámi.

Testování

Test spojení. Tlačítko Otestovat konfiguraci API v akci ihned odešle ukázkový požadavek a ukáže, zda se požadavek k vašemu endpointu dostal.

Test opakování – abyste mechanismus viděli na vlastní oči:

V akci nastavte v poli Opakování při chybě krátký rozvrh, například tři pauzy po 1 minutě.
Zastavte svůj endpoint nebo zablokujte naše adresy ve firewallu.
Uskutečněte testovací hovor s agentem.
Otevřete CRM → Komunikace: záznam ukazuje stav Opakuje se, neúspěšný pokus s jeho chybou a čas dalšího pokusu.
Endpoint znovu spusťte (nebo blokování zrušte). Další pokus hovor doručí a záznam se změní na Doručeno – nebo klikněte na Odeslat znovu a doručte jej okamžitě.

Kontrolní seznam pro váš endpoint

Odpovídejte 2xx, jakmile je požadavek uložen; náročné zpracování provádějte až poté.
Používejte X-Hanc-Delivery-Id jako idempotenční klíč.
Odpovídejte 4xx/5xx, když jste požadavek nemohli přijmout – ozveme se znovu.
Udržujte certifikát platný a obě zdrojové adresy povolené.

Co se odesílá a kdy​

Když váš server není dostupný​

Rozvrh opakování​

Váš vlastní rozvrh​

Po posledním pokusu​

Oznámení o selhání​

Protokol doručení​

Síť a firewall​

Formát požadavku​

Hlavičky​

Ověřování​

Přizpůsobení požadavku vašemu systému​

Proměnné​

Tělo​

Jen vaše pole​

Výběrové odesílání​

Připojení tiketovacího systému​

Testování​

Kontrolní seznam pro váš endpoint​