Plugins
Onde um plugin pode aparecer, quais comandos ele pode chamar e casos de uso reais para cada superfície do protocolo.
Onde um plugin pode aparecer, quais comandos ele pode chamar e casos de uso reais para cada superfície do protocolo.
Um plugin é uma página web sua, hospedada onde você quiser, que roda dentro
de um iframe do SunchatPlus. Ela conversa com a plataforma por um protocolo
baseado em postMessage. Se registra dizendo o que quer expor, e o SunchatPlus
chama de volta quando o usuário interage com aquilo.
O plugin não recebe token de autenticação e não acessa o banco de dados da conta diretamente. Toda chamada de API passa por um proxy que roda no servidor do SunchatPlus. Esse proxy decide o que é permitido e resolve qualquer segredo necessário, sem expor esse valor ao código do plugin.
Implementação completa de um plugin, com README explicando cada peça do protocolo. É o jeito mais rápido de ver isso funcionando.
Um plugin se registra chamando initialize com um objeto descrevendo o que
ele expõe. Cada chave do registro é opcional, e um plugin pode combinar
quantas quiser.
buttons)Um botão aparece em um dos três grupos abaixo, dependendo de onde ele
precisa ficar visível. O grupo escolhido também define o que chega no
callback quando o atendente clica.
| Grupo | Onde aparece | Payload do clique |
|---|---|---|
lista-contatos | Menu de ações de cada contato na lista de contatos | O contato clicado |
atendimento-chat | Header do atendimento de chat aberto | O atendimento atual |
atendimento-chat-menu | Menu "⋮" do atendimento (aceita também o nome legado atendimento-page) | O atendimento atual |
navbar)Um item de navbar aparece no menu principal do SunchatPlus. O tipo group só
organiza outros itens e não dispara nada ao clicar. O tipo item dispara o
callback registrado, e o SunchatPlus abre o plugin de acordo com o modo
definido no cadastro, modal ou rota.
widgetbar)Um item de widgetbar vira um ícone na barra lateral direita. Sem
callback, clicar nele abre o próprio painel do plugin, o mesmo efeito do
comando openWidget. Com callback, o clique roda lógica dentro do iframe
em vez de abrir o painel.
options)Um item de options aparece dentro de Configurações, na área de Plugins. Um
item do tipo item abre o plugin dentro da tela de configurações ao ser
clicado, o lugar certo para uma tela de preferências que só um
administrador precisa acessar.
events)Os sete eventos abaixo cobrem o ciclo de vida de um atendimento. Um plugin escuta quantos quiser, e não existe obrigação de implementar todos.
| Evento | Quando dispara |
|---|---|
aoAbrirAtendimento | O atendente abre um atendimento |
aoFocarAtendimento | O atendente volta o foco para um atendimento já aberto |
aoFecharAtendimento | O atendente fecha o atendimento |
aoAbrirHistoricoAtendimento | O atendente abre, em modo leitura, um atendimento já encerrado |
aoFecharHistoricoAtendimento | O atendente fecha esse histórico |
aoAcessarPaginaChat | O atendente entra na tela geral do Chat, sem um atendimento específico aberto |
aoAcessarPaginaHistorico | O atendente entra na tela geral do histórico |
O protocolo também aceita um nome em inglês para cada um desses sete eventos, mantido por compatibilidade com plugins escritos para outras plataformas de atendimento. Registrar um nome ou o outro tem o mesmo efeito.
Depois de registrado, um plugin chama os comandos abaixo para interagir com
o SunchatPlus. A maioria devolve uma resposta. load e openWidget são
fire-and-forget, sem retorno.
| Comando | O que faz |
|---|---|
initialize | Registra o plugin e o que ele expõe |
apiRequest | Chama uma API interna ou externa pelo proxy do servidor |
getInfoUser | Consulta dados de quem está logado |
getInfoChannels | Consulta os canais de atendimento conectados na conta |
openModal | Abre um modal customizado, com um canal aberto para o host devolver dados |
closeModal | Pede ao host para fechar o modal aberto |
openConfirmDialog | Abre um diálogo de confirmação (sim/não) antes de uma ação |
openAlert | Mostra um aviso ou toast renderizado pelo host |
openPage | Pede ao host para navegar (rota interna) ou abrir uma URL |
openWidget | Abre o painel do plugin na barra lateral direita |
load | Avisa que o plugin terminou de carregar |
O campo modo, definido no cadastro do plugin, decide como uma página do
plugin abre quando ativada por um item de navbar ou de options. modal
sobrepõe a tela atual, e rota ocupa a tela inteira em /extensao/{id}. O
widgetbar não usa esse campo. O painel lateral sempre abre do mesmo jeito,
independente do modo cadastrado.
apiRequest)Um plugin que precisa chamar um sistema externo não pode apontar para qualquer URL. O host de destino precisa estar liberado antecipadamente, e qualquer chave de API fica guardada como segredo no SunchatPlus, nunca no código do plugin. Isso é combinado com o suporte técnico do SunchatPlus antes da publicação.
const pedido = await WlExtension.apiRequest({
host: "meuerp",
method: "GET",
endpoint: "pedidos/por-telefone",
query: { telefone },
secretRefs: {
"X-Api-Key": { secret: "meuErpApiKey", in: "header" },
},
});
O plugin manda só o nome do segredo (meuErpApiKey, no exemplo). O
SunchatPlus resolve esse nome para o valor real do lado do servidor e injeta
no cabeçalho, na query ou no corpo da requisição, conforme indicado em
in. O código do plugin, rodando no navegador de quem atende, nunca recebe
esse valor.
Peça a liberação do host
Informe ao suporte técnico do SunchatPlus o nome, o endereço e os endpoints e métodos que o seu plugin precisa chamar no sistema externo.
Cadastre o segredo
A chave de API do sistema externo é cadastrada como segredo no SunchatPlus, com o nome que o seu plugin vai referenciar em secretRefs.
Publique e cadastre o plugin
Hospede o plugin no seu próprio domínio com HTTPS e cadastre-o na plataforma, como descrito em Plugins.
Sem os dois primeiros passos, uma chamada apiRequest para um host ainda
não liberado falha com erro de host ou endpoint não permitido. É o
comportamento esperado, não um bug do seu plugin.
Um host pode dispensar secretRefs. A API pública do SunchatPlus (host
publica) já resolve a própria autenticação a partir da chave da sua conta,
sem o plugin precisar referenciar segredo nenhum. O catálogo abaixo mostra
os dois casos lado a lado.
Os seis exemplos abaixo são cenários reais, não hipotéticos. Cada um combina uma superfície do protocolo com os comandos que fazem sentido ali, e dois deles usam endpoints que já existem na API do SunchatPlus.
Para ver o protocolo funcionando de ponta a ponta, incluindo o pedido de liberação de host externo e o uso de segredo, use o repositório de exemplo. Ele implementa um plugin completo sem depender de nada além do protocolo público.