Voximplant

Crea o selecciona un agente

Crea el agente en ElevenAgents. Dale un primer mensaje si debe hablar en cuanto se conecte la llamada. Los formatos de audio los establece la integración, por lo que los formatos configurados del agente no se usan para las llamadas de Voximplant.

Activa Finalizar llamada

En Agente → Herramientas → Herramientas del sistema, activa Finalizar llamada para que el agente pueda terminar la conversación. El motivo que indique el agente al finalizar la llamada se envía a tu escenario junto con la decisión.

Añade una regla de transferencia de Voximplant (opcional)

Para que el agente pueda transferir a quien llama a una persona, asígnale la herramienta del sistema Transferir a número con una regla de transferencia cuya configuración de proveedor sea voximplant. La regla no tiene destino: la conversación termina con una decisión transfer-to-agent y tu escenario enruta a quien llama. Las reglas de transferencia se configuran mediante la API. Añade la herramienta mediante un PATCH en el agente:

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"}}
            ]
          }]
        }
      }
    }}}}
  }'

Envía el objeto built_in_tools completo del agente, incluidas las herramientas que ya tenga, como end_call. La opción que el agente devuelve es el token fijo voximplant, por lo que basta con una regla de Voximplant por herramienta. Los números de teléfono y URI SIP configurados para otros proveedores no se ofrecen en llamadas de Voximplant.

Crea una clave de API específica

Crea una clave de API en el mismo espacio de trabajo que el agente y limita su alcance a ElevenAgents. Para aceptar conexiones solo de Voximplant, restringe las direcciones IP permitidas de la clave a los servidores de medios de Voximplant, que Voximplant enumera en https://api.voximplant.com/getMediaResources?with_mediaservers.

Anota la URL de WebSocket

El escenario se conecta a una URL que contiene el ID de tu agente:

Para fijar una rama del agente, añade ?branch_id=<branch_id>.

Crea una aplicación

En el panel de control de Voximplant, abre Applications y haz clic en Create application. Ponle un nombre, por ejemplo elevenlabs-agent, y haz clic en Create.

Guarda la clave de API como secreto

En la aplicación, abre Secrets y haz clic en Add secret. Llámalo ELEVENLABS_API_KEY, pega la clave de API que creaste para el espacio de trabajo del agente en Value y haz clic en Add secret. El escenario la lee con VoxEngine.getSecretValue(), por lo que la clave nunca aparece en el código del escenario.

Crea el escenario

Abre Scenarios, haz clic en Create scenario, llámalo elevenlabs_agent, pega el código siguiente, sustituye el ID del agente en ELEVENLABS_URL y haz clic en Save. Responde una llamada entrante, la transmite al agente y actúa según la decisión cuando termina la conversación. Para una llamada saliente, abre el WebSocket en el controlador CallEvents.Connected de la llamada que realizaste.

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();
  });
});

Enruta llamadas al escenario

Abre Routing, haz clic en Create rule, ponle un nombre y asigna el escenario elevenlabs_agent. El patrón predeterminado .* envía todas las llamadas a la aplicación a través del escenario; limítalo a un número de teléfono si la aplicación también gestiona otras llamadas. Para enrutar un número de teléfono, asócialo a la aplicación en Numbers.

Haz una llamada de prueba

Puedes llamar a la aplicación desde el navegador sin un número de teléfono:

1. Abre Users, haz clic en Create user y crea un usuario con contraseña.

   

2. En Routing, haz clic en Test tools y luego en Softphone. Inicia sesión como ese usuario, permite el acceso al micrófono, introduce cualquier destino y llama. El agente responde con su primer mensaje.

3. Cuando termine la llamada, abre Call history. Cada llamada muestra una conexión WebSocket junto a la llamada propiamente dicha. Haz clic en View log para ver la sesión.

   

   El registro muestra la decisión que envió ElevenLabs, el cierre del WebSocket y lo que hizo el escenario después. En este ejemplo, quien llamó pidió hablar con una persona, por lo que la decisión es transfer-to-agent con el motivo indicado por el agente.