Composant React - ThunderPhone

Le composant ThunderPhoneWidget affiche une barre d’appel au style glassmorphique avec des commandes intégrées pour couper le son, terminer l’appel et afficher l’état de connexion. C’est le moyen le plus rapide d’ajouter une IA vocale à une application React.

Installation

npm install @thunderphone/widget

Utilisation de base

import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'

function App() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
    />
  )
}

Vous devez importer le fichier CSS pour que le widget s’affiche correctement. Sans lui, le widget ne sera pas stylisé.

Props

Le composant accepte les props suivantes via ThunderPhoneWidgetProps :

Prop	Type	Obligatoire	Par défaut	Description
`publishableKey`	`string`	Oui	—	Clé API publiable (`pk_live_...`) des paramètres Développeurs. L’agent est résolu automatiquement à partir de la configuration du widget de la clé.
`theme`	`'light' \| 'dark'`	Non	`'light'`	Jeu de couleurs. Applique la classe `tp--light` ou `tp--dark` à la racine du widget.
`primaryColor`	`string`	Non	`'#000000'` (clair) / `'#ffffff'` (foncé)	Chaîne de couleur CSS utilisée comme couleur d’accentuation (bouton d’appel, forme d’onde, indicateurs actifs).
`title`	`string`	Non	`'Voice assistant'`	Texte affiché dans la barre du widget.
`position`	`'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left'`	Non	`'bottom-right'`	Position fixe du widget dans la fenêtre d’affichage.
`apiBase`	`string`	Non	`'https://api.thunderphone.com/v1'`	Remplacement de l’URL de base de l’API.
`language`	`string`	Non	—	Remplacement de la langue par session — un code de langue ou des paramètres régionaux tels que `en`, `es` ou `fr-FR`. Lorsqu’elle n’est pas définie, la langue configurée de l’agent s’applique.
`voice`	`string`	Non	—	Remplacement de la voix par session — un nom de voix tel que `maria`. Lorsqu’elle n’est pas définie, la voix configurée de l’agent s’applique.
`context`	`string`	Non	—	Contexte factuel de la page ou du site, transmis à l’agent pour chaque session (par exemple, les détails de la page consultée par le visiteur). Tronqué côté serveur à 12 000 caractères.
`onConnect`	`() => void`	Non	—	Appelé lorsque la session vocale se connecte avec succès.
`onDisconnect`	`() => void`	Non	—	Appelé lorsque la session se termine.
`onError`	`(error) => void`	Non	—	Appelé en cas d’erreur. L’objet `error` comporte les champs `error` (code) et `message`.
`className`	`string`	Non	—	Nom de classe CSS supplémentaire appliqué au conteneur du widget.
`ringtone`	`boolean \| string`	Non	`false`	Joue une sonnerie pendant la connexion. `true` pour la sonnerie par défaut, ou une chaîne d’URL pour un audio personnalisé.

Exemples

Thème sombre avec couleur personnalisée

import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'

function App() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      theme="dark"
      primaryColor="#8b5cf6"
      title="Talk to our AI"
    />
  )
}

Position personnalisée

import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'

function App() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      position="bottom-left"
    />
  )
}

Langue, voix et contexte par session

Les props language, voice et context sont transmises à la requête de session (POST /widget/session) au démarrage d’un appel, en remplaçant les valeurs par défaut configurées de l’agent pour cette session :

import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'

function PricingPageWidget() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      language="es"
      voice="maria"
      context="Page: Pricing. Plans: Starter $29/mo, Pro $99/mo. Annual billing saves 20%."
    />
  )
}

Utilisez context pour fournir à l’agent des informations factuelles sur la page consultée par le visiteur : détails du produit, tarifs ou FAQ propres à la page. Son contenu est tronqué côté serveur à 12 000 caractères.

Avec des rappels d’événements

import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'

function SupportWidget() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      onConnect={() => {
        console.log('Voice session connected')
        analytics.track('widget_call_started')
      }}
      onDisconnect={() => {
        console.log('Voice session ended')
        analytics.track('widget_call_ended')
      }}
      onError={(error) => {
        console.error(`Widget error: ${error.error} - ${error.message}`)
      }}
    />
  )
}

Avec un style personnalisé

import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'

function BrandedWidget() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      primaryColor="#4a90d9"
      className="my-custom-widget"
    />
  )
}

.my-custom-widget .tp-button--end {
  background-color: #e74c3c;
}

Consultez le guide de style pour voir toutes les classes CSS et propriétés personnalisées disponibles.

Avec sonnerie

Jouez un son de téléphone qui sonne pendant l’établissement de la connexion :

import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'

function PhoneWidget() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      ringtone={true}
    />
  )
}

Utilisez une sonnerie personnalisée en transmettant l’URL d’un fichier audio :

<ThunderPhoneWidget
  publishableKey="pk_live_your_publishable_key"
  ringtone="https://example.com/my-ringtone.mp3"
/>

La sonnerie se répète tant que le widget est dans l’état connecting et s’estompe progressivement lorsque l’agent se connecte.

Avec une base API personnalisée

Vous devez définir apiBase uniquement si vous utilisez un point de terminaison d’API auto-hébergé ou proxy. La valeur par défaut pointe vers https://api.thunderphone.com/v1.

<ThunderPhoneWidget
  publishableKey="pk_live_your_publishable_key"
  apiBase="https://your-proxy.example.com/v1"
/>

Gestion des erreurs

Lorsque le rappel onError est déclenché, il reçoit un objet d’erreur comportant deux champs :

Champ	Type	Description
`error`	`string`	Code d’erreur lisible par machine
`message`	`string`	Description d’erreur lisible par un humain

Les codes d’erreur courants incluent un domaine non autorisé, un agent introuvable et une clé API non valide.

Étapes suivantes

Hook headless

Besoin d’un contrôle total sur l’interface utilisateur ? Utilisez plutôt le hook useThunderPhone.

Style

Personnalisez les couleurs, les tailles et la mise en page avec des propriétés CSS personnalisées.

​Installation

​Utilisation de base

​Props

​Exemples

​Thème sombre avec couleur personnalisée

​Position personnalisée

​Langue, voix et contexte par session

​Avec des rappels d’événements

​Avec un style personnalisé

​Avec sonnerie

​Avec une base API personnalisée

​Gestion des erreurs

​Étapes suivantes

Hook headless

Style

Installation

Utilisation de base

Props

Exemples

Thème sombre avec couleur personnalisée

Position personnalisée

Langue, voix et contexte par session

Avec des rappels d’événements

Avec un style personnalisé

Avec sonnerie

Avec une base API personnalisée

Gestion des erreurs

Étapes suivantes