Skip to main content

API

Classes

AnalyticsEvent

Creates a new AnalyticsEvent.

Command

Creates a new base Command that handles a particular intent. Specific commands

Analytics

Middleware to track user events.

Properties sent to the analytics service are in snake_case, based on Segment naming conventions.

Some properties are encrypted or excluded, based on Webex Teams recommendations.

  • Users identified by Webex Teams' hashed ID
  • Org names/domain names are reported (not org ID)
  • Single event records do not include both sides of a communication
Bridge
Input

Text input.

Auth
DeploymentConfigError
SalesforceError
Salesforce

Constants

UNKNOWN : String

Placeholder for unknown property value.

UNKNOWN_NUMBER : number

Placeholder for unknown number property value.

MESSAGE_SENT : String

Event name when a message is sent by the user.

MESSAGE_RECEIVED : String

Event name when a bot sends a message to the user and the user (presumably) receives it.

REGEX_NEVER_MATCH : RegExp

A regular expression that never matches anything.

ATTACHMENT_EVENT : string

Name of the event fired when a user engages with an attachment, e.g., an Adaptive Card.

INTENT_DETECTED_EVENT : string

Event name to emit when an intent is detected.

MESSAGE : String

Message sent to a bot in a group space.

DIRECT_MESSAGE : String

Message sent to a bot in a one-on-one space.

STANDARD_MESSAGE_TYPES : Object

Most common bot message types, e.g., "message", "direct_message". Most bots will want to listen for both group and direct messages.

INTENT_MATCHING_TYPES : Object

Ways that a message intent can be detected - with an official intent property, or through pattern-matching.

analyticsEvent

Analytics event.

searchOptions

Giphy search options

eventTemplate

Custom event and properties for analytics.

TEXT_LIMIT

Text limit to avoid DialogFlow error: INVALID_ARGUMENT: Input text exceeds 256 characters.

BASIC_PROPS : Array.<String>

A person must have all of these properties defined to be considered "data complete".

ARCHIVE

Backup directories and files as an archive.

DRY_RUN

Perform a dry run.

IGNORE_TIMESTAMPS

Ignore timestamps to force overwriting similar destination files.

RSYNC_OPTIONS

Use these options for rysnc backup.

DEFAULT_CONFIG : BridgeConfig

Default configuration

GOOGLE_CLOUD_PROJECT
DEFAULT_RELEASES_DIRECTORY : String

Release configuration directory.

DOCKER_COMPOSE_ORIG

"docker-compose build" command

"docker compose" and "docker-compose" are different. Use docker-compose to enable builds with ARGS.

KUBERNETES_DEPLOYMENT

Deployment kinds

SOQL_WILDCARD

Encoded wildcard character for SOQL queries.

SOQL_WILDCARD

Encoded wildcard character for SOQL queries.

Functions

getTime(date)

Returns the date's time in seconds.

main()

Runs the program, parsing any command line options first.

runBridge(source, project, options, command)

Creates a new Bridge from the source, copying the source files to the given project and excluding them from repo commits and package publishing.

getDomain(url) โ‡’ String

Returns the base domain from the given URL.

formatApiVersion(version) โ‡’

Formats the given version number, e.g., "51.0".

getQueryPath(version) โ‡’

Returns the query path, e.g., "services/data/v51.0/query".

getSalesforceObjectsPath(version) โ‡’

Returns the Salesforce objects path, e.g., "services/data/v51.0/sobjects".

getServicesPath(version) โ‡’

Returns the services path, e.g., "services/data/v44.0"

Typedefs

CommandConfig : Object

Command configuration

Message : Object

A message

Message : Object

A message

Command : Object

A command

IntentConfig : Object

Intent configuration

User : Object

User data.

Responses sent from the bot are not sent to a particular user, but to a Webex Teams space. In order to track events from the User's perspective, we need to internally track user data.

space : Object

Partial known space data.

Spaces : Map

Known spaces. Keys are of type Space.space_id. Properties are of type Space.

UserProp : Object

Map of user property names and formatting functions.

MinimalSpace : Object

The space with the message. This space has only one property: an ID.

ShouldTrack : Object

If and why an event should be tracked or not tracked

MinimalUser : Object

