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

Developer cookbook

Εκτελέστε κλήσεις από το 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 στη συνομιλία.