Katalog догађаја

Сви типови webhook догађаја које ThunderPhone емитује.

Свако тело вебхука има поље type чија је вредност један од типова догађаја на овој страници. Када се претплатите на крајњу тачку, низ events мора да садржи типове догађаја које желите (или да буде празан да бисте се претплатили на све — осим догађаја по кораку telephony.turn / web.turn, који се испоручују само крајњим тачкама које су изричито наведене).

Ови догађаји се испоручују на два начина:

• Испоруке на крајњу тачку су увек неблокирајућа обавештења са поновним покушајима: одговорите било којим кодом 2xx; омотница садржи event_id за дедупликацију.
• Блокирајуће размене се извршавају само преко застарелог вебхука са једним URL-ом: захтев за конфигурацију telephony.incoming / web.incoming (бројеви у режиму вебхука и кључеви виџета, временско ограничење од 10 s) и усмеравање алатки у режиму вебхука. Ваш одговор обликује позив уживо.

Примери корисног оптерећења у наставку приказују омотницу крајње тачке у њеном редоследу у преносу (кључеви су сортирани по абецеди: data, event_id, type); застареле испоруке садрже исти data без event_id.

Догађаји позива#

telephony.incoming#

Шаље се када долазни позив стигне на један од Ваших бројева телефона. Испоруке на крајњу тачку су обавештења без чекања одговора која се шаљу за сваки долазни позив, без обзира на то да ли је број конфигурисан за агента или за вебхук. Бројеви без додељеног агента додатно примају блокирајући захтев за конфигурацију на застарелом вебхуку — погледајте 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#

Шаље се када се заврши долазни или одлазни телефонски позив. Неблокирајуће је. Укључује транскрипт, URL снимка када је доступан и резиме обрачуна. Погледајте telephony.complete / web.complete за шему корисног терета.

telephony.tool#

