@sendbird/ai-agent-messenger-react 1.26.1 → 1.28.0

package/dist/index.d.ts

@@ -238,7 +238,7 @@ queryParams?: AIAgentQueryParams;
 * @public
 * @description AIAgent global default config.
 * */
-config?: AIAgentConfig;
+config?: DeepPartial<AIAgentConfig_2>;
 /** @internal */
 deskParams?: {
 customApiHost?: string;
@@ -392,6 +392,14 @@ declare type AIAgentChatSDKParams = ChatSDKSendbirdChatParams<[ChatSDKGroupChann
 
 declare interface AIAgentClientHandlers {
     onCustomEvent?: (event: CustomEvent_2) => void;
+    /**
+     * Called whenever the SDK opens an external URL — markdown links, admin-message
+     * URLs, citation links, CTA buttons, and non-media file-preview clicks.
+     * Provide this to intercept link navigation (analytics, deep links, custom
+     * schemes). When omitted, the SDK falls back to `window.open` on web and
+     * `Linking.openURL` on React Native.
+     */
+    onClickLink?: (params: { url: string }) => void;
 }
 
 declare type AIAgentCommonIconName =
@@ -426,69 +434,98 @@ declare type AIAgentCommonIconName =
 | 'download'
 | 'memory';
 
-export declare interface AIAgentConfig {
-    conversation?: {
-        /**
-         * Whether to show the "Start new conversation" button at the end of the message list.
-         * @default true
-         * */
-        isTalkToAgentViewEnabled?: boolean;
-        /**
-         * Controls the scroll behavior of the conversation.
-         * - `auto`: Automatically scrolls to bottom on new messages and streaming.
-         * - `fixed`: Pins new messages at viewport top, maintains position during streaming.
-         * @default 'auto'
-         * */
-        scrollMode?: ConversationScrollMode;
-        /**
-         * Whether to show the new message indicator button when scrolled away from bottom.
-         * @default true
-         * */
-        newMessageIndicatorEnabled?: boolean;
-        /**
-         * Whether to show the sender's avatar image next to each message.
-         * @default true
-         * */
-        senderAvatarEnabled?: boolean;
-        header?: {
+/**
+ * Public input shape for the AI Agent config. Deep-partial of the canonical
+ * resolved config the SDK consumes internally — every field is optional so
+ * callers only supply the values they want to override. `mergeAIAgentConfig`
+ * fills in the rest before reaching React contexts.
+ */
+export declare type AIAgentConfig = DeepPartial<AIAgentConfig_2>;
+
+/**
+ * Canonical AI Agent config — every field is required after `mergeAIAgentConfig`.
+ * User-facing input uses `DeepPartial<AIAgentConfig>`.
+ */
+declare interface AIAgentConfig_2 {
+    conversation: {
+        /** @deprecated Use `list.isTalkToAgentViewEnabled` instead. */
+        isTalkToAgentViewEnabled: boolean;
+        /** @deprecated Use `list.scrollMode` instead. */
+        scrollMode: ConversationScrollMode;
+        /** @deprecated Use `list.newMessageIndicatorEnabled` instead. */
+        newMessageIndicatorEnabled: boolean;
+        /** @deprecated Use `list.senderAvatarEnabled` instead. */
+        senderAvatarEnabled: boolean;
+        list: {
+            /**
+             * Whether to show the "Start new conversation" button at the end of the message list.
+             * @default true
+             * */
+            isTalkToAgentViewEnabled: boolean;
+            /**
+             * Controls the scroll behavior of the conversation.
+             * - `auto`: Automatically scrolls to bottom on new messages and streaming.
+             * - `fixed`: Pins new messages at viewport top, maintains position during streaming.
+             * @default 'auto'
+             * */
+            scrollMode: ConversationScrollMode;
+            /**
+             * Whether to show the new message indicator button when scrolled away from bottom.
+             * @default true
+             * */
+            newMessageIndicatorEnabled: boolean;
+            /**
+             * Whether to show the sender's avatar image next to each message.
+             * @default true
+             * */
+            senderAvatarEnabled: boolean;
+            /**
+             * Controls how markdown images are displayed while a message is streaming.
+             * - `default`: Renders partial markdown as-is.
+             * - `complete-only`: Hides incomplete image markdown until the image token is complete.
+             * @default 'default'
+             * */
+            markdownImageRenderMode: MarkdownImageRenderMode;
+        };
+        header: {
             /**
              * Whether to show the avatar in the conversation header.
              * @default true
              * */
-            avatarEnabled?: boolean;
+            avatarEnabled: boolean;
         };
-        input?: {
+        input: {
             /**
              * (React-Native only) Whether to enable the camera option in the attachment menu.
              * */
-            camera?: {
-                photoEnabled?: boolean;
+            camera: {
+                photoEnabled: boolean;
             };
             /**
              * Whether to enable the gallery/photo option in the attachment menu.
              * */
-            gallery?: {
-                photoEnabled?: boolean;
+            gallery: {
+                photoEnabled: boolean;
             };
             /**
              * Whether to enable the file option in the attachment menu.
              * */
-            fileEnabled?: boolean;
+            fileEnabled: boolean;
         };
         /**
          * (React only) Whether to play an alert sound when a message is received from the AI agent while the browser is not focused.
          * @default false
          * */
-        messageAlertSoundEnabled?: boolean;
+        messageAlertSoundEnabled: boolean;
         /**
          * File viewer configuration.
          * */
-        fileViewer?: {
+        fileViewer: {
             /**
              * Whether to show the download button in the file viewer.
              * @default true
              * */
-            downloadEnabled?: boolean;
+            downloadEnabled: boolean;
         };
     };
 }
@@ -513,7 +550,7 @@ declare interface AIAgentContextValue {
     networkStateAdapter?: NetworkStateAdapter;
 
     queryParams?: AIAgentQueryParams;
-    config?: AIAgentConfig;
+    config: AIAgentConfig_2;
 
     handlers?: AIAgentClientHandlers;
 }
@@ -651,9 +688,9 @@ declare interface AIAgentInterface {
     readonly session: AIAgentSession | null;
     /** The Desk client. Available after authenticate(). */
     readonly deskClient: DeskClientInterface;
-    // TODO: Change to `AIAgentConfig` (non-optional) once the context migration lands and all usages are updated
-    /** The AI Agent configuration */
-    config: AIAgentConfig | undefined;
+    /** The AI Agent configuration. */
+    get config(): AIAgentConfig_2;
+    set config(value: DeepPartial<AIAgentConfig_2> | undefined);
     /** The query parameters for AI Agent */
     queryParams?: AIAgentQueryParams;
     /** The adapter for detecting online/offline network state */
@@ -887,7 +924,7 @@ export declare type AIAgentProps = PropsWithChildren<{
      * @public
      * @description AIAgent global default config.
      * */
-    config?: AIAgentConfig;
+    config?: DeepPartial<AIAgentConfig_2>;
     /** @internal */
     deskParams?: {
         customApiHost?: string;
@@ -1100,6 +1137,7 @@ declare interface AIAgentStringSet {
         a11y_hint_open_conversation: string;
         a11y_hint_open_conversations: string;
         a11y_hint_close_conversation: string;
+        a11y_hint_close_messenger: string;
         a11y_hint_open_menu: string;
         a11y_hint_connect_to_agent: string;
         a11y_hint_attach_file: string;
@@ -1258,6 +1296,7 @@ declare type BaseMessageProps<T> = T & {
     onClickMedia?: (params: { url: string; type: string }) => void;
     onClickMediaFiles?: (params: { files: Array<{ url: string; type: string; name?: string }>; index: number }) => void;
     onClickFile?: (params: { url: string; type: string }) => void;
+    onClickLink?: (params: { url: string }) => void;
 
     children?: ReactNode;
 };
@@ -2155,14 +2194,12 @@ declare interface ConversationListContextProps {
     conversationListLimit?: number;
     conversationListFilter?: Partial<AIAgentGroupChannelFilter>;
     onOpenConversationView?: (channelUrl: string, status: 'open' | 'closed') => void;
-    announcementsEnabled?: boolean;
 }
 
-export declare function ConversationListContextProvider({ conversationListLimit, conversationListFilter, onOpenConversationView, announcementsEnabled, children, }: PropsWithChildren<ConversationListContextProps>): JSX.Element;
+export declare function ConversationListContextProvider({ conversationListLimit, conversationListFilter, onOpenConversationView, children, }: PropsWithChildren<ConversationListContextProps>): JSX.Element;
 
 declare interface ConversationListContextValue extends AIAgentConversationListContextValue {
     onOpenConversationView: (channelUrl: string, status: 'open' | 'closed') => void;
-    announcementsEnabled: boolean;
 }
 
 export declare const ConversationListHeaderLayout: {
@@ -2397,6 +2434,11 @@ export declare type DateSeparatorProps = SBUFoundationProps<{
     date?: Date | number;
 }>;
 
+/**
+ * Recursively makes every property of T optional, including nested objects.
+ */
+declare type DeepPartial<T> = T extends object ? { [K in keyof T]?: DeepPartial<T[K]> } : T;
+
 export declare const DefaultMessenger: ForwardRefExoticComponent<MessengerProps & RefAttributes<MessengerSessionRef>>;
 
 export declare interface DeskClientInterface {
@@ -2667,6 +2709,7 @@ BaseMessageProps<{
     isFeedbackEnabled?: boolean;
     isFeedbackCommentEnabled?: boolean;
     isSenderAvatarVisible?: boolean;
+    markdownImageRenderMode?: MarkdownImageRenderMode;
 
     // handlers
     onGetCachedMessageTemplate?: (templateKey: string) => string | null;
@@ -2746,6 +2789,7 @@ export declare const IncomingMessageLayout: {
                 isFeedbackEnabled?: boolean;
                 isFeedbackCommentEnabled?: boolean;
                 isSenderAvatarVisible?: boolean;
+                markdownImageRenderMode?: MarkdownImageRenderMode;
                 onGetCachedMessageTemplate?: (templateKey: string) => string | null;
                 onRequestMessageTemplate?: (templateKey: string) => Promise<string>;
                 onHandleTemplateInternalAction?: (action: Action) => void;
@@ -2794,6 +2838,9 @@ export declare const IncomingMessageLayout: {
                     url: string;
                     type: string;
                 }) => void;
+                onClickLink?: (params: {
+                    url: string;
+                }) => void;
                 children?: ReactNode;
             }) | ({
                 messageType: "file";
@@ -2819,6 +2866,7 @@ export declare const IncomingMessageLayout: {
                 isFeedbackEnabled?: boolean;
                 isFeedbackCommentEnabled?: boolean;
                 isSenderAvatarVisible?: boolean;
+                markdownImageRenderMode?: MarkdownImageRenderMode;
                 onGetCachedMessageTemplate?: (templateKey: string) => string | null;
                 onRequestMessageTemplate?: (templateKey: string) => Promise<string>;
                 onHandleTemplateInternalAction?: (action: Action) => void;
@@ -2867,6 +2915,9 @@ export declare const IncomingMessageLayout: {
                     url: string;
                     type: string;
                 }) => void;
+                onClickLink?: (params: {
+                    url: string;
+                }) => void;
                 children?: ReactNode;
             }) | ({
                 messageType: "multipleFiles";
@@ -2892,6 +2943,7 @@ export declare const IncomingMessageLayout: {
                 isFeedbackEnabled?: boolean;
                 isFeedbackCommentEnabled?: boolean;
                 isSenderAvatarVisible?: boolean;
+                markdownImageRenderMode?: MarkdownImageRenderMode;
                 onGetCachedMessageTemplate?: (templateKey: string) => string | null;
                 onRequestMessageTemplate?: (templateKey: string) => Promise<string>;
                 onHandleTemplateInternalAction?: (action: Action) => void;
@@ -2940,6 +2992,9 @@ export declare const IncomingMessageLayout: {
                     url: string;
                     type: string;
                 }) => void;
+                onClickLink?: (params: {
+                    url: string;
+                }) => void;
                 children?: ReactNode;
             })) => ReactNode;
             CTAButton: ({ extendedMessagePayload, onClickCTA, }: IncomingMessageProps) => ReactNode;
@@ -2996,6 +3051,7 @@ export declare const IncomingMessageLayout: {
     isFeedbackEnabled?: boolean;
     isFeedbackCommentEnabled?: boolean;
     isSenderAvatarVisible?: boolean;
+    markdownImageRenderMode?: MarkdownImageRenderMode;
     onGetCachedMessageTemplate?: (templateKey: string) => string | null;
     onRequestMessageTemplate?: (templateKey: string) => Promise<string>;
     onHandleTemplateInternalAction?: (action: Action) => void;
@@ -3044,6 +3100,9 @@ export declare const IncomingMessageLayout: {
     url: string;
     type: string;
     }) => void;
+    onClickLink?: (params: {
+    url: string;
+    }) => void;
     children?: ReactNode;
     }) | ({
     messageType: "file";
@@ -3069,6 +3128,7 @@ export declare const IncomingMessageLayout: {
     isFeedbackEnabled?: boolean;
     isFeedbackCommentEnabled?: boolean;
     isSenderAvatarVisible?: boolean;
+    markdownImageRenderMode?: MarkdownImageRenderMode;
     onGetCachedMessageTemplate?: (templateKey: string) => string | null;
     onRequestMessageTemplate?: (templateKey: string) => Promise<string>;
     onHandleTemplateInternalAction?: (action: Action) => void;
@@ -3117,6 +3177,9 @@ export declare const IncomingMessageLayout: {
     url: string;
     type: string;
     }) => void;
+    onClickLink?: (params: {
+    url: string;
+    }) => void;
     children?: ReactNode;
     }) | ({
     messageType: "multipleFiles";
@@ -3142,6 +3205,7 @@ export declare const IncomingMessageLayout: {
     isFeedbackEnabled?: boolean;
     isFeedbackCommentEnabled?: boolean;
     isSenderAvatarVisible?: boolean;
+    markdownImageRenderMode?: MarkdownImageRenderMode;
     onGetCachedMessageTemplate?: (templateKey: string) => string | null;
     onRequestMessageTemplate?: (templateKey: string) => Promise<string>;
     onHandleTemplateInternalAction?: (action: Action) => void;
@@ -3190,6 +3254,9 @@ export declare const IncomingMessageLayout: {
     url: string;
     type: string;
     }) => void;
+    onClickLink?: (params: {
+    url: string;
+    }) => void;
     children?: ReactNode;
     })) => ReactNode;
     CTAButton: ({ extendedMessagePayload, onClickCTA, }: IncomingMessageProps) => ReactNode;
@@ -3241,6 +3308,7 @@ export declare const IncomingMessageLayout: {
     isFeedbackEnabled?: boolean;
     isFeedbackCommentEnabled?: boolean;
     isSenderAvatarVisible?: boolean;
+    markdownImageRenderMode?: MarkdownImageRenderMode;
     onGetCachedMessageTemplate?: (templateKey: string) => string | null;
     onRequestMessageTemplate?: (templateKey: string) => Promise<string>;
     onHandleTemplateInternalAction?: (action: Action) => void;
@@ -3289,6 +3357,9 @@ export declare const IncomingMessageLayout: {
     url: string;
     type: string;
     }) => void;
+    onClickLink?: (params: {
+    url: string;
+    }) => void;
     children?: ReactNode;
     }) | ({
     messageType: "file";
@@ -3314,6 +3385,7 @@ export declare const IncomingMessageLayout: {
     isFeedbackEnabled?: boolean;
     isFeedbackCommentEnabled?: boolean;
     isSenderAvatarVisible?: boolean;
+    markdownImageRenderMode?: MarkdownImageRenderMode;
     onGetCachedMessageTemplate?: (templateKey: string) => string | null;
     onRequestMessageTemplate?: (templateKey: string) => Promise<string>;
     onHandleTemplateInternalAction?: (action: Action) => void;
@@ -3362,6 +3434,9 @@ export declare const IncomingMessageLayout: {
     url: string;
     type: string;
     }) => void;
+    onClickLink?: (params: {
+    url: string;
+    }) => void;
     children?: ReactNode;
     }) | ({
     messageType: "multipleFiles";
@@ -3387,6 +3462,7 @@ export declare const IncomingMessageLayout: {
     isFeedbackEnabled?: boolean;
     isFeedbackCommentEnabled?: boolean;
     isSenderAvatarVisible?: boolean;
+    markdownImageRenderMode?: MarkdownImageRenderMode;
     onGetCachedMessageTemplate?: (templateKey: string) => string | null;
     onRequestMessageTemplate?: (templateKey: string) => Promise<string>;
     onHandleTemplateInternalAction?: (action: Action) => void;
@@ -3435,6 +3511,9 @@ export declare const IncomingMessageLayout: {
     url: string;
     type: string;
     }) => void;
+    onClickLink?: (params: {
+    url: string;
+    }) => void;
     children?: ReactNode;
     })) => ReactNode;
     CTAButton: ({ extendedMessagePayload, onClickCTA, }: IncomingMessageProps) => ReactNode;
@@ -3509,6 +3588,7 @@ export declare const IncomingMessageLayout: {
             isFeedbackEnabled?: boolean;
             isFeedbackCommentEnabled?: boolean;
             isSenderAvatarVisible?: boolean;
+            markdownImageRenderMode?: MarkdownImageRenderMode;
             onGetCachedMessageTemplate?: (templateKey: string) => string | null;
             onRequestMessageTemplate?: (templateKey: string) => Promise<string>;
             onHandleTemplateInternalAction?: (action: Action) => void;
@@ -3557,6 +3637,9 @@ export declare const IncomingMessageLayout: {
                 url: string;
                 type: string;
             }) => void;
+            onClickLink?: (params: {
+                url: string;
+            }) => void;
             children?: ReactNode;
         }) | ({
             messageType: "file";
@@ -3582,6 +3665,7 @@ export declare const IncomingMessageLayout: {
             isFeedbackEnabled?: boolean;
             isFeedbackCommentEnabled?: boolean;
             isSenderAvatarVisible?: boolean;
+            markdownImageRenderMode?: MarkdownImageRenderMode;
             onGetCachedMessageTemplate?: (templateKey: string) => string | null;
             onRequestMessageTemplate?: (templateKey: string) => Promise<string>;
             onHandleTemplateInternalAction?: (action: Action) => void;
@@ -3630,6 +3714,9 @@ export declare const IncomingMessageLayout: {
                 url: string;
                 type: string;
             }) => void;
+            onClickLink?: (params: {
+                url: string;
+            }) => void;
             children?: ReactNode;
         }) | ({
             messageType: "multipleFiles";
@@ -3655,6 +3742,7 @@ export declare const IncomingMessageLayout: {
             isFeedbackEnabled?: boolean;
             isFeedbackCommentEnabled?: boolean;
             isSenderAvatarVisible?: boolean;
+            markdownImageRenderMode?: MarkdownImageRenderMode;
             onGetCachedMessageTemplate?: (templateKey: string) => string | null;
             onRequestMessageTemplate?: (templateKey: string) => Promise<string>;
             onHandleTemplateInternalAction?: (action: Action) => void;
@@ -3703,6 +3791,9 @@ export declare const IncomingMessageLayout: {
                 url: string;
                 type: string;
             }) => void;
+            onClickLink?: (params: {
+                url: string;
+            }) => void;
             children?: ReactNode;
         })) => ReactNode;
     }) => null;
@@ -3853,6 +3944,8 @@ declare interface ManualSessionInfoParams {
     sessionHandler: AIAgentSessionHandler;
 }
 
+declare type MarkdownImageRenderMode = 'default' | 'complete-only';
+
 declare interface MemoryInfo {
     enabled: boolean;
     showIndicator: boolean;
@@ -3932,7 +4025,7 @@ declare type MessageType_2 = OutgoingMessageProps['messageType'];
 declare interface MessengerContextValue extends AIAgentContextValue {
     rootElement: HTMLElement;
     agentPreviewConfigs?: AgentPreviewConfigs;
-    handlers?: AgentClientHandlers;
+    handlers: ResolvedHandlers;
     state: {
         opened: boolean;
         setOpened: (value: boolean) => void;
@@ -4454,6 +4547,12 @@ declare type ReleaseDisabledByValue =
 | 'reconnecting'
 | 'handoff_pending';
 
+declare interface ResolvedHandlers extends AgentClientHandlers {
+    onClickLink: (params: {
+        url: string;
+    }) => void;
+}
+
 declare type SBUFoundationProps<T = NonNullable<unknown>> = T & {
     className?: string;
     children?: ReactNode;