@shelf/agent-assist-sdk
Advanced tools
Readme
The Shelf Agent Assist SDK allows you to integrate Shelf widget into any platform and provide agents with real-time recommendations, accurate search and content from Shelf knowledge base.
$ npm install @shelf/agent-assist-sdk
or
$ yarn add @shelf/agent-assist-sdk
<script type="text/javascript" src="https://cdn.jsdelivr.net/npm/@shelf/agent-assist-sdk@:tag-version:/lib/agent-assist.min.js"></script>
Properties:
SDK includes the following methods:
Initialize iframe in provided element and set config for agent assist widget. All other methods should be called after
initializeis resolved
initialize(element: HTMLElement, config: InitializeConfig): Promise
| Name | Type | Default value | Description |
|---|---|---|---|
element | HTMLElement | - | Element in which will be rendered Shelf iframe |
config | InitializeConfig | - | Config of widget |
Returns: Promise<boolean>
interface InitializeConfig {
configurationId?: string; // the id of configuration to use;
suggestions?: {
enabled: boolean; // enabled by default
};
gem?: {
send?: {
enabled: boolean; // disabled by default
};
};
favorites?: {
enabled: boolean; // enabled by default
};
announcements?: {
enabled: boolean; // enabled by default
};
telemetry: {
systemName: string; // 'kustomer' | 'genesys_cloud' | 'amazon_connect';
};
theme?: Theme;
shelfDomain: 'shelf.io';
}
interface Theme {
fontSize: string;
fontFamily: string;
mainColor: string;
}
The id of configuration to use. If omitted, it defaults to first configuration on account
since 1.6.0
Optional configurationId: string
Optional suggestions:
| Name | Type | Default | Description |
|---|---|---|---|
enabled | boolean | true | Whenever to display Agent Assist tab. Note: Agent Assist should be enabled in Agent Assist configuration |
Optional favorites: { enabled?: boolean }
| Name | Type | Default | Description |
|---|---|---|---|
enabled | boolean | true | Whenever to display Favorites tab. Note: Agent Assist + Favorites should be enabled in Agent Assist configuration |
since 1.5.0
Optional announcements: { enabled?: boolean }
| Name | Type | Default | Description |
|---|---|---|---|
enabled | boolean | true | Whenever to display Announcements tab. Note: Announcements should be enabled in your plan restrictions and customize settings + Agent Assist configuration |
Required telemetry: { systemName: string }
| Name | Type | Default | Description |
|---|---|---|---|
systemName | string | - | Name of the system where Agent Assist SDK is used |
Required shelfDomain: string
| Name | Type | Default | Description |
|---|---|---|---|
shelfDomain | string | - | Shelf domain to use. shelf.io - is the only possible value for now |
since 1.11.0
Optional onMissingToken: () => Promise<{token: string}>
| Name | Type | Default | Description |
|---|---|---|---|
onMissingToken | Function | - | Invokes on when user identity is not yet identified. Returning {token: "shelf-jwt-token"} object, will tell Agent assist app to use provided token as the user identifier. Helpful when integrating with external systems where user is already authorized in, to enabled automatic login into Shelf Agent Assist. ** Note**: if this function is not implemented or don't resolve token within 7 second, user will automatically be redirected to login page |
eg:
shelf.AgentAssist.initialize(document.getElementById('agent-assist-root'), {
shelfDomain: 'shelf.io',
async onMissingToken() {
// Some method to exchange extrnal system token to shelf token
const authToken = await exchangeExternalToken('external-token');
return {token: authToken};
},
});
Example
shelf.AgentAssist.initialize(document.getElementById('agent-assist-root'), {
favorites: {
enabled: true,
},
suggestions: {
enabled: true,
},
shelfDomain: 'shelf.io',
});
NOTE: Works when
contextSuggestionsis enabled in Agent assist advanced configuration . Gets suggestions for configured context values on agent assist advanced configuration
getContextSuggestions(context: object): void
| Name | Type |
|---|---|
context | object |
Returns: void
Example
// advanced config
{
contextSuggestions: [
{
accessor: "contact_reason",
options: [{
value: "account_problems",
...
}],
...
},
{
accessor: "custom.user.cityStr",
options: [{
value: "boston",
...
}],
...
}
]
}
shelf.AgentAssist.getContextSuggestions({
contact_reason: "account_problems",
custom: {
user: {
cityStr: "boston"
}
}
})
since 1.8.0
Method to get agent assist related info, such as user, account agentAssistSettings etc.
get(field: string): Promise
| Name | Type |
|---|---|
field | 'account' | 'user' | 'agentAssistSettings' |
Returns: Promise
Example
const user = shelf.AgentAssist.get('user');
user; // {_id: "ee49869-3b", subdomain: "test", ...}
Provides clients messages & agent replies, so AI consider whole conversation state, and display recommendations once state of conversation changes Suggestions need to be enabled
getSuggestions(messages: Message[]): void
| Name | Type |
|---|---|
messages | Message[] |
Message
| Name | Type | Notes |
|---|---|---|
id | string? | Identifier of message, mostly is provided by external system. Fallback to ulid if omitted |
createdAt | string? | Send date. Fallback to new Date().toISOString() if omitted |
text | string | Required. Content of messages. Gets redacted before reaching AI reccomnedations engine |
senderType | client | agent | Required. Identidies who created message |
Returns: void
Example
shelf.AgentAssist.setMessages([
{text: 'Hi there. What are available delivery options?', senderType: 'client'},
]);
shelf.AgentAssist.setMessages([
{text: 'Hello. Let me check that in a moment', senderType: 'agent'},
]);
DEPERECATED since 3.1.0. Use setMessages`
Find and display recommendations for one question from Shelf knowledge base. Works only when suggestions are enabled
getSuggestions(question: string[]): Promise
| Key | Type | Notes |
|---|---|---|
id | string | Id of messages. Mostly provided by external system. Fallback to ulid when ommited |
Returns: Promise<number>
Example
shelf.AgentAssist.getSuggestions(['Do I need to wear masks?']);
Clear currently displayed suggestions
clearSuggestions(): Promise
Returns: Promise
Example
shelf.AgentAssist.clearSuggestions();
Subscribe to agent events. Only one listener could be provided
on(eventName: AgentEvent, handler: (data) => void): void
eventName: "send-to-chat" | "copy-snippet" | "content-linked" | "content-unlinked" | "gem-favorited" | "gem-unfavorited"
Triggered when agent clicks on
Send
Example
shelf.AgentAssist.on('send-to-chat', ({text}) => {
// use api to send message to integrated platform
});
Triggered when agent clicks on
Copy
Example
shelf.AgentAssist.on('copy-snippet', ({text}) => {
//
});
since 1.17.0
Triggered when agent link gem to an interaction
Example
shelf.AgentAssist.on('content-linked', ({gemId, objectId, systemId, decisionTreeStepId}) => {
//
});
since 2.0.0
Triggered when agent unlink gem from interaction
Example
shelf.AgentAssist.on('content-unlinked', ({gemId, objectId, systemId}) => {
//
});
since 3.0.0
Triggered when gem is favorited
Example
shelf.AgentAssist.on('gem-favorited', ({gemId}) => {
//
});
since 3.0.0
Triggered when gem is unfavorited
Example
shelf.AgentAssist.on('gem-unfavorited', ({gemId}) => {
//
});
Unsubscribe fom agent events
off(eventName: AgentEvent): void
Example
shelf.AgentAssist.off('send-to-chat');
Open tab inside agent assist
openTab(tab: AgentAssistTab): void | Promise<unknown>
type Tab = 'suggestions' | 'search' | 'gem' | 'favorites' | 'announcements' | 'links' | 'settings';
| Name | Type |
|---|---|
tab | Tab |
Returns: Promise
Example
shelf.AgentAssist.openTab('suggestions');
Open gem inside agent assist
openGemPage(gemId: string): Promise<void>
Example
shelf.AgentAssist.openGemPage('d7a89d02-9d04-43d4-83de-81934efb9de1');
Allows making custom request to the api
request(params: RequestParams): Promise
| Name | Type |
|---|---|
params | RequestParams |
Returns: Promise
interface RequestParams {
url: string;
method: 'PATCH' | 'POST' | 'DELETE' | 'GET' | 'PUT';
body?: Record<string, any>;
headers?: Record<string, string>;
}
Example
// Get current logged user info
shelf.AgentAssist.request({
url: 'auth/v1/user',
method: 'GET',
});
Updates current agent session with external system info. This is needed to troubleshoot possible issues on Shelf side. On the other hand, this data is analyzed to make the suggestions more relevant for agents
updateSession(payload: UpdateSessionPayload): Promise
| Name | Type |
|---|---|
payload | UpdateSessionPayload |
Returns: Promise<string>
interface UpdateSessionPayload {
interactionId?: string;
agentId?: string;
participantId?: string;
participantContext?: Record<string, any>;
}
Example
shelf.AgentAssist.updateSession({
interactionId: 'interaction-id',
agentId: 'some-agent-id',
participantContext: {
contactReason: 'order-missing',
timestamp: '...',
...
}
})
Start a new session. This is necessary for updating session data for different conversations.
startSession(payload: StartSessionPayload): Promise
| Name | Type |
|---|---|
payload | StartSessionPayload |
Returns: Promise<string>
interface StartSessionPayload {
interactionId?: string;
agentId?: string;
participantId?: string;
participantContext?: Record<string, any>;
systemLocation?: string;
systemName?: string;
}
Example
shelf.AgentAssist.startSession({
interactionId: 'interaction-id',
agentId: 'some-agent-id',
participantContext: {
contactReason: 'order-missing',
timestamp: '...',
...
}
})
Allows running custom search with filters; Check API for supported filter; Note: this will apply filters on search tab
applySearch(payload: SearchFilters): Promise
| Name | Type |
|---|---|
payload | SearchFilters |
Returns: Promise
interface SearchFilters {
favorites?: boolean;
from?: number;
fromDate?: string;
parentId?: string;
path?: string;
query?: string;
ratingMoreThan?: 0 | 1 | 2 | 3 | 4;
size?: number;
sort?: SortOptions;
sortBy?: SortBy;
sortOrder?: 'ASC' | 'DESC';
toDate?: string;
gemTypes?: GemType[];
ownerIds?: string[];
categories?: string[];
creationSources?: string[];
mimeTypes?: string[];
gemsToExclude?: string[];
gemIds?: string[];
tags?: string[];
libraryIds?: string[];
searchLanguage?: string;
}
type SortOptions =
| 'RECENT_FIRST'
| 'OLDEST_FIRST'
| 'RECENTLY_UPDATED_FIRST'
| 'RECENTLY_UPDATED_LAST'
| 'A_Z'
| 'Z_A'
| 'RELEVANCE'
| 'BY_GEM_IDS';
type SortByType = 'TITLE' | 'CREATED_DATE' | 'UPDATED_DATE' | 'RELEVANCE' | 'RATING' | 'VIEWS';
type GemType =
| 'Video'
| 'Audio'
| 'Document'
| 'Image'
| 'Directory'
| 'Bookmark'
| 'Person'
| 'Organization'
| 'Article'
| 'Note'
| 'Group'
| 'Project';
Example
shelf.AgentAssist.applySearch({
query: 'change account info',
from: 0,
size: 100,
sortBy: 'TITLE',
sortOrder: 'ASC',
parentId: 'some-folder-id',
searchLanguage: 'it',
categories: ['Trend', 'Idea'],
...
})
Get the current SDK version
version: string
Example
SDK.version; // ex: 1.0.0
yarn installyarn devhttp://localhost:8080/MIT © Shelf
FAQs
SDK for Shelf Agent Assist Express
The npm package @shelf/agent-assist-sdk receives a total of 280 weekly downloads. As such, @shelf/agent-assist-sdk popularity was classified as not popular.
We found that @shelf/agent-assist-sdk demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 53 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Tea.xyz, a crypto project aimed at rewarding open source contributions, is once again facing backlash due to an influx of spam packages flooding public package registries.
Security News
As cyber threats become more autonomous, AI-powered defenses are crucial for businesses to stay ahead of attackers who can exploit software vulnerabilities at scale.
Security News
UnitedHealth Group disclosed that the ransomware attack on Change Healthcare compromised protected health information for millions in the U.S., with estimated costs to the company expected to reach $1 billion.