Open in
Δυναμική διαμόρφωση ανά κλήση
Επιλέξτε τον πράκτορα που απαντά — ή επαναδιατυπώστε το prompt και τις ρυθμίσεις του — ξεχωριστά για κάθε εισερχόμενη κλήση, με βάση προσαρμοσμένη λογική σε ένα webhook που ελέγχετε.
Από προεπιλογή, σε κάθε αριθμό τηλεφώνου και δημοσιεύσιμο κλειδί έχει αντιστοιχιστεί ένας στατικός πράκτορας. Όταν χρειάζεστε προσαρμογή ανά καλούντα ή ανά επισκέπτη — δρομολόγηση VIP, περιβάλλον συνδεδεμένου χρήστη, δοκιμές προτροπών A/B — μεταβείτε σε λειτουργία webhook και αφήστε τον διακομιστή σας να αποφασίσει.
Πώς λειτουργεί
- Εγγράφεστε στο συμβάν
telephony.incoming(τηλέφωνο) ήweb.incoming(widget). Και τα δύο είναι δεσμευτικά webhook: το ThunderPhone περιμένει την απόκρισή σας πριν συνεχίσει την κλήση, έως 13 δευτερόλεπτα για τηλεφωνική κλήση (περιλαμβάνεται μία επανάληψη) και 10 δευτερόλεπτα για συνεδρία widget. - Το ThunderPhone σάς στέλνει
{call_id, from_number, to_number}(οι συνεδρίες widget περιλαμβάνουν πεδία ειδικά για widget αντί για αριθμούς — ανατρέξτε στο σχήμα αιτήματος). - Ο διακομιστής σας απαντά με μια διαμόρφωση πράκτορα (προτροπή, φωνή, προϊόν, εργαλεία, λέξεις). Το ThunderPhone χρησιμοποιεί αυτή τη διαμόρφωση για την κλήση.
- Δεν υπάρχει εφεδρικός πράκτορας. Αν επιστρέψετε
{}ή μη έγκυρη διαμόρφωση, ή αν το αίτημα συνεχίσει να αποτυγχάνει μετά την επανάληψή του, η τηλεφωνική κλήση τερματίζεται αμέσως και καταγράφεται μεend_reasoninbound_config_webhook_failed; ένα αίτημα συνεδρίας widget αποτυγχάνει.
1. Διαμορφώστε τον προορισμό webhook
Για αριθμούς τηλεφώνου, εγγράψτε το τελικό σημείο σας στο telephony.incoming:
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 του τελικού σημείου σας ενσωματωμένη:
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). Μην το παραλείπετε στο περιβάλλον ανάπτυξης — ρυθμίστε το σωστά μία φορά και επαναχρησιμοποιήστε το.
- Απαντάτε γρήγορα. Η πρώτη προσπάθεια μιας τηλεφωνικής κλήσης διακόπτεται στα 10 δευτερόλεπτα και ολόκληρη η αλληλεπίδραση στα 13, ενώ κάθε δευτερόλεπτο είναι σιωπή για τον καλούντα. Κάντε αναζητήσεις στη βάση δεδομένων αν χρειάζεται, αλλά μην καλείτε κατάντη LLM συγχρονισμένα — αν θέλετε δυναμική δημιουργία προτροπών, υπολογίστε τις εκ των προτέρων και αποθηκεύστε τις στην κρυφή μνήμη.
- Χρησιμοποιείτε καθαρή εναλλακτική λύση. Για κάθε μη αναμενόμενη κατάσταση, απαντήστε με ένα
προεπιλεγμένο
promptκαιvoice(ή ένα αποθηκευμένοagent_id). Η επιστροφή του{}ή μιας κατάστασης σφάλματος τερματίζει την κλήση.
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 ...
passimport 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. Σχήμα απόκρισης
Το σώμα της απόκρισης αντιστοιχεί ακριβώς στο σχήμα απόκρισης εισερχόμενης κλήσης. Τα πεδία που χρησιμοποιούνται συχνότερα:
| Πεδίο | Τύπος | Περιγραφή |
|---|---|---|
prompt | συμβολοσειρά (υποχρεωτικό) | Προτροπή συστήματος για τον πράκτορα |
voice | συμβολοσειρά (υποχρεωτικό) | Αναγνωριστικό φωνής από GET /v1/voices |
product | συμβολοσειρά | Στείλτε bolt. Η προεπιλογή είναι spark, μια παλαιότερη τιμή που εξακολουθεί να γίνεται δεκτή. |
background_track | συμβολοσειρά | null | Αναγνωριστικό ήχου περιβάλλοντος |
acknowledgement_prompt_mode | συμβολοσειρά | auto ή manual (μόνο για παλαιότερες τιμές προϊόντος -with-ack) |
acknowledgement_prompt | συμβολοσειρά | Υποχρεωτικό όταν η λειτουργία είναι manual |
language_switching | συμβολοσειρά | Για πολύγλωσσους πράκτορες, ask_first ή follow_caller |
tools | πίνακας | Ενσωματωμένα σχήματα εργαλείων συναρτήσεων — δείτε τα Εργαλεία συναρτήσεων |
Διατηρήστε έναν αποθηκευμένο πράκτορα και παρέχετε μεταβλητές ή περιβάλλον
Επιστρέψτε {"agent_id": 12, "variables": {"name": "Ada"}} για να χρησιμοποιήσετε τον
αποθηκευμένο πράκτορα αυτού του οργανισμού με δεδομένα ανά κλήση. Η προτροπή του μπορεί να περιέχει {{name}} ή
{{name|Friend}}. Οι μεταβλητές του αγκίστρου ιστού συγχωνεύονται πάνω από τις μεταβλητές επιπέδου αιτήματος· η τιμή null
χρησιμοποιεί την προεπιλογή του δεσμευτικού θέσης ή κενό κείμενο, αν δεν παρέχεται κάποια. Οι τελικές
τιμές και τα ονόματα που δεν επιλύθηκαν εμφανίζονται στις λεπτομέρειες κλήσης και στα άγκιστρα ιστού ολοκλήρωσης.
Προσθέστε context, μια συμβολοσειρά ελεύθερης μορφής έως 20.000 χαρακτήρων, για να δώσετε στον πράκτορα
μια σύνοψη για αυτήν την κλήση (σημειώσεις από το CRM σας, τον λόγο που αναμένετε την κλήση)·
προστίθεται μετά την προτροπή σε οριοθετημένο μπλοκ.
Οι απαντήσεις αποθηκευμένου πράκτορα δέχονται μόνο agent_id, variables, context, timezone και language. Αν υπάρχει το prompt,
η απάντηση χρησιμοποιεί ενσωματωμένη ρύθμιση και αγνοεί το agent_id· η ενσωματωμένη προτροπή πρέπει να παραμένει έγκυρη. Αν το άγκιστρο ιστού σας είναι το άγκιστρο ιστού ρύθμισης κλήσεων του εκχωρημένου πράκτορα, μπορείτε επίσης να παραλείψετε το agent_id και να επιστρέψετε μόνο variables, context, timezone ή language για να διατηρήσετε αυτόν τον εκχωρημένο πράκτορα (συμπεριλαμβανομένης οποιασδήποτε καρφίτσωσης έκδοσης) για την κλήση. Οι απαντήσεις ενσωματωμένης
ρύθμισης μπορούν επίσης να περιλαμβάνουν variables και context. Οι απαντήσεις αποθηκευμένου πράκτορα χρησιμοποιούν
τον αναπτυγμένο διαχωρισμό A/B του πράκτορα τόσο στις τηλεφωνικές κλήσεις όσο και στις κλήσεις μέσω γραφικού στοιχείου και, στη συνέχεια, αποδίδουν τις μεταβλητές. Δείτε τις μεταβλητές κλήσης
για όρια και υποστήριξη API συνεδρίας. Η ρύθμιση αποκλεισμού προέρχεται από το παλαιού τύπου
URL αριθμού τηλεφώνου/οργανισμού ή από κλειδί γραφικού στοιχείου σε λειτουργία αγκίστρου ιστού· τα εισερχόμενα συμβάντα του συστήματος τελικού σημείου είναι μόνο ειδοποιήσεις.
Ορίστε τη ζώνη ώρας ανά κλήση
Ένας πράκτορας μπορεί να απαντά σε επαφές σε διαφορετικές ζώνες ώρας. Προσθέστε το timezone, ένα όνομα IANA, σε μια αποθηκευμένη απάντηση πράκτορα ή σε μια ενσωματωμένη απάντηση και ο πράκτορας δηλώνει την ημερομηνία και την ώρα και προσφέρει ώρες σε αυτή τη ζώνη για την κλήση, αντί για τη δική του ζώνη ώρας:
{"agent_id": 12, "timezone": "America/Chicago", "variables": {"name": "Ada"}}Στείλτε τη ζώνη αντί για χρονική σήμανση στο variables: το ρολόι του πράκτορα συνεχίζει να λειτουργεί κατά τη διάρκεια της κλήσης και μια ώρα που μεταβιβάζετε παλιώνει. Μια τιμή που δεν είναι ζώνη IANA αγνοείται και η κλήση συνδέεται στη ζώνη του πράκτορα.
Ορίστε τη γλώσσα ανά κλήση
Ένας πράκτορας μπορεί να απαντά σε καθεμία από τις γλώσσες του. Προσθέστε language, έναν υποστηριζόμενο
κωδικό γλώσσας όπως es (το es-MX διαβάζεται ως es), δίπλα στο agent_id και η
κλήση ξεκινά σε αυτή τη γλώσσα:
{"agent_id": 12, "language": "es", "variables": {"name": "Ada"}}Ο πράκτορας τη μιλά με τη φωνή του για εκείνη τη γλώσσα: την καταχώρισή του
language_voices· διαφορετικά, με ενεργό το
native_voice_switching, την εγγενή φωνή στην οποία θα μεταβεί ο πράκτορας για
εκείνη τη γλώσσα· διαφορετικά, τη δική του φωνή, εφόσον αυτή η φωνή μιλά τη
γλώσσα. Σε κλήσεις χωρίς καταγραφή, το ThunderPhone αναπαράγει επίσης την
ειδοποίηση ζωντανής επεξεργασίας στη γλώσσα της κλήσης. Στη συνέχεια, οι άλλες
γλώσσες του πράκτορα και η κύρια γλώσσα του παραμένουν διαθέσιμες για εναλλαγή.
Αν καμία από αυτές δεν μπορεί να τη μιλήσει, η κλήση εξακολουθεί να ξεκινά σε
εκείνη τη γλώσσα, με την προεπιλεγμένη φωνή της γλώσσας (ένας πράκτορας με
προσαρμοσμένη φωνή τη διατηρεί) και χωρίς άλλες γλώσσες. Αν η κλήση αλλάξει
αργότερα, κατά τη διάρκειά της, σε άλλη από τις γλώσσες του πράκτορα, χρησιμοποιεί
επίσης την καταχώριση language_voices για εκείνη τη γλώσσα όταν και οι δύο
φωνές είναι φωνές καταλόγου· διαφορετικά, εφαρμόζονται οι συνήθεις κανόνες
εναλλαγής. Οι πράκτορες πλήρους αμφίδρομης λειτουργίας διαφέρουν: σε οποιαδήποτε
υποστηριζόμενη γλώσσα, η κλήση διατηρεί τη δική τους φωνή και δεν εφαρμόζονται τα
language_voices και η εναλλαγή εγγενούς φωνής. Απορρίπτεται μόνο ένας κωδικός
που δεν αντιστοιχεί σε υποστηριζόμενη γλώσσα. Οι συνεδρίες του γραφικού στοιχείου
και πραγματικού χρόνου δέχονται το ίδιο πεδίο language.
Πρότυπα
Πλαίσιο συνδεδεμένου χρήστη
Στα γραφικά στοιχεία σε λειτουργία άγκιστρου ιστού, η σελίδα του επισκέπτη γνωρίζει ήδη ποιος
είναι. Καλέστε το άγκιστρο ιστού σας με μια παράμετρο συμβολοσειράς ερωτήματος που το SDK
του γραφικού στοιχείου προωθεί (?customer_id=123) και αναζητήστε τον πελάτη στην πλευρά του διακομιστή.
Κυκλοφορία προτροπών A/B
Πριν το υλοποιήσετε χειροκίνητα, σημειώστε ότι το ThunderPhone διαθέτει εγγενή λειτουργία
Πειραμάτων
(/dashboard/experiments και την καρτέλα A/B του εργαλείου δημιουργίας πρακτόρων) που
ορίζει παραλλαγές, κατανέμει την κίνηση και συγκρίνει αποτελέσματα ανά παραλλαγή —
δεν απαιτείται άγκιστρο ιστού.
Εάν χρειάζεστε οπωσδήποτε έλεγχο από την πλευρά του άγκιστρου ιστού: κατακερματίστε το call_id → κάδος·
εξυπηρετήστε την προτροπή A για 0..49 και την προτροπή B για 50..99. Καταγράψτε τον
κάδο που επιλέξατε στη δική σας ΒΔ και αργότερα συσχετίστε τον με τον βαθμό της
ολοκληρωμένης κλήσης.
Δρομολόγηση βάσει χρόνου
Ώρες λειτουργίας → πράκτορας «ζωντανής υποστήριξης»· εκτός ωραρίου → πράκτορας «λήψης μηνύματος».
Απλή εναλλαγή στο new Date().getUTCHours() στον χειριστή σας.
Επόμενα βήματα
Ακριβή σχήματα αιτήματος + απόκρισης, συμπεριλαμβανομένων όλων των κλειδιών διαμόρφωσης.
Ρυθμίστε σωστά το HMAC μία φορά· επαναχρησιμοποιήστε το παντού.
Συνδυάστε δυναμική δρομολόγηση με εργαλεία ανά πράκτορα.
Επαναλήψεις, σειρά, χρονικά όρια.