Το ThunderPhone v3 είναι πλέον διαθέσιμο.Ξεκινήστε μόνοι σας, από 2¢/λεπτό.Διαβάστε την ανακοίνωση

Developer cookbook

Μεταβλητές και περιβάλλον ανά κλήση

Δώστε σε κάθε κλήση τα δικά της στοιχεία, ως ονομασμένες μεταβλητές για την προτροπή ή ως ελεύθερη σύνοψη, χωρίς να αλλάξετε τον πράκτορα.

Κάθε κλήση μπορεί να περιλαμβάνει δύο είδη εισόδου ανά κλήση. Χρησιμοποιήστε είτε το ένα είτε και τα δύο μαζί:

  • variables: ονομασμένες τιμές που συμπληρώνουν τα {{placeholders}} στο prompt. Χρησιμοποιήστε τις για πεδία στα οποία το prompt αναφέρεται ονομαστικά, όπως το όνομα του καλούντος, έναν αριθμό λογαριασμού ή ένα χρονικό διάστημα ραντεβού.
  • context: κείμενο ελεύθερης μορφής που προστίθεται μετά το prompt. Χρησιμοποιήστε το για μια σύντομη ενημέρωση που δεν ταιριάζει σε πρότυπο, όπως περιγραφή της εργασίας για αυτή την κλήση ή σημειώσεις που συλλέχθηκαν νωρίτερα.

Και τα δύο λειτουργούν με έναν αποθηκευμένο πράκτορα και με ενσωματωμένη διαμόρφωση, σε κάθε τρόπο έναρξης κλήσης που περιγράφεται παρακάτω. Κανένα δεν αλλάζει τον αποθηκευμένο πράκτορα, το ιστορικό εκδόσεών του ή τις άλλες ρυθμίσεις του.

{
  "agent_id": 12,
  "variables": {"name": "Ada", "appointment_slot": "Tuesday at 10 AM"},
  "context": "Ada rescheduled twice last month. She prefers mornings and asked us not to call her work number."
}

Μεταβλητές

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

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

Σύμβολα κράτησης θέσης και προεπιλογές

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) εκτός από τον συνδέτη και μη συνδέτη μηδενικού πλάτους (U+200C, U+200D, που σχηματίζουν λέξεις σε γλώσσες ινδικών και αραβικής γραφής), και τα σημεία κώδικα υποκατάστατων (Cs) αφαιρούνται· το \r\n κανονικοποιείται σε \n. Κάθε τιμή περιορίζεται σε 2.000 χαρακτήρες κατά την απόδοση. Οι παρεχόμενες συμβολοσειρές καθαρίζονται και περικόπτονται επίσης πριν από την αποθήκευση. Το αρχικό αντικείμενο πρέπει να χωρά σε 32 KB JSON UTF-8· τα μεγαλύτερα αντικείμενα λαμβάνουν 400 σε αιτήματα κλήσης/συνεδρίας, ενώ οι εισαγωγές καμπανιών αναφέρουν μη έγκυρες γραμμές μεμονωμένα. Οι πίνακες και τα ένθετα αντικείμενα δεν γίνονται δεκτά ως τιμές. Κλειδιά μεταδεδομένων που δεν ταιριάζουν (για παράδειγμα, μια κεφαλίδα CSV με κενό) διατηρούνται και επιστρέφονται, αλλά δεν μπορούν να αναφερθούν από ένα σύμβολο υποκατάστασης.

Περιεχόμενο

Το context είναι μια συμβολοσειρά έως 20.000 χαρακτήρων. Το ThunderPhone το προσθέτει μετά την προτροπή, αφού συμπληρωθούν οι μεταβλητές της προτροπής, ως οριοθετημένο τμήμα:

<your prompt, with its variables filled in>
 
Details for this call:
<call_context>
Ada rescheduled twice last month. She prefers mornings and asked us not to call her work number.
</call_context>

