Integrations

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

​

How they fit in the pipeline

• Chatwoot sees messages that moderation later drops (the agent gets the full picture).
• A message moderation drops never reaches Dialogflow, commands or handlers.
• before('message') hooks keep running while a chat is in handoff, so moderation and Chatwoot keep working there. Dialogflow’s hook skips handed-off chats: no detectIntent call is made while a human is in charge (see Dialogflow).
• Dialogflow routes are bot.when predicates, so they win over the aiPlugin catch-all whatever the plug order. The rule “install aiPlugin after slashCommandsPlugin” still applies; these plugins do not change it.

​

Chatwoot

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

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

const chatwoot = chatwootPlugin({
  baseUrl: 'https://app.chatwoot.com',
  apiKey: process.env.CHATWOOT_TOKEN!,           // access token of a user/agent
  accountId: 1,
  inboxId: 2,                                    // an "API" inbox
  webhookToken: process.env.CHATWOOT_WEBHOOK_TOKEN!,
  labels: { handoff: ['human'], resume: ['bot'] },
})
bot.plug(chatwoot)

bot.when('talk to a human', async (ctx) => {
  await ctx.handoff({ reason: 'user asked for an agent' })
  await ctx.reply('Connecting you with an agent…')
})

// Chatwoot: Settings → Integrations → Webhooks
//   URL: https://bot.example.com/chatwoot?token=<CHATWOOT_WEBHOOK_TOKEN>
//   events: 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)
})

​

What it does

​

Chatwoot options

​

Security

• Webhook auth is mandatory: the factory throws without webhookToken, webhookSecret or insecureNoWebhookAuth: true. Keep the last one for an endpoint that is not reachable from outside.
• The token is accepted in ?token=, x-chatwoot-token or Authorization: Bearer. Chatwoot itself (checked on 4.7) does not sign account webhooks, so put the token in the webhook URL; webhookSecret is for a sender or proxy that signs as described next. The HMAC-SHA256 signature goes in x-chatwoot-signature (hex, sha256= prefix allowed) and is computed over ${timestamp}.${rawBody}, with x-chatwoot-timestamp (seconds) within webhookToleranceSec (300). A signature over the bare body never expires, so a captured request could be replayed: it is rejected unless you set webhookAllowUntimedSignature: true. Comparisons are constant-time.
• handleWebhook answers 401 without valid auth, 400 on invalid JSON and 503 before the plugin is installed; it never throws. webhookHandler only accepts POST and caps the body at 1 MiB.
• Outgoing HTTP goes through secureFetch from @botmesh/http: HTTPS only, SSRF guard, timeouts and no redirects, so api_access_token never reaches another origin. A self-hosted Chatwoot on a LAN needs http.allowPrivateHosts (and http.allowHttp for plain HTTP): an http:// baseUrl without http.allowHttp throws when the plugin is created, and a blocked private host is reported with the option to set.
• With syncMode: 'all' every conversation is copied to Chatwoot. Use syncMode: 'handoff' if only escalated chats should leave the bot.

​

Chatwoot limitations

• Inbound media is mirrored as text ([image] caption), not uploaded.
• One chat, one conversation. If the mapped conversation is gone (Chatwoot answers 404, or 422 while it is still deleting a contact), a new one is created and the message goes there.
• Marking a refused agent reply as failed uses the message status API, which Chatwoot only offers for API-channel inboxes (the kind this plugin needs anyway).
• Without cursor support in the store the mapping lives in memory (a warning is logged at install).

​

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: 'You are in the queue, position {{position}} (ticket #{{id}})',
  closedMessage: 'We are closed; we will answer when we open (ticket #{{id}})',
  assignMessage: '{{assignee}} is handling your ticket #{{id}}',
  closeMessage: 'Ticket #{{id}} closed. Thanks!',
  handoffOnAssign: true,   // bot.handoff(chatId) on assign
  resumeOnClose: true,     // bot.resume(chatId) on close
  onAssign: async (ticket) => notifyAgent(ticket),
}))

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

// Agent panel / your own API
const tickets = bot.injectTools.tickets!
await tickets.assign('1', 'ana')
await tickets.close('1', { reason: 'solved' })

