La API de plug-ins de CRM fue diseñada para permitir que clientes y desarrolladores puedan integrarse fácilmente con sus sistemas CRM. A través de esta API puede:

  • Iniciar llamadas salientes desde su aplicación
  • Obtener notificaciones sobre la duración de una llamada
  • Obtener notificaciones sobre llamadas entrantes y mostrar los registros de contactos en función del ID del llamante

Nota: 3CX NO PROVEE SOPORTE A DESARROLLADORES para esta API. Si Usted siente que la documentación provista con la aplicación de ejemplo puede ser mejorada, por favor ingrese al portal de soporte de 3CX y envíenos un requerimiento con sus comentarios. Por favor, trate de ser tan específico como pueda con su descripción.

Esta API requiere al módulo de integración CRM instalado en la máquina en donde desea utilizarla.

La diferencia entre la API de línea de comandos y la API de plug-ins de CRM es que ésta última permite agregar un plug-in al módulo de integración CRM y reutilizar mucha de la funcionalidad que 3CX ha creado para otros sistemas CRM.

Introducción

El módulo de integración CRM ha sido diseñado para ser extendido a través de plug-ins. Usted puede escribir su propio plug-in fácilmente utilizando cualquier lenguaje de .NET, haciendo que la integración entre la Central Telefónica 3CX y su sistema CRM sea realmente simple.

La interface del plug-in de CRM

Para escribir su propio plug-in necesita crear una biblioteca de .NET 2.0 conteniendo una clase pública que implemente la siguiente interface:

public interface IPlugin
{
  event OutboundCallRequestHandler OnOutboundCallRequest;

  void Start();
  void Stop();
  void ReloadConfiguration();

  string GetName();
  Icon GetIcon();
  PluginConfigurationControl GetConfigurationControl();
  bool HasToStoreCallInformation {get; set;}

  Contact GetContactInformation(string callerNumber);
  void ShowContactRecord(Contact contact);
  void CreateContactRecord(Contact contact);
  void StoreCallInformation(CallInformation callInformation);
  void VerifyPluginState();
  string GetAdditionalWorkingStatusInformation();
}

Como puede ver, solo es necesario implementar unos pocos métodos para tenerlo funcionando.

Detalles de la interface del plug-in de CRM

La nueva clase del plug-in de CRM que creará necesita tener algunos métodos, propiedades y eventos:

  • El método Start es invocado por la aplicación cuando el plug-in de CRM debe comenzar a funcionar. Esto puede suceder cuando es habilitado por primera vez, o cuando la aplicación arranca con el plug-in habilitado.
  • El método Stop es invocado por la aplicación cuando el plug-in de CRM debe detenerse. Esto puede suceder cuando es deshabilitado, o cuando la aplicación finaliza.
  • El método ReloadConfiguration es invocado por la aplicación luego de guardar los cambios en la configuración. El plug-in debería leer nuevamente la configuración y adaptar su comportamiento en consecuencia.
  • Usted tiene garantía de que estos tres métodos (Start, Stop y ReloadConfiguration) son siempre invocados desde el mismo hilo de ejecución.
  • El método GetName debe retornar el nombre del plug-in. El valor retornado será utilizado en todos los lugares donde la aplicación necesite identificar al plug-in, por ejemplo en el árbol de configuración de plug-ins.
  • El método GetIcon debe retornar un ícono para el plug-in. Este ícono es utilizado en el árbol de configuración de plug-ins.
  • El método GetConfigurationControl debe retornar una instancia de una clase derivada de PluginConfigurationControl. Este es el control que se muestra al usuario para permitir la configuración del plug-in. La clase PluginConfigurationControl es una clase derivada de System.Windows.Forms.UserControl, simplemente agregando el método virtual Save. Debe escribir ese método implementando allí la lógica de guardado de la configuración.
  • La propiedad HasToStoreCallInformation informa si el plug-in debe guardar la información de la llamada luego de que una llamada entrante o saliente ha finalizado. En caso de ser true, la aplicación principal de CRM invocará al método StoreCallInformation cuando la llamada finalice.
  • El método GetContactInformation es invocado cuando recibe una llamada entrante y el plug-in se encuentra habilitado. Note que múltiples llamadas arribando en simultáneo podrían hacer que el método GetContactInformation sea invocado múltiples veces, en forma simultánea desde diferentes hilos de ejecución.
  • El método ShowContactRecord es invocado cuando el usuario presiona el enlace “Haga clic para abrir el registro de contacto” en el screen pop-up. Note que múltiples clics del usuario en diferentes screen pop-ups pueden disparar múltiples invocaciones al método ShowContactRecord desde diferentes hilos de ejecución en forma simultánea.
  • El método CreateContactRecord es invocado cuando el usuario presiona el enlace “Haga clic aquí para crear un nuevo registro de contacto” en el screen pop-up. Note que múltiples clics del usuario en diferentes screen pop-ups pueden disparar múltiples invocaciones al método CreateContactRecord desde diferentes hilos de ejecución en forma simultánea.
  • El método StoreCallInformation method es invocado cuando una llamada entrante o saliente finaliza y la propiedad HasToStoreCallInformation se encuentra configurada como true, conteniendo la información relacionada a la llamada.
  • El método VerifyPluginState es invocado periódicamente cuando el plug-in se encuentra habilitado para verificar su estado. Si el plug-in detecta un problema, debería lanzar una excepción indicando el error.
  • El método GetAdditionalWorkingStatusInformation es invocado periódicamente cuando el plug-in se encuentra habilitado y funcionando (es decir, sin errores), para obtener una descripción para mostrar en la página de estado de los plug-ins. Si el plug-in no necesita mostrar información adicional en la página de estado, entonces solo debe retornar un string vacío.

