Guía de configuración de adaptadores multicanal de OpenFang

20 min de lectura

OpenFang es compatible con más de 40 adaptadores de canal. Este artículo detalla la configuración completa de seis adaptadores comunes: CLI, WhatsApp Business API, Telegram Bot, Discord, Slack Socket Mode y el widget de Web Chat. Incluye soluciones integrales para la ejecución multicanal paralela, el uso compartido de contexto, el refuerzo de seguridad y la supervisión de estado.

Guía de configuración de adaptadores multicanal de OpenFang: Haz que tu Agente esté en todas partes

Slug: openfang-channel-setup-guide Categoría: usage-guides (Guías de uso) Palabras clave objetivo: configuración de canales OpenFang, adaptadores OpenFang, OpenFang WhatsApp Telegram Intención de búsqueda: Informativa (los usuarios desean conectar su Agente a diferentes plataformas) Longitud objetivo: ~1800 palabras Idioma: es

¿Qué es un adaptador de canal?

Un adaptador de canal (Channel Adapter) es el puente entre OpenFang y las plataformas externas. Cada adaptador se encarga de convertir los mensajes de la plataforma externa a un formato unificado que OpenFang pueda entender, y de traducir las respuestas del Agente al formato nativo de la plataforma.

La filosofía de diseño de OpenFang es "escribe la lógica del Agente una vez y ejecútala en más de 40 plataformas". No necesitas reescribir el Agente para cada plataforma; solo tienes que configurar el adaptador de canal correspondiente.

Actualmente, OpenFang admite más de 40 adaptadores de canal, cubriendo categorías como mensajería instantánea, redes sociales, herramientas de colaboración, correo electrónico y API personalizadas.

Conceptos clave de los adaptadores de canal

Todos los adaptadores de canal comparten los siguientes principios de diseño:

  • Formato de mensaje unificado: Independientemente del canal de origen, los mensajes se convierten al formato estándar de mensaje de OpenFang.
  • Sandbox independiente: Cada adaptador de canal se ejecuta en un entorno aislado (sandbox), por lo que un fallo en un canal no afecta a los demás.
  • Carga en caliente (Hot-loading): No es necesario reiniciar el Agente tras añadir o modificar la configuración de un canal.
  • Limitación de tasa (Rate limiting): Protección integrada para evitar superar los límites de la API de la plataforma.

Configuración de adaptadores de canal comunes

Adaptador CLI

La CLI es el adaptador más básico, ideal para desarrollo, depuración y uso local:

toml
[channels.cli]enabled = truehistory_size = 1000              # Número de mensajes del historial a conservarprompt_style = "rich"            # plain / rich / minimal

El adaptador CLI está listo para usar sin configuración adicional. Admite entrada multilínea, autocompletado de comandos y resaltado de sintaxis.

Adaptador WhatsApp

WhatsApp es una de las herramientas de mensajería más utilizadas a nivel mundial. A través de la API de WhatsApp Business, tu Agente puede interactuar directamente con los usuarios en WhatsApp:

toml
[channels.whatsapp]enabled = trueapi_version = "v18.0"phone_number_id = "${WA_PHONE_NUMBER_ID}"access_token = "${WA_ACCESS_TOKEN}"verify_token = "${WA_VERIFY_TOKEN}"[channels.whatsapp.features]media_support = true             # Soporte para enviar imágenes/archivosreply_buttons = true             # Soporte para botones interactivosmax_message_length = 4096typing_indicator = true          # Mostrar "escribiendo..."

Pasos de configuración:

  1. Crea una aplicación de WhatsApp en Meta for Developers.
  2. Obtén el Phone Number ID y el Access Token.
  3. Configura la URL del Webhook (la dirección de tu servidor OpenFang + /webhook/whatsapp).
  4. Introduce la información anterior en la configuración de OpenFang.

Adaptador Telegram

Telegram es una de las plataformas de comunicación más populares en la comunidad técnica; su configuración es sencilla y su API es muy amigable:

toml
[channels.telegram]enabled = truebot_token = "${TELEGRAM_BOT_TOKEN}"allowed_users = []               # Dejar vacío = acceso para todos los usuariosadmin_users = ["@your_username"][channels.telegram.features]inline_queries = true            # Soporte para consultas en líneamarkdown_support = truefile_upload = truemax_file_size_mb = 50

Pasos de configuración:

  1. Habla con @BotFather en Telegram para crear un Bot.
  2. Obtén el Bot Token.
  3. Introduce el Token en el archivo de configuración.

Adaptador Discord

El adaptador de Discord admite tanto servidores (Guilds) como mensajes directos:

toml
[channels.discord]enabled = truebot_token = "${DISCORD_BOT_TOKEN}"application_id = "${DISCORD_APP_ID}"[channels.discord.guilds]server_ids = ["1234567890"]      # IDs de servidores permitidos[channels.discord.features]slash_commands = true            # Soporte para comandos de barra (/)thread_support = true            # Soporte para hilosembed_messages = true            # Mensajes enriquecidos (embeds)