The user (person, bot) receiving a message. This user has a minimal number of properties.

UserInfo : Object

User information for an analytics event

CredentialBody : Object

A Google Auth CredentialBody

IntentConfig : Object

Intent configuration

PhoneNumber : Object

Person's phone number.

Person : Object

A typical bot user

People : Map

Known people.

Keys are of type Person.id. Properties are of type Person.

WebexPerson : Object

A Webex user

Properties beginning with an underscore denote those not normally in a Botkit Person object.

BridgeConfig : Object

Configuration options

Rollback : Object

Rollback information

AdaptiveCard : Object

Adaptive Card

Adaptive Card based on the Adaptive Card schema.

ChoicesConfig
Choice
CredentialBody : Object

Google Auth CredentialBody

ReleaseConfig : Object

Release configuration

SalesforceUser : Object

Salesforce user data.

AnalyticsEvent

Creates a new AnalyticsEvent.

Kind: global class

new AnalyticsEvent(name, properties)

ParamTypeDescription
nameStringEvent name
propertiesObjectEvent properties

analyticsEvent.updateProperty(name, value)

Adds the given property and value to the event. Converts the property name to snake_case to adhere to best practices.

Kind: instance method of AnalyticsEvent

ParamTypeDescription
nameStringProperty name
valueStringProperty value

Command

Creates a new base Command that handles a particular intent. Specific commands

Kind: global class

new Command(config)

Creates a new command. Listens to direct and group messages by default.

ParamTypeDescription
configCommandConfigoptional configuration

command.controller

See "Getters and Setters":

Kind: instance property of Command
See: https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Objects/Inheritance

command.updateController(controller)

Configures the controller to listen for the command phrases and attachment actions, e.g., Adaptive Card actions.

Kind: instance method of Command

ParamType
controllerBotkit

command.defaultHandleText()

Handles text commands by default. Prints a debug statement.

Kind: instance method of Command

command.defaultHandleAttachment()

Handles attachments by default. Prints a debug statement.

Kind: instance method of Command

command.getIntent(message) โ‡’ boolean

Returns the detected intent of the message. If there is no "official" intent attached, uses pattern-matching to determine the intent from the command's list of phrases.

Kind: instance method of Command
Returns: boolean - true if intent was detected, false if not
Emits: Intent#event:detected
See: https://botkit.ai/docs/v4/reference/core.html#hears

ParamType
messageMessage

command._matchNamedIntent(intent) โ‡’ Boolean

Returns true if the intent name matches this intent, false otherwise.

Kind: instance method of Command
Returns: Boolean - true if the intent name matches this intent
See: https://stackoverflow.com/a/9436948/154065

ParamType
intentString | Object

Command.getPhraseExpression(phrases) โ‡’ RegExp

Joins the given phrases into a regular expression.

Kind: static method of Command
Returns: RegExp - joined phrases

ParamTypeDescription
phrasesArrayThe phrases to join

Command.matchPhrase(message, phrase) โ‡’ boolean

Returns true if the user's message text matches the list of command phrases.

Kind: static method of Command
Returns: boolean - true if the user's message matches a known command

ParamTypeDescription
messageMessage | stringthe user's message or message text
phraseRegExpthe phrase to match

Analytics

Middleware to track user events.

Properties sent to the analytics service are in snake_case, based on Segment naming conventions.

Some properties are encrypted or excluded, based on Webex Teams recommendations.

  • Users identified by Webex Teams' hashed ID
  • Org names/domain names are reported (not org ID)
  • Single event records do not include both sides of a communication

Kind: global class

new Analytics(apiKey, config)

ParamTypeDescription
apiKeyStringthe analytics service API key
configObjectconfiguration details
config.appEnvironmentObjectapplication environment, e.g., development, staging
config.appVersionObjectapplication version
config.urlStringthe analytics service URL
config.userPropsArray.<(String|UserProps)>the additional user properties to track

analytics.userProps

Sets additional user properties to pick from each incoming message.

Kind: instance property of Analytics

ParamTypeDescription
propsMap | Array.<Array.<String>>user property names and friendly names

analytics.trackUserMessage(bot, message, next)

Tracks messages from the user to the bot.

Kind: instance method of Analytics
Note: Use with the middleware receive function.

