SDK do messenger | Desenvolvedores

Traduzido para sua conveniência. Código, nomes de campos e a referência da API continuam em inglês. Versão em inglês

O messenger do HelpFalcon é uma janela de chat para o seu site e apps. Os fluxos do bot respondem primeiro e depois passam a conversa para um agente, onde ela vira um ticket de mensagens.

Incorporar

Cada marca tem a sua própria chave em Admin Center, Channels, Messenger. Adicione o snippet antes de </body>:

<script id="ze-snippet" src="https://app.helpfalcon.com/messenger.js?key=YOUR_KEY"></script>

O id="ze-snippet" e a API zE() correspondem ao Web Widget do Zendesk (mensagens), então um site que vem do Zendesk só troca a URL do script e a chave. Adicione https://app.helpfalcon.com a script-src, frame-src e connect-src se o seu site tiver uma Content Security Policy. A sua central de ajuda do HelpFalcon adiciona o snippet sozinha quando o messenger da marca está ligado.

A API zE()

Chamada	O que faz
`zE('messenger', 'open')` / `'close'`	Abre ou fecha a janela de conversa
`zE('messenger', 'show')` / `'hide'`	Mostra ou esconde o lançador
`zE('messenger', 'loginUser', cb => cb(jwt))`	Identifica o visitante (veja abaixo)
`zE('messenger', 'logoutUser')`	Encerra a sessão identificada
`zE('messenger:on', 'open' \| 'close', fn)`	Executa `fn` quando a janela abre ou fecha
`zE('messenger:on', 'unreadMessages', fn)`	`fn(count)` a cada mudança no número de não lidas
`zE('messenger:set', 'locale', 'fr')`	Define o idioma da interface
`zE('messenger:set', 'zIndex', 99999)`	Define a ordem de empilhamento
`zE('messenger:set', 'cookies', false)`	Esconde o messenger e apaga os dados guardados (consentimento desligado)
`zE('messenger:set', 'conversationFields', [{ id, value }])`	Define campos do ticket aplicados na passagem (id ou chave do campo no HelpFalcon)
`zE('messenger:set', 'conversationTags', ['vip'])`	Define tags; cada chamada substitui as anteriores

Identificar visitantes

Visitantes identificados veem o histórico de conversas em qualquer dispositivo, e os agentes sabem quem eles são. O JWT tem o mesmo formato do JWT de mensagens do Zendesk, então um serviço de tokens existente só precisa do novo secret:

Cabeçalho: {"alg": "HS256", "typ": "JWT", "kid": "<key id>"}, assinado com o secret compartilhado de Admin Center, Channels, Messenger (crie um secret novo, não reutilize um antigo). RS256 com uma URL JWKS também é suportado.
Claims: scope: "user", external_id (obrigatório) e, opcionalmente, name, email, email_verified e exp.
O HelpFalcon liga o visitante ao usuário com esse external_id; senão, ao usuário com esse e-mail verificado; senão, a um novo usuário final.

zE('messenger', 'loginUser', function (callback) {
  fetch('/chat-token').then(r => r.text()).then(callback);
});

Domínios permitidos, horário de atendimento e os fluxos do bot são definidos por marca no Admin Center.

Apps móveis

Hoje você pode incorporar o messenger num WebView em apps iOS e Android. SDKs nativos estão no roadmap.