feat: add externalIds support for visitor identification

.changeset/forty-dolphins-check.md

@@ -0,0 +1,10 @@
+---
+'@rocket.chat/model-typings': minor
+'@rocket.chat/core-typings': minor
+'@rocket.chat/apps-engine': minor
+'@rocket.chat/omni-core': minor
+'@rocket.chat/models': minor
+'@rocket.chat/meteor': minor
+---
+
+Adds externalIds field to livechat visitors for external platform identification.

apps/meteor/app/apps/server/bridges/livechat.ts

@@ -1,6 +1,13 @@
 import type { IAppServerOrchestrator, IAppsLivechatMessage, IAppsMessage } from '@rocket.chat/apps';
 import type { IExtraRoomParams } from '@rocket.chat/apps-engine/definition/accessors/ILivechatCreator';
-import type { IVisitor, ILivechatRoom, ILivechatTransferData, IDepartment } from '@rocket.chat/apps-engine/definition/livechat';
+import type {
+	IVisitorExternalIdentifier,
+	IVisitor,
+	ILivechatRoom,
+	ILivechatTransferData,
+	IDepartment,
+	ResolveVisitorContactData,
+} from '@rocket.chat/apps-engine/definition/livechat';
 import type { IMessage as IAppsEngineMessage } from '@rocket.chat/apps-engine/definition/messages';
 import type { IUser } from '@rocket.chat/apps-engine/definition/users';
 import { LivechatBridge } from '@rocket.chat/apps-engine/server/bridges/LivechatBridge';
@@ -16,6 +23,7 @@ import { setCustomFields } from '../../../livechat/server/lib/custom-fields';
 import { getRoomMessages } from '../../../livechat/server/lib/getRoomMessages';
 import type { ILivechatMessage } from '../../../livechat/server/lib/localTypes';
 import { updateMessage, sendMessage } from '../../../livechat/server/lib/messages';
+import { resolveVisitor } from '../../../livechat/server/lib/resolveVisitor';
 import { createRoom } from '../../../livechat/server/lib/rooms';
 import { online } from '../../../livechat/server/lib/service-status';
 import { transfer } from '../../../livechat/server/lib/transfer';
@@ -198,6 +206,10 @@ export class AppLivechatBridge extends LivechatBridge {
 		return Promise.all(result.map((room) => this.orch.getConverters()?.get('rooms').convertRoom(room) as Promise<ILivechatRoom>));
 	}
 
