Katalogi ya Matukio

Aina zote za matukio ya webhook ambayo ThunderPhone hutuma.

Kila mwili wa webhook una sehemu ya type ambayo thamani yake ni mojawapo ya aina za matukio kwenye ukurasa huu. Unapojisajili kwa endpoint, safu ya events lazima iwe na aina za matukio unazotaka (au iwe tupu ili kujisajili kwa kila tukio — isipokuwa matukio ya kila zamu telephony.turn / web.turn, ambayo huwasilishwa tu kwa endpoint zinazoyataja wazi).

Mitindo miwili ya uwasilishaji hutuma matukio haya:

• Uwasilishaji wa endpoint daima ni arifa zisizozuia zenye majaribio upya: jibu kwa 2xx yoyote; bahasha ina event_id kwa ajili ya kuondoa nakala.
• Mabadilishano yanayozuia hufanyika tu kwenye webhook ya urithi yenye URL moja: ombi la usanidi la telephony.incoming / web.incoming (namba 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 ya moja kwa moja.

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

Matukio ya simu#

telephony.incoming#

Hutumwa wakati simu inayoingia inapofikia mojawapo ya namba zako za simu. Uwasilishaji wa endpoint ni arifa za kutuma-na-kusahau zinazotumwa kwa kila simu inayoingia, iwe namba imesanidiwa kwa ejenti au webhook. Namba zisizo na ejenti aliyepewa pia hupokea ombi la usanidi la kuzuia kwenye webhook ya urithi — tazama 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 telephony inayoingia au inayotoka inapomalizika. Haizuii. Inajumuisha transkripti, URL ya rekodi inapopatikana, na muhtasari wa malipo. Tazama telephony.complete / web.complete kwa schema ya payload.

telephony.tool#

Hutumwa baada ya simu ya telephony kuita zana ya function. Arifa ya ukaguzi isiyozuia — zana tayari imetekelezwa tukio hili linapowasilishwa; inahusu zana zako binafsi 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>} yakifanikiwa, au {"status": <status>, "error": "<message>"} yakishindwa.

telephony.turn#

Hutumwa simu ya telephony ikiwa inaendelea, mara moja kwa kila zamu yenye sauti inapotokea — majibu yanayosemwa ya ejenti na zamu zilizonakiliwa za mpigaji simu. Hukuwezesha kufuatilia mazungumzo ya moja kwa moja kupitia webhook za kawaida badala ya kufanya polling GET /v1/calls/{call_id}/transcript. Haizuii.

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

Sawa na telephony.incoming kwa chaneli ya wavuti, hutumwa wakati kipindi cha wijeti ya wavuti au simu ya majaribio ya mic ya builder inapoanza. Uwasilishaji wa endpoint ni wa kutuma-na-kusahau kwa kila kipindi cha wavuti. Funguo zinazoweza kuchapishwa katika mode="webhook" pia hupokea ombi la usanidi la kuzuia kwenye webhook ya urithi — ombi hilo la kuzuia lina muundo tofauti (origin_domain, publishable_key_prefix; hakuna namba za simu). Tazama 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 ni thamani halisi "web". Kwa vipindi vya wijeti katika hali ya webhook, to_number ni tupu (namba ya ejenti ya kipindi hupewa baada ya usanidi); kwa simu za majaribio ya mic ya builder, origin_domain na publishable_key_prefix ni tupu.

web.complete#

Sawa na telephony.complete kwa chaneli ya wavuti, ikijumuisha simu za wijeti ya wavuti (direction: "web") na simu za majaribio ya mic 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 kwa chaneli ya wavuti. data hubeba origin_domain badala ya from_number / to_number.

web.turn#

Sawa na telephony.turn kwa chaneli ya wavuti, ikijumuisha simu za wijeti ya wavuti na simu za majaribio ya mic ya builder. Ina muundo sawa wa payload, ikiwa na origin_domain badala ya from_number / to_number. Kama telephony.turn, inahitaji usajili mahususi — haiwasilishwi kamwe kupitia mkusanyiko tupu wa events.

Matukio ya sauti#

Uundaji wa sauti maalum hufanyika kwa njia isiyosubiri. Matukio haya yasiyozuia hukuruhusu kuchukua hatua kulingana na matokeo ya mwisho badala ya kuuliza mara kwa mara endpoint ya maelezo ya kloni.

voice.ready na voice.failed hutumwa tu kwenye endpoint ya shirika zima yenye events: []. Hayawezi kuchaguliwa kama vichujio mahususi vya matukio.

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 utekelezaji wa ukadiriaji wa AI unapokamilika kwa simu. Hautazuia 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"
}

campaign.completed#

Hutumwa mara moja kampeni inapohama kutoka running hadi completed, iwe ratiba yake imeisha au mawasiliano yote yamefikia hali za mwisho. Majaribio ya kurudia ya runner hayatumi tukio lingine. Tukio hili la mzunguko wa maisha katika kiwango cha shirika hutolewa kwa endpoints zenye upeo wa shirika pekee, si endpoints zenye upeo wa ejenti. Hautazuia utekelezaji.

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

Hesabu nne za matokeo hazipishani na jumla yake ni contacts_total: completed ina mawasiliano yaliyofaulu; no_answer ina mawasiliano yaliyoshindwa au kufikia kikomo cha majaribio ambayo matokeo yao ya mwisho hayakuwa jibu; failed ina mawasiliano mengine yote yaliyoshindwa au kufikia kikomo cha majaribio; na remaining ina mawasiliano yanayosubiri, yaliyopangwa, au yanayopigiwa simu kwa sasa. Mawasiliano yanayosubiri jaribio la kurudia ni remaining, hata kama jaribio lake la karibuni halikujibiwa. Simu zinazoendelea hupatanishwa kabla ya muhtasari wa ukamilishaji unaotumwa mara moja pekee. started_at ni mwanzo wa kampeni uliosanidiwa, au muda wa kuundwa kwa kampeni wakati hakuna mwanzo uliosanidiwa.

issue.reported#

Hutumwa ripoti ya tatizo inapoundwa — iwe imewasilishwa na mtumiaji kutoka dashibodi (source: "user") au kiotomatiki na ukadiriaji wa simu (source: "system"). Hautazuia 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"
}

issue.escalated#

Hutumwa muundo wa tatizo unapotumwa kwa ThunderPhone ili wafanyakazi wapitie: baada ya Ripoti kwa ThunderPhone, au wakati Rekebisha kwa AI haiwezi kuthibitisha urekebishaji wa upande wa mteja na kuelekeza tatizo kiotomatiki. Endpoints za shirika zima pekee hupokea tukio hili.

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

Hii ni arifa, si kifurushi cha ushahidi. Tumia cluster_id kuihusisha na muundo wa tatizo. Tazama Ripoti kwa ThunderPhone.

Matukio ya simu za majaribio#

test-call.completed#

Hutumwa wakati utekelezaji wa simu ya majaribio unafikia hali ya mwisho — completed au failed, ikijumuisha utekelezaji uliofeli wakati wa kuanzishwa na haukuwahi kutoa simu. Haizuii. Ni muhimu kwa kuunganisha utekelezaji 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 tahadhari#

alert.triggered#

Hutumwa wakati sheria ya tahadhari yenye kituo cha Wasilisha kwa webhook za msanidi kilichowashwa inapovuka kizingiti chake. Haizuii. Sheria huwashwa mara moja kisha huheshimu kipindi chake cha kusubiri, hivyo ukiukaji endelevu 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 Tahadhari ili kuunda sheria, vipimo, vipindi vya kusubiri, na vituo vya barua pepe / Slack.

Yanayohusiana#