Voximplant

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:

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.

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:

Para fixar uma ramificação do agente, adicione ?branch_id=<branch_id>.

Crie um aplicativo

No painel de controle do Voximplant, abra Applications e clique em Create application. Dê um nome a ele, por exemplo, elevenlabs-agent, e clique em Create.

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.

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.

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

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.

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.

   

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.

   

   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.