ParamType
bot*
message*
next*

Example

const analyticsMiddleware = new Analytics();
controller.middleware.receive.use(analyticsMiddleware.trackUserMessage);

analytics.trackBotMessage(bot, message, next)

Tracks messages from the bot to the user.

Kind: instance method of Analytics
Note: Use with the middleware send function.

ParamType
bot*
message*
next*

Example

const analyticsMiddleware = new Analytics();
controller.middleware.send.use(analyticsMiddleware.trackBotMessage);

analytics._getAdditionalUserProps(user) โ‡’ Object

Get the additional, desired user properties.

Kind: instance method of Analytics
Returns: Object - additional user properties

ParamTypeDescription
userObjectadditional user info attached to the message

analytics._getSpaceInfo(minimalSpace) โ‡’ Object

Gets more space information.

Kind: instance method of Analytics
Returns: Object - space with more details

ParamTypeDescription
minimalSpaceMinimalSpacespace with the message

analytics._getUserInfo(user) โ‡’ UserInfo

Gets the user properties for the analytics event.

Kind: instance method of Analytics
Returns: UserInfo - user information for an analytics event

ParamType
userMinimalUser

analytics._getStandardInfo(timestamp) โ‡’ Object

Gets information standard to all analytics events.

Kind: instance method of Analytics
Returns: Object - app version and time

ParamTypeDescription
timestampnumbertime in seconds

Analytics.PROPERTY_VALUES

Attach "static" property to the class.

Kind: static property of Analytics
See: https://stackoverflow.com/a/48012789/154065

Bridge

Kind: global class

new Bridge(source, project, config)

Creates a new Bridge from the source to the destination project.

ParamTypeDescription
sourceStringthe source directory
projectStringthe destination project directory
configBridgeConfigconfiguration options

bridge.source

Sets the source directory.

Kind: instance property of Bridge
Throws:

  • DirectoryError

bridge.project

Sets the project directory.

Kind: instance property of Bridge
Throws:

  • DirectoryError
  • ProjectError

bridge.copy() โ‡’ String

Copies files from the source directory to the project destination directory.

Kind: instance method of Bridge
Returns: String - the destination path where files were copied
Throws:

  • SourceIsDestError

bridge.gitIgnore()

Adds destination and backup file paths to .gitignore so the files are not committed to the project repo.

Kind: instance method of Bridge

bridge._rollbackFile(original, backup) โ‡’ Rollback

Rolls back the file to the original copy.

Kind: instance method of Bridge
Returns: Rollback - rollback information
Throws:

  • RollbackError
ParamTypeDescription
original*the original file path
backup*the backup file path

bridge.publishIgnore()

Adds destination file paths to the monorepo config. These files will be ignored when publishing packages.

Kind: instance method of Bridge

Bridge.isMonoRepo(project) โ‡’ boolean

Returns true if the project is a valid monorepo, false otherwise.

Kind: static method of Bridge
Returns: boolean - true if the project is a valid monorepo, false otherwise

ParamTypeDescription
projectStringthe project directory

Bridge.copy() โ‡’ String

Copies files from the source to the destination.

Kind: static method of Bridge
Returns: String - the destination path where files were copied

Bridge.isDirectory(dir) โ‡’ boolean

Returns true if the given path is a directory, false otherwise.

Kind: static method of Bridge
Returns: boolean - true if the given path is a directory, false otherwise
See: https://stackoverflow.com/a/32749571/154065

ParamTypeDescription
dirStringthe directory path

Input

Text input.

Kind: global class
See: https://shoelace.style/components/form

Auth

Kind: global class
See: https://www.npmjs.com/package/google-auth-library

Auth.getCredentials(credentials) โ‡’ CredentialBody

Gets the authorization credentials.

Kind: static method of Auth
Returns: CredentialBody - credentials

ParamTypeDescription
credentialsStringfile path or JSON string containing credentials

Auth.parseCredentials(credentials) โ‡’ CredentialBody

Parses the given credentials.

Kind: static method of Auth
Returns: CredentialBody - credentials needed to authorize

ParamTypeDescription
credentialsStringfile path or JSON string containing credentials

DeploymentConfigError

Kind: global class

