Catalog de evenimente

Fiecare corp 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). Aceste evenimente sunt livrate î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 webhook-ul moștenit cu un singur URL: cererea de configurare telephony.incoming / web.incoming (numere în modul webhook și chei de widget, timeout de 10 s) și dispecerizarea instrumentelor în modul webhook. Răspunsul dumneavoastră modelează apelul în timp real.

Exemplele de payload de mai jos afișează plicul endpoint în ordinea sa de transmisie (chei sortate alfabetic: data, event_id, type); livrările moștenite conțin același data fără event_id.

Evenimente 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 solicitarea de configurare blocantă pe webhook-ul 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. Ne-blocant. Include transcrierea completă, URL-ul înregistrării ș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 acest eveniment este livrat; acoperă propriile dumneavoastră instrumente de funcție (nu instrumentele integrate, de bază de cunoștințe, de conexiune la aplicații 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 reușită sau {"status": <status>, "error": "<message>"} în caz de eșec.

`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 în builder. Livrările către endpoint sunt fire-and-forget pentru fiecare sesiune web. Cheile publicabile în mode="webhook" primesc suplimentar solicitarea de configurare blocantă pe webhook-ul vechi — această 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 literalul "web". Pentru sesiunile widget în modul webhook, to_number este gol (numărul agentului sesiunii este atribuit după configurare); pentru apelurile de testare a microfonului în builder, origin_domain și publishable_key_prefix sunt goale.

`web.complete`

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

Pe webhook-ul vechi cu un singur URL, apelurile de testare a microfonului în builder sunt raportate istoric ca telephony.complete — doar apelurile cu direction: "web" utilizează acolo tipul web.complete. Sistemul de endpointuri mapează atât apelurile web, cât și pe cele de testare la web.*. Payloadurile istorice pot conține valorile vechi direction, widget sau mic.

`web.tool`

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

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

Câmp	Tip	Descriere
`grade.id`	integer	ID-ul evaluării
`grade.score`	integer \| null	0–100
`grade.call_outcome`	string	`success`, `failure`, `unknown` sau `no_conversation`
`grade.summary`	string	Rezumat într-un paragraf
`grade.detected_issues`	array	Șiruri care descriu problemele găsite de evaluator
`grade.status`	string	Întotdeauna `completed` — doar rulările finalizate emit evenimente
`grade.grader_model`	string	Evaluatorul care a produs rezultatul (de exemplu, `heuristic-v1`)
`grade.graded_at`, `grade.created_at`	timestamp

Un apel poate fi evaluat de mai multe ori — o evaluare euristică rapidă este urmată adesea de o evaluare completă cu un model, după ce înregistrarea devine disponibilă, iar reevaluările manuale sunt posibile. Fiecare rulare finalizată emite propriul eveniment call.graded; considerați cel mai recent graded_at drept autoritativ.

`issue.reported`

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

Câmp	Tip	Descriere
`issue_report.severity`	string	`critical`, `warning` sau `info`
`issue_report.status`	string	`open` sau `resolved`
`issue_report.source`	string	`user` (raportat din tabloul de bord) sau `system` (creat prin evaluare)

Reevaluarea unui apel îi reconstruiește rapoartele de probleme generate de sistem, ceea ce reemite issue.reported pentru rapoartele recreate. Eliminați duplicatele după call_id + title dacă doriți o singură notificare pentru fiecare problemă de bază.

Evenimente pentru apeluri de test

`test-call.completed`

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

Câmp	Tip	Descriere
`test_call_run.target_type`	string	`agent` sau `phone_number`
`test_call_run.target_id`	integer	ID-ul agentului sau al numărului de telefon vizat de rulare, corespunzător cu `target_type`
`test_call_run.status`	string	`completed` sau `failed`
`test_call_run.call_id`	integer \| null	`null` când rularea a eșuat înainte de inițierea unui apel
`test_call_run.error_message`	string	Gol în caz de succes

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 de răcire, astfel încât o depășire 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"
}

Câmp	Tip	Descriere
`event_id` (din `data`)	UUID	ID-ul de declanșare al alertei — distinct de `event_id` de livrare din anvelopă
`rule_id`, `rule_name`	UUID, șir de caractere	Regula care s-a declanșat
`metric`	șir de caractere	`success_rate`, `failure_rate`, `avg_score`, `call_volume` sau `suite_regression`
`comparator`	șir de caractere	`lt`, `lte`, `gt` sau `gte`
`metric_value`	număr	Valoarea metricii în fereastra de evaluare atunci când regula s-a declanșat
`threshold`	număr	Pragul configurat
`window_hours`	număr întreg	Fereastra de evaluare retrospectivă
`fired_at`	marcaj temporal

Consultați ghidul despre alerte pentru crearea regulilor, a metricilor, a perioadelor de răcire și pentru canalele de e-mail / Slack.

Asociate

telephony.incoming / web.incoming

Încărcătura utilă blocantă pentru apelurile primite, la care trebuie să răspundeți.

telephony.complete / web.complete

Transcrierea și metricile de după apel.

Endpoint-uri webhook

Abonați un URL la un subset al acestor evenimente.

Instrumente pentru funcții

Cum sunt generate evenimentele telephony.tool / web.tool.

Webhooks

Function Tools

Evenimente apel

`telephony.incoming`

`telephony.complete`

`telephony.tool`

`web.incoming`

`web.complete`

`web.tool`

Evenimente de calitate

`call.graded`

`issue.reported`

Evenimente pentru apeluri de test

`test-call.completed`

Evenimente de alertă

`alert.triggered`

Asociate

telephony.incoming / web.incoming

telephony.complete / web.complete

Endpoint-uri webhook

Instrumente pentru funcții

​Evenimente apel

​telephony.incoming

​telephony.complete

​telephony.tool

​web.incoming

​web.complete

​web.tool

​Evenimente de calitate

​call.graded

​issue.reported

​Evenimente pentru apeluri de test

​test-call.completed

​Evenimente de alertă

​alert.triggered

​Asociate

telephony.incoming / web.incoming

telephony.complete / web.complete

Endpoint-uri webhook

Instrumente pentru funcții

Evenimente apel

`telephony.incoming`

`telephony.complete`

`telephony.tool`

`web.incoming`

`web.complete`

`web.tool`

Evenimente de calitate

`call.graded`

`issue.reported`

Evenimente pentru apeluri de test

`test-call.completed`

Evenimente de alertă

`alert.triggered`

Asociate