Saltar al contenido principal

Omnicanal y Canales

PulseChat puede actuar como una bandeja de entrada omnicanal para plataformas de mensajería externas como WhatsApp, Telegram, Email, SMS, Slack, Viber, etc. Esta página explica cómo funcionan los canales, cómo configurarlos y cómo el personal interactúa con ellos.

1. Conceptos​

  • Canal -- una conexión configurada a un servicio externo (ej. un número de WhatsApp Business, un bot de Telegram, una bandeja de correo IMAP).
  • Conversación de canal -- un hilo con un contacto externo (ej. un chat de WhatsApp con un cliente).
  • Contacto externo -- registro unificado que representa a la parte externa (teléfono, email, etc.), mapeado a clientes/contactos/leads del CRM cuando es posible.

Tablas principales (creadas en 122_version_122.php):

  • pc_channels -- configuraciones de canales (tipo, nombre, configuración encriptada).
  • pc_external_contacts -- identidades de contactos externos de alto nivel.
  • pc_contact_identities -- identificadores específicos (teléfono, email, PSID, chat_id, etc.).
  • pc_automation_rules -- reglas de enrutamiento y automatización.

2. Habilitar Omnicanal​

  1. Como administrador, ve a Configuración de PulseChat.
  2. Habilita:
    • Habilitar Canales Omnicanal
      • Opción: pulsechat_channels_enabled
  3. Guarda.
  4. En la interfaz de chat, aparecerá una pestaña de Canales en la barra lateral.

3. Configurar Canales​

En la interfaz de chat:

  1. Haz clic en la pestaña Canales.
  2. Haz clic en el icono de engranaje en la barra de filtros de Canales (Configuración de Canales).
  3. Esto abre el modal de Configuración de Canales, donde puedes:
    • Crear nuevos canales.
    • Editar canales existentes.
    • Probar y guardar la configuración.

Cada tipo de canal tiene sus propios campos de configuración y requisitos, implementados mediante clases adaptadoras en libraries/channels/:

  • WhatsappAdapter.php
  • TelegramAdapter.php
  • EmailAdapter.php
  • (y otros como SMS, Slack, Viber, etc.)

La interfaz de administración para canales está impulsada por:

  • controllers/Pulsechat_Channels.php
  • assets/js/pulsechat-channels.js
nota

Muchos proveedores de canales requieren webhooks (ej. Telegram, WhatsApp Cloud API) y/o sondeo periódico (ej. Email vía IMAP). Asegúrate de configurar la URL del webhook de tu proveedor o las credenciales IMAP como se indica en la interfaz de Configuración de Canales.

4. Tipos de Canal Soportados​

La migración base (122_version_122.php) declara estos tipos:

  • whatsapp
  • telegram
  • messenger
  • instagram
  • email
  • sms
  • slack
  • viber

Diferentes adaptadores pueden estar presentes o añadirse con el tiempo. Revisa libraries/channels/ para ver los adaptadores disponibles en tu versión.

5. Flujo de Entrada (Alto Nivel)​

  1. Llega un mensaje externo:

    • Vía webhook (ej. WhatsApp/Telegram vía modules/pulsechat/webhook.php o controllers/webhooks/ChannelWebhook.php).
    • Vía sondeo (ej. Email IMAP vía pulsechat_cron_email_poll).

  2. ChannelManager:

    • libraries/channels/ChannelManager.php recibe la carga entrante.
    • Valida límites de frecuencia, decodifica el mensaje y normaliza los metadatos.

  3. Coincidencia de contacto:

    • libraries/ContactMatcher.php intenta mapear el identificador entrante (teléfono, email, PSID, etc.) a un:
      • Contacto externo existente (pc_external_contacts),
      • Contacto / cliente del CRM (tblcontacts / tblclients),
      • Lead (tblleads),
      • o crea un nuevo registro de contacto externo.

  4. Enrutamiento de conversación:

    • pc_conversations contiene conversaciones omnicanal (tipo channel).
    • Las reglas de automatización (pc_automation_rules) pueden aplicarse para:
      • Auto-asignar al personal / equipo.
      • Establecer estado, prioridad, etiquetas.
      • Activar acciones (respuesta automática, creación de ticket, respuesta IA, etc.).

  5. Creación de mensaje:

    • Se inserta una fila de mensaje en pc_messages con:
      • channel_id, channel_type, channel_conversation_id externo.
      • Dirección (inbound), estado, estado de entrega.

  6. Actualización de la interfaz:

    • La lista de conversaciones del canal se actualiza en pulsechat-channels.js.
    • El agente activo ve la nueva conversación y puede responder desde PulseChat.

6. Flujo de Salida (Alto Nivel)​

