Voice SDK - Automation Anywhere EKB Docs

Le VoiceSDK offre des capacités de conversation vocale avancées avec l’intégration automatique du système de chat et des hooks React pour construire des applications compatibles avec la voix. Créez des interactions vocales naturelles avec des agents IA, complètes avec visualisation audio, transcription et gestion de conversation. Dans cet article, vous trouverez un exemple de démarrage rapide qui vous permettra non seulement de vous lancer rapidement, mais aussi de comprendre comment cela fonctionne. Le reste de l’article détaille les diverses méthodes que vous pouvez utiliser, à quoi elles servent et les meilleures pratiques.

Installation

npm install @odin-ai-staging/sdk @elevenlabs/react

Démarrage rapide

Conversation vocale basique

Dans cet exemple, vous apprendrez comment implémenter des conversations vocales en temps réel en utilisant le VoiceSDK dans les applications TypeScript et React. Vous commencez par initialiser le VoiceSDK avec vos identifiants API, y compris un agentId spécifique qui définit quel agent vocal IA gérera la conversation, puis utilisez startVoiceConversation() pour démarrer une session vocale avec des gestionnaires de rappel qui vous permettent de répondre aux événements de connexion, de recevoir des messages IA, de gérer les déconnexions et de traiter les transcriptions en direct de ce que dit l’utilisateur (isFinal indiquant quand une phrase complète a été reconnue). L’option saveToChat vous permet de persister la conversation vocale en tant que texte dans votre historique de chat pour une référence ultérieure. Pour les applications React, vous utiliserez le hook useVoiceConversation, qui fournit une interface plus propre avec la gestion d’état intégrée : il vous donne une variable status pour suivre l’état de la connexion, les méthodes startSession() et endSession() pour contrôler la conversation, setVolume() pour ajuster les niveaux audio, getInputByteFrequencyData() pour visualiser l’entrée audio (parfait pour créer des affichages de forme d’onde) et conversationState qui contient des informations en temps réel comme les niveaux de volume actuels. Cela vous donne tout ce dont vous avez besoin pour créer des applications vocales compatibles avec l’IA avec reconnaissance et synthèse vocale en temps réel, parfait pour créer des assistants vocaux, des interfaces sans mains ou des expériences conversationnelles d’IA, avec le hook React gérant toute la gestion d’état complexe et les connexions WebSocket pour vous.

import { VoiceSDK } from '@odin-ai-staging/sdk';

// Initialiser le SDK
const voiceSDK = new VoiceSDK({
  baseUrl: 'https://your-api-endpoint.com/',
  projectId: 'your-project-id',
  apiKey: 'your-api-key',
  apiSecret: 'your-api-secret',
  agentId: 'your-agent-id'
});

// Démarrer une conversation vocale
async function startVoiceChat() {
  const sessionId = await voiceSDK.startVoiceConversation({
    saveToChat: true,
    callbacks: {
      onConnect: () => console.log('Voix connectée'),
      onMessage: (message) => console.log('Message vocal:', message),
      onDisconnect: () => console.log('Voix déconnectée'),
      onTranscription: (text, isFinal) => {
        if (isFinal) console.log('Utilisateur a dit:', text);
      }
    }
  });
  
  console.log('Session vocale démarrée:', sessionId);
}

Utilisation du hook React

import { useVoiceConversation } from '@odin-ai-staging/sdk';

function VoiceChat() {
  const {
    status,
    startSession,
    endSession,
    setVolume,
    getInputByteFrequencyData,
    conversationState
  } = useVoiceConversation({
    sdkConfig: {
      baseUrl: 'https://your-api-endpoint.com/',
      projectId: 'your-project-id',
      agentId: 'your-agent-id'
    },
    callbacks: {
      onConnect: () => console.log('Connecté !'),
      onMessage: (message) => console.log('Message:', message)
    }
  });

  return (
    <div>
      <button 
        onClick={() => startSession()}
        disabled={status === 'connected'}
      >
        Démarrer le chat vocal
      </button>
      
      <button 
        onClick={() => endSession()}
        disabled={status !== 'connected'}
      >
        Terminer le chat
      </button>
      
      <div>Statut: {status}</div>
      <div>Volume: {conversationState.volume}</div>
    </div>
  );
}

