Integraciones

pnpm add @botmesh/chatwoot @botmesh/tickets @botmesh/moderation @botmesh/dialogflow @botmesh/nlu

​

Cómo encajan en el pipeline

• Chatwoot ve los mensajes que la moderación descarta después (el agente tiene el contexto completo).
• Un mensaje que descarta la moderación nunca llega a Dialogflow, a los comandos ni a los handlers.
• Los hooks before('message') siguen corriendo mientras un chat está en handoff, así que la moderación y Chatwoot siguen funcionando ahí. El hook de Dialogflow se salta los chats en handoff: no se llama a detectIntent mientras atiende un humano (ver Dialogflow).
• Las rutas de Dialogflow son predicados de bot.when, así que ganan al catch-all de aiPlugin sea cual sea el orden de plug. La regla “instala aiPlugin después de slashCommandsPlugin” sigue valiendo; estos plugins no la cambian.

​

Chatwoot

import { createServer } from 'node:http'
import { Bot } from '@botmesh/core'
import { chatwootPlugin } from '@botmesh/chatwoot'

const bot = new Bot({ provider, store, lang: 'es', handoff: { allowCommands: ['/bot'] } })

const chatwoot = chatwootPlugin({
  baseUrl: 'https://app.chatwoot.com',
  apiKey: process.env.CHATWOOT_TOKEN!,           // access token de un usuario/agente
  accountId: 1,
  inboxId: 2,                                    // un inbox de tipo "API"
  webhookToken: process.env.CHATWOOT_WEBHOOK_TOKEN!,
  labels: { handoff: ['humano'], resume: ['bot'] },
})
bot.plug(chatwoot)

bot.when('hablar con humano', async (ctx) => {
  await ctx.handoff({ reason: 'el usuario pidió un agente' })
  await ctx.reply('Te conecto con un agente…')
})

// Chatwoot: Settings → Integrations → Webhooks
//   URL: https://bot.example.com/chatwoot?token=<CHATWOOT_WEBHOOK_TOKEN>
//   eventos: message_created, conversation_status_changed
createServer(chatwoot.webhookHandler()).listen(3001)
await bot.start()

app.post('/chatwoot', express.raw({ type: '*/*' }), async (req, res) => {
  const r = await chatwoot.handleWebhook({ rawBody: req.body, headers: req.headers, query: req.query })
  res.status(r.status).send(r.body)
})

​

Qué hace

​

Opciones de Chatwoot

​

Seguridad

• La autenticación del webhook es obligatoria: la factory lanza un error sin webhookToken, webhookSecret o insecureNoWebhookAuth: true. Reserva esta última para un endpoint que no sea accesible desde fuera.
• El token se acepta en ?token=, x-chatwoot-token o Authorization: Bearer. Chatwoot (comprobado en 4.7) no firma los webhooks de cuenta, así que pon el token en la URL del webhook; webhookSecret es para un emisor o proxy que firme como se describe a continuación. La firma HMAC-SHA256 va en x-chatwoot-signature (hex, admite el prefijo sha256=) y se calcula sobre ${timestamp}.${rawBody}, con x-chatwoot-timestamp (segundos) dentro de webhookToleranceSec (300). Una firma sobre el body solo no caduca nunca, así que una petición capturada se podría repetir: se rechaza salvo con webhookAllowUntimedSignature: true. Las comparaciones son de tiempo constante.
• handleWebhook responde 401 sin autenticación válida, 400 con JSON inválido y 503 antes de que el plugin esté instalado; nunca lanza. webhookHandler solo acepta POST y limita el body a 1 MiB.
• El HTTP saliente pasa por secureFetch de @botmesh/http: solo HTTPS, protección anti-SSRF, timeouts y sin seguir redirecciones, así que el api_access_token nunca llega a otro origen. Un Chatwoot self-hosted en la LAN necesita http.allowPrivateHosts (y http.allowHttp para HTTP plano): una baseUrl http:// sin http.allowHttp lanza al crear el plugin, y un host privado bloqueado se reporta indicando la opción.
• Con syncMode: 'all' todas las conversaciones se copian a Chatwoot. Usa syncMode: 'handoff' si solo los chats escalados deben salir del bot.

​

Limitaciones de Chatwoot

