Skip to main content

getConversationTitle()

function getConversationTitle(args: {
conversation: Pick<Conversation, "title" | "userIds" | "private">;
currentUserId: number;
maxNames?: number;
users: readonly Pick<{
avatarUrls?: | {
s195: string;
s35: string;
s60: string;
s640: string;
}
| null;
dateFormat?: string | null;
email?: string | null;
firstName?: string | null;
fullName: string;
id: number;
imageId?: string | null;
removed: boolean;
restricted?: boolean | null;
setupPending?: boolean | null;
shortName: string;
status?: | {
activeUntil?: string | null;
effects?: {
pauseActivity?: {
scope?: ... | ...;
};
pauseNotifications?: {
scope?: ... | ...;
};
};
emoji?: string | null;
message?: string | null;
}
| null;
theme?: number | null;
timeFormat?: string | null;
timezone: string;
userType: "USER" | "GUEST" | "ADMIN";
version: number;
}, "id" | "fullName" | "shortName" | "removed">[];
}): ConversationTitle;

Works out the title a conversation shows, as the current user sees it.

  • A title with something visible in it wins: custom.
  • A 1:1 shows the other person's full name: one_to_one.
  • A group shows the others' short names in alphabetical order, ignoring case and accents: group. Past maxNames, it counts the rest in othersCount, though a single person over is named instead.
  • People removed from the workspace drop out of a group but stay in a 1:1.
  • A group down to you and one other person sets includesYou. Down to you alone, it shows your full name: yourself.
  • With no name to show, the type is untitled.

private only tells a 1:1 from a group of two. Without it, as on a search result, two people read as a 1:1. Past two people the count decides, since chats imported from Twist can be private with three people in them.

Someone in userIds who isn't in users reads as a name that hasn't loaded, so a group counts them rather than naming them.

The wording stays with the caller: join names, "N more" for othersCount and "you" for includesYou with a list formatter in the user's language.

Parameters​

ParameterTypeDescription
args{ conversation: Pick<Conversation, "title" | "userIds" | "private">; currentUserId: number; maxNames?: number; users: readonly Pick<{ avatarUrls?: | { s195: string; s35: string; s60: string; s640: string; } | null; dateFormat?: string | null; email?: string | null; firstName?: string | null; fullName: string; id: number; imageId?: string | null; removed: boolean; restricted?: boolean | null; setupPending?: boolean | null; shortName: string; status?: | { activeUntil?: string | null; effects?: { pauseActivity?: { scope?: ... | ...; }; pauseNotifications?: { scope?: ... | ...; }; }; emoji?: string | null; message?: string | null; } | null; theme?: number | null; timeFormat?: string | null; timezone: string; userType: "USER" | "GUEST" | "ADMIN"; version: number; }, "id" | "fullName" | "shortName" | "removed">[]; }The arguments for working out the title.
args.conversationPick<Conversation, "title" | "userIds" | "private">The conversation's title, userIds and private flag.
args.currentUserIdnumberThe ID of the user viewing the conversation.
args.maxNames?numberHow many names a group shows before it counts the rest. Defaults to 3, as the Comms apps show. Anything below 1 counts as 1.
args.usersreadonly Pick<{ avatarUrls?: | { s195: string; s35: string; s60: string; s640: string; } | null; dateFormat?: string | null; email?: string | null; firstName?: string | null; fullName: string; id: number; imageId?: string | null; removed: boolean; restricted?: boolean | null; setupPending?: boolean | null; shortName: string; status?: | { activeUntil?: string | null; effects?: { pauseActivity?: { scope?: ... | ...; }; pauseNotifications?: { scope?: ... | ...; }; }; emoji?: string | null; message?: string | null; } | null; theme?: number | null; timeFormat?: string | null; timezone: string; userType: "USER" | "GUEST" | "ADMIN"; version: number; }, "id" | "fullName" | "shortName" | "removed">[]The users to take names from. Include people removed from the workspace, so a group can leave them out rather than count them.

Returns​

ConversationTitle

A new title on every call.

Example​

const users = await api.workspaceUsers.getWorkspaceUsers({
workspaceId: 123,
includeRemoved: true,
})
const title = getConversationTitle({ conversation, users, currentUserId: me.id })
// { type: 'group', names: ['Bob J.', 'Cara S.', 'Dan B.'], othersCount: 2, includesYou: false }