@sendbird/ai-agent-messenger-react 1.36.0 → 1.37.0

package/dist/index.d.ts

@@ -776,6 +776,8 @@ declare interface AIAgentInterface {
     updateContext: (channelUrl: string, context: Record<string, string>) => Promise<ContextObject>;
     /** Retrieves the context data for the specified channel */
     getContextObject: (channelUrl: string) => Promise<ContextObject>;
+    /** Requests a nudge message to be shown above the launcher. Fire-and-forget: the result is only broadcast to onNudgeMessageReceived subscribers */
+    requestNudgeMessage: (params: RequestNudgeMessageParams) => Promise<void>;
     /** Clears memories saved for the current user */
     clearUserMemories: (params?: ClearUserMemoriesParams) => Promise<void>;
 
@@ -786,7 +788,7 @@ declare interface AIAgentInterface {
     setUserMemoryState: (params: SetUserMemoryStateParams) => Promise<MemoryInfo>;
 
     /** @internal Initializes a conversation on the channel if needed (AI Agent channel without conversation). */
-    initConversationIfNeeded: (channel: ChatSDKGroupChannel) => Promise<void>;
+    initConversationIfNeeded: (channel: ChatSDKGroupChannel, params?: { initialUserMessage?: string }) => Promise<void>;
 
     /** @internal Live metric handler; bridged from {@link AIAgentClientHandlers.onLiveMetric}. */
     onLiveMetric?: LiveMetricDispatch;
@@ -797,6 +799,8 @@ declare interface AIAgentInterface {
     /** Disposes all resources held by this instance (WebSocket, desk auth, event handlers). */
     dispose: () => void;
 
+    /** Registers a handler for nudge message responses */
+    onNudgeMessageReceived: (handler: (response: NudgeMessageResponse) => void) => () => void;
     /** Registers a handler for messenger settings updates */
     onMessengerSettingsUpdated: (handler: (params: MessengerSettingsUpdatedParams) => void) => () => void;
     /** Registers a handler for active channel updates */
@@ -857,6 +861,8 @@ declare interface AIAgentMessengerSessionRef {
         /** Patches the context of a specific conversation by aiAgentId and channelUrl. */
         (aiAgentId: string, channelUrl: string, context: Record<string, string>): Promise<ContextObject>;
     };
+    /** Requests a nudge message to be shown above the launcher. Fire-and-forget: the response is not exposed. */
+    requestNudgeMessage: (params: RequestNudgeMessageParams) => Promise<void>;
 }
 
 export declare type AIAgentProps = PropsWithChildren<{
@@ -1163,6 +1169,7 @@ declare interface AIAgentStringSet {
         a11y_send_message: string;
         a11y_attach_file: string;
         a11y_close_messenger: string;
+        a11y_dismiss_nudge_message: string;
         a11y_expand_messenger: string;
         a11y_collapse_messenger: string;
         a11y_connect_agent: string;
@@ -1540,6 +1547,9 @@ declare interface ColorSet {
     csat: {
         background: string;
     };
+    conversation: {
+        headerProfileSkeleton: string;
+    };
     memoryDialog: {
         titleText: string;
         markdownBodyText: string;
@@ -1578,6 +1588,7 @@ declare interface CommandPayloads {
     [CommandType.ActiveChannelUpdated]: ActiveChannelUpdatedParams;
     [CommandType.AnonymousSessionTokenExpired]: undefined;
     [CommandType.AuthTokenRefreshed]: AuthTokenRefreshedParams;
+    [CommandType.NudgeMessageReceived]: NudgeMessageResponse;
 }
 
 export declare const Commands = {
@@ -1586,6 +1597,7 @@ export declare const Commands = {
     ActiveChannelUpdated: (params: ActiveChannelUpdatedParams) => new ActiveChannelUpdatedCommand(params),
     AnonymousSessionTokenExpired: () => new AnonymousSessionTokenExpiredCommand(),
     AuthTokenRefreshed: () => new AuthTokenRefreshedCommand(),
+    NudgeMessageReceived: (response: NudgeMessageResponse) => new NudgeMessageReceivedCommand(response),
 };
 
 declare enum CommandType {
@@ -1594,6 +1606,7 @@ declare enum CommandType {
     ActiveChannelUpdated = 'active.channel.updated',
     AnonymousSessionTokenExpired = 'anon.token.expired',
     AuthTokenRefreshed = 'auth.token.refreshed',
+    NudgeMessageReceived = 'nudge.message.received',
 }
 
 export declare interface ConnectionDelayDialogProps {
@@ -1639,7 +1652,7 @@ declare interface ContextObject {
     context: Record<string, string>;
 }
 
-export declare const Conversation: ({ children, onNavigateToConversationList, channelUrl, onClearChannelUrl, shouldMarkAsRead, shouldInitializeConversation, announcementsEnabled, conversationStatsEnabled, initialFocusTarget, style, closedChannelUrl, onClearClosedChannelUrl, }: ConversationProps) => JSX.Element;
+export declare const Conversation: ({ children, onNavigateToConversationList, channelUrl, onClearChannelUrl, shouldMarkAsRead, shouldInitializeConversation, initialUserMessage, announcementsEnabled, conversationStatsEnabled, initialFocusTarget, style, closedChannelUrl, onClearClosedChannelUrl, }: ConversationProps) => JSX.Element;
 
 export declare const ConversationContext: Context<ConversationContextValue | null>;
 
@@ -1651,6 +1664,7 @@ declare interface ConversationContextProps {
     conversationStatsEnabled?: boolean;
     /** @internal */
     shouldInitializeConversation?: boolean;
+    initialUserMessage?: string;
 }
 
 export declare const ConversationContextProvider: ({ children, ...props }: PropsWithChildren<ConversationContextProps>) => JSX.Element;
@@ -2709,6 +2723,12 @@ export declare type ConversationProps = PropsWithChildren<{
     shouldMarkAsRead?: boolean;
     /** @internal */
     shouldInitializeConversation?: boolean;
+    /**
+     * Message to send as the first user message when the conversation is initialized
+     * on the server (e.g., the callback user message of a clicked nudge message).
+     * Applied only when the channel has no conversation yet.
+     */
+    initialUserMessage?: string;
     announcementsEnabled?: boolean;
     /** @default true */
     conversationStatsEnabled?: boolean;
@@ -5840,6 +5860,13 @@ declare interface NetworkStateAdapter {
     subscribe: (callback: (isOnline: boolean) => void) => () => void;
 }
 
+export declare interface NudgeMessageResponse {
+    /** Message to display above the launcher. */
+    message: string;
+    /** Message to send as the first user message when the nudge is clicked. */
+    callbackUserMessage?: string;
+}
+
 declare type NumberField = {
     key: string;
     type: 'number';
@@ -6421,6 +6448,13 @@ declare class RenderedContentUnusableStatsTracker extends StatsTrackerBase {
     }
 }
 
+export declare interface RequestNudgeMessageParams {
+    /** Event key that triggers the nudge message. */
+    key: string;
+    /** Additional context for the server to generate the message. */
+    context?: Record<string, string>;
+}
+
 declare interface ResolvedHandlers extends AgentClientHandlers {
     onClickLink: (params: {
         url: string;
@@ -7075,6 +7109,7 @@ export declare type StringSet = {
     A11Y_CONVERSATION_ITEM: (agent: string, status: string, time: string, count: number) => string;
     A11Y_CONNECT_AGENT: string;
     A11Y_CLOSE_MESSENGER: string;
+    A11Y_DISMISS_NUDGE_MESSAGE: string;
     A11Y_EXPAND_MESSENGER: string;
     A11Y_COLLAPSE_MESSENGER: string;
     A11Y_HINT_SEND_MESSAGE: string;