@cxco/dcx-connector

2.3.0 • Public • Published

@CXCO/DCX-CONNECTOR

Library to query DigitalCX endpoints using a common query interface and getting normalized answers.


Why should I use the @cxco/dcx-connector?

The @cxco/dcx-connector is a simple JavaScript library that wraps all the DigitalCX standard endpoints using a simple inbount/outbound data contract. It uses axios under the hood to make the HTTP requests. This library also exports the data contracts in case you want to use your own HTTP client but want to normalize the responses.

Installing

Using npm:

npm install @cxco/dcx-connector

Quickstart

Performing an 'ask' request:

import { doDcxRequest } from '@cxco/dcx-connector'

const payload = {
    type: 'ask',
    data: {
        userInput: 'some question'
    },
    metadata: {},
    config: {
        baseUrl: 'https://your-digitalcx-endpoint',
        apiKey: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx',
        culture: 'en',
        customerKey: 'your-customer-key' // only needed if you're using the new CAIC URL 
        projectKey: 'your-project-key' // only needed if you're using the new CAIC URL
    }
}

const answer = await doDcxRequest(payload)

you'll get a response with a payload with two objects inside (data and metadata):

{
  "data":  {
    "answer": "some answer",
    "dialogOptions":  [],
    "images":  [],
    "links":  [],
    "outputAdditions":  {},
    "type": "answer",
    "videos":  []
  },
  "metadata":  {
    "culture": "en",
    "interactionId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "sessionId": "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "id": 0
  }
}

Request Payload

Type

The request can be of the following types:

  • "ask"
  • "dialogstep"
  • "event"
  • "linkclick"
  • "feedback"
  • "faq"
  • "faqsincategory"
  • "defaultfaqs"
  • "categorytree"
  • "category"
  • "searchfaqs"
  • "autocomplete"

Data

The data section allows to pass the main information to the request, e.g. what question needs to be asked. The properties are added to the data object depending on the request being made.

Property Name Description
userInput The question to be asked to the engine. Used in "ask", "searchfaqs" and "autocomplete" requests
dialogPath When in a dialog, it's a node's "Dialog Path". Used in "ask" and "dialogstep" requests
eventName The event to be triggered. Used in the "event" request
classificationId The Classification Id. Used in "faqsincategory", "defaultfaqs", "categorytree", "category" and "searchfaqs" requests
categoryId The Category Id. Used in "faqsincategory" and "category" requests
faqId The FAQ Id. Used in the "faq" request
interactionId The interaction Id. Used in "linkclick" and "feedback" requests
linkId The clicked link id. Used in the "linkclick" request
linkUrl The clicked link URL. Used in the "linkclick" request
score The feedback score. Used in the "feedback" request
label The feedback label. Used in the "feedback" request
comment The feedback comment. Used in the "feedback" request

Metadata

The metadata section allows to pass additional information to the request, e.g. minimum number of FAQs needed. The properties depend on the request being made.

Property Name Description
context Array of context variables and corresponding values
includeFaqs Include FAQs in categories
maxFaqs Maximum number of FAQs to be included in the request
minFaqs Minimum number of FAQs to be included in the request
session Session properties and corresponding values
sessionId The current session Id
sessionMode The session mode
tDialogState The TDialog state
user User properties and corresponding values
max Maximum number of words from dictionary
offset Offset for autocomplete
region The region where the original data resides, e.g. West Europe or Southeast Asia
headers Object containing properties referer and userAgent

Config

The config section contains the information related to the how and where to do the request.

Property Name Description Mandatory
baseUrl the URL of the API yes
apiKey the API key yes
culture language (en/nl/de) yes
timeout time in milliseconds until request times out no
customerKey the customer key (only needed when using the new CAIC URL) yes/no
projectKey the project key (only needed when using the new CAIC URL) yes/no

If you're using the new CAIC URL, the project key and customer key are also needed in the config

Example: using just the data contrats

The "buildRequest" data contract generates an object that is accepted by axios as a request configuration.

// import data contracts from the @cxco/dcx-connector
import { buildRequest, buildResponse } from '@cxco/dcx-connector'


const dcxRequest = async (payload) => {

    const requestConfig = buildRequest(payload)

    if (requestConfig === null) {
      throw new Error('Invalid payload')
    }

    const dcxResponse = await httpClient.doRequest(requestConfig)

    return buildResponse(dcxResponse)
}

Dependencies (2)

Dev Dependencies (14)

Package Sidebar

Install

npm i @cxco/dcx-connector

Weekly Downloads

21

Version

2.3.0

License

ISC

Unpacked Size

30.1 kB

Total Files

7

Last publish

Collaborators

  • cx-company
  • remcodevries
  • bo.strijker