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 une interface utilisateur prête à l'emploi ou construisez la vôtre. Aucun WebRTC à configurer.

En résumé

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

• Un seul hook, useAethexCall(), gère l'appel. Trois widgets prêts à l'emploi sont disponibles par-dessus si vous ne souhaitez pas créer de bouton.

• Nouveautés de la v1.0.0 : support de React Native, commandes de mise en sourdine (mute) et de raccrochage en cours d'appel, et retour d'expérience post-appel.

• Livré en ESM, CJS et types. Compatible SSR, StrictMode et testé pour l'accessibilité 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 vous fournissent une couche de transport et un ensemble de callbacks, puis vous passez la semaine suivante à concevoir un bouton d'appel : l'état inactif, l'état de connexion, l'état d'accès microphone refusé, l'animation indiquant à l'utilisateur que le système est bien à l'écoute, le support clavier, les annonces pour lecteurs d'écran. L'infrastructure n'a jamais été la partie la plus longue. C'est l'interface qui l'était.

Ce SDK propose donc les deux, vous permettant de choisir votre niveau d'intégration.

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 passer de l'un à l'autre sans modifier votre configuration d'authentification ni réécrire votre logique d'appel.

Commencez avec le hook

useAethexCall() rassemble l'ensemble du SDK en un seul appel. Il gère les autorisations du microphone, la connexion peer-to-peer WebRTC, la fermeture de la session, 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("live"),
    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 devez donc gérer le rendu à partir de status et error plutôt que d'envelopper vos appels dans des blocs try/catch. De plus, le hook est compatible SSR (aucun API de navigateur n'est touché lors de l'import ou du rendu) et compatible StrictMode (la fermeture est idempotente). L'entrée React intègre une directive "use client", lui permettant de s'intégrer sans effort dans l'App Router de Next.js.

Après l'appel, récupérez la conversation avec getTranscript({ apiBaseUrl, sessionId }). Lisez vos transcriptions : c'est le meilleur outil de débogage de prompt à votre disposition.

Ou évitez complètement le développement UI

Si vous ne souhaitez pas concevoir le bouton, AethexVoiceOrb est une solution clé en main : un orb, un label et un statut en direct dans une capsule personnalisable, claire ou sombre.

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 habituel pour une bulle de chat ou de voix. Passez float={false} pour l'intégrer dans le flux, ou ajustez sa position avec float="bottom-left", floatOffset, et zIndex.

Deux autres widgets l'accompagnent. AethexCallButton est un bouton simple, et AethexVoiceWidget est un panneau doté d'un titre. Tous deux sont réservés au web. Sur mobile natif, utilisez l'orb ou appuyez-vous sur le hook.

Sécuriser votre clé d'API hors du client

Votre clé d'API doit impérativement rester sur votre serveur. Tout code envoyé au navigateur peut être lu par quiconque ouvre les outils de développement (DevTools). Le SDK est configuré pour lever une erreur si l'adresse apiBaseUrl ressemble à une clé.

Deux flux sont pris en charge, le second étant généralement celui à privilégier.

Proxy. Orientez apiBaseUrl vers un serveur léger qui relaie les requêtes en y injectant votre clé. Un exemple de Cloudflare Worker prêt pour la production est disponible dans le dépôt.

Tokens éphémères. Plutôt que de relayer chaque requête par proxy, générez un token à durée de vie limitée sur votre serveur et transmettez-le au client via getToken. Le SDK communique ensuite directement avec l'API d'Aethex, ce qui vous permet d'héberger une simple route de génération d'une ligne plutôt qu'un proxy complet :

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é d'API. Le token est restreint à un seul agent et expire à la fin de l'appel, garantissant sa sécurité dans le code client même en cas de fuite.

Une contrainte pour les navigateurs : l'origine de l'appelant doit être autorisée (CORS) sur l'API d'Aethex. React Native n'a pas cette restriction, c'est pourquoi getToken est le flux recommandé sur mobile.

Chaque agent a son propre orb

L'orb n'est pas une icône générique. Il est généré à partir du nom de l'agent : chaque agent que vous créez possède ainsi sa propre couleur et texture sans intervention de design. agentName définit l'empreinte de départ (seed) et orbType sélectionne la texture :

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

L'orb reste statique au repos et ne s'anime que lors de la connexion ou pendant un appel, évitant ainsi de détourner l'attention de votre interface. Il respecte la directive CSS prefers-reduced-motion.

Vous préférez la vidéo ? Utilisez videoSrc pour afficher un clip muet en boucle masqué dans un cercle. Deux exemples sont inclus dans le package et hébergés séparément afin de ne pas alourdir le bundle JS.

Contrôles et retours d'expérience, nouveautés v1.0.0

Par défaut, l'orb se présente sous la forme d'un simple bouton d'appel en un seul clic. Trois propriétés vous permettent d'aller plus loin si nécessaire.

controls ajoute un commutateur de mise en sourdine (mute) et un bouton rouge de raccrochage sous l'orb pendant l'appel. showVolume ajoute un curseur de volume de sortie sur le web. feedback affiche une demande d'évaluation en un clic une fois l'appel terminé.

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

Vous préférez concevoir votre propre interface ? Le hook expose directement ces mêmes commandes, notamment isMuted, toggleMute, setOutputVolume, et submitFeedback. Les retours d'expérience sont associés à l'appel ouvert par le token et restent fonctionnels après l'appel : vous pouvez ainsi solliciter une évaluation sur un écran de synthèse plutôt que d'interrompre la conversation.

React Native

Le même hook fonctionne sur mobile natif. Le package est livré avec un build natif que Metro résout automatiquement, l'import reste donc identique :

import { useAethexCall } from "@aethexai/react"

Sous le capot, le système utilise react-native-webrtc au lieu du WebRTC du navigateur, et l'audio de l'agent est automatiquement redirigé vers l'appareil. WebRTC étant un module natif, cette intégration requiert un build de développement Expo et ne fonctionnera pas 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 dispose pas de micro

L'orb fonctionne également sur mobile natif, rendu via Skia au lieu d'un canvas DOM, et accepte les mêmes propriétés, y compris controls et feedback.

Deux limites à noter : les hooks de niveau audio et isSpeaking reposent sur Web Audio et renverront donc 0 sur mobile natif (l'orb s'anime de manière autonome lors d'un appel au lieu de réagir au flux audio). De plus, AethexVoiceWidget et AethexCallButton sont réservés au web. Une application complète prête à l'emploi est disponible dans le répertoire examples/expo-app.

Niveau inférieur

Si vous n'utilisez pas React, @aethexai/react/core exporte VoiceCall, un client WebRTC TypeScript pur proposant le même cycle de vie via des callbacks : onStatusChange, onRemoteStream, onMetrics, onError, onClose. La méthode stop() est idempotente : elle désactive le micro, ferme la connexion peer-to-peer et en informe le serveur, quel que soit le nombre d'appels.

Cette version core ne requiert ni react ni react-dom.

Démarrage rapide

npm

Créez un agent, générez un token, et intégrez l'orb. Nous avons hâte d'entendre ce que le vôtre va raconter.