• Los medios entrantes se reflejan como texto ([image] caption), no se suben como adjuntos.
• Un chat, una conversación. Si la conversación mapeada ya no existe (Chatwoot responde 404, o 422 mientras aún borra un contacto), se crea otra y el mensaje va ahí.
• Marcar como fallida una respuesta rechazada usa la API de estado de mensajes, que Chatwoot solo ofrece en inboxes de canal API (el tipo que este plugin necesita de todos modos).
• Si el store no tiene cursores, el mapeo vive en memoria (se avisa en el log al instalar).

​

Tickets

import { ticketsPlugin } from '@botmesh/tickets'

bot.plug(ticketsPlugin({
  workingHours: { days: [1, 2, 3, 4, 5], start: '09:00', end: '18:00' },
  timezone: 'America/Bogota',
  queueMessage: 'Estás en cola, posición {{position}} (ticket #{{id}})',
  closedMessage: 'Estamos fuera de horario; te respondemos al abrir (ticket #{{id}})',
  assignMessage: '{{assignee}} atiende tu ticket #{{id}}',
  closeMessage: 'Ticket #{{id}} cerrado. ¡Gracias!',
  handoffOnAssign: true,   // bot.handoff(chatId) al asignar
  resumeOnClose: true,     // bot.resume(chatId) al cerrar
  onAssign: async (ticket) => notifyAgent(ticket),
}))

bot.when('soporte', async (ctx) => {
  const ticket = await ctx.tools.tickets!.create({ chatId: ctx.from, subject: ctx.body, priority: 'normal' })
  if (!ticket.created) await ctx.reply(`Ya tienes el ticket #${ticket.id}`)
})

// Panel de agentes / tu propia API
const tickets = bot.injectTools.tickets!
await tickets.assign('1', 'ana')
await tickets.close('1', { reason: 'resuelto' })

​

API

​

Opciones de tickets

​

Persistencia

​

Limitaciones de tickets

• No hay interfaz ni identidad de agentes: assignee es un string libre. Construye el panel sobre bot.injectTools.tickets y protégelo tú.
• Con handoffOnAssign, solo la primera asignación pasa el chat a un humano: una reasignación mantiene el handoff y su meta.assignee (lee el ticket para saber el agente actual), y desasignar (assignee: null) devuelve el ticket a la cola pero deja el chat en handoff. Llama tú a bot.resume(chatId) si el bot debe volver a responder.
• meta tiene que ser un objeto JSON plano (sin Date, Map, instancias de clases, funciones ni BigInt); cualquier otra cosa se rechaza antes de guardar el ticket. Una propiedad con valor undefined se descarta, como en JSON, así que { email: user?.email } o { ...prev, clave: undefined } (para quitar una clave) funcionan; un undefined dentro de un array se rechaza.
• En modo compartido cada llamada relee el índice y todos los tickets activos, así que su coste crece con el número de tickets abiertos.
• list() con un filtro que pueda incluir closed recorre todos los ids desde 1 hasta el último.
• El almacenamiento por defecto (los cursores del store) no tiene compare-and-set, así que sirve para un proceso por namespace del store: dos réplicas sobre él repartirían el mismo id y se pisarían el índice. Para réplicas, pasa un almacenamiento con setIf, como durableKvTicketStorage(kv) sobre el mismo DurableKv (Postgres, Redis, SQLite o un archivo) en todas las réplicas. El desk relee entonces el índice en cada llamada, reclama los ids con compare-and-set y reintenta una escritura perdida (maxRetries, 20 por defecto; después TicketContentionError). Con reuseOpen (por defecto) también reclama con compare-and-set el ticket abierto del chat, así que dos réplicas que crean a la vez un ticket para el mismo chat (desde un handler, la API o el manager) obtienen el mismo. Un create que falla nunca deja un ticket abierto invisible para get, list y queue.
  import { durableKvTicketStorage, ticketsPlugin } from '@botmesh/tickets'
  
  bot.plug(ticketsPlugin({ storage: durableKvTicketStorage(kv) }))
  

​

Moderación

import { Bot } from '@botmesh/core'
import { moderationPlugin } from '@botmesh/moderation'

const bot = new Bot({ provider, lang: 'es' }) // groupMode 'all' (el de por defecto)