Configuration

Interface VoiceSDKConfig

interface VoiceSDKConfig extends BaseClientConfig {
  agentId?: string;            // ID d'agent par défaut pour les conversations
  defaultVoiceSettings?: VoiceSettings;  // Configuration vocale par défaut
}

Paramètres vocaux

interface VoiceSettings {
  stability?: number;          // Stabilité vocale (0.0 à 1.0)
  similarityBoost?: number;    // Amplification de similarité vocale (0.0 à 1.0)
  style?: number;             // Style vocal (0.0 à 1.0)
  useSpeakerBoost?: boolean;  // Activer l'amplification du haut-parleur
}

Exemple de configuration :

const voiceSDK = new VoiceSDK({
  baseUrl: 'https://api.example.com/',
  projectId: 'proj_123',
  apiKey: 'your-api-key',
  apiSecret: 'your-api-secret',
  agentId: 'agent_456',
  defaultVoiceSettings: {
    stability: 0.8,
    similarityBoost: 0.7,
    style: 0.3,
    useSpeakerBoost: true
  }
});

Fonctionnalités principales

Sessions de conversation vocale

Le VoiceSDK gère les sessions de conversation vocale avec intégration automatique du chat :

interface VoiceConversationSession {
  id: string;                    // Identifiant de session
  chatId?: string;               // ID de chat associé
  startTime: number;             // Horodatage du début de session
  endTime?: number;              // Horodatage de fin de session
  messages: VoiceMessage[];      // Messages vocaux de la session
  metadata?: {
    agentId?: string;
    voiceSettings?: VoiceSettings;
    totalDuration?: number;
    userInfo?: { name: string; id: string };
  };
}

Messages vocaux

interface VoiceMessage {
  id: string;                    // ID du message
  type: 'user_speech' | 'ai_speech' | 'system';
  text: string;                  // Texte transcrit/généré
  audioUrl?: string;             // URL du fichier audio
  timestamp: number;             // Horodatage du message
  duration?: number;             // Durée audio en secondes
  voiceSettings?: VoiceSettings; // Paramètres vocaux utilisés
  saved?: boolean;               // Enregistré ou non en base de données
}

Gestion des sessions

`startVoiceConversation(options?)`

Démarrer une nouvelle session de conversation vocale.

async startVoiceConversation(
  options?: StartVoiceConversationOptions
): Promise<string>

Options StartVoiceConversationOptions :

interface StartVoiceConversationOptions {
  callbacks?: VoiceConversationCallbacks;
  saveToChat?: boolean;          // Enregistrement automatique dans l'historique de chat
  existingChatId?: string;       // Continuer un chat existant
  agentId?: string;             // Remplacer l'agent par défaut
  voiceSettings?: VoiceSettings; // Paramètres vocaux personnalisés
  userInfo?: { name: string; id: string };
}

Exemple :

const sessionId = await voiceSDK.startVoiceConversation({
  saveToChat: true,
  existingChatId: 'chat_123',
  voiceSettings: {
    stability: 0.9,
    similarityBoost: 0.8
  },
  userInfo: {
    name: 'Jean Dupont',
    id: 'user_456'
  },
  callbacks: {
    onConnect: () => console.log('Conversation vocale démarrée'),
    onMessage: (message) => handleVoiceMessage(message),
    onTranscription: (text, isFinal) => {
      if (isFinal) displayTranscription(text);
    },
    onConversationSaved: (chatId, messageId) => {
      console.log(`Conversation enregistrée dans le chat ${chatId}`);
    }
  }
});

`endVoiceSession(sessionId, reason?)`

Terminer une session de conversation vocale.

async endVoiceSession(sessionId: string, reason?: string): Promise<void>

Exemple :

await voiceSDK.endVoiceSession(sessionId, 'Utilisateur a terminé la conversation');

