Katalogi ya Matukio

Kila mwili wa webhook una sehemu ya type ambayo thamani yake ni mojawapo ya aina za matukio kwenye ukurasa huu. Unapojisajili kwenye kikomo, safu ya events lazima iwe na aina za matukio unazotaka (au iwe tupu ili kujisajili kwa yote).

Mitindo miwili ya utumaji hubeba matukio haya:

• Utumaji wa kikomo daima ni arifa zisizozuia zenye majaribio tena: jibu kwa 2xx yoyote; bahasha ina event_id kwa ajili ya kuondoa nakala rudufu.
• Mabadilishano yanayozuia hufanyika tu kwenye webhook ya urithi yenye URL moja: ombi la usanidi la telephony.incoming / web.incoming (nambari za hali ya webhook na funguo za wijeti, muda wa kuisha wa s 10) na utumaji wa zana wa hali ya webhook. Jibu lako huunda simu inayoendelea.

Payload za mfano hapa chini zinaonyesha bahasha ya kikomo katika mpangilio wake wa utumaji (funguo zimepangwa kialfabeti: data, event_id, type); utumaji wa urithi hubeba data sawa bila event_id.

Matukio ya simu

telephony.incoming

Hutumwa simu inayoingia inapofika kwenye mojawapo ya namba zako za simu. Uwasilishaji kwenye endpoint ni arifa zinazotumwa bila kusubiri kwa kila simu inayoingia, iwe namba imesanidiwa kwa ejenti au webhook. Namba zisizo na ejenti iliyoteuliwa hupokea pia ombi la usanidi linalozuia kwenye webhook ya zamani — angalia telephony.incoming / web.incoming kwa schema kamili ya ombi / jibu.

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

telephony.complete

Hutumwa simu ya simu inayoingia au kutoka inapoisha. Haizuii. Inajumuisha transkripti, URL ya rekodi inapopatikana, na muhtasari wa malipo. Angalia telephony.complete / web.complete kwa schema ya payload.

telephony.tool

Hutumwa baada ya simu ya simu kuitisha zana ya function. Arifa ya ukaguzi isiyozuia — zana tayari imetekelezwa wakati tukio hili linapowasilishwa; inahusu zana zako mwenyewe za function (si zana zilizojengewa ndani, za msingi wa maarifa, za muunganisho wa app, au za 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 ni matokeo yaliyotekelezwa: {"status": <http status>, "response": <your endpoint's JSON>} yakifaulu, au {"status": <status>, "error": "<message>"} yakishindwa.

web.incoming

Sawa na telephony.incoming katika chaneli ya wavuti, hutumwa wakati kipindi cha wijeti ya wavuti au simu ya majaribio ya maikrofoni ya builder inapoanza. Uwasilishaji kwenye endpoint hutumwa bila kusubiri kwa kila kipindi cha wavuti. Funguo zinazoweza kuchapishwa katika mode="webhook" hupokea pia ombi la usanidi linalozuia kwenye webhook ya zamani — ombi hilo linalozuia lina muundo tofauti (origin_domain, publishable_key_prefix; hakuna namba za simu). Angalia 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 daima huwa thamani halisi "web". Kwa vipindi vya wijeti katika hali ya webhook, to_number haina thamani (namba ya ejenti ya kipindi huteuliwa baada ya usanidi); kwa simu za majaribio ya maikrofoni ya builder, origin_domain na publishable_key_prefix hazina thamani.

web.complete

Sawa na telephony.complete katika chaneli ya wavuti, ikijumuisha simu za wijeti ya wavuti (direction: "web") na simu za majaribio ya maikrofoni ya builder (direction: "test"). Haizuii. Ina muundo sawa wa payload na telephony.complete, pamoja na origin_domain, huku from_number ikiwekwa kuwa "web".

web.tool

Sawa na telephony.tool katika chaneli ya wavuti. data hubeba origin_domain badala ya from_number / to_number.

Matukio ya sauti

Uundaji wa sauti maalum hufanyika kwa njia isiyo ya usawazishaji. Matukio haya yasiyozuia utekelezaji hukuruhusu kuitikia matokeo ya mwisho badala ya kuchunguza mara kwa mara endpoint ya maelezo ya clone.

voice.ready

Hutumwa sauti maalum inapomaliza kuchakatwa na inaweza kupewa ejenti.

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

Hutumwa uchakataji wa sauti maalum unapofikia hitilafu ya kudumu.

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

Matukio ya ubora

call.graded

Hutumwa kila uendeshaji wa ukadiriaji wa AI unapokamilika kwa simu. Haiathiri utekelezaji.

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

Hutumwa wakati ripoti ya tatizo inaundwa — ama ikiwasilishwa na mtumiaji kutoka kwenye dashibodi (source: "user") au kiotomatiki na ukadiriaji wa simu (source: "system"). Haiathiri utekelezaji.

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

Matukio ya simu za majaribio

test-call.completed

Hutumwa wakati uendeshaji wa simu ya majaribio unapofikia hali ya mwisho — completed au failed, ikijumuisha uendeshaji uliogonga hitilafu wakati wa kuanzishwa na ambao haukuwahi kuzalisha simu. Haiathiri utekelezaji. Ni muhimu kwa kuunganisha uendeshaji wa CI wa kundi kwenye mifumo yako ya gumzo/arifa.

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

Matukio ya arifa

alert.triggered

Hutumwa wakati sheria ya arifa yenye chaneli ya Wasilisha kwa webhook za msanidi iliyowezeshwa inapovuka kizingiti chake. Haizuii. Sheria huanzishwa mara moja kisha huheshimu kipindi chake cha kusubiri, hivyo ukiukaji unaoendelea hutoa tukio moja kwa kila dirisha la kipindi cha kusubiri.

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

Tazama mwongozo wa Arifa kwa ajili ya kuunda sheria, vipimo, vipindi vya kusubiri, na chaneli za barua pepe / Slack.

Yanayohusiana