> This is a page from the ElevenLabs documentation. For an index of the documentation, fetch https://elevenlabs.io/docs/llms.txt. # Voximplant > **Warning** > > Die Voximplant-Integration ist nur eingeschränkt verfügbar und wird pro Workspace aktiviert. Kontaktieren Sie Ihren > ElevenLabs-Ansprechpartner, bevor Sie Kundenanrufe weiterleiten. ## Überblick Die Voximplant-Integration verbindet einen Anruf in einem VoxEngine-Szenario über einen WebSocket direkt mit einem Agenten in ElevenAgents und verwendet dazu Voximplant Media Streams. Voximplant verwaltet die Telefonie: Es wählt oder nimmt den Anruf entgegen und entscheidet, was danach geschieht. ElevenAgents verwaltet die Konversation. Es ist kein SIP-Trunk und keine Middleware erforderlich. Eingehende und ausgehende Anrufe funktionieren gleich: Sobald der Anruf verbunden ist, öffnet das Szenario pro Anruf einen WebSocket zu ElevenLabs. Wenn die Konversation endet, sendet ElevenLabs dem Szenario ein einzelnes Entscheidungsereignis, das angibt, ob der Anrufer an einen Menschen übergeben, aufgelegt oder der Anruf als Timeout behandelt werden soll. ## So funktioniert die Integration 1. Ihr VoxEngine-Szenario nimmt einen eingehenden Anruf entgegen oder tätigt einen ausgehenden Anruf. 2. Das Szenario öffnet einen WebSocket zum ElevenLabs-Endpunkt für Ihren Agenten und authentifiziert sich mit einem ElevenLabs-API-Schlüssel als Bearer-Token. 3. Das Szenario startet den Media Stream mit `call.sendMediaTo()` und übergibt dabei alle `customParameters`. ElevenLabs wandelt jeden Parameter in eine dynamische Variable um und antwortet mit einem eigenen `start`. 4. Voximplant und ElevenLabs tauschen in `media`-Nachrichten 16-Bit-lineares PCM-Audio mit 8 kHz aus. 5. Wenn die Konversation endet, sendet ElevenLabs den Rest der letzten Äußerung des Agenten, ein benutzerdefiniertes Ereignis `elevenlabs-decision` und eine `stop`-Nachricht. Das Szenario schließt dann den WebSocket und handelt entsprechend der Entscheidung. ## Anforderungen Stellen Sie vor Beginn sicher, dass Sie Folgendes haben: 1. Ein Voximplant-Konto mit einer Anwendung, einer Telefonnummer oder ausgehenden Anrufen sowie Berechtigung zum Bearbeiten von Szenarien. 2. Einen ElevenLabs-Workspace mit aktivierter Voximplant-Integration. 3. Einen ElevenLabs-Agenten und einen dedizierten API-Schlüssel. ## ElevenLabs konfigurieren #### Agenten erstellen oder auswählen Erstellen Sie den Agenten in ElevenAgents. Geben Sie ihm eine erste Nachricht, wenn er sprechen soll, sobald der Anruf verbunden ist. Die Audioformate werden von der Integration festgelegt. Die für den Agenten konfigurierten Formate werden für Voximplant-Anrufe nicht verwendet. #### Anruf beenden aktivieren Aktivieren Sie unter **Agent → Tools → Systemtools** **Anruf beenden**, damit der Agent die Konversation abschließen kann. Der Grund, den der Agent beim Beenden des Anrufs angibt, wird mit der Entscheidung an Ihr Szenario gesendet. #### Voximplant-Weiterleitungsregel hinzufügen (optional) Damit der Agent den Anrufer an einen Menschen übergeben kann, geben Sie ihm das Systemtool **An Nummer weiterleiten** mit einer Weiterleitungsregel, deren Provider-Konfiguration `voximplant` lautet. Die Regel hat kein Ziel: Die Konversation endet mit einer `transfer-to-agent`-Entscheidung, und Ihr Szenario leitet den Anrufer weiter. Weiterleitungsregeln werden über die API konfiguriert. Fügen Sie das Tool mit einem `PATCH` für den Agenten hinzu: ```bash curl -X PATCH "https://api.elevenlabs.io/v1/convai/agents/agent_7101k5zvyjhmfg983brhmhkd98n6" \ -H "xi-api-key: $ELEVENLABS_API_KEY" -H "Content-Type: application/json" \ -d '{ "conversation_config": {"agent": {"prompt": {"built_in_tools": { "end_call": {"type": "system", "name": "end_call", "description": "", "params": {"system_tool_type": "end_call"}}, "transfer_to_number": { "type": "system", "name": "transfer_to_number", "description": "", "params": { "system_tool_type": "transfer_to_number", "transfers": [], "transfer_rules": [{ "condition": "the caller asks to speak with a human", "provider_configs": [ {"type": "voximplant", "config": {"type": "voximplant_handoff"}} ] }] } } }}}} }' ``` Senden Sie das vollständige `built_in_tools`-Objekt des Agenten, einschließlich bereits vorhandener Tools wie `end_call`. Die Option, die der Agent zurückgibt, ist das feste Token `voximplant`. Daher reicht eine Voximplant-Regel pro Tool aus. Telefonnummern und SIP-URIs, die für andere Provider konfiguriert sind, werden bei Voximplant-Anrufen nicht angeboten. > **Note** > > Weiterleitungsregeln werden über die API verwaltet. Konfigurieren und aktualisieren Sie das Tool **An Nummer weiterleiten** > eines Agenten, der sie verwendet, wie oben beschrieben über die API; der Tool-Editor im Dashboard arbeitet mit der > Weiterleitungsliste pro Nummer. #### Dedizierten API-Schlüssel erstellen Erstellen Sie einen API-Schlüssel im selben Workspace wie der Agent und beschränken Sie seinen Umfang auf ElevenAgents. Um nur Verbindungen von Voximplant zu akzeptieren, beschränken Sie die zulässigen IP-Adressen des Schlüssels auf die Media- Server von Voximplant, die Voximplant unter `https://api.voximplant.com/getMediaResources?with_mediaservers` auflistet. #### WebSocket-URL notieren Das Szenario verbindet sich mit einer URL, die Ihre Agenten-ID enthält: | Umgebung | URL | | ------------- | ----------------------------------------------------------------------------------------------------------------- | | Standard | `wss://api.elevenlabs.io/v1/convai/conversation/voximplant/agent_7101k5zvyjhmfg983brhmhkd98n6` | | Datenresidenz | `wss://api..residency.elevenlabs.io/v1/convai/conversation/voximplant/agent_7101k5zvyjhmfg983brhmhkd98n6` | Um einen Branch des Agenten festzulegen, fügen Sie `?branch_id=` hinzu. > **Info** > > Wenn sich Ihr ElevenLabs-Konto in einer isolierten Datenresidenzumgebung befindet, ersetzen Sie `` durch Ihren > Regionscode. Verfügbare Regionen finden Sie unter [Datenresidenz](/docs/de/overview/administration/data-residency). ## Voximplant einrichten #### Anwendung erstellen Öffnen Sie im [Voximplant Control Panel](https://manage.voximplant.com/applications) **Applications** und klicken Sie auf **Create application**. Geben Sie einen Namen ein, zum Beispiel `elevenlabs-agent`, und klicken Sie auf **Create**. ![Voximplant: Anwendung erstellen](/docs/_fern-files/_img/29af341fa0a32eaaab444ade8305208121487413c5868597386a973b14fe4fe7.webp) #### API-Schlüssel als Secret speichern Öffnen Sie in der Anwendung **Secrets** und klicken Sie auf **Add secret**. Nennen Sie es `ELEVENLABS_API_KEY`, fügen Sie den API-Schlüssel, den Sie für den Workspace des Agenten erstellt haben, unter **Value** ein und klicken Sie auf **Add secret**. Das Szenario liest ihn mit `VoxEngine.getSecretValue()`, sodass der Schlüssel nie im Szenariocode erscheint. ![Voximplant: Secret hinzufügen](/docs/_fern-files/_img/ecf8be823bbc15b263e3f4838684a78de3a3594704be0055b443d15ab93e1485.webp) #### Szenario erstellen Öffnen Sie **Scenarios**, klicken Sie auf **Create scenario**, nennen Sie es `elevenlabs_agent`, fügen Sie den folgenden Code ein, ersetzen Sie die Agenten-ID in `ELEVENLABS_URL` und klicken Sie auf **Save**. Das Szenario nimmt einen eingehenden Anruf entgegen, streamt ihn an den Agenten und handelt nach der Entscheidung, wenn die Konversation endet. Für einen ausgehenden Anruf öffnen Sie den WebSocket im Handler `CallEvents.Connected` des von Ihnen getätigten Anrufs. ```javascript maxLines=0 const ELEVENLABS_URL = "wss://api.elevenlabs.io/v1/convai/conversation/voximplant/agent_7101k5zvyjhmfg983brhmhkd98n6"; VoxEngine.addEventListener(AppEvents.CallAlerting, ({ call }) => { call.answer(); let decision = null; const ws = VoxEngine.createWebSocket(ELEVENLABS_URL, { headers: [ { name: "Authorization", value: `Bearer ${VoxEngine.getSecretValue("ELEVENLABS_API_KEY")}`, }, ], }); ws.addEventListener(WebSocketEvents.OPEN, () => { call.sendMediaTo(ws, { encoding: WebSocketAudioEncoding.PCM16_8KHZ, customParameters: { customer_name: "Ana", task_id: "task-7" }, }); ws.sendMediaTo(call); }); ws.addEventListener(WebSocketEvents.MESSAGE, ({ text }) => { const message = JSON.parse(text); if (message.customEvent === "elevenlabs-decision") { decision = message.payload; Logger.write(`ElevenLabs decision: ${JSON.stringify(decision)}`); } }); ws.addEventListener(WebSocketEvents.CLOSE, (e) => { Logger.write(`ElevenLabs socket closed: code=${e.code} reason=${e.reason}`); if (decision?.action === "transfer-to-agent") { // Route the caller to a human here, for example with VoxEngine.callPSTN(). call.say("Connecting you to an agent.", { language: VoiceList.Amazon.en_US_Joanna }); call.addEventListener(CallEvents.PlaybackFinished, () => call.hangup()); return; } call.hangup(); }); call.addEventListener(CallEvents.Disconnected, () => { ws.close(); VoxEngine.terminate(); }); }); ``` ![Voximplant: Szenario im Editor](/docs/_fern-files/_img/d2e26165f57cae40fc01e8de28052fef09b2f98bd90c0e1a8779423715f61e2e.webp) #### Anrufe an das Szenario weiterleiten Öffnen Sie **Routing**, klicken Sie auf **Create rule**, geben Sie ihr einen Namen und weisen Sie das Szenario `elevenlabs_agent` zu. Das Standardmuster `.*` leitet jeden Anruf an die Anwendung über das Szenario weiter; beschränken Sie es auf eine Telefonnummer, wenn die Anwendung auch andere Anrufe verarbeitet. Um eine Telefonnummer weiterzuleiten, fügen Sie sie unter **Numbers** zur Anwendung hinzu. ![Voximplant: Regel erstellen](/docs/_fern-files/_img/bc6830b7dcd66dc0b59595456b1197bdcbb9174f15778da7ba9655ba4b93936e.webp) #### Testanruf tätigen Sie können die Anwendung ohne Telefonnummer im Browser anrufen: 1. Öffnen Sie **Users**, klicken Sie auf **Create user** und erstellen Sie einen Benutzer mit Passwort. ![Voximplant: Neuer Benutzer](/docs/_fern-files/_img/4754c9234588fd0caa336e1168e207b265557dc4e6a12b1cf8bced1275b8bae6.webp) 2. Klicken Sie unter **Routing** auf **Test tools** und dann auf **Softphone**. Melden Sie sich als dieser Benutzer an, erlauben Sie den Mikrofonzugriff, geben Sie ein beliebiges Ziel ein und rufen Sie an. Der Agent antwortet mit seiner ersten Nachricht. 3. Öffnen Sie nach Ende des Anrufs **Call history**. Jeder Anruf führt neben dem Anruf selbst eine WebSocket-Verbindung auf. Klicken Sie auf **View log**, um die Sitzung anzuzeigen. ![Voximplant: Anrufverlauf](/docs/_fern-files/_img/4e2416ad3587bb320300173cf679f7c5d7a5e545550b0a647062a79866dac40c.webp) Das Protokoll zeigt die von ElevenLabs gesendete Entscheidung, das Schließen des WebSockets und die anschließende Aktion des Szenarios. In diesem Beispiel bat der Anrufer um eine Person, daher lautet die Entscheidung `transfer-to-agent` mit dem vom Agenten angegebenen Grund. ![Voximplant: Sitzungsprotokoll mit dem Ereignis elevenlabs-decision](/docs/_fern-files/_img/f8b4602fa02cfd3c417557377aaa5dd66e2e88a67e7adf4cb037ccae1840f45c.webp) > **Warning** > > Handeln Sie nach dem Ereignis `elevenlabs-decision`, nicht nach `MEDIA_ENDED`. Voximplant löst `MEDIA_ENDED` nach > etwa einer Sekunde ohne Audio von ElevenLabs aus. Das kann mitten in einer Konversation passieren. ## Dynamische Variablen Jeder Schlüssel in `customParameters` wird zu einer dynamischen Variable mit demselben Namen. Werte, die keine Strings sind, werden in Text umgewandelt. Beispielsweise wird aus `true` der Wert `"true"`. `customParameters` kann ein Objekt oder ein JSON-kodierter String sein. Schlüssel, die mit `system__` oder `integration__` beginnen, sind reserviert und werden verworfen. ## Entscheidungsereignisse Wenn die Konversation endet, sendet ElevenLabs vor seiner `stop`-Nachricht genau eine Entscheidung: ```json { "customEvent": "elevenlabs-decision", "payload": { "action": "terminate", "reason": "under_18" } } ``` | `action` | Wann sie gesendet wird | `reason` | | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | | `transfer-to-agent` | Der Agent hat **An Nummer weiterleiten** mit einer Voximplant-Weiterleitungsregel aufgerufen. | Der Grund, den der Agent für die Weiterleitung angegeben hat. | | `timeout` | Für die Konversation ist bei Stille oder nach der letzten Nachricht des Agenten ein Timeout aufgetreten, oder der Agent hat den Anruf nach 15 Sekunden Stille des Anrufers beendet, ohne die Sprechzeit des Agenten. | Die Timeout-Nachricht oder der vom Agenten angegebene Grund. | | `terminate` | Der Agent hat den Anruf mit **Anruf beenden** beendet oder die Konversation endete normal. | Der Grund, den der Agent bei **Anruf beenden** angegeben hat, falls vorhanden. | | `unexpected` | Die Konversation wurde aufgrund eines Fehlers beendet. | Eine Beschreibung des Fehlers. | Wenn das Szenario zuerst `stop` sendet oder den WebSocket schließt, beispielsweise weil der Anrufer aufgelegt hat, sendet ElevenLabs keine Entscheidung. ## Audio Voximplant und ElevenLabs tauschen in beide Richtungen 16-Bit-monaurales lineares PCM mit 8 kHz aus. ElevenLabs gibt das Audio des Agenten nahezu in Echtzeit aus. Wenn der Anrufer den Agenten unterbricht, werden höchstens etwa 0,4 Sekunden der unterbrochenen Antwort weiter abgespielt. ## Authentifizierungsfehler ElevenLabs schließt den WebSocket mit Code `1008` und dem Grund `bad auth token`, wenn der Header `Authorization` fehlt oder fehlerhaft ist, der API-Schlüssel ungültig ist oder nicht von der IP-Adresse der Verbindung verwendet werden darf, der Schlüssel zu einem anderen Workspace gehört oder der Benutzer des Schlüssels nicht auf einen Agenten mit aktivierter Authentifizierung zugreifen kann. ## Einschränkungen und nicht unterstützte Funktionen * Client-Tools und das Systemtool **Tastenton wiedergeben** werden nicht unterstützt. **An Nummer weiterleiten** funktioniert nur über eine Voximplant-Weiterleitungsregel; das Szenario entscheidet, wohin der Anrufer weitergeleitet wird. * Konfigurationsüberschreibungen wie eine andere erste Nachricht können nicht aus dem Szenario übergeben werden; nur dynamische Variablen sind möglich. * Datenerfassungsergebnisse werden nicht an das Szenario gesendet. Verwenden Sie dafür den [Post-Call-Webhook](/docs/de/eleven-agents/workflows/post-call-webhooks).