@tiledesk/tiledesk-server 3.0.1 → 3.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (140) hide show
  1. package/.circleci/config.yml +1 -1
  2. package/CHANGELOG.md +47 -0
  3. package/Dockerfile +3 -2
  4. package/Dockerfile-en +3 -2
  5. package/Dockerfile-jobs +3 -2
  6. package/Dockerfile-profiler +3 -2
  7. package/README.md +15 -0
  8. package/app.js +12 -1
  9. package/bin/quota-reset +68 -0
  10. package/bin/quota-restore +86 -0
  11. package/channels/chat21/chat21Handler.js +50 -34
  12. package/channels/chat21/chat21JoinTracker.js +43 -0
  13. package/config/database.js +5 -5
  14. package/config/native_mcp/native_mcp_servers.json +1 -0
  15. package/controllers/chatbot.controller.js +80 -27
  16. package/controllers/intents.controller.js +42 -0
  17. package/docs/superpowers/plans/2026-09-15-webhook-chatbot-hitl-chat21-ionic.md +468 -0
  18. package/docs/superpowers/plans/2026-09-15-webhook-chatbot-hitl-design-studio.md +1349 -0
  19. package/docs/superpowers/plans/2026-09-15-webhook-chatbot-hitl-server.md +1694 -0
  20. package/docs/superpowers/plans/2026-09-15-webhook-chatbot-hitl-tybot.md +789 -0
  21. package/docs/superpowers/plans/2026-09-29-hitl-known-limits-server.md +83 -0
  22. package/docs/superpowers/plans/2026-09-29-hitl-known-limits-tybot.md +76 -0
  23. package/docs/superpowers/plans/2026-09-29-hitl-participant-removal-chat21-ionic.md +97 -0
  24. package/docs/superpowers/plans/2026-09-29-hitl-participant-removal-design-studio.md +72 -0
  25. package/docs/superpowers/plans/2026-09-29-hitl-participant-removal-server.md +223 -0
  26. package/docs/superpowers/plans/2026-09-29-hitl-participant-removal-tybot.md +121 -0
  27. package/docs/superpowers/plans/2026-09-29-hitl-pre-branch-ports.md +65 -0
  28. package/docs/superpowers/plans/2026-09-30-flow-start-points-design-studio.md +88 -0
  29. package/docs/superpowers/plans/2026-09-30-flow-start-points-server.md +103 -0
  30. package/docs/superpowers/plans/2026-09-30-flow-start-points-tybot.md +43 -0
  31. package/docs/superpowers/plans/2026-10-01-scheduled-start-point-design-studio.md +80 -0
  32. package/docs/superpowers/plans/2026-10-01-scheduled-start-point-runtime.md +39 -0
  33. package/docs/superpowers/plans/2026-10-01-scheduled-start-point-server.md +106 -0
  34. package/docs/superpowers/specs/2026-09-15-webhook-chatbot-hitl-design.md +715 -0
  35. package/docs/superpowers/specs/2026-09-30-flow-start-points-design.md +156 -0
  36. package/docs/superpowers/specs/2026-10-01-scheduled-start-point-design.md +303 -0
  37. package/docs/superpowers/todo/2026-09-14-webhook-chatbot-shared-code-fixes.md +191 -0
  38. package/event/botEvent.js +12 -1
  39. package/event/emailEvent.js +3 -0
  40. package/event/messageEvent.js +44 -0
  41. package/jobs.js +10 -0
  42. package/jobsManager.js +19 -0
  43. package/middleware/errorHandler.js +6 -2
  44. package/models/analyticResult.js +1 -1
  45. package/models/channelConstants.js +3 -2
  46. package/models/dataTable.js +16 -0
  47. package/models/location.js +6 -12
  48. package/models/quotaUsage.js +71 -0
  49. package/models/request.js +71 -61
  50. package/models/requestSnapshot.js +12 -0
  51. package/models/routerLogger.js +1 -1
  52. package/models/webhook.js +44 -0
  53. package/package.json +9 -7
  54. package/pubmodules/emailNotification/requestNotification.js +14 -22
  55. package/pubmodules/events/test/eventRoute.js +7 -6
  56. package/pubmodules/rules/conciergeBot.js +9 -4
  57. package/routes/auth.js +1 -12
  58. package/routes/campaigns.js +0 -13
  59. package/routes/dataTable.js +23 -3
  60. package/routes/faq_kb.js +12 -1
  61. package/routes/messagesRoot.js +0 -1
  62. package/routes/quotes.js +38 -1
  63. package/routes/request.js +81 -5
  64. package/routes/users.js +0 -1
  65. package/routes/webhook.js +160 -8
  66. package/routes/webhooks.js +276 -6
  67. package/routes/widgetLoader.js +6 -3
  68. package/services/QuoteManager.js +77 -16
  69. package/services/aiService.js +1 -1
  70. package/services/chatbotService.js +55 -1
  71. package/services/dataTableService.js +436 -42
  72. package/services/departmentService.js +60 -43
  73. package/services/dolphinSchedulerClient.js +116 -0
  74. package/services/emailService.js +6 -1
  75. package/services/hitlParticipantListener.js +260 -0
  76. package/services/participantInviteService.js +302 -0
  77. package/services/participantRemoveService.js +79 -0
  78. package/services/quotaSnapshotService.js +1167 -0
  79. package/services/requestService.js +102 -144
  80. package/services/scheduledStart/dolphinBackend.js +246 -0
  81. package/services/scheduledStart/schedulerBackend.js +101 -0
  82. package/services/scheduledStart/schedulerServiceClient.js +41 -0
  83. package/services/scheduledStartPublishListener.js +186 -0
  84. package/services/scheduledStartRules.js +173 -0
  85. package/services/scheduledStartService.js +130 -0
  86. package/services/startPointCleanupListener.js +30 -0
  87. package/services/startPointService.js +158 -0
  88. package/services/testWsService.js +1 -4
  89. package/services/updateRequestSnapshotQueued.js +8 -9
  90. package/services/webhookConversationService.js +185 -0
  91. package/services/webhookSettingsValidator.js +61 -0
  92. package/template/email/checkpointReachedEmail.html +5 -0
  93. package/test/agentPromptsRoute.test.js +3 -2
  94. package/test/agentTokensQuota.js +237 -0
  95. package/test/botEventHitlFallback.js +19 -0
  96. package/test/chat21HandlerJoinWiring.js +59 -0
  97. package/test/dataTablesRoute.test.js +649 -2
  98. package/test/dateUtils.test.js +0 -3
  99. package/test/departmentService.js +8 -12
  100. package/test/{fileRoute.js → deprecated/_deprecated_fileRoute} +2 -2
  101. package/test/{kbsettingsRoute.js → deprecated/_deprecated_kbsettingsRoute} +3 -3
  102. package/test/faqRoute.js +6 -1
  103. package/test/faqkbRoute.js +14 -10
  104. package/test/faqkbV3Route.js +1 -1
  105. package/test/filepRoute.js +4 -50
  106. package/test/hitlParticipantListener.js +446 -0
  107. package/test/hitlQueueWiring.js +191 -0
  108. package/test/hitlWaitingReset.js +124 -0
  109. package/test/inviteParticipantsRoute.js +492 -0
  110. package/test/kbRoute.js +1 -1
  111. package/test/messageRoute.js +33 -21
  112. package/test/nativemcp.test.js +7 -1
  113. package/test/openaiRoute.js +2 -8
  114. package/test/publishFailLoud.test.js +414 -0
  115. package/test/quotaSnapshots.js +1044 -0
  116. package/test/removeParticipantsRoute.js +186 -0
  117. package/test/requestService.js +24 -16
  118. package/test/requestServiceRemoveParticipant.js +144 -0
  119. package/test/requestVisibility.test.js +186 -0
  120. package/test/scheduledStartFacade.js +184 -0
  121. package/test/scheduledStartHandover.js +95 -0
  122. package/test/scheduledStartPublish.js +320 -0
  123. package/test/scheduledStartRoute.js +163 -0
  124. package/test/scheduledStartRules.js +177 -0
  125. package/test/scheduledStartRun.js +299 -0
  126. package/test/scheduledStartSchedulerBackend.js +116 -0
  127. package/test/scheduledStartService.js +290 -0
  128. package/test/startPointsCleanup.js +69 -0
  129. package/test/startPointsRegression.js +169 -0
  130. package/test/startPointsRoute.js +158 -0
  131. package/test/webhookConversationRoute.js +347 -0
  132. package/test/webhookConversationService.js +261 -0
  133. package/test/webhookConversationTestUtils.js +55 -0
  134. package/utils/aiUtils.js +95 -1
  135. package/utils/dataTableUtils.js +99 -9
  136. package/utils/intentFieldNames.js +192 -0
  137. package/utils/quotaCliUtil.js +43 -0
  138. package/utils/requestVisibility.js +355 -0
  139. package/websocket/webSocketServer.js +36 -31
  140. /package/test/{imageRoute.js → deprecated/_deprecated_imageRoute} +0 -0
