Présentation du SDK React Aethex

Lancez un appel vocal en direct avec un seul hook, sur le web ou dans React Native. Intégrez l'interface utilisateur prête à l'emploi ou concevez la vôtre. Aucun protocole WebRTC à configurer.

La version courte

• @aethexai/react v1.0.0 est disponible sur npm dès aujourd'hui

• Un seul hook, useAethexCall(), gère l'appel. Trois widgets prêts à l'emploi s'y superposent si vous ne souhaitez pas coder de bouton.

• Nouveautés de la v1.0.0 : support de React Native, commandes de mise en sourdine et de raccrochage en direct, et retours post-appel.

• Livrable en ESM, CJS et types. Compatible SSR, StrictMode et accessibilité testée avec axe

  
  

Ce que nous livrons

Aujourd'hui, nous lançons la v1.0.0 du SDK React Aethex, la solution officielle pour intégrer un agent vocal en direct dans une application React.

La plupart des SDK vocaux sont headless. Ils fournissent une couche de transport et un ensemble de callbacks, vous laissant passer la semaine suivante à concevoir un bouton d'appel : l'état inactif, l'état de connexion, l'accès micro refusé, l'animation indiquant l'écoute active, le support clavier, les annonces pour lecteurs d'écran. La tuyauterie n'a jamais été le goulot d'étranglement. L'interface, si.

Ce SDK livre donc les deux, vous permettant de choisir votre niveau d'abstraction.

Au niveau le plus haut, une seule ligne génère un bouton vocal complet. Au niveau le plus bas, une classe VoiceCall agnostique au framework que vous pouvez piloter vous-même. Entre les deux, un hook et un ensemble de widgets. Vous pouvez naviguer de l'un à l'autre sans modifier votre configuration d'authentification ni réécrire votre logique d'appel.

Commencez avec le hook

useAethexCall() concentre l'ensemble du SDK en un seul appel. Il gère les autorisations du microphone, la connexion homologue WebRTC, la libération des ressources, et vous renvoie un état React standard.

"use client"
import { useAethexCall, useAudioLevel } from "@aethexai/react"

export function CallButton() {
  const { status, isConnected, start, stop, remoteStream, error } = useAethexCall({
    agentId: "YOUR_AGENT_ID",
    getToken,
    onConnected: () => console.log("en direct"),
    onError: (e) => console.error(e.code, e.recoverable),
  })
  const { level } = useAudioLevel(remoteStream)

  if (error) return <p>Échec de l'appel : {error.code}</p>
  return (
    <button onClick={isConnected ? stop : start}>
      {status === "connecting" ? "Connexion…" : isConnected ? "Raccrocher" : "Appeler"}
    </button>
  )
}

"use client"
import { useAethexCall, useAudioLevel } from "@aethexai/react"

export function CallButton() {
  const { status, isConnected, start, stop, remoteStream, error } = useAethexCall({
    agentId: "YOUR_AGENT_ID",
    getToken,
    onConnected: () => console.log("en direct"),
    onError: (e) => console.error(e.code, e.recoverable),
  })
  const { level } = useAudioLevel(remoteStream)

  if (error) return <p>Échec de l'appel : {error.code}</p>
  return (
    <button onClick={isConnected ? stop : start}>
      {status === "connecting" ? "Connexion…" : isConnected ? "Raccrocher" : "Appeler"}
    </button>
  )
}

"use client"
import { useAethexCall, useAudioLevel } from "@aethexai/react"

export function CallButton() {
  const { status, isConnected, start, stop, remoteStream, error } = useAethexCall({
    agentId: "YOUR_AGENT_ID",
    getToken,
    onConnected: () => console.log("en direct"),
    onError: (e) => console.error(e.code, e.recoverable),
  })
  const { level } = useAudioLevel(remoteStream)

  if (error) return <p>Échec de l'appel : {error.code}</p>
  return (
    <button onClick={isConnected ? stop : start}>
      {status === "connecting" ? "Connexion…" : isConnected ? "Raccrocher" : "Appeler"}
    </button>
  )
}

