Μετάβαση στο κύριο περιεχόμενο
Ελληνικά— Επιλέξτε γλώσσα
Μενού

Τηλεφωνία: SIP, LiveKit και G.711

Μάθημα 15 / 16 Ενημερώθηκε 3 Νοεμβρίου 2026 Για developers
Σε αυτήν τη σελίδα
  1. Σύνδεση του Voice Agent API με το τηλεφωνικό δίκτυο
  2. Διαδρομή 1: Απευθείας SIP με την xAI
  3. Διαδρομή 2: Μια γέφυρα μέσω του δικού σας διακομιστή
  4. Διαδρομή 3: Ένα πλαίσιο εργασίας πραγματικού χρόνου
  5. Σε παραγωγή
  6. Βασικά σημεία

Ενημερώθηκε στις 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 και καθοδηγεί τον πράκτορα.

  1. Καταχώριση του αριθμού. Δηλώστε έναν αριθμό “Direct SIP” στην xAI, μαζί με τη διεύθυνση webhook που θα λαμβάνει τις εισερχόμενες κλήσεις. Για αριθμό που σας ανήκει, χρησιμοποιήστε origin: "byo_trunk": η xAI δεν παρέχει αριθμούς μέσω του API. Η απόκριση περιέχει ένα μυστικό υπογραφής (signing secret), το οποίο επιστρέφεται μόνο μία φορά, οπότε αποθηκεύστε το στο θησαυροφυλάκιο μυστικών σας.
  2. Δρομολόγηση του παρόχου σας. Διαμορφώστε τον πάροχό σας ή το PBX ώστε να στέλνει τις κλήσεις στο sip:{number}@sip.voice.x.ai. Η xAI δέχεται σηματοδοσία SIP μέσω TLS στη θύρα 5061, ή μέσω TCP/UDP στη θύρα 5060· προτιμήστε το ;transport=tls όταν ο πάροχός σας το υποστηρίζει.
  3. Λήψη του webhook. Για κάθε κλήση, η xAI στέλνει ένα υπογεγραμμένο webhook realtime.call.incoming. Επαληθεύστε τις κεφαλίδες webhook-id, webhook-timestamp και webhook-signature χρησιμοποιώντας το μυστικό υπογραφής και, στη συνέχεια, διαβάστε το data.call_id.
  4. Σύνδεση στην κλήση. Ανοίξτε τη σύνδεση 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