​

API

​

Ticket options

​

Persistence

​

Ticket limitations

• There is no agent UI or agent identity: assignee is a free string. Build the panel on bot.injectTools.tickets and protect it yourself.
• With handoffOnAssign, only the first assignment hands the chat off: a reassignment keeps the handoff and its meta.assignee (read the ticket for the current agent), and unassigning (assignee: null) puts the ticket back in the queue but keeps the chat handed off. Call bot.resume(chatId) yourself if the bot should answer again.
• meta must be a plain JSON object (no Date, Map, class instances, functions or BigInt); anything else is rejected before the ticket is stored. A property set to undefined is dropped, as in JSON, so { email: user?.email } or { ...prev, key: undefined } (to remove a key) work; undefined inside an array is rejected.
• In shared mode every call re-reads the index and every active ticket, so its cost grows with the number of open tickets.
• list() with a filter that may include closed scans every id from 1 to the last one.
• The default storage (the store’s cursors) has no compare-and-set, so it is for one process per store namespace: two replicas over it would hand out the same id and overwrite each other’s index. For replicas, pass a storage with setIf, such as durableKvTicketStorage(kv) over the same DurableKv (Postgres, Redis, SQLite or a file) on every replica. The desk then re-reads the index on every call, claims ids with a compare-and-set and retries a lost write (maxRetries, default 20, then TicketContentionError). With reuseOpen (the default) it also claims the chat’s open ticket with a compare-and-set, so two replicas creating a ticket for the same chat at once (from a handler, the API or the manager) get the same one. A failed create never leaves an open ticket that get, list and queue cannot see.
  import { durableKvTicketStorage, ticketsPlugin } from '@botmesh/tickets'
  
  bot.plug(ticketsPlugin({ storage: durableKvTicketStorage(kv) }))
  

​

Moderation

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

const bot = new Bot({ provider })            // groupMode 'all' (the default)

bot.plug(moderationPlugin({
  provider,                                   // enables delete/kick/admins when supported
  antiSpam: { maxMessages: 5, windowMs: 10_000, action: 'warn' },
  wordFilter: { banned: ['spam', 'scam', /bit\.ly\/\w+/i], action: 'delete' },
  autoKickOnLink: true,                       // = linkFilter: { action: ['delete', 'kick'] }
  warnings: { max: 3, then: 'kick' },
  groups: {
    [staffGroupId]: false,                    // no moderation here
    [salesGroupId]: { wordFilter: { banned: ['free'] } },
  },
}))

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

​

Rules and actions

• Words are compared ignoring case and accents (ñ stays distinct from n) and as whole words; RegExps run on the raw text.
• Invisible characters (zero-width, soft hyphen, bidi controls) are dropped and compatibility forms such as fullwidth ｓｐａｍ are read as plain letters before words and links are matched, so they cannot hide a banned word or an invite. WhatsApp formatting around a link (_italic_, *bold*, ~strike~) does not hide it either.
• Recognized invites: WhatsApp (chat.whatsapp.com/…), Telegram (t.me/+…, t.me/joinchat/…) and Discord (discord.gg/…, discord.com/invite/…). allowInvites matches the exact code.
• action takes one action or several in order.
• autoKickOnLink: true is shorthand for linkFilter: { action: ['delete', 'kick'] } and only applies when no linkFilter is set (globally or in the group override).

​

Moderation limitations

• State (spam windows, warnings, mutes) lives in memory and is lost on restart.
• No provider in the monorepo exposes groups.removeParticipants / getAdmins yet, so kick degrades to mute and admin detection relies on admins / isAdmin.
• GroupAdminApi and ModerationProvider.groups are @experimental (outside semver) until @botmesh/core defines a groups capability for providers; their shape may change in a minor release.

​

Dialogflow

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

const bot = new Bot({ provider })

bot.plug(dialogflowPlugin({
  credentials: JSON.parse(process.env.GOOGLE_CREDENTIALS!), // service-account JSON
  languageCode: 'en',
  fulfillment: 'unrouted',     // reply with the agent's text when the intent has no route
}))

const df = bot.injectTools.dialogflow!

