Chat Functions

Use the Chat adapter to manage chat rooms.

Importing the adapter

To use the functions of the Chat adapter, import it as shown:

import { chatAdapter } from 'epicenter-libs';

The chatAdapter namespace exports functions that make calls to the Chat API.

learn more

For descriptions of the objects used by the Chat adapter functions, read Chat entities.

---

Create

Create chat

Creates a new chat with the provided name, scope, and permit.

note

The chat name provided in the room argument must be unique for the scope.

Permissions

Requires a role of PARTICIPANT or higher.

Function description

The create() function:

• Accepts optional routing options to customize the API call.
• Constructs a POST request to the /chat endpoint.
• Returns the newly created ChatReadOutView object.

Function signature

export async function create(
    room: string,
    scope: GenericScope,
    permit: Permit,
    optionals: RoutingOptions = {},
): Promise<ChatReadOutView>

Parameters

• room (string): Name of the chat. Must be unique for the scope.
• scope (GenericScope): Scope of the chat. Must not be user specific.
• permit (Permit): A permit for the chat.
• optionals (RoutingOptions, optional): Network call option overrides.

Return value

A promise that resolves to a ChatReadOutView object describing the newly created chat.

Usage example

import { chatAdapter, SCOPE_BOUNDARY, ROLE } from 'epicenter-libs';

await chatAdapter.create(
  'my-chat-room',
  { scopeBoundary: SCOPE_BOUNDARY.GROUP, scopeKey: '00000165ad4e6a3cd22b993340b569486321' },
  { readLock: ROLE.PARTICIPANT, writeLock: ROLE.PARTICIPANT }
);

---

Retrieve

Get chat

Retrieves a chat by its unique key.

Permissions

Requires a role of PARTICIPANT or higher.

Function description

The get() function:

• Accepts optional routing options to customize the network call.
• Constructs a GET request to the /chat/{CHAT_KEY} endpoint.
• Returns the corresponding ChatReadOutView object.

Function signature

export async function get(
    chatKey: string,
    optionals: RoutingOptions = {},
): Promise<ChatReadOutView>

Parameters

• chatKey (string): The unique key identifying the chat.
• optionals (RoutingOptions, optional): Network call option overrides.

Return value

A promise that resolves to the corresponding ChatReadOutView object.

Usage example

import { chatAdapter } from 'epicenter-libs';

await chatAdapter.get('00000165ad4e6a3cd22b993340b658423159');

---

Query for chats

Searches for chats based on the provided search criteria, returning a paginated list.

learn more

For reference on search filters, read Filter and sort syntax.

Permissions

Requires a role of ANONYMOUS or higher.

Function description

The query() function:

• Accepts optional routing options to customize the API call.
• Supports filtering, sorting, and pagination through GenericSearchOptions.
• Constructs a GET request to the /chat/search endpoint with query parameters.
• Returns a paginated list of ChatReadOutView objects.

Function signature

export async function query(
    searchOptions: GenericSearchOptions,
    optionals: RoutingOptions = {},
): Promise<Page<ChatReadOutView>>

Parameters

• searchOptions (GenericSearchOptions): Options for filtering and sorting the search.
  • filter (string[], optional): Array of filter conditions. Multiple conditions can be combined.
  • sort (string[], optional): Array of sorting criteria.
  • first (number, optional): The index of the first item to return (default is 0).
  • max (number, optional): The maximum number of items per page.
• optionals (RoutingOptions, optional): Network call options overrides.

Return value

A promise that resolves to a paginated list of ChatReadOutView objects containing the chats found.

Usage example

import { chatAdapter } from 'epicenter-libs';

await chatAdapter.query({
  filter: [
    'room|=my-chat-room|my-other-chat|room-three',
    'scopeBoundary=GROUP',
    'created>=2022-01-03T20:30:53.054Z',
  ],
  sort: ['+chat.created'],
  first: 3,
  max: 10,
});

---

Update

The only property of a chat that can be updated is its permit, which controls who has read and/or write permissions to the chat.

Manage chat access

To update the permit for a chat, call the updatePermit() function.

Permissions

Requires a role of PARTICIPANT or higher.

Function description

The updatePermit() function:

• Accepts optional routing options to customize the API call.
• Constructs a PATCH request to the /chat/{CHAT_KEY} endpoint.
• Returns the updated ChatReadOutView object.

Function signature

export async function updatePermit(
    chatKey: string,
    permit: Permit,
    optionals: RoutingOptions = {},
): Promise<ChatReadOutView>

