ThreadImpl - Photon

Thread interface with support for custom state. Extends Postable for shared message posting capabilities.

class ThreadImpl implements Thread<TState>

Constructor

ThreadImpl(config: ThreadImplConfig): ThreadImpl<TState>

Parameters

ThreadImplConfig

required

Returns

ThreadImpl

Properties

Adapter

required

The adapter this entity belongs to

AsyncIterable<Message<unknown>>

required

Type: MessageAsync iterator for all messages in the thread. Messages are yielded in chronological order (oldest first). Automatically handles pagination.

Channel<TState>

required

Type: ChannelGet the Channel containing this thread

string

required

Channel/conversation ID

ChannelVisibility

required

The visibility scope of this channel

string

required

Unique ID

boolean

required

Whether this is a direct message conversation

AsyncIterable<Message<unknown>>

required

Type: MessageIterate messages newest first (backward from most recent). Auto-paginates lazily — only fetches pages as consumed.

Message<unknown>[]

required

Type: MessageRecently fetched messages (cached)

AbortSignal

required

Aborted when the platform or application stops the active turn.Pass this to AI/model APIs so cancellation stops upstream generation, not only message delivery.

Promise<TState | null>

required

Get the current state. Returns null if no state has been set.

Methods

WORKFLOW_DESERIALIZE

[WORKFLOW_DESERIALIZE](data: SerializedThread): ThreadImpl

Deserialize a ThreadImpl from @workflow/serde. Uses lazy adapter resolution from Chat.getSingleton(). Requires chat.registerSingleton() to have been called.

Parameters

SerializedThread

required

Returns

ThreadImpl

WORKFLOW_SERIALIZE

[WORKFLOW_SERIALIZE](instance: ThreadImpl): SerializedThread

Serialize a ThreadImpl instance for @workflow/serde. This static method is automatically called by workflow serialization.

Parameters

ThreadImpl

required

Returns

SerializedThread

createSentMessageFromMessage()

createSentMessageFromMessage(message: Message): SentMessage

Wrap a Message object as a SentMessage with edit/delete capabilities. Used internally for reconstructing messages from serialized data.

Parameters

Message

required

Returns

SentMessage

fromJSON()

fromJSON(json: SerializedThread, adapter?: Adapter<unknown, unknown>, chat?: ChatSingleton): ThreadImpl<TState>

Reconstruct a Thread from serialized JSON data. Reconstructs a ThreadImpl from serialized data. Uses lazy resolution from Chat.getSingleton() for adapter and state.

const thread = ThreadImpl.fromJSON(serializedThread);

Parameters

SerializedThread

required

Serialized thread data

Adapter<unknown, unknown>

Type: Adapter

ChatSingleton

Returns

ThreadImpl

getParticipants()

getParticipants(): Promise<Author[]>

Get the unique human participants in this thread. Scans all messages in the thread and returns deduplicated authors, excluding the bot itself. Useful for deciding whether to subscribe based on how many humans are participating — subscribe when it’s a 1:1 conversation, unsubscribe when others join so humans can talk without the bot replying to every message.

// Subscribe only when one person is talking to the bot
bot.onNewMention(async (thread, message) => {
  const participants = await thread.getParticipants();
  if (participants.length === 1) {
    await thread.subscribe();
    await thread.post("I'm here to help!");
  }
});

// Unsubscribe when the thread becomes a group conversation
bot.onSubscribedMessage(async (thread, message) => {
  const participants = await thread.getParticipants();
  if (participants.length > 1) {
    await thread.unsubscribe();
    return;
  }
  await thread.post("Still here to help!");
});

Returns

Author Array of unique non-bot authors

isSubscribed()

isSubscribed(): Promise<boolean>

Check if this thread is currently subscribed. In subscribed message handlers, this is optimized to return true immediately without a state lookup, since we already know we’re in a subscribed context.

Returns

