Catalog de evenimente

Toate tipurile de evenimente webhook emise de ThunderPhone.

Fiecare corp de webhook are un câmp type a cărui valoare este unul dintre tipurile de evenimente de pe această pagină. Când vă abonați la un endpoint, matricea events trebuie să conțină tipurile de evenimente dorite (sau să fie goală pentru a vă abona la toate — cu excepția evenimentelor per tură telephony.turn / web.turn, care sunt livrate doar către endpointurile care le menționează explicit).

Aceste evenimente sunt transmise în două stiluri:

• Livrările către endpointuri sunt întotdeauna notificări neblocante, cu reîncercări: răspundeți cu orice cod 2xx; plicul conține un event_id pentru deduplicare.
• Schimburile blocante au loc numai prin webhook-ul vechi cu un singur URL: cererea de configurare telephony.incoming / web.incoming (numere în modul webhook: 13 s, inclusiv o reîncercare; chei de widget în modul webhook: 10 s) și dispecerizarea instrumentelor în modul webhook. Răspunsul dumneavoastră modelează apelul în direct.

Exemplele de încărcături utile de mai jos afișează anvelopa endpointului în ordinea transmisă (chei sortate alfabetic: data, event_id, type); livrările moștenite conțin aceleași date data fără event_id.

Evenimente pentru apeluri#

telephony.incoming#

Trimis când un apel de intrare ajunge la unul dintre numerele dumneavoastră de telefon. Livrările către endpoint sunt notificări fără așteptarea unui răspuns trimise pentru fiecare apel de intrare, indiferent dacă numărul este configurat cu un agent sau cu un webhook. Numerele fără un agent alocat primesc suplimentar solicitarea de configurare blocantă pe webhookul vechi — consultați telephony.incoming / web.incoming pentru schema completă de solicitare / răspuns.

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

telephony.complete#

Trimis când se încheie un apel telefonic de intrare sau de ieșire. Nu blochează. Include transcrierea, URL-ul înregistrării când este disponibil și rezumatul facturării. Consultați telephony.complete / web.complete pentru schema încărcăturii utile.

telephony.tool#

Trimis după ce un apel telefonic invocă un instrument de funcție. Notificare de audit care nu blochează — instrumentul a fost deja executat când acest eveniment este livrat; acesta acoperă propriile instrumente de funcție și instrumentul integrat send_sms (nu alte instrumente integrate, instrumente din baza de cunoștințe, conexiuni de aplicații sau instrumente MCP). Pentru send_sms, atât arguments.to, cât și arguments.body sunt [REDACTED]. Transcrierile de finalizare le redactează, de asemenea; preluați conținutul și destinatarul din resursa SMS la nivel de organizație folosind message_id din răspuns.