bot.plug(moderationPlugin({
  provider,                                   // activa delete/kick/admins si el provider los admite
  antiSpam: { maxMessages: 5, windowMs: 10_000, action: 'warn' },
  wordFilter: { banned: ['spam', 'estafa', /bit\.ly\/\w+/i], action: 'delete' },
  autoKickOnLink: true,                       // = linkFilter: { action: ['delete', 'kick'] }
  warnings: { max: 3, then: 'kick' },
  groups: {
    [grupoStaff]: false,                      // sin moderación aquí
    [grupoVentas]: { wordFilter: { banned: ['gratis'] } },
  },
}))

bot.on('moderation', (report) => {
  // { chatId, senderId, rule, detail, ref, results: [{ action, status }], warnings }
})

​

Reglas y acciones

• Las palabras se comparan sin mayúsculas ni tildes (la ñ sigue siendo distinta de la n) y como palabra completa; las RegExp se prueban sobre el texto crudo.
• Antes de buscar palabras y enlaces se quitan los caracteres invisibles (espacios de ancho cero, guion suave, controles bidi) y las formas de compatibilidad como ｓｐａｍ (ancho completo) se leen como letras normales, así que no sirven para esconder una palabra o una invitación. El formato de WhatsApp alrededor de un enlace (_cursiva_, *negrita*, ~tachado~) tampoco lo esconde.
• Invitaciones reconocidas: WhatsApp (chat.whatsapp.com/…), Telegram (t.me/+…, t.me/joinchat/…) y Discord (discord.gg/…, discord.com/invite/…). allowInvites compara el código exacto.
• action acepta una acción o varias en orden.
• autoKickOnLink: true es un atajo de linkFilter: { action: ['delete', 'kick'] } y solo se aplica si no hay linkFilter definido (global o en el override del grupo).

​

Limitaciones de la moderación

• El estado (ventanas de spam, advertencias, silencios) vive en memoria y se pierde al reiniciar.
• Ningún provider del monorepo expone todavía groups.removeParticipants / getAdmins, así que kick se degrada a mute y la detección de admins depende de admins / isAdmin.
• GroupAdminApi y ModerationProvider.groups son @experimental (fuera de semver) hasta que @botmesh/core defina una capacidad de grupos para los providers; su forma puede cambiar en una versión minor.

​

Dialogflow

import { Bot, flow } from '@botmesh/core'
import { dialogflowPlugin, whenDialogflowIntent } from '@botmesh/dialogflow'

const bot = new Bot({ provider, lang: 'es' })

bot.plug(dialogflowPlugin({
  credentials: JSON.parse(process.env.GOOGLE_CREDENTIALS!), // JSON de la cuenta de servicio
  languageCode: 'es',
  fulfillment: 'unrouted',     // responde con el texto del agente si la intención no tiene ruta
}))

const df = bot.injectTools.dialogflow!

// Handler: recibe el resultado normalizado
whenDialogflowIntent(bot, df, 'order.status', (ctx, r) =>
  ctx.reply(`Buscando el pedido ${String(r.parameters.order)}…`))

// Flow: los parámetros se copian a c.state antes del primer paso
whenDialogflowIntent(bot, df, 'book.table', flow('reserva')
  .say((_ctx, c) => `Reserva para ${String(c.state.people)} personas`)
  .ask('¿A nombre de quién?', 'name'))

bot.onMessage((ctx) => ctx.reply('No te entendí'))   // aquí caen los mensajes sin ruta

​

Cómo funciona

1. El hook before('message') llama a detectIntent y guarda el resultado asociado a ese mensaje. ctx.tools.dialogflow.resultFor(ctx) lo lee desde cualquier handler.
2. whenDialogflowIntent registra un predicado de bot.when que lee ese resultado (sin una segunda llamada). Si la intención coincide con al menos minConfidence, se ejecuta el destino; si no, el mensaje sigue hacia los demás matchers y el catch-all.
3. No se envían a Dialogflow: mensajes vacíos, interacciones, comandos (commandPrefix, por defecto '/'), textos de más de maxTextLength (256 caracteres, el límite de la API), mensajes de un chat en handoff, mensajes de un usuario dentro de una conversación activa (skipActiveConversation, por defecto true) y lo que rechace filter.
4. Si detectIntent (o filter) falla, se registra en el log, se llama a onError(error, ctx) y el mensaje sigue su camino. Un 401 descarta el access token en caché y reintenta una vez con uno nuevo.

