sitemap.xml llms.txt
Skip to main content

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 a 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:

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

Parameters​

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 a chat​

Retrieves a chat by its unique key.

Permissions​

Requires a role of PARTICIPANT or higher.

Function description​

The get() function:

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:

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:

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 a 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 a 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 a 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 }
);