Шаље се након што телефонски позив позове функцијски алат. Неблокирајуће обавештење за ревизију — алат је већ извршен када се овај догађај испоручи; обухвата Ваше сопствене функцијске алате (не уграђене алате, алате базе знања, везе са апликацијама или 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 је резултат извршавања: {"status": <http status>, "response": <your endpoint's JSON>} при успеху или {"status": <status>, "error": "<message>"} при неуспеху.

telephony.turn#

Шаље се док је телефонски позив у току, једном за сваки говорни сегмент када се догоди — агентове изговорене допуне и транскрибовани сегменти позиваоца. Омогућава Вам да пратите разговор уживо преко обичних вебхукова уместо анкетирања GET /v1/calls/{call_id}/transcript. Неблокирајуће је.

{
  "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#

Еквивалент telephony.incoming за веб-канал, шаље се када сесија веб виџета или тестни позив микрофона у градитељу почне. Испоруке на крајњу тачку су обавештења без чекања одговора за сваку веб сесију. Објављиви кључеви у mode="webhook" додатно примају блокирајући захтев за конфигурацију на застарелом вебхуку — тај блокирајући захтев има другачији облик (origin_domain, publishable_key_prefix; без бројева телефона). Погледајте 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 је увек дословна вредност "web". За сесије виџета у режиму вебхука, to_number је празан (број агента за сесију се додељује након конфигурације); за тестне позиве микрофона у градитељу, origin_domain и publishable_key_prefix су празни.

web.complete#

Еквивалент telephony.complete за веб-канал, обухвата веб позиве виџета (direction: "web") и тестне позиве микрофона у градитељу (direction: "test"). Неблокирајуће је. Исти облик корисног терета као telephony.complete, уз origin_domain, са from_number постављеним на "web".

web.tool#

Еквивалент telephony.tool за веб-канал. data садржи origin_domain уместо from_number / to_number.

web.turn#

Еквивалент telephony.turn за веб-канал, обухвата позиве веб виџета и тестне позиве микрофона у градитељу. Исти облик корисног терета, са origin_domain уместо from_number / to_number. Као и telephony.turn, захтева изричиту претплату — никада се не испоручује кроз празан низ events.

Гласовни догађаји#

Креирање прилагођеног гласа је асинхроно. Ови неблокирајући догађаји Вам омогућавају да реагујете на коначан резултат уместо да проверавате крајњу тачку са детаљима клона.

voice.ready и voice.failed испоручују се само крајњој тачки за целу организацију са events: []. Не могу се изабрати као експлицитни филтери догађаја.

voice.ready#

Шаље се када се обрада прилагођеног гласа заврши и глас може да се додели агенту.

{
  "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#

Шаље се када обрада прилагођеног гласа наиђе на трајни неуспех.

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

Догађаји квалитета#

call.graded#

Шаље се кад год се покретање оцењивања помоћу AI заврши за позив. Неблокирајуће.

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

call.data_extracted#

Шаље се кад год се успешно заврши издвајање структурираних података, укључујући касни поновни покушај након telephony.complete / web.complete или ручно поновно покретање путем POST /v1/calls/{call_id}/extract. Неблокирајуће.

У режиму блокирајућег издвајања, догађај завршетка обично не чека дуже од буџета за издвајање од 75 секунди. Ако се процес радника за издвајање изгуби, производни завршни одлив (сваких пет минута) ослобађа завршетак чији је blocking_deadline_at истекао пре него што започне други покушај издвајања. Каснији успех се засебно испоручује као овај догађај.

{
  "data": {
    "call_id": 987654321,
    "agent_id": 12,
    "agent_name": "Acme intake",
    "extracted_data": {
      "status": "completed",
      "fields": {
        "customer_name": "Alex Morgan",
        "appointment_date": "2026-04-23"
      },
      "evidence": {
        "customer_name": {
          "quote": "My name is Alex Morgan",
          "speaker_role": "caller",
          "turn_index": 4
        },
        "appointment_date": {
          "quote": "April 23 works for me",
          "speaker_role": "caller",
          "turn_index": 7
        }
      },
      "verification": "verified",
      "field_reasons": {},
      "schema_version": "92850758e231a3c95a..."
    },
    "extracted_at": "2026-04-20T18:25:11.002Z",
    "model": "gemini-2.5-flash"
  },
  "event_id": "4d79ef1d-c2b1-4ed6-85b8-8326bd2895ef",
  "type": "call.data_extracted"
}

campaign.completed#

Шаље се једном када кампања пређе из running у completed, било да је њен распоред завршен или су сви контакти достигли коначна стања. Поновни покушаји покретача не емитују други догађај. Овај догађај животног циклуса на нивоу организације испоручује се само крајњим тачкама у опсегу организације, а не крајњим тачкама у опсегу агента. Неблокирајуће.

{
  "data": {
    "campaign_id": "3f6b2c9e-2a0d-4c63-b6d6-a708dc98f403",
    "name": "May win-back",
    "agent_id": 12,
    "status": "completed",
    "started_at": "2026-04-20T17:00:00Z",
    "completed_at": "2026-04-20T18:25:11Z",
    "counts": {
      "contacts_total": 150,
      "completed": 121,
      "failed": 11,
      "no_answer": 18,
      "remaining": 0
    }
  },
  "event_id": "8d8f52ce-6b46-423f-9dde-cea0b91ec135",
  "type": "campaign.completed"
}

Четири броја исхода се међусобно искључују и њихов збир је contacts_total: completed садржи успешне контакте; no_answer садржи неуспеле/исцрпљене контакте у коначном стању чији је коначни исход био неодговарање; failed садржи све остале неуспеле/исцрпљене контакте у коначном стању; а remaining садржи контакте на чекању, заказане контакте или контакте који се тренутно позивају. Контакт који чека на поновни покушај је remaining, чак и када је његов најскорији покушај био неодговарање. Позиви у току се усклађују пре једнократног снимка завршетка. started_at је конфигурисани почетак кампање или време креирања кампање када почетак није конфигурисан.

issue.reported#

Шаље се када се креира пријава проблема — било да је корисник поднесе са контролне табле (source: "user") или аутоматски оцењивањем позива (source: "system"). Неблокирајуће.

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

issue.escalated#

Шаље се када се образац проблема пошаље ThunderPhone-у на преглед особља: након Пријавите ThunderPhone-у, или када Исправите помоћу AI не може да потврди исправку на страни корисника и аутоматски усмери проблем. Овај догађај примају само крајње тачке за целу организацију.

{
  "data": {
    "automatic": false,
    "cluster_id": "7ac2844c-2df0-4fa8-a560-7378da649e19",
    "escalation_id": "ec99f52b-c8c0-41dd-a4f2-dd8a07b10894",
    "status": "open"
  },
  "event_id": "d8f8f420-7a42-45ba-bcf1-b747f9bbecda",
  "type": "issue.escalated"
}

Ово је обавештење, а не пакет доказа. Користите cluster_id да га повежете са обрасцем проблема. Погледајте Пријавите ThunderPhone-у.

Догађаји тест-позива#

test-call.completed#

Шаље се када покретање тест-позива достигне завршни статус — completed или failed, укључујући покретања која нису успела при покретању и никада нису произвела позив. Није блокирајуће. Корисно за повезивање групних CI покретања са вашим системима за ћаскање/обавештења.

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

Догађаји упозорења#

alert.triggered#

Шаље се када правило упозорења са омогућеним каналом Испоручи на webhook-ове за програмере пређе свој праг. Није блокирајуће. Правило се активира једном, а затим поштује период хлађења, па трајно прекорачење производи један догађај по периоду хлађења.

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

Погледајте водич за упозорења за креирање правила, метрике, периоде хлађења и канале е-поште / Slack-а.

Повезано#