RocketChat/Rocket.Chat · error · Error

username-required

Error message

username-required

What it means

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.

Source

Thrown at apps/meteor/server/api/webhooks.ts:86

				urls: [options.target_url],
				name: options.name,
				channel: options.data.channel_name,
				triggerWords: options.data.trigger_words,
				type: 'webhook-outgoing',
				event: 'sendMessage',
				token: Random.id(24),
				scriptEnabled: false,
				script: '',
				enabled: true,
				_id: Random.id(),
				_updatedAt: new Date(),
			});
		case 'newMessageToUser':
			if (options.data?.username?.indexOf('@') === -1) {
				options.data.username = `@${options.data.username}`;
			}
			if (!options.data?.username) {
				throw new Error('username-required');
			}

			return addOutgoingIntegration(user._id, {
				username: 'rocket.cat',
				urls: [options.target_url],
				name: options.name,
				channel: options.data.username,
				triggerWords: options.data.trigger_words,
				_id: '',
				type: 'webhook-outgoing',
				token: '',
				scriptEnabled: false,
				script: '',
				enabled: false,
				_updatedAt: new Date(),
				event: 'sendMessage',
			});
	}

View on GitHub (pinned to f9d3ec372b)

Solutions

1. Ensure options.data.username is a non-empty string identifying the target user before calling addIntegration.
2. Validate the presence of username in the integration form/config before submission.
3. Use the correct field name 'username' inside data for newMessageToUser integrations.

Example fix

// before
addOutgoingIntegration({ ..., type: 'webhook-outgoing', event: 'newMessageToUser', data: {} })

// after
addOutgoingIntegration({ ..., type: 'webhook-outgoing', event: 'newMessageToUser', data: { username: 'target.user' } })

if (!options?.data?.username || typeof options.data.username !== 'string') {
  throw new ClientError('username-required','data.username is required for newMessageToUser');
}

function hasValidUsername(data) {
  return !!data && typeof data.username === 'string' && data.username.trim().length > 0;
}

When it happens

Trigger: 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.

Common situations: 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').

Related errors

• Integration payload must be a JSON object, not an array or p
• Invalid integration id or token provided.
• Invalid Api parameter provided, it must be a valid IApi obje
• error-emoji-param-not-provided
• error-param-required

AI-assisted analysis of RocketChat/Rocket.Chat@f9d3ec372b (2026-08-12). Data as JSON: /api/errors/d9a4a734045e3607. Report an issue: GitHub.