Composer remote control
Operate the chat composer from pages and modules outside the chat — write content, show suggestions, lock the composer, open a conversation. One per host, i.e. host.controller.
Composer remote control
Pages and other modules (for example "Discuss this issue" on an issue page, or page suggestions) operate the chat composer through the composer remote control: first say which conversation, then write content, show suggestions, lock the composer, focus it or open the conversation. Callers never touch the editor; content is a list of parts, not HTML.
Every host created by createChatHost holds one remote control, host.controller. ChatProvider hands it to its subtree: inside the provider useChatController() returns the same object, and CwsMessageThread registers its composer with it when a conversation mounts. Two hosts on one page have separate remote controls. The hooks and types are re-exported from @openmaxai/chat/controller: the hooks from @openmaxai/chat-sdk/react, the types from @openmaxai/chat-sdk.
When to use
- A page outside the chat puts content into a conversation's composer, for example inserting an issue reference into the direct conversation with an Agent.
- A page shows a few suggestions above a conversation's composer; clicking one fills the composer.
- A flow locks the composer while it runs.
You don't need it to operate the composer from inside the chat components.
How to use
discuss-issue.tsx
import { useChatControllerScope } from "@openmaxai/chat-sdk/react";
function DiscussIssueButton({ conversationId, issue }: Props) {
const scope = useChatControllerScope("discuss-issue");
const discuss = async () => {
const handle = scope.conversation({ conversationId });
const result = await handle.composer.insert(
[{ type: "work-reference", item: issue }],
{ newParagraph: true },
);
if (result.ok) await handle.composer.focus();
};
return <button onClick={discuss}>Discuss this issue</button>;
}
- The conversation is mounted (
CwsMessageThreadis showing it): written straight into the composer. - Not mounted: written into the host's
draftsfirst, then opened throughhost.openConversation, landing where it lands: handed to the listener the page mounts withuseChatSdkOpenConversation; once the message area mounts, the composer holds what was written. - Nothing takes the open (the page has not mounted
useChatSdkOpenConversation): the draft is written and the result is{ ok: false, kind: "not_found", reason: "not_open" }; mounting the conversation in this host later still shows what was written. - No operation throws; the result is
{ ok: true }or{ ok: false, kind, reason }, withkindfrom the same set asChatSdkError. - When the host is
dispose()d, the remote control's current scopes end: their locks and suggestions are removed and pending operations getcancelled / scope_disposed. It is not final: for a host disposed in an effect cleanup and mounted again (React StrictMode,<Activity>), the page modules' scopes come back with their effects and register their locks and suggestions again. When the adapter's scope ends (another user, another organization), only pending operations end.
Placement and the current conversation: a conversation mounted in the message area reports "primary"; after the user clicks, types or focuses in the message area, { active: true } means the conversation the message area shows now. Addressing by { memberId } finds or creates the direct conversation through the adapter's directMessages and opens it; without that member on the adapter it returns unavailable / open_failed.
Hooks
useChatController
This host's remote control, i.e. host.controller. Call it inside ChatProvider.
useChatControllerScope
A scope with an owner. The owner name is recorded as the source; unmounting removes the locks and suggestions it registered and ends its pending operations.
useChatConversationHandle
A handle to one conversation and where it is open now (primary, or null when not open).
useChatConversationState
What an address resolves to now and where it is open; changes as conversations open and close.
useChatLock
Lock the composer declaratively: no lock while reason is null; unmounting or a new reason removes the previous lock.
useChatSuggestions
Register suggestions above a conversation's composer declaratively; compared by content, so a new array on every render does not register again.
Types
Import from @openmaxai/chat-sdk (types only, no React): ChatController, ChatControllerScope, ChatConversationHandle, ChatComposerHandle, ChatSuggestionsHandle, ChatAddress, ChatAddressOptions, ChatOpenTarget, ChatOpenResult, ChatComposerContent, ChatComposerPart, ChatComposerPartType, ChatInsertPosition, ChatSuggestion, ChatSuggestionAction, ChatSuggestionContext, ChatSuggestionOptions, ChatControllerResult, ChatControllerFailure, ChatControllerErrorKind, ChatControllerReason, ChatReadOnlyReason, ChatControllerSnapshot, ChatControllerEvent, ChatConversationState, ChatConversationPlacement.
