{"record":{"id":"d9a4a734045e3607","repo":"RocketChat/Rocket.Chat","slug":"username-required","errorCode":null,"errorMessage":"username-required","messagePattern":"username-required","errorType":"http","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"apps/meteor/server/api/webhooks.ts","lineNumber":86,"sourceCode":"\t\t\t\turls: [options.target_url],\n\t\t\t\tname: options.name,\n\t\t\t\tchannel: options.data.channel_name,\n\t\t\t\ttriggerWords: options.data.trigger_words,\n\t\t\t\ttype: 'webhook-outgoing',\n\t\t\t\tevent: 'sendMessage',\n\t\t\t\ttoken: Random.id(24),\n\t\t\t\tscriptEnabled: false,\n\t\t\t\tscript: '',\n\t\t\t\tenabled: true,\n\t\t\t\t_id: Random.id(),\n\t\t\t\t_updatedAt: new Date(),\n\t\t\t});\n\t\tcase 'newMessageToUser':\n\t\t\tif (options.data?.username?.indexOf('@') === -1) {\n\t\t\t\toptions.data.username = `@${options.data.username}`;\n\t\t\t}\n\t\t\tif (!options.data?.username) {\n\t\t\t\tthrow new Error('username-required');\n\t\t\t}\n\n\t\t\treturn addOutgoingIntegration(user._id, {\n\t\t\t\tusername: 'rocket.cat',\n\t\t\t\turls: [options.target_url],\n\t\t\t\tname: options.name,\n\t\t\t\tchannel: options.data.username,\n\t\t\t\ttriggerWords: options.data.trigger_words,\n\t\t\t\t_id: '',\n\t\t\t\ttype: 'webhook-outgoing',\n\t\t\t\ttoken: '',\n\t\t\t\tscriptEnabled: false,\n\t\t\t\tscript: '',\n\t\t\t\tenabled: false,\n\t\t\t\t_updatedAt: new Date(),\n\t\t\t\tevent: 'sendMessage',\n\t\t\t});\n\t}","sourceCodeStart":68,"sourceCodeEnd":104,"githubUrl":"https://github.com/RocketChat/Rocket.Chat/blob/f9d3ec372bb580fa8d036f94cf03925a478ef768/apps/meteor/server/api/webhooks.ts#L68-L104","documentation":"Thrown by the integrations addIntegration helper when creating an outgoing integration of type 'newMessageToUser' but options.data.username is missing or empty. The helper checks (and prepends) a leading '@' before verifying existence, but an undefined/empty username still fails the final truthiness check and throws.","triggerScenarios":"POST to add an outgoing integration with event/type newMessageToUser and a data object lacking username, or with an empty-string username. Triggered via the integrations REST API or the integrations.create endpoint.","commonSituations":"Integration form submits without selecting a target DM user. Programmatic integration setup omits the username field. Username field keyed under a different property name (e.g. 'user' instead of 'username').","solutions":["Ensure options.data.username is a non-empty string identifying the target user before calling addIntegration.","Validate the presence of username in the integration form/config before submission.","Use the correct field name 'username' inside data for newMessageToUser integrations."],"exampleFix":"// before\naddOutgoingIntegration({ ..., type: 'webhook-outgoing', event: 'newMessageToUser', data: {} })\n\n// after\naddOutgoingIntegration({ ..., type: 'webhook-outgoing', event: 'newMessageToUser', data: { username: 'target.user' } })","handlingStrategy":"validation","validationCode":"if (!options?.data?.username || typeof options.data.username !== 'string') {\n  throw new ClientError('username-required','data.username is required for newMessageToUser');\n}","typeGuard":"function hasValidUsername(data) {\n  return !!data && typeof data.username === 'string' && data.username.trim().length > 0;\n}","tryCatchPattern":null,"preventionTips":["Require a target user selection in the integration form before submit.","Use the exact field name 'username' inside data for newMessageToUser.","Validate the integration payload shape client-side."],"tags":["api","integrations","webhooks","validation"],"backgroundTag":null,"analyzedSha":"f9d3ec372bb580fa8d036f94cf03925a478ef768","analyzedAt":"2026-08-12T19:07:17.372Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}