A Kommo possui a capacidade de exibir uma janela de notificação no canto inferior esquerdo da interface. Um exemplo de uso é a notificação de uma chamada recebida pelo serviço de telefonia integrado.

Existem duas maneiras principais de criar notificações de chamadas: via API ou por widget em JavaScript.

Criar notificação de chamada via API

Você pode criar uma notificação de chamada via API. Esse método localiza automaticamente uma entidade (contato, empresa ou lead) pelo número informado e exibe uma notificação para o usuário desejado, mostrando o nome da entidade de acordo com a seguinte prioridade:

• Se o contato/empresa tiver apenas um lead ativo, o lead será exibido.
• Se o contato/empresa tiver mais de um lead ativo ou nenhum lead relacionado, o nome do contato/empresa será exibido.

Se o número ainda não existir no sistema, a notificação oferecerá a opção de criar um novo contato com esse número.

👍

Esse método evita requisições desnecessárias para buscar entidades por número de telefone via API, o que otimiza bastante o funcionamento da integração VoIP.

Criar notificação de chamada via widget JS

Outra forma de criar notificações é através do código JavaScript do widget. Ao receber uma chamada, o PBX consulta a Kommo utilizando o método Lista de Contatos, enviando o número de telefone no parâmetro ?query={phone_number} para obter informações sobre o contato que está ligando. Esse contato deve existir na Kommo, e o usuário que recebe a chamada precisa ter permissão de visualização.

Um timeout mínimo deve ser definido para processar a requisição, a fim de evitar problemas com as chamadas no caso de instabilidade de conexão entre o PBX e a Kommo.

Para entregar as informações da chamada ao script do lado do cliente, costuma-se usar websocket, estabelecendo uma conexão contínua e assinando eventos. Outra alternativa é o polling periódico via JS — carregando em intervalos regulares um arquivo JS hospedado em um servidor externo que retorna o status atual da chamada (por exemplo: chamada recebida, ocioso, etc. por ramal).

A escolha depende do suporte do PBX a websockets. Além disso, é essencial mapear os ramais internos aos usuários da Kommo que têm permissão para visualizar a interface.

Exemplo de cartão de chamada recebida

Para implementar um cartão de chamada recebida, você pode usar o objeto APP.notifications.add_call(call_params). No exemplo abaixo, criamos uma função para trabalhar com ele. Para obter informações do contato usando apenas o número da chamada recebida, use o método Lista de Contatos com parâmetro ?query={phone_number}:

const addCallNotification = async (notificationOptions) => {
  const {
    text,
    from,
    to,
    duration,
    link,
    date = Math.ceil(Date.now() / 1000),
    element: entity,
    clickLink,
  } = notificationOptions;

  /**
   * Se necessário, personalize ou altere os parâmetros da notificação.
   */
  const possibleCallers = await searchContactByPhone(from);

  const notificationText = possibleCallers.reduce((acc, contact, index) => {
    const { name } = contact;

    return `${index ? acc : `${acc}, `}${name}`;
  }, "Este número está vinculado a: ");

  const notification = {
    text: notificationText,
    from,
    to,
    duration,
    link,
    date,
    element: entity,
    click_link: clickLink,
  };

  /**
   * Adiciona uma notificação coma as opções definidas
   */
  APP.notifications.add_call(notification);
};

Para buscar informações de um contato pelo número da chamada recebida, envie uma requisição GET para obter uma Lista de Contatos com o parâmetro ?query={phone_number}:

const FALLBACK_FN = () => undefined;
const PHONE_CUSTOM_FIELD_CODE = "PHONE";

const searchContactByPhone = async (phone, callbacks = {}) => {
  const { onSuccess = FALLBACK_FN, onError = FALLBACK_FN } = callbacks;

  if (!phone) {
    return;
  }

  try {
    const contactsData = await $.ajax(`/api/v4/contacts?query=${phone}`, {
      method: "GET",
    });

    onSuccess(contactsData);

    return contactsData._embedded.contacts;
  } catch (error) {
    onError(error);
  }
};

Localização do widget

É importante lembrar que você deve declarar o scope de conexão do widget no arquivo manifest.json. Para habilitar o cartão de chamadas recebidas, recomenda-se definir o scope como everywhere. Assim, seu widget será carregado em qualquer área da Kommo, garantindo que as notificações de chamadas apareçam independentemente do que o usuário estiver fazendo. Você pode ler mais sobre o escopo de conexão aqui:

"locations": [ "everywhere"]

Criar notificação de erro

Para notificar o usuário sobre problemas que ocorrem em processos de segundo plano, deve-se usar um objeto JavaScript específico. Ao ser chamado, esse objeto exibirá uma notificação de erro — por exemplo, informando que não foi possível conectar ao servidor.

É recomendável usar esse tipo de notificação sempre que o JavaScript da página executar operações em segundo plano (ou seja, que não foram iniciadas diretamente pelo usuário). Assim, você pode informar quando algo deu errado e orientar o usuário sobre os próximos passos.