Integração do seu próprio sistema CRM e telefonia

3.1 Widget WebRTC para chamadas a partir do navegador.

Se o seu CRM utilizar HTTPS, pode integrar o nosso widget. Atenção: não coloque o widget em acesso público na internet, caso contrário qualquer pessoa poderá fazer chamadas através da sua conta. A cada carregamento da página, do lado do servidor é necessário gerar uma chave para o WebRTC utilizando o método GET /v1/webrtc/get_key da nossa API (a validade da chave é de 72 horas).

No painel de utilizador, na página Definições – Integrações e API, na secção “Integração do widget WebRTC”, é necessário introduzir o domínio do seu CRM e selecionar as opções de aparência e posicionamento do widget. De seguida, utilize o código gerado para integrar o widget no seu CRM. Substitua YOUR_KEY pela chave gerada através da API e YOUR_SIP pelo seu número SIP ou login completo do número interno da central a partir do qual serão efetuadas as chamadas.

Exemplo de código:

<script src="https://my.zadarma.com/webphoneWebRTCWidget/v8/js/loader-phone-lib.js?v=17"></script>
<script src="https://my.zadarma.com/webphoneWebRTCWidget/v8/js/loader-phone-fn.js?v=17"></script> 
<script>
  if (window.addEventListener) { 
    window.addEventListener('load', function() { 
      zadarmaWidgetFn('YOUR_KEY', 'YOUR_SIP', 'square' /*square|rounded*/, 'en' /*ru, en, es, fr, de, pl, ua*/, true, "{right:'10px',bottom:'5px'}"); 
    }, false); 
  } else if (window.attachEvent) { 
    window.attachEvent('onload', function(){ 
      zadarmaWidgetFn('YOUR_KEY', 'YOUR_SIP', 'square' /*square|rounded*/, 'en' /*ru, en, es, fr, de, pl, ua*/, true, "{right:'10px',bottom:'5px'}"); 
    }); 
  } 
</script>

Widget em estado oculto:

Widget expandido:

3.2 Chamadas através do retorno de chamada (Callback)

No interface do CRM, junto a cada número de telefone, deve ser adicionada um ícone/botão para iniciar uma chamada para esse número. Recomenda-se também implementar um telefone web com teclado numérico para realizar chamadas para números novos, ainda não guardados no CRM. As chamadas efetuadas seguem o princípio do Callback. O número interno da central telefónica virtual deve ter configurado um telefone IP ou softphone para receber e efetuar chamadas. O utilizador, no CRM, clica no ícone junto ao número de telefone ou no botão de chamada no telefone web, e o CRM envia o pedido de Callback.

Método GET /v1/request/callback/

Parâmetros:

• from – número interno de três dígitos da central telefónica atribuído ao utilizador.
• to – número de telefone para o qual o utilizador pretende ligar.

O utilizador recebe uma chamada no seu softphone, atende e aguarda o estabelecimento da ligação com o número pretendido.

Exemplo de implementação:

Quando um número interno da central telefónica recebe ou faz uma chamada, deve surgir no CRM uma notificação correspondente. A notificação deve ser exibida apenas ao utilizador cujo número interno esteja envolvido na chamada. A notificação pode conter as seguintes informações:

• Número de telefone
• Nome do contacto/empresa/lead, caso o número já esteja guardado no CRM (o nome é um link que permite aceder diretamente à entidade correspondente: contacto, empresa ou lead)
• Se a chamada for de um novo cliente — botão para criar contacto/empresa/lead
• Nome do colaborador responsável, se a chamada for de um cliente existente
• Número virtual para o qual a chamada foi recebida (número ligado na Zadarma)

O evento que desencadeia o aparecimento da notificação pop-up é NOTIFY_INTERNAL (início de uma chamada recebida para um número interno da central telefónica) ou NOTIFY_OUT_START (início de uma chamada efetuada a partir da central telefónica).

Quando o destinatário atende e a conversa começa, o CRM recebe a notificação NOTIFY_ANSWER (resposta a uma chamada recebida ou efetuada). Este evento serve também como gatilho para atualizar a notificação pop-up — por exemplo, pode iniciar um contador que mostre a duração da chamada em tempo real, ou alterar o título da notificação de “Chamada de 442037691880” para “Conversa com 442037691880”.

