Voximplant

Créer ou sélectionner un agent

Concevez l’agent dans ElevenAgents. Donnez-lui un premier message s’il doit parler dès que l’appel se connecte. Les formats audio sont définis par l’intégration, les formats configurés pour l’agent ne sont donc pas utilisés pour les appels Voximplant.

Activer Fin d’appel

Dans Agent → Tools → System tools, activez End call afin que l’agent puisse terminer la conversation. La raison donnée par l’agent lorsqu’il termine l’appel est envoyée à votre scénario avec la décision.

Ajouter une règle de transfert Voximplant (facultatif)

Pour permettre à l’agent de transférer l’appelant vers un intervenant humain, attribuez-lui l’outil système Transfer to number avec une règle de transfert dont la configuration du fournisseur est voximplant. Cette règle n’a pas de destination : la conversation se termine par une décision transfer-to-agent et votre scénario achemine l’appelant. Les règles de transfert se configurent via l’API. Ajoutez l’outil avec une requête PATCH sur l’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"}}
            ]
          }]
        }
      }
    }}}}
  }'

Envoyez l’objet built_in_tools complet de l’agent, y compris les outils dont il dispose déjà, tels que end_call. L’option renvoyée par l’agent est le jeton fixe voximplant, une règle Voximplant par outil suffit donc. Les numéros de téléphone et URI SIP configurés pour d’autres fournisseurs ne sont pas proposés lors des appels Voximplant.

Créer une clé API dédiée

Créez une clé API dans le même Workspace que l’agent et limitez-la à ElevenAgents. Pour n’accepter que les connexions provenant de Voximplant, restreignez les adresses IP autorisées de la clé aux serveurs média de Voximplant, que Voximplant répertorie à l’adresse https://api.voximplant.com/getMediaResources?with_mediaservers.

Noter l’URL WebSocket

Le scénario se connecte à une URL contenant l’identifiant de votre agent :

Pour épingler une branche de l’agent, ajoutez ?branch_id=<branch_id>.

Créer une application

Dans le panneau de contrôle Voximplant, ouvrez Applications et cliquez sur Create application. Donnez-lui un nom, par exemple elevenlabs-agent, puis cliquez sur Create.

Enregistrer la clé API comme secret

Dans l’application, ouvrez Secrets et cliquez sur Add secret. Nommez-le ELEVENLABS_API_KEY, collez la clé API créée pour le Workspace de l’agent dans Value, puis cliquez sur Add secret. Le scénario la lit avec VoxEngine.getSecretValue(), la clé n’apparaît donc jamais dans le code du scénario.

Créer le scénario

Ouvrez Scenarios, cliquez sur Create scenario, nommez-le elevenlabs_agent, collez le code ci-dessous, remplacez l’identifiant de l’agent dans ELEVENLABS_URL, puis cliquez sur Save. Il répond à un appel entrant, le transmet à l’agent et agit selon la décision lorsque la conversation se termine. Pour un appel sortant, ouvrez le WebSocket dans le gestionnaire CallEvents.Connected de l’appel que vous avez émis.

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

Acheminer les appels vers le scénario

Ouvrez Routing, cliquez sur Create rule, donnez-lui un nom et attribuez-lui le scénario elevenlabs_agent. Le modèle par défaut .* envoie chaque appel vers l’application par le scénario ; restreignez-le à un numéro de téléphone si l’application traite également d’autres appels. Pour acheminer un numéro de téléphone, associez-le à l’application sous Numbers.

Effectuer un appel de test

Vous pouvez appeler l’application depuis le navigateur sans numéro de téléphone :

1. Ouvrez Users, cliquez sur Create user et créez un utilisateur avec un mot de passe.

   

2. Dans Routing, cliquez sur Test tools, puis sur Softphone. Connectez-vous avec cet utilisateur, autorisez l’accès au microphone, saisissez n’importe quelle destination et appelez. L’agent répond avec son premier message.

3. À la fin de l’appel, ouvrez Call history. Chaque appel répertorie une connexion WebSocket à côté de l’appel lui-même. Cliquez sur View log pour afficher la session.

   

   Le journal affiche la décision envoyée par ElevenLabs, la fermeture du WebSocket et l’action effectuée ensuite par le scénario. Dans cet exemple, l’appelant a demandé à parler à une personne, la décision est donc transfer-to-agent avec la raison fournie par l’agent.