@shelf/agent-assist-sdk

SDK for Shelf Agent Assist Express

Usage no npm install needed!

<script type="module">
  import shelfAgentAssistSdk from 'https://cdn.skypack.dev/@shelf/agent-assist-sdk';
</script>

README

@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:

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:

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

Returns: Promise<boolean>

InitializeConfig

{
  configurationId?: string; // the id of configuration to use;
  suggestions?: {
    enabled: boolean; // enabled by default
    sendToChatButton?: {
      enabled: boolean; // false by default
    };
    copySnippetButton?: {
      enabled: boolean; // false by default
    };
    autoParsedHashtags?: {
      enabled: boolean; // disabled by default
    };
  };
  gem?: {
    autoParsedHashtags?: {
      enabled: boolean; // disabled by default
    };
    decisionTree?: {
      copyStepButton?: {
        enabled: boolean; // disabled by default
      };
      sendToChatButton?: {
        enabled: boolean; // disabled by default
      };
    };
  };
  favorites?: {
    enabled: boolean; // enabled by default
  };
  workflow?: {
    enabled: boolean; // disabled by default
    sendToChatButton?: {
      enabled: boolean; // disabled by default
    };
    copySnippetButton?: {
      enabled: boolean; // disabled by default
    };
  };
  announcements?: {
    enabled: boolean; // enabled by default
  };
  telemetry: {
    systemName: string; // 'kustomer' | 'genesys_cloud' | 'amazon_connect';
  };
  theme?: ConfigTheme;
  customStyles?: string;
  shelfDomain: 'shelf.io'
}

ConfigTheme

{
  font: {
    mainColor?: string;
    mainColorHover?: string;
    fontSize?: string;
    fontFamily?: string;
  };
  accentColor?: string;
  sectionLabel?: {
    fontWeight?: number;
    minHeight?: string;
  };
  actionButton?: {
    height?: string;
  };
  suggestions?: {
    feedback?: {
      emojiWrapperHeight?: string;
    };
    gemListItem?: {
      iconSize?: number;
      iconHolderSize?: number;
    };
  };
  search?: {
    gemListItem?: {
      padding?: string;
    };
  };
  gemListItem?: {
    iconSize?: number;
    iconHolderSize?: number;
  };
  gem?: {
    externalLink?: {
      marginBottom?: string;
    };
    header?: {
      iconSize?: number;
      iconHolderSize?: number;
    };
    gemMeta?: {
      labelWidth?: string;
    };
  };
}

Default values for ConfigTheme

see more about where styles are applied here

{
  font: {
    fontSize: '14px',
    mainColor: '#606d84',
    mainColorHover: '#2a303b',
    fontFamily: 'Open Sans',
  },
  accentColor: '#fa6b30',
  sectionLabel: {
    fontWeight: 700,
    minHeight: '40px',
  },
  actionButton: {
    height: '40px',
  },
  suggestions: {
    feedback: {
      emojiWrapperHeight: '30px',
    },
    gemListItem: {
      iconSize: 16,
      iconHolderSize: 20,
    },
  },
  search: {
    gemListItem: {
      padding: '10px 0',
    },
  },
  gemListItem: {
    iconSize: 20,
    iconHolderSize: 40,
  },
  gem: {
    externalLink: {
      marginBottom: '20px',
    },
    header: {
      iconSize: 20,
      iconHolderSize: 40,
    },
    gemMeta: {
      labelWidth: '150px',
    },
  },
}

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
sendToChatButton?.enabled boolean false Whenever to display Send to Chat on suggestions tab
copySnippetButton?.enabled boolean false Whenever to display Copy snippet on suggestions tab

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,
     sendToChatButton: {
        enabled: true
     },
     displayCopyButton: {
        enabled: false
     }
    },
    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): Promise

Parameters:

Name Type
context object

Returns: Promise

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", ...}

getSuggestions

Find and display recommendations for one question from Shelf knowledge base. Works only when suggestions are enabled

getSuggestions(question: string[]): Promise

Parameters:

Name Type
questions string[]

Returns: Promise

Example

shelf.AgentAssist.getSuggestions('Do I need to wear masks?')

clearSuggestions

Clear suggestions data

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"

on('send-to-chat`)

Triggered when agent clicks on Send to chat

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 snippet

Example

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

on('copy-hashtag`)

Triggered when agent copies hashtag text

Example

shelf.AgentAssist.on('copy-hashtag', ({snippet, location}) => {
    ...
})

on('content-linked`)

since 1.17.0

Triggered when agent link gem to an interaction

Example

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

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:

| 'suggestions'
| 'search'
| 'gem'
| 'favorites'
| 'workflow'
| 'announcements'

// since 1.6.0
| 'question-suggestions'
| 'context-suggestions'

// since 1.17.0
| 'links'
Name Type
tab Tab

Returns: Promise

Example

shelf.AgentAssist.openTab('suggestions')

request

Allows making custom request to the api

request(params: RequestParams): Promise

Parameters:

Name Type
params RequestParams

Returns: Promise

RequestParams

{
  url: string;
  method: 'PATCH' | 'POST' | 'DELETE' | 'GET' | 'PUT';
  body?: Record<string, any>;
  headers?: Record<string, any>;
}

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

{
  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

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

setCustomStyles

Allows customizing styles of Agent Assist App

setCustomStyles(payload: string): Promise

Parameters:

Name Type
payload string

Returns: Promise

Example

shelf.AgentAssist.setCustomStyles('html {font-size: 13px}');

applySearch

Allows running custom search with filters; Check API for supported filter

applySearch(payload: SearchFilters): Promise

Parameters:

Name Type
payload SearchFilters

Returns: Promise

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

SortOptions =
  'RECENT_FIRST' |
  'OLDEST_FIRST' |
  'RECENTLY_UPDATED_FIRST' |
  'RECENTLY_UPDATED_LAST' |
  'A_Z' |
  'Z_A' |
  'RELEVANCE' |
  'BY_GEM_IDS';

SortByType: 'TITLE' | 'CREATED_DATE' | 'UPDATED_DATE' | 'RELEVANCE' | 'RATING' | 'VIEWS';

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

agentAssistVersion

Get the version of Shelf Agent Assist

agentAssistVersion: string

Example

SDK.agentAssistVersion // ex: 1.0.0

Examples

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

License

MIT © Shelf