Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More
Socket
Sign inDemoInstall
Socket

@shelf/agent-assist-sdk

Package Overview
Dependencies
Maintainers
53
Versions
68
Alerts
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

@shelf/agent-assist-sdk

SDK for Shelf Agent Assist Express

  • 3.6.0
  • latest
  • Source
  • npm
  • Socket score

Version published
Weekly downloads
206
decreased by-47.18%
Maintainers
53
Weekly downloads
 
Created
Source

@shelf/agent-assist-sdk CircleCI

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:

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:
NameTypeDefault valueDescription
elementHTMLElement-Element in which will be rendered Shelf iframe
configInitializeConfig-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:

NameTypeDefaultDescription
enabledbooleantrueWhenever to display Agent Assist tab. Note: Agent Assist should be enabled in Agent Assist configuration

favorites

Optional favorites: { enabled?: boolean }

NameTypeDefaultDescription
enabledbooleantrueWhenever to display Favorites tab. Note: Agent Assist + Favorites should be enabled in Agent Assist configuration

announcements

since 1.5.0

Optional announcements: { enabled?: boolean }

NameTypeDefaultDescription
enabledbooleantrueWhenever to display Announcements tab. Note: Announcements should be enabled in your plan restrictions and customize settings + Agent Assist configuration

telemetry

Required telemetry: { systemName: string }

NameTypeDefaultDescription
systemNamestring-Name of the system where Agent Assist SDK is used

shelfDomain

Required shelfDomain: string

NameTypeDefaultDescription
shelfDomainstring-Shelf domain to use. shelf.io - is the only possible value for now

onMissingToken

since 1.11.0

Optional onMissingToken: () => Promise<{token: string}>

NameTypeDefaultDescription
onMissingTokenFunction-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:
NameType
contextobject

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:
NameType
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:
NameType
messagesMessage[]

Message

NameTypeNotes
idstring?Identifier of message, mostly is provided by external system. Fallback to ulid if omitted
createdAtstring?Send date. Fallback to new Date().toISOString() if omitted
textstringRequired. Content of messages. Gets redacted before reaching AI reccomnedations engine
senderTypeclient | agentRequired. 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:
KeyTypeNotes
idstringId 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';
NameType
tabTab

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:
NameType
paramsRequestParams

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:
NameType
payloadUpdateSessionPayload

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:
NameType
payloadStartSessionPayload

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:
NameType
payloadSearchFilters

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

Keywords

FAQs

Package last updated on 25 Nov 2022

Did you know?

Socket

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.

Install

Related posts

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

Packages

npm

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc