Open in
Πραγματοποιήστε εξερχόμενες κλήσεις (API)
Ενεργοποιήστε μια εξερχόμενη κλήση με AI από τον δικό σας κώδικα — για ροές ερευνών, παρακολούθησης ή επιβεβαίωσης.
Οι εξερχόμενες κλήσεις σάς επιτρέπουν να δώσετε έναν αριθμό προορισμού και μια διαμόρφωση πράκτορα στο ThunderPhone, ώστε ο AI πράκτορας να πραγματοποιεί την κλήση για λογαριασμό σας. Συνήθεις περιπτώσεις χρήσης:
- Επιβεβαιώσεις ραντεβού
- Επανακλήσεις για έρευνες
- Επακόλουθες ενέργειες «δεύτερης προσπάθειας» μετά από αναπάντητη κλήση
- Ειδοποιήσεις τύπου αποστολής
Προϋποθέσεις
- Επιλέξτε έναν αριθμό με δυνατότητα εξερχόμενων κλήσεων
Χρησιμοποιήστε έναν αριθμό που σας ανήκει μέσω μιας σύνδεσης VoIP, ή ζητήστε άδεια να χρησιμοποιείτε τους αριθμούς σας ThunderPhone για εξερχόμενες κλήσεις από τη σελίδα Αριθμοί τηλεφώνου. Οι αριθμοί ThunderPhone ξεκινούν μόνο για εισερχόμενες κλήσεις. Το ThunderPhone εξετάζει κάθε αίτημα χειροκίνητα· μόλις εγκριθεί, οι συγκεκριμένοι αριθμοί μπορούν να πραγματοποιούν κλήσεις έως το εγκεκριμένο ημερήσιο όριο (το οποίο επαναφέρεται στις 00:00 UTC) και να εκτελούν καμπάνιες, ενώ μπορείτε να ζητήσετε υψηλότερο όριο. Οι αριθμοί VoIP πελατών δεν έχουν ημερήσιο όριο, επομένως τους συνιστούμε για εξερχόμενες κλήσεις. Δείτε Χρησιμοποιήστε τους δικούς σας αριθμούς.
- Δημιουργήστε έναν πράκτορα
Μια προτροπή προσανατολισμένη σε εξερχόμενες κλήσεις συνήθως ξεκινά με τον πράκτορα να συστήνεται και να αναφέρει τον σκοπό του — «Γεια σας, εδώ η Acme, σας καλώ για να επιβεβαιώσω το ραντεβού σας για αύριο στις 3 μ.μ.…» Ορίστε το
outbound_speak_orderσεagent_first(η προεπιλογή). - Διατηρήστε θετικό υπόλοιπο
Οι εξερχόμενες κλήσεις επιστρέφουν
402 Payment Requiredεάν το υπόλοιπο είναι ≤$0.00. Φορτίστε το υπόλοιπό σας ή ενεργοποιήστε την αυτόματη επαναφόρτιση στην ενότητα Οργανισμός → Ρυθμίσεις χρέωσης του πίνακα ελέγχου. Το κλειδί σαςsk_live_μπορεί να ελέγξει το υπόλοιπο μεGET /v1/billing, αλλά δεν μπορεί να φορτίσει το υπόλοιπο ή να αλλάξει την αυτόματη επαναφόρτιση.
Πραγματοποιήστε μια κλήση με αποθηκευμένο πράκτορα
Η απλούστερη διαδρομή — αναφέρετε έναν πράκτορα με το id του:
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": "+14155552671",
"agent_id": 12
}'Απόκριση:
{ "call_id": 987654321, "status": "initiated" }Πραγματοποιήστε μια κλήση με ενσωματωμένη διαμόρφωση
Αν θέλετε μια εφάπαξ προτροπή που δεν αξίζει να αποθηκευτεί ως πράκτορας,
περάστε το config αντί για αυτό. Η δομή αντιστοιχεί στο σχήμα απόκρισης του
webhook call.incoming:
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": "+14155552671",
"config": {
"prompt": "You are confirming Jane Doe appointment for 3pm tomorrow…",
"voice": "john",
"product": "spark"
}
}'Ελέγξτε τι συμβαίνει μετά τον τελευταίο έλεγχο σιωπής
Μπορείτε επίσης να περάσετε τις ίδιες ρυθμίσεις τελικής ενέργειας σιωπής στο ενσωματωμένο config που χρησιμοποιούν οι αποθηκευμένοι πράκτορες:
{
"from_number": "+[REDACTED_PHONE]",
"to_number": "+[REDACTED_PHONE]",
"config": {
"silence_final_action": "hang_up"
}
}Χρησιμοποιήστε το silence_final_action για να επιλέξετε τι συμβαίνει μετά τον τελευταίο έλεγχο σιωπής. Μπορείτε επίσης να περάσετε το silence_final_message και, όταν η τελική ενέργεια είναι μεταφορά, το silence_transfer_destination.
Προσθέστε μια λίστα λέξεων στο ενσωματωμένο config
Οι ενσωματωμένες εξερχόμενες κλήσεις μπορούν να περιλαμβάνουν την ίδια λίστα words με τους αποθηκευμένους πράκτορες.
Χρησιμοποιήστε το όταν θέλετε η κλήση να ακολουθεί προσαρμοσμένους κανόνες προφοράς ή αναγνώρισης
χωρίς να αποθηκεύσετε πρώτα έναν πράκτορα.
{
"from_number": "+[REDACTED_PHONE]",
"to_number": "+[REDACTED_PHONE]",
"config": {
"prompt": "[REDACTED_LITERAL]",
"voice": "john",
"product": "spark",
"words": []
}
}Παρακολουθήστε την κλήση
Μια απόκριση με χρόνο queued_at σημαίνει ότι η εξερχόμενη χωρητικότητα του ThunderPhone χρησιμοποιείται: η κλήση πραγματοποιείται όταν υπάρχει διαθέσιμη χωρητικότητα, εντός 10 λεπτών, και τερματίζεται με end_reason outbound_queue_timeout αν δεν υπάρξει διαθέσιμη χωρητικότητα. Δεν χρειάζεται να προσπαθήσετε ξανά. Δείτε τις κλήσεις σε ουρά.
Παράλληλα, εγγραφείτε στην
ειδοποίηση ιστού telephony.complete —
τον ταχύτερο τρόπο για να γνωρίζετε ότι μια κλήση ολοκληρώθηκε. Μπορείτε επίσης να εγγραφείτε στο
call.status_changed για ζωντανές
ενημερώσεις προόδου, όπως κλήση, απάντηση, φωνητικό μήνυμα και αλλαγές στην αναμονή.
Αν δεν μπορείτε να δέχεστε εισερχόμενες ειδοποιήσεις ιστού, ελέγχετε το GET /v1/calls/{call_id} κάθε
λίγα δευτερόλεπτα· η καταχώριση περιλαμβάνει τα end_reason, duration_seconds
και τη διεύθυνση URL της εγγραφής μόλις ολοκληρωθεί η κλήση.
Αν ο πράκτοράς σας έχει ρυθμιστεί ώστε να εξάγει δομημένα δεδομένα μετά την κλήση, αυτά τα δεδομένα παραδίδονται ξεχωριστά αφού ολοκληρωθεί η οριστικοποίηση.
Μεταβιβάστε μεταβλητές ανά κλήση σε έναν αποθηκευμένο πράκτορα
Οι αποθηκευμένοι πράκτορες μπορούν να χρησιμοποιούν δεσμευτικά θέσης όπως {{name}} ή {{name|there}} στο
κείμενο της προτροπής. Όταν πραγματοποιείτε μια εξερχόμενη κλήση με agent_id, μεταβιβάστε
το variables με τις τιμές για τη συγκεκριμένη κλήση:
{
"from_number": "+[REDACTED_PHONE]",
"to_number": "+[REDACTED_PHONE]",
"agent_id": 12,
"variables": {
"name": "Jordan"
}
}Χρησιμοποιήστε τιμές συμβολοσειράς με κλειδί το όνομα του δεσμευτικού θέσης. Αυτές οι μεταβλητές ισχύουν για
αποθηκευμένους πράκτορες· το ενσωματωμένο παράδειγμα config αυτού του οδηγού δεν τις χρησιμοποιεί.
Καταστάσεις αποτυχίας που αξίζει να χειριστείτε
| Σφάλμα | Διόρθωση |
|---|---|
402 Payment Required | Προσθέστε υπόλοιπο ή ενεργοποιήστε την αυτόματη ανανέωση |
400 με code: destination_not_allowed | Το ThunderPhone δεν καλεί αυτόν τον αριθμό: μη έγκυρους αριθμούς, αριθμούς έκτακτης ανάγκης, αριθμούς υψηλής χρέωσης, σύντομους κωδικούς, χώρες υπό κυρώσεις ή πολιτεία των ΗΠΑ που ο οργανισμός σας έχει αποκλείσει για εξερχόμενες κλήσεις. Από αριθμούς ThunderPhone, επιτρέπονται οι συνήθεις αριθμοί ΗΠΑ και Καναδά, καθώς και ορισμένοι διεθνείς προορισμοί, οι οποίοι χρεώνονται με την τιμή του προορισμού. Το reason αναφέρει ποιο ισχύει· δείτε τους αποκλεισμένους προορισμούς |
409 με retryable: false για αριθμό ThunderPhone | Ακολουθήστε το code: ζητήστε εξερχόμενες κλήσεις στη σελίδα «Αριθμοί τηλεφώνου», περιμένετε μια εκκρεμή αξιολόγηση ή χρησιμοποιήστε άλλον επιλέξιμο αριθμό |
429 με code: platform_outbound_daily_limit_reached | Ο οργανισμός έχει ήδη χρησιμοποιήσει τις σημερινές εξερχόμενες κλήσεις από αριθμούς ThunderPhone. Περιμένετε έως το resets_at (00:00 UTC), ζητήστε υψηλότερο όριο στη σελίδα «Αριθμοί τηλεφώνου» ή καλέστε από αριθμό στη δική σας σύνδεση VoIP |
429 με code: concurrent_call_limit_reached | Ο οργανισμός έχει τόσες κλήσεις σε εξέλιξη όσο το όριο ταυτόχρονων κλήσεων (20 από προεπιλογή, συμπεριλαμβανομένων εισερχόμενων, εξερχόμενων, διαδικτυακών και δοκιμαστικών κλήσεων). Επαναλάβετε την προσπάθεια μετά από τα δευτερόλεπτα της κεφαλίδας Retry-After ή όταν τερματιστεί μια κλήση· στείλτε email στο support@thunderphone.com για να αυξήσετε το όριο |
429 με code: outbound_queue_full | Ο οργανισμός έχει 50 κλήσεις σε ουρά σε αναμονή. Επαναλάβετε την προσπάθεια μετά από τα δευτερόλεπτα της κεφαλίδας Retry-After |
429 με code: same_number_too_soon | Καλέσατε τον ίδιο to_number πριν από λιγότερο από 10 δευτερόλεπτα. Επαναλάβετε την προσπάθεια μετά από τα δευτερόλεπτα της κεφαλίδας Retry-After |
409 με retryable: false για αριθμό VoIP πελάτη | Διορθώστε την κατάσταση που υποδεικνύει το code· για αποτυχίες επαλήθευσης, εκτελέστε POST /v1/phone-numbers/{id}/verify-voip |
διένεξη ιδεμποτικότητας 409 | Επαναχρησιμοποιήστε το κλειδί μόνο με το αρχικό κανονικοποιημένο αίτημα ή στείλτε νέο κλειδί |
404 from_number is not registered to this organization | Επιβεβαιώστε ότι το from_number αντιστοιχεί σε ενεργό αριθμό τηλεφώνου στον οργανισμό σας. Ένας αριθμός που βρίσκεται ήδη σε ενεργοποίηση, έχει αποτύχει, αποδεσμεύεται ή έχει αποδεσμευτεί επιστρέφει επίσης αυτή την απόκριση |
500 μόνο με πεδίο detail | Δεν έχει διαμορφωθεί εξερχόμενος κορμός. Επικοινωνήστε με την υποστήριξη· δεν πρόκειται για πρόβλημα κατάστασης αριθμού που μπορείτε να διορθώσετε |
502 Bad Gateway | Παροδική αποτυχία SIP / LiveKit· μπορείτε να επαναλάβετε την προσπάθεια με ασφάλεια |
Δείτε την αναφορά εξερχόμενων κλήσεων
για τον πλήρη σταθερό κατάλογο κωδικών επιλεξιμότητας και τις δύο μορφές απόκρισης 409.
Αν ένας ενεργός αριθμός καταστεί μη επιλέξιμος αφού γίνει δεκτό το αίτημα αλλά πριν
πραγματοποιηθεί η κλήση, ο τελικός έλεγχος επιστρέφει το μη επαναλήψιμο φορτίο 409.
Έλεγχος χρόνου αναμονής
Οι εξερχόμενες κλήσεις που διαρκούν πολύ επειδή ο καλούμενος αργεί να απαντήσει
(δέντρα IVR, ουρές) μπορούν να περιοριστούν με το max_hold_seconds στην κλήση ή ορίζοντάς το στον αποθηκευμένο πράκτορα:
{
"from_number": "+15551234567",
"to_number": "+14155552671",
"agent_id": 12,
"max_hold_seconds": 120
}Ο πράκτορας τερματίζει την κλήση αν δεν έχει ληφθεί ανθρώπινος ήχος τα τελευταία N δευτερόλεπτα. Η προεπιλογή είναι 900 δευτερόλεπτα (15 λεπτά).
Αν ορίσετε το max_hold_seconds τόσο στον αποθηκευμένο πράκτορα όσο και στο αίτημα εξερχόμενης κλήσης, χρησιμοποιείται για τη συγκεκριμένη κλήση η τιμή ανά κλήση.
Επόμενα βήματα
Κάθε πεδίο αιτήματος και κωδικός σφάλματος.
Μεταδώστε τις ολοκληρωμένες εξερχόμενες κλήσεις στο σύστημά σας.
Ρυθμίστε αυτόματη επαναφόρτιση ώστε οι εξερχόμενες κλήσεις να μην αποτυγχάνουν λόγω υπολοίπου.
Εκτελέστε δοκιμαστικά τον εξερχόμενο πράκτορά σας πριν από την παραγωγή.