Promise<boolean> Promise resolving to true if subscribed, false otherwise

markAsRead()

markAsRead(message?: string | Message<unknown>): Promise<void>

Send a read receipt for an inbound message. Defaults to the message being handled, so it takes no argument inside a message handler. Pass a Message or a message ID to target one explicitly; a Message must belong to this thread. Platforms may treat the receipt as a watermark and mark earlier messages read along with the target.

Parameters

string | Message<unknown>

Type: MessageMessage or message ID to acknowledge; defaults to the current message

Returns

Promise<void>

mentionUser()

mentionUser(userId: string): string

Get a platform-specific mention string for a user. Use this to @-mention a user in a message.

await thread.post(`Hey ${thread.mentionUser(userId)}, check this out!`);

Parameters

string

required

Returns

string

post()

post(message: T): Promise<T>

Post a message to this thread. Supports text, markdown, cards, and streaming from async iterables. When posting a stream (e.g., from AI SDK), uses adapter-native streaming when available, or falls back to post + edit with throttling.

// Simple string
await thread.post("Hello!");

// Markdown
await thread.post({ markdown: "**Bold** and _italic_" });

// With emoji
await thread.post(`${emoji.thumbs_up} Great job!`);

// JSX Card (with @jsxImportSource chat)
await thread.post(
  <Card title="Welcome!">
    <Text>Hello world</Text>
  </Card>
);

// Stream from AI SDK
const result = await agent.stream({ prompt: message.text });
await thread.post(result.textStream);

// Stream with options via StreamingPlan PostableObject
const stream = new StreamingPlan(result.fullStream, {
  groupTasks: "plan",
  endWith: [feedbackBlocks],
});
await thread.post(stream);

// Plan with live updates
const plan = new Plan({ initialMessage: "Working..." });
await thread.post(plan);
await plan.addTask({ title: "Step 1" });
await plan.complete({ completeMessage: "Done!" });

Parameters

required

String, PostableMessage, JSX Card, or AsyncIterable

Returns

Promise<T> A SentMessage with methods to edit, delete, or add reactions

post(message: string | PostableRaw | PostableMarkdown | PostableAst | PostableCard | CardElement | TextElement | ImageElement | DividerElement | ActionsElement | SectionElement | FieldsElement | LinkElement | TableElement | ChartElement | ModalElement | CardJSXElement<CardJSXProps> | ButtonElement | LinkButtonElement | FieldElement | TextInputElement | DateInputElement | NumberInputElement | SelectElement | ExternalSelectElement | SelectOptionElement | RadioSelectElement | AsyncIterable<string, any, any>): Promise<SentMessage<unknown>>

Post a message.

Parameters

required

Type:

PostableRawPostableMarkdownPostableAstPostableCardCardElementTextElementImageElementDividerElementActionsElementSectionElementFieldsElementLinkElementTableElementChartElementModalElementCardJSXElementCardJSXPropsButtonElementLinkButtonElementFieldElementTextInputElementDateInputElementNumberInputElementSelectElementExternalSelectElementSelectOptionElementRadioSelectElement

Returns

SentMessage

postEphemeral()

postEphemeral(user: string | Author, message: string | PostableRaw | PostableMarkdown | PostableAst | PostableCard | CardElement | TextElement | ImageElement | DividerElement | ActionsElement | SectionElement | FieldsElement | LinkElement | TableElement | ChartElement | ModalElement | CardJSXElement<CardJSXProps> | ButtonElement | LinkButtonElement | FieldElement | TextInputElement | DateInputElement | NumberInputElement | SelectElement | ExternalSelectElement | SelectOptionElement | RadioSelectElement, options: PostEphemeralOptions): Promise<EphemeralMessage<unknown> | null>

Post an ephemeral message visible only to a specific user. Platform Behavior:

Slack: Native ephemeral (session-dependent, disappears on reload)
Google Chat: Native private message (persists, only target user sees it)
Teams: Native targeted message (public preview)
Discord: No native support - requires fallbackToDM: true

