BOTfriends X SDK

BOTfriends X SDK helps you interact with the BOTfriends X Platform. It is designed to give you the opportunity to create custom integrations. You can run event requests to the used nlp service and create your own responses with it.

Installation

npm install botfriends-x-sdk

Usage

const { BotfriendsClient } = require('botfriends-x-sdk')

// init your client
const bfClient = new BotfriendsClient('some-jwt')

const textResponse = bfclient.message.createTextResponse('some text')

// ...

Methods

Handover

| Method | Description | | ------ | ----------- | | deleteUserMessages | to delete messages of a user | | exportConversations | to export conversations | | exportUserMessages | to export messages of a user | | exportProjectMessages | to export all messages of the project | | getOnlineAgents | to get agents that are currently online | | startHandover | to start the handover for a conversation | | isInHoursOfOperation | to check if currently inside hours of operation |

deleteUserMessages

const userId : String

bfClient.handover.deleteUserMessages(userId)

exportConversations

const userId : String

const exportResponse = bfClient.handover.exportConversations()

exportResponse = [{
  ...
]}

exportUserMessages

const userId : String

const exportResponse = bfClient.handover.exportUserMessages(userId)

exportResponse = [{
  ...
]}

exportProjectMessages

const exportResponse = bfClient.handover.exportProjectMessages()

exportResponse = [{
  ...
]}

getOnlineAgents

const onlineAgentsResponse = bfClient.handover.getOnlineAgents()

onlineAgentsResponse = { onlineAgents: Number }

startHandover

const conversationId : String
const options : StartHandoverOptions = {
  ignoreHoursOfOperation?: Boolean,
  ignoreAgentAvailability?: Boolean
}

const startHandoverResponse = bfClient.handover.startHandover(conversationId, options?)

startHandoverResponse = { success: Boolean }

isInHoursOfOperation

const isInHoursOfOperationResponse = bfClient.handover.isInHoursOfOperation()

isInHoursOfOperationResponse = { isInHoursOfOperation: Boolean }

Intent Management

| Method | Description | | ------ | ----------- | | lastChanges | to load the last IM changes | | entities | to load the entities | | export | to load the IM export data |

lastChanges

const labels? : String[] // Optional, if skipped or invalid, all changes will be returned

const lastChangesResponse = bfClient.im.lastChanges(labels)

lastChangesResponse = {
  id: String,
  notes: String[],
  projectId: String,
  userEmail: String,
  user: String,
  type: String,
  nluId: String,
  updatedKeys: String[],
  timestamp: Number,
  nluService: String,
  intentId: String,
  intentName: String
}

entities

const entitiesResponse = bfClient.im.entities()

entitiesResponse = [{
  id: String,
  name: String,
  type: String,
  nluId: String,
  entities: [{
    entities: [{
        value: String,
        synonyms: String[]
      }
    ],
    languageCode: String
  }]
}],

export

const exportResponse = bfClient.im.export()

exportResponse = {
  intents: IM.Intent[]
  customEntities: IM.CustomEntity[],
  settings: ISettingsExport,
  nluExport: any
}

NLP

| Method | Description | | ------ | ----------- | | addOutputContexts | to add output contexts | | deleteAllOutputContexts | to delete all output contexts | | eventRequest | to run an event request | | detectIntent | to make an intent detection |

addOutputContexts

const recipient : String
const contexts : any[]

bfClient.nlp.addOutputContexts(recipient, contexts)

deleteAllOutputContexts

const recipient : String

bfClient.nlp.deleteAllOutputContexts(recipient)

eventRequest

const eventName : String
const recipient : String
const languageCode? : String // Optional: If no language Code is specified, the default language is used
const channel? : String // Optional

const eventRequestResponse = bfClient.nlp.eventRequest(eventName, recipient, languageCode, channel)

eventRequestResponse = {
  invocationType: 'event',
  recipient: String,
  channel: String,
  intentId: String,
  detectedIntent: String,
  intentMetaData: {
    cofidenceScore: Number,
    languageCode: String
  },
  input: String,
  detectedAction: String,
  detectedEvents: [String],
  parameters: any,
  context: {
    inputcontext: any,
    outputcontext: any
  },
  outputs: [
    {
      type: String,
      messageType
    }
  ]
}

detectIntent

const userQuery : String
const recipient : String
const languageCode? : String // Optional: If no language Code is specified, the default language is used
const channel? : String // Optional

const dectIntentResponse = bfClient.nlp.detectIntent(userQuery, recipient, languageCode, channel)