@@ -0,0 +1,1694 @@
1
+ # Webhook-started chatbot conversations + HITL invite — tiledesk-server Implementation Plan
2
+
3
+ > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
4
+
5
+ **Goal:** Let a webhook with `mode: 'conversation'` start a normal chatbot conversation (like the widget), and let a flow invite platform users into that conversation while the bot stays, protected from auto-close until a human answers.
6
+
7
+ **Architecture:** The public webhook route branches on `webhook.mode`: without it the existing automation path runs untouched; with `'conversation'` a new `webhookConversationService` creates a source lead + `support-group-…` request with the bot as participant and sends the system `/start` message. A new `participantInviteService` (exposed as `POST /:projectid/requests/:request_id/participants/invite`) picks agents (explicit members or one agent from a department), adds them next to the bot, marks the request `workingStatus: 'pending'` + `attributes.hitl_waiting`, and emails them. A `messageEvent` listener resets the request to `open` when an invited human answers.
8
+
9
+ **Tech Stack:** Node.js (CommonJS), Express, Mongoose, mocha + chai + chai-http, winston.
10
+
11
+ **Spec:** `docs/superpowers/specs/2026-09-15-webhook-chatbot-hitl-design.md` (sections 3, 4, 5, 9.1, 10).
12
+
13
+ ## Global Constraints
14
+
15
+ - Repo `tiledesk-server`, branch `feature/webhook-chatbot-hitl` (created from `origin/master` `5d240683`, upstream intentionally unset — never push to `master`).
16
+ - Backward compatibility (spec D11): a webhook **without** `mode` must behave exactly as today for every bot subtype. `test/webhookRoute.js` must pass **unchanged**.
17
+ - Do **not** modify `requestService.create` or `requestService.addParticipantByRequestId` (spec D9; TODO items 1–2). Work around them as specified.
18
+ - Do not use `.save()` on existing `Webhook` documents (pre-save hook never calls `next()` for non-new docs); use `findOneAndUpdate`.
19
+ - Whenever a service changes a request, emit `request.update` with a **populated** request (`lead`, `department`, `participatingBots`, `participatingAgents`, `requester.id_user`) — `pubmodules/cache/mongoose-cachegoose-fn.js:391-403` writes that object into the request cache read by `event/messageEvent.js`.
20
+ - Conversation mode value: exactly `'conversation'`. Channel name for created conversations: exactly `'webhook'`. Lead id: `'webhook_' + webhook_id`. Request id: `'support-group-' + id_project + '-' + UIDGenerator.generate()`.
21
+ - Invite response is always a non-empty JSON body (tybot `HttpUtils` treats an empty 2xx body as an error).
22
+ - `webhook.triggered` analytics payload shape is **not** changed (the consumer schema is unverified); only the request id is passed through the existing `payload.preloaded_request_id` field.
23
+ - Commit messages end with `Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>`.
24
+
25
+ ### How to run tests (every task)
26
+ Prerequisites: Redis reachable at `CACHE_REDIS_HOST`/`CACHE_REDIS_PORT` (default `localhost:6379`; the webhook rate limiter needs it), Node deps installed.
27
+
28
+ ```bash
29
+ cd /Users/nicocardone/Desktop/DEV/TILEDESK/tiledesk-server
30
+ npx mongodb-runner start # once per session (same as npm "pretest")
31
+ npx mocha <test file(s)> --exit
32
+ npx mongodb-runner stop # at the end of the session
33
+ ```
34
+
35
+ ---
36
+
37
+ ## File Structure
38
+
39
+ | File | Status | Responsibility |
40
+ |---|---|---|
41
+ | `models/webhook.js` | Modify | add `mode`, `department_id`, `source_name` fields |
42
+ | `services/webhookSettingsValidator.js` | Create | find the webhook's chatbot; validate/normalize `mode`, `block_id`, `department_id`, `source_name` |
43
+ | `routes/webhooks.js` | Modify | use the validator in `POST /`, `PUT /:chatbot_id`, `PUT /update/:webhook_id`; conversation-mode request id in `POST /preload/:webhook_id` |
44
+ | `services/webhookConversationService.js` | Create | create source lead + request + department + `/start` message |
45
+ | `routes/webhook.js` | Modify | branch prod and dev routes on `webhook.mode` |
46
+ | `services/participantInviteService.js` | Create | resolve invitees, add participants, pending marker, invite email |
47
+ | `routes/request.js` | Modify | `POST /:requestid/participants/invite` |
48
+ | `event/messageEvent.js` | Modify | reset `pending` → `open` when an invited human answers |
49
+ | `test/webhookConversationTestUtils.js` | Create | shared test helpers (`waitFor`, `setupProjectWithBot`) — not a mocha test file (no `describe`) |
50
+ | `test/webhookConversationRoute.js` | Create | HTTP tests for webhook settings + conversation start |
51
+ | `test/webhookConversationService.js` | Create | service tests for the conversation starter |
52
+ | `test/inviteParticipantsRoute.js` | Create | HTTP tests for the invite endpoint |
53
+ | `test/hitlWaitingReset.js` | Create | tests for the waiting-protection reset |
54
+
55
+ ---
56
+
57
+ ### Task 1: Webhook model fields + settings validation in webhook management routes
58
+
59
+ **Files:**
60
+ - Modify: `models/webhook.js:37-42`
61
+ - Create: `services/webhookSettingsValidator.js`
62
+ - Modify: `routes/webhooks.js` (imports at top, `POST /` `:67-93`, `POST /preload/:webhook_id` `:95-112`, `PUT /:chatbot_id` `:182-212`, `PUT /update/:webhook_id` `:214-245`)
63
+ - Create: `test/webhookConversationTestUtils.js`
64
+ - Create: `test/webhookConversationRoute.js`
65
+
66
+ **Interfaces:**
67
+ - Consumes: none.
68
+ - Produces:
69
+ - `Webhook` fields `mode?: 'conversation'`, `department_id?: string|null`, `source_name?: string`.
70
+ - `webhookSettingsValidator.CONVERSATION_MODE === 'conversation'`
71
+ - `webhookSettingsValidator.findChatbot(id_project: string, chatbot_id: string): Promise<Object|null>` (lean faq_kb, not trashed)
72
+ - `webhookSettingsValidator.validate(id_project: string, chatbot: Object, body: Object): Promise<{ok: true, fields: Object} | {ok: false, status: number, message: string}>`
73
+ - test helpers (`test/webhookConversationTestUtils.js`): `PWD`, `uniqueEmail(prefix): string`, `waitFor(fn, {timeout, interval}): Promise<any>`, `setupProjectWithBot(server, {subtype?, waitStart = true}): Promise<{email, pwd, user, project, chatbot_id, startIntent}>`.
74
+
75
+ - [ ] **Step 1: Create the shared test helpers**
76
+
77
+ Create `test/webhookConversationTestUtils.js`:
78
+
79
+ ```js
80
+ const chai = require('chai');
81
+ const chaiHttp = require('chai-http');
82
+ chai.use(chaiHttp);
83
+
84
+ const userService = require('../services/userService');
85
+ const projectService = require('../services/projectService');
86
+ const Faq = require('../models/faq');
87
+
88
+ const PWD = 'pwd';
89
+
90
+ async function waitFor(fn, { timeout = 5000, interval = 100 } = {}) {
91
+ const start = Date.now();
92
+ while (Date.now() - start < timeout) {
93
+ const value = await fn();
94
+ if (value) {
95
+ return value;
96
+ }
97
+ await new Promise((resolve) => setTimeout(resolve, interval));
98
+ }
99
+ throw new Error('waitFor timeout after ' + timeout + 'ms');
100
+ }
101
+
102
+ function uniqueEmail(prefix) {
103
+ return prefix + '-' + Date.now() + '-' + Math.floor(Math.random() * 100000) + '@email.com';
104
+ }
105
+
106
+ /**
107
+ * Creates a user, a project and a tilebot chatbot through the API.
108
+ * The blank template's intents are saved asynchronously by faqService, so the
109
+ * start intent is awaited when waitStart is true.
110
+ */
111
+ async function setupProjectWithBot(server, { subtype, waitStart = true } = {}) {
112
+ const email = uniqueEmail('test-webhook-conv');
113
+ const user = await userService.signup(email, PWD, 'Test Firstname', 'Test lastname');
114
+ const project = await projectService.create('test-webhook-conversation', user._id);
115
+
116
+ const body = { name: 'hitl-bot', type: 'tilebot', language: 'en', template: 'blank' };
117
+ if (subtype) {
118
+ body.subtype = subtype;
119
+ }
120
+ const res = await chai.request(server).post('/' + project._id + '/faq_kb').auth(email, PWD).send(body);
121
+ if (res.status !== 200) {
122
+ throw new Error('Chatbot creation failed with status ' + res.status);
123
+ }
124
+ const chatbot_id = res.body._id;
125
+
126
+ let startIntent = null;
127
+ if (waitStart) {
128
+ startIntent = await waitFor(() => Faq.findOne({ id_faq_kb: chatbot_id, intent_display_name: 'start' }).lean().exec());
129
+ }
130
+
131
+ return { email, pwd: PWD, user, project, chatbot_id, startIntent };
132
+ }
133
+
134
+ module.exports = { PWD, waitFor, uniqueEmail, setupProjectWithBot };
135
+ ```
136
+
137
+ - [ ] **Step 2: Write the failing tests for webhook settings**
138
+
139
+ Create `test/webhookConversationRoute.js`:
140
+
141
+ ```js
142
+ //During the test the env variable is set to test
143
+ process.env.NODE_ENV = 'test';
144
+ process.env.LOG_LEVEL = 'error';
145
+ process.env.BUCKET_WH_CAPACITY = 2;
146
+
147
+ const chai = require('chai');
148
+ const chaiHttp = require('chai-http');
149
+ const server = require('../app');
150
+ const expect = chai.expect;
151
+ chai.use(chaiHttp);
152
+
153
+ const departmentService = require('../services/departmentService');
154
+ const { setupProjectWithBot } = require('./webhookConversationTestUtils');
155
+
156
+ describe('WebhookConversationRoute - settings', function () {
157
+
158
+ this.timeout(20000);
159
+
160
+ it('creates a conversation webhook bound to the start block when block_id is omitted', async () => {
161
+ const { email, pwd, project, chatbot_id, startIntent } = await setupProjectWithBot(server);
162
+ const defaultDepartment = await departmentService.getDefaultDepartment(project._id);
163
+
164
+ const res = await chai.request(server)
165
+ .post('/' + project._id + '/webhooks/')
166
+ .auth(email, pwd)
167
+ .send({ chatbot_id: chatbot_id, mode: 'conversation', source_name: 'Grafana alerts', department_id: defaultDepartment.id });
168
+
169
+ expect(res).to.have.status(200);
170
+ expect(res.body.mode).to.equal('conversation');
171
+ expect(res.body.block_id).to.equal(startIntent.intent_id);
172
+ expect(res.body.source_name).to.equal('Grafana alerts');
173
+ expect(res.body.department_id).to.equal(defaultDepartment.id);
174
+ expect(res.body.webhook_id).to.have.length(32);
175
+ });
176
+
177
+ it('rejects conversation mode for a bot that is not subtype chatbot', async () => {
178
+ const { email, pwd, project, chatbot_id } = await setupProjectWithBot(server, { subtype: 'webhook', waitStart: false });
179
+
180
+ const res = await chai.request(server)
181
+ .post('/' + project._id + '/webhooks/')
182
+ .auth(email, pwd)
183
+ .send({ chatbot_id: chatbot_id, block_id: 'any-block', mode: 'conversation' });
184
+
185
+ expect(res).to.have.status(422);
186
+ expect(res.body.success).to.equal(false);
187
+ });
188
+
189
+ it('rejects an unknown department', async () => {
190
+ const { email, pwd, project, chatbot_id } = await setupProjectWithBot(server);
191
+
192
+ const res = await chai.request(server)
193
+ .post('/' + project._id + '/webhooks/')
194
+ .auth(email, pwd)
195
+ .send({ chatbot_id: chatbot_id, mode: 'conversation', department_id: '5f0000000000000000000000' });
196
+
197
+ expect(res).to.have.status(422);
198
+ });
199
+
200
+ it('returns 404 when the chatbot does not exist', async () => {
201
+ const { email, pwd, project } = await setupProjectWithBot(server, { waitStart: false });
202
+
203
+ const resUnknown = await chai.request(server)
204
+ .post('/' + project._id + '/webhooks/')
205
+ .auth(email, pwd)
206
+ .send({ chatbot_id: '5f0000000000000000000000', block_id: 'any-block' });
207
+ expect(resUnknown).to.have.status(404);
208
+
209
+ const resInvalid = await chai.request(server)
210
+ .post('/' + project._id + '/webhooks/')
211
+ .auth(email, pwd)
212
+ .send({ chatbot_id: 'not-an-object-id', block_id: 'any-block' });
213
+ expect(resInvalid).to.have.status(404);
214
+ });
215
+
216
+ it('switches an existing automation webhook to conversation mode with PUT', async () => {
217
+ const { email, pwd, project, chatbot_id, startIntent } = await setupProjectWithBot(server);
218
+
219
+ const created = await chai.request(server)
220
+ .post('/' + project._id + '/webhooks/')
221
+ .auth(email, pwd)
222
+ .send({ chatbot_id: chatbot_id, block_id: 'legacy-block' });
223
+ expect(created).to.have.status(200);
224
+ expect(created.body.mode).to.equal(undefined);
225
+
226
+ const res = await chai.request(server)
227
+ .put('/' + project._id + '/webhooks/' + chatbot_id)
228
+ .auth(email, pwd)
229
+ .send({ mode: 'conversation', enabled: true, source_name: 'On-call alerts' });
230
+
231
+ expect(res).to.have.status(200);
232
+ expect(res.body.mode).to.equal('conversation');
233
+ expect(res.body.block_id).to.equal(startIntent.intent_id);
234
+ expect(res.body.source_name).to.equal('On-call alerts');
235
+ expect(res.body.enabled).to.equal(true);
236
+ });
237
+
238
+ it('updates settings by webhook_id with PUT /update/:webhook_id', async () => {
239
+ const { email, pwd, project, chatbot_id } = await setupProjectWithBot(server);
240
+
241
+ const created = await chai.request(server)
242
+ .post('/' + project._id + '/webhooks/')
243
+ .auth(email, pwd)
244
+ .send({ chatbot_id: chatbot_id, mode: 'conversation' });
245
+ expect(created).to.have.status(200);
246
+
247
+ const res = await chai.request(server)
248
+ .put('/' + project._id + '/webhooks/update/' + created.body.webhook_id)
249
+ .auth(email, pwd)
250
+ .send({ source_name: 'Renamed source', enabled: false });
251
+
252
+ expect(res).to.have.status(200);
253
+ expect(res.body.source_name).to.equal('Renamed source');
254
+ expect(res.body.enabled).to.equal(false);
255
+ expect(res.body.mode).to.equal('conversation');
256
+ });
257
+
258
+ it('preload returns a support-group request id for conversation webhooks', async () => {
259
+ const { email, pwd, project, chatbot_id } = await setupProjectWithBot(server);
260
+
261
+ const created = await chai.request(server)
262
+ .post('/' + project._id + '/webhooks/')
263
+ .auth(email, pwd)
264
+ .send({ chatbot_id: chatbot_id, mode: 'conversation' });
265
+
266
+ const res = await chai.request(server)
267
+ .post('/' + project._id + '/webhooks/preload/' + created.body.webhook_id)
268
+ .auth(email, pwd);
269
+
270
+ expect(res).to.have.status(200);
271
+ expect(res.body.request_id.startsWith('support-group-' + project._id + '-')).to.equal(true);
272
+ expect(res.body.request_id.split('-')).to.have.length(4);
273
+ });
274
+ });
275
+ ```
276
+
277
+ - [ ] **Step 3: Run the tests to verify they fail**
278
+
279
+ Run: `npx mocha test/webhookConversationRoute.js --exit`
280
+ Expected: FAIL — e.g. `expected undefined to equal 'conversation'` (mode not persisted), `expected 500 to equal 422`, `expected 200 to equal 404`.
281
+
282
+ - [ ] **Step 4: Add the model fields**
283
+
284
+ In `models/webhook.js`, replace the `enabled` field block (lines 37-41) with:
285
+
286
+ ```js
287
+ enabled: {
288
+ type: Boolean,
289
+ required: true,
290
+ default: true
291
+ },
292
+ mode: {
293
+ type: String,
294
+ enum: ['conversation'],
295
+ required: false
296
+ },
297
+ department_id: {
298
+ type: String,
299
+ required: false
300
+ },
301
+ source_name: {
302
+ type: String,
303
+ required: false
304
+ }
305
+ ```
306
+
307
+ - [ ] **Step 5: Create the settings validator**
308
+
309
+ Create `services/webhookSettingsValidator.js`:
310
+
311
+ ```js
312
+ const mongoose = require('mongoose');
313
+ const Faq_kb = require('../models/faq_kb');
314
+ const Faq = require('../models/faq');
315
+ const Department = require('../models/department');
316
+ const chatbotTypes = require('../models/chatbotTypes');
317
+
318
+ const CONVERSATION_MODE = 'conversation';
319
+ const START_INTENT_NAME = 'start';
320
+
321
+ class WebhookSettingsValidator {
322
+
323
+ constructor() {
324
+ this.CONVERSATION_MODE = CONVERSATION_MODE;
325
+ }
326
+
327
+ async findChatbot(id_project, chatbot_id) {
328
+ if (!chatbot_id || !mongoose.Types.ObjectId.isValid(chatbot_id)) {
329
+ return null;
330
+ }
331
+ return Faq_kb.findOne({ _id: chatbot_id, id_project: id_project, trashed: { $in: [null, false] } }).lean().exec();
332
+ }
333
+
334
+ /**
335
+ * Validates the conversation-related fields of a webhook create/update body.
336
+ * Only the keys present in body are returned in fields.
337
+ * @returns {Promise<{ok: true, fields: Object} | {ok: false, status: number, message: string}>}
338
+ */
339
+ async validate(id_project, chatbot, body) {
340
+ const fields = {};
341
+
342
+ if (body.hasOwnProperty('mode')) {
343
+ if (body.mode !== CONVERSATION_MODE) {
344
+ return { ok: false, status: 422, message: "Invalid webhook mode " + body.mode };
345
+ }
346
+ const subtype = chatbot.subtype || chatbotTypes.CHATBOT;
347
+ if (subtype !== chatbotTypes.CHATBOT) {
348
+ return { ok: false, status: 422, message: "Conversation mode requires a chatbot with subtype " + chatbotTypes.CHATBOT };
349
+ }
350
+ fields.mode = CONVERSATION_MODE;
351
+
352
+ if (body.block_id) {
353
+ fields.block_id = body.block_id;
354
+ } else {
355
+ const startIntent = await Faq.findOne({ id_faq_kb: chatbot._id.toString(), intent_display_name: START_INTENT_NAME }).lean().exec();
356
+ if (!startIntent) {
357
+ return { ok: false, status: 422, message: "Start block not found for chatbot " + chatbot._id };
358
+ }
359
+ fields.block_id = startIntent.intent_id;
360
+ }
361
+ } else if (body.block_id) {
362
+ fields.block_id = body.block_id;
363
+ }
364
+
365
+ if (body.hasOwnProperty('department_id')) {
366
+ if (body.department_id) {
367
+ if (!mongoose.Types.ObjectId.isValid(body.department_id)) {
368
+ return { ok: false, status: 422, message: "Department not found with id " + body.department_id };
369
+ }
370
+ const department = await Department.findOne({ _id: body.department_id, id_project: id_project }).lean().exec();
371
+ if (!department) {
372
+ return { ok: false, status: 422, message: "Department not found with id " + body.department_id };
373
+ }
374
+ fields.department_id = body.department_id;
375
+ } else {
376
+ fields.department_id = null;
377
+ }
378
+ }
379
+
380
+ if (body.hasOwnProperty('source_name')) {
381
+ fields.source_name = body.source_name;
382
+ }
383
+
384
+ return { ok: true, fields: fields };
385
+ }
386
+ }
387
+
388
+ module.exports = new WebhookSettingsValidator();
389
+ ```
390
+
391
+ - [ ] **Step 6: Use the validator in `routes/webhooks.js`**
392
+
393
+ Add after `var ObjectId = require('mongoose').Types.ObjectId;` (line 8):
394
+
395
+ ```js
396
+ const webhookSettingsValidator = require('../services/webhookSettingsValidator');
397
+ const UIDGenerator = require('../utils/UIDGenerator');
398
+
399
+ const SETTINGS_KEYS = ['mode', 'block_id', 'department_id', 'source_name'];
400
+
401
+ function hasSettings(body) {
402
+ return SETTINGS_KEYS.some((key) => body.hasOwnProperty(key));
403
+ }
404
+
405
+ /**
406
+ * Loads the chatbot and validates the settings of body.
407
+ * @returns {Promise<{ok: true, fields: Object} | {ok: false, status: number, message: string}>}
408
+ */
409
+ async function validateSettings(id_project, chatbot_id, body) {
410
+ const chatbot = await webhookSettingsValidator.findChatbot(id_project, chatbot_id);
411
+ if (!chatbot) {
412
+ return { ok: false, status: 404, message: "Chatbot not found with id " + chatbot_id };
413
+ }
414
+ return webhookSettingsValidator.validate(id_project, chatbot, body);
415
+ }
416
+ ```
417
+
418
+ Replace the whole `router.post('/', ...)` handler (lines 67-93) with:
419
+
420
+ ```js
421
+ router.post('/', async (req, res) => {
422
+
423
+ let id_project = req.projectid;
424
+ let chatbot_id = req.body.chatbot_id || req.body.id_faq_kb;
425
+
426
+ let validation;
427
+ try {
428
+ validation = await validateSettings(id_project, chatbot_id, req.body);
429
+ } catch (err) {
430
+ winston.error("Error validating new webhook ", err);
431
+ return res.status(500).send({ success: false, error: "Error validating webhook for chatbot " + chatbot_id });
432
+ }
433
+
434
+ if (!validation.ok) {
435
+ winston.verbose("Invalid webhook for chatbot " + chatbot_id + ": " + validation.message);
436
+ return res.status(validation.status).send({ success: false, error: validation.message });
437
+ }
438
+
439
+ let webhook = new Webhook(Object.assign({
440
+ id_project: id_project,
441
+ name: "webhook-" + this.webhook_id,
442
+ chatbot_id: chatbot_id,
443
+ block_id: req.body.block_id,
444
+ copilot: req.body.copilot,
445
+ async: req.body.async
446
+ }, validation.fields));
447
+
448
+ webhook.save((err, savedWebhook) => {
449
+ if (err) {
450
+ if (err.code === 11000) {
451
+ winston.verbose("Webhook already exists for chatbot " + webhook.chatbot_id);
452
+ return res.status(403).send({ success: false, message: "Webhook already exists for chatbot " + webhook.chatbot_id });
453
+ }
454
+ winston.error("Error saving new webhook ", err);
455
+ return res.status(500).send({ success: false, error: err });
456
+ }
457
+
458
+ res.status(200).send(savedWebhook);
459
+ })
460
+
461
+ })
462
+ ```
463
+
464
+ Replace the body of `router.post('/preload/:webhook_id', ...)` (lines 95-112) with:
465
+
466
+ ```js
467
+ router.post('/preload/:webhook_id', async (req, res) => {
468
+
469
+ let id_project = req.projectid;
470
+ let webhook_id = req.params.webhook_id;
471
+ let redis_client = req.app.get('redis_client');
472
+
473
+ let webhook;
474
+ try {
475
+ webhook = await Webhook.findOne({ id_project: id_project, webhook_id: webhook_id }).lean().exec();
476
+ } catch (err) {
477
+ winston.error("Error finding webhook for preload ", err);
478
+ return res.status(500).send({ success: false, message: "Unable to start development webhook" });
479
+ }
480
+
481
+ let request_id;
482
+ if (webhook && webhook.mode === webhookSettingsValidator.CONVERSATION_MODE) {
483
+ request_id = "support-group-" + id_project + "-" + UIDGenerator.generate();
484
+ } else {
485
+ request_id = "automation-request-" + id_project + "-" + new ObjectId() + "-" + webhook_id;
486
+ }
487
+
488
+ try {
489
+ let key = "logs:webhook:" + id_project + ":" + webhook_id;
490
+ let value = JSON.stringify({ request_id: request_id });
491
+ redis_client.set(key, value, { EX: 900 });
492
+ res.status(200).send({ success: true, message: "Webhook preloaded successfully", request_id: request_id });
493
+ } catch(err) {
494
+ winston.error("Error adding key in cache ", err);
495
+ res.status(500).send({ success: false, message: "Unable to start development webhook" })
496
+ }
497
+
498
+ })
499
+ ```
500
+
501
+ In `router.put("/:chatbot_id", ...)`, insert immediately before `let updatedWebhook = await Webhook.findOneAndUpdate(` (line 201):
502
+
503
+ ```js
504
+ if (hasSettings(req.body)) {
505
+ let validation;
506
+ try {
507
+ validation = await validateSettings(id_project, chatbot_id, req.body);
508
+ } catch (err) {
509
+ winston.error("Error validating webhook update ", err);
510
+ return res.status(500).send({ success: false, error: "Error validating webhook for chatbot " + chatbot_id });
511
+ }
512
+ if (!validation.ok) {
513
+ return res.status(validation.status).send({ success: false, error: validation.message });
514
+ }
515
+ Object.assign(update, validation.fields);
516
+ }
517
+ ```
518
+
519
+ In `router.put('/update/:webhook_id', ...)`, insert immediately before `let updatedWebhook = await Webhook.findOneAndUpdate(` (line 233):
520
+
521
+ ```js
522
+ if (hasSettings(req.body)) {
523
+ let existing;
524
+ try {
525
+ existing = await Webhook.findOne({ id_project: id_project, webhook_id: webhook_id }).lean().exec();
526
+ } catch (err) {
527
+ winston.error("Error finding webhook for update ", err);
528
+ return res.status(500).send({ success: false, error: "Error updating webhook with id " + webhook_id });
529
+ }
530
+ if (!existing) {
531
+ return res.status(404).send({ success: false, error: "Webhook not found with id " + webhook_id });
532
+ }
533
+ let validation;
534
+ try {
535
+ validation = await validateSettings(id_project, existing.chatbot_id, req.body);
536
+ } catch (err) {
537
+ winston.error("Error validating webhook update ", err);
538
+ return res.status(500).send({ success: false, error: "Error validating webhook with id " + webhook_id });
539
+ }
540
+ if (!validation.ok) {
541
+ return res.status(validation.status).send({ success: false, error: validation.message });
542
+ }
543
+ Object.assign(update, validation.fields);
544
+ }
545
+ ```
546
+
547
+ - [ ] **Step 7: Run the new tests to verify they pass**
548
+
549
+ Run: `npx mocha test/webhookConversationRoute.js --exit`
550
+ Expected: PASS (7 passing).
551
+
552
+ - [ ] **Step 8: Run the existing webhook tests (backward compatibility)**
553
+
554
+ Run: `npx mocha test/webhookRoute.js --exit`
555
+ Expected: PASS, same number of passing tests as on `master` (run `git stash; npx mocha test/webhookRoute.js --exit; git stash pop` first if you need the baseline count).
556
+
557
+ - [ ] **Step 9: Commit**
558
+
559
+ ```bash
560
+ git add models/webhook.js services/webhookSettingsValidator.js routes/webhooks.js test/webhookConversationTestUtils.js test/webhookConversationRoute.js
561
+ git commit -m "feat(webhooks): add conversation mode, department and source settings
562
+
563
+ Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>"
564
+ ```
565
+
566
+ ---
567
+
568
+ ### Task 2: Conversation starter service
569
+
570
+ **Files:**
571
+ - Create: `services/webhookConversationService.js`
572
+ - Create: `test/webhookConversationService.js`
573
+
574
+ **Interfaces:**
575
+ - Consumes: `Webhook` fields from Task 1 (`mode`, `department_id`, `source_name`).
576
+ - Produces:
577
+ - `webhookConversationService.SOURCE_CHANNEL === 'webhook'`
578
+ - `webhookConversationService.newRequestId(id_project: string): string`
579
+ - `webhookConversationService.start(webhook: Object, chatbot: Object, payload: Object, options?: {dev?: boolean, request_id?: string}): Promise<{request_id: string, request: Object}>`
580
+ - Errors thrown carry `err.status` (`422` misconfigured department, `403` quota exceeded); other errors have no `status`.
581
+
582
+ - [ ] **Step 1: Write the failing service tests**
583
+
584
+ Create `test/webhookConversationService.js`:
585
+
586
+ ```js
587
+ //During the test the env variable is set to test
588
+ process.env.NODE_ENV = 'test';
589
+ process.env.LOG_LEVEL = 'error';
590
+
591
+ const chai = require('chai');
592
+ const expect = chai.expect;
593
+ const config = require('../config/database');
594
+ const mongoose = require('mongoose');
595
+
596
+ mongoose.connect(config.databasetest);
597
+ require('../services/mongoose-cache-fn')(mongoose);
598
+
599
+ const userService = require('../services/userService');
600
+ const projectService = require('../services/projectService');
601
+ const faqService = require('../services/faqService');
602
+ const departmentService = require('../services/departmentService');
603
+ const webhookConversationService = require('../services/webhookConversationService');
604
+ const Request = require('../models/request');
605
+ const Message = require('../models/message');
606
+ const Lead = require('../models/lead');
607
+ const { Webhook } = require('../models/webhook');
608
+ const { waitFor, uniqueEmail, PWD } = require('./webhookConversationTestUtils');
609
+
610
+ async function setup(webhookFields = {}) {
611
+ const user = await userService.signup(uniqueEmail('test-webhook-conv-service'), PWD, 'Test', 'User');
612
+ const project = await projectService.create('test-webhook-conversation-service', user._id);
613
+ const chatbot = await faqService.create(project._id, user._id, { name: 'hitl-bot', type: 'tilebot', language: 'en', template: 'blank' });
614
+ const webhook = await new Webhook(Object.assign({
615
+ id_project: project._id.toString(),
616
+ chatbot_id: chatbot._id.toString(),
617
+ block_id: 'start-intent-id',
618
+ mode: 'conversation',
619
+ source_name: 'Grafana alerts'
620
+ }, webhookFields)).save();
621
+ return { user, project, chatbot, webhook };
622
+ }
623
+
624
+ describe('WebhookConversationService', function () {
625
+
626
+ this.timeout(20000);
627
+
628
+ it('creates a lead, a bot-assigned request in the default department and a /start message', async () => {
629
+ const { project, chatbot, webhook } = await setup();
630
+ const defaultDepartment = await departmentService.getDefaultDepartment(project._id);
631
+
632
+ const result = await webhookConversationService.start(webhook, chatbot, { alert: 'KubePodCrashLooping', webhook_http_method: 'POST' }, {});
633
+
634
+ expect(result.request_id.startsWith('support-group-' + project._id + '-')).to.equal(true);
635
+
636
+ const request = await Request.findOne({ request_id: result.request_id, id_project: project._id.toString() }).lean().exec();
637
+ expect(request.participants).to.deep.equal(['bot_' + chatbot._id.toString()]);
638
+ expect(request.participantsBots).to.deep.equal([chatbot._id.toString()]);
639
+ expect(request.hasBot).to.equal(true);
640
+ expect(request.status).to.equal(200);
641
+ expect(request.channel.name).to.equal('webhook');
642
+ expect(request.department.toString()).to.equal(defaultDepartment.id);
643
+ expect(request.first_text).to.equal('/start');
644
+ expect(request.attributes.webhook_id).to.equal(webhook.webhook_id);
645
+ expect(request.attributes.payload.alert).to.equal('KubePodCrashLooping');
646
+ expect(request.draft).to.not.equal(true);
647
+
648
+ const lead = await Lead.findById(request.lead).lean().exec();
649
+ expect(lead.lead_id).to.equal('webhook_' + webhook.webhook_id);
650
+ expect(lead.fullname).to.equal('Grafana alerts');
651
+
652
+ const startMessage = await waitFor(() => Message.findOne({ recipient: result.request_id, text: '/start' }).lean().exec());
653
+ expect(startMessage.sender).to.equal('system');
654
+ expect(startMessage.attributes.subtype).to.equal('info');
655
+ });
656
+
657
+ it('uses the configured department and the given request id in dev mode', async () => {
658
+ const { user, project } = await setup();
659
+ const department = await departmentService.create('SRE', project._id, 'assigned', user._id);
660
+ const chatbotInProject = await faqService.create(project._id, user._id, { name: 'hitl-bot-2', type: 'tilebot', language: 'en', template: 'blank' });
661
+ const devWebhook = await new Webhook({
662
+ id_project: project._id.toString(),
663
+ chatbot_id: chatbotInProject._id.toString(),
664
+ block_id: 'start-intent-id',
665
+ mode: 'conversation',
666
+ department_id: department._id.toString()
667
+ }).save();
668
+ const request_id = webhookConversationService.newRequestId(project._id.toString());
669
+
670
+ const result = await webhookConversationService.start(devWebhook, chatbotInProject, { alert: 'dev' }, { dev: true, request_id: request_id });
671
+
672
+ expect(result.request_id).to.equal(request_id);
673
+ const request = await Request.findOne({ request_id: request_id }).lean().exec();
674
+ expect(request.department.toString()).to.equal(department._id.toString());
675
+ expect(request.draft).to.equal(true);
676
+ expect(request.attributes.sourcePage).to.include('&td_draft=true');
677
+ });
678
+
679
+ it('rejects with status 422 when the configured department does not exist', async () => {
680
+ const { chatbot, webhook } = await setup({ department_id: '5f0000000000000000000000' });
681
+
682
+ let error;
683
+ try {
684
+ await webhookConversationService.start(webhook, chatbot, {}, {});
685
+ } catch (err) {
686
+ error = err;
687
+ }
688
+ expect(error).to.exist;
689
+ expect(error.status).to.equal(422);
690
+ });
691
+ });
692
+ ```
693
+
694
+ - [ ] **Step 2: Run the tests to verify they fail**
695
+
696
+ Run: `npx mocha test/webhookConversationService.js --exit`
697
+ Expected: FAIL with `Cannot find module '../services/webhookConversationService'`.
698
+
699
+ - [ ] **Step 3: Implement the service**
700
+
701
+ Create `services/webhookConversationService.js`:
702
+
703
+ ```js
704
+ const Request = require('../models/request');
705
+ const Department = require('../models/department');
706
+ const leadService = require('./leadService');
707
+ const requestService = require('./requestService');
708
+ const messageService = require('./messageService');
709
+ const requestEvent = require('../event/requestEvent');
710
+ const UIDGenerator = require('../utils/UIDGenerator');
711
+ const winston = require('../config/winston');
712
+
713
+ const SOURCE_CHANNEL = 'webhook';
714
+ const START_TEXT = '/start';
715
+
716
+ class WebhookConversationError extends Error {
717
+ constructor(status, message) {
718
+ super(message);
719
+ this.status = status;
720
+ }
721
+ }
722
+
723
+ class WebhookConversationService {
724
+
725
+ constructor() {
726
+ this.SOURCE_CHANNEL = SOURCE_CHANNEL;
727
+ }
728
+
729
+ newRequestId(id_project) {
730
+ return 'support-group-' + id_project + '-' + UIDGenerator.generate();
731
+ }
732
+
733
+ async resolveDepartment(id_project, department_id) {
734
+ let department;
735
+ if (department_id) {
736
+ department = await Department.findOne({ _id: department_id, id_project: id_project }).lean().exec();
737
+ if (!department) {
738
+ throw new WebhookConversationError(422, 'Webhook misconfigured: department not found with id ' + department_id);
739
+ }
740
+ return department;
741
+ }
742
+ department = await Department.findOne({ id_project: id_project, default: true }).lean().exec();
743
+ if (!department) {
744
+ throw new WebhookConversationError(422, 'Webhook misconfigured: default department not found for project ' + id_project);
745
+ }
746
+ return department;
747
+ }
748
+
749
+ /**
750
+ * Starts a chatbot conversation the same way the widget does: request with the bot as
751
+ * participant, then the system /start info message that botEvent forwards to the bot.
752
+ */
753
+ async start(webhook, chatbot, payload, options = {}) {
754
+ const id_project = webhook.id_project.toString();
755
+ const request_id = options.request_id || this.newRequestId(id_project);
756
+ const department = await this.resolveDepartment(id_project, webhook.department_id);
757
+
758
+ const lead = await leadService.createIfNotExistsWithLeadId(
759
+ 'webhook_' + webhook.webhook_id,
760
+ webhook.source_name || webhook.name || 'Webhook',
761
+ undefined,
762
+ id_project,
763
+ 'system',
764
+ { webhook_id: webhook.webhook_id }
765
+ );
766
+
767
+ const attributes = { webhook_id: webhook.webhook_id, payload: payload || {} };
768
+ let sourcePage;
769
+ if (options.dev === true) {
770
+ // BotSubscriptionNotifier matches "&td_draft=true", requestService.create matches "td_draft=true"
771
+ sourcePage = 'webhook://' + webhook.webhook_id + '?dev=true&td_draft=true';
772
+ attributes.sourcePage = sourcePage;
773
+ }
774
+
775
+ try {
776
+ await requestService.create({
777
+ request_id: request_id,
778
+ lead_id: lead._id,
779
+ lead: lead,
780
+ id_project: id_project,
781
+ first_text: START_TEXT,
782
+ departmentid: department._id.toString(),
783
+ participants: ['bot_' + chatbot._id.toString()],
784
+ channel: { name: SOURCE_CHANNEL },
785
+ sourcePage: sourcePage,
786
+ preflight: false,
787
+ createdBy: 'system',
788
+ attributes: attributes
789
+ });
790
+ } catch (err) {
791
+ if (err && err.message && err.message.startsWith('Requests limits reached')) {
792
+ throw new WebhookConversationError(403, 'Requests quota exceeded for project ' + id_project);
793
+ }
794
+ throw err;
795
+ }
796
+
797
+ // requestService.create drops the department when participants are passed (see TODO item 1)
798
+ const updatedRequest = await Request.findOneAndUpdate(
799
+ { request_id: request_id, id_project: id_project },
800
+ { $set: { department: department._id, 'snapshot.department': department } },
801
+ { new: true }
802
+ )
803
+ .populate('lead')
804
+ .populate('department')
805
+ .populate('participatingBots')
806
+ .populate('participatingAgents')
807
+ .populate({ path: 'requester', populate: { path: 'id_user' } })
808
+ .exec();
809
+ requestEvent.emit('request.update', updatedRequest);
810
+
811
+ await messageService.send('system', 'Bot', request_id, START_TEXT, id_project, null, { subtype: 'info', updateconversation: false });
812
+
813
+ winston.verbose('(WebhookConversationService) conversation ' + request_id + ' started from webhook ' + webhook.webhook_id);
814
+ return { request_id: request_id, request: updatedRequest };
815
+ }
816
+ }
817
+
818
+ const webhookConversationService = new WebhookConversationService();
819
+ webhookConversationService.WebhookConversationError = WebhookConversationError;
820
+
821
+ module.exports = webhookConversationService;
822
+ ```
823
+
824
+ - [ ] **Step 4: Run the tests to verify they pass**
825
+
826
+ Run: `npx mocha test/webhookConversationService.js --exit`
827
+ Expected: PASS (3 passing).
828
+
829
+ - [ ] **Step 5: Commit**
830
+
831
+ ```bash
832
+ git add services/webhookConversationService.js test/webhookConversationService.js
833
+ git commit -m "feat(webhooks): start chatbot conversations from conversation-mode webhooks
834
+
835
+ Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>"
836
+ ```
837
+
838
+ ---
839
+
840
+ ### Task 3: Branch the public webhook routes on `mode`
841
+
842
+ **Files:**
843
+ - Modify: `routes/webhook.js` (imports `:1-13`, `router.all('/:webhook_id')` `:263-322`, `router.all('/:webhook_id/dev')` `:324-357`)
844
+ - Modify: `test/webhookConversationRoute.js` (append a `describe`)
845
+
846
+ **Interfaces:**
847
+ - Consumes: `webhookSettingsValidator.CONVERSATION_MODE`, `webhookSettingsValidator.findChatbot` (Task 1); `webhookConversationService.start` (Task 2).
848
+ - Produces: `POST|GET /webhook/:webhook_id` and `/webhook/:webhook_id/dev` return `202 {success: true, request_id}` for `mode: 'conversation'`; errors `{success: false, error}` with 404/422/429/403/500.
849
+
850
+ - [ ] **Step 1: Write the failing route tests**
851
+
852
+ Append to `test/webhookConversationRoute.js`:
853
+
854
+ ```js
855
+ const Request = require('../models/request');
856
+ const Message = require('../models/message');
857
+ const { waitFor } = require('./webhookConversationTestUtils');
858
+
859
+ async function createWebhook(ctx, body) {
860
+ const res = await chai.request(server)
861
+ .post('/' + ctx.project._id + '/webhooks/')
862
+ .auth(ctx.email, ctx.pwd)
863
+ .send(Object.assign({ chatbot_id: ctx.chatbot_id }, body));
864
+ expect(res).to.have.status(200);
865
+ return res.body;
866
+ }
867
+
868
+ describe('WebhookConversationRoute - run', function () {
869
+
870
+ this.timeout(20000);
871
+
872
+ it('keeps the automation behaviour for a chatbot webhook without mode', async () => {
873
+ const ctx = await setupProjectWithBot(server);
874
+ const webhook = await createWebhook(ctx, { block_id: 'legacy-block' });
875
+
876
+ const res = await chai.request(server).post('/webhook/' + webhook.webhook_id).send({ alert: 'legacy' });
877
+
878
+ expect(res).to.have.status(200);
879
+ expect(res.body.success).to.equal(true);
880
+ expect(res.body.message).to.equal('Webhook disabled in test mode');
881
+ });
882
+
883
+ it('starts a conversation for a conversation-mode webhook', async () => {
884
+ const ctx = await setupProjectWithBot(server);
885
+ const webhook = await createWebhook(ctx, { mode: 'conversation', source_name: 'Grafana alerts' });
886
+
887
+ const res = await chai.request(server)
888
+ .post('/webhook/' + webhook.webhook_id + '?env=prod')
889
+ .send({ alert: 'KubePodCrashLooping' });
890
+
891
+ expect(res).to.have.status(202);
892
+ expect(res.body.success).to.equal(true);
893
+ expect(res.body.request_id.startsWith('support-group-' + ctx.project._id + '-')).to.equal(true);
894
+
895
+ const request = await Request.findOne({ request_id: res.body.request_id }).lean().exec();
896
+ expect(request.participants).to.deep.equal(['bot_' + ctx.chatbot_id]);
897
+ expect(request.channel.name).to.equal('webhook');
898
+ expect(request.attributes.payload.alert).to.equal('KubePodCrashLooping');
899
+ expect(request.attributes.payload.webhook_http_method).to.equal('POST');
900
+ expect(request.attributes.payload.webhook_query_params.env).to.equal('prod');
901
+
902
+ await waitFor(() => Message.findOne({ recipient: res.body.request_id, text: '/start' }).lean().exec());
903
+ });
904
+
905
+ it('returns 422 for a disabled conversation webhook', async () => {
906
+ const ctx = await setupProjectWithBot(server);
907
+ const webhook = await createWebhook(ctx, { mode: 'conversation' });
908
+ await chai.request(server).put('/' + ctx.project._id + '/webhooks/' + ctx.chatbot_id).auth(ctx.email, ctx.pwd).send({ enabled: false });
909
+
910
+ const res = await chai.request(server).post('/webhook/' + webhook.webhook_id).send({});
911
+ expect(res).to.have.status(422);
912
+ });
913
+
914
+ it('returns 422 on the dev route without preload', async () => {
915
+ const ctx = await setupProjectWithBot(server);
916
+ const webhook = await createWebhook(ctx, { mode: 'conversation' });
917
+
918
+ const res = await chai.request(server).post('/webhook/' + webhook.webhook_id + '/dev').send({});
919
+ expect(res).to.have.status(422);
920
+ expect(res.body.code).to.equal(13001);
921
+ });
922
+
923
+ it('starts a draft conversation with the preloaded request id on the dev route', async () => {
924
+ const ctx = await setupProjectWithBot(server);
925
+ const webhook = await createWebhook(ctx, { mode: 'conversation' });
926
+ const preload = await chai.request(server).post('/' + ctx.project._id + '/webhooks/preload/' + webhook.webhook_id).auth(ctx.email, ctx.pwd);
927
+ expect(preload).to.have.status(200);
928
+ await new Promise((resolve) => setTimeout(resolve, 200)); // preload writes to Redis without awaiting
929
+
930
+ const res = await chai.request(server).post('/webhook/' + webhook.webhook_id + '/dev').send({ alert: 'dev' });
931
+
932
+ expect(res).to.have.status(202);
933
+ expect(res.body.request_id).to.equal(preload.body.request_id);
934
+ const request = await Request.findOne({ request_id: res.body.request_id }).lean().exec();
935
+ expect(request.draft).to.equal(true);
936
+ });
937
+
938
+ it('returns 422 on the dev route for a disabled conversation webhook', async () => {
939
+ const ctx = await setupProjectWithBot(server);
940
+ const webhook = await createWebhook(ctx, { mode: 'conversation' });
941
+ await chai.request(server).post('/' + ctx.project._id + '/webhooks/preload/' + webhook.webhook_id).auth(ctx.email, ctx.pwd);
942
+ await chai.request(server).put('/' + ctx.project._id + '/webhooks/' + ctx.chatbot_id).auth(ctx.email, ctx.pwd).send({ enabled: false });
943
+
944
+ const res = await chai.request(server).post('/webhook/' + webhook.webhook_id + '/dev').send({});
945
+ expect(res).to.have.status(422);
946
+ });
947
+
948
+ it('rate limits conversation webhooks', async () => {
949
+ const ctx = await setupProjectWithBot(server);
950
+ const webhook = await createWebhook(ctx, { mode: 'conversation' });
951
+
952
+ // The bucket capacity is read once when the app is first required (2 if this file loads
953
+ // the app, 10 by default if another test file loaded it first): call until limited.
954
+ const statuses = [];
955
+ for (let i = 0; i < 15 && !statuses.includes(429); i++) {
956
+ const res = await chai.request(server).post('/webhook/' + webhook.webhook_id).send({ i: i });
957
+ statuses.push(res.status);
958
+ }
959
+ expect(statuses).to.include(429);
960
+ expect(statuses.filter((s) => s !== 429 && s !== 202)).to.deep.equal([]);
961
+ });
962
+ });
963
+ ```
964
+
965
+ - [ ] **Step 2: Run the tests to verify they fail**
966
+
967
+ Run: `npx mocha test/webhookConversationRoute.js --exit`
968
+ Expected: the 7 settings tests PASS; in "run", `keeps the automation behaviour…` PASSES and the others FAIL (e.g. `expected 200 to equal 202`, `expected 200 to equal 422`).
969
+
970
+ - [ ] **Step 3: Implement the branch in `routes/webhook.js`**
971
+
972
+ Add after `const default_embedding = require('../config/kb/embedding');` (line 13):
973
+
974
+ ```js
975
+ const webhookSettingsValidator = require('../services/webhookSettingsValidator');
976
+ const webhookConversationService = require('../services/webhookConversationService');
977
+
978
+ async function startConversation(res, webhook, payload, options) {
979
+ let chatbot;
980
+ try {
981
+ chatbot = await webhookSettingsValidator.findChatbot(webhook.id_project, webhook.chatbot_id);
982
+ } catch (err) {
983
+ winston.error("Error finding chatbot for webhook conversation ", err);
984
+ return res.status(500).send({ success: false, error: "Error finding chatbot " + webhook.chatbot_id });
985
+ }
986
+ if (!chatbot) {
987
+ return res.status(404).send({ success: false, error: "Chatbot not found with id " + webhook.chatbot_id });
988
+ }
989
+
990
+ try {
991
+ const result = await webhookConversationService.start(webhook, chatbot, payload, options);
992
+ if (options.dev !== true) {
993
+ webhookEvent.emit("webhook.triggered", { webhook: webhook, payload: { preloaded_request_id: result.request_id } });
994
+ }
995
+ return res.status(202).send({ success: true, request_id: result.request_id });
996
+ } catch (err) {
997
+ if (!err.status) {
998
+ winston.error("Error starting webhook conversation for webhook " + webhook.webhook_id, err);
999
+ }
1000
+ return res.status(err.status || 500).send({ success: false, error: err.status ? err.message : "Error starting conversation" });
1001
+ }
1002
+ }
1003
+ ```
1004
+
1005
+ In `router.all('/:webhook_id', ...)`, insert immediately before `payload.request_id = "automation-request-" + webhook.id_project + "-" + new ObjectId() + "-" + webhook_id;`:
1006
+
1007
+ ```js
1008
+ if (webhook.mode === webhookSettingsValidator.CONVERSATION_MODE) {
1009
+ return startConversation(res, webhook, payload, { dev: false });
1010
+ }
1011
+ ```
1012
+
1013
+ In `router.all('/:webhook_id/dev', ...)`, insert immediately before `let redis_client = req.app.get('redis_client');`:
1014
+
1015
+ ```js
1016
+ if (webhook.mode === webhookSettingsValidator.CONVERSATION_MODE) {
1017
+ if (!webhook.enabled) {
1018
+ return res.status(422).send({ success: false, error: "Webhook " + webhook_id + " is currently turned off" });
1019
+ }
1020
+
1021
+ const rate_manager = req.app.get("rate_manager");
1022
+ const allowed = await rate_manager.canExecute(webhook.id_project, null, 'webhook');
1023
+ if (!allowed) {
1024
+ return res.status(429).send({ message: "Rate limit exceeded" });
1025
+ }
1026
+
1027
+ let preloaded;
1028
+ try {
1029
+ preloaded = await req.app.get('redis_client').get("logs:webhook:" + webhook.id_project + ":" + webhook.webhook_id);
1030
+ } catch (err) {
1031
+ winston.error("Error reading preloaded development request ", err);
1032
+ return res.status(500).send({ success: false, error: "Unable to read development request" });
1033
+ }
1034
+ if (!preloaded) {
1035
+ return res.status(422).send({ success: false, message: "Development webhook is currently turned off", code: errorCodes.WEBHOOK.ERRORS.NO_PRELOADED_DEV_REQUEST });
1036
+ }
1037
+
1038
+ return startConversation(res, webhook, payload, { dev: true, request_id: JSON.parse(preloaded).request_id });
1039
+ }
1040
+ ```
1041
+
1042
+ - [ ] **Step 4: Run the tests to verify they pass**
1043
+
1044
+ Run: `npx mocha test/webhookConversationRoute.js --exit`
1045
+ Expected: PASS (14 passing).
1046
+
1047
+ - [ ] **Step 5: Run backward-compatibility suites**
1048
+
1049
+ Run: `npx mocha test/webhookRoute.js test/webhookConversationService.js --exit`
1050
+ Expected: PASS.
1051
+
1052
+ - [ ] **Step 6: Commit**
1053
+
1054
+ ```bash
1055
+ git add routes/webhook.js test/webhookConversationRoute.js
1056
+ git commit -m "feat(webhooks): start conversations from conversation-mode webhook calls
1057
+
1058
+ Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>"
1059
+ ```
1060
+
1061
+ ---
1062
+
1063
+ ### Task 4: Invite participants service and endpoint
1064
+
1065
+ **Files:**
1066
+ - Create: `services/participantInviteService.js`
1067
+ - Modify: `routes/request.js` (imports near line 36; new route right after `router.post('/:requestid/participants', ...)` which ends at `:423`)
1068
+ - Create: `test/inviteParticipantsRoute.js`
1069
+
1070
+ **Interfaces:**
1071
+ - Consumes: none from earlier tasks (works on any request).
1072
+ - Produces:
1073
+ - `participantInviteService.invite(id_project: string, request_id: string, {department_id?: string, members?: string[]}): Promise<{request_id: string, department_id: string|null, invited: Array<{id_user: string, fullname: string, already_participant: boolean}>, reason?: 'no_available_agents'}>`; errors carry `err.status` (404, 409, 422).
1074
+ - Request marker after a successful invite: `workingStatus === 'pending'`, `attributes.hitl_waiting === true`.
1075
+ - HTTP `POST /:projectid/requests/:requestid/participants/invite` → `200` with the object above, or `{success: false, error}` with the error status.
1076
+
1077
+ - [ ] **Step 1: Write the failing tests**
1078
+
1079
+ Create `test/inviteParticipantsRoute.js`:
1080
+
1081
+ ```js
1082
+ //During the test the env variable is set to test
1083
+ process.env.NODE_ENV = 'test';
1084
+ process.env.LOG_LEVEL = 'error';
1085
+
1086
+ const chai = require('chai');
1087
+ const chaiHttp = require('chai-http');
1088
+ const server = require('../app');
1089
+ const expect = chai.expect;
1090
+ chai.use(chaiHttp);
1091
+
1092
+ const userService = require('../services/userService');
1093
+ const projectService = require('../services/projectService');
1094
+ const departmentService = require('../services/departmentService');
1095
+ const faqService = require('../services/faqService');
1096
+ const requestService = require('../services/requestService');
1097
+ const Project_user = require('../models/project_user');
1098
+ const Request = require('../models/request');
1099
+ const RoleConstants = require('../models/roleConstants');
1100
+ const { uniqueEmail, PWD } = require('./webhookConversationTestUtils');
1101
+
1102
+ async function addAgent(project, owner, { available = true } = {}) {
1103
+ const email = uniqueEmail('test-invite-agent');
1104
+ const agent = await userService.signup(email, PWD, 'Agent', 'Smith');
1105
+ await new Project_user({
1106
+ id_project: project._id.toString(),
1107
+ id_user: agent._id.toString(),
1108
+ role: RoleConstants.AGENT,
1109
+ roleType: RoleConstants.TYPE_AGENTS,
1110
+ user_available: available,
1111
+ createdBy: owner._id.toString(),
1112
+ updatedBy: owner._id.toString()
1113
+ }).save();
1114
+ return { agent, email };
1115
+ }
1116
+
1117
+ async function setup({ ownerAvailable = true } = {}) {
1118
+ const ownerEmail = uniqueEmail('test-invite-owner');
1119
+ const owner = await userService.signup(ownerEmail, PWD, 'Owner', 'User');
1120
+ const project = await projectService.create('test-invite-participants', owner._id);
1121
+ if (!ownerAvailable) {
1122
+ await Project_user.findOneAndUpdate({ id_project: project._id, id_user: owner._id }, { user_available: false }).exec();
1123
+ }
1124
+ const chatbot = await faqService.create(project._id, owner._id, { name: 'hitl-bot', type: 'tilebot', language: 'en', template: 'blank' });
1125
+ const request = await requestService.create({
1126
+ request_id: 'support-group-' + project._id + '-' + Date.now() + Math.floor(Math.random() * 1000),
1127
+ id_project: project._id.toString(),
1128
+ first_text: '/start',
1129
+ participants: ['bot_' + chatbot._id.toString()],
1130
+ channel: { name: 'webhook' },
1131
+ preflight: false,
1132
+ createdBy: 'system'
1133
+ });
1134
+ return { owner, ownerEmail, project, chatbot, request };
1135
+ }
1136
+
1137
+ function invite(ctx, body, auth) {
1138
+ const req = chai.request(server).post('/' + ctx.project._id + '/requests/' + ctx.request.request_id + '/participants/invite');
1139
+ if (auth && auth.jwt) {
1140
+ req.set('Authorization', 'JWT ' + auth.jwt);
1141
+ } else {
1142
+ req.auth(ctx.ownerEmail, PWD);
1143
+ }
1144
+ return req.send(body);
1145
+ }
1146
+
1147
+ describe('InviteParticipantsRoute', function () {
1148
+
1149
+ this.timeout(20000);
1150
+
1151
+ it('invites all named members that are active agents and keeps the bot', async () => {
1152
+ const ctx = await setup();
1153
+ const a1 = await addAgent(ctx.project, ctx.owner);
1154
+ const a2 = await addAgent(ctx.project, ctx.owner, { available: false });
1155
+
1156
+ const res = await invite(ctx, { members: [a1.email, a2.agent._id.toString(), 'unknown@email.com'] });
1157
+
1158
+ expect(res).to.have.status(200);
1159
+ expect(res.body.invited.map((i) => i.id_user).sort()).to.deep.equal([a1.agent._id.toString(), a2.agent._id.toString()].sort());
1160
+ expect(res.body.invited.every((i) => i.already_participant === false)).to.equal(true);
1161
+
1162
+ const request = await Request.findOne({ request_id: ctx.request.request_id }).lean().exec();
1163
+ expect(request.participants).to.include('bot_' + ctx.chatbot._id.toString());
1164
+ expect(request.participants).to.include(a1.agent._id.toString());
1165
+ expect(request.participants).to.include(a2.agent._id.toString());
1166
+ expect(request.workingStatus).to.equal('pending');
1167
+ expect(request.attributes.hitl_waiting).to.equal(true);
1168
+ });
1169
+
1170
+ it('falls back to the department when no member resolves', async () => {
1171
+ const ctx = await setup();
1172
+
1173
+ const res = await invite(ctx, { members: ['nobody@email.com'] });
1174
+
1175
+ expect(res).to.have.status(200);
1176
+ expect(res.body.invited).to.have.length(1);
1177
+ expect(res.body.invited[0].id_user).to.equal(ctx.owner._id.toString());
1178
+ });
1179
+
1180
+ it('invites exactly one available agent from a pooled department', async () => {
1181
+ const ctx = await setup({ ownerAvailable: false });
1182
+ const pooled = await departmentService.create('SRE pooled', ctx.project._id, 'pooled', ctx.owner._id);
1183
+ const a1 = await addAgent(ctx.project, ctx.owner);
1184
+ const a2 = await addAgent(ctx.project, ctx.owner);
1185
+
1186
+ const res = await invite(ctx, { department_id: pooled._id.toString() });
1187
+
1188
+ expect(res).to.have.status(200);
1189
+ expect(res.body.invited).to.have.length(1);
1190
+ expect([a1.agent._id.toString(), a2.agent._id.toString()]).to.include(res.body.invited[0].id_user);
1191
+ expect(res.body.department_id).to.equal(pooled._id.toString());
1192
+ });
1193
+
1194
+ it('invites the operator selected by an assigned department', async () => {
1195
+ const ctx = await setup();
1196
+
1197
+ const res = await invite(ctx, {});
1198
+
1199
+ expect(res).to.have.status(200);
1200
+ expect(res.body.invited).to.have.length(1);
1201
+ expect(res.body.invited[0].id_user).to.equal(ctx.owner._id.toString());
1202
+ });
1203
+
1204
+ it('returns an empty invite list with a reason when nobody is available', async () => {
1205
+ const ctx = await setup({ ownerAvailable: false });
1206
+
1207
+ const res = await invite(ctx, {});
1208
+
1209
+ expect(res).to.have.status(200);
1210
+ expect(res.body.invited).to.deep.equal([]);
1211
+ expect(res.body.reason).to.equal('no_available_agents');
1212
+ const request = await Request.findOne({ request_id: ctx.request.request_id }).lean().exec();
1213
+ expect(request.workingStatus).to.not.equal('pending');
1214
+ });
1215
+
1216
+ it('reports members that are already participants', async () => {
1217
+ const ctx = await setup();
1218
+ const a1 = await addAgent(ctx.project, ctx.owner);
1219
+ await invite(ctx, { members: [a1.email] });
1220
+
1221
+ const res = await invite(ctx, { members: [a1.email] });
1222
+
1223
+ expect(res).to.have.status(200);
1224
+ expect(res.body.invited).to.have.length(1);
1225
+ expect(res.body.invited[0].already_participant).to.equal(true);
1226
+ });
1227
+
1228
+ it('returns 409 for a closed request and 404 for an unknown request', async () => {
1229
+ const ctx = await setup();
1230
+ await Request.updateOne({ request_id: ctx.request.request_id }, { $set: { status: 1000 } }).exec();
1231
+
1232
+ const closed = await invite(ctx, {});
1233
+ expect(closed).to.have.status(409);
1234
+
1235
+ const unknown = await chai.request(server)
1236
+ .post('/' + ctx.project._id + '/requests/support-group-unknown/participants/invite')
1237
+ .auth(ctx.ownerEmail, PWD)
1238
+ .send({});
1239
+ expect(unknown).to.have.status(404);
1240
+ });
1241
+
1242
+ it('accepts the bot token of the same project and rejects a bot token of another project', async () => {
1243
+ const ctx = await setup();
1244
+ const other = await setup();
1245
+
1246
+ const ownJwt = await chai.request(server).get('/' + ctx.project._id + '/faq_kb/' + ctx.chatbot._id + '/jwt').auth(ctx.ownerEmail, PWD);
1247
+ const otherJwt = await chai.request(server).get('/' + other.project._id + '/faq_kb/' + other.chatbot._id + '/jwt').auth(other.ownerEmail, PWD);
1248
+
1249
+ const allowed = await invite(ctx, {}, { jwt: ownJwt.body.jwt });
1250
+ expect(allowed).to.have.status(200);
1251
+
1252
+ const denied = await invite(ctx, {}, { jwt: otherJwt.body.jwt });
1253
+ expect(denied).to.have.status(403);
1254
+ });
1255
+ });
1256
+ ```
1257
+
1258
+ - [ ] **Step 2: Run the tests to verify they fail**
1259
+
1260
+ Run: `npx mocha test/inviteParticipantsRoute.js --exit`
1261
+ Expected: FAIL — requests to `/participants/invite` return 404 (route not found).
1262
+
1263
+ - [ ] **Step 3: Implement the service**
1264
+
1265
+ Create `services/participantInviteService.js`:
1266
+
1267
+ ```js
1268
+ const mongoose = require('mongoose');
1269
+ const Request = require('../models/request');
1270
+ const Project = require('../models/project');
1271
+ const Project_user = require('../models/project_user');
1272
+ const User = require('../models/user');
1273
+ const Department = require('../models/department');
1274
+ const RequestConstants = require('../models/requestConstants');
1275
+ const RoleConstants = require('../models/roleConstants');
1276
+ const requestService = require('./requestService');
1277
+ const departmentService = require('./departmentService');
1278
+ const emailService = require('./emailService');
1279
+ const requestEvent = require('../event/requestEvent');
1280
+ const winston = require('../config/winston');
1281
+
1282
+ const PENDING = 'pending';
1283
+
1284
+ class InviteError extends Error {
1285
+ constructor(status, message) {
1286
+ super(message);
1287
+ this.status = status;
1288
+ }
1289
+ }
1290
+
1291
+ function toId(value) {
1292
+ return value && value.toString();
1293
+ }
1294
+
1295
+ class ParticipantInviteService {
1296
+
1297
+ async invite(id_project, request_id, { department_id, members } = {}) {
1298
+ const request = await Request.findOne({ request_id: request_id, id_project: id_project }).exec();
1299
+ if (!request) {
1300
+ throw new InviteError(404, 'Request not found with id ' + request_id);
1301
+ }
1302
+ if (request.status === RequestConstants.CLOSED) {
1303
+ throw new InviteError(409, 'Request ' + request_id + ' is closed');
1304
+ }
1305
+
1306
+ const participants = (request.participants || []).map(toId);
1307
+ let invitees = await this.resolveMembers(id_project, members);
1308
+ let resolvedDepartmentId = null;
1309
+
1310
+ if (invitees.length === 0) {
1311
+ const department = await this.resolveDepartment(id_project, department_id || toId(request.department));
1312
+ resolvedDepartmentId = toId(department._id);
1313
+ invitees = await this.pickFromDepartment(id_project, department, request, participants);
1314
+ }
1315
+
1316
+ if (invitees.length === 0) {
1317
+ return { request_id: request_id, department_id: resolvedDepartmentId, invited: [], reason: 'no_available_agents' };
1318
+ }
1319
+
1320
+ const invited = [];
1321
+ const newlyAdded = [];
1322
+ for (const id_user of invitees) {
1323
+ const already_participant = participants.includes(id_user);
1324
+ if (!already_participant) {
1325
+ await requestService.addParticipantByRequestId(request_id, id_project, id_user);
1326
+ newlyAdded.push(id_user);
1327
+ }
1328
+ invited.push({ id_user: id_user, fullname: await this.fullnameOf(id_user), already_participant: already_participant });
1329
+ }
1330
+
1331
+ const updatedRequest = await this.markWaiting(request_id, id_project);
1332
+ this.notifyInvited(id_project, updatedRequest, newlyAdded);
1333
+
1334
+ return { request_id: request_id, department_id: resolvedDepartmentId, invited: invited };
1335
+ }
1336
+
1337
+ /** Resolves ids or emails to active agent-type project users of the project. */
1338
+ async resolveMembers(id_project, members) {
1339
+ if (!Array.isArray(members) || members.length === 0) {
1340
+ return [];
1341
+ }
1342
+ const ids = [];
1343
+ for (const member of members) {
1344
+ if (!member || typeof member !== 'string') {
1345
+ continue;
1346
+ }
1347
+ let id_user = null;
1348
+ if (mongoose.Types.ObjectId.isValid(member)) {
1349
+ id_user = member;
1350
+ } else {
1351
+ const user = await User.findOne({ email: member.trim().toLowerCase(), status: 100 }).lean().exec();
1352
+ id_user = user ? toId(user._id) : null;
1353
+ }
1354
+ if (!id_user) {
1355
+ continue;
1356
+ }
1357
+ const project_user = await Project_user.findOne({ id_project: id_project, id_user: id_user, roleType: RoleConstants.TYPE_AGENTS, status: 'active' }).lean().exec();
1358
+ if (project_user && !ids.includes(id_user)) {
1359
+ ids.push(id_user);
1360
+ }
1361
+ }
1362
+ return ids;
1363
+ }
1364
+
1365
+ async resolveDepartment(id_project, department_id) {
1366
+ let department;
1367
+ if (department_id) {
1368
+ if (!mongoose.Types.ObjectId.isValid(department_id)) {
1369
+ throw new InviteError(422, 'Department not found with id ' + department_id);
1370
+ }
1371
+ department = await Department.findOne({ _id: department_id, id_project: id_project }).lean().exec();
1372
+ if (!department) {
1373
+ throw new InviteError(422, 'Department not found with id ' + department_id);
1374
+ }
1375
+ return department;
1376
+ }
1377
+ department = await Department.findOne({ id_project: id_project, default: true }).lean().exec();
1378
+ if (!department) {
1379
+ throw new InviteError(422, 'Default department not found for project ' + id_project);
1380
+ }
1381
+ return department;
1382
+ }
1383
+
1384
+ /** One agent: the operator selected by assigned routing, or one random available agent for pooled routing. */
1385
+ async pickFromDepartment(id_project, department, request, participants) {
1386
+ const result = await departmentService.getOperators(toId(department._id), id_project, true, undefined, { request: request });
1387
+
1388
+ const operators = (result.operators || []).map((op) => toId(op.id_user)).filter(Boolean);
1389
+ const freeOperators = operators.filter((id_user) => !participants.includes(id_user));
1390
+ if (freeOperators.length > 0) {
1391
+ return [freeOperators[0]];
1392
+ }
1393
+ if (operators.length > 0) {
1394
+ // the selected operator is already in the conversation: count it as invited
1395
+ return [operators[0]];
1396
+ }
1397
+
1398
+ const available = (result.available_agents || []).filter((pu) => !participants.includes(toId(pu.id_user)));
1399
+ const picked = departmentService.getRandomAvailableOperator(available);
1400
+ return (picked || []).map((op) => toId(op.id_user));
1401
+ }
1402
+
1403
+ async fullnameOf(id_user) {
1404
+ const user = await User.findById(id_user).lean().exec();
1405
+ if (!user) {
1406
+ return '';
1407
+ }
1408
+ return ((user.firstname || '') + ' ' + (user.lastname || '')).trim();
1409
+ }
1410
+
1411
+ async markWaiting(request_id, id_project) {
1412
+ const updatedRequest = await Request.findOneAndUpdate(
1413
+ { request_id: request_id, id_project: id_project },
1414
+ { $set: { workingStatus: PENDING, 'attributes.hitl_waiting': true } },
1415
+ { new: true }
1416
+ )
1417
+ .populate('lead')
1418
+ .populate('department')
1419
+ .populate('participatingBots')
1420
+ .populate('participatingAgents')
1421
+ .populate({ path: 'requester', populate: { path: 'id_user' } })
1422
+ .exec();
1423
+ requestEvent.emit('request.workingStatus.update', { request: updatedRequest });
1424
+ requestEvent.emit('request.update', updatedRequest);
1425
+ return updatedRequest;
1426
+ }
1427
+
1428
+ /** Same opt-outs as requestNotification.sendAgentEmail (assigned branch). Fire and forget. */
1429
+ notifyInvited(id_project, request, userIds) {
1430
+ if (!userIds || userIds.length === 0) {
1431
+ return;
1432
+ }
1433
+ setImmediate(async () => {
1434
+ try {
1435
+ const project = await Project.findOne({ _id: id_project, status: 100 }).select('+settings').exec();
1436
+ if (!project) {
1437
+ return;
1438
+ }
1439
+ const conversationSettings = project.settings && project.settings.email && project.settings.email.notification && project.settings.email.notification.conversation;
1440
+ if (conversationSettings && (conversationSettings.blocked === true || conversationSettings.assigned === false)) {
1441
+ return;
1442
+ }
1443
+ for (const id_user of userIds) {
1444
+ const project_user = await Project_user.findOne({ id_user: id_user, id_project: id_project, status: 'active' }).lean().exec();
1445
+ const userSettings = project_user && project_user.settings && project_user.settings.email && project_user.settings.email.notification && project_user.settings.email.notification.conversation;
1446
+ if (!project_user || (userSettings && userSettings.assigned && userSettings.assigned.toyou === false)) {
1447
+ continue;
1448
+ }
1449
+ const user = await User.findOne({ _id: id_user, status: 100 }).lean().exec();
1450
+ if (user) {
1451
+ emailService.sendNewAssignedRequestNotification(user.email, request, project);
1452
+ }
1453
+ }
1454
+ } catch (err) {
1455
+ winston.error('(ParticipantInviteService) error sending invite emails', err);
1456
+ }
1457
+ });
1458
+ }
1459
+ }
1460
+
1461
+ const participantInviteService = new ParticipantInviteService();
1462
+ participantInviteService.InviteError = InviteError;
1463
+
1464
+ module.exports = participantInviteService;
1465
+ ```
1466
+
1467
+ - [ ] **Step 4: Add the route**
1468
+
1469
+ In `routes/request.js`, add after `const faq_kb = require('../models/faq_kb');` (line 36):
1470
+
1471
+ ```js
1472
+ const participantInviteService = require('../services/participantInviteService');
1473
+ ```
1474
+
1475
+ Insert right after the `router.post('/:requestid/participants', ...)` handler (after its closing `});` at line 423):
1476
+
1477
+ ```js
1478
+ router.post('/:requestid/participants/invite', async (req, res) => {
1479
+
1480
+ const body = req.body || {};
1481
+ let members = body.members;
1482
+ if (members !== undefined && !Array.isArray(members)) {
1483
+ return res.status(422).send({ success: false, error: "members must be an array" });
1484
+ }
1485
+
1486
+ try {
1487
+ const result = await participantInviteService.invite(req.projectid, req.params.requestid, {
1488
+ department_id: body.department_id,
1489
+ members: members
1490
+ });
1491
+ return res.status(200).send(result);
1492
+ } catch (err) {
1493
+ if (!err.status) {
1494
+ winston.error("Error inviting participants to request " + req.params.requestid, err);
1495
+ }
1496
+ return res.status(err.status || 500).send({ success: false, error: err.status ? err.message : "Error inviting participants" });
1497
+ }
1498
+ });
1499
+ ```
1500
+
1501
+ - [ ] **Step 5: Run the tests to verify they pass**
1502
+
1503
+ Run: `npx mocha test/inviteParticipantsRoute.js --exit`
1504
+ Expected: PASS (8 passing).
1505
+
1506
+ - [ ] **Step 6: Run the request suites for regressions**
1507
+
1508
+ Run: `npx mocha test/requestRoute.js test/requestService.js --exit`
1509
+ Expected: PASS (same results as on `master`).
1510
+
1511
+ - [ ] **Step 7: Commit**
1512
+
1513
+ ```bash
1514
+ git add services/participantInviteService.js routes/request.js test/inviteParticipantsRoute.js
1515
+ git commit -m "feat(requests): invite platform users into a conversation while the bot stays
1516
+
1517
+ Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>"
1518
+ ```
1519
+
1520
+ ---
1521
+
1522
+ ### Task 5: Reset the waiting protection when an invited human answers
1523
+
1524
+ **Files:**
1525
+ - Modify: `event/messageEvent.js` (add a listener after the existing `message.create.from.requester` listener, which ends at `:203`)
1526
+ - Create: `test/hitlWaitingReset.js`
1527
+
1528
+ **Interfaces:**
1529
+ - Consumes: request marker from Task 4 (`workingStatus: 'pending'`, `attributes.hitl_waiting: true`); `participantInviteService.invite` (Task 4) in tests.
1530
+ - Produces: on `message.create`, a waiting request goes back to `workingStatus: 'open'` and loses `attributes.hitl_waiting` when the sender is in `participantsAgents` and the message is not an info message (or is an info message carrying `attributes.action`).
1531
+
1532
+ - [ ] **Step 1: Write the failing tests**
1533
+
1534
+ Create `test/hitlWaitingReset.js`:
1535
+
1536
+ ```js
1537
+ //During the test the env variable is set to test
1538
+ process.env.NODE_ENV = 'test';
1539
+ process.env.LOG_LEVEL = 'error';
1540
+
1541
+ const chai = require('chai');
1542
+ const expect = chai.expect;
1543
+ const config = require('../config/database');
1544
+ const mongoose = require('mongoose');
1545
+
1546
+ mongoose.connect(config.databasetest);
1547
+ require('../services/mongoose-cache-fn')(mongoose);
1548
+
1549
+ const userService = require('../services/userService');
1550
+ const projectService = require('../services/projectService');
1551
+ const faqService = require('../services/faqService');
1552
+ const requestService = require('../services/requestService');
1553
+ const messageService = require('../services/messageService');
1554
+ const participantInviteService = require('../services/participantInviteService');
1555
+ const Request = require('../models/request');
1556
+ const { uniqueEmail, PWD } = require('./webhookConversationTestUtils');
1557
+
1558
+ async function waitingConversation() {
1559
+ const owner = await userService.signup(uniqueEmail('test-hitl-reset'), PWD, 'Owner', 'User');
1560
+ const project = await projectService.create('test-hitl-reset', owner._id);
1561
+ const chatbot = await faqService.create(project._id, owner._id, { name: 'hitl-bot', type: 'tilebot', language: 'en', template: 'blank' });
1562
+ const request_id = 'support-group-' + project._id + '-' + Date.now() + Math.floor(Math.random() * 1000);
1563
+ await requestService.create({
1564
+ request_id: request_id,
1565
+ id_project: project._id.toString(),
1566
+ first_text: '/start',
1567
+ participants: ['bot_' + chatbot._id.toString()],
1568
+ channel: { name: 'webhook' },
1569
+ preflight: false,
1570
+ createdBy: 'system'
1571
+ });
1572
+ await participantInviteService.invite(project._id.toString(), request_id, { members: [owner._id.toString()] });
1573
+ return { owner, project, chatbot, request_id };
1574
+ }
1575
+
1576
+ async function statusAfter(request_id, ms = 700) {
1577
+ await new Promise((resolve) => setTimeout(resolve, ms));
1578
+ return Request.findOne({ request_id: request_id }).lean().exec();
1579
+ }
1580
+
1581
+ describe('HITL waiting reset', function () {
1582
+
1583
+ this.timeout(20000);
1584
+
1585
+ it('reopens the conversation when the invited human writes', async () => {
1586
+ const ctx = await waitingConversation();
1587
+
1588
+ await messageService.send(ctx.owner._id.toString(), 'Owner User', ctx.request_id, 'Approve', ctx.project._id.toString(), ctx.owner._id.toString(), {});
1589
+
1590
+ const request = await statusAfter(ctx.request_id);
1591
+ expect(request.workingStatus).to.equal('open');
1592
+ expect(request.attributes.hitl_waiting).to.equal(undefined);
1593
+ });
1594
+
1595
+ it('reopens the conversation on an info message carrying an action (button click)', async () => {
1596
+ const ctx = await waitingConversation();
1597
+
1598
+ await messageService.send(ctx.owner._id.toString(), 'Owner User', ctx.request_id, 'Approve', ctx.project._id.toString(), ctx.owner._id.toString(), { subtype: 'info', action: 'approve_block' });
1599
+
1600
+ const request = await statusAfter(ctx.request_id);
1601
+ expect(request.workingStatus).to.equal('open');
1602
+ });
1603
+
1604
+ it('stays pending for bot messages and plain info messages', async () => {
1605
+ const ctx = await waitingConversation();
1606
+
1607
+ await messageService.send('bot_' + ctx.chatbot._id.toString(), 'hitl-bot', ctx.request_id, 'Restart checkout-api?', ctx.project._id.toString(), 'system', {});
1608
+ await messageService.send(ctx.owner._id.toString(), 'Owner User', ctx.request_id, 'Owner joined', ctx.project._id.toString(), 'system', { subtype: 'info' });
1609
+
1610
+ const request = await statusAfter(ctx.request_id);
1611
+ expect(request.workingStatus).to.equal('pending');
1612
+ expect(request.attributes.hitl_waiting).to.equal(true);
1613
+ });
1614
+ });
1615
+ ```
1616
+
1617
+ - [ ] **Step 2: Run the tests to verify they fail**
1618
+
1619
+ Run: `npx mocha test/hitlWaitingReset.js --exit`
1620
+ Expected: the first two tests FAIL with `expected 'pending' to equal 'open'`; the third PASSES.
1621
+
1622
+ - [ ] **Step 3: Implement the listener**
1623
+
1624
+ In `event/messageEvent.js`, insert right after the closing `});` of the `messageEvent.on('message.create.from.requester', ...)` listener (line 203):
1625
+
1626
+ ```js
1627
+ // HITL: when an invited human participant answers a conversation that is waiting for them,
1628
+ // reopen it so the normal auto-close rules apply again (the requester rule above does not
1629
+ // fire because the requester of webhook conversations is a source lead that never writes).
1630
+ messageEvent.on('message.create', function (messageJson) {
1631
+ var request = messageJson.request;
1632
+ if (!request || !request.attributes || request.attributes.hitl_waiting !== true) return;
1633
+
1634
+ var agents = (request.participantsAgents || []).map(function (id) { return id && id.toString(); });
1635
+ if (agents.indexOf(messageJson.sender) === -1) return;
1636
+
1637
+ var attributes = messageJson.attributes || {};
1638
+ if (attributes.subtype === 'info' && !attributes.action) return;
1639
+
1640
+ Request.findOneAndUpdate(
1641
+ { request_id: request.request_id, id_project: request.id_project, 'attributes.hitl_waiting': true },
1642
+ { $set: { workingStatus: 'open' }, $unset: { 'attributes.hitl_waiting': 1 } },
1643
+ { new: true },
1644
+ function (err, updatedRequest) {
1645
+ if (err) {
1646
+ winston.error("Error resetting HITL waiting status to open", err);
1647
+ return;
1648
+ }
1649
+ if (updatedRequest) {
1650
+ winston.debug("HITL request workingStatus set to open", { request_id: request.request_id });
1651
+ requestEvent.emit('request.workingStatus.update', { request: updatedRequest });
1652
+ requestEvent.emit('request.update', updatedRequest);
1653
+ }
1654
+ }
1655
+ );
1656
+ });
1657
+ ```
1658
+
1659
+ - [ ] **Step 4: Run the tests to verify they pass**
1660
+
1661
+ Run: `npx mocha test/hitlWaitingReset.js --exit`
1662
+ Expected: PASS (3 passing).
1663
+
1664
+ - [ ] **Step 5: Commit**
1665
+
1666
+ ```bash
1667
+ git add event/messageEvent.js test/hitlWaitingReset.js
1668
+ git commit -m "feat(requests): reopen HITL-waiting conversations when the invited human answers
1669
+
1670
+ Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>"
1671
+ ```
1672
+
1673
+ ---
1674
+
1675
+ ### Task 6: Full regression run
1676
+
1677
+ **Files:** none (verification only).
1678
+
1679
+ - [ ] **Step 1: Run all new and related suites together**
1680
+
1681
+ Run:
1682
+ ```bash
1683
+ npx mocha test/webhookRoute.js test/webhookConversationRoute.js test/webhookConversationService.js test/inviteParticipantsRoute.js test/hitlWaitingReset.js test/requestRoute.js test/requestService.js test/messageRoute.js test/departmentService.js test/hasRole.js --exit
1684
+ ```
1685
+ Expected: PASS. Any failure in a pre-existing suite must be compared against the same command on `origin/master` (in a separate worktree) before being attributed to this branch.
1686
+
1687
+ - [ ] **Step 2: Run the full test suite**
1688
+
1689
+ Run: `npm test`
1690
+ Expected: same pass/fail set as `origin/master` plus the new passing tests. Record any pre-existing failures in the PR description instead of fixing them here.
1691
+
1692
+ - [ ] **Step 3: Review the branch diff**
1693
+
1694
+ Run: `git diff origin/master --stat` and confirm only the files listed in "File Structure" (plus the docs committed earlier) changed.