Package Reference

API Integration

The package ships its own Axios-based REST client, pointed at the apiUrl you provide. You can pass additional query-string parameters into any of its GET (and optionally POST/PATCH) requests without forking the package.

Required backend endpoints

The client-side chat UI expects your backend to expose REST endpoints for the following operations (paths shown are the package's internal defaults):

Key	Endpoint	Purpose
login	POST /user/login/client-user	Client-user authentication (JWT exchange)
users	GET /user/list	List selectable users for new chats
conversations	GET /conversation/list	List the logged-in user's conversations
conversationInfo	GET /conversation/get/information/:id	Conversation/channel details
messages	GET /message/get-all-from-conversation	Paginated message history
pinnedMessages	GET /message/pinned-messages	Pinned messages for a conversation
starredMessages	GET /message/starred-messages	Starred messages for the user
searchMessages	GET /message/search-messages	In-chat message search
searchMessagesContext	GET /message/searched-message/context	Context around a search hit
createGroup	POST /conversation/create-group	Create a new group conversation
updateGroupPermissions	PATCH /conversation/update-group-permissions	Update who can post, edit, or manage the group
updateGroupInfo	PATCH /conversation/update-group-info	Update group name, avatar, or description
manageMembers	PATCH /conversation/manage-members	Add or remove group members
manageAdmins	PATCH /conversation/manage-admins	Promote or demote group admins
blockUnblock	POST /user/block-unblock	Block or unblock another user
presignedUrls	GET /attachment/presigned-url	Request an S3 presigned URL for attachment upload

Passing extra query parameters

By default, queryParams apply only to GET requests (queryParamApis defaults to ['get']). Login and other write operations are unaffected unless you opt in with queryParamApis={['all']}.

Pattern 1 — same params on every GET request

Use when every GET call should receive the same extra keys (for example a branch or tenant id). Write operations stay untouched unless you change queryParamApis.

Request	Resulting query string
GET /user/list	?branchId=12
GET /conversation/list	?limit=20&page=1&branchId=12
GET /message/get-all-from-conversation	?conversationId=...&limit=...&branchId=12
POST /user/login/client-user	(no extra query params)

tsx

<ChatMain
  {...chatConfig}
  queryParams={{ branchId: "12" }}
  // queryParamApis default = ['get']
/>

Pattern 2 — different params per GET endpoint

Prefer queryParamsByApi when each endpoint needs its own filters. Keys must match the API key table above (for example conversations, messages, presignedUrls).

tsx

<ChatMain
  {...chatConfig}
  queryParamsByApi={{
    conversations: { branchId: "12" },
    messages: { locale: "en" },
    users: { orgId: "x" },
  }}
/>

Pattern 3 — params on a single endpoint only

Narrow shared queryParams to one API by setting queryParamApis to that key instead of the default ['get'].

tsx

<ChatMain
  {...chatConfig}
  queryParams={{ branchId: "12" }}
  queryParamApis={["conversations"]}
/>

Combining shared and per-API params

Result: conversations receives ?tenant=abc&branchId=12; messages receives ?tenant=abc&locale=en.

tsx

<ChatMain
  {...chatConfig}
  queryParams={{ tenant: "abc" }}
  queryParamApis={["conversations", "messages"]}
  queryParamsByApi={{
    conversations: { branchId: "12" },
    messages: { locale: "en" },
  }}
/>

queryParamApis values

Value	Meaning
['get']	Default. All GET endpoints in the table above
['all']	Every apiClient request — GET, POST, and PATCH
Specific keys, e.g. ['conversations']	Only the listed endpoints

All valid queryParamsByApi keys

queryParamsByApi accepts an object keyed by API identifier. The 16 keys below are the complete list of identifiers it recognizes — every REST call the package makes is addressable by one of these keys.

#	Key
1	login
2	users
3	conversations
4	conversationInfo
5	messages
6	pinnedMessages
7	starredMessages
8	searchMessages
9	searchMessagesContext
10	createGroup
11	updateGroupPermissions
12	updateGroupInfo
13	manageMembers
14	manageAdmins
15	blockUnblock
16	presignedUrls

tsx

// Correct — specific keys inside queryParamsByApi
queryParamsByApi={{
  conversations: { branchId: "12" },
  createGroup: { orgId: "x" },
  presignedUrls: { bucket: "chat-uploads" },
}}

// Correct — 'all' / 'get' used only with queryParamApis
queryParamApis={["all"]}   // every request receives queryParams
queryParamApis={["get"]}   // default: every GET request receives queryParams

// Incorrect — 'all' / 'get' are not queryParamsByApi keys
queryParamsByApi={{ all: { branchId: "12" } }}   // ignored

Imperative helpers

Prefer the ChatMain props when the values are known at render time. Use these setters when credentials or filters arrive asynchronously after mount (for example after a host-app login completes) and you need to update the shared API client without remounting the whole tree.

tsx

import {
  setChatQueryParams,
  setChatQueryParamApis,
  setChatQueryParamsByApi,
} from "@realtimexsco/live-chat";

setChatQueryParams({ branchId: "12" });
setChatQueryParamApis(["conversations"]);
setChatQueryParamsByApi({ messages: { locale: "en" } });

Key

Endpoint

Purpose

POST /user/login/client-user

Client-user authentication (JWT exchange)

users

GET /user/list

List selectable users for new chats

conversations

GET /conversation/list

List the logged-in user's conversations

conversationInfo

GET /conversation/get/information/:id

Conversation/channel details

messages

GET /message/get-all-from-conversation

Paginated message history

pinnedMessages

GET /message/pinned-messages

Pinned messages for a conversation

starredMessages

GET /message/starred-messages

Starred messages for the user

searchMessages

GET /message/search-messages

In-chat message search

searchMessagesContext

GET /message/searched-message/context

Context around a search hit

createGroup

POST /conversation/create-group

Create a new group conversation

updateGroupPermissions

PATCH /conversation/update-group-permissions

Update who can post, edit, or manage the group

updateGroupInfo

PATCH /conversation/update-group-info

Update group name, avatar, or description

manageMembers

PATCH /conversation/manage-members

Add or remove group members

manageAdmins

PATCH /conversation/manage-admins

Promote or demote group admins

blockUnblock

POST /user/block-unblock

Block or unblock another user

presignedUrls

GET /attachment/presigned-url

Request an S3 presigned URL for attachment upload

Request

Resulting query string

GET /user/list

?branchId=12

GET /conversation/list

?limit=20&page=1&branchId=12

GET /message/get-all-from-conversation

?conversationId=...&limit=...&branchId=12

POST /user/login/client-user

(no extra query params)

<ChatMain {...chatConfig} queryParams={{ tenant: "abc" }} queryParamApis={["conversations", "messages"]} queryParamsByApi={{ conversations: { branchId: "12" }, messages: { locale: "en" }, }} />

Value

Meaning

['get']

Default. All GET endpoints in the table above

['all']

Every apiClient request — GET, POST, and PATCH

Specific keys, e.g. ['conversations']

Only the listed endpoints

Key

users

conversations

conversationInfo

messages

pinnedMessages

starredMessages

searchMessages

searchMessagesContext

createGroup

updateGroupPermissions

updateGroupInfo

manageMembers

manageAdmins

blockUnblock

presignedUrls

// Correct — specific keys inside queryParamsByApi queryParamsByApi={{ conversations: { branchId: "12" }, createGroup: { orgId: "x" }, presignedUrls: { bucket: "chat-uploads" }, }} // Correct — 'all' / 'get' used only with queryParamApis queryParamApis={["all"]} // every request receives queryParams queryParamApis={["get"]} // default: every GET request receives queryParams // Incorrect — 'all' / 'get' are not queryParamsByApi keys queryParamsByApi={{ all: { branchId: "12" } }} // ignored

import { setChatQueryParams, setChatQueryParamApis, setChatQueryParamsByApi, } from "@realtimexsco/live-chat"; setChatQueryParams({ branchId: "12" }); setChatQueryParamApis(["conversations"]); setChatQueryParamsByApi({ messages: { locale: "en" } });