Um plugin é uma página web sua, hospedada onde você quiser, que roda dentro de um iframe do Novus CRM. Ela conversa com a plataforma por um protocolo baseado em postMessage. Se registra dizendo o que quer expor, e o Novus CRM 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 Novus CRM. Esse proxy decide o que é permitido e resolve qualquer segredo necessário, sem expor esse valor ao código do plugin.

Repositório de exemplo

Implementação completa de um plugin, com README explicando cada peça do protocolo. É o jeito mais rápido de ver isso funcionando.

​
Onde um plugin pode aparecer

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.

​
Botões no atendimento (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.

​
Itens de menu (navbar)

Um item de navbar aparece no menu principal do Novus CRM. O tipo group só organiza outros itens e não dispara nada ao clicar. O tipo item dispara o callback registrado, e o Novus CRM abre o plugin de acordo com o modo definido no cadastro, modal ou rota.

​
Painel lateral (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.

​
Itens de configurações (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.

​
Eventos de atendimento (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.
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.

​
Comandos disponíveis

Depois de registrado, um plugin chama os comandos abaixo para interagir com o Novus CRM. A maioria devolve uma resposta. load e openWidget são fire-and-forget, sem retorno. 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.

​
Chamando uma API externa (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 Novus CRM, nunca no código do plugin. Isso é combinado com o suporte técnico do Novus CRM antes da publicação.
O plugin manda só o nome do segredo (meuErpApiKey, no exemplo). O Novus CRM 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.
1

Peça a liberação do host

Informe ao suporte técnico do Novus CRM o nome, o endereço e os endpoints e métodos que o seu plugin precisa chamar no sistema externo.
2

Cadastre o segredo

A chave de API do sistema externo é cadastrada como segredo no Novus CRM, com o nome que o seu plugin vai referenciar em secretRefs.
3

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 Novus CRM (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.

​
Catálogo de casos de uso reais

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 Novus CRM.
Um widgetbar consulta um ERP externo sempre que o atendente abre um atendimento, e mostra o status do pedido daquele contato sem sair da tela. A implementação completa está no repositório de exemplo, no topo desta página.
Um botão no header do atendimento chama a API pública do Novus CRM para enviar um texto ao contato da conversa aberta. Esse host (publica) não pede secretRefs. A chave da API pública já é resolvida automaticamente pelo proxy.
O corpo segue o mesmo contrato de Enviar mensagem de texto na API pública. Se o atendimento tiver mais de um canal disponível, use getInfoChannels() para deixar quem atende escolher por qual reenviar, em vez de assumir atendimento.canalId.
Um botão na lista de contatos recebe o contato clicado como payload e cria, ou atualiza, o mesmo cadastro num CRM externo, usando uma chave de API guardada como segredo.
Um item no menu do atendimento cancela um pedido no ERP, mas só depois de o atendente confirmar num diálogo. confirmDialog evita que um clique errado dispare algo que não tem volta.
Um item de navbar abre um painel de BI externo ocupando a tela inteira. Cadastre este plugin com modo: rota. O Novus CRM abre /extensao/{id} como página própria em vez de sobrepor a tela atual.
Um item em Configurações abre uma tela de preferências que só quem administra a conta acessa. getInfoUser identifica quem está logado, útil para aplicar uma preferência por atendente ou por departamento.

​
Ver isso funcionando

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.