Javascript API

O tolvnow possui uma Javascript API Chat, que você pode utilizar para personalizar a chamada do chat em seu site, incluindo diversas opções e automatizações.


Código de instalação

Abaixo colocamos a chamada padrão do tolvnow, ou seja, o código de instalação que geramos automaticamente para você quando a conta é criada:


<script>

// CALLBACKS VÃO AQUI

var _tn = _tn || [];
_tn.push(['_setAccount', 'CHAVE_DA_SUA_CONTA']);
_tn.push(['_setAction', 'track-view']);

// COMANDOS EXTRAS VÃO AQUI

(function() {
document.write(unescape("%3Cspan id='tolvnow'%3E%3C/span%3E"));
var tss = document.createElement('script');
tss.type = 'text/javascript';
tss.async = true;
tss.src = '//tracker.tolvnow.com/js/tn.js';
var s = document.getElementsByTagName('script')[0];
s.parentNode.insertBefore(tss, s);
})();
</script>

NOTA: Na linha número 9, colocamos um comentário “COMANDOS EXTRAS VÃO AQUI”, e é no local deste comentário que você irá incluir as instruções extras que vamos listar a seguir.


Desabilitar o monitoramento:

  • Os clientes desta página não aparecerão no grid dos agentes.
_tn.push(['_monitoring',false]); 


Modo de visualização:

  • Alterar o modo de visualização do chat:
  • Sobrescreve a opção padrão da administração. Você pode optar por ‘widget’ ou ‘popup’. Se você estiver com o Widget como padrão e setar para popup, a opçã0 _setCallMode também deve ser informada.
  • Opções de _setCallMode:
    • 0 – Popup – Chamada no local onde o código de instalação foi colocado
    • 1 -Popup – Fixa no rodapé à direita
    • 2 -Popup – Fixa no rodapé à esquerda
    • 3 -Popup – Fixa à direita
    • 4 -Popup – Fixa à esquerda
    • 5 – Não exibir a chamada ou widget.
    • 6 -Popup – Fixa no topo à direita
    • 7 -Popup – Fixa no topo à esquerda
    • 10 – Widget – Fixa no rodapé à direita
    • 11 – Widget – Fixa no rodapé à esquerda

_tn.push(['_setChatMode', 'popup']);
_tn.push(['_setCallMode', '1']);


Definir tema:

  • Definir o tema (apenas para widget): 
  • Incluindo a opção abaixo, você pode trocar o tema padrão (definido na administração da conta):
    • Os temas são atualizados constantemente, então, consulte a área de administração para ver os temas disponíveis. Na tela de aparência da administração da conta, na opção TEMA DO WIDGET, abrindo as opções, entre parênteses está o nome do tema que deve ser incluído nesta chamada.
_tn.push(['_setTheme', 'black']);


Definir imagem:

  • Definir a imagem / ícone do widget:
  • Incluindo a opção abaixo, você sobrescreve a opção padrão do ícone do chat, sendo que a imagem deve estar sob https. A imagem deve ter 61×61 pixels.
_tn.push(['_setMainIcon', 'https://www.seusite.com/imagens/icone.png']);


Definir o balão (Eye Catcher) personalizado:

  • Para poder definir um balão (ou Eye Catcher) personalizado, é indispensável que você esteja com um balão padrão definido no manager, caso contrário, mesmo definindo esta opção, ele não será exibido.
_tn.push(['_setEyeCatcher', 'https://www.seusite.com/imagens/balao.png']);


Definir a mensagem do caller:

  • A mensagem do caller é aquela mensagem que aparece no widget quando minimizado.
_tn.push(['_setMessageOnline','Estamos online']);_tn.push(['_setMessageOffline','Estamos offline']);


Definir o nome e e-mail do cliente:

  • Você pode definir o nome e e-mail do cliente na chamada (através da sua programação), assim ele não precisará digitar novamente:

_tn.push(['_setName','João Silva']);_tn.push(['_setEmail','joao.silva@suaempresa.com.br']);
  • Evita que o formulário de identificação seja postado automaticamente mesmo que todos os campos obrigatórios tenham sido setados via parâmetros _setName e _setEmail.
