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

Developer cookbook

Ενσωματώστε το γραφικό στοιχείο ιστού

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

Το διαδικτυακό γραφικό στοιχείο προσφέρει στους επισκέπτες του ιστότοπού σας μια συνομιλία με κλικ για ομιλία με έναν AI πράκτορα, χρησιμοποιώντας το μικρόφωνο του προγράμματος περιήγησης. Είναι ένα ξεχωριστό JavaScript / React SDK με τη δική του αναφορά SDK — αυτός ο οδηγός εστιάζει στη ρύθμιση στην πλευρά του ThunderPhone που χρειάζεται το γραφικό στοιχείο.

Προαπαιτούμενα

  1. Δημιουργήστε έναν πράκτορα

    Ο πράκτορας του οποίου η προτροπή και η φωνή θα εκτελούν τη συνεδρία του widget. Ορίστε widget_enabled: true (η προεπιλογή).

  2. Επιλέξτε τη λειτουργία δρομολόγησης
    • mode="agent" — ένας στατικός πράκτορας ανά κλειδί. Η απλούστερη επιλογή.
    • mode="webhook" — ο διακομιστής σας επιλέγει τον πράκτορα ανά επισκέπτη μέσω ενός webhook web.incoming. Χρησιμοποιήστε το για συνδεδεμένους χρήστες, δοκιμές A/B ή δρομολόγηση ανά σελίδα.
  3. Καταχωρίστε τους επιτρεπόμενους τομείς

    Καταχωρίστε κάθε όνομα κεντρικού υπολογιστή που θα ενσωματώνει το widget. Τα προγράμματα περιήγησης στέλνουν την προέλευση της σελίδας με κάθε αίτημα συνεδρίας, επομένως η λίστα εμποδίζει το κλειδί σας να λειτουργεί όταν κάποιος το αντιγράψει σε άλλον ιστότοπο. Δεν αποτελεί έλεγχο ταυτότητας: ένα script εκτός προγράμματος περιήγησης μπορεί να στείλει οποιαδήποτε κεφαλίδα Origin. Το localhost δεν επιτρέπεται αυτόματα στην παραγωγή· για να δοκιμάσετε τοπικά με το API παραγωγής, προσθέστε το localhost στη λίστα.

  4. Επιλέξτε τις παρακάμψεις προγράμματος περιήγησης

    Αποφασίστε ποιες ρυθμίσεις συνεδρίας μπορεί να στέλνει η σελίδα σας. Τα νέα κλειδιά δεν δέχονται καμία· δείτε Παρακάμψεις προγράμματος περιήγησης.

Δημιουργήστε ένα δημοσιεύσιμο κλειδί

Static agent
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":            "Marketing site (prod)",
    "mode":            "agent",
    "agent_id":        12,
    "allowed_domains": ["example.com", "*.example.com"],
    "allowed_overrides": ["context"]
  }'
Dynamic via webhook
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":            "Support (dynamic)",
    "mode":            "webhook",
    "webhook_url":     "https://example.com/thunderphone/widget-hook",
    "allowed_domains": ["support.example.com"]
  }'

Η απόκριση περιλαμβάνει ένα key που ξεκινά με pk_live_.... Τα δημοσιεύσιμα κλειδιά είναι δημόσια από σχεδίαση — μπορείτε με ασφάλεια να τα συμπεριλάβετε στο πακέτο του προσκηνίου σας. Δείτε την αναφορά δημοσιεύσιμων κλειδιών για όλα τα πεδία.

Προσθέστε το γραφικό στοιχείο στον ιστότοπό σας

Τρεις επιλογές ενσωμάτωσης καλύπτονται στην τεκμηρίωση SDK του γραφικού στοιχείου:

Και οι τρεις δέχονται το ίδιο publishableKey και αποδίδουν το κουμπί μικροφώνου μαζί με το στοιχείο ήχου κατά την κλήση.

Παρακάμψεις προγράμματος περιήγησης

Το γραφικό στοιχείο μπορεί να στείλει τέσσερις ρυθμίσεις ανά συνεδρία από τη σελίδα:

