--- title: "Δυναμική διαμόρφωση ανά κλήση" description: "Επιλέξτε τον πράκτορα που απαντά — ή επαναδιατυπώστε το prompt και τις ρυθμίσεις του — ξεχωριστά για κάθε εισερχόμενη κλήση, με βάση προσαρμοσμένη λογική σε ένα webhook που ελέγχετε." --- Από προεπιλογή, σε κάθε αριθμό τηλεφώνου και δημοσιεύσιμο κλειδί έχει αντιστοιχιστεί ένας στατικός πράκτορας. Όταν χρειάζεστε προσαρμογή **ανά καλούντα** ή **ανά επισκέπτη** — δρομολόγηση VIP, περιβάλλον συνδεδεμένου χρήστη, δοκιμές προτροπών A/B — μεταβείτε σε λειτουργία webhook και αφήστε τον διακομιστή σας να αποφασίσει. ## Πώς λειτουργεί 1. Εγγράφεστε στο συμβάν [`telephony.incoming`](/el/webhooks/events) (τηλέφωνο) ή [`web.incoming`](/el/webhooks/events) (widget). Και τα δύο είναι **δεσμευτικά** webhooks: το ThunderPhone περιμένει έως 10 δευτερόλεπτα για την απάντησή σας πριν συνεχίσει την κλήση. 2. Το ThunderPhone σάς στέλνει `{call_id, from_number, to_number}` (οι συνεδρίες widget περιλαμβάνουν πεδία ειδικά για widget αντί για αριθμούς — δείτε το [σχήμα αιτήματος](/el/webhooks/call-incoming)). 3. Ο διακομιστής σας απαντά με μια διαμόρφωση πράκτορα (προτροπή, φωνή, προϊόν, εργαλεία). Το ThunderPhone χρησιμοποιεί αυτή τη διαμόρφωση για την κλήση. 4. Αν επιστρέψετε `{}`, προκύψει χρονικό όριο ή σφάλμα, χρησιμοποιείται ως εναλλακτική ο στατικά αντιστοιχισμένος πράκτορας. Ασφαλής προεπιλογή. Λειτουργεί με τον ίδιο τρόπο για τηλεφωνικές κλήσεις (`telephony.incoming`) και συνεδρίες widget (`web.incoming`), είτε παραδίδονται σε τελικό σημείο webhook είτε στο παλαιότερο webhook μίας διεύθυνσης URL. **Δεν αναπαράγεται ανακοίνωση συγκατάθεσης του ThunderPhone σε κλήσεις που διαμορφώνονται μέσω ενσωματωμένου webhook.** Αυτή η διαδρομή παρακάμπτει την ανακοίνωση έναρξης κλήσης σε επίπεδο πράκτορα και εξαιρείται ρητά από το πλαίσιο ανακοινώσεων συγκατάθεσης του ThunderPhone (Όροι Παροχής Υπηρεσιών, ενότητα «Ηχογράφηση και συγκατάθεση»). Ο οργανισμός σας είναι υπεύθυνος για όλες τις ειδοποιήσεις και συγκαταθέσεις σχετικά με ηχογράφηση, παρακολούθηση, συμμετοχή AI και αναγνώριση καλούντος σε αυτές τις κλήσεις. Παρέχετέ τες στη δική σας ροή — για παράδειγμα στο αρχικό σενάριο της προτροπής — πριν ενεργοποιήσετε τη λειτουργία ενσωματωμένου webhook. Μια απάντηση webhook που αναφέρεται σε αποθηκευμένο `agent_id` χρησιμοποιεί την κανονική πολιτική ηχογράφησης και γνωστοποίησης αυτού του πράκτορα. ## 1. Διαμορφώστε τον προορισμό webhook Για αριθμούς τηλεφώνου, εγγράψτε το τελικό σημείο σας στο `telephony.incoming`: ```bash curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints \ -H "Authorization: Bearer sk_live_YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "label": "Prod call-incoming", "url": "https://example.com/thunderphone/incoming", "events": ["telephony.incoming"] }' ``` Η απάντηση περιλαμβάνει ένα `secret` μίας χρήσης — αποθηκεύστε το· θα το χρησιμοποιήσετε για επαλήθευση υπογραφής. Για συνεδρίες widget, δημιουργήστε ένα δημοσιεύσιμο κλειδί σε `mode="webhook"` με τη διεύθυνση URL του τελικού σημείου σας ενσωματωμένη: ```bash curl -X POST https://api.thunderphone.com/v1/publishable-key \ -H "Authorization: Bearer sk_live_YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Dynamic widget", "mode": "webhook", "webhook_url": "https://example.com/thunderphone/widget-incoming", "allowed_domains": ["example.com"] }' ``` Το widget θα στέλνει POST σε αυτή τη διεύθυνση URL σε κάθε έναρξη συνεδρίας. ## 2. Υλοποιήστε τον χειριστή Τρεις πρακτικοί κανόνες: - **Επαληθεύετε την υπογραφή** σε κάθε αίτημα (βλ. [Επαλήθευση υπογραφών webhook](/el/guides/verify-webhook-signatures)). Μην το παραλείπετε στο περιβάλλον ανάπτυξης — υλοποιήστε το σωστά μία φορά και επαναχρησιμοποιήστε το. - **Απαντάτε γρήγορα**. Τα δέκα δευτερόλεπτα είναι το αυστηρό όριο και κάθε δευτερόλεπτο είναι νεκρός χρόνος για τον καλούντα. Κάντε αναζητήσεις στη βάση δεδομένων αν χρειάζεται, αλλά μην καλείτε κατάντη LLM συγχρονισμένα — αν θέλετε δυναμική δημιουργία προτροπών, προϋπολογίστε και αποθηκεύστε στην κρυφή μνήμη. - **Εφαρμόζετε καθαρή εναλλακτική λύση**. Κάθε μη αναμενόμενη κατάσταση πρέπει να επιστρέφει `{}`, ώστε ο στατικά εκχωρημένος πράκτορας να διαχειρίζεται την κλήση. ```python FastAPI import hashlib import hmac import json import os from fastapi import FastAPI, HTTPException, Request app = FastAPI() SECRET = os.environ["THUNDERPHONE_WEBHOOK_SECRET"] def verify(body: bytes, sig: str) -> bool: expected = hmac.new(SECRET.encode(), body, hashlib.sha256).hexdigest() return hmac.compare_digest(expected, sig or "") @app.post("/thunderphone/incoming") async def incoming(request: Request): body = await request.body() if not verify(body, request.headers.get("X-ThunderPhone-Signature", "")): raise HTTPException(401) event = json.loads(body) if event["type"] not in ("telephony.incoming", "web.incoming"): return {} # fall back to default caller = event["data"]["from_number"] # Cheap DB lookup: is this a known VIP? customer = lookup_customer(caller) if customer and customer.tier == "vip": return { "prompt": f"You are a VIP concierge for {customer.name}. Be proactive…", "voice": "john", "product": "storm-base", } return {} # default agent handles non-VIPs def lookup_customer(phone: str): # ... your CRM integration ... pass ``` ```javascript Express import crypto from "node:crypto"; import express from "express"; const app = express(); const SECRET = process.env.THUNDERPHONE_WEBHOOK_SECRET; function verify(body, sig) { const expected = crypto.createHmac("sha256", SECRET).update(body).digest("hex"); return sig && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig)); } app.post( "/thunderphone/incoming", express.raw({ type: "application/json" }), async (req, res) => { if (!verify(req.body, req.header("X-ThunderPhone-Signature"))) { return res.sendStatus(401); } const event = JSON.parse(req.body.toString("utf8")); const IMPORTANT_TYPES = new Set([ "telephony.incoming", "web.incoming", ]); if (!IMPORTANT_TYPES.has(event.type)) return res.json({}); const customer = await lookupCustomer(event.data.from_number); if (customer?.tier === "vip") { return res.json({ prompt: `You are a VIP concierge for ${customer.name}. Be proactive…`, voice: "john", product: "storm-base", }); } res.json({}); // fall back to default agent }, ); ``` ## 3. Σχήμα απόκρισης Το σώμα της απόκρισης αντιστοιχεί ακριβώς στο [σχήμα απόκρισης εισερχόμενης κλήσης](/el/webhooks/call-incoming). Τα πεδία που χρησιμοποιούνται συχνότερα: | Πεδίο | Τύπος | Περιγραφή | |-------|------|-------------| | `prompt` | συμβολοσειρά (υποχρεωτικό) | Προτροπή συστήματος για τον πράκτορα | | `voice` | συμβολοσειρά (υποχρεωτικό) | Αναγνωριστικό φωνής από το [`GET /v1/voices`](/api-reference/agents#voices) | | `product` | συμβολοσειρά | Προεπιλογή: `spark` | | `background_track` | συμβολοσειρά \| null | Αναγνωριστικό ήχου περιβάλλοντος | | `acknowledgement_prompt_mode` | συμβολοσειρά | `auto` ή `manual` (μόνο Storm με επιβεβαίωση) | | `acknowledgement_prompt` | συμβολοσειρά | Υποχρεωτικό όταν η λειτουργία είναι `manual` | | `tools` | πίνακας | Ενσωματωμένα σχήματα εργαλείων συναρτήσεων — δείτε [Εργαλεία συναρτήσεων](/el/tools/overview) | Η σειρά εκφώνησης ανά κλήση και το `max_hold_seconds` δεν είναι διαθέσιμα στην απόκριση του άγκιστρου ιστού. Ορίστε τα στον [πράκτορα](/api-reference/agents) που αναφέρετε. ### Διατηρήστε έναν αποθηκευμένο πράκτορα και παρέχετε μεταβλητές Επιστρέψτε `{"agent_id": 12, "variables": {"name": "Ada"}}` για να χρησιμοποιήσετε τον αποθηκευμένο πράκτορα του οργανισμού με δεδομένα ανά κλήση. Η προτροπή του μπορεί να περιέχει `{{name}}` ή `{{name|Friend}}`. Οι μεταβλητές του άγκιστρου ιστού συγχωνεύονται πάνω από τις μεταβλητές επιπέδου αιτήματος· το null χρησιμοποιεί την προεπιλεγμένη τιμή του συμβόλου κράτησης ή κενό κείμενο εάν δεν παρέχεται καμία. Οι τελικές τιμές και τα μη επιλυμένα ονόματα εμφανίζονται στις λεπτομέρειες κλήσης και στα άγκιστρα ιστού ολοκλήρωσης. Οι αποκρίσεις αποθηκευμένου πράκτορα δέχονται μόνο `agent_id` και `variables`. Εάν υπάρχει το `prompt`, η απόκριση χρησιμοποιεί ενσωματωμένη διαμόρφωση και αγνοεί το `agent_id` (συμπεριλαμβανομένων μεταδεδομένων null ή μη ακέραιου αριθμού)· η ενσωματωμένη προτροπή πρέπει και πάλι να είναι έγκυρη. Οι αποκρίσεις ενσωματωμένης διαμόρφωσης μπορούν επίσης να περιλαμβάνουν `variables`. Οι αποκρίσεις αποθηκευμένου πράκτορα χρησιμοποιούν τη δημοσιευμένη κατανομή A/B του πράκτορα τόσο σε τηλεφωνικές κλήσεις όσο και σε κλήσεις γραφικού στοιχείου και, στη συνέχεια, αποδίδουν τις μεταβλητές. Δείτε τις [μεταβλητές κλήσης](/el/guides/call-variables) για όρια και υποστήριξη API συνεδρίας. Η διαμόρφωση αποκλεισμού προέρχεται από το παλαιό URL αριθμού τηλεφώνου/οργανισμού ή από ένα κλειδί γραφικού στοιχείου σε λειτουργία άγκιστρου ιστού· τα εισερχόμενα συμβάντα τελικού σημείου-συστήματος είναι μόνο ειδοποιήσεις. ## Πρότυπα ### Πλαίσιο συνδεδεμένου χρήστη Στα γραφικά στοιχεία σε λειτουργία άγκιστρου ιστού, η σελίδα του επισκέπτη γνωρίζει ήδη ποιος είναι. Καλέστε το άγκιστρο ιστού σας με μια παράμετρο συμβολοσειράς ερωτήματος που το SDK του γραφικού στοιχείου προωθεί (`?customer_id=123`) και αναζητήστε τον πελάτη στην πλευρά του διακομιστή. ### Κυκλοφορία προτροπών A/B Πριν το υλοποιήσετε χειροκίνητα, σημειώστε ότι το ThunderPhone διαθέτει εγγενή λειτουργία [Πειραμάτων](/el/guides/concepts) (`/dashboard/experiments` και την καρτέλα **A/B** του εργαλείου δημιουργίας πρακτόρων) που ορίζει παραλλαγές, κατανέμει την κίνηση και συγκρίνει αποτελέσματα ανά παραλλαγή — δεν απαιτείται άγκιστρο ιστού. Εάν χρειάζεστε οπωσδήποτε έλεγχο από την πλευρά του άγκιστρου ιστού: κατακερματίστε το `call_id` → κάδος· εξυπηρετήστε την προτροπή A για `0..49` και την προτροπή B για `50..99`. Καταγράψτε τον κάδο που επιλέξατε στη δική σας ΒΔ και αργότερα συσχετίστε τον με τον βαθμό της ολοκληρωμένης κλήσης. ### Δρομολόγηση βάσει χρόνου Ώρες λειτουργίας → πράκτορας «ζωντανής υποστήριξης»· εκτός ωραρίου → πράκτορας «λήψης μηνύματος». Απλή εναλλαγή στο `new Date().getUTCHours()` στον χειριστή σας. --- ## Επόμενα βήματα Ακριβή σχήματα αιτήματος + απόκρισης, συμπεριλαμβανομένων όλων των κλειδιών διαμόρφωσης. Ρυθμίστε σωστά το HMAC μία φορά· επαναχρησιμοποιήστε το παντού. Συνδυάστε δυναμική δρομολόγηση με εργαλεία ανά πράκτορα. Επαναλήψεις, σειρά, χρονικά όρια.