Parameters

• chatKey (string): The unique key identifying the chat.
• permit (Permit): The new permit.
• optionals (RoutingOptions, optional): Network call options overrides.

Return value

A promise that resolves to ChatReadOutView object describing the updated chat.

Usage example

import { chatAdapter, ROLE } from 'epicenter-libs';

await chatAdapter.updatePermit(
  '0000018d61f1217b22ce0ae605ff00659e3u',
  { readLock: ROLE.PARTICIPANT, writeLock: ROLE.PARTICIPANT }
);

---

Chat messages

Send message

Sends a message to a chat.

The sendMessage() function offers two options:

• Send a message to all users in the chat room.
• Send a private message to one of the users in the chat room.

tip

To send the message only to a specific user, pass the optional userKey parameter.

Permissions

Requires a role of PARTICIPANT or higher.

Function description

The sendMessage() function:

• Accepts optional routing options, including a userKey for private messages.
• Constructs a PUT request to either:
  • /chat/message/{CHAT_KEY} for public messages, or
  • /chat/message/{CHAT_KEY}/{USER_KEY} for private messages.
• Returns the created ChatMessageReadOutView object.

Function signature

export async function sendMessage(
    chatKey: string,
    message: string,
    optionals: { userKey?: string } & RoutingOptions = {},
): Promise<ChatMessageReadOutView>

Parameters

• chatKey (string): The unique key identifying the chat to send the message to.
• message (string): The text of the message to send.
• optionals ({ userKey?: string } & RoutingOptions, optional):
  • userKey? (string): If provided, sends the message privately to the specified user. Otherwise, the message is visible to everyone in the chat.
  • RoutingOptions: Network call options overrides.

Return value

A promise that resolves to the created ChatMessageReadOutView object.

Usage example

import { chatAdapter } from 'epicenter-libs';

// Send a public message to a chat
await chatAdapter.sendMessage('0000017dd3bf540e5ada5b1e058f08f20461', 'hello');

// Send a private message to a specific user within the chat
await chatAdapter.sendMessage(
  '0000017dd3bf540e5ada5b1e058f08f20461',
  'hello, privately',
  { userKey: '000001796733eef0842f4d6d960997018a33' }
);

---

Send message as admin

To send a message to a chat as an admin, call the sendMessageAdmin() function. This endpoint requires elevated authentication.

Permissions

Requires a role of SUPPORT or higher.

Function description

The sendMessageAdmin() function:

• Accepts optional routing options, including a userKey for private messages.
• Constructs a PUT request to either:
  • /chat/message/system/{CHAT_KEY} for public system messages, or
  • /chat/message/system/{CHAT_KEY}/{USER_KEY} for private system messages.
• Sends the message text as a system/admin message.
• Returns the created ChatMessageReadOutView object.

Function signature

export async function sendMessageAdmin(
    chatKey: string,
    message: string,
    optionals: { userKey?: string } & RoutingOptions = {},
): Promise<ChatMessageReadOutView>

Parameters

• chatKey (string): The unique key identifying the chat.
• message (string): The message text to send.
• optionals ({ userKey?: string } & RoutingOptions, optional):
  • userKey? (string): If provided, sends the message privately to the specified user.
  • RoutingOptions: Network call options overrides.

Return value

A promise that resolves to a ChatMessageReadOutView object.

Usage example

import { chatAdapter } from 'epicenter-libs';

// Send a public system message
await chatAdapter.sendMessageAdmin(
  '0000017dd3bf540e5ada5b1e058f08f20461',
  'hello'
);

// Send a private system message
await chatAdapter.sendMessageAdmin(
  '0000017dd3bf540e5ada5b1e058f08f20461',
  'hello, privately',
  { userKey: '000001796733eef0842f4d6d960997018a33' }
);

---

Get messages

Retrieves messages from a chat.

Permissions

Requires a role of PARTICIPANT or higher.

Function description

The getMessages() function:

• Accepts optional routing options, including message‑specific parameters.
• Constructs a GET request to the /chat/message/{CHAT_KEY} endpoint.
• Supports retrieving a fixed number of messages (maxRecords) starting from a given message ID (horizon), working backward.
• Returns a list of ChatMessageReadOutView objects.

Function signature

export async function getMessages(
    chatKey: string,
    optionals: {
        maxRecords?: number;
        horizon?: number;
    } & RoutingOptions = {},
): Promise<ChatMessageReadOutView[]>

Parameters

