@botpress/qna

    10.51.10 • Public • Published

    Botpress Q&A ⚡

    Botpress Q&A is a Botpress module that adds the unified Q&A management interface to your bot admin panel.

    It either relies on the NLU module or on Microsoft QnA Maker for recognizing the questions. By default it also uses the builtins module to send the text response, but it's configurable (see below).

    Installation

    ⚠️ This module only works with the new Botpress X.

    • Install the peer dependencies and the module iteslf yarn add @botpress/builtins @botpress/nlu @botpress/qna (note: you can skip the builtins module if you use the custom text renderer.)
    • Configure NLU or register at Microsoft QnA Maker and provide the API key for it

    Configuration

    The following properties can be configured either in the qna.json file or using the environment variables:

    Key Environment Variable Required Default
    qnaDir QNA_DIR No ./qna The directory where the Q&A data is stored.
    textRenderer QNA_TEXT_RENDERER No #builtin_text (requires @botpress/builtins to be installed) The renderer used to format the text responses.
    exportCsvEncoding QNA_EXPORT_CSV_ENCODING No utf8 Encoding for CSV that can be exported from Q&A module
    qnaMakerApiKey QNA_MAKER_API_KEY No API-key for Microsoft QnA Maker. If provided QnA maker gets used to save items and search through them (instead of NLU-module)
    qnaMakerKnowledgebase QNA_MAKER_KNOWLEDGEBASE No botpress Name of the QnA Maker knowledgebase to use
    qnaCategories QNA_CATEGORIES No Comma-separated list of categories to use within QNA-module
    qnaShowTyping QNA_SHOW_TYPING No 0s The time of showing typing indicators

    Usage

    Go to the bot admin panel and choose Q&A from the left hand side menu.

    This opens Q&A module's page that allows you to manage questions. You can:

    • create new questions by filling in the form at the top
    • edit existing questions by changing appropriate fields of their forms
    • remove or disable questions by either clicking "Remove" button or changing "Enabled" checkbox
    • filter questions via search-input

    Each questions can be associated either with text-answer (by default it'll use #builtin_text renderer to send it) or with redirect to another flow node. You can specify behavior via "Reply with" radio-button.

    Qna-package adds middleware that listens to user's messages and if they match an intent of the question it either responds with an answer, or redirects to some flow-node.

    Programmatic usage

    botpress-qna exposes public API for importing/exporting questions: bp.qna.import and bp.qna.export. See examples below on how to use them.

    // Importing questions provided as an array of objects
    const questions = [
      { questions: ['Question1', 'Question2'], action: 'text', answer: 'Answer1' },
      { questions: ['Question3'], action: 'redirect', answer: 'main.flow.json#some-node' }
    ]
    await bp.qna.import(questions)
     
    // Importing questions from json-string
    const questionsJson = `[
      { "questions": [ "Question1", "Question2" ], "action": "text", "answer": "Answer1" },
      { "questions": [ "Question3" ], "action": "redirect", "answer": "main.flow.json#some-node" }
    ]`
    await bp.qna.import(questions, { format: 'json' })
     
    // Importing questions from csv-string
    // Note: consequtive questions with similar answer will be merged into one record with multiple questions
    const questionsCsv = 
    `"Question1","text","Answer1"
    "Question2","text","Answer1"
    "Question3","redirect","main.flow.json#some-node"`
    await bp.qna.import(questions, { format: 'csv' })
    const questionsExported = await bp.qna.export() // Should return structure similar to "questions" const in previous example
     
    const questionsFlatExported = await bp.qna.export({ flat: true })
    // Should return a flat structure with question-string in each record like this (might be useful for exporting to CSV):
    // 
    // [
    //   { question: 'Question1', action: 'text', answer: 'Answer1' },
    //   { question: 'Question2', action: 'text', answer: 'Answer1' },
    //   { question: 'Question3', action: 'redirect', answer: 'main.flow.json#some-node' }
    // ]
    const answers = await bp.qna.answersOn('How can I reach you out?')
    // [ { questions: [ 'How can I reach you out?' ],
    //     answer: 'You could find us on Facebook!',
    //     id: 116,
    //     confidence: 100,
    //     enabled: true,
    //     action: 'text' } ]

    Controlling if Q&A should intercept

    It may appear that it's not useful for Q&A to just intercept all the users' messages and try to match them against Q&A's intents. This can be customized by providing a hook to Q&A module that will prevent interception when returning false or a promise resolving to false.

    The hook is a function accepting event and state parameters:

    bp.qna.shouldProcessMessage((event, state) => Promise.resolve(false))
    bp.qna.shouldProcessMessage(async (event, state) => state.qnaEnabled) // It's also possible to use an async-function

    Contributing

    The best way to help right now is by helping with the exising issues here on GitHub and by reporting new issues!

    License

    Botpress is dual-licensed under AGPLv3 and the Botpress Proprietary License.

    By default, any bot created with Botpress is licensed under AGPLv3, but you may change to the Botpress License from within your bot's web interface in a few clicks.

    For more information about how the dual-license works and why it works that way please see the FAQS.

    Keywords

    none

    Install

    npm i @botpress/qna

    DownloadsWeekly Downloads

    43

    Version

    10.51.10

    License

    AGPL-3.0-only

    Unpacked Size

    1.29 MB

    Total Files

    11

    Last publish

    Collaborators

    • laurentlp
    • samuelmasse
    • slvnperron
    • spgingras
    • franklevasseur