{"record":{"id":"12ef3e328c83f058","repo":"RocketChat/Rocket.Chat","slug":"invalid-token","errorCode":"invalid-token","errorMessage":"invalid-token","messagePattern":"invalid-token","errorType":"exception","errorClass":"Error","httpStatus":400,"severity":"error","filePath":"apps/meteor/server/api/v1/omnichannel/agent.ts","lineNumber":28,"sourceCode":"\tvalidateForbiddenErrorResponse,\n\tvalidateUnauthorizedErrorResponse,\n} from '@rocket.chat/rest-typings';\n\nimport { API } from '../..';\nimport { findRoom, findGuest, findAgent, findOpenRoom } from './lib/livechat';\nimport { hasPermissionAsync } from '../../../lib/authorization/hasPermission';\nimport { hasRoleAsync } from '../../../lib/authorization/hasRole';\nimport { RoutingManager } from '../../../lib/omnichannel/RoutingManager';\nimport { getRequiredDepartment } from '../../../lib/omnichannel/departmentsLib';\nimport { saveAgentInfo } from '../../../lib/omnichannel/omni-users';\nimport { setUserStatusLivechat, allowAgentChangeServiceStatus } from '../../../lib/omnichannel/utils';\nimport type { ExtractRoutesFromAPI } from '../../ApiClass';\n\nAPI.v1.addRoute('livechat/agent.info/:rid/:token', {\n\tasync get() {\n\t\tconst visitor = await findGuest(this.urlParams.token);\n\t\tif (!visitor) {\n\t\t\tthrow new Error('invalid-token');\n\t\t}\n\n\t\tconst room = await findRoom(this.urlParams.token, this.urlParams.rid);\n\t\tif (!room) {\n\t\t\tthrow new Error('invalid-room');\n\t\t}\n\n\t\tconst agent = room?.servedBy && (await findAgent(room.servedBy._id));\n\t\tif (!agent) {\n\t\t\tthrow new Error('invalid-agent');\n\t\t}\n\n\t\treturn API.v1.success({ agent });\n\t},\n});\n\nAPI.v1.addRoute(\n\t'livechat/agent.next/:token',","sourceCodeStart":10,"sourceCodeEnd":46,"githubUrl":"https://github.com/RocketChat/Rocket.Chat/blob/f9d3ec372bb580fa8d036f94cf03925a478ef768/apps/meteor/server/api/v1/omnichannel/agent.ts#L10-L46","documentation":"Thrown by GET /api/v1/livechat/agent.info/:rid/:token when findGuest(token) returns null. findGuest calls LivechatVisitors.getVisitorByToken(token), so this error means no livechat visitor matches the provided token. The token is a URL path parameter identifying the livechat guest session.","triggerScenarios":"Calling agent.info with a visitor token that does not exist in the LivechatVisitors collection — the token was never issued, was for a different server instance, or the visitor record was deleted.","commonSituations":"Stale token from a previous server instance before migration; visitor record purged by a retention/cleanup job; typo in the token; token from a test environment used against production.","solutions":["Verify the token is correct and was issued by this server instance.","If the visitor no longer exists, register a new livechat guest via POST /api/v1/livechat/visitor to obtain a fresh token.","Check the LivechatVisitors collection for the token to confirm it exists."],"exampleFix":"// before: using a stale/unknown token\nGET /api/v1/livechat/agent.info/ROOM_ID/old-or-wrong-token\n// after: obtain a valid token first\nPOST /api/v1/livechat/visitor { \"visitor\": { \"name\": \"Guest\", \"token\": \"new-unique-token\" } }\n// then use the token\nGET /api/v1/livechat/agent.info/ROOM_ID/new-unique-token","handlingStrategy":"validation","validationCode":"// Validate the visitor token exists before calling agent.info\nasync function isValidVisitorToken(baseUrl, token) {\n  // Use the livechat visitor endpoint to verify\n  const res = await fetch(`${baseUrl}/api/v1/livechat/visitor/${token}`);\n  return res.ok;\n}\n\nif (!(await isValidVisitorToken(baseUrl, token))) {\n  throw new Error('Invalid visitor token — register a new guest first');\n}","typeGuard":"function isValidVisitorTokenFormat(token: unknown): token is string {\n  return typeof token === 'string' && token.length > 0;\n}","tryCatchPattern":"try {\n  await getAgentInfo(rid, token);\n} catch (e) {\n  if (e.error === 'invalid-token' || e.message === 'invalid-token') {\n    // Register a new visitor and retry\n    const newToken = await registerLivechatVisitor();\n    return getAgentInfo(rid, newToken);\n  }\n  throw e;\n}","preventionTips":["Store visitor tokens securely after registration and verify they haven't been purged.","Register visitors via POST /api/v1/livechat/visitor before using the token in other endpoints.","Handle token invalidation gracefully by re-registering the visitor."],"tags":["omnichannel","livechat","visitor","token"],"backgroundTag":null,"analyzedSha":"f9d3ec372bb580fa8d036f94cf03925a478ef768","analyzedAt":"2026-08-12T19:07:17.372Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}