ΡύθμισηΙδιότητα γραφικού στοιχείουΤι αλλάζει
contextcontextΚείμενο από τη σελίδα, που προστίθεται στην προτροπή του πράκτορα ως αναφορά
variablesκαμία (μόνο ακατέργαστο POST /v1/widget/session)Τιμές για τα σύμβολα θέσης {{variable}} στην προτροπή
voicevoiceΗ φωνή του πράκτορα για αυτήν τη συνεδρία
languagelanguageΗ γλώσσα με την οποία ξεκινά η συνεδρία

Το δημοσιεύσιμο κλειδί σας είναι δημόσιο, επομένως οποιοσδήποτε το έχει μπορεί να στείλει αυτές τις ρυθμίσεις, ακόμη και από ένα script που πλαστογραφεί τον τομέα σας. Επομένως, καθεμία είναι απενεργοποιημένη μέχρι να την επιτρέψετε στο κλειδί: επιλέξτε την στην ενότητα Παρακάμψεις προγράμματος περιήγησης όταν δημιουργείτε ή επεξεργάζεστε το widget στον πίνακα ελέγχου ή ορίστε το allowed_overrides μέσω του API δημοσιεύσιμων κλειδιών. Επιτρέψτε μόνο ό,τι στέλνει πραγματικά η σελίδα σας.

Ένα αίτημα συνεδρίας που περιέχει μια ρύθμιση την οποία δεν επιτρέπει το κλειδί αποτυγχάνει με 400 και την αναφέρει ονομαστικά:

{
  "error": "override_not_allowed",
  "fields": ["voice"],
  "message": "This publishable key does not allow the browser to set `voice`. ..."
}

Ο έλεγχος εφαρμόζεται και στις δύο λειτουργίες. Στη λειτουργία webhook, μια επιτρεπόμενη ρύθμιση προωθείται επίσης στο webhook web.incoming (context φτάνει ως website_context). Τα κλειδιά που δημιουργήθηκαν πριν υπάρξει αυτή η ρύθμιση επιτρέπουν και τις τέσσερις, επομένως οι υπάρχουσες ενσωματώσεις συνεχίζουν να λειτουργούν· απενεργοποιήστε ό,τι δεν χρησιμοποιείτε.

Το context του widget περικόπτεται στους 12.000 χαρακτήρες (περίπου 3.400 διακριτικά κειμένου στα τυπικά αγγλικά) και αποτελεί μέρος της προτροπής που διαβάζουν τα μοντέλα, επομένως ένα μεγαλύτερο context κοστίζει περισσότερο ανά λεπτό. Ο πράκτορας λαμβάνει οδηγία να το αντιμετωπίζει ως περιεχόμενο της σελίδας και όχι ως οδηγίες.

Webhook λειτουργίας γραφικού στοιχείου

Όταν mode="webhook", το ThunderPhone καλεί το webhook_url σας σε κάθε έναρξη συνεδρίας με ένα ωφέλιμο φορτίο web.incoming. Επιστρέψτε τη ρύθμιση πράκτορα που θέλετε να εκτελέσετε για τον συγκεκριμένο επισκέπτη — ακολουθεί το ίδιο σχήμα απόκρισης με τις τηλεφωνικές κλήσεις:

{
  "prompt":  "You are a VIP concierge for Jane Doe.",
  "voice":   "john",
  "product": "storm-base",
  "tools":   [ /* per-customer tools */ ]
}

Μπορείτε να συνδυάσετε περιβάλλον από τη δική σας συνεδρία (ποιος πελάτης περιηγείται, σε ποια σελίδα βρίσκεται) στην προτροπή και να αλλάζετε πράκτορες ανά ανάπτυξη.

Παρακολούθηση των συνεδριών

Οι συνεδρίες του widget εμφανίζονται στο GET /v1/calls με direction="widget" — με την ίδια απομαγνητοφώνηση, εγγραφή, αξιολόγηση και χρέωση όπως οι τηλεφωνικές κλήσεις. Φιλτράρετε κατά direction για να δημιουργήσετε έναν πίνακα ελέγχου μόνο για το widget.


Επόμενα βήματα