Developer cookbook

Μεταβλητές ανά κλήση

Εξατομικεύστε έναν αποθηκευμένο πράκτορα για κάθε κλήση χωρίς να αλλάξετε το αναπτυγμένο prompt, τα εργαλεία ή τις ρυθμίσεις του.

Τοποθετήστε placeholders στην προτροπή του αποθηκευμένου AI πράκτορά σας και, στη συνέχεια, παρέχετε ένα αντικείμενο variables κατά την έναρξη μιας κλήσης. Η αποθηκευμένη διαμόρφωση και το ιστορικό εκδόσεων παραμένουν αμετάβλητα. Το ThunderPhone αποδίδει το κείμενο πριν στείλει τη διαμόρφωση κλήσης στο φωνητικό περιβάλλον εκτέλεσης.

Όταν δεν χρειάζονται τιμές, παραλείψτε το variables, μην στείλετε null (απορρίπτεται με 400).

Placeholders και προεπιλογές#

You are calling {{name|Friend}} about account {{account_id}}.
The available appointment is {{ appointment_slot }}.

Τα ονόματα κάνουν διάκριση πεζών-κεφαλαίων και ακολουθούν το [A-Za-z_][A-Za-z0-9_]*. Επιτρέπονται κενά γύρω από το όνομα· το κενό μετά το | αποτελεί μέρος της προεπιλεγμένης τιμής και διατηρείται. Το {{name|Friend}} χρησιμοποιεί το Friend όταν λείπει το name ή είναι null· μια κενή συμβολοσειρά είναι τιμή που παρέχεται ρητά. Οι τιμές που λείπουν χωρίς προεπιλογή γίνονται κενές συμβολοσειρές και τα ονόματά τους εμφανίζονται στο unresolved_variables. Το κείμενο ανάμεσα σε διπλά άγκιστρα που δεν είναι έγκυρο placeholder αφαιρείται. Το κείμενο με διπλά άγκιστρα μέσα σε κάθε παρεχόμενη τιμή αφαιρείται ανεξάρτητα· μια τιμή δεν μπορεί να αφαιρέσει το περιβάλλον κείμενο της προτροπής ή άλλη τιμή. Αφαιρούνται επίσης ασύζευκτα οριοθέτες με διπλά άγκιστρα. Τα παραδείγματα JSON στις προτροπές δεν πρέπει να χρησιμοποιούν {{. Οι τιμές είναι απλό κείμενο και δεν αξιολογούνται ποτέ ως κώδικας ούτε αναπτύσσονται αναδρομικά ως πρότυπα.

Οι μεταβλητές μπορούν επίσης να εμφανίζονται στις προτροπές επιβεβαίωσης, στα εξερχόμενα μηνύματα φωνητικού ταχυδρομείου και στο κείμενο ανακοίνωσης συναίνεσης όταν αυτό το πεδίο αποστέλλεται για τηλεφωνική κλήση. Ο πράκτορας δεν διαθέτει ξεχωριστό πεδίο first_message: τοποθετήστε τις αρχικές οδηγίες του στην προτροπή. Τα υπάρχοντα placeholders φωνητικού ταχυδρομείου {agent_name} και {org_name} συνεχίζουν να λειτουργούν.

Οι τιμές μπορούν να είναι συμβολοσειρές, αριθμοί, δυαδικές τιμές ή null· οι δυαδικές τιμές αποδίδονται ως true και false. Οι χαρακτήρες ελέγχου Unicode (Cc) εκτός από αλλαγή γραμμής (\n), στηλοθέτη (\t), και επιστροφή φορέα (\r), όλοι οι χαρακτήρες μορφοποίησης (Cf) και τα σημεία κώδικα υποκατάστατου (Cs) αφαιρούνται· το \r\n κανονικοποιείται σε \n. Κάθε τιμή περιορίζεται σε 2.000 χαρακτήρες κατά την απόδοση. Οι παρεχόμενες συμβολοσειρές καθαρίζονται και περικόπτονται επίσης πριν από την αποθήκευση. Το αρχικό αντικείμενο πρέπει να χωρά σε 32 KB JSON UTF-8· μεγαλύτερα αντικείμενα λαμβάνουν 400 σε αιτήματα κλήσης/συνεδρίας, ενώ οι εισαγωγές καμπανιών αναφέρουν τις μη έγκυρες γραμμές ξεχωριστά. Οι πίνακες και τα ένθετα αντικείμενα δεν γίνονται δεκτά ως τιμές. Κλειδιά μεταδεδομένων που δεν αντιστοιχούν (για παράδειγμα, μια κεφαλίδα CSV με κενό) διατηρούνται και επιστρέφονται, αλλά δεν μπορούν να αναφερθούν από placeholder.

Από πού προέρχονται οι τιμές#

Εξερχόμενο API#

Στείλτε το variables μαζί με το agent_id στο POST /v1/call:

{
  "from_number": "+15551234567",
  "to_number": "+14155550199",
  "agent_id": 12,
  "variables": {
    "name": "Ada",
    "account_id": "A-17",
    "appointment_slot": "Tuesday at 10 AM"
  }
}

Λειτουργεί επίσης με τον προεπιλεγμένο εξερχόμενο πράκτορα του αριθμού τηλεφώνου ή με ένα ενσωματωμένο config.prompt. Ένα κλειδί ιδιομορφίας δεν μπορεί να επαναχρησιμοποιηθεί με διαφορετικές μεταβλητές.

CSV καμπάνιας#

Οι στήλες CSV που δεν αφορούν αριθμούς τηλεφώνου αποθηκεύονται ήδη ως μεταβλητές επαφής. Κάθε κλήση τις χρησιμοποιεί πλέον αυτόματα. Χρησιμοποιήστε κεφαλίδες όπως name, account_id και appointment_slot ώστε να αντιστοιχούν στα placeholders σας. Η υπάρχουσα αντιστοίχιση ονόματος μπορεί να συνδυάσει στήλες ονόματος και επωνύμου στη μεταβλητή name.

Webhook δυναμικής διαμόρφωσης#

Στη διαδρομή webhook διαμόρφωσης με αποκλεισμό, επιστρέψτε έναν αποθηκευμένο πράκτορα στον οργανισμό σας μαζί με τυχόν τιμές ανά κλήση:

{"agent_id": 12, "variables": {"name": "Ada", "account_id": "A-17"}}

Τα κλειδιά της απόκρισης αντικαθιστούν τις μεταβλητές επιπέδου αιτήματος, ενώ τα υπόλοιπα κλειδιά του αιτήματος διατηρούνται. Μια τιμή απόκρισης null επιλέγει την προεπιλεγμένη τιμή του placeholder. Το συγχωνευμένο αντικείμενο πρέπει επίσης να χωρά σε 32 KB. Οι αποκρίσεις αποθηκευμένου πράκτορα δέχονται μόνο agent_id και variables; επιστρέψτε ενσωματωμένη διαμόρφωση όταν χρειάζεται να αντικαταστήσετε το prompt ή τις ρυθμίσεις. Μια απόκριση που περιέχει prompt χρησιμοποιεί πάντα ενσωματωμένη διαμόρφωση: οποιοδήποτε agent_id σε αυτή την απόκριση αγνοείται, συμπεριλαμβανομένων τιμών null ή μεταδεδομένων που δεν είναι ακέραιοι αριθμοί. Το ενσωματωμένο prompt πρέπει και πάλι να περάσει την κανονική επικύρωση. Οι ενσωματωμένες αποκρίσεις webhook μπορούν επίσης να περιλαμβάνουν variables. Οι αποκρίσεις webhook αποθηκευμένου πράκτορα χρησιμοποιούν το αναπτυγμένο διαχωρισμό A/B του πράκτορα τόσο σε τηλεφωνικές όσο και σε κλήσεις widget· οι μεταβλητές αποδίδονται μετά την επιλογή παραλλαγής. Για εισερχόμενες τηλεφωνικές κλήσεις, χρησιμοποιήστε έναν αριθμό χωρίς εκχωρημένο εισερχόμενο πράκτορα και διαμορφώστε το webhook του αριθμού τηλεφώνου ή του οργανισμού του· τα κλειδιά widget χρησιμοποιούν mode="webhook". Οι εισερχόμενες ειδοποιήσεις του συστήματος endpoint δεν παρέχουν αποκρίσεις διαμόρφωσης με αποκλεισμό.

API συνεδριών Widget και Realtime#

Το POST /v1/widget/session δέχεται ένα αντικείμενο variables ανώτατου επιπέδου. Το δημοσιεύσιμο κλειδί του επιλέγει τον αποθηκευμένο πράκτορα. Τα κλειδιά λειτουργίας webhook προωθούν αυτές τις τιμές στο webhook διαμόρφωσης και συγχωνεύουν την απόκριση όπως περιγράφεται παραπάνω. Τα variables widget/realtime που παρέχονται από το πρόγραμμα περιήγησης ελέγχονται από τον πελάτη, προωθούνται αυτούσια στο web.incoming μετά την επικύρωση και τον καθαρισμό συμβολοσειρών που περιγράφονται παραπάνω και επαναλαμβάνονται στα webhook ολοκλήρωσης και στο ιστορικό κλήσεων. Μην τα αντιμετωπίζετε ως αξιόπιστα δεδομένα ταυτότητας ή εξουσιοδότησης.

Το POST /v1/realtime/sessions δέχεται variables μαζί με το agent_id (ή ενσωματωμένο config). Αυτά είναι πεδία API δημιουργίας συνεδρίας. Η γέφυρα Realtime WebSocket δεν προωθεί επιλογή variables· παρέχετέ την απευθείας στο API δημιουργίας συνεδρίας. Οι πελάτες Widget πρέπει να περιλαμβάνουν το variables στο δημοσιευμένο ωφέλιμο φορτίο συνεδρίας· η προώθηση SDK δεν αποτελεί μέρος αυτής της αλλαγής API. Οι δοκιμαστικές κλήσεις μικροφώνου του εργαλείου δημιουργίας και οι προσομοιωμένες δοκιμαστικές κλήσεις επιλύουν προεπιλογές και placeholder που λείπουν, αλλά δεν διαθέτουν είσοδο μεταβλητών ανά κλήση.

Τιμές που επιστρέφονται μετά την κλήση#

Τα GET /v1/calls, GET /v1/calls/{call_id}, telephony.complete και web.complete περιλαμβάνουν τις τελικές συγχωνευμένες τιμές variables και unresolved_variables. Τα παλαιότερα ωφέλιμα φορτία ολοκλήρωσης που περιλαμβάνουν data.history τις περιλαμβάνουν επίσης:

{
  "variables": {"name": "Ada", "account_id": "A-17"},
  "unresolved_variables": ["appointment_slot"]
}

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

Συμβατότητα με υπάρχοντα προτροπές#

Η απόδοση εφαρμόζεται επίσης σε υπάρχοντα προτροπές αποθηκευμένων πρακτόρων και παραλλαγών A/B, σε ενσωματωμένες διαμορφώσεις εξερχόμενων κλήσεων και πραγματικού χρόνου, καθώς και σε προτροπές που επιστρέφονται από webhook διαμόρφωσης. Άγνωστα placeholders {{name}} μετατρέπονται σε κενό κείμενο, ακόμη και όταν δεν παρέχονται variables. Ελέγξτε τις υπάρχουσες προτροπές πριν από την κυκλοφορία, συμπεριλαμβανομένων των εξωτερικά παρεχόμενων ενσωματωμένων προτροπών και προτροπών webhook που το ThunderPhone δεν μπορεί να καταγράψει. Οι κλήσεις μικροφώνου και προσομοίωσης του Builder εφαρμόζουν την ίδια προεπιλεγμένη/κενή συμπεριφορά.