Ο πράκτορας το διαβάζει μαζί με τις οδηγίες του, επομένως γράψτε το όπως θα ενημερώνατε έναν συνάδελφο πριν από την κλήση. Το περιεχόμενο δεν είναι πρότυπο: το {{name}} μέσα σε αυτό παραμένει όπως έχει γραφτεί. Αν το κείμενο χρειάζεται μια τιμή, εισαγάγετε την τιμή εσείς πριν από την αποστολή.

  • Το null, μια κενή συμβολοσειρά ή μόνο κενά διαστήματα σημαίνουν ότι δεν υπάρχει περιεχόμενο.
  • Μια τιμή που δεν είναι συμβολοσειρά ή υπερβαίνει τους 20.000 χαρακτήρες απορρίπτεται με 400 σε αιτήματα κλήσης και συνεδρίας· από webhook διαμόρφωσης αποτυγχάνει η ανταλλαγή όπως με μη έγκυρες variables (βλ. παρακάτω).
  • Τα κενά διαστήματα στην αρχή και στο τέλος περικόπτονται και αφαιρούνται οι ίδιοι χαρακτήρες ελέγχου και μορφοποίησης που αφαιρούνται από τις τιμές μεταβλητών.
  • Το περιεχόμενο αποτελεί μέρος του prompt της κλήσης, επομένως συνυπολογίζεται στο μέγεθος prompt της κλήσης.

Σε έναν πράκτορα με βήματα, το περιεχόμενο ακολουθεί την προτροπή κάθε πράκτορα στην κλήση, όχι τις οδηγίες κάθε βήματος.

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

Εξερχόμενο API

Στείλτε τα variables και context στο POST /v1/call:

{
  "from_number": "+15551234567",
  "to_number": "+14155552671",
  "agent_id": 12,
  "variables": {
    "name": "Ada",
    "account_id": "A-17",
    "appointment_slot": "Tuesday at 10 AM"
  },
  "context": "Ada asked to be called back about the late fee on her March invoice."
}

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

CSV καμπάνιας

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

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

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

{
  "agent_id": 12,
  "variables": {"name": "Ada", "account_id": "A-17"},
  "context": "[REDACTED_LITERAL]"
}
{
  "agent_id": 12,
  "variables": {"name": "Ada", "account_id": "A-17"},
  "context": "Ada called yesterday about a leak in unit 4B; a plumber is booked for Friday."
}

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

Webhook ρύθμισης κλήσης πράκτορα

Για να διατηρήσετε έναν αριθμό αντιστοιχισμένο στον πράκτορά του και να συμπληρώνετε μόνο τις τιμές της κλήσης, δώστε στον πράκτορα ένα webhook ρύθμισης κλήσης. Πριν από κάθε εισερχόμενη κλήση που απαντά ο πράκτορας σε έναν αριθμό, το webhook λαμβάνει την κλήση και το αναγνωριστικό, το όνομα και την έκδοση του πράκτορα και απαντά με τα ίδια variables, context, language και timezone ανά κλήση όπως παραπάνω, χωρίς να απαιτείται agent_id. Ένας πράκτορας του οποίου οι ρυθμίσεις χρησιμοποιούν ένα σύμβολο κράτησης θέσης χωρίς προεπιλεγμένη τιμή χρειάζεται αυτό το webhook για να απαντήσει σε έναν αριθμό τηλεφώνου: η κλήση δεν ξεκινά όταν το webhook αποτυγχάνει. Τα σύμβολα κράτησης θέσης με προεπιλεγμένη τιμή, όπως {{name|there}}, επιτρέπουν στον πράκτορα να απαντά χωρίς αυτό.

Κεφαλίδες SIP

Οι κλήσεις που φτάνουν σε έναν πράκτορα μέσω SIP (μιας διεύθυνσης SIP ή ενός αριθμού σε μη αυτόματη σύνδεση SIP) μπορούν να μεταφέρουν περιβάλλον στις κεφαλίδες X-* και User-to-User. Κάθε μία γίνεται μεταβλητή sip_, όπως {{sip_x_amzn_connectcontactid}} ή {{sip_uui}}, με τη χαμηλότερη προτεραιότητα: υπερισχύει μια τιμή με το ίδιο όνομα από το API ή ένα webhook. Δείτε Μεταβίβαση περιβάλλοντος κλήσης σε κεφαλίδες SIP. Οι τιμές κεφαλίδων ορίζονται από τον αποστολέα, επομένως αντιμετωπίστε τις ως μη αξιόπιστες, όπως κάθε τιμή που παρέχεται από το πρόγραμμα περιήγησης.