`getVoiceState(sessionId)`

Obtenir l’état actuel de la conversation vocale.

getVoiceState(sessionId: string): VoiceConversationState | null

Exemple :

const state = voiceSDK.getVoiceState(sessionId);
if (state) {
  console.log('Statut de connexion:', state.connectionStatus);
  console.log('Est en train de parler:', state.isSpeaking);
  console.log('Volume:', state.volume);
}

Intégration React

Hook useVoiceConversation

Le hook useVoiceConversation fournit l’intégration React avec la gestion d’état :

function useVoiceConversation(options: VoiceHookOptions): {
  // Propriétés du hook
  status: VoiceStatus;
  isSpeaking: boolean;
  startSession: (config?: VoiceSessionConfig) => Promise<string>;
  endSession: () => Promise<void>;
  setVolume: (options: { volume: number }) => void;
  
  // Propriétés SDK améliorées
  conversationState: VoiceConversationState;
  currentSessionId: string | null;
  getInputByteFrequencyData: () => Uint8Array | null;
  getOutputByteFrequencyData: () => Uint8Array | null;
}

Exemple React complet :

import React, { useState } from 'react';
import { useVoiceConversation } from '@odin-ai-staging/sdk';

function VoiceConversationComponent() {
  const [messages, setMessages] = useState<string[]>([]);
  const [isRecording, setIsRecording] = useState(false);

  const {
    status,
    isSpeaking,
    startSession,
    endSession,
    setVolume,
    conversationState,
    currentSessionId,
    getInputByteFrequencyData
  } = useVoiceConversation({
    sdkConfig: {
      baseUrl: process.env.REACT_APP_API_BASE_URL,
      projectId: process.env.REACT_APP_PROJECT_ID,
      agentId: process.env.REACT_APP_AGENT_ID
    },
    callbacks: {
      onConnect: () => {
        console.log('Connecté au chat vocal');
        setIsRecording(true);
      },
      onDisconnect: () => {
        console.log('Déconnecté du chat vocal');
        setIsRecording(false);
      },
      onTranscription: (text, isFinal) => {
        if (isFinal) {
          setMessages(prev => [...prev, `Vous: ${text}`]);
        }
      },
      onMessage: (message) => {
        if (message.type === 'ai_speech') {
          setMessages(prev => [...prev, `IA: ${message.text}`]);
        }
      },
      onError: (error) => {
        console.error('Erreur vocale:', error);
        setIsRecording(false);
      }
    }
  });

  const handleStartConversation = async () => {
    try {
      await startSession({
        saveToChat: true,
        voiceSettings: {
          stability: 0.8,
          similarityBoost: 0.7
        }
      });
    } catch (error) {
      console.error('Impossible de démarrer la conversation:', error);
    }
  };

  const handleEndConversation = async () => {
    try {
      await endSession();
    } catch (error) {
      console.error('Impossible de terminer la conversation:', error);
    }
  };

  const handleVolumeChange = (volume: number) => {
    setVolume({ volume });
  };

  return (
    <div className="voice-conversation">
      <div className="controls">
        <button 
          onClick={handleStartConversation}
          disabled={status === 'connected'}
        >
          Démarrer le chat vocal
        </button>
        
        <button 
          onClick={handleEndConversation}
          disabled={status !== 'connected'}
        >
          Terminer le chat vocal
        </button>
      </div>

      <div className="status">
        <div>Statut: {status}</div>
        <div>En train de parler: {isSpeaking ? 'Oui' : 'Non'}</div>
        <div>Enregistrement: {isRecording ? 'Oui' : 'Non'}</div>
        <div>Volume: {conversationState.volume}</div>
      </div>

      <div className="volume-control">
        <label>Volume:</label>
        <input
n          type="range"
          min="0"
          max="100"
          value={conversationState.volume}
          onChange={(e) => handleVolumeChange(parseInt(e.target.value))}
        />
      </div>

      <div className="messages">
        {messages.map((message, index) => (
          <div key={index} className="message">
            {message}
          </div>
        ))}
      </div>

      {currentSessionId && (
        <AudioVisualizer 
          getInputData={getInputByteFrequencyData}
          isActive={status === 'connected'}
        />
      )}
    </div>
  );
}