​

Opciones de Dialogflow

​

Seguridad y privacidad

• Unas credenciales inválidas (code: 'INVALID_CREDENTIALS') y unas opciones inválidas (code: 'INVALID_CONFIG': minConfidence fuera de 0–1, un fulfillment o sessionScope desconocido, un commandPrefix vacío, una location mal formada…) lanzan DialogflowError de forma síncrona al hacer bot.plug(). El access token se pide de forma perezosa con el primer mensaje, se guarda en caché y se renueva poco antes de caducar.
• La clave de sesión se hashea (SHA-256, 32 caracteres) antes de usarse como id de sesión de Dialogflow, así que ni los ids de chat ni los números de teléfono se envían a Google. El texto del mensaje sí.
• Guarda el JSON de la cuenta de servicio en un secreto, nunca en el repo.
• Los parámetros (en el resultado y al copiarse a c.state) omiten __proto__, constructor y prototype: vienen de un servicio remoto y no deben llegar al prototipo del objeto de estado.
• Un destino de ruta que no sea una función handler, un builder flow() o un flow compilado lanza un TypeError al registrarlo.

​

Limitaciones de Dialogflow

• Solo se envía texto (ni audio ni eventos). En CX el rellenado de formularios vive en las páginas: allRequiredParamsPresent siempre es true.

​

Intenciones locales (NLU)

import { nluPlugin, whenIntent } from '@botmesh/nlu'

bot.plug(nluPlugin, {
  threshold: 0.5, // confianza mínima, 0..1
  intents: {
    saludo: ['hola', 'buenas', 'buenos días'],
    'pedido.estado': ['mi pedido {id}', 'estado de mi pedido', 'dónde está mi pedido'],
  },
})
const nlu = bot.injectTools.nlu!

whenIntent(bot, nlu, 'saludo', (ctx) => ctx.reply('¡Hola! ¿En qué te ayudo?'))
whenIntent(bot, nlu, 'pedido.estado', async (ctx, match) => {
  const id = match.entities?.id
  await ctx.reply(id ? `Buscando el pedido ${id}…` : '¿Cuál es tu número de pedido?')
})
// Lo que ninguna intención reclama sigue a otros handlers (o al autoresponder de IA).

• nluPlugin es un plugin spec: se enchufa con bot.plug(nluPlugin, config). Deja un IntentEngine en ctx.tools.nlu (y en bot.injectTools.nlu).
• whenIntent(bot, engine, intent, handler) es un predicado de bot.when(): el handler solo corre cuando la mejor intención del mensaje es esa, por encima del umbral, y recibe el resultado. Devuelve la función para quitarlo.
• engine.match(text) devuelve { intent, confidence, entities? } o null; engine.rank(text) puntúa todas las intenciones (útil para depurar una frase); engine.define(intent, utterances) añade frases en caliente.
• La comparación normaliza mayúsculas, tildes, puntuación, letras de ancho completo y caracteres invisibles (¡HOLA! equivale a hola) y puntúa por palabras en común; los signos vocálicos de escrituras como el devanagari se quedan en su palabra. Una frase con solo emojis o puntuación lanza en define(): nunca podría coincidir. La puntuación separa palabras, así que un id como A-1 no llena un único slot. Una frase exacta, o una con marcadores {slot} que encaja con todo el mensaje, puntúa 1; cada slot captura una palabra.
• Alcance: sin lematización, sinónimos ni embeddings. Dale a cada intención varias frases cortas con las palabras que de verdad escriben tus usuarios y evita intenciones que compartan casi todo el vocabulario.

​

Combinarlos

bot.plug(moderationPlugin({ provider, antiSpam: { maxMessages: 5, windowMs: 10_000 } }))
bot.plug(chatwootPlugin({ /* … */ labels: { handoff: ['humano'] } }))
bot.plug(ticketsPlugin({ handoffOnAssign: true, resumeOnClose: true }))

​

Siguientes pasos

• Handoff humano
• Hooks
• Plugins
• IA