{"record":{"id":"f2ac31be36873936","repo":"RocketChat/Rocket.Chat","slug":"error-invalid-contact-manager","errorCode":"error-invalid-contact-manager","errorMessage":"The contact manager must have the role \"livechat-agent\"","messagePattern":"The contact manager must have the role \"livechat-agent\"","errorType":"error_code","errorClass":"MeteorError","httpStatus":null,"severity":"error","filePath":"apps/meteor/server/lib/omnichannel/contacts/registerContact.ts","lineNumber":41,"sourceCode":"\nexport async function registerContact(\n\t{ token, name, email = '', phone, username, customFields = {}, contactManager }: RegisterContactProps,\n\tuserId: string,\n): Promise<string> {\n\tif (!token || typeof token !== 'string') {\n\t\tthrow new MeteorError('error-invalid-contact-data', 'Invalid visitor token');\n\t}\n\n\tconst visitorEmail = email.trim().toLowerCase();\n\n\tif (contactManager?.username) {\n\t\t// verify if the user exists with this username and has a livechat-agent role\n\t\tconst manager = await Users.findOneByUsername(contactManager.username, { projection: { roles: 1 } });\n\t\tif (!manager) {\n\t\t\tthrow new MeteorError('error-contact-manager-not-found', `No user found with username ${contactManager.username}`);\n\t\t}\n\t\tif (!manager.roles || !Array.isArray(manager.roles) || !manager.roles.includes('livechat-agent')) {\n\t\t\tthrow new MeteorError('error-invalid-contact-manager', 'The contact manager must have the role \"livechat-agent\"');\n\t\t}\n\t}\n\n\tconst existingUserByToken = await LivechatVisitors.getVisitorByToken(token, { projection: { _id: 1 } });\n\tlet visitorId = existingUserByToken?._id;\n\n\tif (!existingUserByToken) {\n\t\tif (!username) {\n\t\t\tusername = await LivechatVisitors.getNextVisitorUsername();\n\t\t}\n\n\t\tconst existingUserByEmail = await LivechatVisitors.findOneGuestByEmailAddress(visitorEmail);\n\t\tvisitorId = existingUserByEmail?._id;\n\n\t\tif (!existingUserByEmail) {\n\t\t\tconst userData = {\n\t\t\t\tusername,\n\t\t\t\tts: new Date(),","sourceCodeStart":23,"sourceCodeEnd":59,"githubUrl":"https://github.com/RocketChat/Rocket.Chat/blob/b2c16d5842cbe6b69b59bdf6fc5e5f1afcd1f0b0/apps/meteor/server/lib/omnichannel/contacts/registerContact.ts#L23-L59","documentation":"registerContact found a user with the given contactManager.username, but that user's roles array is missing, malformed, or does not include 'livechat-agent'. Omnichannel requires contact managers to be livechat agents so routing and visibility rules hold. This is a role/permission problem, not a lookup problem — the user exists but is not an agent.","triggerScenarios":"POST /api/v1/omnichannel/contact (or registerContact) with contactManager.username of a valid user who was never added as an omnichannel agent, was removed from the agent list, or whose roles field is empty/non-array due to a data issue.","commonSituations":"Admin removed the agent from Omnichannel > Agents but integrations still reference them; user was created via SSO without the livechat-agent role; roles document corrupted after a migration.","solutions":["Add the 'livechat-agent' role to the user (POST /api/v1/user.update or add them under Administration > Omnichannel > Agents)","Confirm the user now appears as an agent via GET /api/v1/livechat/agents, then retry registration","If the user should not be an agent, pass a different contactManager.username or omit contactManager"],"exampleFix":"// before\n// user 'johndoe' exists but has roles: ['user']\nawait registerContact({ token, email, contactManager: { username: 'johndoe' } }, userId);\n\n// after\nawait POST('/api/v1/user.update', { userId, data: { roles: ['user', 'livechat-agent'] } });\nawait registerContact({ token, email, contactManager: { username: 'johndoe' } }, userId);","handlingStrategy":"type-guard","validationCode":"const manager = await Users.findOneByUsername(contactManager.username, { projection: { roles: 1 } });\nif (!manager?.roles?.includes('livechat-agent')) {\n  throw new Error('Contact manager must be a livechat agent; add the role first');\n}\nawait registerContact(params, userId);","typeGuard":"type AgentUser = { _id: string; roles?: string[] };\nconst isLivechatAgent = (u: AgentUser | null): u is AgentUser & { roles: string[] } =>\n  Array.isArray(u?.roles) && (u.roles as string[]).includes('livechat-agent');","tryCatchPattern":"try {\n  await registerContact(params, userId);\n} catch (err) {\n  if (err instanceof MeteorError && err.code === 'error-invalid-contact-manager') {\n    // add livechat-agent role or pick another manager, then retry\n  }\n  throw err;\n}","preventionTips":["Only offer users from GET /api/v1/livechat/agents as contact-manager choices in UIs","When deactivating an agent, update contacts that reference them as manager","Check roles via users.info in integration smoke tests"],"tags":["omnichannel","livechat","contacts","contact-manager","roles","permissions","validation"],"backgroundTag":"user-missing-role","analyzedSha":"b2c16d5842cbe6b69b59bdf6fc5e5f1afcd1f0b0","analyzedAt":"2026-08-18T15:26:39.429Z","schemaVersion":2},"datasetVersion":"2026-08-21T13:17:26.733Z"}