Webhooks

Katalog událostí

Všechny typy událostí webhooků, které ThunderPhone odesílá.

Každé tělo webhooku obsahuje pole type, jehož hodnota je jedním z typů událostí na této stránce. Když se přihlásíte k odběru koncového bodu, pole events musí obsahovat požadované typy událostí (nebo může být prázdné pro odběr všech — kromě událostí jednotlivých tahů telephony.turn / web.turn, které se doručují pouze koncovým bodům, jež je výslovně uvádějí).

Tyto události se doručují dvěma způsoby:

• Doručení do koncového bodu jsou vždy neblokující oznámení s opakovanými pokusy: odpovězte libovolným stavem 2xx; obálka obsahuje event_id pro deduplikaci.
• Blokující výměny probíhají pouze na starším webhooku s jedinou adresou URL: v rámci konfiguračního požadavku telephony.incoming / web.incoming (čísla v režimu webhooku a klíče widgetu, časový limit 10 s) a distribuce nástrojů v režimu webhooku. Vaše odpověď ovlivňuje probíhající hovor.

Níže uvedené příklady datových částí zobrazují obálku koncového bodu v pořadí přenášeném po síti (klíče jsou seřazené abecedně: data, event_id, type); starší doručení obsahují stejná data bez event_id.

Události hovorů#

telephony.incoming#

Odesílá se, když příchozí hovor dorazí na jedno z vašich telefonních čísel. Doručení na endpoint jsou oznámení odesílaná bez čekání na odpověď pro každý příchozí hovor bez ohledu na to, zda je číslo nakonfigurované pro agenta nebo webhook. Čísla bez přiřazeného agenta navíc obdrží blokující požadavek na konfiguraci na starším webhooku — úplné schéma požadavku / odpovědi najdete v telephony.incoming / web.incoming.

{
  "data": {
    "call_id": 987654321,
    "from_number": "+14155550199",
    "to_number": "+15551234567"
  },
  "event_id": "3f6b2ad0-1c9e-4a57-9f2b-8f6f0f9d2f11",
  "type": "telephony.incoming"
}

telephony.complete#

Odesílá se po ukončení příchozího nebo odchozího telefonního hovoru. Neblokující. Zahrnuje přepis, URL záznamu, pokud je k dispozici, a souhrn vyúčtování. Schéma datové části najdete v telephony.complete / web.complete.

telephony.tool#

Odesílá se poté, co telefonní hovor vyvolá nástroj funkce. Neblokující oznámení pro audit — nástroj už byl spuštěn v okamžiku doručení této události; vztahuje se na vaše vlastní nástroje funkcí (nikoli na vestavěné nástroje, nástroje znalostní báze, připojení aplikací nebo nástroje MCP).

{
  "data": {
    "arguments": { "date": "2026-04-21" },
    "call_id": 987654321,
    "from_number": "+14155550199",
    "response": {
      "response": { "available_slots": ["9:00 AM", "2:00 PM"] },
      "status": 200
    },
    "to_number": "+15551234567",
    "tool_name": "search_appointments"
  },
  "event_id": "1f0a7c3e-52d4-4a0e-8f4b-b1a6a1c0d9e2",
  "type": "telephony.tool"
}

