DeepdeskSDK Class

Overview

class DeepdeskSDK {
/**
* Create an instance of the DeepdeskSDK for each conversation.
*/
constructor(options: SDKOptions);
/**
* Get conversation id of current conversation.
* Throws an error when there is no conversation loaded yet.
*/
conversationId(): number;
/**
* Check if a conversation is loaded.
*/
hasConversation(): boolean;
/**
* Create a conversation and set the conversationId
* @param options - The create conversation options
*/
createConversation(options: CreateConversationOptions): Promise<Conversation>;
/**
* Get a conversation by session ID and sets the conversationId
* @param sessionId - A string with the conversation session ID.
* A session ID is local to the customer service platform, and identifies a
* conversation that takes place within a certain time frame.
*/
getConversationBySessionId(sessionId: string): Promise<Conversation>;
/**
* Store the visitor information in memory
* Is used to extract information for text placeholders
*/
setVisitorInfo(visitorInfo: VisitorInfo): void;
/**
* Store the agent information in memory
* Is used to extract information for text placeholders
*/
setAgentInfo(agentInfo: AgentInfo): void;
/**
* Method to call when the conversation is updated, either by an incoming message
* from the visitor, or a message sent by the agent.
* Usually this method is not needed, because messages are updated via the backend webhooks. Only use this method when webhook implementation is not possible.
*/
updateTranscript(transcriptPatch: Conversation['messages']): Promise<Conversation>;
/**
* Refresh suggestions based on the current conversation messages.
* Use when agent or visitor has submitted a message and Deepdesk webhook is notified.
* Be carefull not to refresh suggestions when the agent is already typing.
*/
refresh(): void;
/**
* Start or continue timing the interaction between agent and customer.
* Is used to track the average handling time (AHT).
*/
handlingTimeStart(): void;
/**
* Stop or pause timing the interaction between agent and customer
* Sends an (intermediate) analytics event to Deepdesk.
*/
handlingTimeStop(): void;
/**
* Method to call when the agent has sent a message to the visitor
* Sends an analytics event to Deepdesk.
*/
notifySubmit(): void;
/**
* Emit an event
*/
emit<K extends keyof SDKEventMap>(type: K, eventPayload: SDKEventMap[K]): void;
/**
* Attach listener to SDK event
* Returns a method to remove the added event
*/
on<K extends keyof SDKEventMap>(type: K, handler: SDKHandler<K>): () => void;
/**
* Remove specific listener (event type and handler) from SDK.
* Or remove all listeners if no arguments are given.
*/
off<K extends keyof SDKEventMap>(type: K, handler: SDKHandler<K>): void;
off(): void;
/**
* Renders the tab completion and suggestions overlay and 2-way binds events
* @param targetElement - the element to inject the deepdesk element in
* @param options - optional tabcompletion and/or suggestion list options
*/
mount(targetElement: HTMLElement, options?: MountOptions): void;
/**
* Unmounts a mounted DeepdeskSDK.
* This removes the suggestions overlay, the tab completion and the input listeners.
* This does not unmount the widget, to unmount the widget use `unmountWidget()`.
*/
unmount(): void;
/**
* Injects the Deepdesk Widget element into the provided DOM element.
* The widget will expand to a parent positioned relative, absolute or fixed.
* @param containerElement - the element to inject the deepdesk element in
* @param options - optional widget options
* @param callback - default undefined
*/
renderWidget(containerElement: HTMLElement, options?: WidgetOptions): void;
/**
* Unmounts the widget. This removes the widget from the DOM.
*/
unmountWidget(): void;

constructor

new DeepdeskSDK(config: SDKConfig);
interface SDKConfig {
/**
* Base API URL for the Deepdesk backend,
* e.g. https://acme.deepdesk.com/api
*/
deepdeskUrl: string;
/**
* Optional base url for the Deepdesk broker backend
* Only applicable if using autoflows or custom messages features.
* e.g. https://acme.deepdesk.com/broker/api
*/
brokerUrl?: string;
/**
* Set the language for all the UI labels.
* Note: This has no effect on the language of the suggestions!
* Default: en-US
*/
locale?: 'en-US' | 'nl-NL';
/**
* Optional jwt token for Authorization: Bearer <...> header.
* This is an alternative to the preferred SSO implementation.
* Contact support@deepdesk.com for how to obtain a token.
*/
token?: string;
}

createConversation

Create or get conversation based on unique sessionId/agentId/platform signature.

Note: Only use this method when there is no backend integration possible. The preferred route is to implement the Deepdesk backend webhooks for notifying Deepdesk of new messages (thus creating the conversation in the backend) and using getConversationBySessionId in the front end to get de correct conversation.

deepdeskSDK.createConversation(options: CreateConversationOptions);
interface CreateConversationOptions {
/**
* The platform's conversation/thread/case ID.
*/
sessionId: string;
/**
* The platform's agent ID
*/
agentId: string;
/**
* The messaging platform, e.g. 'liveengage'
*/
platform: string;
/**
* Optional client profile code, e.g. 'b2b' or 'b2c'
*/
profileCode?: string;
}

getConversationBySessionId

Get the current conversation created by the Deepdesk backend via the Deepdesk webhooks.

Optionally add polling options when you are not sure if the webhook received the message in time.

await deepdeskSDK.getConversationBySessionId(sessionId: string, options?: GetConversationBySessionIdOptions);
interface GetConversationBySessionIdOptions {
/**
* Number of attempts in the case the conversation is not created yet via the Deepdesk webhook.
*/
attempts?: number;
/**
* Delay between attempts in miliseconds
* Default: 1000(ms)
*/
retryDelay?: number;
}

mount

Mount the suggestions overlay and / or the tab completion components on a textarea or contenteditable div.

deepdeskSDK.mount(element: HTMLElement, options?: MountOptions);
interface MountOptions {
/*
* Enable or disable the suggestions overlay, or enable it with custom options.
* Default: true
*/
suggestionsOverlay?: boolean | SuggestionsOverlayOptions;
/*
* Enable or disable tab completion, or enable it with custom options.
* Default: true
*/
tabCompletion?: boolean | TabCompletionOptions;
/*
* Advanced: Provide you own InputMediator class.
* DeepdeskSDK <-> InputMediator <-> platform input
* Default: Deepdesk's TextAreaInput or ContentEditableInput depended on mount element.
* See: https://deepdesk.github.io/api-reference/classes/input-mediator
*/
InputMediator?: Constructable<InputMediator<HTMLElement>>;
/*
* Automatically detect when an agent submits a message.
* Default: false
*
* Can be enabled instead of manually calling `DeepdeskSDK.notifySubmit()`.
* Enabling this setting is discouraged, because it only works in ideal circumstances.
* The algorithm assumes that if the textarea is cleared,
* and it is not a result of user action (Delete, Backspace, Cut, etc.),
* the text in the textarea must have been submitted.
*/
detectSubmit?: boolean;
}
interface SuggestionsOverlayOptions {
/*
* Custom suggestion overlay styling
* See: https://deepdesk.github.io/topics/custom-styling
*/
customStyles?: SuggestionsOverlayCustomStyles;
/*
* Enable or disable a toggle button to collapse the suggestions
* Default: false
*/
showToggleButton?: boolean;
/*
* Enable or disable hot keys (feature is broken at the moment)
* Default: false
*/
// showHotKeys?: boolean;
/*
* Enable or disable "hide on blur"
* When enabled it only shows the suggestions overlay when the textarea is focused.
* Default: false
*/
hideOnBlur?: boolean;
/*
* Enable or disable text suggestions or provide max. number of suggestions.
* Disabling makes no sence.
* Default: true
*/
showTextSuggestions?: boolean | number;
}
interface TabCompletionOptions {
/*
* Custom tab completion styling
* See: https://deepdesk.github.io/topics/custom-styling
*/
customStyles?: TabCompletionCustomStyles;
}

Optimistic mounting vs. Async mounting

// Async mounting
deepdeskSDK.getConversationBySessionId('123', {
attempts: 5,
retryDelay: 500,
}).then(() => {
deepdeskSDK.mount(inputElement); // Make sure inputElement still exists
// other deepdeskSDK calls
}).catch(() => {
console.log('Could not find conversation');
});
// Optimistic mounting
deepdeskSDK.mount(inputElement);
deepdeskSDK.getConversationBySessionId('123', {
attempts: 5,
retryDelay: 500,
}).catch(() => {
console.log('Could not find conversation');
deepdeskSDK.unmount();
// and cleanup other stuf like listeners
});

on

Listen to the DeepdeskSDK events when the agent interacts with the provided suggestions.

/**
* 'select-text-suggestion'
* An agent selected a text suggestion rendered by `DeepdeskSDK.mount()`
* Also see: https://deepdesk.github.io/api-reference/resources/text-suggestion
*/
deepdeskSDK.on('select-text-suggestion', (suggestion: TextSuggestion) => void);
/**
* 'select-url-suggestion'
* An agent selected an url suggestion rendered by `DeepdeskSDK.renderWidget()`
* Also see: https://deepdesk.github.io/topics/widget
* Also see: https://deepdesk.github.io/api-reference/resources/url-suggestion
*/
deepdeskSDK.on('select-url-suggestion', (suggestion: UrlSuggestion) => void);
/**
* 'select-sticky-message'
* An agent selected a sticky message rendered by `DeepdeskSDK.renderWidget()`
* Also see: https://deepdesk.github.io/topics/widget
* Also see: https://deepdesk.github.io/api-reference/resources/sticky-message
*/
deepdeskSDK.on('select-sticky-message', (suggestion: StickyMessage) => void);
/**
* 'reset'
* An agent pressed ESC to restore the input value to the typed text.
*/
deepdeskSDK.on('reset', (suggestion: { text: string }) => void);

renderWidget

Mount the the widget in a HTML element. It will expand to the full height and width of the targeted element.

The widget can contain url suggestions, sticky messages, autoflows and custom messages. For the last two the Deepdesk Broker must be configured as well. See the brokerUrl option in the DeepdeskSDK constructor.

deepdeskSDK.renderWidget(element: HTMLElement, options?: WidgetOptions);
interface WidgetOptions {
/*
* Custom widget styling
* See: https://deepdesk.github.io/topics/custom-styling
*/
customStyles?: WidgetCustomStyles;
/*
* Enable or disable autoflows
* Default: false
*/
showAutoflows?: boolean;
/*
* Enable or disable contextual information in url suggestions.
* Contextual information is only intended for agents and is not sent to the visitor.
* Default: false
*/
showContext?: boolean;
/*
* Enable or disable custom messages.
* Default: false
*/
showCustomMessages?: boolean;
/*
* Enable or disable images for url suggestions and sticky messages.
* Default: false
*/
showImages?: boolean;
/*
* Enable or disable sticky messages, or provide max. number of messages.
* Default: false
*/
showStickyMessages?: boolean | number;
/*
* Enable or disable url suggestions, or provide max. number of suggestions.
* Default: false
*/
showUrlSuggestions?: boolean | number;
}

setVisitorInfo

Set visitor info, used for placeholder interpolation in the suggestions.

setVisitorInfo(visitorInfo: VisitorInfo): void;
interface VisitorInfo {
/**
* Platform's visitor id
*/
visitorId?: string;
/**
* Visitor name. Visitor first name is often what you want to show in the suggestions.
*/
visitorName?: string;
/**
* Visitor e-mail
*/
visitorEmail?: string;
/**
* Visitor postal code
*/
visitorPostalCode?: string;
/**
* Visitor house number
*/
visitorHouseNumber?: string;
}

Placeholder replacements:

'{visitor_name}': visitorName,
'{postal_code}': visitorPostalCode,
'{street_number}': visitorHouseNumber,
'{house_number}': visitorHouseNumber,
'{postal_code_house_number}': `${visitorPostalCode} ${visitorHouseNumber}`,
'{postal_code_street_number}': `${visitorPostalCode} ${visitorHouseNumber}`,
'{subscription_name}': visitorName,

setAgentInfo

Set agent info, used for placeholder interpolation in the suggestions.

setAgentInfo(agentInfo: AgentInfo): void;
interface AgentInfo {
/**
* Platform's agent id
*/
agentId?: string;
/**
* Agent's nickname or first name
*/
agentNickname?: string;
/**
* Agent's first name or full name
*/
agentName?: string;
/**
* Agent's e-mail address
*/
agentEmail?: string;
};

Placeholder replacements:

'{agent_name}': agentNickname,