@shelf/agent-assist-sdk

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.

Install

As npm module

$ npm install @shelf/agent-assist-sdk

$ yarn add @shelf/agent-assist-sdk

As script

<script type="text/javascript" src="https://cdn.jsdelivr.net/npm/@shelf/agent-assist-sdk@:tag-version:/lib/agent-assist.min.js"></script>

API reference

Properties:

version

SDK includes the following methods:

initialize()
get()
applySearch()
getContextSuggestions()
setMessages()
getSuggestions()
clearSuggestions()
openTab()
request()
on()
off()
openGemPage()
request()
updateSession()
startSession()

SDK.initialize

Initialize iframe in provided element and set config for agent assist widget. All other methods should be called after initialize is resolved

initialize(element: HTMLElement, config: InitializeConfig): Promise

Parameters:

Name	Type	Default value	Description
`element`	HTMLElement	-	Element in which will be rendered Shelf iframe
`config`	InitializeConfig	-	Config of widget

Returns: Promise<boolean>

InitializeConfig

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';
}

Theme

interface Theme {
  fontSize: string;
  fontFamily: string;
  mainColor: string;
}

configurationId

The id of configuration to use. If omitted, it defaults to first configuration on account

since 1.6.0

Optional configurationId: string

suggestions

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

favorites

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

announcements

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

telemetry

Required telemetry: { systemName: string }

Name	Type	Default	Description
`systemName`	string	-	Name of the system where Agent Assist SDK is used

shelfDomain

Required shelfDomain: string

Name	Type	Default	Description
`shelfDomain`	string	-	Shelf domain to use. `shelf.io` - is the only possible value for now

onMissingToken

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',
});

getContextSuggestions

NOTE: Works when contextSuggestions is enabled in Agent assist advanced configuration . Gets suggestions for configured context values on agent assist advanced configuration

getContextSuggestions(context: object): void

Parameters:

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"
    }
  }
})

get

since 1.8.0

Method to get agent assist related info, such as user, account agentAssistSettings etc.

get(field: string): Promise

Parameters:

Name	Type
`field`	'account' \| 'user' \| 'agentAssistSettings'

Returns: Promise

Example

const user = shelf.AgentAssist.get('user');

user; // {_id: "ee49869-3b", subdomain: "test", ...}

setMessages

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

Parameters:

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'},
]);

getSuggestions

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

Parameters:

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?']);

clearSuggestions

Clear currently displayed suggestions

clearSuggestions(): Promise

Returns: Promise

Example

shelf.AgentAssist.clearSuggestions();

on

Subscribe to agent events. Only one listener could be provided

on(eventName: AgentEvent, handler: (data) => void): void

on('send-to-chat`)

Triggered when agent clicks on Send

Example

shelf.AgentAssist.on('send-to-chat', ({text}) => {
  // use api to send message to integrated platform
});

on('copy-snippet`)

Triggered when agent clicks on Copy

Example

shelf.AgentAssist.on('copy-snippet', ({text}) => {
  //
});

on('content-linked`)

since 1.17.0

Triggered when agent link gem to an interaction

Example

shelf.AgentAssist.on('content-linked', ({gemId, objectId, systemId, decisionTreeStepId}) => {
  //
});

on('content-unlinked`)

since 2.0.0

Triggered when agent unlink gem from interaction

Example

shelf.AgentAssist.on('content-unlinked', ({gemId, objectId, systemId}) => {
  //
});

on('gem-favorited')

since 3.0.0

Triggered when gem is favorited

Example

shelf.AgentAssist.on('gem-favorited', ({gemId}) => {
  //
});

on('gem-unfavorited')

since 3.0.0

Triggered when gem is unfavorited

Example

shelf.AgentAssist.on('gem-unfavorited', ({gemId}) => {
  //
});

off

Unsubscribe fom agent events

off(eventName: AgentEvent): void

Example

shelf.AgentAssist.off('send-to-chat');

openTab

Open tab inside agent assist

openTab(tab: AgentAssistTab): void | Promise<unknown>

AgentAssistTab:

type Tab = 'suggestions' | 'search' | 'gem' | 'favorites' | 'announcements' | 'links' | 'settings';

Name	Type
`tab`	Tab

Returns: Promise

Example

shelf.AgentAssist.openTab('suggestions');

openGemPage

Open gem inside agent assist

openGemPage(gemId: string): Promise<void>

Example

shelf.AgentAssist.openGemPage('d7a89d02-9d04-43d4-83de-81934efb9de1');

request

Allows making custom request to the api

request(params: RequestParams): Promise

Parameters:

Name	Type
`params`	RequestParams

Returns: Promise

RequestParams

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',
});

updateSession

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

Parameters:

Name	Type
`payload`	UpdateSessionPayload

Returns: Promise<string>

UpdateSessionPayload

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: '...',
    ...
  }
})

startSession

Start a new session. This is necessary for updating session data for different conversations.

startSession(payload: StartSessionPayload): Promise

Parameters:

Name	Type
`payload`	StartSessionPayload

Returns: Promise<string>

StartSessionPayload

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: '...',
    ...
  }
})

applySearch

Allows running custom search with filters; Check API for supported filter; Note: this will apply filters on search tab

applySearch(payload: SearchFilters): Promise

Parameters:

Name	Type
`payload`	SearchFilters

Returns: Promise

SearchFilters

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'],
  ...
})

version

Get the current SDK version

version: string

Example

SDK.version; // ex: 1.0.0

Examples

yarn install
yarn dev
open browser on http://localhost:8080/

@shelf/agent-assist-sdk

@shelf/agent-assist-sdk

Install

As npm module

As script

API reference

SDK.initialize

Parameters:

InitializeConfig

Theme

configurationId

suggestions

favorites

announcements

telemetry

shelfDomain

onMissingToken

getContextSuggestions

Parameters:

get

Parameters:

setMessages

Parameters:

getSuggestions

Parameters:

clearSuggestions

on

on('send-to-chat`)

on('copy-snippet`)

on('content-linked`)

on('content-unlinked`)

on('gem-favorited')

on('gem-unfavorited')

off

openTab

openGemPage

request

Parameters:

RequestParams

updateSession

Parameters:

UpdateSessionPayload

startSession

Parameters:

StartSessionPayload

applySearch

Parameters:

SearchFilters

version

Examples

License

Readme

Keywords

Package Sidebar

Install

Repository

Homepage

DownloadsWeekly Downloads

Version

License

Unpacked Size

Total Files

Last publish

Collaborators

Weekly Downloads