response je výsledek spuštění: při úspěchu {"status": <http status>, "response": <your endpoint's JSON>}, případně při selhání {"status": <status>, "error": "<message>"}.

telephony.turn#

Odesílá se během probíhajícího telefonního hovoru, jednou pro každý tah obsahující řeč, jakmile nastane — mluvené odpovědi agenta a přepsané tahy volajícího. Umožňuje sledovat živou konverzaci prostřednictvím běžných webhooků místo dotazování GET /v1/calls/{call_id}/transcript. Neblokující.

{
  "data": {
    "call_id": 987654321,
    "entry_type": "completion",
    "from_number": "+14155550199",
    "position": 7,
    "role": "assistant",
    "start_ms": 15200,
    "text": "How many employees does your company have?",
    "to_number": "+15551234567"
  },
  "event_id": "8d3f5a2c-7b1e-4c9a-b6d0-2e4f6a8c0d1e",
  "type": "telephony.turn"
}

web.incoming#

Ekvivalent telephony.incoming pro webový kanál, odesílaný při zahájení relace webového widgetu nebo testovacího hovoru mikrofonu v nástroji pro tvorbu. Doručení na endpoint jsou oznámení odesílaná bez čekání na odpověď pro každou webovou relaci. Publikovatelné klíče v režimu mode="webhook" navíc obdrží blokující požadavek na konfiguraci na starším webhooku — tento blokující požadavek má jinou strukturu (origin_domain, publishable_key_prefix; bez telefonních čísel). Viz telephony.incoming / web.incoming.

{
  "data": {
    "call_id": 987654322,
    "from_number": "web",
    "origin_domain": "https://example.com",
    "publishable_key_prefix": "pk_live_a1b2",
    "to_number": "+15551234567"
  },
  "event_id": "9a2b4c6d-8e0f-4a1b-9c2d-3e4f5a6b7c8d",
  "type": "web.incoming"
}

from_number je vždy doslovná hodnota "web". Pro relace widgetu v režimu webhooku je to_number prázdné (číslo agenta relace se přiřadí po konfiguraci); pro testovací hovory mikrofonu v nástroji pro tvorbu jsou origin_domain a publishable_key_prefix prázdné.

web.complete#

Ekvivalent telephony.complete pro webový kanál, který zahrnuje hovory webového widgetu (direction: "web") a testovací hovory mikrofonu v nástroji pro tvorbu (direction: "test"). Neblokující. Má stejnou strukturu datové části jako telephony.complete, navíc s origin_domain, přičemž from_number je nastaveno na "web".

web.tool#

Ekvivalent telephony.tool pro webový kanál. Objekt data obsahuje origin_domain namísto from_number / to_number.

web.turn#

Ekvivalent telephony.turn pro webový kanál, který zahrnuje hovory webového widgetu a testovací hovory mikrofonu v nástroji pro tvorbu. Má stejnou strukturu datové části, s origin_domain namísto from_number / to_number. Stejně jako telephony.turn vyžaduje výslovné přihlášení k odběru — nikdy se nedoručuje prostřednictvím prázdného pole events.

Události hlasů#

Vytvoření vlastního hlasu probíhá asynchronně. Tyto neblokující události vám umožňují reagovat na konečný výsledek místo dotazování na koncový bod podrobností klonu.

voice.ready#

Odesláno, když vlastní hlas dokončí zpracování a lze jej přiřadit k agentovi.

{
  "data": {
    "voice": {
      "created_at": "2026-07-30T14:12:08.317Z",
      "display_name": "Support voice",
      "failure_reason": "",
      "gender": "female",
      "id": "cv_2f6f90b0e9a34ee8b39be7d1",
      "language": "en",
      "name": "custom:cv_2f6f90b0e9a34ee8b39be7d1",
      "status": "ready",
      "updated_at": "2026-07-30T14:13:31.605Z"
    }
  },
  "event_id": "2d5f0a61-e9b5-4a3c-b684-29d7d9e4b214",
  "type": "voice.ready"
}

voice.failed#

Odesláno, když zpracování vlastního hlasu skončí trvalým selháním.

{
  "data": {
    "reason": "audio sample could not be processed",
    "voice": {
      "created_at": "2026-07-30T14:12:08.317Z",
      "display_name": "Support voice",
      "failure_reason": "audio sample could not be processed",
      "gender": "female",
      "id": "cv_2f6f90b0e9a34ee8b39be7d1",
      "language": "en",
      "name": "custom:cv_2f6f90b0e9a34ee8b39be7d1",
      "status": "failed",
      "updated_at": "2026-07-30T14:13:31.605Z"
    }
  },
  "event_id": "3493e985-1a75-4f77-a10a-e74af440cd31",
  "type": "voice.failed"
}

Události kvality#

call.graded#

Odesílá se vždy, když je pro hovor dokončen běh hodnocení AI. Neblokující.

{
  "data": {
    "call_id": 987654321,
    "grade": {
      "call_outcome": "success",
      "created_at": "2026-04-20T18:25:11.002Z",
      "detected_issues": [],
      "graded_at": "2026-04-20T18:25:11.002Z",
      "grader_model": "heuristic-v1",
      "id": 5512,
      "score": 92,
      "status": "completed",
      "summary": "Caller asked about their policy and got a full answer…"
    }
  },
  "event_id": "7c1d2e3f-4a5b-4c6d-8e9f-0a1b2c3d4e5f",
  "type": "call.graded"
}

issue.reported#

Odesílá se při vytvoření hlášení problému — buď jej uživatel odešle z ovládacího panelu (source: "user"), nebo je automaticky vytvoří hodnocení hovoru (source: "system"). Neblokující.

{
  "data": {
    "call_id": 987654321,
    "issue_report": {
      "created_at": "2026-04-20T18:25:11.002Z",
      "description": "Five-second silence before responding to the main question.",
      "id": 4321,
      "severity": "warning",
      "source": "system",
      "status": "open",
      "title": "Agent paused too long"
    }
  },
  "event_id": "5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b",
  "type": "issue.reported"
}

Události testovacích hovorů#

test-call.completed#

Odesílá se, když běh testovacího hovoru dosáhne konečného stavu — completed nebo failed, včetně běhů, které selhaly při spuštění a nikdy nevytvořily hovor. Neblokující. Užitečné pro propojení dávkových běhů CI s vašimi chatovacími systémy a systémy oznámení.

{
  "data": {
    "test_call_run": {
      "call_id": 987654321,
      "completed_at": "2026-04-20T18:25:04.822Z",
      "error_message": "",
      "id": 7110,
      "status": "completed",
      "target_id": 12,
      "target_type": "agent"
    }
  },
  "event_id": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
  "type": "test-call.completed"
}

Události upozornění#

alert.triggered#

Odesílá se, když pravidlo upozornění s povoleným kanálem Doručovat do webhooků pro vývojáře překročí svou prahovou hodnotu. Neblokující. Pravidlo se spustí jednou a poté respektuje dobu ochlazení, takže trvalé překročení vytvoří jednu událost za každé okno ochlazení.

{
  "data": {
    "comparator": "lt",
    "event_id": "b8e6a1d4-2c3f-4a5b-9c8d-7e6f5a4b3c2d",
    "fired_at": "2026-04-20T18:00:00+00:00",
    "metric": "success_rate",
    "metric_value": 71.4,
    "rule_id": "d2c3b4a5-6f7e-4d8c-9b0a-1c2d3e4f5a6b",
    "rule_name": "Success rate below 80%",
    "threshold": 80.0,
    "window_hours": 24
  },
  "event_id": "4d5e6f7a-8b9c-4d0e-9f1a-2b3c4d5e6f7a",
  "type": "alert.triggered"
}

Informace o vytváření pravidel, metrikách, dobách ochlazení a kanálech e-mail / Slack najdete v průvodci upozorněními.

Související#