+	/**
+	 * @deprecated Use `createAndReturnVisitor` instead.
+	 * Note: This method does not support `externalIds`.
+	 */
 	protected async createVisitor(visitor: IVisitor, appId: string): Promise<string> {
 		this.orch.debugLog(`The App ${appId} is creating a livechat visitor.`);
 
@@ -226,6 +238,9 @@ export class AppLivechatBridge extends LivechatBridge {
 	protected async createAndReturnVisitor(visitor: IVisitor, appId: string): Promise<IVisitor | undefined> {
 		this.orch.debugLog(`The App ${appId} is creating a livechat visitor.`);
 
+		// Add appId to each externalId entry
+		const externalIds = visitor.externalIds?.map((entry) => ({ ...entry, appId }));
+
 		const registerData = {
 			department: visitor.department,
 			username: visitor.username,
@@ -235,6 +250,7 @@ export class AppLivechatBridge extends LivechatBridge {
 			id: visitor.id,
 			...(visitor.phone?.length && { phone: { number: visitor.phone[0].phoneNumber } }),
 			...(visitor.visitorEmails?.length && { email: visitor.visitorEmails[0].address }),
+			...(externalIds?.length && { externalIds }),
 		};
 
 		const livechatVisitor = await registerGuest(registerData, {
@@ -335,6 +351,34 @@ export class AppLivechatBridge extends LivechatBridge {
 			.convertVisitor(await LivechatVisitors.findOneVisitorByPhone(phoneNumber));
 	}
 
+	protected async resolveVisitor(
+		externalId: Omit<IVisitorExternalIdentifier, 'appId'>,
+		contactData: ResolveVisitorContactData | undefined,
+		appId: string,
+	): Promise<IVisitor | undefined> {
+		this.orch.debugLog(`The App ${appId} is resolving a livechat visitor by external ID.`);
+
+		const visitor = await resolveVisitor({
+			appId,
+			externalId,
+			contactData,
+		});
+
+		return this.orch.getConverters()?.get('visitors').convertVisitor(visitor);
+	}
+
+	protected async updateVisitorExternalId(
+		visitorId: string,
+		externalId: Omit<IVisitorExternalIdentifier, 'appId'>,
+		appId: string,
+	): Promise<IVisitor | undefined> {
+		this.orch.debugLog(`The App ${appId} is updating externalId for visitor ${visitorId}.`);
+
+		const visitor = await LivechatVisitors.updateExternalIdById(visitorId, appId, externalId);
+
+		return this.orch.getConverters()?.get('visitors').convertVisitor(visitor);
+	}
+
 	protected async findDepartmentByIdOrName(value: string, appId: string): Promise<IDepartment | undefined> {
 		this.orch.debugLog(`The App ${appId} is looking for livechat departments.`);
 

apps/meteor/app/apps/server/converters/visitors.js

@@ -37,6 +37,7 @@ export class AppVisitorsConverter {
 			livechatData: 'livechatData',
 			status: 'status',
 			activity: 'activity',
+			externalIds: 'externalIds',
 		};
 
 		return transformMappedData(visitor, map);
@@ -57,6 +58,7 @@ export class AppVisitorsConverter {
 			status: visitor.status || 'online',
 			...(visitor.visitorEmails && { visitorEmails: visitor.visitorEmails }),
 			...(visitor.department && { department: visitor.department }),
+			...(visitor.externalIds && { externalIds: visitor.externalIds }),
 		};
 
 		return Object.assign(newVisitor, visitor._unmappedProperties_);

apps/meteor/app/livechat/server/lib/resolveVisitor.ts

@@ -0,0 +1,23 @@
+import type { IVisitorExternalIdentifier, ILivechatVisitor } from '@rocket.chat/core-typings';
+import { LivechatVisitors } from '@rocket.chat/models';
+
+type ResolveVisitorContactData = { phone: string } | { email: string };
+
+type ResolveVisitorParams = {
+	appId: string;
+	externalId: Omit<IVisitorExternalIdentifier, 'appId'>;
+	contactData?: ResolveVisitorContactData;
+};
+
+export async function resolveVisitor({ appId, externalId, contactData }: ResolveVisitorParams): Promise<ILivechatVisitor | null> {
+	const visitorByExternalId = await LivechatVisitors.findOneByExternalId(externalId.entityId);
+	if (visitorByExternalId) {
+		return visitorByExternalId;
+	}
+
+	if (contactData && (('phone' in contactData && contactData.phone) || ('email' in contactData && contactData.email))) {
+		return LivechatVisitors.findOneVisitorByPhoneOrEmailAndAddExternalId(contactData, appId, externalId);
+	}
+
+	return null;
+}

apps/meteor/client/views/omnichannel/contactInfo/tabs/ContactInfoChannels/ContactInfoChannelsItem.tsx

@@ -10,6 +10,7 @@ import { useBlockChannel } from './useBlockChannel';
 import { OmnichannelRoomIcon } from '../../../../../components/RoomIcon/OmnichannelRoomIcon';
 import { useTimeFromNow } from '../../../../../hooks/useTimeFromNow';
 import { useOutboundMessageModal } from '../../../components/outboundMessage/modals/OutboundMessageModal';
+import { useVisitorInfo } from '../../../directory/hooks/useVisitorInfo';
 import { useOmnichannelSource } from '../../../hooks/useOmnichannelSource';
 
 type ContactInfoChannelsItemProps = Serialized<ILivechatContactChannel> & {
@@ -29,6 +30,19 @@ const ContactInfoChannelsItem = ({
 	const { getSourceLabel, getSourceName } = useOmnichannelSource();
 	const getTimeFromNow = useTimeFromNow(true);
 
+	const { data: visitorData } = useVisitorInfo(visitor.visitorId);
+
+	const channelLabel = useMemo(() => {
+		const phone = getSourceLabel(details);
+		const externalId = details?.id ? visitorData?.externalIds?.find((e) => e.appId === details.id) : undefined;
+		const username = externalId?.metadata?.username;
+
+		if (typeof username === 'string' && phone) {
+			return `${username} - ${phone}`;
+		}
+		return typeof username === 'string' ? username : phone;
+	}, [visitorData?.externalIds, details, getSourceLabel]);
+
 	const [showButton, setShowButton] = useState(false);
 	const handleBlockContact = useBlockChannel({ association: visitor, blocked });
 	const outboundMessageModal = useOutboundMessageModal();
@@ -94,7 +108,7 @@ const ContactInfoChannelsItem = ({
 				)}
 			</Box>
 			<Box minHeight='x24' alignItems='center' mbs={4} display='flex' justifyContent='space-between'>
-				<Box>{getSourceLabel(details)}</Box>
+				<Box>{channelLabel}</Box>
 				{showButton && <GenericMenu detached title={t('Options')} sections={[{ items: menuItems }]} tiny />}
 			</Box>
 		</Box>

apps/meteor/client/views/omnichannel/directory/components/ContactField.tsx

@@ -26,7 +26,6 @@ const ContactField = ({ contact, room }: ContactFieldProps) => {
 	const getVisitorInfo = useEndpoint('GET', '/v1/livechat/visitors.info');
 	const { data, isPending, isError } = useQuery({
 		queryKey: ['/v1/livechat/visitors.info', contact._id],
-
 		queryFn: () => getVisitorInfo({ visitorId: contact._id }),
 	});
 
@@ -39,17 +38,19 @@ const ContactField = ({ contact, room }: ContactFieldProps) => {
 	}
 
 	const {
-		visitor: { username, name },
+		visitor: { username, name, phone },
 	} = data;
 
 	const displayName = name || username;
+	const phoneNumber = phone?.[0]?.phoneNumber;
+	const contactIdentifier = [...new Set([username, phoneNumber])].filter(Boolean).join(' · ');
 
 	return (
 		<Field>
 			<Label>{t('Contact')}</Label>
 			<Info style={{ display: 'flex' }}>
 				<Avatar size='x40' title={fname} url={avatarUrl} />
-				<AgentInfoDetails mis={10} name={displayName} shortName={username} status={<UserStatus status={status} />} />
+				<AgentInfoDetails mis={10} name={displayName} shortName={contactIdentifier} status={<UserStatus status={status} />} />
 			</Info>
 		</Field>
 	);

apps/meteor/tests/data/apps/app-packages/README.md

@@ -135,6 +135,153 @@ export class TestEndpoint extends ApiEndpoint {
 
 </details>
 
+#### External ID Test (resolveVisitor API)
+
+File name: `external-id-test_0.0.1.zip`
+
+An app that tests the `ILivechatCreator.resolveVisitor()` and `ILivechatUpdater.updateVisitorExternalId()` APIs for resolving and updating livechat visitors by external identifiers. This is used to test the WhatsApp BSUID (Business Scoped User ID) support and progressive visitor enrichment.
+
+**Endpoints:**
+
+1. `POST /api/apps/public/:appId/resolve-visitor` - Resolve visitor by externalId with phone/email fallback
+2. `POST /api/apps/public/:appId/update-external-id` - Update visitor's externalId for this app
+
+**Request body (resolve-visitor):**
+```json
+{
+  "externalId": { "entityId": "bsuid-123", "metadata": { "username": "@johndoe" } },
+  "phone": "+1234567890"
+}
+```
+
+**Request body (update-external-id):**
+```json
+{
+  "visitorId": "visitor-123",
+  "externalId": { "entityId": "bsuid-123", "metadata": { "username": "@johndoe" } }
+}
+```
+
+**Response:**
+- Returns the visitor if found/updated
+- Returns `{ visitor: null }` if not found
+
+<details>
+<summary>App source code</summary>
+
+**ExternalIdTestApp.ts**
+```typescript
+import {
+	IAppAccessors,
+	IConfigurationExtend,
+	ILogger,
+} from '@rocket.chat/apps-engine/definition/accessors';
+import { App } from '@rocket.chat/apps-engine/definition/App';
+import { IAppInfo } from '@rocket.chat/apps-engine/definition/metadata';
+import { ApiSecurity, ApiVisibility } from '@rocket.chat/apps-engine/definition/api';
+import { ResolveVisitorEndpoint } from './ResolveVisitorEndpoint';
+import { UpdateExternalIdEndpoint } from './UpdateExternalIdEndpoint';
+
+export class ExternalIdTestApp extends App {
+	constructor(info: IAppInfo, logger: ILogger, accessors: IAppAccessors) {
+		super(info, logger, accessors);
+	}
+
+	public override async extendConfiguration(configuration: IConfigurationExtend): Promise<void> {
+		await configuration.api.provideApi({
+			visibility: ApiVisibility.PUBLIC,
+			security: ApiSecurity.UNSECURE,
+			endpoints: [new ResolveVisitorEndpoint(this), new UpdateExternalIdEndpoint(this)],
+		});
+	}
+}
+```
+
+**ResolveVisitorEndpoint.ts**
+```typescript
+import {
+	HttpStatusCode,
+	IHttp,
+	IModify,
+	IPersistence,
+	IRead,
+} from '@rocket.chat/apps-engine/definition/accessors';
+import { ApiEndpoint, IApiEndpointInfo, IApiRequest, IApiResponse } from '@rocket.chat/apps-engine/definition/api';
+
+export class ResolveVisitorEndpoint extends ApiEndpoint {
+	public override path = 'resolve-visitor';
+
+	public async post(
+		request: IApiRequest,
+		_endpoint: IApiEndpointInfo,
+		_read: IRead,
+		modify: IModify,
+		_http: IHttp,
+		_persistence: IPersistence,
+	): Promise<IApiResponse> {
+		const { externalId, phone, email } = request.content;
+
+		let contactData: { phone: string } | { email: string } | undefined;
+
+		if (phone) {
+			contactData = { phone };
+		} else if (email) {
+			contactData = { email };
+		}
+
+		const visitor = await modify.getCreator().getLivechatCreator().resolveVisitor(externalId, contactData);
+
+		return {
+			status: HttpStatusCode.OK,
+			content: { visitor: visitor || null },
+		};
+	}
+}
+```
+
+**UpdateExternalIdEndpoint.ts**
+```typescript
+import {
+	HttpStatusCode,
+	IHttp,
+	IModify,
+	IPersistence,
+	IRead,
+} from '@rocket.chat/apps-engine/definition/accessors';
+import { ApiEndpoint, IApiEndpointInfo, IApiRequest, IApiResponse } from '@rocket.chat/apps-engine/definition/api';
+
+export class UpdateExternalIdEndpoint extends ApiEndpoint {
+	public override path = 'update-external-id';
+
+	public async post(
+		request: IApiRequest,
+		_endpoint: IApiEndpointInfo,
+		_read: IRead,
+		modify: IModify,
+		_http: IHttp,
+		_persistence: IPersistence,
+	): Promise<IApiResponse> {
+		const { visitorId, externalId } = request.content;
+
+		if (!visitorId || !externalId) {
+			return {
+				status: HttpStatusCode.BAD_REQUEST,
+				content: { error: 'visitorId and externalId are required' },
+			};
+		}
+
+		const visitor = await modify.getUpdater().getLivechatUpdater().updateVisitorExternalId(visitorId, externalId);
+
+		return {
+			status: HttpStatusCode.OK,
+			content: { visitor: visitor || null },
+		};
+	}
+}
+```
+
+</details>
+
 #### Nested Requests simulation
 
 File name: `nested-requests_0.0.1.zip`

apps/meteor/tests/data/apps/app-packages/index.ts

@@ -7,3 +7,5 @@ export const appAPIParameterTest = path.resolve(__dirname, './api-parameter-test
 export const appCausingNestedRequests = path.resolve(__dirname, './nested-requests_0.0.1.zip');
 
 export const appUpdateStatusTest = path.resolve(__dirname, './update-status-test_0.0.1.zip');
+
+export const appExternalIdTest = path.resolve(__dirname, './external-id-test_0.0.1.zip');