Integração com sistemas de CRM via API para desenvolvedores

O objetivo de integrar o JivoChat a um sistema de CRM é para salvar os dados do JivoChat na seção de leads/clientes do seu CRM, e também para mostrar informações atualizadas (por exemplo: informações de contato do visitante, detalhes do lead, balanço da conta, entre outros) no aplicativo do operador da JivoChat, o qual é utilizado para usuários do JivoChat receberem chats de seus consumidores.

Para ativar uma integração, basta inserir um Endpoint URL do seu CRM ou servidor nas configurações do canal em que deseja ativar a integração. Após inserido, enviaremos de forma automática diversos Webhooks com todas as informações sobre conversas do canal conectado para a URL especificada.

Para inserir uma URL para o recebimento de Webhooks, acesse o aplicativo Web do JivoChat ou um de nossos apps para Desktop e vá até Configurações -> Canais -> Configurações (abaixo do nome do canal que deseja ativar a integração).

Depois, acesse o menu "Configurações de integração para desenvolvedores", ative os Webhooks e insira o Endpoint URL no campo "URL para Webhooks".

Pronto, agora o JivoChat já irá enviar webhooks automaticamente para a URL especificada.

Nos seguintes casos, o sistema da JivoChat envia uma requisição HTTP POST para a URL especificada:

• chat_accepted - Um operador aceitou uma requisição de chat no aplicativo
• client_updated - O formulário de contato de um visitante foi atualizado (o visitante inseriu seus dados no formulário ou o operador adicionou/editou os dados de um cliente na janela do chat dentro do app)
• chat_assigned - Um chat foi conectado ao CRM
• chat_finished - Chat finalizado (um chat foi encerrado por um operador clicando em "Encerrar conversa" no topo do chat, automaticamente por contagem regressiva após um cliente ter saído do site ou após o operador fechar o aplicativo)
• chat_assigned - Um operador manualmente conectou um visitante ao cadastro CRM de um cliente clicando em ‘Vincular ao CRM’ e colando um link
• offline_message - Uma mensagem offline foi enviada pelo formulário de contato enquanto os operadores estavam offline

Quais informações são enviadas#

Você pode utilizar nossa documentação acessando este link.

Dados principais enviados pelo JivoChat:

• ID do chat – Você pode utilizar este número de ID para gerar um link direto para a conversa no app do JivoChat. Por exemplo: https://app.jivosite.com/chat/archive/{chat_id}_chat-{site_id}-{chat_id} (https://app.jivosite.com/chat/archive/1652173_chat-1-1652173)
• Nome, e-mail e número de telefone
• ID do cliente – Você pode utilizar este número de ID para gerar um link para a página com todos os chats deste visitante. Por exemplo: https://app.jivosite.com/chat/archive/2164_client-497422-2083 (https://app.jivosite.com/chat/archive/{chat_id}_chat-{site_id}-{client_id}) (Obs.: nós identificamos visitantes por cookies, não IP)
• Comentário – Você pode adicionar comentários sobre os visitantes dentro do aplicativo

• ID, Login e Nome do Operador que conversou com o cliente – Você pode utilizar esta informação para criar um lead ou conta de um cliente no seu CRM. Se o chat foi transferido entre operadores, você receberá um arranjo (array) com os dados de todos os operadores.
• Todas as mensagens dos chats com marcações de tempo

O JivoChat pode receber respostas do seu sistema de CRM com os seguintes dados:

• Informações completas de contato dos seus clientes/leads, se o e-mail ou telefone cadastrado já existe no sistema da JivoChat. Por exemplo, se um visitante deixou seu e-mail durante um chat, seu CRM pode enviar ao JivoChat o nome do visitante, telefone e comentário, completando automaticamente esses campos de contato no JivoChat.
• Qualquer informação customizada, como por exemplo: balanço do visitante, licença atual e quaisquer outras informações, além do link para a conta do cliente no seu CRM:

• Enviamos diversos dados detalhados como a fonte da visita, IP, cidade, página atual entre outros. Você pode enviar para o seu CRM qualquer informação da página de detalhes dos visitantes no JivoChat. Por exemplo, se o visitante está logado em um site ou envia algum ID como o ID de usuário do Google Analytics, é possível enviar esta informação para o seu CRM utilizando o método jivo_api.setUserToken – utilize-a como mostrado abaixo:

