Configurer le widget externe

Q: Comment le widget se charge-t-il sur mon site ?

Ajoutez la balise . Le chargeur récupère le code du widget, applique les attributs data-* et initialise la conversation. Vérifiez l’adresse du site, la clé et les règles réseau de la page si le chargement échoue.

Q: Puis-je personnaliser le widget sans modifier son code ?

Oui. Les options prévues se règlent avec les attributs data-* de la balise d’intégration. Consultez Personnaliser l’interface du widget pour les valeurs prises en charge. La modification de ces attributs nécessite l’accès au code d’intégration de votre site.

Financement et utilisation de l’IA

IA incluse utilise des crédits REDA. Votre propre IA utilise le compte fournisseur de votre organisation, facturé directement par ce fournisseur. La licence définit un mode pour toute l’organisation. Dans les deux cas, REDA AI gouverne les outils et actions configurés dans Salesforce. Configurer la licence et les comptes IA.

Si l’administrateur change la connexion effective, le modèle ou le financement, les sessions concernées doivent démarrer une nouvelle conversation. Faites-le lorsque demandé ; l’ancienne conversation ne peut pas continuer sur le nouveau circuit. Pour les comptes clients, vérifiez l’accès aux identifiants de l’invité du site ou de l’utilisateur connecté au portail. Voir les permissions.

Un chatbot destiné aux visiteurs de votre site Le canal Widget externe permet d’intégrer un agent REDA AI à votre site web. Les visiteurs peuvent échanger avec lui sans compte Salesforce.

Un canal adapté à l’interface

