useMessages
Read and send private messages within one DM thread in a built app.
import { useMessages } from 'flowstack-sdk'Reads and sends private messages in a single thread with withUserKey. Mirrors useCollection's ergonomics but is backed by the server-owned, ACL'd DM endpoints instead of a Mongo collection. The backend pins the sender to the caller's identity and only delivers into a mutually-consented (open) thread, so send() to a not-yet-open thread returns an error.
Private messaging is a built-app capability: it requires an appScope on the FlowstackProvider config. Treat the type signatures in packages/flowstack-sdk/src/hooks/useMessages.ts as the source of truth.
Signature
const { messages, send, isLoading, error, refresh } = useMessages(withUserKey, options?)Parameters
| Param | Type | Notes | Description |
|---|---|---|---|
withUserKey | string | null | undefined | required, since 0.2.2 | The counterpart's user key. When null/undefined the hook stays idle (no fetch). |
options.limit | number | default 50, since 0.2.2 | Max messages to load (max 200). |
options.refreshInterval | number | since 0.2.2 | Auto-poll interval in ms. No polling by default. |
options.enabled | boolean | default true, since 0.2.2 | Set false to skip the initial fetch (e.g. before a counterpart is selected). |
Returns
| Field | Type | Description |
|---|---|---|
messages | DmMessage[] | Messages in the thread — each { message_id, from, to, body, created_at, read_at }. |
send | (body: string) => Promise<void> | Send a message to the counterpart. Refetches on success; throws if the thread is not yet mutually open. |
isLoading | boolean | True while a fetch is in flight. |
error | string | null | Error message from the last failed load or send. |
refresh | () => Promise<void> | Refetch the message list. |
Examples
const { messages, send } = useMessages(counterpartUserKey, { refreshInterval: 4000 });
await send('hey there');
messages.map((m) => (
<Bubble key={m.message_id} mine={m.from === myKey}>{m.body}</Bubble>
));dangerouslySetInnerHTML). If a body is ever passed to an agent, treat it as data, not instructions.send() throws if the thread is not mutually open. Call openThread() (from useThreads) first and wait until both parties consent.See also
useThreads · sendMessage · listMessages · DmMessage
Source: README.md#private-messaging-dms · Also available in llms-full.txt and registry.json.