Каталог на събитията

Всички типове събития на уебхукове, които 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#

Изпраща се, когато правило за предупреждение с активиран канал Доставяне до уебхукове за разработчици премине своя праг. Не блокира. Правилото се задейства веднъж и след това спазва периода си на изчакване, така че продължително нарушение генерира по едно събитие за всеки прозорец на изчакване.

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

Свързано#