@sendbird/ai-agent-messenger-react 1.41.0 → 1.43.0

package/dist/index.d.ts

@@ -65,8 +65,11 @@ declare interface ActiveChannelUpdatedParams {
 }
 
 export declare interface AgentClientHandlers extends AIAgentClientHandlers {
+    /** @internal */
     onMessageSend?: (message: string) => void;
+    /** @internal */
     onFunctionCallDetailClick?: (func: FunctionCallsInfo) => void;
+    /** @internal */
     onInitializeFailed?: (error: Error) => void;
 }
 
@@ -251,8 +254,7 @@ customApiHost?: string;
 * */
 agentPreviewConfigs?: AgentPreviewConfigs;
 /**
-* @internal
-* @description Event handlers for the ai agent client.
+* @public
 */
 handlers?: AgentClientHandlers;
 /**
@@ -267,7 +269,8 @@ enableCloseConversationButton?: boolean;
 enableExpandButton?: boolean;
 /**
 * @internal
-* @description Whether to automatically disconnect the WebSocket when the user is inactive in launcher mode.
+* @description Whether to automatically disconnect the WebSocket after the messenger stays closed for 60 seconds.
+* The legacy name is kept for compatibility; this applies regardless of launcher rendering or customization.
 * Set to false to keep the connection alive even during inactivity. (default: true)
 */
 enableAutoDisconnectInLauncher?: boolean;
@@ -439,6 +442,10 @@ declare interface AIAgentClientHandlers {
      * should be efficient and non-blocking, as this may be called frequently.
      */
     onLiveMetric?: (metric: LiveMetric) => void;
+    /**
+     * Called when a displayable nudge message is received after `requestNudgeMessage`.
+     */
+    onNudgeMessageReceived?: (response: NudgeMessageResponse) => void;
 }
 
 declare type AIAgentCommonIconName =
