Voximplant

Create or select an agent

Create the agent in ElevenAgents. Give it a first message if it should speak as soon as the call connects. Audio formats are set by the integration, so the agent’s configured formats are not used for Voximplant calls.

Enable End call

In Agent → Tools → System tools, enable End call so the agent can finish the conversation. The reason the agent gives when it ends the call is sent to your scenario with the decision.

Add a Voximplant transfer rule (optional)

To let the agent hand the caller to a human, give it the Transfer to number system tool with a transfer rule whose provider configuration is voximplant. The rule has no destination: the conversation ends with a transfer-to-agent decision and your scenario routes the caller. Transfer rules are configured through the API. Add the tool with a PATCH on the agent:

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

Send the agent’s full built_in_tools object, including tools it already has such as end_call. The option the agent echoes back is the fixed token voximplant, so one Voximplant rule per tool is enough. Phone numbers and SIP URIs configured for other providers are not offered on Voximplant calls.

Create a dedicated API key

Create an API key in the same workspace as the agent and scope it to ElevenAgents. To accept connections only from Voximplant, restrict the key’s allowed IP addresses to Voximplant’s media servers, which Voximplant lists at https://api.voximplant.com/getMediaResources?with_mediaservers.

Note the WebSocket URL

The scenario connects to a URL that contains your agent ID:

To pin a branch of the agent, add ?branch_id=<branch_id>.

Create an application

In the Voximplant control panel, open Applications and click Create application. Give it a name, for example elevenlabs-agent, and click Create.

Store the API key as a secret

In the application, open Secrets and click Add secret. Name it ELEVENLABS_API_KEY, paste the API key you created for the agent’s workspace into Value, and click Add secret. The scenario reads it with VoxEngine.getSecretValue(), so the key never appears in the scenario code.

Create the scenario

Open Scenarios, click Create scenario, name it elevenlabs_agent, paste the code below, replace the agent ID in ELEVENLABS_URL, and click Save. It answers an inbound call, streams it to the agent, and acts on the decision when the conversation ends. For an outbound call, open the WebSocket in the CallEvents.Connected handler of the call you placed.

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

Route calls to the scenario

Open Routing, click Create rule, give it a name, and assign the elevenlabs_agent scenario. The default pattern .* sends every call to the application through the scenario; narrow it to a phone number if the application handles other calls too. To route a phone number, attach it to the application under Numbers.

Make a test call

You can call the application from the browser without a phone number:

1. Open Users, click Create user, and create a user with a password.

   

2. In Routing, click Test tools, then Softphone. Sign in as that user, allow microphone access, enter any destination, and call. The agent answers with its first message.

3. When the call ends, open Call history. Each call lists a WebSocket leg next to the call itself. Click View log to see the session.

   

   The log shows the decision ElevenLabs sent, the WebSocket close, and what the scenario did next. In this example the caller asked for a person, so the decision is transfer-to-agent with the reason the agent gave.