@cxco/dcx-connector v2.3.0
@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)
}