Autorización en Kommo

Dado que nuestra integración utiliza OAuth 2.0 para la autorización, después de completar la configuración como se describe en nuestra guía paso a paso, se generará un código de autorización. Este código debe intercambiarse por un par de tokens de acceso y actualización. Estos tokens deben almacenarse de forma segura en tu base de datos, junto con su tiempo de expiración.

🚧

Ten en cuenta que un mismo usuario puede instalar la integración en múltiples cuentas. Los integradores deben garantizar una estricta separación de datos entre estas cuentas para evitar cualquier fuga de información o acceso no autorizado entre cuentas que pertenezcan al mismo usuario.

Una vez que la integración está instalada, aparecerá la ventana de configuración con los campos que debe completar el administrador de la cuenta de Kommo. Kommo solo considerará que tu integración está configurada correctamente cuando estos ajustes se guarden de manera exitosa. Esto se implementa en la UI/UX llamando a la función de callback onSave cuando el administrador elige guardar la configuración de la integración. La función debe retornar true cuando el widget se haya configurado correctamente, y false en caso contrario.

function CustomWidget() {
  const self = this;

  self.clickSaveButton = function () {
    /*
     * Esta función define las acciones que se ejecutan
     * cuando se hace clic en el botón de guardar.
     */
    const $save_button = $(document).find(".js-widget-save");

    $save_button.click();
  };

  /**
   * Un objeto que contiene los callbacks específicos del widget.
   * Obtén más información sobre los callbacks aquí https://developers.kommo.com/docs/script-js
   */
  this.callbacks = {
    /**
     * Callback que se activa cuando se hace clic en el botón ".js-widget-save".
     */
    onSave: (widgetConfiguration) => {
      const { active, fields } = widgetConfiguration;

      /**
       * Aquí puedes especificar una condición que determine
       * si el widget está listo para ser configurado.
       */
      const isWidgetConfiguredByCRM = active.toLowerCase() === "y";

      /**
       * El manifest.json especifica los nombres de los campos que se muestran en la configuración.
       * Estos nombres son las claves del objeto "fields".
       * Los valores de esas claves corresponden a los valores ingresados
       * en el momento en que se activa el callback onSave.
       */
      const { login, password } = fields;

      const areFieldsFilled = login && password;

      const isWidgetReady = isWidgetConfiguredByCRM && areFieldsFilled;

      if (isWidgetReady) {
        alert("La configuración de integración se ha guardado correctamente!");

        /**
         * Retorna true si el widget está listo.
         */
        return true;
      }

      alert("Kommo no pudo registrar tu widget.");

      /**
       * De lo contrario, retorna false.
       */
      return false;
    },
  };

  return this;
}

Ten en cuenta que no debes utilizar el subdominio de la cuenta como clave primaria para tus ajustes, ya que podría cambiar. Tampoco recomendamos utilizar el ID de la cuenta con ese propósito. La mejor opción es utilizar un campo ID autoincremental como clave primaria, y que el ID de la cuenta y el subdominio simplemente se almacenen como propiedades de tipo int y string, Para más información sobre la configuración, consulta el artículo de configuración de widgets.

Autorización del servicio VoIP

Después de que el usuario instala la integración desde el Centro de integraciones de Kommo, la integración debe mostrar una ventana modal de configuración donde el usuario pueda realizar algunas acciones, como proporcionar las credenciales para acceder al servicio VoIP. Estas credenciales solo las conoce el administrador de la cuenta del servicio VoIP. Otra opción es utilizar OAuth 2.0 para la autorización.

Es necesario guardar la información de autorización para realizar futuras llamadas a la API del servicio. A partir de este punto, el widget puede considerarse activo.

Configuración de la integración

La configuración del manejo de llamadas permite definir cómo responde el sistema a distintos tipos de llamadas y acciones del usuario. Entre los ajustes disponibles se incluyen habilitar el sonido de llamada, proporcionar retroalimentación de la llamada, abrir automáticamente la tarjeta del cliente cuando se recibe una llamada y permitir que los usuarios califiquen la calidad de la llamada.

Los administradores también pueden configurar qué ocurre en diferentes escenarios de llamada, como llamadas de números conocidos o desconocidos, y llamadas contestadas o perdidas. Esta flexibilidad permite que el sistema se adapte a distintos flujos de comunicación y procesos de negocio.

Cuando se recibe una llamada desde un número desconocido, el sistema puede crear automáticamente un nuevo contacto y un lead, o registrar la llamada como un lead entrante. Los gerentes pueden tener la opción de aceptar estos leads manualmente, o los leads pueden aceptarse automáticamente una vez que la llamada es contestada.

Para las llamadas recibidas de contactos conocidos, la configuración puede incluir la creación automática de un lead si no existe uno activo, y añadir el número de teléfono a la nota si el contacto tiene múltiples números asociados.

Cuando un gerente pierde una llamada, el sistema puede crear automáticamente una tarea de seguimiento, establecer su fecha de caducidad, vincular la tarea al lead correspondiente y asignar un usuario responsable para asegurar que se realice la acción necesaria.

Para las llamadas salientes realizadas a números nuevos, la configuración puede incluir la creación automática de un nuevo contacto y un nuevo lead, garantizando que todas las interacciones queden registradas y rastreadas correctamente dentro del sistema.

Representación de dados

Un ejemplo de la información que puedes registrar en tu base de datos:

kommo_auth_tokens

voip_users

voip_calls

Entidades

Mientras programamos, necesitamos declarar algunas entidades:

Call

FromWebhook