Cuando un agente responde en una conversación de canal:

  1. pulsechat-channels.js llama a:

    • config.channelSendMessageUrl vía admin/pulsechat/channel_api/send_channel_message

  2. Pulsechat_Channels::send_channel_message():

    • Valida permisos.
    • Persiste el mensaje en pc_messages como outbound.

  3. ChannelManager:

    • Usa el adaptador apropiado (WhatsappAdapter, TelegramAdapter, EmailAdapter, etc.) para enviar el mensaje a la plataforma externa.
    • Actualiza delivery_status (queued, sent, delivered, read, failed) y mensajes de error si los hay.

  4. Retroalimentación en la interfaz:

    • El mensaje aparece en la conversación con un indicador de estado.
    • Los errores (ej. token inválido, problemas de red) se muestran en la interfaz, a menudo con indicaciones (ej. "actualiza tu token de WhatsApp en la configuración del canal").

7. Notas Específicas por Canal​

7.1 WhatsApp​

  • Adaptador: libraries/channels/WhatsappAdapter.php
  • Requiere:
    • Token de Acceso Permanente de Meta (token de Usuario del Sistema con permiso whatsapp_business_messaging).
    • ID del número de teléfono y detalles de la cuenta de WhatsApp Business.
  • Interfaz:
    • El formulario de configuración del canal muestra campos como token de acceso, ID del teléfono, token de verificación del webhook, etc.
    • Los errores de WhatsApp (ej. "La sesión ha expirado") se capturan y muestran al agente con indicaciones de remediación.

7.2 Telegram​

  • Adaptador: libraries/channels/TelegramAdapter.php
  • Requiere:
    • Token del bot de BotFather.
  • Usa webhooks:
    • Debes configurar Telegram con la URL del webhook mostrada en la Configuración de Canales.
    • La verificación de firma se maneja en el adaptador.

7.3 Email​

  • Adaptador: libraries/channels/EmailAdapter.php
  • Usa sondeo IMAP y SMTP:
    • IMAP: obtención de correo entrante desde una bandeja.
    • SMTP: envío de respuestas (o recurso al SMTP predeterminado de Perfex si no está configurado).
  • Sondeo:
    • Implementado vía pulsechat_cron_email_poll() en pulsechat.php.
    • Enganchado al after_cron_run de Perfex.
  • TLS/OAuth:
    • El adaptador de email soporta inicios de sesión basados en OAuth o contraseñas de aplicación según el proveedor y la configuración.

8. Reglas de Automatización​

En modo omnicanal, puedes definir Reglas de Automatización para enrutamiento y acciones.

  • Almacenadas en pc_automation_rules.
  • Configurables mediante la interfaz omnicanal (sección de Reglas de Automatización).
  • Las acciones pueden incluir:
    • Asignar al personal / equipo.
    • Establecer estado / prioridad.
    • Añadir etiquetas.
    • Enviar respuestas predefinidas.
    • Crear tickets.
    • Activar Respuesta IA (se integra con el asistente de IA para respuestas completamente automáticas).

Estas reglas te permiten construir flujos de trabajo avanzados como:

  • "Si el mensaje viene de WhatsApp al número de 'Ventas', asignar al equipo de Ventas y etiquetar como whatsapp-lead."
  • "Si el canal es Email y el asunto contiene 'soporte', crear automáticamente un ticket y marcar la conversación como pending."

9. Interfaz de la Pestaña de Canales​

En la pestaña de Canales, los agentes ven:

  • Una barra de filtros:

    • Filtro de estado (Abierto, Pendiente, Resuelto, Cerrado).
    • Filtro de prioridad (Baja, Normal, Alta, Urgente).
    • Filtro de tipo de canal (WhatsApp, Telegram, Email, etc.).
    • Botón de Configuración de Canales (engranaje).

  • Una lista de conversaciones de canal:

    • Cada fila muestra:
      • Nombre del contacto externo.
      • Icono / tipo de canal.
      • Vista previa del último mensaje.
      • Estado, prioridad, conteo de no leídos.

  • Al seleccionar una conversación:

    • Se abre en el panel central del chat.
    • El panel de detalles muestra el contexto CRM del contacto (cliente/contacto/lead vinculado si coincide).

10. Mejores Prácticas​

  • Siempre prueba un canal después de configurarlo:

    • Usa un teléfono/email de prueba.
    • Verifica que los mensajes entrantes y salientes funcionen y los estados se actualicen.

  • Usa Reglas de Automatización para:

    • Asignar automáticamente nuevas conversaciones al equipo correcto.
    • Etiquetar y priorizar por canal y contenido.

  • Mantén las credenciales actualizadas:

    • Los tokens y contraseñas de aplicación suelen expirar.
    • Cuando veas fallos repetidos de envío, revisa la Configuración de Canales y los paneles del proveedor.

  • Para canales de email:

    • Asegúrate de que el cron de Perfex esté configurado y ejecutándose regularmente, o los emails entrantes no se obtendrán.

Si un canal específico presenta problemas, consulta Solución de Problemas y Preguntas Frecuentes para verificaciones específicas.