Webhooks

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 numai endpointurilor care le menționează explicit).

Aceste evenimente sunt transmise în două stiluri:

• Livrările către endpoint 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 rulează numai pe webhookul moștenit cu un singur URL: cererea de configurare telephony.incoming / web.incoming (numere în modul webhook și chei de widget, expirare după 10 s) și dispecerizarea instrumentelor în modul webhook. Răspunsul dumneavoastră modelează apelul activ.

Exemplele de sarcini utile de mai jos arată plicul endpointului în ordinea sa de transmitere (chei sortate alfabetic: data, event_id, type); livrările moștenite conțin aceleași data fără event_id.

Evenimente de apel#

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 fire-and-forget trimise pentru fiecare apel de intrare, indiferent dacă numărul este configurat pentru agent sau pentru webhook. Numerele fără un agent atribuit primesc suplimentar cererea de configurare blocantă pe webhookul legacy — consultați telephony.incoming / web.incoming pentru schema completă de cerere / 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. Ne-blocant. Include transcrierea, URL-ul înregistrării când este disponibil și rezumatul facturării. Consultați telephony.complete / web.complete pentru schema payloadului.

telephony.tool#

Trimis după ce un apel telefonic invocă un instrument de funcție. Notificare de audit ne-blocantă — instrumentul a fost deja executat când este livrat acest eveniment; acoperă propriile dumneavoastră instrumente de funcție (nu instrumente integrate, de bază de cunoștințe, de conexiune la aplicație sau 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 este rezultatul executat: {"status": <http status>, "response": <your endpoint's JSON>} în caz de succes 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 de 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 direct prin webhookuri simple, în loc să interogați periodic GET /v1/calls/{call_id}/transcript. Ne-blocant.

{
  "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 pentru canalul web al telephony.incoming, trimis când începe o sesiune de widget web sau un apel de testare a microfonului din builder. Livrările către endpoint sunt fire-and-forget pentru fiecare sesiune web. Cheile publicabile în mode="webhook" primesc suplimentar cererea de configurare blocantă pe webhookul legacy — acea cerere blocantă are o formă 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 literalul "web". Pentru sesiunile de widget în modul webhook, to_number este gol (numărul agentului sesiunii este atribuit după configurare); pentru apelurile de testare a microfonului din builder, origin_domain și publishable_key_prefix sunt goale.

web.complete#

Echivalentul pentru canalul web al telephony.complete, care acoperă apelurile din widgetul web (direction: "web") și apelurile de testare a microfonului din builder (direction: "test"). Ne-blocant. Aceeași formă de payload ca telephony.complete, plus origin_domain, cu from_number setat la "web".

web.tool#

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

web.turn#

Echivalentul pentru canalul web al telephony.turn, care acoperă apelurile din widgetul web și apelurile de testare a microfonului din builder. Aceeași formă de payload, cu origin_domain în loc de from_number / to_number. La fel ca telephony.turn, necesită o abonare explicită — nu este livrat niciodată printr-un array events gol.

Evenimente vocale#

Crearea unei voci 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#

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

issue.reported#

Trimis când este creat un raport de problemă — fie depus de un utilizator din tabloul de bord (source: "user"), fie automat de 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"
}

Evenimente pentru apeluri de test#

test-call.completed#

Trimis când o rulare de apel de test atinge o stare terminală — completed sau failed, inclusiv rulările care au eșuat la lansare și nu au produs 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 webhookuri de dezvoltator activat își depășește pragul. Nu blochează execuția. O regulă se declanșează o dată, apoi respectă perioada de răcire, astfel încât o încălcare susținută produce un eveniment pentru fiecare fereastră de răcire.

{
  "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 pentru alerte pentru crearea regulilor, a metricilor, a perioadelor de răcire și pentru canalele de e-mail / Slack.

Asociate#