SDK del messenger
Inserta el messenger de HelpFalcon en tu web o en tu app, contrólalo con zE() e identifica a los visitantes con un JWT.
Traducido para tu comodidad. El código, los nombres de campos y la referencia de la API siguen en inglés. Versión en inglés
El messenger de HelpFalcon es una ventana de chat para tu web y tus apps. Los flujos del bot responden primero y luego pasan la conversación a un agente, donde se convierte en un ticket de mensajería.
Insertarlo
Cada marca tiene su propia clave en Admin Center, Channels, Messenger. Añade el fragmento antes de </body>:
<script id="ze-snippet" src="https://app.helpfalcon.com/messenger.js?key=YOUR_KEY"></script>El id="ze-snippet" y la API zE() coinciden con el Web Widget de Zendesk (mensajería), así que una web que viene de Zendesk solo cambia la URL del script y la clave. Añade https://app.helpfalcon.com a script-src, frame-src y connect-src si tu web tiene una Content Security Policy. Tu centro de ayuda de HelpFalcon añade el fragmento por sí solo cuando el messenger de la marca está activado.
La API zE()
| Llamada | Qué hace |
|---|---|
zE('messenger', 'open') / 'close' | Abre o cierra la ventana de conversación |
zE('messenger', 'show') / 'hide' | Muestra u oculta el lanzador |
zE('messenger', 'loginUser', cb => cb(jwt)) | Identifica al visitante (ver abajo) |
zE('messenger', 'logoutUser') | Termina la sesión identificada |
zE('messenger:on', 'open' | 'close', fn) | Ejecuta fn cuando la ventana se abre o se cierra |
zE('messenger:on', 'unreadMessages', fn) | fn(count) en cada cambio del número de no leídos |
zE('messenger:set', 'locale', 'fr') | Define el idioma de la interfaz |
zE('messenger:set', 'zIndex', 99999) | Define el orden de apilamiento |
zE('messenger:set', 'cookies', false) | Oculta el messenger y borra sus datos guardados (sin consentimiento) |
zE('messenger:set', 'conversationFields', [{ id, value }]) | Define campos del ticket que se aplican en el traspaso (id o clave del campo en HelpFalcon) |
zE('messenger:set', 'conversationTags', ['vip']) | Define etiquetas; cada llamada sustituye a las anteriores |
Identificar a los visitantes
Los visitantes identificados ven su historial de conversaciones en cualquier dispositivo, y los agentes ven quiénes son. El JWT tiene la misma forma que el JWT de mensajería de Zendesk, así que un servicio de tokens existente solo necesita el nuevo secret:
- Cabecera:
{"alg": "HS256", "typ": "JWT", "kid": "<key id>"}, firmada con el secret compartido de Admin Center, Channels, Messenger (crea un secret nuevo, no reutilices uno antiguo). También se admite RS256 con una URL JWKS. - Claims:
scope: "user",external_id(obligatorio) y, opcionalmente,name,email,email_verifiedyexp. - HelpFalcon vincula al visitante con el usuario de ese
external_id; si no, con el usuario de ese correo verificado; si no, con un nuevo usuario final.
zE('messenger', 'loginUser', function (callback) {
fetch('/chat-token').then(r => r.text()).then(callback);
});Los dominios permitidos, el horario de atención y los flujos del bot se configuran por marca en el Admin Center.
Apps móviles
Hoy puedes insertar el messenger en un WebView en apps de iOS y Android. Los SDK nativos están en la hoja de ruta.