• chatKey (string): The unique key identifying the chat.
• optionals ({ maxRecords?: number; horizon?: number; } & RoutingOptions, optional): Optional arguments, including network call option overrides.
  • maxRecords (number, optional): Maximum number of messages to retrieve.
  • horizon (number, optional): The message ID to start from. Messages are retrieved in reverse order from this ID.

Return value

A promise that resolves to a list of ChatMessageReadOutView objects.

Usage example

import { chatAdapter } from 'epicenter-libs';

// Get the chat message with id: 5
await chatAdapter.getMessages(
  '0000017dd3bf540e5ada5b1e058f08f20461',
  { horizon: 5, maxRecords: 1 }
);

// Get the 10 chat messages starting from id 5 (inclusive)
await chatAdapter.getMessages(
  '0000017dd3bf540e5ada5b1e058f08f20461',
  { horizon: 5, maxRecords: 10 }
);

---

Get messages for specific user

To retrieve messages for a specific user within a chat, call the getMessagesForUser() function.

Permissions

Requires a role of FACILITATOR or higher.

Function description

The getMessagesForUser() function:

• Accepts optional routing options, including message‑specific parameters.
• Constructs a GET request to the /chat/message/{CHAT_KEY}/{PSEUDONYM_KEY} endpoint.
• Supports retrieving a fixed number of messages (maxRecords) starting from a given message ID (horizon), working backward.
• Returns the list of retrieved chat messages for the specified user.

Function signature

export async function getMessagesForUser(
    chatKey: string,
    pseudonymKey: string,
    optionals: {
        maxRecords?: number;
        horizon?: number;
    } & RoutingOptions = {},
): Promise<ChatMessageReadOutView[]>

Parameters

• chatKey (string): The unique key identifying the chat.
• pseudonymKey (string): The key identifying the user whose messages should be retrieved.
• optionals ({ maxRecords?: number; horizon?: number } & RoutingOptions, optional):
  • maxRecords? (number): Maximum number of messages to return.
  • horizon? (number): Message ID to start from.
    • Retrieval works backward from this ID.
    • If omitted, the platform uses the most recent message.
  • RoutingOptions: Network call options overrides.

Return value

A promise that resolves to a list of ChatMessageReadOutView objects.

Usage example

import { chatAdapter } from 'epicenter-libs';

// Get the message with ID 5 for a specific user
const message = await chatAdapter.getMessagesForUser(
  '0000017dd3bf540e5ada5b1e058f08f20461',
  '000001796733eef0842f4d6d960997018a33',
  { horizon: 5, maxRecords: 1 }
);

// Get 10 messages starting from ID 5 (inclusive), working backward
const messages = await chatAdapter.getMessagesForUser(
  '0000017dd3bf540e5ada5b1e058f08f20461',
  '000001796733eef0842f4d6d960997018a33',
  { horizon: 5, maxRecords: 10 }
);

Get messages as admin

To retrieve all messages from a chat as an admin, call the getMessagesAdmin() function. This endpoint requires elevated authentication.

Permissions

Requires a role of SUPPORT or higher.

Function description

The getMessagesAdmin() function:

• Accepts optional routing options, including message‑specific parameters.
• Constructs a GET request to the /chat/message/all/{CHAT_KEY} endpoint.
• Supports retrieving a fixed number of messages (maxRecords) starting from a given message ID (horizon), working backward.

Function signature

export async function getMessagesAdmin(
    chatKey: string,
    optionals: {
        maxRecords?: number;
        horizon?: number;
    } & RoutingOptions = {},
): Promise<ChatMessageReadOutView[]>

Parameters

• chatKey (string): The unique key identifying the chat.
• optionals ({ maxRecords?: number; horizon?: number } & RoutingOptions, optional):
  • maxRecords? (number): Maximum number of messages to return.
  • horizon? (number): Message ID to start from.
    • Retrieval works backward from this ID.
    • If omitted, the platform uses the most recent message.
  • RoutingOptions: Network call options overrides.

Return value

A promise that resolves to a list of ChatMessageReadOutView objects.

Usage example

import { chatAdapter } from 'epicenter-libs';

// Get the message with ID 5
const message = await chatAdapter.getMessagesAdmin(
  '0000017dd3bf540e5ada5b1e058f08f20461',
  { horizon: 5, maxRecords: 1 }
);

// Get 10 messages starting from ID 5 (inclusive), working backward
const messages = await chatAdapter.getMessagesAdmin(
  '0000017dd3bf540e5ada5b1e058f08f20461',
  { horizon: 5, maxRecords: 10 }
);