Κατάλογος συμβάντων

Όλοι οι τύποι συμβάντων webhook που εκπέμπει το ThunderPhone.

Κάθε σώμα webhook έχει ένα πεδίο type του οποίου η τιμή είναι ένας από τους τύπους συμβάντων αυτής της σελίδας. Όταν εγγράφεστε σε ένα τελικό σημείο, ο πίνακας events πρέπει να περιέχει τους τύπους συμβάντων που θέλετε (ή να είναι κενός για εγγραφή σε όλα — εκτός από τα συμβάντα ανά σειρά telephony.turn / web.turn, τα οποία παραδίδονται μόνο σε τελικά σημεία που τα ονομάζουν ρητά).

Δύο τρόποι παράδοσης μεταφέρουν αυτά τα συμβάντα:

• Οι παραδόσεις σε τελικά σημεία είναι πάντα μη αποκλειστικές ειδοποιήσεις με επαναλήψεις: απαντήστε με οποιονδήποτε κωδικό 2xx· το περιτύλιγμα περιέχει ένα event_id για αποδιπλοποίηση.
• Οι αποκλειστικές ανταλλαγές εκτελούνται μόνο στο παλαιού τύπου webhook ενός URL: το αίτημα διαμόρφωσης telephony.incoming / web.incoming (αριθμοί σε λειτουργία webhook και κλειδιά widget, χρονικό όριο 10 δευτ.) και η δρομολόγηση εργαλείων σε λειτουργία webhook. Η απάντησή σας διαμορφώνει τη ζωντανή κλήση.

Τα παρακάτω παραδείγματα payload δείχνουν το περιτύλιγμα τελικού σημείου στη σειρά μετάδοσης (κλειδιά ταξινομημένα αλφαβητικά: data, event_id, type)· οι παλαιού τύπου παραδόσεις μεταφέρουν τα ίδια data χωρίς event_id.

Συμβάντα κλήσεων#

telephony.incoming#

Αποστέλλεται όταν μια εισερχόμενη κλήση φτάνει σε έναν από τους αριθμούς τηλεφώνου σας. Οι παραδόσεις σε endpoint είναι ειδοποιήσεις fire-and-forget που αποστέλλονται για κάθε εισερχόμενη κλήση, ανεξάρτητα από το αν ο αριθμός έχει ρυθμιστεί για πράκτορα ή webhook. Οι αριθμοί χωρίς εκχωρημένο πράκτορα λαμβάνουν επιπλέον το αίτημα διαμόρφωσης blocking στο παλαιότερο webhook — ανατρέξτε στο telephony.incoming / web.incoming για το πλήρες σχήμα αιτήματος / απόκρισης.

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

telephony.complete#

Αποστέλλεται όταν ολοκληρώνεται μια εισερχόμενη ή εξερχόμενη τηλεφωνική κλήση. Μη αποκλειστικό. Περιλαμβάνει την απομαγνητοφώνηση, το URL εγγραφής όταν είναι διαθέσιμο και τη σύνοψη χρέωσης. Ανατρέξτε στο telephony.complete / web.complete για το σχήμα ωφέλιμου φορτίου.

telephony.tool#

