@shelf/agent-assist-sdk

@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

or

$ 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

eventName: "send-to-chat" | "copy-snippet" | "content-linked" | "content-unlinked" | "gem-favorited" | "gem-unfavorited"

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/

License

MIT © Shelf