{"record":{"id":"923493e7fb4994e5","repo":"RocketChat/Rocket.Chat","slug":"error-livechat-visitor-registration","errorCode":null,"errorMessage":"error-livechat-visitor-registration","messagePattern":"error-livechat-visitor-registration","errorType":"exception","errorClass":"Error","httpStatus":400,"severity":"error","filePath":"apps/meteor/server/api/v1/omnichannel/message.ts","lineNumber":276,"sourceCode":"\t\t\tif (visitor) {\n\t\t\t\tconst extraQuery = await callbacks.run('livechat.applyRoomRestrictions', {}, { userId: this.userId });\n\t\t\t\tconst room = await LivechatRooms.findOneOpenByVisitorToken(visitorToken, { projection: { _id: 1 } }, extraQuery);\n\t\t\t\trid = room?._id ?? Random.id();\n\t\t\t} else {\n\t\t\t\trid = Random.id();\n\n\t\t\t\tconst guest: typeof this.bodyParams.visitor & { connectionData?: unknown } = this.bodyParams.visitor;\n\n\t\t\t\tif (settings.get('Livechat_Allow_collect_and_store_HTTP_header_informations')) {\n\t\t\t\t\tguest.connectionData = normalizeHttpHeaderData(this.request.headers);\n\t\t\t\t}\n\n\t\t\t\tvisitor = await registerGuest(guest, {\n\t\t\t\t\tshouldConsiderIdleAgent: settings.get<boolean>('Livechat_enabled_when_agent_idle'),\n\t\t\t\t\tshouldConsiderOfflineAgent: settings.get<boolean>('Livechat_accept_chats_with_no_agents'),\n\t\t\t\t});\n\t\t\t\tif (!visitor) {\n\t\t\t\t\tthrow new Error('error-livechat-visitor-registration');\n\t\t\t\t}\n\t\t\t}\n\n\t\t\tconst guest = visitor;\n\t\t\tif (!guest) {\n\t\t\t\tthrow new Error('error-invalid-token');\n\t\t\t}\n\n\t\t\tconst sentMessages = await Promise.all(\n\t\t\t\tthis.bodyParams.messages.map(async (message: { msg: string }): Promise<{ username: string; msg: string; ts: number }> => {\n\t\t\t\t\tconst messageToSend = {\n\t\t\t\t\t\tguest,\n\t\t\t\t\t\tmessage: {\n\t\t\t\t\t\t\t_id: Random.id(),\n\t\t\t\t\t\t\trid,\n\t\t\t\t\t\t\ttoken: visitorToken,\n\t\t\t\t\t\t\tmsg: message.msg,\n\t\t\t\t\t\t},","sourceCodeStart":258,"sourceCodeEnd":294,"githubUrl":"https://github.com/RocketChat/Rocket.Chat/blob/b2c16d5842cbe6b69b59bdf6fc5e5f1afcd1f0b0/apps/meteor/server/api/v1/omnichannel/message.ts#L258-L294","documentation":"Thrown by POST /api/v1/livechat/messages (note: authRequired — an agent/user token, unlike the visitor routes) when the supplied visitor.token does not match an existing visitor and the fallback attempt to create one fails: registerGuest() from @rocket.chat/omni-core returned null. registerGuest nulls out when the visitor payload is invalid — e.g. missing required fields, unparseable visitor data, or a department that cannot be resolved/served.","triggerScenarios":"POST /api/v1/livechat/messages with body { visitor: { token: 'new-or-unknown', ... }, messages: [...] } where the visitor object fails registration — missing name/username generation inputs, invalid visitorEmails entries, nonexistent or disabled department, or duplicate token with conflicting data.","commonSituations":"Integrations fabricating visitor objects by hand and omitting required fields; sending a department id that was archived; email string failing validation; payload shaped for the old registerGuest API after an upgrade tightened validation.","solutions":["Send a minimal but well-formed visitor object (token, name) and confirm it registers via POST /api/v1/livechat/visitor first, then reuse that token in livechat/messages.","If passing department, use an enabled department id from GET /api/v1/livechat/departments and provide valid email arrays.","Check server logs — registerGuest failures around registration (department resolution, validation) are logged and pinpoint the offending field.","Ensure the request carries a valid user auth token (X-Auth-Token/X-User-Id), since this route is not visitor-authenticated."],"exampleFix":"// before (malformed visitor payload)\nawait sdk.post('livechat/messages', {\n  visitor: { token: 'tkn1', department: 'retired-dept-id' },\n  messages: [{ msg: 'hello' }],\n});\n\n// after (pre-register a valid visitor, then send messages)\nawait sdk.post('livechat/visitor', { visitor: { token: 'tkn1', name: 'Lead' } });\nawait sdk.post('livechat/messages', {\n  visitor: { token: 'tkn1', name: 'Lead' },\n  messages: [{ msg: 'hello' }],\n});","handlingStrategy":"validation","validationCode":"// Pre-register the visitor so livechat/messages never hits the fallback path\nasync function ensureRegisteredVisitor(visitor: { token: string; name?: string; email?: string[] }): Promise<void> {\n  const res = await fetch('/api/v1/livechat/visitor', {\n    method: 'POST',\n    headers: { 'Content-Type': 'application/json' },\n    body: JSON.stringify({ visitor }),\n  });\n  const body = await res.json();\n  if (!body.success) throw new Error(`visitor registration failed: ${body.error}`);\n}","typeGuard":"interface MinimalVisitor { token: string; name?: string; email?: { address: string }[]; department?: string }\nfunction isValidVisitorPayload(v: unknown): v is MinimalVisitor {\n  const o = v as MinimalVisitor;\n  return typeof o?.token === 'string' && o.token.length > 0 &&\n    (o.email === undefined || Array.isArray(o.email)) &&\n    (o.department === undefined || typeof o.department === 'string');\n}","tryCatchPattern":"if (isLivechatErrorResponse(body) && body.error === 'error-livechat-visitor-registration') {\n  // registration payload rejected: log visitor payload (minus PII) and surface a configuration error, do not retry blindly\n  reportInvalidVisitorPayload(visitorToken);\n}","preventionTips":["Register visitors explicitly first (livechat/visitor) and treat livechat/messages' auto-register as a convenience, not the primary path.","Send only known-good fields: token, name, valid emails, and enabled department ids from livechat/departments.","Remember this route requires user authentication (X-Auth-Token/X-User-Id), unlike the visitor-token routes."],"tags":["livechat","omnichannel","visitor-registration","rest-api","payload-validation"],"backgroundTag":"registration-failed","analyzedSha":"b2c16d5842cbe6b69b59bdf6fc5e5f1afcd1f0b0","analyzedAt":"2026-08-18T15:26:39.429Z","contentChangedAt":"2026-08-18T15:26:39.429Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}