_tn.push(['_forceIdentification', 1]);


Definir o valor dos campos:

  • Você pode definir o valor de todos os campos do formulário de identificação (além do nome e email) via javascript api. 
_tn.push(['_addTag','field_530','(51) 2102-0346']);_tn.push(['_addTag','field_539','Twitter']);
  • No exemplo acima, você vê as chaves field_530 e field_539. Os números 530 e 539 são os códigos dos campos no formulário de identificação, ou seja, você deverá acessar o administrador da sua conta no menu Configurações -> Formulários -> Identificação e pegar o código, que está na coluna # (nas flechas vermelhas abaixo).
 


Definir uma identificação de usuário para aparecer no Grid de visitantes:

  • O tolvnow permite que você defina uma identificação de um usuário explicitamente, para que esta seja exibida no grid dos visitantes para os agentes. Esta funcionalidade é muito útil se você tem uma área autenticada no seu site, e você deseja que o tolvnow exiba no Grid, por exemplo, o nome do cliente. Outro uso interessante desta funcionalidade para lojas virtuais é você informar no grid o valor que o cliente tem no momento no seu carrinho de compras. 
_tn.push(['_setUserIdentification','Tiago [R$ 300,00]']);


Esconder o widget depois de alguns dias:

  • Depois de X dias, o widget do chat não será mais exibido. Esta função é útil caso você queira exibir a função do chat apenas para novos clientes.
_tn.push(['_setHideCallerAfter',2]); // em dias


Esconder as opções de identificação via redes sociais:

  • Esta opção permite que você remova as opções de identificação via redes sociais.
_tn.push(['_setSocialDisabled',true]);


Direcionar para departamento automaticamente:

  • Utilize esta opção para direcionar o cliente para um determinado departamento automaticamente. Esta função é muito útil em alguns casos, como por exemplo, se sua empresa é uma imobiliária: se o cliente estiver na área de locações, direcione ele diretamente para o departamento de atendimento de locações, ou, caso ele esteja na área de vendas, direcionar diretamente para o departamento de vendas.
_tn.push(['_setDepto','1']);
  • O código que no nosso exemplo abaixo aparece como 1 deve ser o código do seu departamento. Este código pode ser encontrado na sua área de administração, em Configurações -> Departamentos.


Limitar a seleção de departamentos:

  • Esta opção permite que você defina apenas alguns departamentos para serem exibidos como opção de seleção pelo cliente. Esta opção é especialmente útil se você possui o tolvnow instalado em diferentes sites e deseja oferecer como opção para o cliente apenas um ou outro departamento.
_tn.push(['_allowedDepts',[1,78]]);
  • Perceba que o parâmetro _allowedDepts recebe um array de códigos numéricos, que correspondem ao código do departamento (no caso, os códigos de Comercial e Financeiro, respectivamente), que pode ser encontrado na área administrativa do tolvnow, em configurações -> departamentos, conforme indicado pela seta vermelha.
 
  • Esta opção permite apenas arrays, ou seja, se você quiser exibir apenas 1 opção, deverá informar um array de uma posição, conforme abaixo (que exibirá apenas o departamento Comercial): 
_tn.push(['_allowedDepts',[1]]);


Exibir a opção de fechar o widget:

  • O cliente pode fechar o widget, de forma que este não será mais exibido.
_tn.push(['_setCallerCloseable',true]);


Exibir opção de esconder o widget:

  • O cliente poderá esconder o widget apenas durante a sessão de navegação atual.
_tn.push(['_setShowHideOption', true]);


Habilitar/Desabilitar aviso sonoro do widget:

  • Se definido como false, os efeitos sonoros do widget serão desabilitados. O valor padrão é true. 
_tn.push(['_setAudioEnabled', true]);


Métodos:

Todos os métodos devem ser chamados dentro do laço do método load para evitar que seu código seja executado antes do tolvnow terminar de carregar totalmente.

Como rodar funções depois de carregar o tolvnow:
Para rodar funções ou código após a carga do tolvnow, utilize o método load.
Exemplo de implementação, incluindo o código abaixo depois do script de instalação:

<script>_tno.load(function() {	// tolvnow carregado });
</script>

Como consultar o status dos departamentos:
O método deptos retorna no callback um objeto com o status de todos os departamentos ativos.  Exemplo:

{	"123" : {		"n" : "Comercial",		"s" : "Online"	},	"124" : {		"n" : "Suporte",		"s" : "Offline"	}}
 O objeto retornado possui objetos cujas referências são os códigos dos respectivos departamentos. As propriedades n e s referem-se respectivamente ao Nome do departamento e ao status do departamento (Online, Offline, Ocupado, sempre com a primeira letra maiúscula).
Exemplo de implementação, incluindo o código abaixo depois do script de instalação:

<script>_tno.load(function() {	_tno.deptos(function(json) {
		// tratar retorno json
		if(json[124] && json[124].s == "Online") {
			// exibe uma imagem ou link de online
		} else {
			// exibe como offline
		}
	});});</script>


Callback’s:

  • Callback´s são funções javascript que o tolvnow irá chamar automaticamente quando um determinado evento ocorrer. Você pode utilizá-las para implementar personalizações de comportamento do chat em seu site, ou até mesmo registrar os eventos em alguma ferramenta de Analytics.
  • tolvnowcustom: Deve ser implementada antes do script de chamada do tolvnow, ou , antes da linha 3 do script que mostramos no início deste post.
  • Sempre que você implementar esta função, a API do tolvnow irá chama-la, passando por parâmetro true ou false de acordo com o status da conta:
    • true: existem agentes online
    • false: nenhum agente online

Exemplo de implementação: 


function tolvnowcustom(status) {
if(status == true) $("#chamada-chat").html("Chat Online"); else $("#chamada-chat").html("Chat Offline"); }
  • tolvnowHasOpened: Deve ser implementada antes do script de chamada do tolvnow, ou , antes da linha 3 do script que mostramos no início deste post. A API irá chamar esta função sempre que o widget do tolvnow for aberto, passando por parâmetro true oufalse de acordo com o status da conta:
    • true: existem agentes online
    • false: nenhum agente online
  • Exemplo de implementação: 
function tolvnowHasOpened(status) {
 if(status == true)
    console.log("Widget Abriu - Online");
 else
    console.log("Widget Abriu - Offline");
}
  • tolvnowHasClosed: Deve ser implementada antes do script de chamada do tolvnow, ou , antes da linha 3 do script que mostramos no início deste post. A API irá chamar esta função sempre que o widget do tolvnow for minimizado, passando por parâmetro true oufalse de acordo com o status da conta:
    • true: existem agentes online
    • false: nenhum agente online
  • Exemplo de implementação: 

function tolvnowHasClosed(status) {
 if(status == true)
    console.log("Widget fechou - Online");
 else
    console.log("Widget fechou - Offline");
}
  • tolvnowNotifyClicked: Deve ser implementada antes do script de chamada do tolvnow, ou , antes da linha 3 do script que mostramos no início deste post. A API irá chamar esta função sempre que o usuário interagir com um convite ou uma promoção:
  • status: true: existem agentes online / false: nenhum agente online
  • codigo: código da notificação ( Convites iniciam com C e Promoções começam com P)
  • open: true – se abriu o widget / popup
  • url: se for promoção, informa a url do direcionamento
  • Exemplo de implementação: 
function tolvnowNotifyClicked(status,codigo,open,url) {
 if(status == true)
    console.log("Widget fechou - Online");
 else
    console.log("Widget fechou - Offline");

  // tratamento dos outros campos
}

Como abrir e fechar o chat via javascript:
  • Você pode incluir outras chamadas para o tolvnow no corpo da seu site. Para isso, basta implementar um link para _tno.open().
  • Exemplo de implementação:
<a href="javascript:_tno.open()">Abrir chat</a>
  • Para fechar o chat (apenas widget), utilize uma instrução conforme abaixo:
<a href="javascript:_tno.close()">Fechar chat</a>
  • Importante: para que este script funcione, você deve ter incluído na página o nosso script de chamada.