// Always send (DM fallback on Discord/Teams)
await thread.postEphemeral(user, 'Only you can see this!', { fallbackToDM: true })

// Only send if native ephemeral supported (Slack/GChat)
const result = await thread.postEphemeral(user, 'Secret!', { fallbackToDM: false })
if (!result) {
  // Platform doesn't support native ephemeral - handle accordingly
}

Parameters

string | Author

required

Type: AuthorUser ID string or Author object (from message.author or event.user)

required

Type:

PostableRawPostableMarkdownPostableAstPostableCardCardElementTextElementImageElementDividerElementActionsElementSectionElementFieldsElementLinkElementTableElementChartElementModalElementCardJSXElementCardJSXPropsButtonElementLinkButtonElementFieldElementTextInputElementDateInputElementNumberInputElementSelectElementExternalSelectElementSelectOptionElementRadioSelectElement

Message content (string, markdown, card, etc.). Streaming is not supported.

PostEphemeralOptions

required

Returns

EphemeralMessage EphemeralMessage with usedFallback: true if DM was used, or null if native ephemeral not supported and fallbackToDM is false

refresh()

refresh(): Promise<void>

Refresh recentMessages from the API. Fetches the latest 50 messages and updates recentMessages.

Returns

Promise<void>

reply()

reply(target: string | Message<unknown>, message: string | PostableRaw | PostableMarkdown | PostableAst | PostableCard | CardElement | TextElement | ImageElement | DividerElement | ActionsElement | SectionElement | FieldsElement | LinkElement | TableElement | ChartElement | AsyncIterable<string | StreamChunk | StreamEvent, any, any> | ModalElement | CardJSXElement<CardJSXProps> | ButtonElement | LinkButtonElement | FieldElement | TextInputElement | DateInputElement | NumberInputElement | SelectElement | ExternalSelectElement | SelectOptionElement | RadioSelectElement): Promise<SentMessage<unknown>>

Reply to a specific message in this thread, using the platform’s native reply (quote, threaded reply) rather than posting a loose message. Throws NotImplementedError on adapters without native reply support.

chat.onNewMessage(async (thread, message) => {
  await thread.reply(message, 'Got it');
});

Parameters

string | Message<unknown>

required

Type: MessageThe message to reply to, or its id. Prefer passing the Message: it is checked against this thread, and it is carried through to SentMessage.replyTo and cached thread history. A raw id is resolved only if it matches a message this thread already holds (recentMessages or the message being handled); otherwise the reply is still sent, but replyTo is left undefined and no cross-thread check happens.

required

Type:

PostableRawPostableMarkdownPostableAstPostableCardCardElementTextElementImageElementDividerElementActionsElementSectionElementFieldsElementLinkElementTableElementChartElementStreamChunkStreamEventModalElementCardJSXElementCardJSXPropsButtonElementLinkButtonElementFieldElementTextInputElementDateInputElementNumberInputElementSelectElementExternalSelectElementSelectOptionElementRadioSelectElement

Reply content. Streams are buffered and posted as one message rather than streamed edit-by-edit.

Returns

SentMessage

schedule()

schedule(message: string | PostableRaw | PostableMarkdown | PostableAst | PostableCard | CardElement | TextElement | ImageElement | DividerElement | ActionsElement | SectionElement | FieldsElement | LinkElement | TableElement | ChartElement | ModalElement | CardJSXElement<CardJSXProps> | ButtonElement | LinkButtonElement | FieldElement | TextInputElement | DateInputElement | NumberInputElement | SelectElement | ExternalSelectElement | SelectOptionElement | RadioSelectElement, options: { postAt: Date }): Promise<ScheduledMessage<unknown>>

Schedule a message for future delivery. Currently only supported by the Slack adapter. Other adapters will throw NotImplementedError.

