Skip to content

The open alternative to Salesforce, designed for AI.

feat(messaging): resolve identity for non-email participants (#25906)

Félix Malfait2ec4ce6725b5
diff --git a/packages/twenty-client-sdk/src/metadata/generated/schema.graphql b/packages/twenty-client-sdk/src/metadata/generated/schema.graphql
index ff0d0d176ef..e29a6b2a41f 100644
--- a/packages/twenty-client-sdk/src/metadata/generated/schema.graphql
+++ b/packages/twenty-client-sdk/src/metadata/generated/schema.graphql
@@ -5229,6 +5229,8 @@ input AppMessageParticipantInput {
role: MessageParticipantRole!
handle: String!
displayName: String
+ personId: UUID
+ workspaceMemberId: UUID
}
enum MessageParticipantRole {
diff --git a/packages/twenty-client-sdk/src/metadata/generated/schema.ts b/packages/twenty-client-sdk/src/metadata/generated/schema.ts
index c6b6b76e193..2e59d660ae3 100644
--- a/packages/twenty-client-sdk/src/metadata/generated/schema.ts
+++ b/packages/twenty-client-sdk/src/metadata/generated/schema.ts
@@ -7695,7 +7695,7 @@ export interface IngestAppMessagesInput {messageChannelId: Scalars['UUID'],messa
export interface AppMessageInput {externalId: Scalars['String'],threadExternalId: Scalars['String'],subject?: (Scalars['String'] | null),text: Scalars['String'],receivedAt: Scalars['DateTime'],participants: AppMessageParticipantInput[]}
-export interface AppMessageParticipantInput {role: MessageParticipantRole,handle: Scalars['String'],displayName?: (Scalars['String'] | null)}
+export interface AppMessageParticipantInput {role: MessageParticipantRole,handle: Scalars['String'],displayName?: (Scalars['String'] | null),personId?: (Scalars['UUID'] | null),workspaceMemberId?: (Scalars['UUID'] | null)}
export interface CreateEmailingDomainInput {domain: Scalars['String']}
diff --git a/packages/twenty-client-sdk/src/metadata/generated/types.ts b/packages/twenty-client-sdk/src/metadata/generated/types.ts
index a414219e805..1cb9b6814fa 100644
--- a/packages/twenty-client-sdk/src/metadata/generated/types.ts
+++ b/packages/twenty-client-sdk/src/metadata/generated/types.ts
@@ -13302,6 +13302,12 @@ export default {
"displayName": [
1
],
+ "personId": [
+ 3
+ ],
+ "workspaceMemberId": [
+ 3
+ ],
"__typename": [
1
]
diff --git a/packages/twenty-docs/developers/extend/apps/logic/messaging-channels.mdx b/packages/twenty-docs/developers/extend/apps/logic/messaging-channels.mdx
index 7efd1e725d8..0f5e6b9cdea 100644
--- a/packages/twenty-docs/developers/extend/apps/logic/messaging-channels.mdx
+++ b/packages/twenty-docs/developers/extend/apps/logic/messaging-channels.mdx
@@ -128,9 +128,34 @@ A batch is all-or-nothing, and repeating one `externalId` inside a single batch
### Linking participants to People
-Twenty matches email participants to People by email address. That will not match a LinkedIn URN or a phone number, so ingested participants start unlinked, and an unlinked thread does not appear on anyone's record page.
+Twenty matches email participants to People by email address. That cannot match a LinkedIn URN or a phone number, so **an app must say who a participant is** — an unlinked thread does not appear on anyone's record page.
-Until app-supplied identity linking lands, resolve contacts yourself: look the participant up by whatever field your provider's identity lives in (`Person.linkedinLink`, a custom field your app added), then attach the thread to that record. See [Extending objects](/developers/extend/apps/data/extending-objects) for adding an identity field of your own.
+Pass `personId` alongside the handle:
+
+```ts
+participants: [
+ {
+ role: MessageParticipantRole.FROM,
+ handle: event.sender.memberUrn,
+ displayName: event.sender.name,
+ personId: await resolvePersonIdFromLinkedinUrn(event.sender.memberUrn),
+ },
+]
+```
+
+Resolve the id however your provider's identity is stored — against `Person.linkedinLink`, or an identity field your app added with [`defineField`](/developers/extend/apps/data/extending-objects). Unknown ids are rejected up front rather than stored as dangling links.
+
+Once a participant is linked, Twenty builds the thread's targets, and the conversation appears on that Person's record page and on their company's, exactly as an email thread does.
+
+`workspaceMemberId` is also accepted, for a participant who is a member of this workspace rather than a contact. It is **attribution only**: thread targets are built from `personId` alone — the same as for email — so a participant linked only to a workspace member shows in the thread but pulls the conversation onto no record page. Pass `personId` when you want the thread to land somewhere.
+
+<Note>
+A late match is not lost. Re-ingesting a message with an identity you have since resolved links the participant that is already there — matched on the message, handle and role, so a display name that changed or was omitted in the meantime does not split it in two. An omitted name keeps the one already stored; a new one replaces it. Sending a different `personId` corrects an earlier link rather than adding a second one.
+
+There is no way to *clear* an identity yet: a null is treated as "leave it alone", not "unlink". Correcting a wrong link means supplying the right one.
+</Note>
+
+Participants you leave unlinked are still stored and still render in the thread — they simply do not pull the conversation onto a record.
## Listing and updating channels
@@ -186,5 +211,5 @@ Deleting a channel deletes the messages ingested through it, and any thread left
- **It is not polled.** Twenty's import pipeline polls mailbox providers on a cron. App channels are push-only: nothing fetches on your behalf, so your app is responsible for getting messages in, via a webhook route or a cron logic function.
- **It does not send.** Outbound delivery is not yet routed to apps; a reply composed in Twenty cannot reach your provider. Until it is, link out to the provider's own UI for replies.
-- **It does not resolve contacts.** Twenty matches email participants to People by email address, which will not match a LinkedIn URN. Link participants to People explicitly when you ingest them.
-- **It does not create contacts.** Twenty's auto-creation derives people and companies from email domains, which is meaningless for most providers, so it is off for app channels.
+- **It does not resolve contacts.** Twenty matches email participants to People by email address, which cannot match a LinkedIn URN, so app channels [link participants explicitly at ingestion](#linking-participants-to-people) instead.
+- **It does not create contacts.** Twenty's auto-creation derives people and companies from email domains, which is meaningless for most providers, so it is off for app channels. Create the Person yourself, then pass its `personId`.
diff --git a/packages/twenty-front/src/generated-metadata/graphql.ts b/packages/twenty-front/src/generated-metadata/graphql.ts
index dee5350988d..2ad909d093c 100644
--- a/packages/twenty-front/src/generated-metadata/graphql.ts
+++ b/packages/twenty-front/src/generated-metadata/graphql.ts
@@ -316,7 +316,9 @@ export type AppMessageInput = {
export type AppMessageParticipantInput = {
displayName?: InputMaybe<Scalars['String']['input']>;
handle: Scalars['String']['input'];
+ personId?: InputMaybe<Scalars['UUID']['input']>;
role: MessageParticipantRole;
+ workspaceMemberId?: InputMaybe<Scalars['UUID']['input']>;
};
export type Application = {
diff --git a/packages/twenty-sdk/src/sdk/logic-function/messaging/types/ingest-message.type.ts b/packages/twenty-sdk/src/sdk/logic-function/messaging/types/ingest-message.type.ts
index 75d7ed1a317..b7ad01dd5ff 100644
--- a/packages/twenty-sdk/src/sdk/logic-function/messaging/types/ingest-message.type.ts
+++ b/packages/twenty-sdk/src/sdk/logic-function/messaging/types/ingest-message.type.ts
@@ -7,7 +7,24 @@ export type IngestMessageParticipant = {
// The participant's identity on the provider, in the same namespace as the
// channel's own handle.
handle: string;
+ // Omitting it on a later delivery keeps whatever name is already stored,
+ // so enriching a participant with an identity does not require resending
+ // the rest of the row.
displayName?: string;
+ // Twenty resolves email participants to People by email address, which
+ // cannot match a provider handle. Supply the record yourself when you know
+ // it — look the handle up against `Person.linkedinLink` or an identity
+ // field your app added. Without it the participant stays unlinked and the
+ // thread never appears on anyone's record page.
+ //
+ // Ingesting the same message again with an identity you have since
+ // resolved links the existing participant, so a late match is not lost.
+ personId?: string;
+ // For a participant who is a member of this workspace rather than a contact.
+ // Attribution only: record-page placement is built from `personId` alone, so
+ // a participant linked only to a workspace member shows in the thread but
+ // pulls the conversation onto no record.
+ workspaceMemberId?: string;
};
export type IngestMessage = {
diff --git a/packages/twenty-server/src/engine/metadata-modules/message-channel/dtos/ingest-app-messages.input.ts b/packages/twenty-server/src/engine/metadata-modules/message-channel/dtos/ingest-app-messages.input.ts
index 5c3d2210f1b..d48ebb7b8ee 100644
--- a/packages/twenty-server/src/engine/metadata-modules/message-channel/dtos/ingest-app-messages.input.ts
+++ b/packages/twenty-server/src/engine/metadata-modules/message-channel/dtos/ingest-app-messages.input.ts
@@ -48,6 +48,23 @@ export class AppMessageParticipantInput {
@IsString()
@MaxLength(255)
displayName?: string;
+
+ // Nothing can derive a Person from a handle that is not an email address,
+ // so a caller that already knows who this is says so here. Without it the
+ // participant stays unlinked and the thread never reaches a record page.
+ @Field(() => UUIDScalarType, { nullable: true })
+ @IsOptional()
+ @IsUUID()
+ personId?: string;
+
+ // Attribution only. Thread targets — what puts a conversation on a record
+ // page — are built from personId alone, exactly as they are for email, so a
+ // participant linked only to a workspace member is stored and shows in the
+ // thread but pulls the conversation onto nothing.
+ @Field(() => UUIDScalarType, { nullable: true })
+ @IsOptional()
+ @IsUUID()
+ workspaceMemberId?: string;
}
@InputType('AppMessageInput')
diff --git a/packages/twenty-server/src/engine/metadata-modules/message-channel/services/__tests__/application-message-ingestion.service.spec.ts b/packages/twenty-server/src/engine/metadata-modules/message-channel/services/__tests__/application-message-ingestion.service.spec.ts
index a4d0c853135..1195a1e7810 100644
--- a/packages/twenty-server/src/engine/metadata-modules/message-channel/services/__tests__/application-message-ingestion.service.spec.ts
+++ b/packages/twenty-server/src/engine/metadata-modules/message-channel/services/__tests__/application-message-ingestion.service.spec.ts
@@ -14,6 +14,7 @@ import { ApplicationMessageChannelsService } from 'src/engine/metadata-modules/m
import { ApplicationMessageIngestionService } from 'src/engine/metadata-modules/message-channel/services/application-message-ingestion.service';
import { MessageDirection } from 'src/modules/messaging/common/enums/message-direction.enum';
import { MessagingSaveMessagesAndEnqueueContactCreationService } from 'src/modules/messaging/message-import-manager/services/messaging-save-messages-and-enqueue-contact-creation.service';
+import { WorkspaceOrmManager } from 'src/engine/twenty-orm/workspace-orm.manager';
const APPLICATION_ID = '11111111-1111-4111-8111-111111111111';
const WORKSPACE_ID = '33333333-3333-4333-8333-333333333333';
@@ -25,6 +26,8 @@ describe('ApplicationMessageIngestionService', () => {
let service: ApplicationMessageIngestionService;
let channelsService: jest.Mocked<ApplicationMessageChannelsService>;
let saveMessagesService: jest.Mocked<MessagingSaveMessagesAndEnqueueContactCreationService>;
+ let existingRecordIds: string[];
+ let recordLookup: jest.Mock;
let cacheLockService: { withLock: jest.Mock };
const scope = {
@@ -52,6 +55,10 @@ describe('ApplicationMessageIngestionService', () => {
}) as AppMessageInput;
beforeEach(async () => {
+ existingRecordIds = [];
+ recordLookup = jest
+ .fn()
+ .mockImplementation(async () => existingRecordIds.map((id) => ({ id })));
cacheLockService = { withLock: jest.fn((fn: () => unknown) => fn()) };
channelsService = {
@@ -92,6 +99,13 @@ describe('ApplicationMessageIngestionService', () => {
provide: MessagingSaveMessagesAndEnqueueContactCreationService,
useValue: saveMessagesService,
},
+ {
+ provide: WorkspaceOrmManager,
+ useValue: {
+ executeInWorkspaceContext: (callback: () => unknown) => callback(),
+ getRepository: () => ({ find: recordLookup }),
+ },
+ },
],
}).compile();
@@ -251,6 +265,107 @@ describe('ApplicationMessageIngestionService', () => {
},
]);
});
+ describe('explicit identity', () => {
+ const PERSON_ID = '66666666-6666-4666-8666-666666666666';
+
+ it('passes a supplied personId through to the saved participant', async () => {
+ existingRecordIds = [PERSON_ID];
+
+ await service.ingest({
+ ...scope,
+ messages: [
+ aMessage({
+ participants: [
+ {
+ role: MessageParticipantRole.FROM,
+ handle: 'urn:li:person:ada',
+ personId: PERSON_ID,
+ },
+ { role: MessageParticipantRole.TO, handle: CHANNEL_HANDLE },
+ ],
+ }),
+ ],
+ });
+
+ expect(savedMessages()[0].participants[0]).toEqual(
+ expect.objectContaining({ personId: PERSON_ID }),
+ );
+ });
+
+ it('defaults an omitted identity to null rather than undefined', async () => {
+ await service.ingest({ ...scope, messages: [aMessage()] });
+
+ expect(savedMessages()[0].participants[0]).toEqual(
+ expect.objectContaining({ personId: null, workspaceMemberId: null }),
+ );
+ });
+
+ it('rejects a workspaceMemberId that does not exist in the workspace', async () => {
+ existingRecordIds = [];
+
+ await expect(
+ service.ingest({
+ ...scope,
+ messages: [
+ aMessage({
+ participants: [
+ {
+ role: MessageParticipantRole.FROM,
+ handle: 'urn:li:person:ada',
+ workspaceMemberId: PERSON_ID,
+ },
+ ],
+ }),
+ ],
+ }),
+ ).rejects.toMatchObject({
+ code: MessageChannelExceptionCode.INVALID_MESSAGE_CHANNEL_INPUT,
+ });
+
+ expect(
+ saveMessagesService.saveMessagesAndEnqueueContactCreation,
+ ).not.toHaveBeenCalled();
+ });
+
+ it('rejects a personId that does not exist in the workspace', async () => {
+ existingRecordIds = [];
+
+ await expect(
+ service.ingest({
+ ...scope,
+ messages: [
+ aMessage({
+ participants: [
+ {
+ role: MessageParticipantRole.FROM,
+ handle: 'urn:li:person:ada',
+ personId: PERSON_ID,
+ },
+ ],
+ }),
+ ],
+ }),
+ ).rejects.toMatchObject({
+ code: MessageChannelExceptionCode.INVALID_MESSAGE_CHANNEL_INPUT,
+ });
+
+ expect(
+ saveMessagesService.saveMessagesAndEnqueueContactCreation,
+ ).not.toHaveBeenCalled();
+ });
+
+ // The assertion that matters is the absence of the lookup: without it the
+ // test passes just as well with the early return deleted.
+ it('does not query for records when no identity is supplied', async () => {
+ await service.ingest({ ...scope, messages: [aMessage()] });
+
+ expect(recordLookup).not.toHaveBeenCalled();
+ expect(
+ saveMessagesService.saveMessagesAndEnqueueContactCreation,
+ ).toHaveBeenCalled();
+ });
+ });
+
it("refuses to ingest into another member's private channel", async () => {
channelsService.findOwnedOrThrow.mockRejectedValue(
new Error('ownership violation'),
diff --git a/packages/twenty-server/src/engine/metadata-modules/message-channel/services/application-message-ingestion.service.ts b/packages/twenty-server/src/engine/metadata-modules/message-channel/services/application-message-ingestion.service.ts
index 5606cd2602e..e8ea23f5b45 100644
--- a/packages/twenty-server/src/engine/metadata-modules/message-channel/services/application-message-ingestion.service.ts
+++ b/packages/twenty-server/src/engine/metadata-modules/message-channel/services/application-message-ingestion.service.ts
@@ -2,6 +2,7 @@ import { Injectable } from '@nestjs/common';
import { MessageParticipantRole } from 'twenty-shared/types';
import { isDefined } from 'twenty-shared/utils';
+import { In } from 'typeorm';
import { CacheLockService } from 'src/engine/core-modules/cache-lock/cache-lock.service';
import { type MessageChannelEntity } from 'src/engine/metadata-modules/message-channel/entities/message-channel.entity';
@@ -15,6 +16,8 @@ import { ApplicationMessageChannelsService } from 'src/engine/metadata-modules/m
import { buildAppIngestionLockKey } from 'src/engine/metadata-modules/message-channel/utils/build-app-ingestion-lock-key.util';
import { buildAppMessageHeaderMessageId } from 'src/engine/metadata-modules/message-channel/utils/build-app-message-header-message-id.util';
import { resolveAppMessageDirection } from 'src/engine/metadata-modules/message-channel/utils/resolve-app-message-direction.util';
+import { WorkspaceOrmManager } from 'src/engine/twenty-orm/workspace-orm.manager';
+import { buildSystemAuthContext } from 'src/engine/twenty-orm/utils/build-system-auth-context.util';
import { MessagingSaveMessagesAndEnqueueContactCreationService } from 'src/modules/messaging/message-import-manager/services/messaging-save-messages-and-enqueue-contact-creation.service';
import { type MessageWithParticipants } from 'src/modules/messaging/message-import-manager/types/message';
@@ -54,6 +57,7 @@ export class ApplicationMessageIngestionService {
constructor(
private readonly applicationMessageChannelsService: ApplicationMessageChannelsService,
private readonly saveMessagesService: MessagingSaveMessagesAndEnqueueContactCreationService,
+ private readonly workspaceOrmManager: WorkspaceOrmManager,
private readonly cacheLockService: CacheLockService,
) {}
@@ -81,6 +85,7 @@ export class ApplicationMessageIngestionService {
this.assertEachMessageHasOneSender(messages);
this.assertExternalIdsAreUnique(messages);
+ await this.assertReferencedIdentitiesExist({ messages, workspaceId });
const messagesToSave = messages.map((message) =>
this.toMessageWithParticipants({
@@ -182,10 +187,90 @@ export class ApplicationMessageIngestionService {
role: participant.role,
handle: participant.handle,
displayName: participant.displayName ?? '',
+ personId: participant.personId ?? null,
+ workspaceMemberId: participant.workspaceMemberId ?? null,
})),
};
}
+ // A participant pointing at a record that is not there, or belongs to
+ // another workspace, would insert a dangling link that quietly never
+ // renders. Checked up front so the app gets told, rather than at the FK.
+ private async assertReferencedIdentitiesExist({
+ messages,
+ workspaceId,
+ }: {
+ messages: AppMessageInput[];
+ workspaceId: string;
+ }): Promise<void> {
+ const personIds = new Set<string>();
+ const workspaceMemberIds = new Set<string>();
+
+ for (const message of messages) {
+ for (const participant of message.participants) {
+ if (isDefined(participant.personId)) {
+ personIds.add(participant.personId);
+ }
+
+ if (isDefined(participant.workspaceMemberId)) {
+ workspaceMemberIds.add(participant.workspaceMemberId);
+ }
+ }
+ }
+
+ if (personIds.size === 0 && workspaceMemberIds.size === 0) {
+ return;
+ }
+
+ const authContext = buildSystemAuthContext(workspaceId);
+
+ await this.workspaceOrmManager.executeInWorkspaceContext(
+ async () => {
+ await this.assertRecordsExist({
+ objectMetadataName: 'person',
+ ids: personIds,
+ });
+ await this.assertRecordsExist({
+ objectMetadataName: 'workspaceMember',
+ ids: workspaceMemberIds,
+ });
+ },
+ authContext,
+ { lite: true },
+ );
+ }
+
+ private async assertRecordsExist({
+ objectMetadataName,
+ ids,
+ }: {
+ objectMetadataName: 'person' | 'workspaceMember';
+ ids: Set<string>;
+ }): Promise<void> {
+ if (ids.size === 0) {
+ return;
+ }
+
+ const repository = this.workspaceOrmManager.getRepository(
+ objectMetadataName,
+ { shouldBypassPermissionChecks: true },
+ );
+
+ const found = await repository.find({
+ where: { id: In([...ids]) },
+ select: { id: true },
+ });
+ const foundIds = new Set(found.map((record) => record.id));
+ const missingIds = [...ids].filter((id) => !foundIds.has(id));
+
+ if (missingIds.length > 0) {
+ throw new MessageChannelException(
+ `Unknown ${objectMetadataName} id(s) on ingested participants: ${missingIds.join(', ')}`,
+ MessageChannelExceptionCode.INVALID_MESSAGE_CHANNEL_INPUT,
+ );
+ }
+ }
+
// Direction, the thread's sender column and the timeline preview all read
// the FROM participant, so a message without exactly one is rejected rather
// than silently rendering as an empty conversation.
diff --git a/packages/twenty-server/src/modules/match-participant/__tests__/match-participant.service.spec.ts b/packages/twenty-server/src/modules/match-participant/__tests__/match-participant.service.spec.ts
new file mode 100644
index 00000000000..cbdc214eb5d
--- /dev/null
+++ b/packages/twenty-server/src/modules/match-participant/__tests__/match-participant.service.spec.ts
@@ -0,0 +1,87 @@
+import { Test, type TestingModule } from '@nestjs/testing';
+
+import { WorkspaceOrmManager } from 'src/engine/twenty-orm/workspace-orm.manager';
+import { MatchParticipantService } from 'src/modules/match-participant/match-participant.service';
+import { ParticipantTargetReconciliationService } from 'src/modules/match-participant/participant-target-reconciliation.service';
+import { type MessageParticipantWorkspaceEntity } from 'src/modules/messaging/common/standard-objects/message-participant.workspace-entity';
+
+const MESSAGE_ID = '77777777-7777-4777-8777-777777777777';
+
+describe('MatchParticipantService', () => {
+ let service: MatchParticipantService<MessageParticipantWorkspaceEntity>;
+ let participantTargetReconciliationService: {
+ reconcileParticipantTargets: jest.Mock;
+ };
+ let participantRepository: { find: jest.Mock; updateMany: jest.Mock };
+
+ beforeEach(async () => {
+ participantTargetReconciliationService = {
+ reconcileParticipantTargets: jest.fn(),
+ };
+ participantRepository = {
+ find: jest.fn().mockResolvedValue([]),
+ updateMany: jest.fn().mockResolvedValue(undefined),
+ };
+
+ const module: TestingModule = await Test.createTestingModule({
+ providers: [
+ MatchParticipantService,
+ {
+ provide: WorkspaceOrmManager,
+ useValue: { getRepository: () => participantRepository },
+ },
+ {
+ provide: ParticipantTargetReconciliationService,
+ useValue: participantTargetReconciliationService,
+ },
+ ],
+ }).compile();
+
+ service = module.get(MatchParticipantService);
+ });
+
+ const aParticipant = () =>
+ ({
+ id: '88888888-8888-4888-8888-888888888888',
+ messageId: MESSAGE_ID,
+ handle: 'urn:li:person:abc',
+ personId: '66666666-6666-4666-8666-666666666666',
+ }) as unknown as MessageParticipantWorkspaceEntity;
+
+ // The whole point of the mode: a handle that is not an email address would
+ // resolve to nobody, and the matcher writes personId back to null when it
+ // finds nobody — discarding an identity the caller had already supplied.
+ it('reconciles targets without looking any handle up as an email', async () => {
+ await service.matchParticipants({
+ participants: [aParticipant()],
+ sourceRecordIds: [MESSAGE_ID],
+ objectMetadataName: 'messageParticipant',
+ matchWith: 'targetsOnly',
+ });
+
+ expect(
+ participantTargetReconciliationService.reconcileParticipantTargets,
+ ).toHaveBeenCalledWith({
+ sourceRecordIds: [MESSAGE_ID],
+ objectMetadataName: 'messageParticipant',
+ transactionScope: undefined,
+ });
+ expect(participantRepository.find).not.toHaveBeenCalled();
+ expect(participantRepository.updateMany).not.toHaveBeenCalled();
+ });
+
+ // The mode returns early; falling through would reconcile a second time at
+ // the end of the match path, for no benefit and twice the queries.
+ it('reconciles exactly once', async () => {
+ await service.matchParticipants({
+ participants: [aParticipant()],
+ sourceRecordIds: [MESSAGE_ID],
+ objectMetadataName: 'messageParticipant',
+ matchWith: 'targetsOnly',
+ });
+
+ expect(
+ participantTargetReconciliationService.reconcileParticipantTargets,
+ ).toHaveBeenCalledTimes(1);
+ });
+});
diff --git a/packages/twenty-server/src/modules/match-participant/match-participant.service.ts b/packages/twenty-server/src/modules/match-participant/match-participant.service.ts
index c550b767c97..510cead5dff 100644
--- a/packages/twenty-server/src/modules/match-participant/match-participant.service.ts
+++ b/packages/twenty-server/src/modules/match-participant/match-participant.service.ts
@@ -40,7 +40,7 @@ type MatchParticipantsForPeopleArgs = {
workspaceId: string;
};
-type MatchParticipantsArgs<
+export type MatchParticipantsArgs<
ParticipantWorkspaceEntity extends
| Pick<
CalendarEventParticipantWorkspaceEntity,
@@ -54,7 +54,11 @@ type MatchParticipantsArgs<
participants: ParticipantWorkspaceEntity[];
sourceRecordIds: string[];
objectMetadataName: ObjectMetadataName;
- matchWith: 'workspaceMemberOnly' | 'personOnly' | 'workspaceMemberAndPerson';
+ matchWith:
+ | 'workspaceMemberOnly'
+ | 'personOnly'
+ | 'workspaceMemberAndPerson'
+ | 'targetsOnly';
transactionScope?: WorkspaceTransactionScope;
};
@@ -93,6 +97,22 @@ export class MatchParticipantService<
// rematch can never change them; skip the recompute in that case.
const shouldReconcileTargets = matchWith !== 'workspaceMemberOnly';
+ // A source whose handles are not email addresses has no matching to do:
+ // looking every handle up as an email would find nothing and write
+ // personId back to null, erasing the identities the caller supplied. The
+ // targets still have to be built, so reconcile and stop there.
+ if (matchWith === 'targetsOnly') {
+ await this.participantTargetReconciliationService.reconcileParticipantTargets(
+ {
+ sourceRecordIds,
+ objectMetadataName,
+ transactionScope,
+ },
+ );
+
+ return;
+ }
+
if (participants.length === 0) {
if (shouldReconcileTargets) {
await this.participantTargetReconciliationService.reconcileParticipantTargets(
diff --git a/packages/twenty-server/src/modules/messaging/message-import-manager/drivers/gmail/types/gmail-message.type.ts b/packages/twenty-server/src/modules/messaging/message-import-manager/drivers/gmail/types/gmail-message.type.ts
index 9f8c04d9a87..0a1124cfd53 100644
--- a/packages/twenty-server/src/modules/messaging/message-import-manager/drivers/gmail/types/gmail-message.type.ts
+++ b/packages/twenty-server/src/modules/messaging/message-import-manager/drivers/gmail/types/gmail-message.type.ts
@@ -1,5 +1,7 @@
import { type MessageParticipantRole } from 'twenty-shared/types';
+import { type ExplicitParticipantIdentity } from 'src/modules/messaging/message-import-manager/types/message';
+
export type GmailMessage = {
historyId: string;
externalId: string;
@@ -18,7 +20,7 @@ export type Participant = {
role: MessageParticipantRole;
handle: string;
displayName: string;
-};
+} & ExplicitParticipantIdentity;
export type ParticipantWithMessageId = Participant & { messageId: string };
diff --git a/packages/twenty-server/src/modules/messaging/message-import-manager/services/messaging-save-messages-and-enqueue-contact-creation.service.ts b/packages/twenty-server/src/modules/messaging/message-import-manager/services/messaging-save-messages-and-enqueue-contact-creation.service.ts
index 505c0732350..c048b7fa1dc 100644
--- a/packages/twenty-server/src/modules/messaging/message-import-manager/services/messaging-save-messages-and-enqueue-contact-creation.service.ts
+++ b/packages/twenty-server/src/modules/messaging/message-import-manager/services/messaging-save-messages-and-enqueue-contact-creation.service.ts
@@ -3,6 +3,7 @@ import { Injectable } from '@nestjs/common';
import {
FieldActorSource,
MessageChannelContactAutoCreationPolicy,
+ MessageChannelType,
MessageParticipantRole,
} from 'twenty-shared/types';
import { isDefined } from 'twenty-shared/utils';
@@ -197,16 +198,26 @@ export class MessagingSaveMessagesAndEnqueueContactCreationService {
return undefined;
}
+ const messageIds = [
+ ...new Set(
+ savedMessagesResult.participantsWithMessageId.map(
+ ({ messageId }) => messageId,
+ ),
+ ),
+ ];
+
+ // The matcher resolves a participant by looking its handle up as an email
+ // address. On a channel whose handles are not email addresses that finds
+ // nothing and writes personId back to null, discarding the identities the
+ // caller supplied at save time, so those channels only reconcile targets.
await this.messageParticipantService.matchMessageParticipants({
participants: savedMessagesResult.savedMessageParticipants,
- messageIds: [
- ...new Set(
- savedMessagesResult.participantsWithMessageId.map(
- ({ messageId }) => messageId,
- ),
- ),
- ],
+ messageIds,
workspaceId,
+ matchWith:
+ messageChannel.type === MessageChannelType.APP
+ ? 'targetsOnly'
+ : 'workspaceMemberAndPerson',
});
return {
diff --git a/packages/twenty-server/src/modules/messaging/message-import-manager/types/message.ts b/packages/twenty-server/src/modules/messaging/message-import-manager/types/message.ts
index e79c47ba28f..b9299c64941 100644
--- a/packages/twenty-server/src/modules/messaging/message-import-manager/types/message.ts
+++ b/packages/twenty-server/src/modules/messaging/message-import-manager/types/message.ts
@@ -53,7 +53,16 @@ export type MessageParticipant = Omit<
| 'messageId'
| 'messageCampaign'
| 'messageCampaignId'
->;
+> &
+ ExplicitParticipantIdentity;
+
+// Email providers leave these unset and the email matcher fills them in
+// afterwards. A source whose handles are not email addresses supplies them
+// up front instead, because nothing can derive them from the handle.
+export type ExplicitParticipantIdentity = {
+ personId?: string | null;
+ workspaceMemberId?: string | null;
+};
export type MessageWithParticipants = Message & {
participants: MessageParticipant[];
diff --git a/packages/twenty-server/src/modules/messaging/message-participant-manager/services/__tests__/messaging-message-participant.service.spec.ts b/packages/twenty-server/src/modules/messaging/message-participant-manager/services/__tests__/messaging-message-participant.service.spec.ts
new file mode 100644
index 00000000000..8516b2cff28
--- /dev/null
+++ b/packages/twenty-server/src/modules/messaging/message-participant-manager/services/__tests__/messaging-message-participant.service.spec.ts
@@ -0,0 +1,304 @@
+import { Test, type TestingModule } from '@nestjs/testing';
+
+import { QUERY_MAX_RECORDS } from 'twenty-shared/constants';
+import { MessageParticipantRole } from 'twenty-shared/types';
+
+import { type WorkspaceTransactionScope } from 'src/engine/twenty-orm/types/workspace-transaction-scope.type';
+import { WorkspaceOrmManager } from 'src/engine/twenty-orm/workspace-orm.manager';
+import { MatchParticipantService } from 'src/modules/match-participant/match-participant.service';
+import { ParticipantTargetReconciliationService } from 'src/modules/match-participant/participant-target-reconciliation.service';
+import { type ParticipantWithMessageId } from 'src/modules/messaging/message-import-manager/drivers/gmail/types/gmail-message.type';
+import { MessagingMessageParticipantService } from 'src/modules/messaging/message-participant-manager/services/messaging-message-participant.service';
+
+const WORKSPACE_ID = '33333333-3333-4333-8333-333333333333';
+const MESSAGE_ID = '77777777-7777-4777-8777-777777777777';
+const PARTICIPANT_ID = '88888888-8888-4888-8888-888888888888';
+const PERSON_ID = '66666666-6666-4666-8666-666666666666';
+
+describe('MessagingMessageParticipantService', () => {
+ let service: MessagingMessageParticipantService;
+ let participantRepository: {
+ find: jest.Mock;
+ insert: jest.Mock;
+ updateMany: jest.Mock;
+ };
+ let transactionScope: WorkspaceTransactionScope;
+ let matchParticipantService: { matchParticipants: jest.Mock };
+
+ const anEmailParticipant = (): ParticipantWithMessageId => ({
+ messageId: MESSAGE_ID,
+ handle: '[email protected]',
+ displayName: 'Ada',
+ role: MessageParticipantRole.FROM,
+ });
+
+ beforeEach(async () => {
+ matchParticipantService = { matchParticipants: jest.fn() };
+ participantRepository = {
+ find: jest.fn().mockResolvedValue([]),
+ insert: jest.fn().mockResolvedValue({ identifiers: [] }),
+ updateMany: jest.fn().mockResolvedValue(undefined),
+ };
+
+ transactionScope = {
+ getRepository: () => participantRepository,
+ } as unknown as WorkspaceTransactionScope;
+
+ const module: TestingModule = await Test.createTestingModule({
+ providers: [
+ MessagingMessageParticipantService,
+ {
+ provide: WorkspaceOrmManager,
+ useValue: {
+ executeInWorkspaceContext: (callback: () => unknown) => callback(),
+ },
+ },
+ {
+ provide: MatchParticipantService,
+ useValue: matchParticipantService,
+ },
+ {
+ provide: ParticipantTargetReconciliationService,
+ useValue: { reconcileParticipantTargets: jest.fn() },
+ },
+ ],
+ }).compile();
+
+ service = module.get(MessagingMessageParticipantService);
+ });
+
+ const givenAnExistingParticipant = (personId: string | null) => {
+ participantRepository.find.mockResolvedValueOnce([
+ {
+ id: PARTICIPANT_ID,
+ messageId: MESSAGE_ID,
+ handle: '[email protected]',
+ displayName: 'Ada',
+ role: MessageParticipantRole.FROM,
+ personId,
+ workspaceMemberId: null,
+ },
+ ]);
+ };
+
+ it('inserts a new participant with a null identity when none is supplied', async () => {
+ await service.saveMessageParticipants(
+ [anEmailParticipant()],
+ WORKSPACE_ID,
+ transactionScope,
+ );
+
+ expect(participantRepository.insert).toHaveBeenCalledWith([
+ expect.objectContaining({
+ handle: '[email protected]',
+ personId: null,
+ workspaceMemberId: null,
+ }),
+ ]);
+ expect(participantRepository.updateMany).not.toHaveBeenCalled();
+ });
+
+ it('links an existing participant when the caller now knows the person', async () => {
+ givenAnExistingParticipant(null);
+
+ await service.saveMessageParticipants(
+ [{ ...anEmailParticipant(), personId: PERSON_ID }],
+ WORKSPACE_ID,
+ transactionScope,
+ );
+
+ expect(participantRepository.updateMany).toHaveBeenCalledWith([
+ {
+ criteria: PARTICIPANT_ID,
+ partialEntity: {
+ personId: PERSON_ID,
+ workspaceMemberId: null,
+ displayName: 'Ada',
+ },
+ },
+ ]);
+ });
+
+ it('leaves an existing participant alone when the caller supplies no identity', async () => {
+ givenAnExistingParticipant(PERSON_ID);
+
+ await service.saveMessageParticipants(
+ [anEmailParticipant()],
+ WORKSPACE_ID,
+ transactionScope,
+ );
+
+ expect(participantRepository.updateMany).not.toHaveBeenCalled();
+ expect(participantRepository.insert).toHaveBeenCalledWith([]);
+ });
+
+ it('does not rewrite an identity that already matches', async () => {
+ givenAnExistingParticipant(PERSON_ID);
+
+ await service.saveMessageParticipants(
+ [{ ...anEmailParticipant(), personId: PERSON_ID }],
+ WORKSPACE_ID,
+ transactionScope,
+ );
+
+ expect(participantRepository.updateMany).not.toHaveBeenCalled();
+ });
+ // The enrichment promise: ingest first, resolve the contact later. A
+ // provider that renames someone between deliveries, or omits the name,
+ // must not split the participant in two.
+ it('links the existing participant when the display name changed too', async () => {
+ givenAnExistingParticipant(null);
+
+ await service.saveMessageParticipants(
+ [{ ...anEmailParticipant(), displayName: 'Ada L.', personId: PERSON_ID }],
+ WORKSPACE_ID,
+ transactionScope,
+ );
+
+ expect(participantRepository.insert).toHaveBeenCalledWith([]);
+ expect(participantRepository.updateMany).toHaveBeenCalledWith([
+ {
+ criteria: PARTICIPANT_ID,
+ partialEntity: {
+ personId: PERSON_ID,
+ workspaceMemberId: null,
+ displayName: 'Ada L.',
+ },
+ },
+ ]);
+ });
+
+ // An omitted name reaches the service as an empty string, and this is the
+ // only branch that writes the column, so the stored one has to survive: an
+ // app adding a person link should not have to resend the name to keep it.
+ it('keeps the stored display name when the caller omits it', async () => {
+ givenAnExistingParticipant(null);
+
+ await service.saveMessageParticipants(
+ [{ ...anEmailParticipant(), displayName: '', personId: PERSON_ID }],
+ WORKSPACE_ID,
+ transactionScope,
+ );
+
+ expect(participantRepository.insert).toHaveBeenCalledWith([]);
+ expect(participantRepository.updateMany).toHaveBeenCalledWith([
+ {
+ criteria: PARTICIPANT_ID,
+ partialEntity: {
+ personId: PERSON_ID,
+ workspaceMemberId: null,
+ displayName: 'Ada',
+ },
+ },
+ ]);
+ });
+
+ // A batch is capped by messages, not participants, so one conversation with
+ // many people in it can produce more updates than updateMany accepts.
+ it('chunks identity updates past the single-call limit', async () => {
+ const participantCount = QUERY_MAX_RECORDS + 50;
+ const existingParticipants = Array.from(
+ { length: participantCount },
+ (_unused, index) => ({
+ id: `participant-${index}`,
+ messageId: MESSAGE_ID,
+ handle: `member-${index}`,
+ displayName: 'Ada',
+ role: MessageParticipantRole.FROM,
+ personId: null,
+ workspaceMemberId: null,
+ }),
+ );
+
+ participantRepository.find.mockResolvedValueOnce(existingParticipants);
+
+ await service.saveMessageParticipants(
+ existingParticipants.map(({ handle }) => ({
+ ...anEmailParticipant(),
+ handle,
+ personId: PERSON_ID,
+ })),
+ WORKSPACE_ID,
+ transactionScope,
+ );
+
+ expect(participantRepository.updateMany).toHaveBeenCalledTimes(2);
+
+ const updatedCount = participantRepository.updateMany.mock.calls.reduce(
+ (total, [updates]) => total + updates.length,
+ 0,
+ );
+
+ expect(updatedCount).toBe(participantCount);
+ participantRepository.updateMany.mock.calls.forEach(([updates]) => {
+ expect(updates.length).toBeLessThanOrEqual(QUERY_MAX_RECORDS);
+ });
+ });
+
+ it('corrects a wrong person link without leaving the old one behind', async () => {
+ const OTHER_PERSON_ID = '55555555-5555-4555-8555-555555555555';
+
+ givenAnExistingParticipant(OTHER_PERSON_ID);
+
+ await service.saveMessageParticipants(
+ [{ ...anEmailParticipant(), displayName: 'Ada L.', personId: PERSON_ID }],
+ WORKSPACE_ID,
+ transactionScope,
+ );
+
+ expect(participantRepository.insert).toHaveBeenCalledWith([]);
+ expect(participantRepository.updateMany).toHaveBeenCalledWith([
+ expect.objectContaining({
+ partialEntity: expect.objectContaining({ personId: PERSON_ID }),
+ }),
+ ]);
+ });
+
+ // Email relies on the exact match: the matcher, not the caller, sets the
+ // identity, so a renamed sender is a different participant row as before.
+ it('still inserts a new row when a caller with no identity renames a sender', async () => {
+ givenAnExistingParticipant(null);
+
+ await service.saveMessageParticipants(
+ [{ ...anEmailParticipant(), displayName: 'Ada L.' }],
+ WORKSPACE_ID,
+ transactionScope,
+ );
+
+ expect(participantRepository.insert).toHaveBeenCalledWith([
+ expect.objectContaining({ displayName: 'Ada L.', personId: null }),
+ ]);
+ expect(participantRepository.updateMany).not.toHaveBeenCalled();
+ });
+
+ it('matches with people and workspace members by default', async () => {
+ await service.matchMessageParticipants({
+ participants: [],
+ messageIds: [MESSAGE_ID],
+ workspaceId: WORKSPACE_ID,
+ });
+
+ expect(matchParticipantService.matchParticipants).toHaveBeenCalledWith(
+ expect.objectContaining({ matchWith: 'workspaceMemberAndPerson' }),
+ );
+ });
+
+ // An app channel's handles are not email addresses, so running the matcher
+ // would null out the identities the caller supplied at save time.
+ it('forwards targetsOnly so a non-email channel never runs the email matcher', async () => {
+ await service.matchMessageParticipants({
+ participants: [],
+ messageIds: [MESSAGE_ID],
+ workspaceId: WORKSPACE_ID,
+ matchWith: 'targetsOnly',
+ });
+
+ expect(matchParticipantService.matchParticipants).toHaveBeenCalledWith(
+ expect.objectContaining({
+ matchWith: 'targetsOnly',
+ sourceRecordIds: [MESSAGE_ID],
+ objectMetadataName: 'messageParticipant',
+ }),
+ );
+ });
+});
diff --git a/packages/twenty-server/src/modules/messaging/message-participant-manager/services/messaging-message-participant.service.ts b/packages/twenty-server/src/modules/messaging/message-participant-manager/services/messaging-message-participant.service.ts
index f8d1847333a..165019b2432 100644
--- a/packages/twenty-server/src/modules/messaging/message-participant-manager/services/messaging-message-participant.service.ts
+++ b/packages/twenty-server/src/modules/messaging/message-participant-manager/services/messaging-message-participant.service.ts
@@ -1,11 +1,18 @@
import { Injectable } from '@nestjs/common';
+import { isNonEmptyString } from '@sniptt/guards';
+import chunk from 'lodash.chunk';
+import { QUERY_MAX_RECORDS } from 'twenty-shared/constants';
+import { isDefined } from 'twenty-shared/utils';
import { In } from 'typeorm';
import { WorkspaceOrmManager } from 'src/engine/twenty-orm/workspace-orm.manager';
import { type WorkspaceTransactionScope } from 'src/engine/twenty-orm/types/workspace-transaction-scope.type';
import { buildSystemAuthContext } from 'src/engine/twenty-orm/utils/build-system-auth-context.util';
-import { MatchParticipantService } from 'src/modules/match-participant/match-participant.service';
+import {
+ type MatchParticipantsArgs,
+ MatchParticipantService,
+} from 'src/modules/match-participant/match-participant.service';
import { type MessageParticipantWorkspaceEntity } from 'src/modules/messaging/common/standard-objects/message-participant.workspace-entity';
import { type ParticipantWithMessageId } from 'src/modules/messaging/message-import-manager/drivers/gmail/types/gmail-message.type';
@@ -39,34 +46,124 @@ export class MessagingMessageParticipantService {
},
});
+ const suppliesIdentity = (participant: ParticipantWithMessageId) =>
+ isDefined(participant.personId) ||
+ isDefined(participant.workspaceMemberId);
+
+ // A caller that states who a participant is owns that row, so it is
+ // matched on what cannot drift between deliveries: the message, the
+ // handle and the role. Keying on displayName as well would make a
+ // provider that renames someone — or simply omits the name on a later
+ // delivery — insert a rival row instead, leaving the original behind
+ // with its stale person link and the thread attached to both records.
+ //
+ // Callers that supply no identity keep the exact match, so the email
+ // path, where the matcher fills these in afterwards, is unchanged.
+ const findExisting = (participant: ParticipantWithMessageId) =>
+ existingParticipantsBasedOnMessageIds.find(
+ (existingParticipant) =>
+ existingParticipant.messageId === participant.messageId &&
+ existingParticipant.handle === participant.handle &&
+ existingParticipant.role === participant.role &&
+ (suppliesIdentity(participant) ||
+ existingParticipant.displayName === participant.displayName),
+ );
+
+ // Paired once: the lookup is a scan of every existing row, and both
+ // the insert list and the update list below need the same answer.
+ const participantsWithExisting = participants.map((participant) => ({
+ participant,
+ existingParticipant: findExisting(participant),
+ }));
+
const participantsToCreate: Pick<
MessageParticipantWorkspaceEntity,
- 'messageId' | 'handle' | 'displayName' | 'role'
- >[] = participants
- .filter(
- (participant) =>
- !existingParticipantsBasedOnMessageIds.find(
- (existingParticipant) =>
- existingParticipant.messageId === participant.messageId &&
- existingParticipant.handle === participant.handle &&
- existingParticipant.displayName === participant.displayName &&
- existingParticipant.role === participant.role,
- ),
- )
- .map((participant) => {
+ | 'messageId'
+ | 'handle'
+ | 'displayName'
+ | 'role'
+ | 'personId'
+ | 'workspaceMemberId'
+ >[] = participantsWithExisting
+ .filter(({ existingParticipant }) => !isDefined(existingParticipant))
+ .map(({ participant }) => {
return {
messageId: participant.messageId,
handle: participant.handle,
displayName: participant.displayName,
role: participant.role,
+ personId: participant.personId ?? null,
+ workspaceMemberId: participant.workspaceMemberId ?? null,
};
});
+ // A re-ingested participant whose caller now knows the person it
+ // belongs to would otherwise keep its original, unlinked row forever.
+ // Only callers that supply an identity can trigger this, so the email
+ // path — which leaves both undefined and relies on the matcher — is
+ // untouched.
+ const identityUpdates = participantsWithExisting.flatMap(
+ ({ participant, existingParticipant }) => {
+ if (
+ !isDefined(existingParticipant) ||
+ !suppliesIdentity(participant)
+ ) {
+ return [];
+ }
+
+ const personId =
+ participant.personId ?? existingParticipant.personId;
+ const workspaceMemberId =
+ participant.workspaceMemberId ??
+ existingParticipant.workspaceMemberId;
+ // Carried along because the row is no longer matched on it: without
+ // this a rename would be silently dropped on every later delivery.
+ // An omitted name arrives as an empty string though, and this is
+ // the only branch that writes the column back, so taking that
+ // literally would erase whatever an earlier delivery supplied — a
+ // caller adding a person link should not have to resend the rest
+ // of the row to keep it.
+ const displayName = isNonEmptyString(participant.displayName)
+ ? participant.displayName
+ : existingParticipant.displayName;
+
+ if (
+ personId === existingParticipant.personId &&
+ workspaceMemberId === existingParticipant.workspaceMemberId &&
+ displayName === existingParticipant.displayName
+ ) {
+ return [];
+ }
+
+ return [
+ {
+ criteria: existingParticipant.id,
+ partialEntity: { personId, workspaceMemberId, displayName },
+ },
+ ];
+ },
+ );
+
+ // One ingested batch is bounded by messages, not by participants, so
+ // a conversation with many people in it can exceed what updateMany
+ // accepts in a single call.
+ for (const identityUpdatesChunk of chunk(
+ identityUpdates,
+ QUERY_MAX_RECORDS,
+ )) {
+ await messageParticipantRepository.updateMany(identityUpdatesChunk);
+ }
+
const { identifiers } =
await messageParticipantRepository.insert(participantsToCreate);
+ const touchedIds = [
+ ...identifiers.map(({ id }) => id),
+ ...identityUpdates.map(({ criteria }) => criteria),
+ ];
+
return messageParticipantRepository.find({
- where: { id: In(identifiers.map(({ id }) => id)) },
+ where: { id: In(touchedIds) },
});
},
authContext,
@@ -78,10 +175,12 @@ export class MessagingMessageParticipantService {
participants,
messageIds,
workspaceId,
+ matchWith = 'workspaceMemberAndPerson',
}: {
participants: MessageParticipantWorkspaceEntity[];
messageIds: string[];
workspaceId: string;
+ matchWith?: MatchParticipantsArgs<MessageParticipantWorkspaceEntity>['matchWith'];
}): Promise<void> {
const authContext = buildSystemAuthContext(workspaceId);
@@ -91,7 +190,7 @@ export class MessagingMessageParticipantService {
participants,
sourceRecordIds: messageIds,
objectMetadataName: 'messageParticipant',
- matchWith: 'workspaceMemberAndPerson',
+ matchWith,
});
},
authContext,