Deux détails importants. start() ne lève jamais d'exception ; vous gérez le rendu via status et error plutôt que d'encapsuler les appels de fonction dans des blocs try/catch. De plus, le hook est compatible SSR (aucun appel aux API du navigateur à l'importation ou au rendu) et compatible StrictMode (la libération des ressources est idempotente). L'entrée React intègre la directive "use client", facilitant son intégration dans l'App Router de Next.js.

Une fois l'appel terminé, récupérez la conversation avec getTranscript({ apiBaseUrl, sessionId }). L'analyse de vos transcriptions reste votre meilleur outil pour perfectionner vos prompts.

Ou passez l'étape de l'interface utilisateur

Si vous préférez ne pas concevoir de bouton, le composant AethexVoiceOrb est prêt à l'emploi : une sphère, un label et un statut en direct intégrés dans une capsule personnalisable, claire ou sombre.

import { AethexVoiceOrb } from "@aethexai/react/widgets"

<AethexVoiceOrb agentId={AGENT} getToken={getToken} title="Parler à Kora" />

import { AethexVoiceOrb } from "@aethexai/react/widgets"

<AethexVoiceOrb agentId={AGENT} getToken={getToken} title="Parler à Kora" />

import { AethexVoiceOrb } from "@aethexai/react/widgets"

<AethexVoiceOrb agentId={AGENT} getToken={getToken} title="Parler à Kora" />

Il s'affiche en bas à droite par défaut, l'emplacement standard pour une bulle de chat ou d'appel vocal. Passez float={false} pour l'intégrer dans le flux, ou ajustez-le avec float="bottom-left", floatOffset et zIndex.

Deux autres widgets sont également disponibles. AethexCallButton est un bouton standard, et AethexVoiceWidget est un panneau doté d'un titre. Tous deux sont exclusivement pour le web. Sur mobile natif, utilisez l'orb ou passez par le hook.

Sécuriser votre clé API hors du client

Votre clé API doit impérativement rester sur votre serveur. Tout code envoyé au navigateur peut être lu dans les outils de développement. Le SDK est configuré pour lever une erreur si apiBaseUrl ressemble à une clé sous forme de chaîne.

Deux flux sont pris en charge, le second étant généralement le plus recommandé.

Proxy. Orientez apiBaseUrl vers un service léger chargé de transférer les requêtes et d'y injecter votre clé. Un exemple de Cloudflare Worker prêt pour la production est inclus dans le dépôt.

Jetons éphémères. Plutôt que de relayer chaque requête, générez un jeton à durée de vie limitée sur votre serveur et transmettez-le au client via getToken. Le SDK communique alors directement avec l'API Aethex, réduisant votre infrastructure à une simple route de génération de jeton plutôt qu'un proxy complet :

useAethexCall({
  agentId,
  getToken: async () => {
    const res = await fetch("/api/aethex-token", { method: "POST" })
    return (await res.json()).token
  },
})

useAethexCall({
  agentId,
  getToken: async () => {
    const res = await fetch("/api/aethex-token", { method: "POST" })
    return (await res.json()).token
  },
})

useAethexCall({
  agentId,
  getToken: async () => {
    const res = await fetch("/api/aethex-token", { method: "POST" })
    return (await res.json()).token
  },
})

Votre route de génération appelle POST /api/v1/conversation/token avec votre clé API. Le jeton est restreint à un agent spécifique et expire à la fin de l'appel, garantissant sa sécurité côté client en cas d'exposition.

Une spécificité pour les navigateurs : l'origine des utilisateurs doit être autorisée par CORS sur l'API Aethex. React Native n'a pas cette contrainte, ce qui fait de getToken le flux recommandé sur mobile.

Chaque agent a son propre orb

L'orb n'est pas une simple icône générique. Il est généré dynamiquement à partir du nom de l'agent, garantissant à chaque agent sa propre palette de couleurs et sa texture sans intervention de design. agentName définit la valeur d'initialisation (seed) et orbType sélectionne la texture :

<AethexVoiceOrb agentId={AGENT} getToken={getToken} orbType="liquid" agentName="Kora" />

<AethexVoiceOrb agentId={AGENT} getToken={getToken} orbType="liquid" agentName="Kora" />

<AethexVoiceOrb agentId={AGENT} getToken={getToken} orbType="liquid" agentName="Kora" />

L'orb reste statique en mode inactif et s’anime uniquement durant la connexion ou l'appel, évitant de surcharger visuellement votre interface. Il respecte la directive d'accessibilité prefers-reduced-motion.

Vous préférez la vidéo ? Utilisez videoSrc pour intégrer un clip muet en boucle masqué sous forme de cercle. Deux fichiers vidéo sont inclus dans le package et stockés séparément pour optimiser le poids du bundle JS initial.

Commandes et retours, nouveautés de la v1.0.0

L'orb brut s'utilise par défaut comme un simple bouton d'appel à touche unique. Trois propriétés permettent d'enrichir l'expérience utilisateur selon vos besoins.

controls ajoute un interrupteur de mise en sourdine (mute) et un bouton rouge de fin d'appel sous l'orb pendant la communication. showVolume intègre un curseur de contrôle du volume de sortie sur le web. feedback lance une invitation de notation rapide dès que l'appel prend fin.

<AethexVoiceOrb agentId={AGENT} getToken={getToken} controls showVolume feedback />

<AethexVoiceOrb agentId={AGENT} getToken={getToken} controls showVolume feedback />

<AethexVoiceOrb agentId={AGENT} getToken={getToken} controls showVolume feedback />

Vous développez votre propre interface ? Le hook expose ces mêmes commandes de manière directe, incluant isMuted, toggleMute, setOutputVolume et submitFeedback. La soumission de feedback est rattachée à la session initiée par le jeton et reste active après l'appel, vous permettant de solliciter un retour sur un écran récapitulatif sans interrompre le fil de la conversation.

React Native

Le même hook est pris en charge sur environnement natif. Le package distribue un build natif résolu automatiquement par Metro, conservant l'import d'origine inchangé :

import { useAethexCall } from "@aethexai/react"

import { useAethexCall } from "@aethexai/react"

import { useAethexCall } from "@aethexai/react"

Sous le capot, l'exécution s'appuie sur react-native-webrtc au lieu de l'API WebRTC du navigateur, et le flux audio de l'agent est automatiquement routé vers le haut-parleur de l'appareil. Le protocole WebRTC s'appuyant sur un module natif, son exécution nécessite un build de développement Expo et n'est pas supportée dans Expo Go :

npx expo install react-native-webrtc @config-plugins/react-native-webrtc expo-dev-client
npx expo prebuild --clean
npx expo run:ios --device   # iOS requiert un appareil physique ; le Simulateur ne prend pas en charge le micro

npx expo install react-native-webrtc @config-plugins/react-native-webrtc expo-dev-client
npx expo prebuild --clean
npx expo run:ios --device   # iOS requiert un appareil physique ; le Simulateur ne prend pas en charge le micro

npx expo install react-native-webrtc @config-plugins/react-native-webrtc expo-dev-client
npx expo prebuild --clean
npx expo run:ios --device   # iOS requiert un appareil physique ; le Simulateur ne prend pas en charge le micro

L'orb fonctionne également en natif, rendu avec Skia à la place d'un canvas DOM, et accepte des paramètres équivalents tels que controls et feedback.

Deux contraintes techniques subsistent. Les hooks de niveau audio et isSpeaking dépendent de Web Audio, renvoyant la valeur 0 en natif ; l'orb s'anime de manière autonome pendant l'appel au lieu de réagir dynamiquement à l'audio. De plus, AethexVoiceWidget et AethexCallButton sont limités au web. Une application exemple pleinement exploitable est disponible sous examples/expo-app.

Accéder aux couches inférieures

Si vous n'utilisez pas React, @aethexai/react/core exporte VoiceCall, un client WebRTC écrit en TypeScript standard, exposant le même cycle de vie sous forme de callbacks : onStatusChange, onRemoteStream, onMetrics, onError, onClose. La méthode stop() est idempotente : elle désactive le micro, ferme le canal de communication homologue et notifie le serveur, indépendamment du nombre d'appels successifs.

Cette version core ne requiert ni react ni react-dom comme dépendances.

Démarrer

npm

npm

npm

Configurez votre agent, générez un jeton et intégrez l'orb. Nous avons hâte de découvrir l'expérience vocale que vous allez concevoir.