const scheduled = await thread.schedule("Reminder: standup!", {
  postAt: new Date("2026-03-09T09:00:00Z"),
});

// Cancel before it's sent
await scheduled.cancel();

Parameters

required

Type:

PostableRawPostableMarkdownPostableAstPostableCardCardElementTextElementImageElementDividerElementActionsElementSectionElementFieldsElementLinkElementTableElementChartElementModalElementCardJSXElementCardJSXPropsButtonElementLinkButtonElementFieldElementTextInputElementDateInputElementNumberInputElementSelectElementExternalSelectElementSelectOptionElementRadioSelectElement

The message content (streaming not supported)

{ postAt: Date }

required

Scheduling options including the target delivery time

Returns

ScheduledMessage A ScheduledMessage with cancel() capability

setState()

setState(newState: Partial<TState>, options?: { replace: boolean }): Promise<void>

Set the thread state. Merges with existing state by default. State is persisted for 30 days.

Parameters

Partial<TState>

required

{ replace: boolean }

Returns

Promise<void>

startTyping()

startTyping(status?: string): Promise<void>

Show typing indicator in the thread. Some platforms support persistent typing indicators, others just send once. Optional status (e.g. “Typing…”, “Searching documents…”) is shown where supported.

Parameters

string

Returns

Promise<void>

subscribe(): Promise<void>

Subscribe to future messages in this thread. Once subscribed, messages in non-DM threads trigger onSubscribedMessage handlers. DM threads route to onDirectMessage first when a direct message handler is registered. The initial message that triggered subscription will NOT fire the handler.

chat.onNewMention(async (thread, message) => {
  await thread.subscribe();  // Subscribe to follow-up messages
  await thread.post("I'm now watching this thread!");
});

Returns

Promise<void>

toJSON()

toJSON(): SerializedThread

Serialize the thread to a plain JSON object. Use this to pass thread data to external systems like workflow engines.

// Pass to a workflow
await workflow.start("my-workflow", {
  thread: thread.toJSON(),
  message: serializeMessage(message),
});

Returns

SerializedThread

unsubscribe()

unsubscribe(): Promise<void>

Unsubscribe from this thread. Future messages will no longer trigger onSubscribedMessage handlers.

Returns

Promise<void>

​Constructor

​Parameters

​Returns

​Properties

​Methods

​WORKFLOW_DESERIALIZE

​Parameters

​Returns

​WORKFLOW_SERIALIZE

​Parameters

​Returns

​createSentMessageFromMessage()

​Parameters

​Returns

​fromJSON()

​Parameters

​Returns

​getParticipants()

​Returns

​isSubscribed()

​Returns

​markAsRead()

​Parameters

​Returns

​mentionUser()

​Parameters

​Returns

​post()

​Parameters

​Returns

​Parameters

​Returns

​postEphemeral()

​Parameters

​Returns

​refresh()

​Returns

​reply()

​Parameters

​Returns

​schedule()

​Parameters

​Returns

​setState()

​Parameters

​Returns

​startTyping()

​Parameters

​Returns

​subscribe()

​Returns

​toJSON()

​Returns

​unsubscribe()

​Returns

Constructor

Parameters

Returns

Properties

Methods

WORKFLOW_DESERIALIZE

Parameters

Returns

WORKFLOW_SERIALIZE

Parameters

Returns

createSentMessageFromMessage()

Parameters

Returns

fromJSON()

Parameters

Returns

getParticipants()

Returns

isSubscribed()

Returns

markAsRead()

Parameters

Returns

mentionUser()

Parameters

Returns

post()

Parameters

Returns

Parameters

Returns

postEphemeral()

Parameters

Returns

refresh()

Returns

reply()

Parameters

Returns

schedule()

Parameters

Returns

setState()

Parameters

Returns

startTyping()

Parameters

Returns

subscribe()

Returns

toJSON()

Returns

unsubscribe()

Returns