new DeploymentError(message)

ParamTypeDescription
messageStringerror message

SalesforceError

Kind: global class

new SalesforceError(message)

ParamTypeDescription
messageStringerror message

Salesforce

Kind: global class

new Salesforce(url, adapter)

Create instance of Salesforce controller

ParamTypeDescription
urlStringSalesforce host address
adapterObjectSalesforce adapter

UNKNOWN : String

Placeholder for unknown property value.

Kind: global constant

UNKNOWN_NUMBER : number

Placeholder for unknown number property value.

Kind: global constant

MESSAGE_SENT : String

Event name when a message is sent by the user.

Kind: global constant

MESSAGE_RECEIVED : String

Event name when a bot sends a message to the user and the user (presumably) receives it.

Kind: global constant

REGEX_NEVER_MATCH : RegExp

A regular expression that never matches anything.

Kind: global constant
See: https://2ality.com/2012/09/empty-regexp.html

ATTACHMENT_EVENT : string

Name of the event fired when a user engages with an attachment, e.g., an Adaptive Card.

Kind: global constant

INTENT_DETECTED_EVENT : string

Event name to emit when an intent is detected.

Kind: global constant

MESSAGE : String

Message sent to a bot in a group space.

Kind: global constant

DIRECT_MESSAGE : String

Message sent to a bot in a one-on-one space.

Kind: global constant

STANDARD_MESSAGE_TYPES : Object

Most common bot message types, e.g., "message", "direct_message". Most bots will want to listen for both group and direct messages.

Kind: global constant

INTENT_MATCHING_TYPES : Object

Ways that a message intent can be detected - with an official intent property, or through pattern-matching.

Kind: global constant

analyticsEvent

Analytics event.

Kind: global constant

searchOptions

Giphy search options

Kind: global constant
See: https://developers.giphy.com/docs/api/endpoint/

eventTemplate

Custom event and properties for analytics.

Kind: global constant

TEXT_LIMIT

Text limit to avoid DialogFlow error: INVALID_ARGUMENT: Input text exceeds 256 characters.

Kind: global constant

BASIC_PROPS : Array.<String>

A person must have all of these properties defined to be considered "data complete".

Kind: global constant

ARCHIVE

Backup directories and files as an archive.

Kind: global constant
See: https://serverfault.com/a/141778/106402

DRY_RUN

Perform a dry run.

Kind: global constant

IGNORE_TIMESTAMPS

Ignore timestamps to force overwriting similar destination files.

Kind: global constant

RSYNC_OPTIONS

Use these options for rysnc backup.

Kind: global constant

DEFAULT_CONFIG : BridgeConfig

Default configuration

Kind: global constant

GOOGLE_CLOUD_PROJECT

Kind: global constant
See: https://github.com/googleapis/google-auth-library-nodejs/blob/1ca3b733427d951ed624e1129fca510d84d5d0fe/src/auth/googleauth.ts#L646

DEFAULT_RELEASES_DIRECTORY : String

Release configuration directory.

Kind: global constant

DOCKER_COMPOSE_ORIG

"docker-compose build" command

"docker compose" and "docker-compose" are different. Use docker-compose to enable builds with ARGS.

Kind: global constant
See: https://stackoverflow.com/a/67853849/154065

KUBERNETES_DEPLOYMENT

Deployment kinds

Kind: global constant

SOQL_WILDCARD

Encoded wildcard character for SOQL queries.

Kind: global constant

SOQL_WILDCARD

Encoded wildcard character for SOQL queries.

Kind: global constant

getTime(date)

Returns the date's time in seconds.

Kind: global function

ParamTypeDescription
dateDatethe date to convert

main()

Runs the program, parsing any command line options first.

Kind: global function

runBridge(source, project, options, command)

Creates a new Bridge from the source, copying the source files to the given project and excluding them from repo commits and package publishing.

Kind: global function
See: https://github.com/tj/commander.js#action-handler

ParamTypeDefaultDescription
sourceStringthe source directory
projectString.the destination project directory
optionsObjectthe program options from the command line
commandObjectthe program command

getDomain(url) โ‡’ String

Returns the base domain from the given URL.

Kind: global function
Returns: String - domain of the URL

ParamType
urlURL | String

