> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt. # Anpassad LLM-integrering ## Översikt ElevenAgents [inbyggda Twilio-integrering](/docs/sv/eleven-agents/phone-numbers/twilio-integration/native-integration) omfattar användningsfallet där ElevenLabs är värd för LLM:en. Använd den här guiden när du behöver full kontroll över LLM-hjärnan på din egen server — din egen modell, RAG-pipeline, routning av funktionsanrop eller annat resonemang på serversidan — och agenten fortfarande finns på ett Twilio-telefonnummer. Den anpassade LLM-delen levereras av [Speech Engine SDK](/docs/sv/eleven-api/guides/cookbooks/speech-engine), som öppnar en WebSocket mellan ElevenLabs och din server så att din LLM kan strömma svar medan samtalet pågår. Twilio-delen använder [Media Streams](https://www.twilio.com/docs/voice/media-streams) för att vidarebefordra samtalsljud till agenten. ## Arkitektur Speech Engine SDK exponerar två WebSocket-slutpunkter i agentens konversationssystem: * **Brain WebSocket** körs på din server. ElevenLabs ansluter till den för att leverera transkript och ta emot LLM-genererad text. * **Conversation WebSocket** körs på ElevenLabs. Klienter ansluter till den för att skicka in ljud och ta emot syntetiserat ljud. Twilio-bryggan ansluter via en signerad URL och vidarebefordrar μ-law-ljud i båda riktningarna. Eftersom Twilio Media Streams och Speech Engine båda använder `ulaw_8000` vidarebefordrar bryggan base64-kodat ljud utan omkodning. ```mermaid sequenceDiagram participant Caller participant Twilio participant Bridge as Bridge Server participant EL as ElevenLabs (conversation WS) participant Brain as Brain Server Caller->>Twilio: Dial number Twilio->>Bridge: POST /incoming-call Bridge-->>Twilio: TwiML Twilio->>Bridge: WebSocket /media-stream Bridge->>EL: Open conversation WebSocket (signed URL) loop Conversation Caller->>Twilio: Speak Twilio->>Bridge: media event (μ-law base64) Bridge->>EL: user_audio_chunk EL->>Brain: user_transcript Brain-->>EL: agent_response (streamed) EL->>Bridge: audio event (μ-law base64) Bridge->>Twilio: media event Twilio->>Caller: Play audio end ``` Bryggan och brain-servern kan köras i samma process om det passar — exemplet nedan kombinerar dem. ## När du ska använda det här mönstret Både den här guiden och den [inbyggda Twilio-integreringen](/docs/sv/eleven-agents/phone-numbers/twilio-integration/native-integration) placerar en agent på ett Twilio-telefonnummer. Skillnaden är vem som äger LLM:en: * **Inbyggd integrering**: ElevenLabs är värd för LLM:en och du konfigurerar den via agenten. Enklare. * **Anpassad LLM via Speech Engine SDK** (den här guiden): du är värd för LLM:en på din egen server. Full kontroll över modellen, RAG, funktionsanrop och affärslogik. Fler rörliga delar. Om din LLM-logik ryms inom standardkonfigurationen för agenten bör du använda den inbyggda integreringen. Använd den här guiden när din brain behöver köra kod i din egen infrastruktur. Det här mönstret använder Speech Engine SDK, som använder en WebSocket-anslutning för att kommunicera mellan din server och ElevenLabs API. Du kan också använda guiden [Custom LLM](/docs/sv/eleven-agents/customization/llm/custom-llm), som använder en OpenAI-kompatibel HTTP-slutpunkt i stället för Speech Engine SDK. Den största skillnaden mellan de två är WebSockets jämfört med HTTP-förfrågningar. Med WebSockets upprätthåller du en enda anslutning i stället för att upprätta en ny HTTP-anslutning för varje tur, vilket kan minska fördröjningen. ## Förutsättningar * Ett [Twilio](https://www.twilio.com/)-konto och ett telefonnummer med röstfunktioner. * En Speech Engine-resurs. Följ [snabbstartsguiden för Speech Engine](/docs/sv/eleven-api/guides/cookbooks/speech-engine) för att skapa en och lära dig mönstret för brain-servern. * En offentlig HTTPS-tunnel (t.ex. [ngrok](https://ngrok.com)). Twilio ringer upp din brygga via det offentliga internet. * Python 3.9+ eller Node.js 18+. ## Konfigurera agenten för μ-law-ljud Twilio Media Streams använder 8 kHz μ-law-ljud. Konfigurera Speech Engine så att den tar emot och skickar ut samma format, så att bryggan inte behöver omkoda. **`configure_engine.py`** ```python title="configure_engine.py" import asyncio import os from elevenlabs import AsyncElevenLabs elevenlabs = AsyncElevenLabs(api_key=os.environ["ELEVENLABS_API_KEY"]) async def update_engine(): await elevenlabs.speech_engine.update( speech_engine_id="seng_8k3m9xr4hjnfg983brhmhkd98n6", asr={"user_input_audio_format": "ulaw_8000"}, tts={ "model_id": "eleven_flash_v2", "agent_output_audio_format": "ulaw_8000", }, speech_engine={ "request_headers": {"x-api-key": os.environ["SHARED_SECRET"]}, }, ) asyncio.run(update_engine()) ``` **`configure-engine.mts`** ```typescript title="configure-engine.mts" import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js"; import "dotenv/config"; const elevenlabs = new ElevenLabsClient({ apiKey: process.env.ELEVENLABS_API_KEY, }); await elevenlabs.speechEngine.update("seng_8k3m9xr4hjnfg983brhmhkd98n6", { asr: { userInputAudioFormat: "ulaw_8000" }, tts: { modelId: "eleven_flash_v2", agentOutputAudioFormat: "ulaw_8000", }, speechEngine: { requestHeaders: { "x-api-key": process.env.SHARED_SECRET! }, }, }); ``` `eleven_flash_v2` håller fördröjningen för text-till-tal låg, vilket är viktigt i ett telefonsamtal. Blocket `request_headers` instruerar ElevenLabs att inkludera `x-api-key: ` i varje WebSocket-anslutning till brain-servern — brain-servern kontrollerar headern för att säkerställa att endast din Speech Engine kan nå den. ## Bygg bryggservern Bryggan har tre rutter: * `POST /incoming-call` — Twilio-webhook. Returnerar TwiML som instruerar Twilio att öppna en Media Stream till `/media-stream`. * `GET /media-stream` — Twilio Media Streams WebSocket. Vidarebefordrar ljud till och från Speech Engine Conversation WebSocket. * `GET /ws` — Brain WebSocket. ElevenLabs ansluter hit när en konversation startar. Kör standardservern `engine.serve()` / `engine.attach()`. #### Installera beroenden **`Python`** ```bash title="Python" pip install "elevenlabs" "aiohttp" "twilio" "python-dotenv" ``` **`Node`** ```bash title="Node" npm install @elevenlabs/elevenlabs-js express ws twilio dotenv openai ``` #### Skapa en signerad URL för Speech Engine Bryggan begär en signerad URL varje gång ett nytt samtal kommer in. URL:en innehåller Speech Engine-ID:t och en engångssignatur, så bryggan behöver aldrig den råa API-nyckeln. **`bridge.py`** ```python title="bridge.py" from elevenlabs import AsyncElevenLabs elevenlabs = AsyncElevenLabs(api_key=os.environ["ELEVENLABS_API_KEY"]) async def signed_url() -> str: response = await elevenlabs.conversational_ai.conversations.get_signed_url( agent_id=os.environ["SPEECH_ENGINE_ID"], ) return response.signed_url ``` **`bridge.mts`** ```typescript title="bridge.mts" import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js"; const elevenlabs = new ElevenLabsClient({ apiKey: process.env.ELEVENLABS_API_KEY, }); async function signedUrl(): Promise { const response = await elevenlabs.conversationalAi.conversations.getSignedUrl({ agentId: process.env.SPEECH_ENGINE_ID!, }); return response.signedUrl; } ``` #### Servera TwiML-svaret När ett samtal kommer in skickar Twilio en POST-förfrågan till `/incoming-call`. Svaret är TwiML som öppnar en Media Stream till bryggans egen `/media-stream` WebSocket. **`bridge.py`** ```python title="bridge.py" from aiohttp import web from twilio.request_validator import RequestValidator validator = RequestValidator(os.environ["TWILIO_AUTH_TOKEN"]) async def incoming_call(request: web.Request) -> web.Response: form = await request.post() signature = request.headers.get("X-Twilio-Signature", "") url = str(request.url) if not validator.validate(url, dict(form), signature): return web.Response(status=403, text="forbidden") host = request.headers.get("X-Forwarded-Host") or request.host twiml = ( '' "" f'' "" ) return web.Response(text=twiml, content_type="text/xml") ``` **`bridge.mts`** ```typescript title="bridge.mts" import express from "express"; import twilio from "twilio"; const app = express(); app.use(express.urlencoded({ extended: false })); app.post( "/incoming-call", twilio.webhook({ validate: true }), (req, res) => { const host = req.headers["x-forwarded-host"] ?? req.get("host"); const twiml = ` `; res.type("text/xml").send(twiml); }, ); ``` `RequestValidator` (Python) och `twilio.webhook({ validate: true })` (Node) kontrollerar headern `X-Twilio-Signature` mot `TWILIO_AUTH_TOKEN`. Utan validering kan vem som helst på det offentliga internet skicka en POST-förfrågan till `/incoming-call` och debitera samtal på ditt konto. #### Koppla ihop Media Stream Media Stream är en WebSocket som skickar en sekvens av JSON-händelser: `connected`, `start`, `media` (ljudets nyttolast) och `stop`. Bryggan öppnar en Speech Engine Conversation WebSocket vid `start` och vidarebefordrar ljud i båda riktningarna tills strömmen stängs. **`bridge.py`** ```python title="bridge.py" maxLines=0 import asyncio import json import aiohttp from aiohttp import web async def media_stream(request: web.Request) -> web.WebSocketResponse: twilio_ws = web.WebSocketResponse() await twilio_ws.prepare(request) stream_sid: str | None = None el_session: aiohttp.ClientSession | None = None el_ws: aiohttp.ClientWebSocketResponse | None = None pump_task: asyncio.Task | None = None async def pump_el_to_twilio(el: aiohttp.ClientWebSocketResponse): async for msg in el: if msg.type != aiohttp.WSMsgType.TEXT: continue event = json.loads(msg.data) etype = event.get("type") if etype == "audio": await twilio_ws.send_str(json.dumps({ "event": "media", "streamSid": stream_sid, "media": {"payload": event["audio_event"]["audio_base_64"]}, })) elif etype == "interruption": await twilio_ws.send_str(json.dumps({ "event": "clear", "streamSid": stream_sid, })) elif etype == "ping": event_id = event.get("ping_event", {}).get("event_id") await el.send_str(json.dumps({ "type": "pong", "event_id": event_id, })) try: async for msg in twilio_ws: if msg.type != aiohttp.WSMsgType.TEXT: continue event = json.loads(msg.data) if event["event"] == "start": stream_sid = event["start"]["streamSid"] el_session = aiohttp.ClientSession() el_ws = await el_session.ws_connect(await signed_url()) await el_ws.send_str(json.dumps({ "type": "conversation_initiation_client_data", })) pump_task = asyncio.create_task(pump_el_to_twilio(el_ws)) elif event["event"] == "media" and el_ws is not None: await el_ws.send_str(json.dumps({ "user_audio_chunk": event["media"]["payload"], })) elif event["event"] == "stop": break finally: if pump_task: pump_task.cancel() if el_ws and not el_ws.closed: await el_ws.close() if el_session and not el_session.closed: await el_session.close() return twilio_ws ``` **`bridge.mts`** ```typescript title="bridge.mts" maxLines=0 import { WebSocket, WebSocketServer } from "ws"; import { createServer } from "node:http"; const httpServer = createServer(app); const wss = new WebSocketServer({ noServer: true }); httpServer.on("upgrade", (req, socket, head) => { if (req.url === "/media-stream") { wss.handleUpgrade(req, socket, head, (ws) => handleMediaStream(ws)); } else { socket.destroy(); } }); async function handleMediaStream(twilioWs: WebSocket) { let streamSid: string | null = null; let elReady: Promise | null = null; twilioWs.on("message", async (raw) => { const event = JSON.parse(raw.toString()); if (event.event === "start") { streamSid = event.start.streamSid; // Convert rejection into a clean null + close so a failed signed-URL // fetch doesn't become an unhandled rejection on the next media event. elReady = openElevenLabsWebSocket(twilioWs, () => streamSid).catch((err) => { console.error("Failed to open Speech Engine conversation:", err); twilioWs.close(); return null; }); } else if (event.event === "media" && elReady) { const elWs = await elReady; if (!elWs) return; elWs.send(JSON.stringify({ user_audio_chunk: event.media.payload, })); } else if (event.event === "stop") { twilioWs.close(); } }); twilioWs.on("close", async () => { (await elReady)?.close(); }); } async function openElevenLabsWebSocket( twilioWs: WebSocket, getStreamSid: () => string | null, ): Promise { const elWs = new WebSocket(await signedUrl()); await new Promise((resolve, reject) => { elWs.once("open", () => resolve()); elWs.once("error", reject); }); elWs.send(JSON.stringify({ type: "conversation_initiation_client_data", })); elWs.on("message", (raw) => { const event = JSON.parse(raw.toString()); const streamSid = getStreamSid(); if (event.type === "audio") { twilioWs.send(JSON.stringify({ event: "media", streamSid, media: { payload: event.audio_event.audio_base_64 }, })); } else if (event.type === "interruption") { twilioWs.send(JSON.stringify({ event: "clear", streamSid })); } else if (event.type === "ping") { elWs.send(JSON.stringify({ type: "pong", event_id: event.ping_event?.event_id, })); } }); return elWs; } ``` Händelsen `interruption` från Speech Engine utlöser en `clear`-händelse på Twilio-strömmen, som kasserar buffrat ljud så att avbrott fungerar smidigt. Händelsen `ping` besvaras med `pong` för att hålla Conversation WebSocket aktiv. #### Kör brain-servern parallellt Brain-servern är standardservern för Speech Engine som visas i [snabbstartsguiden](/docs/sv/eleven-api/guides/cookbooks/speech-engine). Det enda tillägget är kontrollen av den delade hemligheten vid WebSocket-uppgraderingen — acceptera anslutningen endast om `x-api-key` matchar värdet som du angav i Speech Engine. **`bridge.py`** ```python title="bridge.py" maxLines=0 import os from elevenlabs import AsyncElevenLabs elevenlabs = AsyncElevenLabs(api_key=os.environ["ELEVENLABS_API_KEY"]) SHARED_SECRET = os.environ["SHARED_SECRET"] async def brain_ws(request: web.Request) -> web.WebSocketResponse: if request.headers.get("x-api-key") != SHARED_SECRET: return web.Response(status=401, text="unauthorized") ws = web.WebSocketResponse() await ws.prepare(request) engine = await elevenlabs.speech_engine.get(os.environ["SPEECH_ENGINE_ID"]) session = engine.create_session(ws) async def on_transcript(transcript): # Replace this with your own LLM call; see the quickstart. await session.send_response("Hello, you've reached the demo.") session.on("user_transcript", on_transcript) await session.run() return ws def make_app() -> web.Application: app = web.Application() app.router.add_post("/incoming-call", incoming_call) app.router.add_get("/media-stream", media_stream) app.router.add_get("/ws", brain_ws) return app if __name__ == "__main__": web.run_app(make_app(), port=3001) ``` **`bridge.mts`** ```typescript title="bridge.mts" maxLines=0 httpServer.on("upgrade", async (req, socket, head) => { if (req.url === "/ws") { if (req.headers["x-api-key"] !== process.env.SHARED_SECRET) { socket.write("HTTP/1.1 401 Unauthorized\r\n\r\n"); socket.destroy(); return; } // Hand off to engine.attach() — see the Speech Engine quickstart. } else if (req.url === "/media-stream") { wss.handleUpgrade(req, socket, head, (ws) => handleMediaStream(ws)); } else { socket.destroy(); } }); httpServer.listen(3001); ``` Se [snabbstartsguiden för Speech Engine](/docs/sv/eleven-api/guides/cookbooks/speech-engine#server-setup) för den fullständiga implementeringen av `on_transcript`, inklusive ett LLM-anrop och strömmat svar. ## Peka Twilio mot bryggan #### Starta bryggan och en offentlig tunnel ```bash ngrok http 3001 python bridge.py ``` Notera den `https://`-URL som ngrok skriver ut — Twilio skickar en POST-förfrågan till den. #### Uppdatera Speech Engine ws\_url Ange `speech_engine.ws_url` till den offentliga WebSocket-URL:en för din brain-slutpunkt så att ElevenLabs vet var den ska ansluta. ```python await elevenlabs.speech_engine.update( speech_engine_id="seng_8k3m9xr4hjnfg983brhmhkd98n6", speech_engine={"ws_url": "wss://abc123.ngrok.io/ws"}, ) ``` ```typescript await elevenlabs.speechEngine.update("seng_8k3m9xr4hjnfg983brhmhkd98n6", { speechEngine: { wsUrl: "wss://abc123.ngrok.io/ws" }, }); ``` #### Konfigurera Twilio-numret Öppna telefonnumrets **Voice Configuration** i Twilio-konsolen: * **A call comes in**: Webhook * **URL**: `https://abc123.ngrok.io/incoming-call` * **HTTP method**: POST Om numret är kopplat till en Elastic SIP Trunk ska du koppla bort det först — ett Twilio-nummer dirigeras antingen till en trunk eller till en webhook, inte båda. #### Ring numret Ring numret från valfri telefon. Agenten svarar; tala i samtalet så bör du höra agenten svara. När felsökningsloggning är aktiverad loggar bryggan samtalets SID, konversations-ID och ljudformat för varje tur. ## Produktionsöverväganden * **Webhook-validering**: validera alltid `X-Twilio-Signature` på `/incoming-call`. Exemplet ovan använder Twilios hjälpbibliotek; hoppa inte över detta steg. * **Delad hemlighet**: tillämpa den delade hemligheten på brain WebSocket. Utan den kan vem som helst som gissar din ngrok-URL ansluta och utge sig för att vara ElevenLabs. * **Stabil värd**: URL:er i ngroks kostnadsfria nivå ändras vid varje omstart. Använd en reserverad ngrok-domän eller ett riktigt värdnamn så att du inte behöver uppdatera Speech Engine `ws_url` och Twilio-webhooken efter varje omstart. * **Fördröjning**: varje samtal lägger till två nätverkshopp utöver LLM:ens tid till första token. Använd en modell med låg fördröjning och strömma svar för att hålla den upplevda fördröjningen låg. * **En eller två processer**: exemplet placerar bryggan och brain-servern på samma port så att en enda ngrok-tunnel täcker allt. I produktion kan du dela upp dem på två tjänster så länge båda har en offentlig URL. * **Promptinjektion**: talad inmatning från ett telefonsamtal är otillförlitlig användarinmatning. Validera transkript innan de påverkar verktygsanrop eller databasskrivningar. ## Nästa steg #### [Inbyggd Twilio-integrering](/docs/sv/eleven-agents/phone-numbers/twilio-integration/native-integration) Använd den hostade LLM:en i stället för en anpassad. #### [Snabbstart för Speech Engine](/docs/sv/eleven-api/guides/cookbooks/speech-engine) Bygg brain-servern från början till slut med en strömmande LLM. #### [Custom LLM (OpenAI-kompatibel)](/docs/sv/eleven-agents/customization/llm/custom-llm) En alternativ mekanism för anpassade LLM:er som använder en OpenAI-kompatibel HTTP-slutpunkt. #### [Referens för Python SDK](/docs/sv/eleven-api/resources/libraries/speech-engine/python-sdk-reference) Klasser, metoder och händelser för Speech Engine Python SDK. #### [Referens för JavaScript SDK](/docs/sv/eleven-api/resources/libraries/speech-engine/javascript-sdk-reference) Klasser, metoder och händelser för Speech Engine JavaScript SDK.