> This is a page from the ElevenLabs documentation. For an index of the documentation, fetch https://elevenlabs.io/docs/llms.txt. # Voximplant > **Warning** > > A integração com o Voximplant está disponível de forma limitada e é habilitada por workspace. Entre em contato com seu > representante da ElevenLabs antes de encaminhar o tráfego de clientes. ## Visão geral A integração com o Voximplant conecta uma chamada em um cenário do VoxEngine diretamente a um agente no ElevenAgents por WebSocket, usando o Voximplant Media Streams. O Voximplant gerencia a telefonia: ele faz ou atende a chamada e decide o que acontece depois. O ElevenAgents gerencia a conversa. Não é necessário um tronco SIP nem middleware. As chamadas de entrada e saída funcionam da mesma forma: assim que a chamada é conectada, o cenário abre um WebSocket por chamada para a ElevenLabs. Quando a conversa termina, a ElevenLabs envia ao cenário um único evento de decisão que informa se deve transferir a pessoa que ligou para um humano, encerrar a chamada ou tratar a chamada como um timeout. ## Como a integração funciona 1. Seu cenário do VoxEngine atende uma chamada de entrada ou faz uma chamada de saída. 2. O cenário abre um WebSocket para o endpoint da ElevenLabs do seu agente, autenticando-se com uma chave de API da ElevenLabs como token bearer. 3. O cenário inicia o stream de mídia com `call.sendMediaTo()`, transmitindo quaisquer `customParameters`. A ElevenLabs transforma cada parâmetro em uma variável dinâmica e responde com seu próprio `start`. 4. O Voximplant e a ElevenLabs trocam áudio PCM linear de 16 bits a 8 kHz em mensagens `media`. 5. Quando a conversa termina, a ElevenLabs envia o restante da última frase do agente, um evento personalizado `elevenlabs-decision` e uma mensagem `stop`. Em seguida, o cenário fecha o WebSocket e age de acordo com a decisão. ## Requisitos Antes de começar, confira se você tem: 1. Uma conta do Voximplant com um aplicativo, um número de telefone ou chamadas de saída e permissão para editar cenários. 2. Um workspace da ElevenLabs com a integração com o Voximplant habilitada. 3. Um agente da ElevenLabs e uma chave de API dedicada. ## Configure a ElevenLabs #### Crie ou selecione um agente Crie o agente no ElevenAgents. Defina uma primeira mensagem se ele precisar falar assim que a chamada for conectada. Os formatos de áudio são definidos pela integração, portanto os formatos configurados do agente não são usados em chamadas do Voximplant. #### Habilite Encerrar chamada Em **Agente → Ferramentas → Ferramentas do sistema**, habilite **Encerrar chamada** para que o agente possa finalizar a conversa. O motivo informado pelo agente ao encerrar a chamada é enviado ao seu cenário com a decisão. #### Adicione uma regra de transferência do Voximplant (opcional) Para permitir que o agente transfira a pessoa que ligou para um humano, forneça a ele a ferramenta de sistema **Transferir para número** com uma regra de transferência cuja configuração de provedor seja `voximplant`. A regra não tem destino: a conversa termina com uma decisão `transfer-to-agent`, e seu cenário encaminha a pessoa que ligou. As regras de transferência são configuradas pela API. Adicione a ferramenta com um `PATCH` no agente: ```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"}} ] }] } } }}}} }' ``` Envie o objeto `built_in_tools` completo do agente, incluindo as ferramentas que ele já possui, como `end_call`. A opção que o agente retorna é o token fixo `voximplant`, portanto uma regra do Voximplant por ferramenta é suficiente. Números de telefone e URIs SIP configurados para outros provedores não são oferecidos em chamadas do Voximplant. > **Note** > > As regras de transferência são uma configuração gerenciada pela API. Configure e atualize pela API a ferramenta **Transferir para número** > de um agente que as utiliza, conforme acima; o editor de ferramentas do dashboard funciona com a > lista de transferências por número. #### Crie uma chave de API dedicada Crie uma chave de API no mesmo workspace do agente e limite o escopo dela ao ElevenAgents. Para aceitar conexões somente do Voximplant, restrinja os endereços IP permitidos da chave aos servidores de mídia do Voximplant, listados pelo Voximplant em `https://api.voximplant.com/getMediaResources?with_mediaservers`. #### Anote a URL do WebSocket O cenário se conecta a uma URL que contém o ID do seu agente: | Ambiente | URL | | ------------------- | ----------------------------------------------------------------------------------------------------------------- | | Padrão | `wss://api.elevenlabs.io/v1/convai/conversation/voximplant/agent_7101k5zvyjhmfg983brhmhkd98n6` | | Residência de dados | `wss://api..residency.elevenlabs.io/v1/convai/conversation/voximplant/agent_7101k5zvyjhmfg983brhmhkd98n6` | Para fixar uma ramificação do agente, adicione `?branch_id=`. > **Info** > > Se sua conta da ElevenLabs estiver em um ambiente isolado de residência de dados, substitua `` pelo código da > sua região. Consulte [residência de dados](/docs/pt/overview/administration/data-residency) para ver as regiões > disponíveis. ## Configure o Voximplant #### Crie um aplicativo No [painel de controle do Voximplant](https://manage.voximplant.com/applications), abra **Applications** e clique em **Create application**. Dê um nome a ele, por exemplo, `elevenlabs-agent`, e clique em **Create**. ![Voximplant: Criar aplicativo](/docs/_fern-files/_img/29af341fa0a32eaaab444ade8305208121487413c5868597386a973b14fe4fe7.webp) #### Armazene a chave de API como segredo No aplicativo, abra **Secrets** e clique em **Add secret**. Nomeie-o como `ELEVENLABS_API_KEY`, cole no campo **Value** a chave de API que você criou para o workspace do agente e clique em **Add secret**. O cenário a lê com `VoxEngine.getSecretValue()`, portanto a chave nunca aparece no código do cenário. ![Voximplant: Adicionar segredo](/docs/_fern-files/_img/ecf8be823bbc15b263e3f4838684a78de3a3594704be0055b443d15ab93e1485.webp) #### Crie o cenário Abra **Scenarios**, clique em **Create scenario**, nomeie-o como `elevenlabs_agent`, cole o código abaixo, substitua o ID do agente em `ELEVENLABS_URL` e clique em **Save**. Ele atende uma chamada de entrada, a transmite para o agente e age de acordo com a decisão quando a conversa termina. Para uma chamada de saída, abra o WebSocket no manipulador `CallEvents.Connected` da chamada que você fez. ```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: o cenário no editor](/docs/_fern-files/_img/d2e26165f57cae40fc01e8de28052fef09b2f98bd90c0e1a8779423715f61e2e.webp) #### Encaminhe chamadas para o cenário Abra **Routing**, clique em **Create rule**, dê um nome a ela e atribua o cenário `elevenlabs_agent`. O padrão padrão `.*` envia todas as chamadas para o aplicativo por meio do cenário; restrinja-o a um número de telefone se o aplicativo também atender outras chamadas. Para encaminhar um número de telefone, anexe-o ao aplicativo em **Numbers**. ![Voximplant: Criar regra](/docs/_fern-files/_img/bc6830b7dcd66dc0b59595456b1197bdcbb9174f15778da7ba9655ba4b93936e.webp) #### Faça uma chamada de teste Você pode ligar para o aplicativo pelo navegador sem um número de telefone: 1. Abra **Users**, clique em **Create user** e crie um usuário com uma senha. ![Voximplant: Novo usuário](/docs/_fern-files/_img/4754c9234588fd0caa336e1168e207b265557dc4e6a12b1cf8bced1275b8bae6.webp) 2. Em **Routing**, clique em **Test tools** e depois em **Softphone**. Entre como esse usuário, permita o acesso ao microfone, informe qualquer destino e ligue. O agente atende com sua primeira mensagem. 3. Quando a chamada terminar, abra **Call history**. Cada chamada lista uma conexão WebSocket ao lado da própria chamada. Clique em **View log** para ver a sessão. ![Voximplant: Histórico de chamadas](/docs/_fern-files/_img/4e2416ad3587bb320300173cf679f7c5d7a5e545550b0a647062a79866dac40c.webp) O registro mostra a decisão enviada pela ElevenLabs, o fechamento do WebSocket e o que o cenário fez em seguida. Neste exemplo, a pessoa que ligou pediu para falar com alguém, então a decisão é `transfer-to-agent` com o motivo informado pelo agente. ![Voximplant: Registro da sessão com o evento elevenlabs-decision](/docs/_fern-files/_img/f8b4602fa02cfd3c417557377aaa5dd66e2e88a67e7adf4cb037ccae1840f45c.webp) > **Warning** > > Aja com base no evento `elevenlabs-decision`, não em `MEDIA_ENDED`. O Voximplant dispara `MEDIA_ENDED` após > cerca de um segundo sem áudio da ElevenLabs, o que pode acontecer no meio de uma conversa. ## Variáveis dinâmicas Cada chave em `customParameters` se torna uma variável dinâmica com o mesmo nome. Valores que não são strings são convertidos em texto; por exemplo, `true` se torna `"true"`. `customParameters` pode ser um objeto ou uma string codificada em JSON. Chaves que começam com `system__` ou `integration__` são reservadas e são descartadas. ## Eventos de decisão Quando a conversa termina, a ElevenLabs envia exatamente uma decisão antes da mensagem `stop`: ```json { "customEvent": "elevenlabs-decision", "payload": { "action": "terminate", "reason": "under_18" } } ``` | `action` | Quando é enviado | `reason` | | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | | `transfer-to-agent` | O agente chamou **Transferir para número** com uma regra de transferência do Voximplant. | O motivo informado pelo agente para a transferência. | | `timeout` | A conversa atingiu o tempo limite por silêncio ou após a última mensagem do agente, ou o agente encerrou a chamada após 15 segundos de silêncio da pessoa que ligou, sem contar o tempo em que o agente estava falando. | A mensagem de timeout ou o motivo informado pelo agente. | | `terminate` | O agente encerrou a chamada com **Encerrar chamada**, ou a conversa terminou normalmente. | O motivo informado pelo agente com **Encerrar chamada**, quando houver. | | `unexpected` | A conversa terminou devido a um erro. | Uma descrição do erro. | Se o cenário enviar `stop` ou fechar o WebSocket primeiro, por exemplo, porque a pessoa que ligou desligou, a ElevenLabs não enviará nenhuma decisão. ## Áudio O Voximplant e a ElevenLabs trocam PCM linear mono de 16 bits a 8 kHz em ambas as direções. A ElevenLabs transmite o áudio do agente em um ritmo próximo ao tempo real, portanto, quando a pessoa que ligou interrompe o agente, no máximo cerca de 0,4 segundos da resposta interrompida ainda são reproduzidos. ## Erros de autenticação A ElevenLabs fecha o WebSocket com o código `1008` e o motivo `bad auth token` quando o cabeçalho `Authorization` está ausente ou malformado, a chave de API é inválida ou não é permitida a partir do endereço IP de conexão, a chave pertence a outro workspace ou o usuário da chave não pode acessar um agente com autenticação habilitada. ## Limitações e recursos não compatíveis * Ferramentas de cliente e a ferramenta de sistema **Reproduzir tom de tecla do teclado** não são compatíveis. **Transferir para número** funciona apenas por meio de uma regra de transferência do Voximplant; o cenário decide para onde a pessoa que ligou vai. * Substituições de configuração, como uma primeira mensagem diferente, não podem ser transmitidas pelo cenário; apenas variáveis dinâmicas podem. * Os resultados da coleta de dados não são enviados ao cenário. Use o [webhook pós-chamada](/docs/pt/eleven-agents/workflows/post-call-webhooks) para recebê-los.