Contrôles vocaux

Contrôle du volume

// Définir le volume (0-100)
await voiceSDK.setVolume(sessionId, 75);

Contrôle du microphone

// Désactiver/activer le microphone
await voiceSDK.setMicrophoneMuted(sessionId, true);  // Désactiver
await voiceSDK.setMicrophoneMuted(sessionId, false); // Activer

Mises à jour des paramètres vocaux

// Mettre à jour les paramètres vocaux pendant la conversation
await voiceSDK.updateVoiceSettings(sessionId, {
  stability: 0.9,
  similarityBoost: 0.8,
  style: 0.4
});

Visualisation audio

Données audio en temps réel

// Obtenir les données de fréquence audio pour la visualisation
const audioData = voiceSDK.getAudioFrequencyData(sessionId);

if (audioData) {
  const inputData = audioData.input;   // Entrée audio de l'utilisateur
  const outputData = audioData.output; // Sortie audio de l'IA
  
  // Utiliser pour la visualisation audio
  renderAudioVisualization(inputData, outputData);
}

Composant de visualisation audio

import React, { useRef, useEffect } from 'react';

interface AudioVisualizerProps {
  getInputData: () => Uint8Array | null;
  isActive: boolean;
}

function AudioVisualizer({ getInputData, isActive }: AudioVisualizerProps) {
  const canvasRef = useRef<HTMLCanvasElement>(null);

  useEffect(() => {
    if (!isActive) return;

    const canvas = canvasRef.current;
    if (!canvas) return;

    const ctx = canvas.getContext('2d');
    if (!ctx) return;

    const animate = () => {
      const data = getInputData();
      
      if (data) {
        // Effacer le canevas
        ctx.clearRect(0, 0, canvas.width, canvas.height);
        
        // Dessiner les barres de fréquence
        const barWidth = canvas.width / data.length;
        
        for (let i = 0; i < data.length; i++) {
          const barHeight = (data[i] / 255) * canvas.height;
          
          ctx.fillStyle = `hsl(${i * 2}, 100%, 50%)`;
          ctx.fillRect(
            i * barWidth,
            canvas.height - barHeight,
            barWidth - 1,
            barHeight
          );
        }
      }
      
      requestAnimationFrame(animate);
    };

    animate();
  }, [isActive, getInputData]);

  return (
    <canvas 
      ref={canvasRef}
      width={400}
      height={100}
      className="audio-visualizer"
    />
  );
}

Intégration du chat

Enregistrement automatique du chat

Les conversations vocales peuvent être automatiquement enregistrées dans votre système de chat :

const sessionId = await voiceSDK.startVoiceConversation({
  saveToChat: true,  // Activer l'enregistrement automatique
  existingChatId: 'chat_123',  // Optionnel : continuer un chat existant
  callbacks: {
    onConversationSaved: (chatId, messageId) => {
      console.log(`Conversation vocale enregistrée dans le chat ${chatId}`);
      // Mettre à jour l'interface utilisateur pour afficher la conversation enregistrée
      refreshChatHistory(chatId);
    }
  }
});

Intégration manuelle du chat

// Obtenir l'historique de conversation à partir de la session vocale
const messages = voiceSDK.getConversationHistory(sessionId);

// Enregistrer dans le chat manuellement
for (const message of messages) {
  if (message.type === 'user_speech') {
    await chatSDK.sendMessage(message.text, {
      chatId: 'chat_123',
      metadata: {
        voiceMessage: true,
        audioUrl: message.audioUrl,
        sessionId: sessionId
      }
    });
  }
}

Mises à jour contextuelles

Envoyer du contexte supplémentaire à la conversation vocale :

// Envoyer le contexte de l'historique de chat
await voiceSDK.sendContextualUpdate(
  sessionId,
  'L\'utilisateur a précédemment posé des questions sur les prix. La conversation actuelle porte sur les fonctionnalités.'
);

