SDK du messenger
Intégrez le messenger HelpFalcon à votre site ou à votre app, pilotez-le avec zE() et identifiez les visiteurs avec un JWT.
Traduit pour votre confort. Le code, les noms de champs et la référence de l'API restent en anglais. Version anglaise
Le messenger HelpFalcon est une fenêtre de chat pour votre site et vos apps. Les parcours du bot répondent d’abord, puis passent la conversation à un agent, où elle devient un ticket de messagerie.
L’intégrer
Chaque marque a sa propre clé dans Admin Center, Channels, Messenger. Ajoutez le snippet avant </body> :
<script id="ze-snippet" src="https://app.helpfalcon.com/messenger.js?key=YOUR_KEY"></script>L’id="ze-snippet" et l’API zE() correspondent au Web Widget Zendesk (messagerie) : un site qui quitte Zendesk ne change que l’URL du script et la clé. Ajoutez https://app.helpfalcon.com à script-src, frame-src et connect-src si votre site a une Content Security Policy. Votre centre d’aide HelpFalcon ajoute le snippet tout seul quand le messenger de la marque est activé.
L’API zE()
| Appel | Effet |
|---|---|
zE('messenger', 'open') / 'close' | Ouvre ou ferme la fenêtre de conversation |
zE('messenger', 'show') / 'hide' | Affiche ou masque le lanceur |
zE('messenger', 'loginUser', cb => cb(jwt)) | Identifie le visiteur (voir ci-dessous) |
zE('messenger', 'logoutUser') | Termine la session identifiée |
zE('messenger:on', 'open' | 'close', fn) | Exécute fn à l’ouverture ou à la fermeture de la fenêtre |
zE('messenger:on', 'unreadMessages', fn) | fn(count) à chaque changement du nombre de non-lus |
zE('messenger:set', 'locale', 'fr') | Définit la langue de l’interface |
zE('messenger:set', 'zIndex', 99999) | Définit l’ordre d’empilement |
zE('messenger:set', 'cookies', false) | Masque le messenger et supprime ses données stockées (consentement retiré) |
zE('messenger:set', 'conversationFields', [{ id, value }]) | Définit des champs de ticket appliqués au transfert (id ou clé du champ HelpFalcon) |
zE('messenger:set', 'conversationTags', ['vip']) | Définit des tags ; chaque appel remplace les précédents |
Identifier les visiteurs
Les visiteurs identifiés voient l’historique de leurs conversations sur tous leurs appareils, et les agents savent qui ils sont. Le JWT a le même format que le JWT de messagerie de Zendesk : un service de tokens existant n’a besoin que du nouveau secret.
- En-tête :
{"alg": "HS256", "typ": "JWT", "kid": "<key id>"}, signé avec le secret partagé de Admin Center, Channels, Messenger (créez un nouveau secret, ne réutilisez pas un ancien). RS256 avec une URL JWKS est aussi pris en charge. - Claims :
scope: "user",external_id(obligatoire) et, en option,name,email,email_verifiedetexp. - HelpFalcon relie le visiteur à l’utilisateur ayant cet
external_id, sinon à l’utilisateur ayant cet e-mail vérifié, sinon à un nouvel utilisateur final.
zE('messenger', 'loginUser', function (callback) {
fetch('/chat-token').then(r => r.text()).then(callback);
});Les domaines autorisés, les horaires d’ouverture et les parcours du bot se règlent par marque dans l’Admin Center.
Apps mobiles
Intégrez dès aujourd’hui le messenger dans une WebView dans vos apps iOS et Android. Les SDK natifs sont sur la feuille de route.