Voximplant

Crea o seleziona un agente

Crea l’agente in ElevenAgents. Imposta un primo messaggio se deve parlare non appena la chiamata si connette. I formati audio sono impostati dall’integrazione, quindi i formati configurati dell’agente non vengono usati per le chiamate Voximplant.

Abilita Termina chiamata

In Agente → Strumenti → Strumenti di sistema, abilita Termina chiamata affinché l’agente possa concludere la conversazione. Il motivo fornito dall’agente quando termina la chiamata viene inviato al tuo scenario insieme alla decisione.

Aggiungi una regola di trasferimento Voximplant (facoltativo)

Per consentire all’agente di trasferire il chiamante a un operatore, assegnagli lo strumento di sistema Trasferisci a numero con una regola di trasferimento la cui configurazione del provider sia voximplant. La regola non ha destinazione: la conversazione termina con una decisione transfer-to-agent e il tuo scenario instrada il chiamante. Le regole di trasferimento vengono configurate tramite l’API. Aggiungi lo strumento con un PATCH sull’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"}}
            ]
          }]
        }
      }
    }}}}
  }'

Invia l’intero oggetto built_in_tools dell’agente, inclusi gli strumenti che possiede già, come end_call. L’opzione che l’agente restituisce è il token fisso voximplant, quindi è sufficiente una regola Voximplant per strumento. I numeri di telefono e gli URI SIP configurati per altri provider non vengono offerti nelle chiamate Voximplant.

Crea una chiave API dedicata

Crea una chiave API nello stesso workspace dell’agente e limitane l’ambito a ElevenAgents. Per accettare connessioni soltanto da Voximplant, limita gli indirizzi IP consentiti della chiave ai server multimediali Voximplant, elencati da Voximplant all’indirizzo https://api.voximplant.com/getMediaResources?with_mediaservers.

Annota l'URL WebSocket

Lo scenario si connette a un URL che contiene l’ID del tuo agente:

Per fissare un branch dell’agente, aggiungi ?branch_id=<branch_id>.

Crea un'applicazione

Nel pannello di controllo Voximplant, apri Applications e fai clic su Create application. Assegnale un nome, ad esempio elevenlabs-agent, quindi fai clic su Create.

Salva la chiave API come segreto

Nell’applicazione, apri Secrets e fai clic su Add secret. Assegna il nome ELEVENLABS_API_KEY, incolla in Value la chiave API creata per il workspace dell’agente e fai clic su Add secret. Lo scenario la legge con VoxEngine.getSecretValue(), quindi la chiave non appare mai nel codice dello scenario.

Crea lo scenario

Apri Scenarios, fai clic su Create scenario, chiamalo elevenlabs_agent, incolla il codice qui sotto, sostituisci l’ID dell’agente in ELEVENLABS_URL e fai clic su Save. Risponde a una chiamata in entrata, la trasmette all’agente e agisce in base alla decisione al termine della conversazione. Per una chiamata in uscita, apri il WebSocket nel gestore CallEvents.Connected della chiamata effettuata.

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

Instrada le chiamate allo scenario

Apri Routing, fai clic su Create rule, assegnale un nome e assegna lo scenario elevenlabs_agent. Il pattern predefinito .* invia ogni chiamata all’applicazione tramite lo scenario; limitalo a un numero di telefono se l’applicazione gestisce anche altre chiamate. Per instradare un numero di telefono, collegalo all’applicazione in Numbers.

Effettua una chiamata di prova

Puoi chiamare l’applicazione dal browser senza un numero di telefono:

1. Apri Users, fai clic su Create user e crea un utente con una password.

   

2. In Routing, fai clic su Test tools, poi su Softphone. Accedi come quell’utente, consenti l’accesso al microfono, inserisci una destinazione qualsiasi e chiama. L’agente risponde con il suo primo messaggio.

3. Al termine della chiamata, apri Call history. Ogni chiamata elenca una sessione WebSocket accanto alla chiamata stessa. Fai clic su View log per visualizzare la sessione.

   

   Il log mostra la decisione inviata da ElevenLabs, la chiusura del WebSocket e cosa ha fatto poi lo scenario. In questo esempio il chiamante ha chiesto di parlare con una persona, quindi la decisione è transfer-to-agent con il motivo fornito dall’agente.