detectIntentResponse = {
  invocationType: 'userQuery',
  recipient: String,
  channel: String,
  intentId: String,
  detectedIntent: String,
  intentMetaData: {
    cofidenceScore: Number,
    languageCode: String
  },
  input: String,
  detectedAction: String,
  detectedEvents: [String],
  parameters: any,
  context: {
    inputcontext: any,
    outputcontext: any
  },
  outputs: [
    {
      type: String,
      messageType
    }
  ]
}

Messages

| Method | Description | | ------ | ----------- | | createTextResponse | to create a botfriends text response | | createImageResponse | to create a botfriends image response | | createCardResponse | to create a botfriends card response | | createQuickreply | to create a botfriends quickreply response | | createQuickreplyElement | to create a botfriends quickreply element | | createVoiceResponse | to create a botfriends voice response | | createForwardingMessage | to create a botfriends forwarding call response |

createTextResponse

const text : String

const textResponse = bfClient.message.createTextResponse(text)

textResponse = {
  type: 'text',
  message: { text: String }
}

createImageResponse

const imageURL : String

const imageRepsonse = bfClient.message.createImageResponse(imageURL)

imageRepsonse = {
  type: 'image',
  message: { image: String }
}

createCardResponse

const title : String
const subtitle? : String
const image? : String
const buttons?: [
  { title: String, postback: String }
]


const cardResponse = bfClient.message.createCardResponse(title, subtitle?, image?, buttons?)

cardResponse = {
  type: 'card',
  message: {
    card: {
      title: String,
      subtitle: String,
      image: String,
      buttons: [
        {
          title: String,
          postback: String
        }
      ]
    }
  }
}

createQuickreply

const text : String
const quickreply : [quickreplyElements]

const quickreplyElementResponse = bfClient.message.createQuickreplyElement(text, quickreply)

quickreplyElementResponse = {
  type: 'quickreply',
  message: {
    text: String,
    quickreply: [quickreplyElements]
  }
}

createQuickreplyElement

const title : String
const postback : String

const quickreplyResponse = bfClient.message.createQuickreply(title, postback)

quickreplyResponse = {
  title: String,
  postback: String
}

createVoiceResponse

const voicemessage : String
const ssml : Boolean


const voiceResponse = bfClient.message.createVoiceResponse(voicemessage, ssml)

voiceResponse = {
  type: 'voice',
  message: {
    voice: String,
    ssml: Boolean
  }
}

createForwardingMessage

const phoneNumber : String

const forwardingCallResponse = bfClient.message.createForwardingMessage(phoneNumber)

forwardingCallResponse = {
  type: 'callForwarding',
  message: {
    phoneNumber: String
  }
}

Send

| Method | Description | | ------ | ----------- | | text | to push text message to a user | | outputs | to push output messages to a user |

text

const userId : String
const message: String
const role?: Role

bfClient.send.text(userId, message, role)

outputs

const userId : String
const outputs: Output[]
const role?: Role

bfClient.send.outputs(userId, outputs, role)

Utils

| Method | Description | | ------ | ----------- | | extractParams | converts the Botfriends-X Intent Paramaters to simple key-value object. For example {name: {kind: 'stringValue', stringValue: 'John'}} will result {name: 'John'}| | replaceOutputPlaceholders | replaces placeholders with params in the given intent responses. For example: Params: {name: 'John'}, intent with output: 'Welcome #name!' will result the intent with output: 'Welcome John!'| | createContext | creates a Botfriends-X output context | | getContextParam | returns context param from the given intent with the given key |

extractParams

const parameters : BF-X Parameter

const extractParamsResult = bfClient.utils.extractParams(parameters)

extractParamsResult = {} // any object

replaceOutputPlaceholders

const params : {[key: string]: string}
const intent: BF-X Intent

bfClient.utils.replaceOutputPlaceholders(params, intent)

createContext

const contextBaseUrl : String
const userId : String
const name: String
const params: {[key: string]: string}
const lifespanCount?: Number  // Optional: If no lifespanCount is specified, the default lifespanCount is 1

const createContextResult = bfClient.utils.createContext(contextBaseUrl, userId, name, params, lifespanCount)

createContextResult = {
  name: String
  lifespanCount: Number
  parameters: {
    fields: Parameter
  }
}

getContextParam

const intent: BF-X Intent
const key : String

const getContextParamResult = bfClient.utils.getContextParam(intent, key)

getContextParamResult = String | null

If you have any problems, contact us here

Authors

• BOTfriends GmbH