// Handler: receives the normalized result
whenDialogflowIntent(bot, df, 'order.status', (ctx, r) =>
  ctx.reply(`Looking up order ${String(r.parameters.order)}…`))

// Flow: the parameters are copied into c.state before the first step
whenDialogflowIntent(bot, df, 'book.table', flow('booking')
  .say((_ctx, c) => `Table for ${String(c.state.people)}`)
  .ask('Under what name?', 'name'))

bot.onMessage((ctx) => ctx.reply('Sorry, I did not get that'))   // unrouted messages land here

​

How it works

1. The before('message') hook calls detectIntent and stores the result for that message. ctx.tools.dialogflow.resultFor(ctx) reads it from any handler.
2. whenDialogflowIntent registers a bot.when predicate that reads that result (no second call). If the intent matches with at least minConfidence, the target runs; otherwise the message falls through to other matchers and the catch-all.
3. Not sent to Dialogflow: empty messages, interactions, commands (commandPrefix, default '/'), texts longer than maxTextLength (256 characters, the API limit), messages from a chat in handoff, messages from a user inside an active conversation (skipActiveConversation, default true) and anything filter rejects.
4. If detectIntent (or filter) fails, it is logged, onError(error, ctx) is called and the message keeps flowing. A 401 drops the cached access token and retries once with a fresh one.

​

Dialogflow options

​

Security and privacy

• Invalid credentials (code: 'INVALID_CREDENTIALS') and invalid options (code: 'INVALID_CONFIG': minConfidence outside 0–1, an unknown fulfillment or sessionScope, an empty commandPrefix, a malformed location…) throw DialogflowError synchronously at bot.plug(). The access token is fetched lazily on the first message, cached and refreshed shortly before it expires.
• The session key is hashed (SHA-256, 32 characters) before it is used as the Dialogflow session id, so chat ids and phone numbers are not sent to Google. The message text is.
• Keep the service-account JSON in a secret, never in the repo.
• Parameters (in the result and copied into c.state) skip __proto__, constructor and prototype: they come from a remote service and must not reach the prototype of the state object.
• A route target that is not a handler function, a flow() builder or a compiled flow throws a TypeError when it is registered.

​

Dialogflow limitations

• Only text is sent (no audio, no events). CX form filling lives in pages: allRequiredParamsPresent is always true there.

​

Local intent matching (NLU)

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

bot.plug(nluPlugin, {
  threshold: 0.5, // minimum confidence, 0..1
  intents: {
    greeting: ['hi', 'hello', 'good morning'],
    'order.status': ['my order {id}', 'order status', 'where is my order'],
  },
})
const nlu = bot.injectTools.nlu!

whenIntent(bot, nlu, 'greeting', (ctx) => ctx.reply('Hi! How can I help?'))
whenIntent(bot, nlu, 'order.status', async (ctx, match) => {
  const id = match.entities?.id
  await ctx.reply(id ? `Looking up order ${id}…` : 'What is your order number?')
})
// Messages no intent claimed fall through to other handlers (or the AI autoresponder).

• nluPlugin is a plugin spec: plug it as bot.plug(nluPlugin, config). It puts an IntentEngine in ctx.tools.nlu (and bot.injectTools.nlu).
• whenIntent(bot, engine, intent, handler) is a bot.when() predicate: the handler runs only when the message’s best intent is that one, above the threshold, and receives the match. It returns the unsubscribe function.
• engine.match(text) returns { intent, confidence, entities? } or null; engine.rank(text) scores every intent (useful to debug a phrase); engine.define(intent, utterances) adds phrases at runtime.
• Matching normalizes case, accents, punctuation, full-width letters and invisible characters (¡HOLA! equals hola), then scores the words in common; vowel signs of scripts such as Devanagari stay in their word. A phrase with only emoji or punctuation throws in define(): it could never match. Punctuation splits words, so an id like A-1 does not fill one slot. An exact phrase, or a phrase with {slot} placeholders that lines up with the whole message, scores 1; a slot captures one word.
• Scope: no stemming, synonyms or embeddings. Give each intent several short phrases in the words your users really type, and avoid intents that share most of their vocabulary.

​

Combining them

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

​

Next steps

• Human handoff
• Hooks
• Plugins
• AI