formatApiVersion(version) โ‡’

Formats the given version number, e.g., "51.0".

Kind: global function
Returns: formatted API version number

ParamTypeDescription
versionString | numberAPI version number

getQueryPath(version) โ‡’

Returns the query path, e.g., "services/data/v51.0/query".

Kind: global function
Returns: the Salesforce query path

ParamTypeDescription
versionStringformatted API version number

getSalesforceObjectsPath(version) โ‡’

Returns the Salesforce objects path, e.g., "services/data/v51.0/sobjects".

Kind: global function
Returns: the Salesforce objects path

ParamTypeDescription
versionStringformatted API version number

getServicesPath(version) โ‡’

Returns the services path, e.g., "services/data/v44.0"

Kind: global function
Returns: the services path

ParamTypeDescription
versionStringformatted API version number

CommandConfig : Object

Command configuration

Kind: global typedef
Properties

NameTypeDescription
intentStringname of the intent
messageTypesArray.<string>Types of messages to listen for, e.g., a direct (1-on-1) message
phrasesArray.<string>Phrases to listen for
handleTextfunctionHandles message text
handleAttachmentfunctionHandles message attachment actions, e.g., Adaptive Card clicks
friendlyNamestringFriendly name of the command

Message : Object

A message

Kind: global typedef
Properties

NameTypeDescription
_intentObjectThe detected user intent
textstringThe message text

Message : Object

A message

Kind: global typedef

Command : Object

A command

Kind: global typedef
Properties

NameType
friendlyNameString

new Command(config)

Creates a new command. Listens to direct and group messages by default.

ParamTypeDescription
configCommandConfigoptional configuration

command.controller

See "Getters and Setters":

Kind: instance property of Command
See: https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Objects/Inheritance

command.updateController(controller)

Configures the controller to listen for the command phrases and attachment actions, e.g., Adaptive Card actions.

Kind: instance method of Command

ParamType
controllerBotkit

command.defaultHandleText()

Handles text commands by default. Prints a debug statement.

Kind: instance method of Command

command.defaultHandleAttachment()

Handles attachments by default. Prints a debug statement.

Kind: instance method of Command

command.getIntent(message) โ‡’ boolean

Returns the detected intent of the message. If there is no "official" intent attached, uses pattern-matching to determine the intent from the command's list of phrases.

Kind: instance method of Command
Returns: boolean - true if intent was detected, false if not
Emits: Intent#event:detected
See: https://botkit.ai/docs/v4/reference/core.html#hears

ParamType
messageMessage

command._matchNamedIntent(intent) โ‡’ Boolean

Returns true if the intent name matches this intent, false otherwise.

Kind: instance method of Command
Returns: Boolean - true if the intent name matches this intent
See: https://stackoverflow.com/a/9436948/154065

ParamType
intentString | Object

Command.getPhraseExpression(phrases) โ‡’ RegExp

Joins the given phrases into a regular expression.

Kind: static method of Command
Returns: RegExp - joined phrases

ParamTypeDescription
phrasesArrayThe phrases to join

Command.matchPhrase(message, phrase) โ‡’ boolean

Returns true if the user's message text matches the list of command phrases.

Kind: static method of Command
Returns: boolean - true if the user's message matches a known command

ParamTypeDescription
messageMessage | stringthe user's message or message text
phraseRegExpthe phrase to match

IntentConfig : Object

Intent configuration

Kind: global typedef
Properties

NameTypeDescription
projectIdStringthe project ID
knowledgeBaseIdStringthe knowledge base ID
credentialsCredentialBodycredentials needed to sign into the intent API

User : Object

User data.

Responses sent from the bot are not sent to a particular user, but to a Webex Teams space. In order to track events from the User's perspective, we need to internally track user data.

Kind: global typedef
Properties

NameTypeDescription
user_idStringEncrypted user ID
domainStringDomain of the user, e.g., cisco.com

space : Object

Partial known space data.

Kind: global typedef
Properties

NameTypeDescription
space_idStringspace ID
space_typeStringspace type, e.g., "direct" or "group"

Spaces : Map

Known spaces. Keys are of type Space.space_id. Properties are of type Space.

Kind: global typedef

UserProp : Object

