> This is a page from the ElevenLabs documentation. For an index of the documentation, fetch https://elevenlabs.io/docs/llms.txt. # Voximplant > **Warning** > > De Voximplant-integratie is beperkt beschikbaar en wordt per workspace ingeschakeld. Neem contact op met je > ElevenLabs-contactpersoon voordat je klantverkeer routeert. ## Overzicht De Voximplant-integratie verbindt een gesprek in een VoxEngine-scenario rechtstreeks via een WebSocket met een agent in ElevenAgents, met Voximplant Media Streams. Voximplant beheert de telefonie: het kiest of beantwoordt het gesprek en bepaalt wat er daarna gebeurt. ElevenAgents beheert het gesprek. Er is geen SIP-trunk of middleware nodig. Inkomende en uitgaande gesprekken werken op dezelfde manier: zodra het gesprek is verbonden, opent het scenario één WebSocket per gesprek naar ElevenLabs. Wanneer het gesprek eindigt, stuurt ElevenLabs het scenario één beslissingsevent dat aangeeft of de beller moet worden doorverbonden met een medewerker, het gesprek moet worden beëindigd, of het gesprek als een time-out moet worden behandeld. ## Zo werkt de integratie 1. Je VoxEngine-scenario beantwoordt een inkomend gesprek of plaatst een uitgaand gesprek. 2. Het scenario opent een WebSocket naar het ElevenLabs-endpoint voor je agent en verifieert zich met een ElevenLabs API-sleutel als bearer token. 3. Het scenario start de mediastream met `call.sendMediaTo()` en geeft eventuele `customParameters` mee. ElevenLabs zet elke parameter om in een dynamische variabele en antwoordt met een eigen `start`. 4. Voximplant en ElevenLabs wisselen 16-bits lineaire PCM-audio op 8 kHz uit in `media`-berichten. 5. Wanneer het gesprek eindigt, stuurt ElevenLabs de rest van de laatste zin van de agent, één aangepast event `elevenlabs-decision` en een bericht `stop`. Het scenario sluit vervolgens de WebSocket en handelt op basis van de beslissing. ## Vereisten Controleer voordat je begint of je het volgende hebt: 1. Een Voximplant-account met een applicatie, een telefoonnummer of de mogelijkheid om uitgaande gesprekken te voeren, en toestemming om scenario's te bewerken. 2. Een ElevenLabs-workspace waarin de Voximplant-integratie is ingeschakeld. 3. Een ElevenLabs-agent en een speciale API-sleutel. ## ElevenLabs configureren #### Een agent maken of selecteren Maak de agent in ElevenAgents. Geef deze een eerste bericht als de agent moet spreken zodra het gesprek wordt verbonden. Audioformaten worden ingesteld door de integratie, dus de geconfigureerde formaten van de agent worden niet gebruikt voor Voximplant-gesprekken. #### Gesprek beëindigen inschakelen Schakel in **Agent → Tools → System tools** **End call** in, zodat de agent het gesprek kan afronden. De reden die de agent opgeeft bij het beëindigen van het gesprek, wordt samen met de beslissing naar je scenario gestuurd. #### Een Voximplant-doorverbindingsregel toevoegen (optioneel) Geef de agent de systeemtool **Transfer to number** met een doorverbindingsregel waarvan de providerconfiguratie `voximplant` is, zodat de agent de beller kan doorverbinden met een medewerker. De regel heeft geen bestemming: het gesprek eindigt met een beslissing `transfer-to-agent` en je scenario routeert de beller. Doorverbindings- regels worden via de API geconfigureerd. Voeg de tool toe met een `PATCH` op de agent: ```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"}} ] }] } } }}}} }' ``` Stuur het volledige object `built_in_tools` van de agent, inclusief tools die de agent al heeft, zoals `end_call`. De optie die de agent terugstuurt, is het vaste token `voximplant`, dus één Voximplant-regel per tool is voldoende. Telefoonnummers en SIP-URI's die voor andere providers zijn geconfigureerd, worden niet aangeboden bij Voximplant- gesprekken. > **Note** > > Doorverbindingsregels zijn een instelling die via de API wordt beheerd. Configureer en update de tool **Transfer to number** van > een agent die deze gebruikt via de API, zoals hierboven; de tooleditor van het dashboard werkt met de > doorverbindingslijst per nummer. #### Een speciale API-sleutel maken Maak een API-sleutel in dezelfde workspace als de agent en beperk deze tot ElevenAgents. Beperk de toegestane IP-adressen van de sleutel tot de mediaservers van Voximplant om alleen verbindingen van Voximplant te accepteren. Voximplant vermeldt deze op `https://api.voximplant.com/getMediaResources?with_mediaservers`. #### De WebSocket-URL noteren Het scenario maakt verbinding met een URL die je agent-ID bevat: | Omgeving | URL | | ------------- | ----------------------------------------------------------------------------------------------------------------- | | Standaard | `wss://api.elevenlabs.io/v1/convai/conversation/voximplant/agent_7101k5zvyjhmfg983brhmhkd98n6` | | Dataresidency | `wss://api..residency.elevenlabs.io/v1/convai/conversation/voximplant/agent_7101k5zvyjhmfg983brhmhkd98n6` | Voeg `?branch_id=` toe om een branch van de agent vast te zetten. > **Info** > > Als je ElevenLabs-account zich in een geïsoleerde residency-omgeving bevindt, vervang je `` door je > regiocode. Bekijk [dataresidency](/docs/nl/overview/administration/data-residency) voor de beschikbare > regio's. ## Voximplant instellen #### Een applicatie maken Open in het [Voximplant-configuratiescherm](https://manage.voximplant.com/applications) **Applications** en klik op **Create application**. Geef de applicatie een naam, bijvoorbeeld `elevenlabs-agent`, en klik op **Create**. ![Voximplant: Applicatie maken](/docs/_fern-files/_img/29af341fa0a32eaaab444ade8305208121487413c5868597386a973b14fe4fe7.webp) #### De API-sleutel als secret opslaan Open in de applicatie **Secrets** en klik op **Add secret**. Geef deze de naam `ELEVENLABS_API_KEY`, plak de API-sleutel die je voor de workspace van de agent hebt gemaakt in **Value** en klik op **Add secret**. Het scenario leest deze met `VoxEngine.getSecretValue()`, zodat de sleutel nooit in de scenariocode verschijnt. ![Voximplant: Secret toevoegen](/docs/_fern-files/_img/ecf8be823bbc15b263e3f4838684a78de3a3594704be0055b443d15ab93e1485.webp) #### Het scenario maken Open **Scenarios**, klik op **Create scenario**, noem het `elevenlabs_agent`, plak de onderstaande code, vervang de agent-ID in `ELEVENLABS_URL` en klik op **Save**. Hiermee wordt een inkomend gesprek beantwoord, gestreamd naar de agent en gehandeld op basis van de beslissing wanneer het gesprek eindigt. Open voor een uitgaand gesprek de WebSocket in de handler `CallEvents.Connected` van het gesprek dat je hebt geplaatst. ```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: Het scenario in de editor](/docs/_fern-files/_img/d2e26165f57cae40fc01e8de28052fef09b2f98bd90c0e1a8779423715f61e2e.webp) #### Gesprekken naar het scenario routeren Open **Routing**, klik op **Create rule**, geef de regel een naam en wijs het scenario `elevenlabs_agent` toe. Het standaardpatroon `.*` stuurt elk gesprek naar de applicatie via het scenario; beperk dit tot een telefoonnummer als de applicatie ook andere gesprekken afhandelt. Koppel een telefoonnummer aan de applicatie onder **Numbers** om gesprekken naar een telefoonnummer te routeren. ![Voximplant: Regel maken](/docs/_fern-files/_img/bc6830b7dcd66dc0b59595456b1197bdcbb9174f15778da7ba9655ba4b93936e.webp) #### Een testgesprek voeren Je kunt de applicatie vanuit de browser bellen zonder telefoonnummer: 1. Open **Users**, klik op **Create user** en maak een gebruiker met een wachtwoord. ![Voximplant: Nieuwe gebruiker](/docs/_fern-files/_img/4754c9234588fd0caa336e1168e207b265557dc4e6a12b1cf8bced1275b8bae6.webp) 2. Klik in **Routing** op **Test tools** en daarna op **Softphone**. Log in als die gebruiker, geef toegang tot de microfoon, voer een willekeurige bestemming in en bel. De agent antwoordt met het eerste bericht. 3. Open **Call history** wanneer het gesprek eindigt. Elk gesprek vermeldt een WebSocket-leg naast het gesprek zelf. Klik op **View log** om de sessie te bekijken. ![Voximplant: Gespreksgeschiedenis](/docs/_fern-files/_img/4e2416ad3587bb320300173cf679f7c5d7a5e545550b0a647062a79866dac40c.webp) Het log toont de beslissing die ElevenLabs heeft verzonden, het sluiten van de WebSocket en wat het scenario vervolgens heeft gedaan. In dit voorbeeld vroeg de beller om een persoon, dus de beslissing is `transfer-to-agent` met de reden die de agent opgaf. ![Voximplant: Sessielog met het event elevenlabs-decision ](/docs/_fern-files/_img/f8b4602fa02cfd3c417557377aaa5dd66e2e88a67e7adf4cb037ccae1840f45c.webp) > **Warning** > > Handel op basis van het event `elevenlabs-decision`, niet op `MEDIA_ENDED`. Voximplant activeert `MEDIA_ENDED` na > ongeveer een seconde zonder audio van ElevenLabs, wat midden in een gesprek kan gebeuren. ## Dynamische variabelen Elke sleutel in `customParameters` wordt een dynamische variabele met dezelfde naam. Waarden die geen strings zijn, worden omgezet naar tekst. Zo wordt `true` bijvoorbeeld `"true"`. `customParameters` kan een object of een JSON-gecodeerde string zijn. Sleutels die beginnen met `system__` of `integration__` zijn gereserveerd en worden verwijderd. ## Beslissingsevents Wanneer het gesprek eindigt, stuurt ElevenLabs precies één beslissing vóór het bericht `stop`: ```json { "customEvent": "elevenlabs-decision", "payload": { "action": "terminate", "reason": "under_18" } } ``` | `action` | Wanneer deze wordt verzonden | `reason` | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------- | | `transfer-to-agent` | De agent heeft **Transfer to number** aangeroepen met een Voximplant-doorverbindingsregel. | De reden die de agent opgaf voor de doorverbinding. | | `timeout` | Het gesprek kreeg een time-out door stilte of na het laatste bericht van de agent, of de agent beëindigde het gesprek na 15 seconden stilte van de beller, exclusief de tijd dat de agent sprak. | Het time-outbericht of de reden die de agent opgaf. | | `terminate` | De agent beëindigde het gesprek met **End call**, of het gesprek eindigde normaal. | De reden die de agent opgaf met **End call**, indien aanwezig. | | `unexpected` | Het gesprek eindigde vanwege een fout. | Een beschrijving van de fout. | Als het scenario eerst `stop` stuurt of de WebSocket sluit, bijvoorbeeld omdat de beller heeft opgehangen, stuurt ElevenLabs geen beslissing. ## Audio Voximplant en ElevenLabs wisselen in beide richtingen 16-bits mono lineaire PCM op 8 kHz uit. ElevenLabs stuurt de audio van de agent vrijwel in realtime, dus wanneer de beller de agent onderbreekt, wordt nog maximaal ongeveer 0,4 seconden van het onderbroken antwoord afgespeeld. ## Authenticatiefouten ElevenLabs sluit de WebSocket met code `1008` en reden `bad auth token` wanneer de header `Authorization` ontbreekt of onjuist is opgemaakt, de API-sleutel ongeldig is of niet is toegestaan vanaf het IP-adres waarmee verbinding wordt gemaakt, de sleutel bij een andere workspace hoort, of de gebruiker van de sleutel geen toegang heeft tot een agent waarvoor authenticatie is ingeschakeld. ## Beperkingen en niet-ondersteunde functies * Clienttools en de systeemtool **Play keypad touch tone** worden niet ondersteund. **Transfer to number** werkt alleen via een Voximplant-doorverbindingsregel; het scenario bepaalt waar de beller naartoe gaat. * Configuratieoverschrijvingen zoals een ander eerste bericht kunnen niet vanuit het scenario worden doorgegeven; alleen dynamische variabelen kunnen dat. * Resultaten van gegevensverzameling worden niet naar het scenario gestuurd. Gebruik hiervoor de [post-call webhook](/docs/nl/eleven-agents/workflows/post-call-webhooks).