Gestion des erreurs

try {
  const sessionId = await voiceSDK.startVoiceConversation({
    callbacks: {
      onError: (error) => {
        console.error('Erreur de conversation vocale:', error);
        
        // Gérer les types d'erreur spécifiques
        if (error.message.includes('microphone')) {
          showMicrophonePermissionDialog();
        } else if (error.message.includes('network')) {
          showNetworkErrorMessage();
        }
      },
      onDisconnect: (details) => {
        console.log('Déconnecté:', details?.reason);
        
        // Gérer différentes raisons de déconnexion
        if (details?.reason === 'user_ended') {
          showConversationSummary();
        } else if (details?.reason === 'error') {
          showReconnectOption();
        }
      }
    }
  });
} catch (error) {
  console.error('Impossible de démarrer la conversation vocale:', error);
  
  if (error.message.includes('agent')) {
    showAgentConfigError();
  }
}

Exemples

Support client avec voix

import { VoiceSDK, ChatSDK } from '@odin-ai-staging/sdk';

class VoiceCustomerSupport {
  private voiceSDK: VoiceSDK;
  private chatSDK: ChatSDK;
  private activeSession?: string;

  constructor() {
    const config = {
      baseUrl: process.env.API_BASE_URL,
      projectId: process.env.PROJECT_ID,
      apiKey: process.env.API_KEY,
      apiSecret: process.env.API_SECRET,
    };

    this.voiceSDK = new VoiceSDK(config);
    this.chatSDK = new ChatSDK(config);
  }

  async startSupportSession(customerId: string, issueType: string) {
    try {
      // Créer un nouveau chat pour cette session de support
      const chat = await this.chatSDK.createChat(
        `Support vocal - ${issueType}`,
        [] // Pourrait ajouter des clés de document pertinentes en fonction du type de problème
      );

      // Démarrer la conversation vocale
      this.activeSession = await this.voiceSDK.startVoiceConversation({
        saveToChat: true,
        existingChatId: chat.chat_id,
        agentId: this.getAgentForIssueType(issueType),
        userInfo: {
          name: `Client ${customerId}`,
          id: customerId
        },
        callbacks: {
          onConnect: () => {
            console.log('Session de support démarrée');
            this.logSupportEvent('session_started', { customerId, issueType });
          },
          onTranscription: (text, isFinal) => {
            if (isFinal) {
              this.logSupportEvent('customer_spoke', { 
                customerId, 
                text: text.substring(0, 100) // Enregistrer les 100 premiers caractères
              });
            }
          },
          onMessage: (message) => {
            if (message.type === 'ai_speech') {
              this.logSupportEvent('agent_responded', {
                customerId,
                responseLength: message.text.length
              });
            }
          },
          onConversationSaved: (chatId, messageId) => {
            console.log(`Conversation de support enregistrée dans le chat ${chatId}`);
          },
          onDisconnect: (details) => {
            this.logSupportEvent('session_ended', {
              customerId,
              reason: details?.reason,
              duration: this.getSessionDuration()
            });
          }
        }
      });

      return {
        sessionId: this.activeSession,
        chatId: chat.chat_id
      };
    } catch (error) {
      console.error('Impossible de démarrer la session de support:', error);
      throw error;
    }
  }

  async endSupportSession() {
    if (this.activeSession) {
      await this.voiceSDK.endVoiceSession(this.activeSession);
      this.activeSession = undefined;
    }
  }

  private getAgentForIssueType(issueType: string): string {
    const agentMap = {
      'technical': 'agent_technical_support',
      'billing': 'agent_billing_support',
      'general': 'agent_general_support'
    };
    return agentMap[issueType] || agentMap['general'];
  }

  private logSupportEvent(event: string, data: any) {
    console.log(`Événement de support: ${event}`, data);
    // Envoyer vers votre système d'analyse/journalisation
  }

  private getSessionDuration(): number {
    // Calculer la durée de la session
    return 0; // Espace réservé
  }
}

Meilleures pratiques

