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

Developer cookbook

Διαχείριση εισερχόμενων κλήσεων (API)

Από άκρο σε άκρο: ρυθμίστε έναν πράκτορα, αντιστοιχίστε τον σε έναν αριθμό τηλεφώνου, δεχτείτε μια κλήση και εξετάστε την απομαγνητοφώνηση.

Η τυπική ροή «απάντηση σε τηλέφωνο με AI», από το τερματικό σας. Θα:

  1. Δημιουργήσετε έναν πράκτορα με προτροπή και φωνή.
  2. Εκχωρήσετε (ή προσθέσετε) έναν τηλεφωνικό αριθμό και ορίσετε τον πράκτορα ως χειριστή εισερχόμενων κλήσεων.
  3. Καλέσετε τον αριθμό. Παρατηρήστε το αρχείο καταγραφής κλήσης, την απομαγνητοφώνηση και την εγγραφή.

Συνολικές κλήσεις API: τέσσερις. Συνολικός χρόνος: λιγότερο από πέντε λεπτά.

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

Ένας πράκτορας συνδυάζει την προτροπή, τη φωνή και τη βαθμίδα προϊόντος που θα διαχειρίζονται την κλήση. Μπορείτε επίσης να ορίσετε όρια κλήσης, όπως max_call_duration_seconds και ring_duration_seconds, στον πράκτορα. Για εξερχόμενες κλήσεις, μπορείτε επίσης να ορίσετε το max_hold_seconds για να περιορίσετε το χρονικό διάστημα που ο πράκτορας περιμένει σε αναμονή πριν τερματίσει την κλήση. Οι πράκτορες Bolt υποστηρίζουν επίσης τα audio_tier, endpointing και intelligence για να ελέγχετε τον τρόπο με τον οποίο ακούν και απαντούν: το intelligence είναι core ή pro, και το audio_tier (Ακρόαση) είναι lite, standard, plus ή max (το Max δεν είναι γενικά διαθέσιμο). Οι παλαιότερες τιμές (lite και standard για το intelligence· lean, hearing και deep_hearing για την ακρόαση) εξακολουθούν να γίνονται δεκτές. Οι πράκτορες πλήρους αμφίδρομης λειτουργίας διατηρούν την ίδια φωνή στις υποστηριζόμενες γλώσσες, επομένως η εναλλαγή φωνής ανά γλώσσα δεν ισχύει σε αυτές τις κλήσεις. Οι πράκτορες υποστηρίζουν επίσης τα intro_clip και intro_ring_count για την αναπαραγωγή μιας προηχογραφημένης εισαγωγής και έως δύο κλήσεων πριν μιλήσει ο πράκτορας. Οι νέοι πράκτορες χρειάζονται επίσης μια ζώνη ώρας. Αν ο πράκτοράς σας είναι πολύγλωσσος, μπορείτε να ορίσετε το language_switching για να ελέγξετε αν ζητά άδεια πριν αλλάξει γλώσσα ή αν ακολουθεί τη γλώσσα του καλούντος. Μπορείτε επίσης να ορίσετε το words στον πράκτορα για να ελέγχετε πώς προφέρει συγκεκριμένους όρους και ποιους όρους αναζητά. Δείτε τους Πράκτορες για κάθε πεδίο διαμόρφωσης· το ελάχιστο είναι:

curl -X POST https://api.thunderphone.com/v1/agents \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name":    "Acme Support",
    "prompt":  "You are a friendly support agent for Acme. Help callers with orders and returns. Keep answers short.",
    "voice":   "john",
    "product": "bolt"
  }'

Αποθηκεύστε το id που επιστρέφεται — θα το χρειαστείτε στο βήμα 2.

2. Αποκτήστε έναν τηλεφωνικό αριθμό

Αν χρειάζεστε απλώς έναν αριθμό για να καλέσετε, αποκτήστε έναν αριθμό ThunderPhone από το απόθεμα της ThunderPhone:

curl -X POST https://api.thunderphone.com/v1/phone-numbers \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"area_code": "415"}'

Η απόκριση περιλαμβάνει ένα id και έναν number σε E.164. Οι αριθμοί ThunderPhone ξεκινούν με status="provisioning" και γίνονται active μέσα σε λίγα δευτερόλεπτα — εκτελέστε έλεγχο GET /v1/phone-numbers/{id} για να παρακολουθήσετε τη μετάβαση, αν το χρειάζεστε.

3. Αντιστοιχίστε τον πράκτορα

Συσχετίστε τον πράκτορα από το βήμα 1 με την εισερχόμενη κατεύθυνση του αριθμού:

