Widget ​

The Deepdesk SDK provides a widget component that can be rendered separately from the suggestions overlay. This widget can display various types of content like URL suggestions, pinned messages, and custom data.

Rendering the Widget ​

To render the widget, use the renderWidget method of the DeepdeskSDK instance:

// Get a reference to the container element where you want to render the widget
const containerElement = document.getElementById('widget-container');

// Render the widget with optional configuration
deepdeskSDK.renderWidget(containerElement, {
    // Enable or disable images for url suggestions and pinned messages
    showImages: false,
    // Custom widget styling
    customStyles: {
        // Add your custom styles here
    },
});

The widget will expand to the full height and width of the targeted container element.

Widget Options ​

The renderWidget method accepts the following options:

interface WidgetOptions {
    /*
     * Custom widget styling
     * See: /guide/custom-styling/widget
     */
    customStyles?: WidgetCustomStyles;

    /*
     * Enable or disable images for url suggestions and pinned messages.
     * Default: false
     */
    showImages?: boolean;
}

Setting up Conversation Query ​

The setConversationQuery method is essential for features that require access to the conversation history, such as conversation summary and entity detection. This method allows you to provide a callback that returns the conversation data in a structured format.

Why is it needed? ​

The conversation query is needed to:

1. Generate conversation summaries
2. Detect entities in the conversation
3. Provide context for AI assistants
4. Keep the conversation data separate from the Deepdesk backend for privacy reasons

How to use it ​

deepdeskSDK.setConversationQuery(() => {
    // Return an array of messages in the required format
    return [
        { source: 'visitor', text: 'Hello, I need help with my internet connection' },
        { source: 'agent', text: 'I understand. What seems to be the problem?' },
        { source: 'visitor', text: 'My wifi keeps disconnecting' },
    ];
});

The callback function should return a Promise or an array of message objects. Each message object must have:

• source: Either 'agent' or 'visitor'
• text: The message content as a string

Example with Async Data ​

deepdeskSDK.setConversationQuery(async () => {
    // Fetch conversation history from your platform's API
    const messages = await fetchConversationHistory();

    // Transform the messages into the required format
    return messages.map(msg => ({
        source: msg.isAgent ? 'agent' : 'visitor',
        text: msg.content,
    }));
});

Conversation Lifecycle Events ​

The SDK provides a way to evaluate AI assistants based on conversation lifecycle events using the evaluateConversationAssistant method. This method is useful for triggering specific AI responses at key moments in the conversation.

Available Events ​

The method accepts three types of events:

1. 'accepted': Triggered when an agent accepts a conversation
2. 'new-message': Triggered when a new message is received (from visitor or agent)
3. 'ended': Triggered when the conversation ends

Basic Usage ​

// When an agent accepts the conversation
await deepdeskSDK.evaluateConversationAssistant('accepted');

// When a new message is received
await deepdeskSDK.evaluateConversationAssistant('new-message');

// When the conversation ends
await deepdeskSDK.evaluateConversationAssistant('ended');

Configuration Options ​

You can customize the evaluation by providing options:

await deepdeskSDK.evaluateConversationAssistant('new-message', {
    // Custom input data for the assistant
    input: {
        customField: 'value',
    },
    // Specify how to get the conversation transcript
    transcript: 'in-memory-transcript', // or 'stored-transcript'
    // Whether to include conversation tags
    includeTags: true,
    // Whether to show the assistant's response in the widget
    showCuesInWidget: true,
});

Transcript Options ​

The transcript option can be set to:

• 'in-memory-transcript': Uses the transcript from the browser memory (requires setConversationQuery to be configured)
• 'stored-transcript': Uses the transcript stored in the Deepdesk backend
• Custom transcript array: Provide your own transcript data

Example with custom transcript:

await deepdeskSDK.evaluateConversationAssistant('ended', {
    transcript: [
        { source: 'visitor', text: 'I need help with my order' },
        { source: 'agent', text: 'I can help you with that' },
    ],
});

Handling Assistant Responses ​

The assistant's response will be automatically displayed in the widget by default. You can listen for these responses using the cues event:

deepdeskSDK.on('cues', cues => {
    // Handle the assistant's response
    console.log('Assistant response:', cues);
});

Unmounting the Widget ​

When you no longer need the widget, you can unmount it:

deepdeskSDK.unmountWidget();

This will clean up any resources and remove the widget from the DOM.