Αποστέλλεται αφού μια τηλεφωνική κλήση καλέσει ένα εργαλείο συνάρτησης. Μη αποκλειστική ειδοποίηση ελέγχου — το εργαλείο έχει ήδη εκτελεστεί όταν παραδίδεται αυτό το συμβάν· καλύπτει τα δικά σας εργαλεία συνάρτησης (όχι ενσωματωμένα εργαλεία, εργαλεία βάσης γνώσεων, σύνδεσης εφαρμογών ή 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 είναι το αποτέλεσμα που εκτελέστηκε: {"status": <http status>, "response": <your endpoint's JSON>} σε περίπτωση επιτυχίας ή {"status": <status>, "error": "<message>"} σε περίπτωση αποτυχίας.

telephony.turn#

Αποστέλλεται ενώ μια τηλεφωνική κλήση βρίσκεται σε εξέλιξη, μία φορά για κάθε σειρά ομιλίας καθώς συμβαίνει — τις προφορικές ολοκληρώσεις του πράκτορα και τις απομαγνητοφωνημένες σειρές του καλούντος. Σας επιτρέπει να παρακολουθείτε τη ζωντανή συνομιλία μέσω απλών webhooks αντί να κάνετε polling στο GET /v1/calls/{call_id}/transcript. Μη αποκλειστικό.

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

Το ισοδύναμο του telephony.incoming για το κανάλι web, αποστέλλεται όταν ξεκινά μια συνεδρία widget web ή μια δοκιμαστική κλήση μικροφώνου του builder. Οι παραδόσεις σε endpoint είναι fire-and-forget για κάθε συνεδρία web. Τα δημοσιεύσιμα κλειδιά σε mode="webhook" λαμβάνουν επιπλέον το αίτημα διαμόρφωσης blocking στο παλαιότερο webhook — αυτό το αίτημα blocking έχει διαφορετική μορφή (origin_domain, publishable_key_prefix· χωρίς αριθμούς τηλεφώνου). Ανατρέξτε στο 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 είναι πάντα η κυριολεκτική τιμή "web". Για συνεδρίες widget σε λειτουργία webhook, το to_number είναι κενό (ο αριθμός πράκτορα της συνεδρίας εκχωρείται μετά τη διαμόρφωση)· για δοκιμαστικές κλήσεις μικροφώνου του builder, τα origin_domain και publishable_key_prefix είναι κενά.

web.complete#

Το ισοδύναμο του telephony.complete για το κανάλι web, που καλύπτει κλήσεις widget web (direction: "web") και δοκιμαστικές κλήσεις μικροφώνου του builder (direction: "test"). Μη αποκλειστικό. Έχει την ίδια μορφή ωφέλιμου φορτίου με το telephony.complete, καθώς και το origin_domain, με το from_number ορισμένο σε "web".

web.tool#

Το ισοδύναμο του telephony.tool για το κανάλι web. Το data περιέχει το origin_domain αντί για from_number / to_number.

web.turn#

Το ισοδύναμο για το κανάλι web του telephony.turn, που καλύπτει κλήσεις widget web και δοκιμαστικές κλήσεις μικροφώνου του builder. Ίδια μορφή ωφέλιμου φορτίου, με origin_domain αντί για from_number / to_number. Όπως το telephony.turn, απαιτεί ρητή εγγραφή — δεν παραδίδεται ποτέ μέσω ενός κενού πίνακα events.

Συμβάντα φωνής#

Η δημιουργία προσαρμοσμένης φωνής είναι ασύγχρονη. Αυτά τα μη αποκλειστικά συμβάντα σάς επιτρέπουν να αντιδράτε σε ένα τελικό αποτέλεσμα αντί να υποβάλλετε επαναλαμβανόμενα αιτήματα στο τελικό σημείο λεπτομερειών κλώνου.

Τα voice.ready και voice.failed παραδίδονται μόνο σε ένα τελικό σημείο για ολόκληρο τον οργανισμό με events: []. Δεν μπορούν να επιλεγούν ως ρητά φίλτρα συμβάντων.

voice.ready#

Αποστέλλεται όταν μια προσαρμοσμένη φωνή ολοκληρώνει την επεξεργασία και μπορεί να εκχωρηθεί σε έναν πράκτορα.

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

Αποστέλλεται όταν η επεξεργασία προσαρμοσμένης φωνής καταλήγει σε μόνιμη αποτυχία.

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

Συμβάντα ποιότητας#

call.graded#

Αποστέλλεται κάθε φορά που ολοκληρώνεται μια εκτέλεση αξιολόγησης AI για μια κλήση. Δεν προκαλεί αποκλεισμό.

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

call.data_extracted#

Αποστέλλεται κάθε φορά που ολοκληρώνεται επιτυχώς η εξαγωγή δομημένων δεδομένων, συμπεριλαμβανομένης μιας καθυστερημένης επανάληψης μετά από telephony.complete / web.complete ή μιας μη αυτόματης επανεκτέλεσης μέσω POST /v1/calls/{call_id}/extract. Δεν προκαλεί αποκλεισμό.

Σε λειτουργία εξαγωγής με αποκλεισμό, το συμβάν ολοκλήρωσης συνήθως δεν αναμένει περισσότερο από τον προϋπολογισμό εξαγωγής των 75 δευτερολέπτων. Αν χαθεί η διεργασία worker εξαγωγής, η εκκαθάριση οριστικοποίησης παραγωγής, κάθε πέντε λεπτά, απελευθερώνει μια ολοκλήρωση της οποίας το blocking_deadline_at έχει παρέλθει πριν ξεκινήσει άλλη προσπάθεια εξαγωγής. Μια μεταγενέστερη επιτυχία παραδίδεται ξεχωριστά ως αυτό το συμβάν.

{
  "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": "gemini-2.5-flash"
  },
  "event_id": "4d79ef1d-c2b1-4ed6-85b8-8326bd2895ef",
  "type": "call.data_extracted"
}

campaign.completed#

Αποστέλλεται μία φορά όταν μια καμπάνια μεταβαίνει από running σε completed, είτε έληξε το πρόγραμμά της είτε όλες οι επαφές έφτασαν σε τελικές καταστάσεις. Οι επαναλήψεις του runner δεν εκπέμπουν άλλο συμβάν. Αυτό το συμβάν κύκλου ζωής σε επίπεδο οργανισμού παραδίδεται μόνο σε τερματικά σημεία με εμβέλεια οργανισμού, όχι σε τερματικά σημεία με εμβέλεια πράκτορα. Δεν προκαλεί αποκλεισμό.

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

Οι τέσσερις μετρήσεις αποτελέσματος δεν αλληλεπικαλύπτονται και αθροίζονται σε contacts_total: το completed περιέχει επιτυχημένες επαφές· το no_answer περιέχει τελικές αποτυχημένες/εξαντλημένες επαφές των οποίων το τελικό αποτέλεσμα ήταν μη απάντηση· το failed περιέχει όλες τις άλλες τελικές αποτυχημένες/εξαντλημένες επαφές· και το remaining περιέχει εκκρεμείς, προγραμματισμένες ή κλήσεις που βρίσκονται σε εξέλιξη. Μια επαφή που αναμένει επανάληψη είναι remaining, ακόμη και όταν η πιο πρόσφατη προσπάθειά της ήταν μη απάντηση. Οι κλήσεις σε εξέλιξη συμφωνούνται πριν από το στιγμιότυπο ολοκλήρωσης που εκπέμπεται μία φορά. Το started_at είναι η διαμορφωμένη έναρξη της καμπάνιας ή η ώρα δημιουργίας της καμπάνιας όταν δεν είχε διαμορφωθεί έναρξη.

issue.reported#

Αποστέλλεται όταν δημιουργείται μια αναφορά ζητήματος — είτε υποβάλλεται από έναν χρήστη από τον πίνακα ελέγχου (source: "user") είτε αυτόματα από την αξιολόγηση κλήσης (source: "system"). Δεν προκαλεί αποκλεισμό.

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

Αποστέλλεται όταν ένα μοτίβο ζητημάτων αποστέλλεται στο ThunderPhone για έλεγχο από το προσωπικό: μετά την επιλογή Αναφορά στο ThunderPhone, ή όταν το Fix with AI δεν μπορεί να επιβεβαιώσει μια διόρθωση από την πλευρά του πελάτη και δρομολογεί το ζήτημα αυτόματα. Μόνο τερματικά σημεία σε επίπεδο οργανισμού λαμβάνουν αυτό το συμβάν.

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

Αυτή είναι μια ειδοποίηση, όχι το πακέτο αποδεικτικών στοιχείων. Χρησιμοποιήστε το cluster_id για να το συσχετίσετε με το μοτίβο ζητημάτων. Δείτε Αναφορά στο ThunderPhone.

Συμβάντα δοκιμαστικών κλήσεων#

test-call.completed#

Αποστέλλεται όταν μια εκτέλεση δοκιμαστικής κλήσης φτάνει σε τελική κατάσταση — completed ή failed, συμπεριλαμβανομένων εκτελέσεων που απέτυχαν κατά την εκκίνηση και δεν πραγματοποίησαν ποτέ κλήση. Δεν αποκλείει άλλες διεργασίες. Χρήσιμο για τη σύνδεση μαζικών εκτελέσεων CI με τα συστήματα συνομιλιών/ειδοποιήσεών σας.

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

Συμβάντα ειδοποιήσεων#

alert.triggered#

Αποστέλλεται όταν ένας κανόνας ειδοποίησης με ενεργοποιημένο το κανάλι Παράδοση σε webhooks προγραμματιστή υπερβαίνει το όριό του. Δεν αποκλείει άλλες διεργασίες. Ένας κανόνας ενεργοποιείται μία φορά και έπειτα τηρεί την περίοδο αναμονής του, επομένως μια συνεχής υπέρβαση παράγει ένα συμβάν ανά παράθυρο περιόδου αναμονής.

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

Δείτε τον οδηγό ειδοποιήσεων για τη δημιουργία κανόνων, μετρήσεων, περιόδων αναμονής και καναλιών email / Slack.

Σχετικά#