curl -X PATCH https://api.thunderphone.com/v1/phone-numbers/{phone_id} \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"inbound_agent_id": 12}'

Αυτό ήταν — ο αριθμός είναι ενεργός. Αφού εγκριθούν οι εξερχόμενες κλήσεις για τον οργανισμό σας, μπορείτε επίσης να ορίσετε outbound_agent_id στο ίδιο PATCH. Μέχρι τότε, το API απορρίπτει αυτή την αντιστοίχιση με 400.

Αν δρομολογείτε εισερχόμενες κλήσεις μέσω webhook διαμόρφωσης αντί για σταθερό inbound_agent_id, αυτό το webhook μπορεί πλέον να επιστρέφει timezone ανά κλήση μαζί με agent_id και variables. Για πράκτορες Bolt, μπορείτε επίσης να ορίσετε τα audio_tier, endpointing και intelligence στον πράκτορα κατά τις εγγραφές μέσω API. Το API εξακολουθεί να δέχεται το παλαιότερο όνομα eagerness ως ψευδώνυμο για το endpointing. Αν ο πράκτοράς σας χρησιμοποιεί συνδέσεις API με trigger="call_start", το ThunderPhone μπορεί να εκτελεί αυτά τα εργαλεία μία φορά στην αρχή κάθε τηλεφωνικής κλήσης, πριν από τον χαιρετισμό, χρησιμοποιώντας τα αποθηκευμένα call_start_arguments τους.

Επιστροφές κλήσεων προς τις εξερχόμενες κλήσεις σας

Όταν κάποιος καλέσει ξανά έναν αριθμό που τον κάλεσε τις τελευταίες 30 ημέρες, ο πράκτορας που απαντά λαμβάνει μια σύντομη σημείωση ιστορικού για εκείνη την κλήση: πότε πραγματοποιήθηκε, από ποιον πράκτορα και τι συνέβη (καμία απάντηση, φωνητικό μήνυμα ή συνομιλία). Ένας αριθμός χωρίς εισερχόμενο πράκτορα στέλνει τις ίδιες λεπτομέρειες στο webhook διαμόρφωσής σας ως returning_call. Αν αυτός ο αριθμός δεν έχει webhook ή το webhook λήξει χρονικά ή δεν είναι προσβάσιμο, η κλήση δρομολογείται στον πράκτορα που πραγματοποίησε την προηγούμενη κλήση αντί να τερματιστεί. Η αναγνώριση καλούντος μπορεί να πλαστογραφηθεί, επομένως η σύνοψη και οι μεταβλητές της προηγούμενης κλήσης κοινοποιούνται μόνο αν ένας διαχειριστής ενεργοποιήσει την επιλογή Κοινοποίηση λεπτομερειών της προηγούμενης κλήσης στην περιοχή Οργανισμός → Γενικά → Επιστροφές κλήσεων. Δείτε Επιστροφές κλήσεων.

4. Δεχτείτε μια κλήση

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

Ενώ η κλήση βρίσκεται σε εξέλιξη, εμφανίζεται στο GET /v1/calls με status="in_progress". Όταν ολοκληρωθεί, η εγγραφή ενημερώνεται με end_reason, duration_seconds, billable_minutes και (τελικά) ένα URL εγγραφής και αξιολόγηση AI.

Οι εισερχόμενες κλήσεις προσμετρώνται στο όριο ταυτόχρονων κλήσεων του οργανισμού σας (20 κλήσεις σε εξέλιξη από προεπιλογή, κοινό με τις εξερχόμενες, τις διαδικτυακές και τις δοκιμαστικές κλήσεις). Μια κλήση που φτάνει όταν το όριο έχει καλυφθεί απορρίπτεται πριν απαντήσει ο πράκτορας και τερματίζεται, δεν χρεώνεται και καταγράφεται ως αποτυχημένη κλήση με αιτία τερματισμού concurrent_call_limit_reached. Στείλτε email στο support@thunderphone.com αν χρειάζεστε υψηλότερο όριο.

5. Επιθεωρήστε τα αποτελέσματα

Ανακτήστε τη λίστα των πρόσφατων κλήσεων:

curl 'https://api.thunderphone.com/v1/calls?limit=5' \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Ανακτήστε την απομαγνητοφώνηση:

curl https://api.thunderphone.com/v1/calls/{call_id}/transcript \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Και το URL της εγγραφής (βραχύβιο, υπογεγραμμένο):

curl https://api.thunderphone.com/v1/calls/{call_id}/audio \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Αν έχετε εγγραφεί στη telephony.complete διαδικτυακή ειδοποίηση, θα λάβετε τα ίδια δεδομένα ως POST στον διακομιστή σας — δείτε call.complete.

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


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