{
  "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 este rezultatul executat: {"status": <http status>, "response": <your endpoint's JSON>} în caz de reușită sau {"status": <status>, "error": "<message>"} în caz de eșec.

telephony.turn#

Trimis în timp ce un apel telefonic este în desfășurare, o dată pentru fiecare tur care conține vorbire, pe măsură ce are loc — răspunsurile rostite ale agentului și tururile transcrise ale apelantului. Vă permite să urmăriți conversația în timp real prin webhookuri obișnuite, în loc să interogați periodic GET /v1/calls/{call_id}/transcript. Nu blochează.

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

Echivalentul pe canalul web al telephony.incoming, trimis când începe o sesiune a unui widget web sau un apel de test al microfonului în constructor. Livrările către endpoint sunt fără așteptarea unui răspuns pentru fiecare sesiune web. Cheile publicabile în mode="webhook" primesc suplimentar solicitarea de configurare blocantă pe webhookul vechi — acea solicitare blocantă are o structură diferită (origin_domain, publishable_key_prefix; fără numere de telefon). Consultați 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 este întotdeauna valoarea literală "web". Pentru sesiunile widgetului în modul webhook, to_number este gol (numărul agentului pentru sesiune este alocat după configurare); pentru apelurile de test ale microfonului în constructor, origin_domain și publishable_key_prefix sunt goale.

web.complete#

Echivalentul pe canalul web al telephony.complete, care acoperă apelurile widgetului web (direction: "web") și apelurile de test ale microfonului în constructor (direction: "test"). Nu blochează. Are aceeași structură a încărcăturii utile ca telephony.complete, plus origin_domain, cu from_number setat la "web".

web.tool#

Echivalentul pe canalul web al telephony.tool. Elementul data conține origin_domain în loc de from_number / to_number.

web.turn#

Echivalentul pe canalul web al telephony.turn, care acoperă apelurile widgetului web și apelurile de test ale microfonului în constructor. Are aceeași structură a încărcăturii utile, cu origin_domain în loc de from_number / to_number. La fel ca telephony.turn, necesită o abonare explicită — nu este niciodată livrat printr-o matrice events goală.

call.transfer_completed#

Trimis o dată per apel, cu rezultatul final al unui transfer de apel: un transfer direct sau puntea dintre persoane pe care o lasă în urmă un transfer asistat după ce agentul se retrage. Nu blochează execuția și este livrat numai către endpointuri (niciodată către webhookul moștenit cu un singur URL). Sosește după telephony.complete al apelului: după ce operatorul preia apelul sau transferul eșuează ori, atunci când ThunderPhone a creat o punte pentru apel, după încheierea punții.

{
  "data": {
    "agent_id": 12,
    "agent_name": "Front desk",
    "bridge_kind": "cold_fallback",
    "bridge_seconds": 255,
    "bridge_total_cents": 5,
    "call_id": 987654321,
    "destination": "+15555550102",
    "sip_status": 403,
    "transfer_outcome": "bridged"
  },
  "event_id": "5b0f6c1e-9d2a-5e7b-8c4d-1a2b3c4d5e6f",
  "type": "call.transfer_completed"
}

Aceleași valori se află pe obiectul apelului ca transfer_outcome, transfer_destination, transfer_sip_status, transfer_bridge_kind, transfer_bridge_seconds și transfer_bridge_total_cents. event_id este același la fiecare livrare pentru un apel, astfel încât un raport repetat nu produce niciodată un al doilea eveniment.

Evenimente SMS#

Evenimentele SMS descriu mesajele trimise prin contul Twilio sau Telnyx conectat al organizației. Corpul mesajului este omis, iar to este redactat. Preluați mesajul din domeniul organizației din GET /v1/sms/{message_id} atunci când aveți nevoie de conținutul sau de destinatarul acestuia.

sms.sent#

Trimis atunci când operatorul clientului acceptă o solicitare SMS de ieșire. Acesta nu este un raport de livrare pe dispozitiv.

{
  "data": {
    "accepted_at": "2026-09-19T15:42:10.113Z",
    "agent_id": 12,
    "call_id": 987654321,
    "created_at": "2026-09-19T15:42:09.901Z",
    "direction": "outbound",
    "error_code": null,
    "error_message": null,
    "from_number": "+15551234567",
    "id": "313a3117-827b-46e9-a01a-ac1493838724",
    "provider": "twilio",
    "provider_id": "SM0123456789abcdef0123456789abcdef",
    "segment_count": 1,
    "source": "agent_tool",
    "status": "accepted",
    "to": "[REDACTED]"
  },
  "event_id": "0ae347b4-1716-45bb-9a0e-b52373586e37",
  "type": "sms.sent"
}

sms.failed#

Trimis după o respingere permanentă din partea operatorului, după epuizarea reîncercărilor tranzitorii sau atunci când rezultatul este necunoscut în mod definitiv. error_code este un cod ThunderPhone stabil, iar error_message indică acțiunea clientului, atunci când este disponibilă. status: "unknown" înseamnă că operatorul ar fi putut accepta SMS-ul; reconciliați-l în jurnalul operatorului, deoarece ThunderPhone nu îl va retrimite automat.

sms.received#

Rezervat pentru suportul SMS de intrare. În versiunea curentă nu sunt emise evenimente sms.received. Configurarea webhook-urilor de intrare ale operatorului și verificarea semnăturii vor fi lansate separat.

Evenimente vocale#

Crearea vocilor personalizate este asincronă. Aceste evenimente neblocante vă permit să reacționați la un rezultat final, în loc să interogați repetat endpointul cu detaliile clonei.

voice.ready și voice.failed sunt livrate numai către un endpoint la nivelul întregii organizații cu events: []. Acestea nu pot fi selectate ca filtre explicite de evenimente.

voice.ready#

Trimis atunci când o voce personalizată finalizează procesarea și poate fi atribuită unui agent.

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

Trimis atunci când procesarea unei voci personalizate ajunge la o eroare permanentă.

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

Evenimente de calitate#

call.graded#

Trimis de fiecare dată când o rulare de evaluare AI se finalizează pentru un apel. Nu blochează execuția.

{
  "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…"
    },
    "report": null
  },
  "event_id": "7c1d2e3f-4a5b-4c6d-8e9f-0a1b2c3d4e5f",
  "type": "call.graded"
}