Quando a chamada é terminada, é enviado o evento NOTIFY_END (fim de uma chamada recebida para o número interno da central telefónica) ou NOTIFY_OUT_END (fim de uma chamada efetuada a partir da central telefónica).

Após receber o NOTIFY_END ou NOTIFY_OUT_END, a notificação pop-up deve ser encerrada.

Exemplo de implementação:

Para carregar as gravações de chamadas da Zadarma para o CRM, é necessário que nas definições do número interno da central telefónica esteja ativada a opção de gravação de chamadas na nuvem. Após o término da chamada, quando a gravação estiver pronta para download, o CRM receberá o evento NOTIFY_RECORD (a gravação da chamada está pronta para ser descarregada).

No parâmetro call_id_with_rec encontra-se o identificador necessário para obter a gravação da chamada, utilizando o método GET /v1/pbx/record/request/. A resposta contém o link para o ficheiro de áudio da chamada. Se o seu CRM possuir um armazenamento próprio na nuvem, a gravação pode ser automaticamente carregada para esse espaço. Caso contrário, é possível implementar um botão “play” para reproduzir o áudio diretamente a partir do link recebido. O botão de reprodução pode ser colocado junto à informação da chamada, por exemplo na linha temporal de um lead/contato/negócio ou na secção geral de estatísticas de chamadas.

Para gerar estatísticas gerais de chamadas no CRM, deve ser utilizada a informação recebida dos eventos NOTIFY_END e NOTIFY_OUT_END.

Criação automática de entidades ou eventos no CRM em chamadas recebidas de números desconhecidos ou chamadas efetuadas para números não registados. Quando uma chamada é recebida ou iniciada, o número é verificado na base de dados do CRM. Se o número não for encontrado, pode ser criado automaticamente um novo contacto/lead/negócio/tarefa e atribuído ao utilizador que fez a chamada. Recomenda-se disponibilizar opções separadas de criação automática para chamadas recebidas e efetuadas.

Para chamadas efetuadas, a criação pode ocorrer: – quando a chamada é iniciada (NOTIFY_OUT_START), – quando a chamada é atendida (NOTIFY_ANSWER), – ou após o término da chamada (NOTIFY_OUT_END). O número de destino da chamada é transmitido no parâmetro destination.

Para chamadas recebidas, a criação pode ocorrer quando a chamada é recebida por um número interno de um utilizador do CRM (NOTIFY_INTERNAL), onde o número do chamador é transmitido no parâmetro caller_id. Assim, o utilizador pode abrir a ficha do cliente recém-criada durante a chamada, adicionar notas, etc. Após o término da chamada recebida, é enviado o evento NOTIFY_END, que contém o parâmetro internal (número interno da central telefónica que recebeu a chamada). Ao comparar esse número com a lista de utilizadores do CRM, o sistema pode identificar automaticamente o responsável. Também é possível criar a entidade apenas após o término da chamada recebida, com base no evento NOTIFY_END.

Alguns CRMs não utilizam criação automática de entidades, permitindo que o gestor que atendeu a chamada decida se deve criar manualmente um lead/contato/tarefa.

Quando uma chamada é recebida de um cliente existente (cujo número já está guardado no CRM), a chamada é automaticamente encaminhada para o utilizador responsável por esse cliente. Assim, o chamador não precisa ouvir a mensagem de boas-vindas nem pedir para ser encaminhado ao seu gestor habitual — a chamada é direcionada automaticamente para o telefone do gestor responsável. Isto é implementado através do evento NOTIFY_START.

No parâmetro caller_id é transmitido o número do chamador. Se esse número estiver registado no CRM como o número de contacto de um cliente e esse cliente tiver um responsável designado, a chamada pode ser direcionada para o número interno desse colaborador. Também é possível definir a duração máxima de tentativa de contacto com o responsável (por exemplo, 15 segundos). Se o responsável não atender dentro desse período, a chamada é redirecionada para o menu de voz, continuando o fluxo configurado na central telefónica. Isto é implementado através da resposta ao pedido POST NOTIFY_START.

{
    "redirect": "101",
    "return_timeout": "15"
}

onde:

• redirect – número interno da central telefónica (número de três dígitos).
• return_timeout – valor em segundos (≥ 3) que define a duração da chamada do número interno antes de esta regressar ao menu; o valor recomendado é 15 ou 20 segundos.

