Open in
Εκτελέστε κλήσεις από το Slack ή μια εφαρμογή συνομιλίας
Δημιουργήστε το δικό σας bot για Slack, Teams ή διαδικτυακή συνομιλία που ξεκινά κλήσεις, τις παρακολουθεί ζωντανά, καθοδηγεί τον πράκτορα και απαντά στις ερωτήσεις του, χρησιμοποιώντας το δημόσιο API.
Μπορείτε να καθοδηγείτε έναν πράκτορα από την εφαρμογή συνομιλίας που χρησιμοποιεί ήδη η ομάδα σας. Ένα μήνυμα ξεκινά μια κλήση. Η κλήση εξελίσσεται ζωντανά σε ένα νήμα. Μια απάντηση στο νήμα καθοδηγεί τον πράκτορα. Όταν ο πράκτορας χρειάζεται μια απόφαση, σας ρωτά εκεί και περιμένει την απάντησή σας.
Το ThunderPhone δεν φιλοξενεί αυτό το bot για εσάς. Εσείς (ή ο πράκτορας προγραμματισμού σας) δημιουργείτε έναν μικρό διακομιστή που συνδέει την εφαρμογή συνομιλίας σας με το δημόσιο API. Αυτή η σελίδα παρουσιάζει τα στοιχεία. Είναι τα ίδια για Slack, Microsoft Teams, Discord ή μια ιδιωτική σελίδα διαδικτυακής συνομιλίας· τα παραδείγματα χρησιμοποιούν Slack.
Πώς συνδέονται όλα
| Κάνετε αυτό στη συνομιλία | Το bot σας καλεί | Τι συμβαίνει |
|---|---|---|
| Στείλτε «Καλέστε την Comcast και μάθετε την εκτιμώμενη ώρα αποκατάστασης της βλάβης» | POST /v1/call με το μήνυμα ως context | Ο πράκτορας καλεί. Το bot σας ανοίγει ένα νήμα για την κλήση |
| Παρακολουθήστε το νήμα | Λαμβάνει webhook telephony.turn | Κάθε γραμμή που λέει ο πράκτορας ή το άλλο άτομο εμφανίζεται στο νήμα |
| Απαντήστε στο νήμα κατά τη διάρκεια της κλήσης | POST /v1/calls/{call_id}/whisper | Ο πράκτορας λαμβάνει το σημείωμά σας ιδιωτικά και ενεργεί βάσει αυτού. Το άλλο άτομο δεν το ακούει ποτέ |
| Απαντήστε στην ερώτηση του πράκτορα | Το endpoint εργαλείου σας επιστρέφει την απάντησή σας ή την παραδίδει αργότερα με POST /v1/calls/{call_id}/tool-results | Ο πράκτορας συνεχίζει την κλήση με αυτήν· σε λειτουργία αναμονής, το άλλο άτομο ακούει εν τω μεταξύ μουσική αναμονής |
| Διαβάστε το αποτέλεσμα | Λαμβάνει telephony.complete | Το bot σας δημοσιεύει τη σύνοψη και το αποτέλεσμα |
Το bot σας διατηρεί μία αντιστοίχιση: ποιο νήμα συνομιλίας ανήκει σε ποιο call_id.
Πριν ξεκινήσετε
- Ένα κλειδί API, αποθηκευμένο στον διακομιστή σας και ποτέ σε πρόγραμμα περιήγησης ή σε συνομιλία. Δημιουργήστε ένα στις Ρυθμίσεις οργανισμού → Κλειδιά (δείτε Κλειδιά).
- Έναν αριθμό με δυνατότητα εξερχόμενων κλήσεων και έναν πράκτορα για τις κλήσεις. Το μήνυμα
γίνεται
contextανά κλήση, επομένως ένας γενικός πράκτορας διαχειρίζεται κάθε εργασία. - Έναν διακομιστή που μπορεί να λαμβάνει webhook, όπως Railway, Fly.io, Render ή τη δική σας υποδομή.
- Ένα endpoint webhook που δείχνει σε αυτόν τον διακομιστή και είναι εγγεγραμμένο στα
telephony.turnκαιtelephony.complete. Τα συμβάντα turn αποστέλλονται μόνο σε endpoint που τα περιλαμβάνουν στη λίστα τους. Δείτε Webhook. Τα συμβάντα turn χρειάζονται ενεργοποιημένη την εγγραφή κλήσεων του πράκτορα, και τοsummaryστο τέλος της κλήσης χρειάζεται τη ρύθμιση Δημιουργία σύνοψης κλήσης του πράκτορα· χωρίς αυτά τα πεδία παραμένουν κενά. - Τη δική σας εφαρμογή συνομιλίας. Για Slack, δημιουργήστε μια εφαρμογή στον χώρο εργασίας σας στο api.slack.com/apps.
1. Ξεκινήστε μια κλήση από ένα μήνυμα
Όταν το bot σας λαμβάνει ένα μήνυμα (άμεσο μήνυμα ή αναφορά με @),
επιβεβαιώστε αμέσως το αίτημα του Slack (το Slack επαναλαμβάνει κάθε αίτημα που δεν
επιβεβαιώνεται εντός 3 δευτερολέπτων) και εκτελέστε τα υπόλοιπα στο παρασκήνιο. Ελέγξτε
ότι ο αποστολέας επιτρέπεται να πραγματοποιεί κλήσεις και, στη συνέχεια, ξεκινήστε την κλήση με το
μήνυμα ως context:
curl -X POST https://api.thunderphone.com/v1/call \
-H "Authorization: Bearer sk_live_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"from_number": "+15551234567",
"to_number": "+18005550100",
"agent_id": 12,
"context": "Matthew asked: get the outage ETA for account 4471. Wait on hold if needed.",
"idempotency_key": "slack-D012AB3CD-1731000000.000100"
}'Αποθηκεύστε το επιστρεφόμενο call_id για το νήμα του Slack (channel μαζί με το
ts του μηνύματος) και απαντήστε στο νήμα («Πραγματοποιείται κλήση…»). Δημιουργήστε το
idempotency_key από το κανάλι και το ts του μηνύματος (ένα ts είναι μοναδικό
μόνο μέσα στο κανάλι του), ώστε ένα συμβάν Slack που επαναλαμβάνεται να μην πραγματοποιεί δεύτερη
κλήση. Αν το αίτημα αναφέρει ένα άτομο αντί για αριθμό, το bot σας
αναζητά πρώτα τον αριθμό. Το ThunderPhone καλεί μόνο το to_number που στέλνετε.
2. Παρακολουθήστε την κλήση στο νήμα
Κάθε webhook telephony.turn περιλαμβάνει το call_id, τον ομιλητή (role:
assistant για τον πράκτορα, user για το άλλο άτομο), το text και τη
position της σειράς. Αναζητήστε το νήμα με βάση το call_id και
δημοσιεύστε τη γραμμή.
- Επαληθεύστε κάθε webhook πριν ενεργήσετε βάσει αυτού. Δείτε Επαλήθευση υπογραφών webhook.
- Καταργήστε τα διπλότυπα με βάση το
event_idτου περιβλήματος και ταξινομήστε κατάposition. Η παράδοση γίνεται τουλάχιστον μία φορά και οι σειρές μπορεί να φτάσουν εκτός σειράς. - Ομαδοποιήστε γραμμές αν μια πολυάσχολη κλήση θα κατέκλυζε το νήμα· η δημοσίευση κάθε λίγα δευτερόλεπτα διαβάζεται καλύτερα από ένα μήνυμα ανά γραμμή.
Όταν φτάσει το telephony.complete, δημοσιεύστε τον τρόπο λήξης της κλήσης (το status
και το end_reason της), το summary και τυχόν εξαγόμενα δεδομένα, και κλείστε το
νήμα. Δείτε Ολοκλήρωση κλήσης για τα πεδία.
3. Καθοδηγήστε την κλήση από το νήμα
Όταν κάποιος απαντά στο νήμα μιας ενεργής κλήσης, στείλτε την απάντηση ως ψίθυρο, εκτός αν ο πράκτορας περιμένει απάντηση σε ερώτηση (βήμα 4), οπότε η απάντηση είναι η απάντηση στην ερώτηση:
curl -X POST https://api.thunderphone.com/v1/calls/987654321/whisper \
-H "Authorization: Bearer sk_live_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"text": "Ask whether they can waive the late fee."}'Ο πράκτορας το ακούει ιδιωτικά και το ενσωματώνει στην επόμενη σειρά του· το άλλο
άτομο δεν ακούει ποτέ τον ίδιο τον ψίθυρο. Ένας ψίθυρος έχει από 1 έως 1000 χαρακτήρες. Ένα
409 σημαίνει ότι η κλήση δεν είναι πλέον ενεργή: ενημερώστε το νήμα ότι η κλήση έχει λήξει.
4. Αφήστε τον πράκτορα να σας ρωτήσει
Δώστε στον πράκτορα ένα εργαλείο, για παράδειγμα το ask_owner με μία παράμετρο
question, που καλεί τον διακομιστή σας. Δημιουργήστε το ως
σύνδεση API και συνδέστε το με τον πράκτορα.
Κάθε αίτημα εργαλείου μεταφέρει την κλήση στην κεφαλίδα X-ThunderPhone-Call-ID.
Υπάρχουν τρεις τρόποι να λάβετε την απάντηση.
Κρατήστε την κλήση σε αναμονή (έως 10 λεπτά). Ρυθμίστε το εργαλείο σε λειτουργία αναμονής: spec.wait_mode
"hold" και spec.timeout έως 600 δευτερόλεπτα (χωρίς χρονικό όριο, η αναμονή
διαρκεί 20 δευτερόλεπτα), μέσω του
API (το πρόγραμμα επεξεργασίας
του πίνακα ελέγχου δεν διαθέτει ακόμη κανένα από τα δύο πεδία). Το τελικό σημείο σας δημοσιεύει την ερώτηση στο νήμα της κλήσης και απαντά
αμέσως με ένα εκκρεμές αποτέλεσμα:
{"status": "pending", "request_id": "q-C012AB3CD-1731000042.000300"}Το άλλο άτομο ακούει μία φράση από τον πράκτορα και έπειτα μουσική αναμονής. Σε
τηλεφωνικό μενού ή τηλεφωνητή, ο πράκτορας χρησιμοποιεί προφορικές ενημερώσεις αντί γι’ αυτό, και ένας
πράκτορας πλήρους αμφίδρομης επικοινωνίας δεν τίθεται σε αναμονή: λαμβάνει την εκκρεμή απάντηση ως αποτέλεσμα. Όταν η
απάντηση φτάσει στο νήμα, παραδώστε την με
POST /v1/calls/{call_id}/tool-results:
curl -X POST https://api.thunderphone.com/v1/calls/987654321/tool-results \
-H "Authorization: Bearer sk_live_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"request_id": "q-C012AB3CD-1731000042.000300", "result": {"answer": "Yes, book Tuesday at 10."}}'Η μουσική χαμηλώνει και ο πράκτορας συνεχίζει με την απάντησή σας. Αν κανείς δεν
απαντήσει πριν από το timeout, ο πράκτορας ενημερώνεται ότι δεν ήρθε απάντηση και προτείνει
τα επόμενα βήματα στο άλλο άτομο. Ενώ μια ερώτηση εκκρεμεί για μια κλήση, η
επόμενη απάντηση στο νήμα της την απαντά: παραδώστε την ως αποτέλεσμα του εργαλείου και
μην τη στείλετε επίσης ως ψίθυρο (ένας ψίθυρος φτάνει στον πράκτορα μόνο αφού
επιστρέψει το εργαλείο). Δείτε
Μεγάλες αναμονές.
Περιμένετε στο αίτημα (έως 3 λεπτά). Το τελικό σημείο σας δημοσιεύει την ερώτηση,
περιμένει μια απάντηση και την επιστρέφει, όπως {"answer": "Yes, book Tuesday at 10."}.
Ρυθμίστε το spec.timeout του εργαλείου μέσω του API, έως 180 δευτερόλεπτα (η
προεπιλογή είναι 20). Δώστε στο τελικό σημείο σας το δικό του χρονικό όριο, λίγα δευτερόλεπτα μικρότερο
(για παράδειγμα 170 δευτερόλεπτα), ώστε όταν κανείς δεν απαντά να επιστρέφει
κάτι που μπορεί να αξιοποιήσει ο πράκτορας, όπως
{"answer": null, "note": "No reply yet. Offer to take a message."}. Ένα εργαλείο
που φτάνει το timeout του φτάνει στον πράκτορα ως σφάλμα, και ο κεντρικός υπολογιστής σας πρέπει
να διατηρεί ένα αίτημα ανοιχτό για τόσο χρόνο. Ενώ περιμένει, ο πράκτορας λέει στο άλλο
άτομο ότι ελέγχει, λέει ότι εξακολουθεί να εργάζεται μετά από περίπου 12 δευτερόλεπτα και
έπειτα δίνει μια σύντομη ενημέρωση περίπου κάθε 15 δευτερόλεπτα. Η λειτουργία αναμονής λειτουργεί
και εδώ: ορίστε το spec.wait_mode σε "hold" και το άλλο άτομο ακούει μουσική
αντί για τις ενημερώσεις.
Απαντήστε με ψίθυρο. Το τελικό σημείο σας δημοσιεύει την ερώτηση και επιστρέφει αμέσως,
για παράδειγμα {"status": "asked", "note": "Matthew has been asked; his answer will come as guidance."}.
Όταν φτάσει η απάντηση, στείλτε την ως ψίθυρο (βήμα 3), και ο πράκτορας
ανταποκρίνεται αμέσως σε αυτήν. Χρησιμοποιήστε το για απαντήσεις που μπορεί να χρειαστούν περισσότερα από
10 λεπτά. Η κλήση δεν τίθεται σε αναμονή: η προτροπή σας πρέπει να λέει στον
πράκτορα τι να κάνει στο μεταξύ, όπως να κρατά συντροφιά στο άτομο ή να προσφέρει
να το καλέσει ξανά.
Σε κάθε περίπτωση, αναφέρετε στην προτροπή του πράκτορα πότε να χρησιμοποιεί το εργαλείο και τι να λέει στο άλλο άτομο ενώ περιμένει:
When you need Matthew's decision, use ask_owner with a short question.
Tell the person you're checking with Matthew and it may take a minute.
If there's no answer, offer to take a message or have Matthew call back.Όρια που πρέπει να λάβετε υπόψη
- Το τελικό σημείο σας πρέπει να απαντά εντός του
timeoutτου εργαλείου, το πολύ σε 180 δευτερόλεπτα. Ένα εργαλείο σε λειτουργία αναμονής μπορεί να διατηρεί την κλήση σε αναμονή έως και 600 δευτερόλεπτα με εκκρεμές αποτέλεσμα. - Όσο ένα εργαλείο περιμένει, ο πράκτορας δεν απαντά στο άλλο άτομο. Σε λειτουργία αναμονής ακούει μουσική· διαφορετικά, σύντομες προφορικές ενημερώσεις.
- Ένα ψιθύρισμα έχει έως 1000 χαρακτήρες.
- Η παράδοση του
telephony.turnγίνεται τουλάχιστον μία φορά και μπορεί να είναι εκτός σειράς.
Λίστα ελέγχου ασφαλείας
- Διατηρήστε το κλειδί API στον διακομιστή σας.
- Επαληθεύστε τις υπογραφές του ThunderPhone στα webhook και στα αιτήματα εργαλείων, καθώς και
το μυστικό υπογραφής του Slack στα αιτήματα του Slack. Οι δύο υπογραφές του ThunderPhone
χρησιμοποιούν διαφορετικά μυστικά: οι παραδόσεις webhook χρησιμοποιούν το μυστικό του ίδιου του
τελικού σημείου webhook και τα αιτήματα εργαλείων χρησιμοποιούν το μυστικό webhook του οργανισμού σας
από το
GET /v1/webhook. - Αποφασίστε ποιος μπορεί να ξεκινά κλήσεις: ελέγξτε το αναγνωριστικό χρήστη Slack πριν πραγματοποιήσετε μία.
- Οι εξερχόμενες κλήσεις ακολουθούν τους ίδιους κανόνες όπως κάθε άλλη κλήση. Δείτε Νομοθεσία για εξερχόμενες κλήσεις.
Δημιουργήστε το με έναν προγραμματιστικό πράκτορα
Κατευθύνετε τον προγραμματιστικό πράκτορά σας στον διακομιστή MCP τεκμηρίωσης και σε αυτήν τη σελίδα και ζητήστε «ένα bot Slack για τον πράκτορά μου ThunderPhone που ακολουθεί αυτόν τον οδηγό». Ο Zeus, ο βοηθός στην εφαρμογή ThunderPhone, μπορεί να ρυθμίσει την πλευρά του πράκτορα (το τελικό σημείο webhook, το εργαλείο και τις γραμμές προτροπής) και να γράψει αρχικό κώδικα για το bot στη συνομιλία.