call.data_extracted#

Trimis de fiecare dată când extragerea structurată de date se finalizează cu succes, inclusiv după o reîncercare întârziată după telephony.complete / web.complete sau după o rerulare manuală prin POST /v1/calls/{call_id}/extract. Nu blochează execuția.

Într-un mod de extragere cu blocare, evenimentul de finalizare așteaptă în mod normal cel mult bugetul de extragere de 75 de secunde. Dacă procesul de lucru pentru extragere este pierdut, procesul de golire pentru finalizare din producție (la fiecare cinci minute) eliberează o finalizare al cărei blocking_deadline_at a trecut înainte de a începe o altă încercare de extragere. Un succes ulterior este livrat separat prin acest eveniment.

{
  "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": "<model id>",
    "summary": "Alex Morgan called to book a follow-up visit and confirmed Thursday, April 23."
  },
  "event_id": "4d79ef1d-c2b1-4ed6-85b8-8326bd2895ef",
  "type": "call.data_extracted"
}

campaign.completed#

Trimis o dată când o campanie trece de la running la completed, indiferent dacă programarea sa s-a încheiat sau toate contactele au ajuns în stări terminale. Reîncercările executorului nu emit un alt eveniment. Acest eveniment de ciclu de viață la nivel de organizație este livrat numai către endpointuri cu domeniu de organizație, nu către endpointuri cu domeniu de agent. Nu blochează execuția.

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

Cele patru numărători de rezultate sunt disjuncte și totalul lor este contacts_total: completed conține contactele reușite; no_answer conține contactele terminale eșuate/epuizate al căror rezultat final a fost lipsa răspunsului; failed conține toate celelalte contacte terminale eșuate/epuizate; iar remaining conține contacte în așteptare, programate sau apelate în prezent. Un contact care așteaptă o reîncercare este remaining, chiar și atunci când cea mai recentă încercare nu a primit răspuns. Apelurile în desfășurare sunt reconciliate înainte de instantaneul de finalizare emis o singură dată. started_at este începutul configurat al campaniei sau ora creării campaniei atunci când nu a fost configurat un început.

issue.reported#

Trimis când este creat un raport de problemă — fie trimis de un utilizator din tabloul de bord (source: "user"), fie creat automat prin evaluarea apelului (source: "system"). Nu blochează execuția.

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

Trimis când un model de problemă este trimis la ThunderPhone pentru revizuire de către personal: după Raportați la ThunderPhone sau când Remediere cu AI nu poate confirma o remediere de partea clientului și direcționează problema automat. Numai endpointurile la nivelul întregii organizații primesc acest eveniment.

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

Aceasta este o notificare, nu pachetul de dovezi. Utilizați cluster_id pentru a o corela cu modelul de problemă. Consultați Raportați la ThunderPhone.

Evenimente pentru apeluri de test#

test-call.completed#

Trimis atunci când o rulare de apel de test ajunge la o stare terminală — completed sau failed, inclusiv rulările care au eșuat la lansare și nu au generat niciodată un apel. Nu blochează execuția. Util pentru conectarea rulărilor CI în lot la sistemele dumneavoastră de chat/notificări.

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

Evenimente de alertă#

alert.triggered#

Trimis atunci când o regulă de alertă cu canalul Livrare către webhook-uri pentru dezvoltatori activat își depășește pragul. Nu blochează execuția. O regulă se declanșează o singură dată și apoi respectă perioada sa de așteptare, astfel încât o încălcare persistentă produce un eveniment pentru fiecare fereastră de așteptare.

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

Consultați ghidul despre alerte pentru crearea regulilor, metricilor, perioadelor de așteptare și canalelor de e-mail / Slack.