Esta opção permite transmitir o nome do cliente do CRM para o telefone IP ou softphone do utilizador que recebe a chamada. É implementada através do evento NOTIFY_START e da respetiva resposta. No evento, o parâmetro caller_id contém o número do chamador; se o número já estiver registado no CRM e associado a um cliente/contato/lead, na resposta ao NOTIFY_START pode ser enviado o nome do cliente (em caracteres latinos):

{
    "caller_name": "IBM"
}

onde:

• caller_name – nome do cliente/empresa guardado no CRM.

Quando ocorre uma chamada recebida de um cliente, ao receber o evento NOTIFY_END, o número do chamador pode ser obtido a partir do parâmetro caller_id. Assim, é possível identificar no CRM o cliente/contato/lead associado a esse número e o gestor responsável. Se a chamada não tiver sido atendida (ou seja, o estado disposition não for “answered”), pode ser criada automaticamente uma tarefa, lembrete ou notificação para o gestor responsável informando que houve uma chamada não atendida do cliente.

Pode criar uma lista de números cujas chamadas serão automaticamente rejeitadas. Os números podem ser adicionados à lista na página de definições de telefonia ou através de um botão específico junto a cada utilizador. Esta funcionalidade baseia-se igualmente no evento NOTIFY_START e na resposta a este. Se o número do chamador (parâmetro caller_id) estiver na lista negra do CRM, na resposta ao NOTIFY_START deve ser enviado:

{
    "redirect": "blacklist" 
}

Após concluir com sucesso os passos anteriores e testar a integração a nível de utilizador individual, pode enviar um pedido para adicionar a integração ao marketplace da Zadarma (caso o seu sistema tenha mais de 30 000 utilizadores mensais). Isto permitirá que qualquer utilizador Zadarma com conta ativa e central configurada utilize a integração. Além disso, proporcionará ao utilizador final uma forma rápida e conveniente de guardar todas as definições necessárias. Os pedidos devem ser enviados para o endereço de e-mail integration@zadarma.com com o assunto: “Pedido de adição de integração com o sistema [Nome do seu CRM] ao marketplace Zadarma”. O pedido deve incluir as seguintes informações adicionais:

URL no seu CRM para ativar a integração

Para este endereço será enviada informação sobre o utilizador Zadarma que tenta integrar a telefonia com o seu CRM. No formato de transmissão escolhido (GET, POST), será enviado um identificador único do utilizador no formato de string md5 hash. Em resposta, deve ser devolvida uma chave gerada aleatoriamente, que será associada a esse utilizador. Posteriormente, em cada pedido ao seu sistema CRM, o identificador do utilizador e o hash enviado por si serão utilizados como dados de autenticação através do cabeçalho:

Authorization: Bearer [userId . hash]

O identificador do utilizador também será transmitido em cada notificação de chamada no campo zdUserId. São necessários exemplos dos possíveis formatos de resposta.

URL no seu CRM para desativar a integração

Para este endereço será enviado um pedido quando o utilizador tentar desativar a integração. É utilizada a autenticação padrão Bearer.

URL no seu CRM para receber notificações de chamadas

São enviadas notificações de chamadas para todos os utilizadores integrados. O utilizador pode ser identificado através do campo zdUserId. O formato das notificações pode ser consultado na página de descrição da API. É utilizada a autenticação padrão Bearer.

URL no seu CRM para obter o nome do cliente a partir do número de telefone

Necessário para utilizar a função “Exibição do nome do cliente no softphone”. São necessários exemplos de pedido e de respostas possíveis. É utilizada a autenticação padrão Bearer.

(Opcional) URL no seu CRM para obter a lista de gestores

Necessário para utilizar a função “Associação de gestores aos números internos da central telefónica”. Isto permitirá que o utilizador associe diretamente, a partir do painel da Zadarma, os gestores do CRM aos números internos da central Zadarma. Caso seja necessária a sincronização desses dados com o seu CRM, deve também ser indicado o URL para o qual esses dados podem ser enviados em formato JSON. São necessários exemplos de pedido e de respostas possíveis. É utilizada a autenticação padrão Bearer.

Nome do autor da integração (pode indicar o nome da sua empresa e o link para a página principal)

Logótipo da integração no formato PNG, com fundo transparente e dimensões de 500 x 150 px.