Para generar una llamada saliente, el plug-in necesita disparar el evento OnOutboundCallRequest, indicando el número de destino. Note que posteriormente la aplicación principal de integración CRM puede agregar un prefijo, por ejemplo para seleccionar una ruta de salida.

Creando un plug-in con Microsoft Visual Studio

El procedimiento para crear un plug-in con Microsoft Visual Studio es muy sencillo. Puede utilizar  Visual Studio 2005, 2008 o 2010:

    1. Cree un nuevo proyecto. Seleccione el lenguaje de.NET de su preferencia (C#, VB .NET, etc.) y cree un nuevo proyecto de tipo “Windows Class Library”. Asegúrese que el proyecto sea creado para el .NET Framework 2.0.
    2. Agregue una referencia a la biblioteca “CRM Plugin Interface.dll” que se instala con el módulo de integración CRM (normalmente C:Program Files3CX CRM IntegrationCRM Plugin Interface.dll).
    3. Renombre la clase creada por defecto “Class1” a algo válido para su plug-in, por ejemplo “MyCrmPlugin”, y luego modifique la clase para implementar la interface TCX.CRM.IPlugin.
public class MyCrmPlugin : TCX.CRM.IPlugin
{
}
    1. Agregue la implementación de la interface:

    1. Obtendrá algo como esto:
public class MyCrmPlugin : TCX.CRM.IPlugin
{
  #region IPlugin Members

  public void CreateContactRecord(TCX.CRM.Contact contact)
  {
    throw new NotImplementedException();
  }

  public string GetAdditionalWorkingStatusInformation()
  {
    throw new NotImplementedException();
  }

  public TCX.CRM.PluginConfigurationControl GetConfigurationControl()
  {
    throw new NotImplementedException();
  }

  public TCX.CRM.Contact GetContactInformation(string contactNumber)
  {
    throw new NotImplementedException();
  }

  public System.Drawing.Icon GetIcon()
  {
    throw new NotImplementedException();
  }

  public string GetName()
  {
    throw new NotImplementedException();
  }

  public bool HasToStoreCallInformation
  {
    get
    {
      throw new NotImplementedException();
    }
    set
    {
      throw new NotImplementedException();
    }
  }

  public event TCX.CRM.OutboundCallRequestHandler OnOutboundCallRequest;

  public void ReloadConfiguration()
  {
    throw new NotImplementedException();
  }

  public void ShowContactRecord(TCX.CRM.Contact contact)
  {
    throw new NotImplementedException();
  }

  public void Start()
  {
    throw new NotImplementedException();
  }

  public void Stop()
  {
    throw new NotImplementedException();
  }

  public void StoreCallInformation(TCX.CRM.CallInformation callInformation)
  {
    throw new NotImplementedException();
  }

  public void VerifyPluginState()
  {
    throw new NotImplementedException();
  }

  #endregion
}
  1. Ahora deberá completar la implementación de cada método, de acuerdo a lo descripto más arriba.

Desplegando su plug-in

Cuando tenga su biblioteca .NET lista, simplemente cópiela en la carpeta Plugins dentro del directorio de instalación del módulo de integración CRM (normalmente C:Program Files3CX CRM IntegrationPlugins), y reinicie la aplicación “3CX CRM Integration”. La nueva biblioteca de su plug-in CRM será cargada automáticamente, y podrá configurar su plug-in desde la interfaz de la aplicación “3CX CRM Integration”.