Un agent dont Canal = Widget externe (External_Widget) est destiné à cette interface publique. Il ne doit pas être appelé depuis le composant interne Salesforce, un flux ou Apex utilisant le canal API, ni depuis le composant communautaire. Le point d’accès public /chat/v1/* vérifie que le canal de l’agent est External_Widget. Choisissez le canal correspondant à l’interface de déploiement.

Le widget ajoute une conversation REDA AI à un site ou à une application web. Les visiteurs peuvent poser des questions et consulter les informations que votre configuration autorise à rendre publiques, sans se connecter à Salesforce. Pour un portail avec identification des utilisateurs, utilisez le canal Communauté adapté.

Sans connexion Salesforce pour le visiteur — Le widget utilise la clé publique configurée pour l’agent ; celle-ci n’authentifie pas une personne.
Accès invité — L’intégration utilise l’utilisateur invité du site Salesforce, avec les accès et outils que vous avez configurés.
Origines autorisées — Vous limitez les sites web depuis lesquels le navigateur peut initialiser le chatbot.
Apparence configurable — Couleurs, textes, présentation, bouton de lancement et accueil se règlent avec les attributs d’intégration.
Adaptation au mobile — Le widget s’adapte aux petits écrans et propose un mode plein écran.

Vue d’ensemble de la configuration

Configurer la définition de l’agent
Choisissez le canal Widget externe, puis configurez les origines autorisées, le message d’accueil et les outils.
Générer la clé API
Générez la clé API externe utilisée par le widget et vérifiez le site Salesforce associé.
Intégrer le widget
Ajoutez la balise de chargement sur votre site, avec la clé publique et l’adresse du point d’accès.
Personnaliser l’apparence
Ajoutez, si nécessaire, des attributs data-* pour les couleurs, la présentation, le bouton et l’accueil.

Étape 1 : configurer la définition de l’agent

Ouvrez Définitions des agents dans l’application REDA AI.
Ouvrez une définition existante ou créez l’agent destiné aux visiteurs.
Réglez Canal sur Widget externe (External_Widget).
Renseignez Origines autorisées avec les origines des sites concernés, par exemple https://example.com, https://www.example.com.
Renseignez Message de bienvenue externe, par exemple « Bonjour ! Comment pouvons-nous vous aider ? ».
Si vous le souhaitez, configurez une Image de mascotte pour personnaliser l’avatar.
Attribuez uniquement les outils adaptés au canal public ; commencez par des consultations de données destinées aux visiteurs.
Activez l’agent lorsque sa configuration est prête, puis testez-le avec les accès réels du site.

Étape 2 : générer une clé API

Le widget utilise une clé API externe liée à l’agent. Consultez Gestion des clés API pour la génération, le site Salesforce et les autorisations nécessaires. Relevez les deux valeurs suivantes dans l’interface :

Clé API — La clé générée pour cet agent.
URL du point d’accès — L’adresse REST du site Salesforce, par exemple https://<org>.my.salesforce-sites.com/chat/services/apexrest/redaai/chat/v1. Utilisez l’adresse réelle de votre site, dont le domaine et le chemin peuvent différer.

Ajoutez une balise <script> à votre page. Le chargeur REDA AI récupère le widget, applique les paramètres d’intégration et initialise la conversation.

Intégration minimale : attributs obligatoires

<script
  src="https://<org>.my.salesforce-sites.com/chat/resource/redaai__REDAAILoader"
  data-api-key="your-api-key-here"
  data-endpoint="https://<org>.my.salesforce-sites.com/chat/services/apexrest/redaai/chat/v1">
</script>

Remplacez <org> et le chemin du site par les valeurs de votre installation, puis your-api-key-here par la clé générée. Les valeurs du bloc sont des exemples.

À savoir

Les attributs data-api-key et data-endpoint sont obligatoires. Vérifiez aussi que le navigateur peut charger la ressource et joindre le point d’accès.

Cette clé est publique. Elle figure dans le HTML de votre site et peut être copiée. Le contrôle Origines autorisées vérifie l’en-tête Origin fourni par le navigateur lors de l’initialisation ; il ne constitue pas une authentification pour les clients serveur, qui peuvent fabriquer cet en-tête. Les droits de l’utilisateur invité et la sécurité des outils exposés doivent limiter les données et les opérations réellement accessibles. Ajoutez aussi des limites d’utilisation adaptées.

Exemple d’intégration avec personnalisation

Les attributs facultatifs data-* règlent l’apparence et le comportement du widget. Les textes anglais ci-dessous sont des valeurs d’exemple à remplacer par vos textes français :

<script
  src="https://<org>.my.salesforce-sites.com/chat/resource/redaai__REDAAILoader"
  data-api-key="your-api-key-here"
  data-endpoint="https://<org>.my.salesforce-sites.com/chat/services/apexrest/redaai/chat/v1"
  data-title="Support Agent"
  data-primary-color="#0070D2"
  data-bubble-style="pill"
  data-bubble-label="Ask Support"
  data-header-style="minimal"
  data-welcome-heading="How can {title} help?"
  data-welcome-subtext="Ask me anything about your account"
  data-theme="light"
  data-position="bottom-right"
  data-display-mode="bubble">
</script>

Vous préférez un panneau latéral pleine hauteur ? Utilisez data-display-mode="docked-right" ou docked-left. L’assistant s’ouvre alors sur le bord choisi, ce qui peut faciliter l’affichage de cartes et de photos. La position du bouton de lancement reste indépendante. Consultez Mode d’affichage.

Consultez Personnaliser l’interface du widget pour la liste complète des attributs data-*.

Configurer les origines autorisées

Le champ Origines autorisées limite les origines web acceptées à l’initialisation du widget. Il contribue à empêcher qu’un autre site utilise votre agent depuis le navigateur de ses visiteurs.

Une liste vide autorise toutes les origines.

Une liste vide n’impose aucune restriction d’origine. Un autre site disposant de la clé publique peut alors tenter d’utiliser l’agent. La clé étant visible dans le code de la page, comme expliqué à l’étape 2, renseignez les origines pour encadrer l’utilisation depuis les navigateurs.

Configurez cette liste pour chaque widget ouvert aux visiteurs.

Exemple d’origines

https://example.com, https://www.example.com, https://support.example.com

Dans cet exemple, les initialisations provenant des navigateurs sont limitées à ces trois origines.

Incluez le protocole — https://example.com et example.com ne représentent pas la même valeur de configuration.
Séparez les origines par des virgules.
Indiquez chaque origine réellement utilisée — Si votre site répond à www.example.com et à example.com, renseignez les deux origines complètes avec leur protocole.
Testez avant l’ouverture au public — Ajoutez l’origine de préproduction pendant les essais et vérifiez l’initialisation depuis ce site.

Fonctionnement du contrôle d’origine

Dans un navigateur, l’en-tête Origin reflète normalement l’origine de la page et ne peut pas être remplacé librement par son JavaScript. Une clé copiée sur un autre site ne suffit donc pas à passer cette vérification lorsque la liste est correctement configurée.

Un appel sans en-tête Origin attendu peut être refusé. Un client serveur peut toutefois envoyer cet en-tête lui-même : ne désactivez pas la liste en pensant qu’elle devient une authentification serveur. Pour une intégration de serveur à serveur, définissez un mécanisme d’accès adapté. Les limites de débit par session et par heure, ainsi que le plafond quotidien global de crédits, restent des contrôles complémentaires.

Lors d’une mise à niveau, vérifiez la valeur déjà enregistrée. Une liste vide laisse les origines sans restriction ; contrôlez-la avant d’ouvrir ou de reconduire un déploiement public.

Comprenez la portée de cette liste. Le navigateur fournit l’en-tête Origin, ce qui permet de bloquer l’intégration sur un autre site web. La liste ne peut pas arrêter à elle seule un client serveur qui fabrique cet en-tête, par exemple avec curl.

Les contrôles de données et d’outils, les limites de débit, le plafond quotidien de crédits et la révocation de la clé complètent cette protection. Le filtrage d’origine ne remplace pas l’identification d’un utilisateur ni une autorisation d’accès à ses données privées.

Autorisations de l’utilisateur invité

Le widget utilise le contexte invité du site Salesforce. Vérifiez les droits effectifs et les chemins d’exécution de chaque outil exposé :

Accès aux objets limité — Autorisez seulement les objets nécessaires aux visiteurs, par exemple des articles publics ou la création de demandes d’assistance.
Accès aux champs limité — Exposez uniquement les champs destinés à être publics.
Partage des enregistrements — Vérifiez les règles de partage invité et les autres contrôles applicables ; une conversation anonyme ne doit pas donner accès à des données propres à un client identifié.
Création facultative — Si nécessaire, autorisez un parcours précis de création, par exemple une demande d’assistance, avec les validations adaptées.

Vérifier avant le déploiement

Examinez le profil invité, les règles de partage et la sécurité des outils personnalisés. Testez comme visiteur anonyme : un essai avec un administrateur connecté ne démontre pas les accès réels du widget.

Choisir les outils du widget externe

Le tableau suivant aide à définir le besoin. La disponibilité réelle dépend des canaux autorisés par les métadonnées de l’outil et de votre configuration : n’exposez pas un outil simplement parce qu’il est cité ici.

Outil	À envisager ?	Remarques
`soql_query`	Selon le besoin	Pour rechercher uniquement des enregistrements destinés au public, avec les contrôles de l’outil vérifiés.
`get_record`	Selon le besoin	Pour consulter des détails publics, si cet outil est autorisé sur le canal externe dans votre version et votre configuration.
`count_records`	Selon le besoin	Pour compter des données publiques, uniquement si les métadonnées de l’outil autorisent ce canal.
`create_record`	Usage ciblé	Pour créer une demande ou un prospect, si ce parcours est prévu. Limitez les objets, les champs et les opérations dans la configuration et le code applicables.
`describe_object`	Non par défaut	L’exposition du schéma n’est généralement pas nécessaire aux visiteurs ; évaluez précisément tout besoin avant d’élargir les accès.
`send_email`	Non par défaut	Un envoi d’e-mail anonyme peut être détourné. Ne l’exposez pas comme une fonction générale de messagerie publique.
`update_record` / `delete_record`	Non par défaut	Évitez les modifications ou suppressions par des visiteurs anonymes. Une intégration exigeant de telles opérations nécessite un parcours d’autorisation spécifiquement conçu.
`web_search`	Facultatif	Activez la recherche web sur l’agent si elle répond au besoin. Chaque recherche peut ajouter un coût de crédits.

Le widget externe n’affiche pas les cartes de confirmation du canal interne. Les outils d’action admissibles peuvent être exécutés automatiquement, puis un tour de suivi permet à l’agent de communiquer le résultat réel. Vérifiez aussi les enregistrements et les journaux pour les opérations importantes. Le champ de l’agent Profondeur max. de continuation, de valeur par défaut 3, limite les tours automatiques de suivi. Comme toutes ces conversations utilisent le contexte invité du site, sélectionnez les actions avec soin. Consultez Confirmation des actions : différences entre canaux.

Exemples d’utilisation

Chatbot d’assistance

Sur une page d’assistance, l’agent répond aux questions fréquentes, recherche des articles publics et peut créer une demande lorsque le parcours est configuré et autorisé.

Outils possibles selon la configuration : soql_query, create_record pour les demandes uniquement.

Recueil de prospects

Sur une page commerciale, l’agent recueille une demande et crée un prospect pour le suivi, si votre configuration et les informations communiquées au visiteur le prévoient.

Outils possibles selon la configuration : soql_query, create_record pour les prospects uniquement.

Informations en libre-service

Les visiteurs consultent des informations publiques sur des services, des disponibilités ou, dans un exemple immobilier, des biens. Les données privées d’un compte ou d’une réservation nécessitent une identification et des contrôles distincts.

Outils possibles, si le canal est autorisé : soql_query, get_record.

Les attributs data-* de la balise d’intégration permettent notamment de régler :

Le bouton de lancement — Rond ou allongé, avec un texte facultatif.
L’en-tête — Fond de marque coloré ou présentation minimale.
L’accueil — Titre, avatar et texte secondaire facultatif.
Les couleurs — Couleur principale, en-tête, messages utilisateur, fond, texte et bordures.
La typographie — Police et taille du texte.
Les dimensions — Largeur et hauteur du panneau, taille du bouton et arrondi des angles.
La position — En bas à droite ou à gauche.
Le thème — Clair ou sombre.
Le mobile — Seuil d’adaptation et mode plein écran facultatif.
Les textes et langues — Libellés, exemples de saisie, textes accessibles et messages configurables.

Pour les attributs et les exemples détaillés, consultez Personnaliser l’interface du widget.

Bonnes pratiques

Vérifier les droits invités

Contrôlez les droits invités et l’accès réel aux données avant d’ouvrir le widget. Testez aussi les outils personnalisés qui peuvent appliquer leurs propres règles d’accès.

Limitez les outils — Conservez uniquement ceux dont les visiteurs ont besoin. Chaque définition augmente le contexte envoyé au modèle et peut élargir les opérations accessibles.

Rédigez des garde-fous — Utilisez les prompts de type Guardrail, dont le libellé français livré est « Rambarde », pour préciser le comportement attendu. Exemple : « Ne communique jamais les tarifs internes. Propose de contacter l’équipe commerciale. » Ces instructions complètent les droits techniques ; elles ne les remplacent pas.

Examinez les conversations — Repérez les questions fréquentes et les difficultés pour améliorer les informations publiques et la configuration.

Testez plusieurs appareils — Vérifiez les parcours sur ordinateur, tablette et mobile avant l’ouverture au public.

Questions fréquentes

Ajoutez la balise <script>. Le chargeur récupère le code du widget, applique les attributs data-* et initialise la conversation. Vérifiez l’adresse du site, la clé et les règles réseau de la page si le chargement échoue.

Oui. Renseignez toutes les origines concernées dans Origines autorisées, séparées par des virgules, et utilisez le code d’intégration de cet agent sur chaque site. Les conversations partagent les limites et le budget applicables.

Lorsque la liste d’origines est renseignée, l’initialisation depuis un navigateur dont l’origine n’est pas admise est rejetée. Cette restriction de navigateur ne constitue pas une authentification pour un client serveur.

Oui. Préparez une définition, une clé et des origines autorisées pour chaque agent. Chaque site doit charger le code et la clé correspondant au bon agent et au bon point d’accès.

Il est conçu pour être chargé une fois dans la page et peut rester présent lors des changements de route. Son Shadow DOM isole une partie de ses styles. Testez cependant le cycle de vie de votre application, la navigation et les règles de sécurité ; cette isolation ne garantit pas l’absence de tout conflit JavaScript.

Oui. Les options prévues se règlent avec les attributs data-* de la balise d’intégration. Consultez Personnaliser l’interface du widget pour les valeurs prises en charge. La modification de ces attributs nécessite l’accès au code d’intégration de votre site.

Étapes suivantes

Personnalisez l’apparence avec Personnaliser l’interface du widget, puis vérifiez Accès aux données et autorisations pour valider le contexte invité.

← Précédent : Canal interne

Suivant : Personnaliser l’interface du widget →