Webchat WebChat Widget

Widget de chat embeddable pour intégrer Webchat sur n'importe quel site web.

🚀 Installation

Via CDN (Recommandé)

Ajoutez ce code juste avant la fermeture de la balise </body> de votre site :

<script>
  window.webchatConfig = {
    apiUrl: "https://votre-api.com",
    siteId: "votre-site-id",
    agentName: "Support",
    welcomeMessage: "Besoin d'aide ?",
    autoOpen: false,
    autoOpenDelay: 5,
    primaryColor: "#4299e1",
  };
</script>
<script
  src="https://cdn.jsdelivr.net/npm/@webchat/webchat-widget@latest/dist/webchat.umd.js"
  async
></script>

Via NPM

npm install @webchat/webchat-widget

import "@webchat/webchat-widget/dist/webchat.css";
import "@webchat/webchat-widget";

// Configuration
window.webchatConfig = {
  apiUrl: "https://votre-api.com",
  siteId: "votre-site-id",
  // ... autres options
};

⚙️ Configuration

Options disponibles

| Option | Type | Défaut | Description | | ---------------- | ------- | ----------------------- | ------------------------------------- | | apiUrl | string | http://localhost:8080 | URL de l'API Webchat | | siteId | string | Requis | ID unique de votre site | | agentName | string | "Support" | Nom affiché de l'agent | | welcomeMessage | string | "Besoin d'aide ?" | Message d'accueil | | autoOpen | boolean | false | Ouverture automatique du chat | | autoOpenDelay | number | 5 | Délai avant ouverture auto (secondes) | | primaryColor | string | "#4299e1" | Couleur principale du widget | | position | string | "bottom-right" | Position du widget |

Positions disponibles

• bottom-right (défaut)
• bottom-left
• top-right
• top-left

🎨 Personnalisation

Couleurs

Le widget utilise des variables CSS que vous pouvez surcharger :

:root {
  --webchat-webchat-primary-color: #your-color;
  --webchat-webchat-primary-hover: #your-hover-color;
  --webchat-webchat-bg-color: #ffffff;
  --webchat-webchat-text-color: #2d3748;
}

Styles personnalisés

Vous pouvez ajouter vos propres styles en ciblant les classes du widget :

.webchat-webchat-widget {
  /* Vos styles personnalisés */
}

.webchat-webchat-toggle-btn {
  /* Personnaliser le bouton */
}

🔧 API JavaScript

Méthodes disponibles

// Accéder à l'instance du widget
const widget = window.webchatWidget;

// Ouvrir le chat
widget.openChat();

// Fermer le chat
widget.closeChat();

// Basculer l'état du chat
widget.toggleChat();

// Envoyer un message programmatiquement
widget.sendMessage("Bonjour !");

// Vérifier si le chat est ouvert
console.log(widget.isOpen);

Événements

// Écouter les événements du widget
document.addEventListener("webchat:ready", () => {
  console.log("Widget prêt");
});

document.addEventListener("webchat:opened", () => {
  console.log("Chat ouvert");
});

document.addEventListener("webchat:closed", () => {
  console.log("Chat fermé");
});

document.addEventListener("webchat:message", (event) => {
  console.log("Nouveau message:", event.detail);
});

📱 Responsive

Le widget est entièrement responsive et s'adapte automatiquement aux écrans mobiles.

🌙 Mode sombre

Le widget détecte automatiquement la préférence de mode sombre de l'utilisateur via prefers-color-scheme: dark.

🔒 Sécurité

• Authentification automatique des visiteurs anonymes
• Tokens JWT temporaires (24h)
• Validation côté serveur
• Protection CORS

🚀 Développement

Prérequis

• Node.js 18+
• npm ou yarn

Installation

git clone https://github.com/votre-org/webchat-widget.git
cd webchat-widget
npm install

Scripts disponibles

# Développement avec watch
npm run dev

# Build de production
npm run build

# Build de développement
npm run build:dev

# Prévisualisation
npm run preview

Structure du projet

webchat-widget/
├── src/
│   ├── webchat.js      # Script principal
│   └── webchat.css     # Styles
├── dist/               # Fichiers buildés
├── vite.config.js      # Configuration Vite
└── package.json

📦 Distribution

Le widget est distribué via :

• jsDelivr CDN : https://cdn.jsdelivr.net/npm/@webchat/webchat-widget@latest/dist/webchat.umd.js
• NPM : npm install @webchat/webchat-widget

🐛 Débogage

Mode debug

Ajoutez debug: true à votre configuration pour activer les logs détaillés :

window.webchatConfig = {
  // ... autres options
  debug: true,
};

Problèmes courants

1. Widget ne s'affiche pas

   • Vérifiez que siteId est défini
   • Vérifiez la console pour les erreurs

2. Connexion WebSocket échoue

   • Vérifiez l'URL de l'API
   • Vérifiez la configuration CORS

3. Styles cassés

   • Vérifiez que le CSS est bien chargé
   • Vérifiez les conflits avec vos styles

📄 Licence

MIT License - voir le fichier LICENSE pour plus de détails.

🤝 Contribution

Les contributions sont les bienvenues ! Voir CONTRIBUTING.md pour les guidelines.