@@ -1016,8 +1023,7 @@ export declare type AIAgentProps = PropsWithChildren<{
      * */
     agentPreviewConfigs?: AgentPreviewConfigs;
     /**
-     * @internal
-     * @description Event handlers for the ai agent client.
+     * @public
      */
     handlers?: AgentClientHandlers;
     /**
@@ -1032,7 +1038,8 @@ export declare type AIAgentProps = PropsWithChildren<{
     enableExpandButton?: boolean;
     /**
      * @internal
-     * @description Whether to automatically disconnect the WebSocket when the user is inactive in launcher mode.
+     * @description Whether to automatically disconnect the WebSocket after the messenger stays closed for 60 seconds.
+     * The legacy name is kept for compatibility; this applies regardless of launcher rendering or customization.
      * Set to false to keep the connection alive even during inactivity. (default: true)
      */
     enableAutoDisconnectInLauncher?: boolean;
@@ -2892,6 +2899,10 @@ declare type CustomEvent_2 =
 | {
     type: 'user-action-requested';
     data: UserActionRequestedData;
+}
+| {
+    type: 'external-handoff-changed';
+    data: ExternalHandoffChangedData;
 };
 export { CustomEvent_2 as CustomEvent }
 
@@ -3105,6 +3116,8 @@ export declare interface ExtendedMessagePayload {
     // Whether this message is the last bubble in a multi-bubble turn.
     // Sent as `true` only on the last bubble; omitted (undefined) on non-last bubbles.
     // Only reliable once the server stream has completed (data.stream = false).
+    // Not on the payload spec page yet — agreed in Slack:
+    // https://sendbird.slack.com/archives/C0BLUB6G3RP/p1787219498878089
     is_last_in_turn?: boolean;
     cta_button: {
         label: string;
@@ -3187,13 +3200,36 @@ declare type ExternalAuthTokenExpiredData = {
     cpaKey: string;
 };
 
+/**
+ * A change to the external-service handoff the server records as channel metadata.
+ *
+ * Both fields carry the current state, not only the one the server just changed, so the newest
+ * event supersedes the previous one rather than merging into it. Live only: not replayed on load
+ * or after a reconnect, and the same state can arrive more than once, so handle it idempotently.
+ */
+export declare interface ExternalHandoffChangedData {
+    /** The destination the server wrote, or `null` when this client has not seen the destination write. Server-defined and open-ended. */
+    externalServiceType: string | null;
+    /** Unix seconds, set once the external session ended. */
+    endedAt: number | null;
+}
+
 export declare interface FeedbackInfo {
     rating: 'good' | 'bad';
     comment?: string;
 }
 
+export declare interface FixedLauncherProps extends Pick<LauncherProps, 'opened' | 'setOpened' | 'entryPoint' | 'activeRoute'> {
+    /** Configured launcher size, available for sizing or positioning your custom UI. */
+    size?: number;
+    /** Placement styles for the custom launcher. Apply them or use your own positioning. */
+    style?: CSSProperties;
+}
+
 export declare const FixedMessenger: ForwardRefExoticComponent<MessengerProps & RefAttributes<MessengerSessionRef>> & {
     Style: (props: FixedMessengerStyleProps) => null;
+    Launcher: ({ component }: FixedMessengerLauncherProps) => null;
+    NudgeMessage: ({ component }: FixedMessengerNudgeMessageProps) => null;
     Conversation: ({ component }: FixedMessengerConversationProps) => null;
     ConversationChildren: ({ children }: PropsWithChildren) => null;
     ConversationList: ({ component }: FixedMessengerConversationListProps) => null;
@@ -3208,6 +3244,10 @@ declare interface FixedMessengerConversationProps {
     component: ComponentType<ConversationProps>;
 }
 
+declare interface FixedMessengerLauncherProps {
+    component: ComponentType<FixedLauncherProps>;
+}
+
 export declare type FixedMessengerMargin = {
     top: number;
     bottom: number;
@@ -3215,6 +3255,10 @@ export declare type FixedMessengerMargin = {
     end: number;
 };
 
+declare interface FixedMessengerNudgeMessageProps {
+    component: ComponentType<FixedNudgeMessageProps>;
+}
+
 export declare type FixedMessengerPosition = `${PositionHorizontal}-${PositionVertical}`;
 
 declare interface FixedMessengerStyleProps {
@@ -3237,6 +3281,11 @@ declare interface FixedMessengerStyleProps {
     launcherSize?: number;
 }
 
+export declare interface FixedNudgeMessageProps extends Omit<NudgeMessageViewProps, 'nudgeMessageKey'> {
+    /** Placement styles for the custom nudge message. Apply them or use your own positioning. */
+    style?: CSSProperties;
+}
+
 declare type ForegroundTaskScheduler = (start: () => void) => void | (() => void);
 
 declare interface Form {
@@ -5624,7 +5673,7 @@ declare interface LanguageSet extends Omit<AIAgentLanguageSet, 'strings'> {
     stringSet: StringSet;
 }
 
-export declare function LauncherBase({ className, children, isOpened, onClick, 'aria-label': ariaLabel, 'aria-describedby': ariaDescribedBy, type, imageUrl, dir, animated, backgroundColor, size, hasUnread, }: LauncherProps): JSX.Element;
+export declare function LauncherBase({ className, children, isOpened, onClick, 'aria-label': ariaLabel, 'aria-describedby': ariaDescribedBy, type, imageUrl, dir, animated, backgroundColor, size, hasUnread, }: LauncherProps_2): JSX.Element;
 
 declare type LauncherImageType = 'default_icon' | 'custom_image';
 
@@ -5634,6 +5683,15 @@ declare interface LauncherInfo {
 }
 
 declare type LauncherProps = {
+    opened: boolean;
+    setOpened: (opened: boolean) => void;
+    size?: number;
+    className?: string;
+    entryPoint?: LauncherRoute;
+    activeRoute?: LauncherRoute;
+};
+
+declare type LauncherProps_2 = {
     className?: string;
     children?: ReactNode;
     isOpened: boolean;
@@ -5649,6 +5707,8 @@ declare type LauncherProps = {
     hasUnread?: boolean;
 };
 
+export declare type LauncherRoute = 'Conversation' | 'ConversationList';
+
 declare interface LayoutContextValue<Props, Components extends Record<string, ComponentType<any>>> {
     Template: ComponentType<Props>;
     updateTemplate: (template: ComponentType<Props>) => void;
@@ -6704,6 +6764,21 @@ export declare interface NudgeMessageResponse {
     callbackUserMessage?: string;
 }
 
+declare interface NudgeMessageState {
+    /** The nudge to display; null while the messenger is opened or no nudge is active. */
+    nudgeMessage: NudgeMessageResponse | null;
+    /**
+     * Counts nudges received and never falls back when one is cleared; each platform's renderer keys
+     * the bubble on it to replay the entrance animation.
+     */
+    nudgeMessageKey: number;
+    dismissNudgeMessage: () => void;
+    /** Starts a new conversation from the nudge: creates a channel, opens the messenger, and sends the callback user message. */
+    startNudgeConversation: () => Promise<void>;
+}
+
+declare type NudgeMessageViewProps = NudgeMessageState;
+
 declare type NumberField = {
     key: string;
     type: 'number';