Adaptador Slack

Ideal para entornos de colaboración empresarial:

toml
[channels.slack]enabled = truebot_token = "${SLACK_BOT_TOKEN}"signing_secret = "${SLACK_SIGNING_SECRET}"app_token = "${SLACK_APP_TOKEN}"[channels.slack.features]socket_mode = true               # Usar Socket Mode (recomendado, no requiere URL pública)thread_replies = truereaction_feedback = true

Slack recomienda usar Socket Mode, ya que no requiere configurar una URL de Webhook accesible públicamente, lo cual es ideal para despliegues en redes internas.

Adaptador Web Chat

Inserta una ventana de chat de OpenFang en tu sitio web:

toml
[channels.webchat]enabled = trueport = 3000cors_origins = ["https://your-site.com"][channels.webchat.ui]theme = "auto"                   # light / dark / autologo_url = "/assets/agent-logo.png"welcome_message = "¡Hola! Soy el Agente de OpenFang, ¿en qué puedo ayudarte?"placeholder = "Escribe tu pregunta..."

Una vez configurado, añade esto a tu página web:

html
<script src="https://your-server:3000/widget.js"></script><script>OpenFangWidget.init({ position: 'bottom-right' })</script>

Ejecución multicanal simultánea

La arquitectura de OpenFang admite de forma nativa la ejecución multicanal en paralelo. El núcleo del Agente mantiene un estado de sesión unificado, y todos los canales comparten el contexto:

toml
# Habilitar múltiples canales simultáneamente[channels]cli.enabled = truewhatsapp.enabled = truetelegram.enabled = truediscord.enabled = truewebchat.enabled = true[channels.routing]strategy = "context_aware"       # round_robin / context_aware / prioritypreserve_context = true          # Mantener contexto entre canales para el mismo usuario

La estrategia de enrutamiento context_aware significa que si un usuario inicia una conversación en WhatsApp y luego cambia a Telegram, el Agente cargará automáticamente el contexto anterior.

Configuración de seguridad de canales

Más canales implican una mayor superficie de ataque. OpenFang ofrece controles de seguridad granulares para los canales:

toml
[channels.security]per_user_rate_limit = 30         # Máximo 30 mensajes por usuario por minutoper_channel_rate_limit = 100     # Máximo 100 mensajes por canal por minutorequire_auth = ["discord", "slack"]public_channels = ["webchat"]authenticated_channels = ["whatsapp", "telegram", "discord", "slack"][channels.security.content_filter]block_urls = falseblock_attachments = falsemax_prompt_length = 4000

Recomendaciones de seguridad clave:

  • Habilita límites de tasa estrictos para canales accesibles públicamente (Web Chat).
  • En entornos de producción, todos los canales excepto la CLI deben requerir autenticación de usuario.
  • Audita periódicamente los registros de acceso a los canales.

Supervisión del estado de los canales

bash
# Ver el estado de todos los canalesopenfang channels list# Ejemplo de salida:# Channel        Status    Messages/24h   Errors   Latency# cli            ✅ active       0           0         -# telegram       ✅ active     156          2       120ms# whatsapp       ✅ active      89          0       250ms# discord        ⚠️ degraded    43          5       500ms# webchat        ✅ active      12          0        45ms# Reiniciar un canal específicoopenfang channels restart discord# Ver registros detallados de un canalopenfang channels logs telegram --level debug

Preguntas frecuentes

¿Es necesario reiniciar el Agente al añadir un nuevo canal?
No. OpenFang admite la carga en caliente de la configuración de canales:

``bash
openfang channels reload
``

¿El historial de conversaciones es compartido entre diferentes canales?
Por defecto, sí. El historial de conversaciones de un mismo usuario se comparte entre todos los canales, por lo que no perderás el contexto al cambiar de plataforma. Si necesitas aislamiento por canal, puedes configurar preserve_context = false.
¿El adaptador de WhatsApp requiere una cuenta de WhatsApp Business?
Sí. El adaptador de WhatsApp utiliza la API de WhatsApp Business Platform y requiere una cuenta Business verificada. Las cuentas personales de WhatsApp no admiten acceso a la API.
¿Cómo puedo añadir un adaptador de canal personalizado?
OpenFang proporciona un SDK de canales. Solo necesitas implementar el trait ChannelAdapter para crear un adaptador personalizado:

``rust
use openfang::channels::{ChannelAdapter, Message};

struct MyCustomChannel;
impl ChannelAdapter for MyCustomChannel {
async fn receive(&self) -> Vec<Message> { /* ... */ }
async fn send(&self, msg: Message) -> Result<()> { /* ... */ }
}
``

Siguientes pasos

  • Guía de creación de flujos de trabajo automatizados de OpenFang: Orquesta agentes multicanal en procesos automatizados.
  • Mejores prácticas de seguridad de OpenFang: Protege tus despliegues de agentes multicanal.