Διεπαφή προγραμματισμού συνεδρίας στοιχείου ενσωμάτωσης

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

Το πεδίο context του προγράμματος περιήγησης του ίδιου του στοιχείου ενσωμάτωσης είναι διαφορετικό: μεταφέρει κείμενο από τη σελίδα στην οποία βρίσκεται ο επισκέπτης, το οποίο ο πράκτορας αντιμετωπίζει ως περιεχόμενο ιστοτόπου (βλ. Ενσωμάτωση του στοιχείου ενσωμάτωσης ιστού). Το περιεχόμενο ανά κλήση ενός στοιχείου ενσωμάτωσης προέρχεται από το άγκιστρο ιστού διαμόρφωσης ενός κλειδιού λειτουργίας αγκίστρου ιστού, όπως παραπάνω. Όταν μια κλήση έχει και τα δύο, το περιεχόμενο ανά κλήση προηγείται και έπειτα ακολουθεί το περιεχόμενο της σελίδας.

Διεπαφή προγραμματισμού συνεδρίας πραγματικού χρόνου

Το POST /v1/realtime/sessions δέχεται τα variables, context και language στο ανώτατο επίπεδο μαζί με το agent_id ή ένα ενσωματωμένο config:

{
  "agent_id": 12,
  "variables": {"name": "Ada"},
  "context": "Ada is calling from the front desk about a guest's lost key card."
}

Το context τοποθετείται μόνο στο ανώτατο επίπεδο· μια ενσωματωμένη config το απορρίπτει ως άγνωστο πεδίο.

WebSocket σε πραγματικό χρόνο

Με έναν αποθηκευμένο πράκτορα, η αναπτυγμένη προτροπή του αποθηκευμένου πράκτορα παραμένει η προτροπή του. Το session.instructions γίνεται το πλαίσιο της κλήσης, το session.prompt.variables (ή το session.config.variables) γίνονται οι μεταβλητές του και το session.language γίνεται η γλώσσα ανά κλήση. Επιλέξτε τον πράκτορα με το session.prompt.id στο πρώτο session.update, το οποίο ξεκινά τη συνεδρία μόλις φτάσει αυτή η ενημέρωση:

{
  "type": "session.update",
  "session": {
    "type": "realtime",
    "prompt": {"id": "12", "variables": {"name": "Ada"}},
    "instructions": "Ada asked for a callback about her delivery window."
  }
}

Το ?agent_id=12 στο URL σύνδεσης ξεκινά τον πράκτορα μόλις συνδεθεί το socket, πριν από οποιοδήποτε session.update, επομένως δεν περιλαμβάνει εισαγωγή ανά κλήση. Προσθέστε &wait_for_session_update=1 για να περιμένετε το πρώτο session.update και να χρησιμοποιήσετε τις οδηγίες και τις μεταβλητές του.

Σε μια ενσωματωμένη συνεδρία (χωρίς αποθηκευμένο πράκτορα), το session.instructions είναι το ίδιο το prompt, όπως και πριν. Οι δοκιμαστικές κλήσεις μικροφώνου και προσομοίωσης του Builder επιλύουν προεπιλογές και ελλείποντα σύμβολα κράτησης, αλλά δεν διαθέτουν μεταβλητές ανά κλήση ή εισαγωγή περιβάλλοντος.

Μετά την κλήση

Τα 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"]
}

Το prompt_snapshot της κλήσης (GET /v1/calls/{call_id}) εμφανίζει την προτροπή του πράκτορα με τις μεταβλητές της συμπληρωμένες και το μπλοκ περιβάλλοντος προστιθέμενο.

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

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

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

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