Τηλεφωνία: SIP, LiveKit και G.711
Σε αυτήν τη σελίδα
Ενημερώθηκε στις 3 Νοεμβρίου 2026, με βάση τον οδηγό SIP Phone Calls της xAI, τη σελίδα Speech to Speech και το παράδειγμα Phone Voice Agent από το cookbook. Η xAI μπορεί να απαντά σε κλήσεις στον δικό σας αριθμό (απευθείας SIP, υπογεγραμμένο webhook, μεταφορά, τερματισμός, πλήκτρα DTMF), παράλληλα με μια γέφυρα μέσω του δικού σας διακομιστή. Πηγές: SIP Phone Calls · Speech to Speech · Phone Voice Agent.
Σύνδεση του Voice Agent API με το τηλεφωνικό δίκτυο
Το Voice Agent API μπορεί να λαμβάνει τηλεφωνικές κλήσεις: οι πελάτες σας καλούν έναν συνηθισμένο αριθμό και συνομιλούν με τον πράκτορα Grok. Υπάρχουν τρεις διαδρομές για να το επιτύχετε αυτό, από την πιο ενσωματωμένη έως την πιο ευέλικτη.
Διαδρομή 1: Απευθείας SIP με την xAI
Σε αυτή τη λειτουργία, η xAI απαντά η ίδια στην κλήση. Η κλήση καταλήγει στην υποδομή SIP της xAI, η οποία σας ειδοποιεί μέσω webhook· η εφαρμογή σας συνδέεται στην κλήση μέσω WebSocket και καθοδηγεί τον πράκτορα.
- Καταχώριση του αριθμού. Δηλώστε έναν αριθμό “Direct SIP” στην xAI, μαζί με τη διεύθυνση webhook που θα λαμβάνει τις εισερχόμενες κλήσεις. Για αριθμό που σας ανήκει, χρησιμοποιήστε
origin: "byo_trunk": η xAI δεν παρέχει αριθμούς μέσω του API. Η απόκριση περιέχει ένα μυστικό υπογραφής (signing secret), το οποίο επιστρέφεται μόνο μία φορά, οπότε αποθηκεύστε το στο θησαυροφυλάκιο μυστικών σας. - Δρομολόγηση του παρόχου σας. Διαμορφώστε τον πάροχό σας ή το PBX ώστε να στέλνει τις κλήσεις στο
sip:{number}@sip.voice.x.ai. Η xAI δέχεται σηματοδοσία SIP μέσω TLS στη θύρα 5061, ή μέσω TCP/UDP στη θύρα 5060· προτιμήστε το;transport=tlsόταν ο πάροχός σας το υποστηρίζει. - Λήψη του webhook. Για κάθε κλήση, η xAI στέλνει ένα υπογεγραμμένο webhook
realtime.call.incoming. Επαληθεύστε τις κεφαλίδεςwebhook-id,webhook-timestampκαιwebhook-signatureχρησιμοποιώντας το μυστικό υπογραφής και, στη συνέχεια, διαβάστε τοdata.call_id. - Σύνδεση στην κλήση. Ανοίξτε τη σύνδεση
wss://api.x.ai/v1/realtime?call_id={call_id}με το κλειδί API σας (τα εφήμερα διακριτικά δεν γίνονται δεκτά για συνεδρία SIP), στείλτεsession.updateκαι, έπειτα,response.createόταν ο πράκτορας πρέπει να μιλήσει.
import json
import os
import websockets
async def join_call(call_id):
async with websockets.connect(
f"wss://api.x.ai/v1/realtime?call_id={call_id}",
additional_headers={"Authorization": f"Bearer {os.environ['XAI_API_KEY']}"},
) as ws:
await ws.send(json.dumps({
"type": "session.update",
"session": {
"voice": "rex",
"instructions": "You are the customer service agent. Answer in English, briefly.",
"turn_detection": {"type": "server_vad"},
},
}))
await ws.send(json.dumps({"type": "response.create"})) # the agent greets the caller
async for message in ws:
event = json.loads(message)
# same handling as for a regular WebSocket session
Μόλις συνδεθείτε, η συνεδρία λειτουργεί όπως οποιαδήποτε άλλη φωνητική συνεδρία: η xAI αναμεταδίδει τον ήχο του καλούντος και αναπαράγει τον πράκτορα σε αυτόν, χωρίς ο διακομιστής σας να μεταφέρει ήχο.
Μεταφορά ή τερματισμός κλήσης
Δύο κλήσεις REST ελέγχουν τη γραμμή. Το POST /v1/realtime/calls/{call_id}/refer, με ένα target_uri σε μορφή tel: ή sip:, μεταφέρει τον καλούντα· το αίτημα περιμένει την έκβαση της μεταφοράς. Ένα 200 με κενό σώμα σημαίνει ότι ο προορισμός απάντησε· ένα 502 μεταφέρει τον κωδικό απόρριψης SIP και ένα 504 σηματοδοτεί λήξη χρονικού ορίου (timeout). Μετά από μια αποτυχία, η συνεδρία παραμένει ανοιχτή και ο πράκτορας μπορεί να συνεχίσει να μιλά: εναπόκειται σε εσάς να διαβάσετε την απόκριση και, εάν χρειάζεται, να ζητήσετε από τον πράκτορα να εξηγήσει το πρόβλημα. Το POST /v1/realtime/calls/{call_id}/hangup τερματίζει την κλήση.
Είσοδος από πληκτρολόγιο (DTMF)
Σε μια συνεδρία SIP, τα πλήκτρα που πατά ο καλών αποθηκεύονται προσωρινά σε buffer και στη συνέχεια περνούν στο μοντέλο ως κείμενο μόλις ο καλών πατήσει #, μετά από 2,5 δευτερόλεπτα χωρίς νέο πλήκτρο, ή μόλις αρχίσει να μιλά. Ο πελάτης σας λαμβάνει ένα συμβάν input_audio_buffer.dtmf_event_received ανά πλήκτρο, ώστε να μπορείτε να κρατάτε αρχείο. Για να επιτρέψετε στον πράκτορα να πατάει μόνος του πλήκτρα, για παράδειγμα για να πλοηγηθεί στο τηλεφωνικό μενού μιας άλλης υπηρεσίας, προσθέστε {"type": "function", "name": "send_dtmf"} στα εργαλεία του, χωρίς παραμέτρους: το API παρέχει το σχήμα και στέλνει τους τόνους, και εσείς δεν πρέπει να απαντάτε σε αυτές τις κλήσεις συναρτήσεων. Αυτά τα συμβάντα υπάρχουν μόνο σε συνεδρία SIP.
Τεκμηριωμένοι πάροχοι
Ο οδηγός της xAI περιγράφει αναλυτικά τη ρύθμιση για τέσσερις παρόχους (Twilio, με ενεργοποιημένο το Elastic SIP Trunking και τη μεταφορά κλήσεων στο trunk εάν μεταφέρετε κλήσεις· Bandwidth· Telnyx· και Plivo) καθώς και για οποιονδήποτε πάροχο, κέντρο επαφών ή PBX που μπορεί να ανοίξει μια διαδρομή SIP προς τη διεύθυνση του αριθμού σας. Όσον αφορά τον κωδικοποιητή (codec), το παράδειγμα της Telnyx ζητά να ενεργοποιήσετε τουλάχιστον το G.711 μ-law, το G.711 A-law ή το G.722.
Διαδρομή 2: Μια γέφυρα μέσω του δικού σας διακομιστή
Εάν θέλετε να διατηρήσετε τον έλεγχο της ροής ήχου, ο διακομιστής σας λαμβάνει τον ήχο της κλήσης και τον αναμεταδίδει σε μια κανονική συνεδρία WebSocket. Αυτή είναι η αρχιτεκτονική του παραδείγματος Phone Voice Agent από το cookbook της xAI: το Twilio μεταδίδει τον ήχο της κλήσης σε μ-law μέσω των Media Streams του, και ο διακομιστής τον περνά στο API ως έχει, χωρίς μετατροπή, και προς τις δύο κατευθύνσεις.
# Phone call → carrier → your server → xAI WebSocket
import base64
import json
import os
import websockets
async def relay_call(call_audio_stream):
ws = await websockets.connect(
"wss://api.x.ai/v1/realtime?model=grok-voice-latest",
additional_headers={"Authorization": f"Bearer {os.environ['XAI_API_KEY']}"},
)
# G.711 μ-law at 8000 Hz, the North American phone network format
await ws.send(json.dumps({
"type": "session.update",
"session": {
"voice": "rex",
"instructions": "Customer service agent.",
"turn_detection": {"type": "server_vad"},
"audio": {
"input": {"format": {"type": "audio/pcmu", "rate": 8000}},
"output": {"format": {"type": "audio/pcmu", "rate": 8000}},
},
},
}))
async for chunk in call_audio_stream:
await ws.send(json.dumps({
"type": "input_audio_buffer.append",
"audio": base64.b64encode(chunk).decode(),
}))
Το API δέχεται εγγενώς και τις δύο παραλλαγές του G.711, αποφεύγοντας οποιαδήποτε μετακωδικοποίηση (transcoding): audio/pcmu (μ-law, το πρότυπο για τη Βόρεια Αμερική και την Ιαπωνία) και audio/pcma (A-law, το πρότυπο στην Ευρώπη και στις περισσότερες άλλες χώρες), και τα δύο στα 8000 Hz.
{
"audio": {
"input": {"format": {"type": "audio/pcma", "rate": 8000}},
"output": {"format": {"type": "audio/pcma", "rate": 8000}}
}
}
Τα πλήκτρα DTMF και οι κλήσεις REST για μεταφορά και τερματισμό ανήκουν στη διαδρομή απευθείας SIP: σε μια γέφυρα, ο πάροχός σας τα διαχειρίζεται.
Διαδρομή 3: Ένα πλαίσιο εργασίας πραγματικού χρόνου
Η τεκμηρίωση της xAI αναφέρει δύο έτοιμες ενσωματώσεις: τους LiveKit Agents και το Pipecat. Αυτά διαχειρίζονται τη μεταφορά σε πραγματικό χρόνο (WebRTC, δωμάτια, δρομολόγηση κλήσεων) και συνδέουν τον φωνητικό πράκτορα Grok στο κατάλληλο σημείο, γλιτώνοντας μια ομάδα που δεν επιθυμεί να χτίσει από την αρχή ένα στρώμα τηλεφωνίας από αυτή τη διαδικασία.
Σε παραγωγή
Διαχείριση σιωπών. Στο τηλέφωνο, ένας καλών που σιωπά αφήνει μια νεκρή γραμμή. Το turn_detection.idle_timeout_ms κάνει τον πράκτορα να επικοινωνεί με τον καλούντα μετά από σιωπή διάρκειας της επιλογής σας (μάθημα 6).
Συνέχιση συνομιλίας σε νέα κλήση. Η επαναφορά συνεδρίας λειτουργεί και μέσω SIP: ενεργοποιήστε το resumption.enabled στην πρώτη κλήση και κρατήστε το call_id της. Όταν ο πελάτης καλέσει ξανά, ανοίξτε το wss://api.x.ai/v1/realtime?call_id={new_call_id}&conversation_id={previous_call_id} και στείλτε ξανά το ίδιο session.update. Το ιστορικό λήγει μετά από 30 λεπτά αδράνειας.
Ακολουθήστε τους κανόνες. Ενημερώστε τους καλούντες ότι μιλούν με τεχνητή νοημοσύνη και, εάν καταγράφετε κλήσεις, αναφέρετέ το στην αρχή. Για δεδομένα υγείας, η xAI αναφέρει ότι μια συμφωνία συνεργάτη επιχειρήσεων (BAA) μπορεί να υπογραφεί μετά από ένα ερωτηματολόγιο.
Μετρήστε την καθυστέρησή σας. Η καθυστέρηση που αντιλαμβάνονται οι καλούντες αθροίζει το τηλεφωνικό δίκτυο, τη γέφυρά σας (αν έχετε) και τη δημιουργία απόκρισης. Μετρήστε την από άκρο σε άκρο σε πραγματικές κλήσεις και διατηρήστε γρήγορες τις συναρτήσεις που καλεί ο πράκτορας κατά τη διάρκεια της συνομιλίας.
Βασικά σημεία
- Με το απευθείας SIP, η xAI απαντά στον αριθμό σας, σας ειδοποιεί με ένα υπογεγραμμένο webhook
realtime.call.incomingκαι εσείς συνδέεστε στην κλήση μέσωwss://api.x.ai/v1/realtime?call_id=… - Το
referμεταφέρει την κλήση (η έκβαση επιστρέφεται στην απόκριση HTTP) και τοhangupτην τερματίζει - Τα πλήκτρα DTMF φτάνουν στο μοντέλο και καταγράφονται μέσω του
input_audio_buffer.dtmf_event_received· το εργαλείοsend_dtmfεπιτρέπει στον πράκτορα να πατάει πλήκτρα - Σε μια γέφυρα μέσω του διακομιστή σας, το εγγενές G.711 (
audio/pcmu,audio/pcma) αποφεύγει τη μετακωδικοποίηση - Οι LiveKit Agents και το Pipecat είναι οι ενσωματώσεις που αναφέρει η xAI