Map of user property names and formatting functions.

Kind: global typedef
Properties

NameTypeDescription
nameStringuser property name
formatfunctionfunction to format the user property name

MinimalSpace : Object

The space with the message. This space has only one property: an ID.

Kind: global typedef

ParamTypeDescription
idStringID of the space with the message

ShouldTrack : Object

If and why an event should be tracked or not tracked

Kind: global typedef
Properties

NameTypeDescription
shouldTrackbooleantrue if an event should be tracked, false otherwise
reasonStringreason an event is tracked or not tracked

MinimalUser : Object

The user (person, bot) receiving a message. This user has a minimal number of properties.

Kind: global typedef

ParamTypeDescription
idStringID of the user receiving the message
nameStringemail of the user receiving the message

UserInfo : Object

User information for an analytics event

Kind: global typedef
Properties

NameTypeDescription
user_idstringuser ID
user_propertiesObjectuser properties
user_properties.app_environmentstringthe app environment, e.g., "development", "staging"
user_properties.domainstringthe domain of the user, e.g., "cisco.com"

CredentialBody : Object

A Google Auth CredentialBody

Kind: global typedef
See

Properties

NameType
client_emailString
private_keyString
project_idString

IntentConfig : Object

Intent configuration

Kind: global typedef
Properties

NameTypeDescription
projectIdStringthe project ID
knowledgeBaseIdStringthe knowledge base ID
credentialsCredentialBodycredentials needed to sign into the intent API

PhoneNumber : Object

Person's phone number.

Kind: global typedef
Properties

NameTypeDescription
typeStringtype of phone number, e.g., work, home
valueStringphone number itself, e.g., '+1 555 867 5309'

Person : Object

A typical bot user

Kind: global typedef
Properties

NameTypeDescription
idStringEncrypted person ID
emailsArray.<String>email addresses
phoneNumbersArray.<PhoneNumber>phone numbers
displayNameStringdisplay name
nickNameStringnickname
firstNameStringfirst name
lastNameStringlast name
avatarStringURL of person's avatar at 1600px
orgIdStringencrypted organization ID
createdDatedate person was created in Webex Teams, e.g., 2014-06-20T20:35:16.172Z
typeStringtype of user, e.g., "person"

People : Map

Known people.

Keys are of type Person.id. Properties are of type Person.

Kind: global typedef

WebexPerson : Object

A Webex user

Properties beginning with an underscore denote those not normally in a Botkit Person object.

Kind: global typedef
Properties

NameTypeDescription
_cecIdStringCisco Employee Connection ID
_cecEmailStringCisco Employee Connection email, e.g., cecid@cisco.com
_contactTypeStringtype of contact, e.g., "Cisco" or "Partner"
_domainStringdomain name, e.g., cisco.com
_rolesArray.<String>user's roles

BridgeConfig : Object

Configuration options

Kind: global typedef
Properties

NameTypeDescription
dryRunbooleanperform a dry run

Rollback : Object

Rollback information

Kind: global typedef

ParamTypeDescription
originalStringthe original file path
backupStringthe backup file path

AdaptiveCard : Object

Adaptive Card

Adaptive Card based on the Adaptive Card schema.

Kind: global typedef

ChoicesConfig

Kind: global typedef

ParamTypeDescription
getChoiceTitlefunctiondetermine the title displayed on the UI
getChoiceValuefunctiondetermine the value

Choice

Kind: global typedef

ParamTypeDescription
choiceStringtitle of the choice as it appears in the UI
valueStringvalue of the choice "behind-the-scenes"

CredentialBody : Object

Google Auth CredentialBody

Kind: global typedef
See

Properties

NameTypeDescription
client_emailString
private_keyString
project_idStringproject ID (optional)

ReleaseConfig : Object

Release configuration

Kind: global typedef
Properties

NameTypeDescription
releasesDirStringpath to a releases directory

SalesforceUser : Object

Salesforce user data.

Kind: global typedef
Properties

NameTypeDescription
idStringuser ID
usernameStringusername
accessTokenStringuser's API access token
organizationIdStringuser's organization ID
urlStringfull URL after signing in, e.g, https://SUBDOMAIN.my.salesforce.com/id/ORGANIZATION-ID/USER-ID