function jivo_onLoadCallback(){
	jivo_api.setUserToken("um link | id | qualquer informação");
}

O JivoChat não processa o user_token e isso não será mostrado em nenhum lugar. O user_token irá somente transferir todos os dados gerados para o seu CRM.

Como receber informações do JivoChat no seu servidor#

A requisição dos webhooks do JivoChat são requisições HTTP com método POST para a URL especificada. O corpo da requisição é um objeto JSON com todos os dados. Você pode encontrar todos os detalhes na nossa documentação da API. Veja abaixo um exemplo em PHP de como receber uma requisição e salvá-la em um arquivo log:

<?php
$fp = fopen('/request.log', 'a');
fwrite($fp, file_get_contents('php://input'));
fclose($fp); ?>

Isso, é claro, não significa que você deva utilizar um arquivo de texto para manter todos os dados. Este é somente um example que pode ser utilizar para visualizar como são nossas requisições e como elas funcionam. Na sequência, você deverá analisar esses dados, gravá-los em sua base de dados, pesquisar por um registro de lead e etc. Depois disso, seu CRM deverá enviar uma resposta com os dados do cliente no objeto, como descrito na documentação da API. Você pode utilizar algo como a função "echo" em PHP, sem nenhum cabeçalho HTTP adicional.

Visualize abaixo um exemplo de resposta:

{"result":"ok","custom_data":[{"title":"Answer","content":"42"},{"title":"Last chat","content":"27 Sep 2016 19:37:12"}],"contact_info":{"name":"John Doe","phone":"+79500123567","email":"johny1337@jivoteam.com","description":"Visitor comment"},"enable_assign":true,"crm_link":"http:\/\/mycrm.ru\/user\/1"}

Desde um navegador:

O que a integração deverá realizar?#

Isso é geralmente o que os usuários esperam de uma integração com seus sistemas de CRM:

Quando seu CRM estiver conectado ao sistema da JivoChat (quando um evento chat_accepted ou chat_updated ocorrer), ele deverá procurar pelo cliente no seu CRM e se um cliente com as informações de contato especificadas já existir, seu CRM deverá preencher o restante dos dados de contato do cliente no JivoChat, além de inserir no chat um link direto para o perfil do cliente no seu CRM. Se o cliente ainda não existir no seu CRM, um novo cadastro de cliente/lead deverá ser automaticamente criada utilizando as informações enviadas pelo JivoChat para o seu CRM.

Criação de registro de lead

• Alguns sistemas de CRM possuem não somente nomes de Leads, mas também títulos de Leads. Um exemplo disso seria: "JivoChat #18 - Tomas Silva".
• Um detalhe muito importante é atribuir um gerente de conta. É melhor atribuir um gerente com o login da JivoChat igual ao login no CRM ou algum usuário padrão.
• Especifique uma fonte de Lead: JivoChat. Isso é útil para encontrar um lead vindo de um chat.
• Mostre a fonte da visita e a página na qual o chat foi iniciado. O JivoChat não envia isso via webhooks, mas se for possível, utilize o setUserToken da nossa API para criar esta integração. O CRM e operadores do chat saberão de qual canal o lead foi enviado. Isso é perfeito para quando parâmetros UTM são conhecidos e mostrados.
• Adicione uma descrição ou comentário sobre o visitante, pois é útil para gerentes e outros funcionários.
• Alguns sistemas de CRM exigem a inserção de dados em alguns campos para criar um novo Lead. Verifique o que está ocorrendo caso esses campos estejam vazios.
• Quando mensagens offline são enviadas, o sistema CRM deverá criar uma tarefa ou e-mail com o gerente responsável pelo processamento do pedido, ou simplesmente criar um Lead.
• Grave conversas em um registro de Lead: em notas ou feed.

Favor analisar com cuidado a prioridade de dados. Quais dados serão gravados ou excluídos? Se um visitante apresentou-se em um chat e inseriu um endereço de e-mail "A" e um telefone "B", porém no CRM há um Lead com o e-mail "A" e telefone "C", qual número deverá ser gravado? O número antigo ou o mais recente? O ideal é que o CRM possua campos extras para e-mails e telefones adicionais.