Kommo permite mostrar una ventana de notificación en la esquina inferior izquierda. Un ejemplo de uso es una notificación sobre una llamada entrante enviada por el sistema de telefonía.

Existen dos formas principales de crear notificaciones de llamadas: crear la notificación de llamada mediante la API y mediante el widget JavaScript.

Crear una notificación de llamada mediante API

Puedes crear una notificación de llamada a través de la API. Este método buscará automáticamente una entidad (contacto/compañía/lead) por el número telefónico enviado y mostrará una notificación para el empleado correspondiente con el nombre de la entidad, según la siguiente prioridad:

• Si el contacto/la compañía tiene un solo lead activo, entonces se mostrará ese lead.
• Si el contacto/la compañía tiene más de un lead activo o no tiene leads relacionados, entonces se mostrará el nombre del contacto o de la compañía.

Si ese número aún no existe en el sistema, la notificación ofrecerá crear un contacto con ese número.

👍

Este método te permitirá evitar realizar solicitudes innecesarias para buscar entidades por número de teléfono mediante la API, lo que optimiza significativamente el funcionamiento de la integración VoIP.

Crear una notificación de llamada mediante el widget JS

Otra forma es crear notificaciones utilizando la parte JavaScript del widget. Al recibir una llamada entrante, la PBX virtual consulta a Kommo mediante el método API Obtener contactos, enviando el número telefónico en el parámetro ?query={phone_number} para solicitar información sobre el contacto que llama. Este contacto debe existir en Kommo y el usuario correspondiente debe tener permisos para ver la tarjeta del contacto deseado.

Debe establecerse un timeout mínimo para procesar la solicitud y evitar problemas con las llamadas en caso de conectividad degradada entre la PBX y Kommo.

Para enviar la información de llamadas entrantes al script JS del lado del cliente, normalmente se utiliza tecnología web-socket. Esto implica establecer una conexión persistente y suscribirse a eventos. Como alternativa, puede emplearse un sondeo periódico mediante JS — cargando regularmente un archivo JS desde un servidor externo, el cual devuelve un arreglo que indica el estado actual de la llamada (por ej.: llamada entrante, inactivo, etc., para cada número interno del usuario).

La elección entre estos métodos depende de si la PBX virtual admite web-sockets. También es importante mapear los números internos a los usuarios de Kommo que estén autorizados a ver la interfaz.

Ejemplo de una tarjeta de llamada entrante

Para implementar una tarjeta de llamada entrante, puedes usar el objeto APP.notifications.add_call(call_params) . En el ejemplo, se crea una función para trabajar con este objeto. Para obtener la información del contacto utilizando únicamente el número telefónico de la llamada entrante, puedes utilizar el método Obtener contactos con el 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;

  /**
   * Si es necesario, personalice o modifique los parámetros de notificación.
   */
  const possibleCallers = await searchContactByPhone(from);

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

    return `${index ? acc : `${acc}, `}${name}`;
  }, "El número de teléfono está vinculado a: ");

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

  /**
   * Agrega una notificación con las opciones definidas.
   */
  APP.notifications.add_call(notification);
};

Para obtener la información de un contacto mediante el número telefónico de una llamada entrante, puedes enviar una solicitud Obtener lista de contactos con el 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);
  }
};

Ubicación del widget

Es importante recordar que debes declarar el alcance de conexión del widget en el archivo manifest.json. Para habilitar la función de tarjeta de llamada entrante, se recomienda establecer el alcance en everywhere. De esta manera, tu widget se activará en cualquier área de Kommo, permitiéndote recibir notificaciones de llamadas entrantes sin importar lo que el usuario esté haciendo en Kommo en ese momento. Puedes leer más sobre los alcances de conexión aquí:

"locations": [ "everywhere"]

Crear una notificación de error

Para notificar a los usuarios sobre problemas que ocurren en procesos en segundo plano, debe utilizarse un objeto JavaScript específico. Cuando se invoque, este objeto mostrará una notificación de error al usuario, por ejemplo, informándole sobre una conexión fallida con el servidor.

Se recomienda utilizar este tipo de notificaciones siempre que el JavaScript de la página realice operaciones en segundo plano (acciones que se ejecutan silenciosamente sin interacción directa del usuario). En estos casos, puedes informar al usuario que algo salió mal y proporcionar orientación sobre los pasos que debe seguir.