Evenimente de migrare#

migration.call.complete#

Trimis când se încheie un apel inițiat prin POST /v1/migrations/{id}/calls, indiferent de platforma care l-a preluat. Nu blochează. Ajunge la până la aproximativ 5 minute după încheierea apelului. data conține toate câmpurile din telephony.complete, plus un bloc migration. Un apel inițiat de ThunderPhone trimite, de asemenea, telephony.complete ca de obicei, cu același call_id. Un apel de pe cealaltă platformă care nu s-a încheiat după 2 ore sau a cărui migrare s-a finalizat ori și-a pierdut cheia înainte este trimis cu status: "unknown" și fără transcriere.

{
  "data": {
    "agent_id": 42,
    "agent_name": "Front desk",
    "billable_minutes": null,
    "billing_total_cents": null,
    "call_id": null,
    "direction": "outbound",
    "duration_seconds": 94,
    "end_reason": "user_hangup",
    "end_time": "2026-10-06T17:01:34+00:00",
    "extracted_data": null,
    "from_number": "+15551234567",
    "migration": {
      "arm": "vendor",
      "id": "5f0c2a9e-7b1d-4c3e-8a6f-2d9e1b4c7a30",
      "metadata": {
        "lead_id": "8812"
      },
      "routing_id": "9b2f8c1e-4d3a-4f6b-8e2d-1a7c5b9e0f34",
      "vendor": "retell",
      "vendor_call_id": "call_6a1f0e",
      "vendor_cost_usd": "0.1240"
    },
    "product": "",
    "recording_mode": "vendor",
    "recording_url": "https://…",
    "start_time": "2026-10-06T17:00:00+00:00",
    "status": "completed",
    "summary": "The callee booked a table for two on Thursday.",
    "thunderphone_retained_call_content": true,
    "to_number": "+14155552671",
    "transcripts": [
      {
        "content": "Hi Ada, this is Rosa's calling about your booking.",
        "role": "agent"
      },
      {
        "content": "Yes, Thursday works.",
        "role": "user"
      }
    ],
    "transfer_number": null,
    "unresolved_variables": [],
    "variables": {
      "first_name": "Ada"
    },
    "voice": ""
  },
  "event_id": "7c1e2f3a-4b5c-4d6e-8f7a-9b0c1d2e3f4a",
  "type": "migration.call.complete"
}

Pentru un apel vendor, ThunderPhone nu are date de facturare sau de extragere: billable_minutes, billing_total_cents și extracted_data sunt null, product și voice sunt goale, recording_mode este vendor, iar recording_url este linkul celeilalte platforme, când aceasta a furnizat unul.

migration.rollback#

Trimis atunci când trecerea treptată a unei migrări redirecționează automat toate apelurile înapoi către cealaltă platformă: 3 apeluri nu s-au conectat la ThunderPhone în 15 minute, 2 apeluri trimise către ThunderPhone s-au încheiat înainte ca agentul vocal să răspundă sau rata rezultatelor sarcinilor ThunderPhone a scăzut cu mai mult decât diferența configurată sub cea a celeilalte platforme. Nu blochează, o dată pentru fiecare revenire. După aceasta, ponderea ThunderPhone este de 0%, iar migrarea este pusă pe pauză până când cineva o reia din fila Migrare a agentului vocal. Încărcătura nu conține numere de telefon, transcrieri sau ID-uri de apel.

{
  "data": {
    "agent_id": 42,
    "agent_name": "Front desk",
    "dropped": 0,
    "migration_id": "5f0c2a9e-7b1d-4c3e-8a6f-2d9e1b4c7a30",
    "ours": {
      "graded": 20,
      "success_rate": 0.8
    },
    "ours_failed": 3,
    "ours_percent": 0,
    "previous_percent": 25,
    "reason": "ours_failed_burst",
    "rolled_back_at": "2026-10-10T12:05:00+00:00",
    "step": 1,
    "theirs": {
      "graded": 20,
      "success_rate": 0.8
    },
    "vendor": "retell"
  },
  "event_id": "3d1f6b2a-8c4e-5a7b-9d0e-2f1a3b4c5d6e",
  "type": "migration.rollback"
}

Resurse asociate#