Piloter le widget MagicAI Chat avec JavaScript

Dans cet article, vous apprendrez comment piloter le widget MagicAI Chat sur votre site web avec JavaScript, quelles options sont disponibles, comment elles interagissent avec la configuration de chat et quelles limites s'appliquent.

Sommaire

• Guide rapide
• Conditions préalables
• Exemple de démarrage
• Options de configuration
• Interaction de vos paramètres avec la configuration de chat
• Limites à connaître
• Exemples pratiques
• Articles associés

Guide rapide

1. Intégrez le widget de chat sur votre site web avec le code de la carte Extrait de code.
2. Dans votre propre script, appelez window.SpaChatWidget?.configure({ ... }) en ne passant que les options que vous souhaitez modifier.
3. Vérifiez la valeur de retour : true signifie que les valeurs ont été acceptées, false signifie que rien n'a été appliqué.
4. Utilisez window.SpaChatWidget?.open() et window.SpaChatWidget?.close() pour ouvrir ou fermer le chat.

Conditions préalables

• Configuration de chat publiée : une configuration à l'état de brouillon ne fournit pas de code d'intégration.
• Widget intégré : le code de la carte Extrait de code est en place sur votre site web. Il charge le script du widget avec l'identifiant de votre configuration de chat. La manière de l'intégrer et les exigences techniques applicables sont décrites dans Configurer MagicAI Chat.
• Votre script s'exécute après le widget : les méthodes ci-dessous ne sont disponibles qu'une fois le script du widget chargé. Si votre code s'exécute plus tôt, l'appel est ignoré et rien ne change.

Exemple de démarrage

Une fois le script du widget chargé, votre page peut utiliser l'objet window.SpaChatWidget. Il propose trois méthodes : configure(), open() et close().

window.SpaChatWidget?.configure({
  teaserMessage: 'Comment pouvons-nous vous aider ?',
  teaserVisible: true,
  suggestions: [
    { buttonText: 'Voir les abonnements', message: 'Quels abonnements sont disponibles ?' }
  ]
});

window.SpaChatWidget?.open();  // Ouvrir le chat
window.SpaChatWidget?.close(); // Fermer le chat

L'opérateur ?. sécurise l'appel : si le widget n'est pas encore chargé, l'appel est ignoré au lieu de provoquer une erreur de script.

configure() renvoie true lorsque les valeurs sont acceptées et false lorsqu'elles sont invalides. Vous pouvez utiliser la valeur de retour pour contrôler votre appel :

const accepted = window.SpaChatWidget?.configure({ teaserVisible: false });

if (accepted === false) {
  console.warn('Le widget de chat a rejeté les paramètres.');
}

Si le widget n'est pas encore chargé, l'appel est ignoré et la valeur de retour est undefined et non true ou false.

Options de configuration

Toutes les options sont facultatives. Ne passez que celles que vous souhaitez modifier.

Lorsqu'un visiteur clique sur une suggestion, le chat démarre avec le texte de message comme premier message du visiteur. Si une entrée n'a pas de message, c'est le buttonText qui est envoyé à la place.

Interaction de vos paramètres avec la configuration de chat

Sans paramètres issus de votre site web, le widget utilise le message d'annonce et les suggestions de la configuration de chat. Vous pouvez les gérer sans code dans la configuration de chat, sous Paramètres / MagicAI / Chatbot, carte Informations de base.

• Le contenu est remplacé : teaserMessage remplace le texte d'annonce configuré, suggestions remplace la liste complète des suggestions configurées.
• La visibilité est commandée séparément : visible, teaserVisible, suggestionsVisible et startscreenSuggestionsVisible fonctionnent indépendamment du contenu. Si vous ne passez aucune option de visibilité, le widget affiche ce que fournit la configuration de chat.
• Visible nécessite du contenu : mettre une option de visibilité sur true ne crée ni texte d'annonce ni suggestions. Si ni votre site web ni la configuration de chat n'en fournissent, rien n'est affiché.
• Les appels sont fusionnés : un appel ultérieur conserve les options des appels précédents et ne modifie que celles qu'il contient. Par exemple, un appel avec uniquement teaserVisible: false laisse en place un teaserMessage défini auparavant.
• Délai : le texte d'annonce et les suggestions apparaissent à côté du bouton de chat environ trois secondes après le chargement du widget.
• Message d'annonce fermé : si un visiteur ferme le message d'annonce, celui-ci et les suggestions restent masqués pour le reste de cette session de navigateur. Un appel avec visible: true, teaserVisible: true ou suggestionsVisible: true annule cet état et les affiche de nouveau. Il prévaut donc aussi sur le choix du visiteur.

Limites à connaître

• Texte d'annonce : max. 500 caractères.
• Suggestions : max. 3, chaque texte de bouton max. 40 caractères et non vide, chaque message max. 500 caractères.
• Appel invalide : configure() renvoie false si une valeur a un type incorrect, si une limite est dépassée ou si l'argument n'est pas un objet simple. Dans ce cas, aucune des valeurs de l'appel n'est appliquée.
• Accepté ne signifie pas chargé : la valeur de retour true confirme seulement que les valeurs sont valides. Elle ne signifie pas que le chat a fini de charger ni qu'une conversation a démarré.
• Masquer ne ferme pas : visible: false masque le bouton de chat mais ne ferme pas un chat déjà ouvert. Pour le fermer, utilisez close() ou isOpen: false.

Exemples pratiques

Les extraits suivants sont des exemples. Adaptez les textes et les ID d'éléments à votre site web et exécutez le code une fois le script du widget chargé.

Exemple : ouvrir le chat depuis votre propre bouton

<button type="button" id="open-chat">Discutez avec nous</button>

<script>
  document.getElementById('open-chat').addEventListener('click', function () {
    window.SpaChatWidget?.open();
  });
</script>

Exemple : afficher un message d'annonce propre à une page

Sur une page consacrée aux cours, par exemple, vous pouvez remplacer le texte d'annonce configuré par un texte adapté :

window.SpaChatWidget?.configure({
  teaserMessage: 'Des questions sur nos cours ? Posez-nous simplement la question.',
  teaserVisible: true
});

Exemple : masquer le bouton de chat sur une page

Sur une page où le bouton de chat ne doit pas apparaître, par exemple une page de paiement :

window.SpaChatWidget?.configure({ visible: false });

Exécutez l'appel sur chaque page où le paramètre doit s'appliquer.

Articles associés

• Configurer MagicAI Chat

Remarque : Cet article a été créé à l'aide de l'intelligence artificielle et traduit automatiquement sans relecture. Nous vous prions de nous excuser pour d'éventuelles erreurs.