Gestion des erreurs et solutions de secours

const voiceSupport = {
  async startWithFallback() {
    try {
      return await this.voiceSDK.startVoiceConversation(options);
    } catch (error) {
      console.warn('Voix échouée, utilisation du chat texte comme solution de secours:', error);
      
      // Solution de secours : chat texte uniquement
      return await this.chatSDK.createChat('Chat support (texte)');
    }
  }
};

Gestion des ressources

class VoiceManager {
  private activeSessions = new Set<string>();

  async startSession(options: any) {
    const sessionId = await this.voiceSDK.startVoiceConversation(options);
    this.activeSessions.add(sessionId);
    return sessionId;
  }

  async cleanup() {
    // Terminer toutes les sessions actives
    for (const sessionId of this.activeSessions) {
      try {
        await this.voiceSDK.endVoiceSession(sessionId);
      } catch (error) {
        console.warn('Impossible de terminer la session:', sessionId, error);
      }
    }
    this.activeSessions.clear();
  }
}

Optimisation des performances

// Utiliser React.memo pour les composants de visualisation audio
const AudioVisualizer = React.memo(({ getInputData, isActive }) => {
  // Ralentir les mises à jour d'animation
  const throttledAnimate = useCallback(
    throttle(() => {
      // Logique d'animation
    }, 16), // ~60fps
    []
  );
  
  // ... logique du composant
});

Accessibilité

function VoiceAccessibleChat() {
  const [transcript, setTranscript] = useState('');
  
  const { startSession } = useVoiceConversation({
    callbacks: {
      onTranscription: (text, isFinal) => {
        setTranscript(text);
        
        // Mettre à jour le lecteur d'écran
        if (isFinal) {
          announceToScreenReader(`Vous avez dit: ${text}`);
        }
      }
    }
  });

  return (
    <div>
      <button 
        aria-label="Démarrer la conversation vocale"
        onClick={startSession}
      >
        🎤 Démarrer le chat vocal
      </button>
      
      <div 
        aria-live="polite"
        aria-label="Transcription vocale"
      >
        {transcript}
      </div>
    </div>
  );
}

​Installation

​Démarrage rapide

​Conversation vocale basique

​Utilisation du hook React

​Configuration

​Interface VoiceSDKConfig

​Paramètres vocaux

​Fonctionnalités principales

​Sessions de conversation vocale

​Messages vocaux

​Gestion des sessions

​startVoiceConversation(options?)

​endVoiceSession(sessionId, reason?)

​getVoiceState(sessionId)

​Intégration React

​Hook useVoiceConversation

​Contrôles vocaux

​Contrôle du volume

​Contrôle du microphone

​Mises à jour des paramètres vocaux

​Visualisation audio

​Données audio en temps réel

​Composant de visualisation audio

​Intégration du chat

​Enregistrement automatique du chat

​Intégration manuelle du chat

​Mises à jour contextuelles

​Gestion des erreurs

​Exemples

​Support client avec voix

​Meilleures pratiques

​Gestion des erreurs et solutions de secours

​Gestion des ressources

​Optimisation des performances

​Accessibilité

Installation

Démarrage rapide

Conversation vocale basique

Utilisation du hook React

Configuration

Interface VoiceSDKConfig

Paramètres vocaux

Fonctionnalités principales

Sessions de conversation vocale

Messages vocaux

Gestion des sessions

`startVoiceConversation(options?)`

`endVoiceSession(sessionId, reason?)`

`getVoiceState(sessionId)`

Intégration React

Hook useVoiceConversation

Contrôles vocaux

Contrôle du volume

Contrôle du microphone

Mises à jour des paramètres vocaux

Visualisation audio

Données audio en temps réel

Composant de visualisation audio

Intégration du chat

Enregistrement automatique du chat

Intégration manuelle du chat

Mises à jour contextuelles

Gestion des erreurs

Exemples

Support client avec voix

Meilleures pratiques

Gestion des erreurs et solutions de secours

Gestion des ressources

Optimisation des performances

Accessibilité