Answer Bot API

Answer Bot API makes it possible for the system to read, infer meaning, and deliver precise answers from large sets of documents with high accuracy.

Uploading Q&A and Documents

Please sign up and sign in to the Alli dashboard first. You must select 'Cognitive Search' for the Project Type when you sign up. Go to the Q&A tab on the dashboard to upload question-answer pairs. If you want to upload unstructured text data such as Word, PDF, Powerpoint, and Excel file, go to the Documents tab in the dashboard and upload the documents.

If you want to automatically sync with your data source, such as MS OneDrive, please go to the Source tab. Uploading the document via API is in the Upload Document section in this page.

Getting the API KEY

Please provide your API key in the request header API-KEY. Your API key can be found in your dashboard Settings menu, under the General tab.

Providing Agent or User Information

For certain endpoints, you can add agent or user information in the request header to specify who makes the call.

Agent information can be provided in the request header AGENT-EMAIL. You can find your agents' email information in your dashboard Settings > Agent menu. Below is an example.

-H 'AGENT-EMAIL: agent_1@email.com'

A user ID can be provided in the request header OWN-USER-ID. The user ID can be either a new one or an existing one, and if a new user ID is provided, Alli will create a new user with that ID. Any future API calls with the same OWN-USER-ID header will be considered as they're from the same user.

If you want to update the user's email address at the same time, you can provide the email address in the request header USER-EMAIL. Below is an example.

-H 'OWN-USER-ID: 5f1234567a409876c082487z' \
-H 'USER-EMAIL: user_1@email.com'

You cannot use non-ASCII characters for OWN-USER-ID. If the user ID includes any non-ASCII characters, you can encode the ID to base64 and use base64:CONVERTED_ID.

You can find saved user ID and email information in your Alli dashboard Customers menu.

Error Messages

Please read the error message you get if you don't get the response that you expected. For example, if you don't use the right HTTP method for the API, you'll get this type of error as response:

{“error”: “Method Not Allowed POST: /webapi/faq_feedbacks”}

Search from Q&A

POST https://backend.alli.ai/webapi/faq

This API lets you find the most relevant question and answer pairs from your Q&A knowledge base.

Headers

NameTypeDescription

API-KEY*

string

Your API key can be found in your dashboard Settings menu, under the General tab.

AGENT-EMAIL

string

If you want to specify an agent who makes this API call, you can provide the agent's email address here. It can be found under Settings > Agents in your dashboard.

OWN-USER-ID

string

If you want to specify a user who makes this API call, you can provide the user's ID here. It can be a new one or be found in the Conversations menu in your dashboard.

USER-EMAIL

string

If you want to update the user's email when using OWN-USER-ID, you can provide the new email address here.

Request Body

NameTypeDescription

autoRegisterCandidates

boolean

The default value is true. When this option has set false, it'll not automatically register the query to candidates when there was no answer for the given query.

hashtagsOperator

string

Either AND or OR. Choose AND if you want each returned result to contain all hashtags. Choose OR if you want each returned result to contain at least one of the hashtags.

hashtags

array

An array of all the hashtags that you would like to appear.

maxResults

integer

The maximum number of results to be returned.

query*

string

This is a query string.

format

string

html or text. If it's text, the return value will be in plain text. If it's html, it will return html. If your answer contains styled html, such as different font size and color, you can use html. If you simply want to get an answer as a text, you can use the text. The default value is html.

The API will find the most relevant question and answers from your Q&A database.

confidence: It shows the confidence value from AI model. Shown as a number value between 0 and 1.

effectiveConfidence: When you provide feedback to the query result, it automatically trains the AI model. Effective confidence is the adjusted score with these users' and agents' feedback. Shown as a number value between 0 and 1.

question: This is the question part of the selected Q&A pair.

answer: This is the answer part of the selected Q&A pair.

id: This is used to identify the result to give or cancel feedback.

hashtags: Hashtags registered for the Q&A.

lastUpdatedDate: The date when the Q&A is last updated.

agentFeedback: The feedback from agents (through dashboard and REST calls) about this Q&A.

userFeedback: The feedback from users (through conversation) about this Q&A.

count: The number of suggested Q&As.

hashId: This hash id is being used when you call select_answer later.

The number of search results and the threshold follows your dashboard setting. Please check your settings in Q&A > Settings.

{"result": 
  [
    {
      "confidence": CONFIDENCE_VALUE, 
      "effectiveConfidence": EFFECTIVE_CONFIDENCE_VALUE, 
      "question": "QUESTION_1", 
      "answer": "ANSWER_1",
      "id": "ID_1",
      "hashtags": [],
      "lastUpdatedDate": "DATE",
      "agentFeedback": {
                "positiveCount": 1,
                "negativeCount": 0
              },
      "userFeedback": {
                "positiveCount": 1,
                "negativeCount": 0
              }
    }, ... 
  ],
  "count": 3,
  "hashId": "HASH_ID"
}

Request Example

Please replace YOUR_API_KEY with your one in the example below. Please see getting-api-key section.

curl -d '{ 
  "query": "How much is it?",
  "maxResults": 3, 
  "hashtags": ["wiki", "knowledge"], 
  "hashtagsOperator": "OR",
  "format": "text"}' \
-H 'API-KEY: YOUR API KEY' \
-H 'Content-Type: application/json' \
https://backend.alli.ai/webapi/faq

Response Example

{"result": 
  [
    {
      "confidence": 0.8371959004827834, 
      "effectiveConfidence": 0.9698303406362148, 
      "question": "How is the product priced?", 
      "answer": "We have a pricing table that includes a free plan.",
      "id": "ClMVIjCoNDAiZDLyNWZhM1O3YTUIIKZjPPRcER==",
      "hashtags": [],
      "lastUpdatedDate": "2020-11-19",
      "agentFeedback": {
                "positiveCount": 1,
                "negativeCount": 0
            },
      "userFeedback": {
                "positiveCount": 1,
                "negativeCount": 0
            }
    },
    {
      "confidence": 0.6119840535714456, 
      "effectiveConfidence": 0.7738889000171243, 
      "question": "Do you have a pricing table?", 
      "answer": "Yes we do. Please check out our website",
      "id": "RkFROjVmNDAwZDMyNWZhM2Y4YTA1ZDZjNWUwMQ==",
      "hashtags": [],
      "lastUpdatedDate": "2020-11-20",
      "agentFeedback": {
                "positiveCount": 1,
                "negativeCount": 0
            },
      "userFeedback": {
                "positiveCount": 1,
                "negativeCount": 0
            } 
  ],
  "count": 2,
  "hashId": "d4ca12d4e64766er0c2b45f4aa5463a4"
}

Search from Documents

POST https://backend.alli.ai/webapi/mrc

Documents API finds an answer from your unstructured text documents and even from complex tables.

Headers

NameTypeDescription

API-KEY*

string

Your API key can be found in your dashboard Settings menu, under the General tab.

AGENT-EMAIL

string

If you want to specify an agent who makes this API call, you can provide the agent's email address here. It can be found under Settings > Agents in your dashboard. The permission settings for the agent to access documents or folders are applied by sending this info.

OWN-USER-ID

string

If you want to specify a user who makes this API call, you can provide the user's ID here. It can be a new one or be found in the Conversations menu in your dashboard. The permission settings for non-agent users to access documents or folders are applied by sending this info.

USER-EMAIL

string

If you want to update the user's email when using OWN-USER-ID, you can provide the new email address here.

Request Body

NameTypeDescription

returnPreview

boolean

If true, the html body and css for the html type preview will be returned for each search result. The default value is false.

autoRegisterCandidates

boolean

The default value is true. When this option has set false, it'll not automatically register the query to candidates when there was no answer for the given query.

hashtagsOperator

string

Either AND or OR. Choose AND if you want each returned result's document to have all of the specified hashtags. Choose OR if you want each returned result's document to have at least one of the specified hashtag.

maxResults

integer

Number of results to see

query*

string

This is a query string.

hashtags

array

Documents you uploaded to the dashboard have hashtags. You can set the search scope to these hash-tagged documents.

format

string

It can be 'html' or 'text'. If it's text, the return value will be in plain text. If it's html, it will return html. If your answer contains styled html, such as different font size and color, you can use html. If you simply want to get an answer as a text, you can use the text.

returnPdfPreview

boolean

If true, the pdfPreview field will be returned for each search result. The default value is false.

returnPdfPreviewRawData

boolean

If true, the pdfPreviewRawData field will be returned for each search result. The default value is false.

sortKey

String

This is a secondary sort key where you set in Document's custom properties

sortDirection

String

This is a secondary sorting order. The value will be "asc" or "desc"

combinedHashtags

array

Documents you uploaded to the dashboard have hashtags. You can set the search scope to allow for groups of hashtags. Note: If "combinedHashtags" are used, you must keep the "hashtags" parameter empty.

combinedHashtagsOperator

string

Either AND or OR. Choose AND if you want both of the combined hashtags in the results.

Choose OR if you want at least one of the combined hashtags in the results.

You will get the result as the following JSON format:

answer: It's the answer extracted from uploaded documents in the dashboard.answerHash: This is used to identify the answer to give or cancel feedback.

answerHash: This is used to identify the answer to give or cancel feedback.

confidence: It shows the confidence value from AI model. Shown as a number value between 0 and 1.

effectiveConfidence: When you provide feedback to the query result, it automatically trains the AI model. Effective confidence is the adjusted score with these users' and agents' feedback. Shown as a number value between 0 and 1.

documentId: The document's ID where the answer is extracted from.

documentName: The document's name where the answer is extracted from.hashtags: The hashtags attached to the document.

pageNo: The page number in the document where the answer was derived.

createdDate: The date when the document was uploaded.

agentFeedback: The feedback from agents (through dashboard and REST calls) about this document

userFeedback: The feedback from users about this document

body: If returnPreview is true in the request, the html body of the document search preview is displayed.

css: If returnPreview is true in the request, the css of the document search preview is displayed.

pdfPreview: If returnPdfPreview is true in the request, the URL to a PDF preview of the document with the answer highlighted is displayed. Note that the URL can be restricted using the Download IP Allowlist setting.

folder: If the answer is found from a folder under the Documents database, the folder name will be returned here.

editor: List of the agents' email who has the editor access to the documents (if they're set in the Alli dashboard).

viewer: List of the agents' email who has the viewer access to the documents. (if they're set in the Alli dashboard).

The number of search results and the threshold follows your dashboard setting. Please check your setting in Documents > Settings.

{
    "result": [
        {
            "answer": "ANSWER_1",
            "answerHash": "ANSWER_HASH_1",
            "confidence": CONFIDENCE_1,
            "effectiveConfidence": EFFECTIVE_CONFIDENCE_1,
            "documentId": "DOCUMENT_ID_1",
            "documentName": "DOCUMENT_NAME_1",
            "hashtags": [],
            "pageNo": PAGE_NUMBER,
            "createdDate": "DATE",
            "agentFeedback": {
                "positiveCount": 0,
                "negativeCount": 0
            },
            "userFeedback": {
                "positiveCount": 0,
                "negativeCount": 0
            },
            "body": "PREVIEW_HTML_BODY",
            "css": "PREVIEW_CSS",
            "pdfPreview": "PDF_PREVIEW_URL",
            "folder": "folder 1", 
            "editor": ["email_1@allganize.ai", "email_2@allganize.ai"], 
            "viewer": ["email_3@allganize.ai"]
        }
    ]
}

Request Example (hashtags)

Please replace YOUR_API_KEY with your one in the example below. Please see getting-api-key section.

curl -X POST -d '{ 
  "query": "can I disclose the composite ratings?",
  "maxResults": 3, 
  "hashtags": ["wiki", "knowledge"], 
  "hashtagsOperator": "OR",
  "format": "text",
  "returnPdfPreview": true,
  "returnPdfPreviewRawData": true \
-H 'API-KEY: YOUR API KEY' \
-H 'Content-Type: application/json' \
https://backend.alli.ai/webapi/mrc

Request Example (combinedHashtags)

Please replace YOUR_API_KEY with your one in the example below. Please see getting-api-key section.

curl -X POST -d '{ 
  "query": "can I disclose the composite ratings?",
  "maxResults": 3, 
  "hashtags": [], 
  "hashtagsOperator": "OR",
  "combinedHashtags": [["wiki","knowledge"],["elibrary","compliance"]]
  "combinedHashtagsOperator": "AND",
  "format": "text",
  "returnPdfPreview": true,
  "returnPdfPreviewRawData": true }' \
-H 'API-KEY: YOUR API KEY' \
-H 'Content-Type: application/json' \
https://backend.alli.ai/webapi/mrc

Response Example

{
  "count": 2,
  "result": [
    {
      "answer": "an institution’s board of directors and senior management",
      "answerHash": "8430cf3b9af628abc1bb063802db39be",
      "confidence": 0.9998937845230103,
      "effectiveConfidence": 1,
      "documentId": "S25vd2xlZGdlQmFzZTo1ZjMzODFkZmNhYWJjYWUyMjkzYjFhY2U=",
      "documentName": "Policy document 1.docx",
      "hashtags": [
        "hashtag1",
        "hashtag2"
      ],
      "pageNo": 5,
      "createdDate": "2020-11-18",
      "agentFeedback": {
        "positiveCount": 1,
        "negativeCount": 0
      },
      "userFeedback": {
        "positiveCount": 0,
        "negativeCount": 0
      },
      "pdfPreviewRawData": {
        "pdfs": [
          {
            "pdfUrl": "PDF_ACTUAL_URL",
            "pageNo": 1,
            "highlight_indexes": [
                12
              ]
          },
          {
            "pdfUrl": "PDF_ACTUAL_URL",
            "pageNo": 2,
            "highlight_indexes": [
                12,
                13,
                14
              ]
          }
      ],
      "totalPageNo": 10
      },
      "pdfPreview" : "PDF_PREVIEW_URL"
      "folder": "folder 1", 
      "editor": ["email_1@allganize.ai", "email_2@allganize.ai"], 
      "viewer": ["email_3@allganize.ai"]
    },
    {
      "answer": "banks cannot, except in very limited circumstances",
      "answerHash": "d849a49662a4f21df51de24d06196547",
      "confidence": 0.9998629689216614,
      "effectiveConfidence": 0.9998629689216614,
      "documentId": "S25vd2xlZGdlQmFzZTo1ZjMzODFkZmNhYWJjYWUyMjkzYjFhY2U=",
      "documentName": "Bank policy 2020.pdf",
      "hashtags": [
        "hashtag1",
        "hashtag2"
      ],
      "pageNo": 220,
      "createdDate": "2020-11-18",
      "agentFeedback": {
        "positiveCount": 1,
        "negativeCount": 0
      },
      "userFeedback": {
        "positiveCount": 0,
        "negativeCount": 0
      },
      "pdfPreviewRawData": {
        "pdfs": [
          {
            "pdfUrl": "PDF_ACTUAL_URL",
            "pageNo": 1,
            "highlight_indexes": [
                12
              ]
          }
      ],
      "totalPageNo": 5
      },
      "pdfPreview" : "PDF_PREVIEW_URL"
    }
  ]
}

Get Single Q&A

GET https://backend.alli.ai/webapi/single_faq

This is the method to get all the details of a single Q&A.

Headers

NameTypeDescription

API-KEY*

string

Your API key can be found in your dashboard Settings menu, under the General tab.

Request Body

NameTypeDescription

id*

string

The id of the FAQ you are looking for.

format

string

The format of the answer value for this FAQ. Default is HTML.

{
    "result": {
        "question": "Who is there?",
        "answer": "Elmo",
        "id": "RkFROjYwMmY2ZTQ0YWZmMWQ5YmQ0NmM5Y2VkNw==",
        "userFeedback": {
            "positiveCount": 0,
            "negativeCount": 0
        },
        "agentFeedback": {
            "positiveCount": 0,
            "negativeCount": 1
        },
        "lastUpdatedDate": "2021-02-19",
        "createdDate": "2021-02-19",
        "hashtags": []
    }
}

Request Example

Please replace YOUR_API_KEY with your one in the example below. Please see getting-api-key section to get the api key.

curl -X GET \
-d '{"id": "iuHjHBhjHGbhjm==", "format": "text"}' \
-H "API-KEY: YOUR API KEY" \
https://backend.alli.ai/webapi/single_faq

Response Example

{
    "result": {
        "question": "Who is there?",
        "similarQuestion": ["Who's present?", "Who is it?"],
        "answer": "Elmo",
        "id": "RkFROjYwMmY2ZTQ0YWZmMWQ5YmQ0NmM5Y2VkNw==",
        "userFeedback": {
            "positiveCount": 0,
            "negativeCount": 0
        },
        "agentFeedback": {
            "positiveCount": 0,
            "negativeCount": 1
        },
        "lastUpdatedDate": "2021-02-19",
        "createdDate": "2021-02-19",
        "hashtags": []
    }
}

Get Single Document

GET https://backend.alli.ai/webapi/single_document

This is the method to get all details of a single document.

Headers

NameTypeDescription

API-KEY*

string

Your API key can be found in your dashboard Settings menu, under the General tab.

Request Body

NameTypeDescription

id*

string

The id of the document.

      "id": "S25vd2xlZGdlQmFzZTo1ZjMzODFkZmNhYWJjYWUyMjkzYjFhY2U=",
      "documentName": "Policy document 1.docx",
      "createdDate": "2020-11-12",
      "agentFeedback": {
                "positiveCount": 1,
                "negativeCount": 0
            },
            "userFeedback": {
            "positiveCount": 0,
            "negativeCount": 0
        },
      "hashtags" : ["hashtag1", "hashtag2"]
    }
}

Request Example

Please replace YOUR_API_KEY with your one in the example below. Please see getting-api-key section to get the api key.

curl -X GET \
-d '{"id": "S25vd2xlZGdlQmFzZTo1ZjMzODFkZmNhYWJjYWUyMjkzYjFhY2U="}' \
-H "API-KEY: YOUR API KEY" \
https://backend.alli.ai/webapi/single_document

Response Example

{"result": {
      "id": "S25vd2xlZGdlQmFzZTo1ZjMzODFkZmNhYWJjYWUyMjkzYjFhY2U=",
      "documentName": "Policy document 1.docx",
      "createdDate": "2020-11-12",
      "agentFeedback": {
                "positiveCount": 1,
                "negativeCount": 0
            },
      "userFeedback": {
            "positiveCount": 0,
            "negativeCount": 0
        },
      "hashtags" : ["hashtag1", "hashtag2"]
    }
}

Q&A Feedbacks

GET https://backend.alli.ai/webapi/faq_feedbacks

This API lets you get the list of feedbacks given to Q&A pairs for each search query.

Headers

NameTypeDescription

API-KEY*

string

Your API key can be found in your dashboard Settings menu, under the General tab.

AGENT-EMAIL

string

If you want to only see feedbacks given by a specific agent, you can provide the agent's email address here. It can be found under Settings > Agents in your dashboard.

OWN-USER-ID

string

If you want to only see feedbacks given by a specific user, you can provide the user's ID here. It can be found in the Conversations menu in your dashboard.

Request Body

NameTypeDescription

offset

integer

offset allows you to specify the ranking number of the first item on the page.

limit

integer

limit allows you to set the number of objects returned on one page. The maximum value is 100.

{
  "result": [
    {
      "query": "QUERY_1",
      "feedbacks": [
        {
          "faqId": "FAQ_ID_1_1", 
          "positive": true or false
        }, ...
      ]
    }, ...
  ],
  "count": COUNT_1
}

Request Example

Please replace YOUR_API_KEY with your one in the example below. Please see getting-api-key section to get the api key.

If you'd like to get a feedback list from a specific user, please put OWN-USER-ID in the header. If you'd like to get a feedback list from a specific agent, please put AGENT-EMAIL in the header. Without OWN-USER-ID or AGENT-EMAIL, all the feedbacks will be returned.

curl -X GET \
-d '{"offset": 0, "limit": 10}' \
-H "API-KEY: YOUR API KEY" \
https://backend.alli.ai/webapi/faq_feedbacks

Response Example

{
  "result": [
    {
      "query": "where is the office?",
      "feedbacks": [
        {
          "faqId": "RkFROjVmNDA1MWVkMTFmOWJjMTJjOGUwMTg5YQ==",
          "positive": true
        },
        {
          "faqId": "RkFROjVmNDA1MWVkMTFmOWJjMTJjOGUwMThhNA==",
          "positive": false
        },
        {
          "faqId": "RkFROjVmNDA1MWVjMTFmOWJjMTJjOGUwMTgyYw==",
          "positive": true
        }
      ]
    },
    {
      "query": "Are you funded?",
      "feedbacks": [
        {
          "faqId": "RkFROjVmNDA1MWVjMTFmOWJjMTJjOGUwMTgyNw==",
          "positive": true
        }
      ]
    }
  ],
  "count": 4
}

Q&A Feedback

POST https://backend.alli.ai/webapi/faq_feedback

This API lets you give or cancel feedback given to a Q&A pair for a search query.

Headers

NameTypeDescription

API-KEY*

string

Your API key can be found in your dashboard Settings menu, under the General tab.

AGENT-EMAIL

string

If you want to specify an agent who makes this API call, you can provide the agent's email address here. It can be found under Settings > Agents in your dashboard.

Request Body

NameTypeDescription

query*

string

The query you want to give or cancel feedback for, toward the Q&A.

id*

string

The ID for the Q&A you want to give or cancel feedback for the query. It is created whenever a Q&A search happens and bound to the query and the Q&A pair. It can be retrieved using the Q&A API above.

isPositive*

boolean

When the value is true, positive feedback is given to the Q&A for the query. When it's false, negative feedback is given. When it's null, it cancels the feedback.

{
    "result": {
        "faqTrainSearchResult": {
            "faq": {
                "id": "ID"
            },
            "agentFeedback": {
                "positiveCount": NUMBER,
                "negativeCount": NUMBER
            }
        }
    },
    "errors": null
}

Request Example

Please replace YOUR_API_KEY with your one in the example below. Please see getting-api-key section to get the api key.

Please replace Q&A_ID accordingly. About getting Q&A_ID, please take a look at Search from Q&A or Q&A Feedbacks section. It's id in Response Example of Search from Q&A section, or faq_id in Response Example of Q&A Feedbacks.

curl https://backend.alli.ai/webapi/faq_feedback \
-d '{"query": "What do I do if I didn't get a receipt?", 
     "id": "Q&A_ID", 
     "isPositive": true}' \
-H "API-KEY: YOUR API KEY" \
-H "Content-Type: application/json"

Response Example

{
    "result": {
        "faqTrainSearchResult": {
            "faq": {
                "id": "RkFROjVlOTc5MWExMjM5NjFiNzYzOTcxMWI1Mg=="
            },
            "agentFeedback": {
                "positiveCount": 1,
                "negativeCount": 0
            }
        }
    },
    "errors": null
}

Q&A User Feedback

POST https://backend.alli.ai/webapi/faq/user_feedback

The feedback registered with the above API will be submitted as user feedback. This API registers user feedback (user feedback is what the users who use the Alli chatbot and approve or disprove of answers submit).

Headers

NameTypeDescription

API-KEY*

string

Your API key can be found in your dashboard Settings menu, under the General tab.

OWN-USER-ID

string

If you want to specify a user who makes this API call, you can provide the user's ID here. It can be a new one or be found in the Conversations menu in your dashboard.

USER-EMAIL

string

If you want to update the user's email when using OWN-USER-ID, you can provide the new email address here.

Request Body

NameTypeDescription

prev

boolean

A boolean as to the previous feedback you'd assigned this query (only should be used to modify previous feedback)

positive*

boolean

A boolean as to whether the feedback is positive or negative

query*

string

The query that you made, that you're providing feedback for

id*

string

The ID of the Q&A object you want to provide feedback (can be found in the "faq" field of the /webapi/faq response).

analyticsHashtags

array

An array of all the hashtags that you would like to register as a scope, used in analytics by hashtag

{
    "result": {
        "userFeedback": {
            "positiveCount": 1,
            "negativeCount": 0
        }
    }
}

Request Example

curl https://backend.alli.ai/webapi/faq/user_feedback \
-H 'API-KEY: YOUR_API_KEY' \
-H "Content-Type: application/json" \
-d '{
    "query": "QUERY",
    "prev": PREVIOUSLY_ASSIGNED_FEEDBACK,
    "id": "FAQ_ID",
    "positive": true
}'

Response Example

{
    "result": {
        "userFeedback": {
            "positiveCount": 1,
            "negativeCount": 0
        }
    }
}

Upload Q&As

POST https://backend.alli.ai/webapi/upload_faq_file

You can upload multiple Q&As in the tsv, csv, xlsx, and zip format using this API.

Headers

NameTypeDescription

API-KEY*

string

Your API key can be found in your dashboard Settings menu, under the General tab.

AGENT-EMAIL

string

If you want to specify an agent who makes this API call, you can provide the agent's email address here. It can be found under Settings > Agents in your dashboard.

Request Body

NameTypeDescription

file*

string

Your local Q&A file location. xlsx, tsv, csv, and zip files are supported.

{
    "result": "success",
    "notUploaded": [
        {
            "question": "QUESTION_1",
            "state": "dup"
        },
        {
            "question": "QUESTION_2",
            "state": "up"
        }
    ]
}

Request Example

Please replace YOUR_API_KEY with your one in the example below. To get the api key, please see getting-api-key section.

curl -F 'file=@/location/to/your_file' \
-H 'API-KEY: YOUR_API_KEY'
https://backend.alli.ai/webapi/upload_faq_file

Response Example

{
    "result": "success",
    "notUploaded": [
        {
            "question": "How to teach AI",
            "state": "dup"
        },
        {
            "question": "I'd like to schedule a meeting or a demo.",
            "state": "up"
        }
    ]
}

Add Q&A

POST https://backend.alli.ai/webapi/register_faq

You can add a new Q&A or update an existing Q&A using this API.

Headers

NameTypeDescription

API-KEY*

string

Your API key can be found in your dashboard Settings menu, under the General tab.

AGENT-EMAIL

string

If you want to specify an agent who makes this API call, you can provide the agent's email address here. It can be found under Settings > Agents in your dashboard.

Request Body

NameTypeDescription

status

string

ON or OFF. When on, registered Q&A will be turned on for Q&A search.

question*

string

The question part of the Q&A.

similarQuestions

array

Similar questions that has the same answer. You can add multiple similar questions.

answer*

string

The answer part of the Q&A. If the same question exists in the database, this answer will replace the existing one.

hashtags

array

Hashtags added to the Q&A. You can add multiple hashtags.

memo

string

Memo on the Q&A to share with agents.

followFolderPermission

boolean

When uploading, if there is a folder to which it belongs, the permission of the folder is inherited or not inherited. (Default value: True) If not inherited, the permissions specified below are used. Unless otherwise specified, all agents and users have the privilege.

agentEditor

array

Register an agent with permission to edit the file

agentViewer

array

Register an agent with permission to view the file

userViewer

object

Register a user with permission to view the file. You can register using customer_id, customer_group. customer_id is the same as own-user-id, and customer_group's id (categoryElementsId) can be obtained through the CUSTOMER GROUP inquiry API.

allowOtherAgentsView

boolean

Agents who are not in the editor/viewer list can also view

allowOtherUsersView

boolean

Users who are not in the editor/viewer list can also view

{
    "result": {
        "status": "created",
        "id": "Q&A_ID"
    },
    "errors": null
}

Request Example

Please replace YOUR_API_KEY with your one in the example below. To get the api key, please see getting-api-key section.

curl 'https://backend.alli.ai/webapi/register_faq' \
-H 'API-KEY: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
    "status": "ON",
    "question": "Where is the office?",
    "similarQuestions": ["Office location?", "Office address?"],
    "answer": "We have offices in Oakland(US), Seoul(Korea), and Tokyo(Japan)",
    "hashtags": ["office", "location"],
    "memo": "Added from API",
    "folder": "folder 1", 
    "agentEditor": ["your@email.com"], 
    "agentViewer": ["your@email_2.com"],
    "userViewer": {
    "variables": {
      "CUSTOMER_ID": ["id_1", "id_2"],
      "CUSTOMER_GROUP": ["{categoryElementId}", "{categoryElementId}"]
        }
    },
    "followFolderPermission": false,
    "allowOtherAgentsView": true,
    "allowOtherUsersView": true
}'

Response Example

{
    "result": {
        "status": "created",
        "id": "RkFROkYwYRQxYzIzMDcxYWM5M3JlOWR5Y2EeOQ=="
    },
    "errors": null
}

Delete Q&A

POST https://backend.alli.ai/webapi/delete_faq

You can delete a Q&A using this API.

Headers

NameTypeDescription

API-KEY*

string

Your API key can be found in your dashboard Settings menu, under the General tab.

Request Body

NameTypeDescription

id*

string

The ID of the Q&A you want to delete.

{
    "result": {
        "status": "deleted"
    },
    "errors": null
}

Request Example

Please replace YOUR_API_KEY with your one in the example below. To get the api key, please see getting-api-key section.

curl 'https://backend.alli.ai/webapi/delete_faq' \
-H 'API-KEY: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d {
    "id": "RkFROkYwYRQxYzIzMDcxYWM5M3JlOWR5Y2EeOQ=="
    }

Response Example

{
    "result": {
        "status": "deleted"
    },
    "errors": null
}

List Q&As

GET https://backend.alli.ai/webapi/faqs

You can list Q&As in the Knowledge Base using this API.

Headers

NameTypeDescription

API-KEY*

string

Your API key can be found in your dashboard Settings menu, under the General tab.

Request Body

NameTypeDescription

searchTerm

string

Keyword search query to filter the list. You can use operators to run advanced searches. "TERM1 TERM2" for AND, "TERM1 OR TERM2" for OR, and "\"TERM\"" for exact match.

isUsed

boolean

If true, only turned-on Q&As will be listed, If false, only turned-off Q&As will.

hashtags

array

Hashtags to filter the list. You can add multiple hashtags.

hashtagsOperator

string

and or or. If it's and, hashtags filter for multiple hashtags works with AND logic. If or, OR logic.

createdByAgent

boolean

If true, the list will only include Q&As created by agents. If false, only the other Q&As will be included. Please note that createdByAgent, answeredByMrc, autoGenerated, editedByAgent filters are mutually exclusive, and OR logic is applied if two or more of them are used.

answeredByMrc

boolean

If true, the list will only include Q&As that are the answers are automatically extracted from uploaded Documents. If false, only the other Q&As will be included.

autoGenerated

boolean

If true, the list will only include auto-generated Q&As. If false, only the other Q&As will be included.

editedByAgent

boolean

If true, the list will only include Q&A's edited by any agent after registered. If false, only the other Q&As will be included.

format

string

html or text. If your answers contain styled html, such as different font size or color, you can use html to get answers in html format. If you simply want to get answers as a text, you can use the text. The default value is html.

offset

integer

offset allows you to specify the ranking number of the first item on the page.

limit

integer

limit allows you to set the number of objects returned on one page. The maximum and the default value is 1000.

offset: The same offset value with the offset request parameter.

count: Total number of Q&As listed after limit is applied.

totalCount: Total number of Q&As as the result of applied filters.

id: The ID of the Q&A.

question: The question part of the Q&A.

answer: The answer part of the Q&A.

hashtags: The hashtags added on the Q&A.

userFeedback: Number of positive and negative user feedbacks. User feedbacks affects the search result for future queries.

agentFeedback: Number of positive and negative agent feedbacks. Agent feedbacks affects the search result for future queries.

lastUpdatedDate: The date when the Q&A is last updated.

createdDate: The date when the Q&A is created.

{
    "offset": 0,
    "count": 10,
    "totalCount": 12,
    "results": [
        {
            "id": "Q&A_ID_1",
            "question": "QUESTION_1",
            "answer": "ANSWER_1",
            "hashtags": [
                "HASHTAG_1",
                "HASHTAG_2"
            ],
            "userFeedback": {
                "positiveCount": 0,
                "negativeCount": 0
            },
            "agentFeedback": {
                "positiveCount": 0,
                "negativeCount": 0
            },
            "lastUpdatedDate": "2021-05-04",
            "createdDate": "2021-02-23"
        },
        {
            "id": "Q&A_ID_2",
            "question": "QUESTION_2",
            "answer": "ANSWER_2",
            "hashtags": [
                "HASHTAG_1",
                "HASHTAG_3"
            ],
            "userFeedback": {
                "positiveCount": 0,
                "negativeCount": 0
            },
            "agentFeedback": {
                "positiveCount": 0,
                "negativeCount": 0
            },
            "lastUpdatedDate": "2021-05-04",
            "createdDate": "2021-02-23"
        }, ...
    ]
}

Request Example

Please replace YOUR_API_KEY with your one in the example below. To get the api key, please see getting-api-key section.

curl -X GET 'https://backend.alli.ai/webapi/faqs' \
-H 'API-KEY: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
    "searchTerm": "Allganize",
    "isUsed": true,
    "hashtags": ["company", "Alli"],
    "hashtagsOperator": "OR",
    "createdByAgent": true,
    "answeredByMrc": true,
    "autoGenerated": false,
    "editedByAgent": false,
    "format": "text",
    "offset": 0,
    "limit": 10
}'

Response Example

{
    "offset": 0,
    "count": 2,
    "totalCount": 2,
    "results": [
        {
            "id": "RkRODjYwUIr2YTUzYTc0MjNmMDgxOTFkZTRlNA==",
            "question": "How many people work at Allganize?",
            "answer": "Currently (Nov 2019), we have 16 employees working at three different locations.",
            "hashtags": [
                "company",
                "actual"
            ],
            "userFeedback": {
                "positiveCount": 0,
                "negativeCount": 0
            },
            "agentFeedback": {
                "positiveCount": 0,
                "negativeCount": 0
            },
            "lastUpdatedDate": "2021-05-04",
            "createdDate": "2021-02-23"
        },
        {
            "id": "RkFROjYwIdU4YTUzYTc0MjNmUR2wOTFkZTU1OA==",
            "question": "Do you have any references or case studies?",
            "answer": "We do! Check out our recent case studies and other articles on our blog: https://blog.allganize.ai/",
            "hashtags": [
                "company",
                "actual"
            ],
            "userFeedback": {
                "positiveCount": 0,
                "negativeCount": 0
            },
            "agentFeedback": {
                "positiveCount": 0,
                "negativeCount": 0
            },
            "lastUpdatedDate": "2021-05-04",
            "createdDate": "2021-02-23"
        }
    ]
}

Q&A Candidates

GET https://backend.alli.ai/webapi/faq_candidates

Using this API, you can get the list of unanswered questions from customers. They're called Candidates.

Headers

NameTypeDescription

API-KEY*

string

Your API key can be found in your dashboard Settings menu, under the General tab.

Request Body

NameTypeDescription

hashtags

array

Hashtag array if you want to limit the search scope to the given hashtags

searchTerm

string

Search query to filter the candidates to see. You can use operators to run advanced searches. "TERM1 TERM2" for AND, "TERM1 OR TERM2" for OR, and "\"TERM\"" for exact match.

order

string

How to order the candidates. You can use ATTRIBUTE_[DESC or ASC] format. ATTRIBUTE can be FREQUENCY or CREATED_AT.

state

string

Status of the candidates to see. It can be ALL or ACTIVE or ARCHIVED.

offset

integer

offset allows you to specify the ranking number of the first item on the page.

limit

integer

limit allows you to set the number of objects returned on one page. The maximum value is 100.

sources

array

Source array if you want to limit the search scope to the given sources. You can use SDK, QNA, DOCUMENTS and API as source.

You will get the result as the following JSON format.

count: The total number of candidates.

id: The ID of the extracted answer to the unanswered question. Whenever there is a new unanswered question registered, Alli tries to extract and add an answer from uploaded documents automatically.

frequency: Sum of all the frequency numbers under the questions.

textAnswer: The answer extracted from the uploaded documents for the question.

state: The status of the candidate. ACTIVE if the candidate is not added to the Q&A database yet. ARCHIVED if the candidate is added to the Q&A database.

createdAt: The timestamp of when the candidate was created.

questions: Multiple similar questions can have the same answer. Information about all the questions for the answer is under here.

id (under questions): The ID of the unanswered question from customers.

question (under questions): The unanswered question from customers.

frequency (under questions): How many times the question was asked by customers.

id (under history): The ID of the history information of the unanswered question. The history is the customers' log when the question was asked.

{
	"result": {
		"faqCandidates": [
		  {
				"id": "ID_ANSWER_1",
				"frequency": 1,
				"textAnswer": "ANSWER_1",
				"state": "ACTIVE",
				"createdAt": NUMBER,
				"questions": [{
					"id": "ID_QUESTION_1",
					"question": "QUESTION_1",
					"frequency": 1,
					"history": {
						"id": "ID_HISTORY_1"
					}
				}]
			},
		],
		"count": 1
	},
	"errors": null
}

Request Example

Please replace YOUR_API_KEY with your one in the example below. To get the api key, please see getting-api-key section.

curl -X GET \
-d '{ "hashtags": ["wiki"], 
    "searchTerm": "user", 
    "order": "FREQUENCY_DESC", 
    "state": "ALL", 
    "offset": 0, 
    "limit": 10}' \
-H "API-KEY: YOUR API KEY" \
https://backend.alli.ai/webapi/faq_candidates

Response Example

{
	"result": {
		"faqCandidates": [
		  {
				"id": "RkFRQ2FuZGlkYXRlOjVlYjA3OGU5MGFmZmMyM2QxZjc4ZTMzMQ==",
				"frequency": 1,
				"textAnswer": "This is how to use it, A from Z.\n— From User Guide.pdf",
				"state": "ACTIVE",
				"createdAt": 1588623593321,
				"questions": [{
					"id": "RkFRQ2FuZGlkYXRlUXVlc3Rpb246NWViMDc4ZTkwYWZmYzIzZDFmNzhlMzMw",
					"question": "User manual?",
					"frequency": 1,
					"history": {
						"id": "Q29udmVyc2F0aW9uOjVlYjA3OGI2NWUyMTJlMTMzZDM4NDAzOA=="
					}
				}]
			},
			{
				"id": "RkFRQ2FuZGlkYXRlOjVlOWEzZWI2MmZlOTFkMzIwYjE2YWQyOQ==",
				"frequency": 1,
				"textAnswer": "You can cancel the policy in 15 days\n— From UserPolicy.pdf",
				"state": "ACTIVE",
				"createdAt": 1587166902114,
				"questions": [{
					"id": "RkFRQ2FuZGlkYXRlUXVlc3Rpb246NWU5YTNlYjYyZmU5MWQzMjBiMTZhZDI4",
					"question": "Can I cancel?",
					"frequency": 1,
					"history": {
						"id": "Q29udmVyc2F0aW9uOjVlOWEzZDliNjU5YmM2NTEyMTk5MDQ3Ng=="
					}
				}]
			}
		],
		"count": 1
	},
	"errors": null
}

Q&A Candidates

POST https://backend.alli.ai/webapi/add_faq_candidates

Registers a new Q&A Candidate with the system.

Headers

NameTypeDescription

API-KEY*

string

Your API key can be found in your dashboard Settings menu, under the General tab.

AGENT-EMAIL

string

If you want to specify an agent who makes this API call, you can provide the agent's email address here. It can be found under Settings > Agents in your dashboard.

OWN-USER-ID

string

If you want to specify a user who makes this API call, you can provide the user's ID here. It can be a new one or be found in the Conversations menu in your dashboard.

USER-EMAIL

string

If you want to update the user's email when using OWN-USER-ID, you can provide the new email address here.

Request Body

NameTypeDescription

queries*

string

The list of all queries you would like to register

analyticsHashtags

array

An array of all the hashtags that you would like to register as a scope, used in analytics by hashtag. Please note that these hashtags will not be registered as candidates' hashtags.

{
    "result": {
        "candidates": [
            {
                "id": "CANDIDATE_ID_1"
            },
            {
                "id": "CANDIDATE_ID_2"
            }
        ]
    },
    "errors": null
}

Request Example

Please replace YOUR_API_KEY with your one in the example below. To get the api key, please see getting-api-key section.

curl https://backend.alli.ai/webapi/add_faq_candidates \
-d '{"queries": ["what is that processor", "how much does the processor cost"]}' \
-H "Content-Type: application/json" \
-H "API-KEY: YOUR_API_KEY"

Response Example

{
    "result": {
        "candidates": [
            {
                "id": "RkFRQ2FuZGlkYXRlOjVmOGE1ZDA0ODgxNzc0OWNjMWUwMzRiNg=="
            },
            {
                "id": "iGBiuGIGIugBIGBIugBIuBGiHBiJUhbhIBgIbKHJBJCYUBLHKGJfBJbIb=="
            }
        ]
    },
    "errors": null
}

Documents Feedbacks

GET https://backend.alli.ai/webapi/mrc_feedbacks

This API lets you get the list of feedbacks given to Document search results (AI-extracted answers from uploaded documents) for each search query.

Headers

NameTypeDescription

API-KEY*

string

Your API key can be found in your dashboard Settings menu, under the General tab.

AGENT-EMAIL

string

If you want to only see feedbacks given by a specific agent, you can provide the agent's email address here. It can be found under Settings > Agents in your dashboard.

OWN-USER-ID

string

If you want to only see feedbacks given by a specific user, you can provide the user's ID here. It can be found in the Conversations menu in your dashboard.

Request Body

NameTypeDescription

offset

integer

offset allows you to specify the ranking number of the first item on the page.

limit

integer

limit allows you to set the number of objects returned on one page. The maximum value is 100.

{
  "result": [
    {
      "query": "QUERY_1",
      "feedbacks": [
        {
          "documentId": "DOCUMENT_ID_1",
          "answer": "ANSWER_1",
          "answerHash": "ANSWER_HASH_1",
          "positive": true or false
        }, ...
      ]
    }
  ],
  "count": NUMBER
}

Request Example

Please replace YOUR_API_KEY with your one in the example below. To get the api key, please see getting-api-key section.

If you'd like to get a feedback list from a specific user, please put OWN-USER-ID in the header. If you'd like to get a feedback list from a specific agent, please put AGENT-EMAIL in the header.

curl -X GET \
-d '{"offset": 0, "limit": 10}' \
-H "API-KEY: YOUR API KEY" \
https://backend.alli.ai/webapi/mrc_feedbacks

Response Example

{
  "result": [
    {
      "query": "cancel the policy",
      "feedbacks": [
        {
          "documentId": "S25vd2xlZGdlQmFzZTo1ZWM1YmJiZTczNmUxNmM0NDRjZDI2ZGM=",
          "answer": "You can cancel the policy in 30 days.",
          "answerHash": "44094c4a281484daadf28e67a4745747",
          "positive": true
        },
        {
          "documentId": "S25vd2xlZGdlQmFzZTo1ZWM1YmJiZTczNmUxNmM0NDRjZDI2ZGM=",
          "answer": "This is how you enroll the policy.",
          "answerHash": "296ffa9691166c583b00365fb6839a06",
          "positive": false
        },
        {
          "documentId": "S25vd2xlZGdlQmFzZTo1ZWM1YmJiZTczNmUxNmM0NDRjZDI2ZGM=",
          "answer": "You cannot get refunded upon cancelation after 30 days.",
          "answerHash": "48e5273910c913dbf0fc08482f7cd22c",
          "positive": true
        }
      ]
    }
  ],
  "count": 3
}

Documents Search Feedback

POST https://backend.alli.ai/webapi/mrc_feedback

This API lets you give or cancel feedback given to a Document search result for a search query.

Headers

NameTypeDescription

API-KEY*

string

Your API key can be found in your dashboard Settings menu, under the General tab.

AGENT-EMAIL

string

If you want to specify an agent who makes this API call, you can provide the agent's email address here. It can be found under Settings > Agents in your dashboard.

Request Body

NameTypeDescription

query*

string

The query you want to give or cancel feedback for, toward the extracted search result.

id*

string

The ID for the document where the answer was extracted from.

answerHash*

string

The ID of the Document search result you want to give or cancel feedback for the query. It is created whenever a Documents search happens and bound to the query and the answer pair. It can be retrieved using the Documents API above.

isPositive*

boolean

When the value is true, positive feedback is given to the extracted answer for the query. When it's false, negative feedback is given. When it's null, it cancels the feedback.

{
    "result": {
        "mrcFeedbackSearchResult": {
            "agentFeedback": {
                "positiveCount": NUMBER,
                "negativeCount": NUMBER
            }
        }
    },
    "errors": null
}

Request Example

Please replace YOUR_API_KEY with your one in the example below. To get the api key, please see getting-api-key section. Please replace DOCUMENT_ID and ANSWER_HASH accordingly. About getting document id and answer hash, please take a look at Search from Documents or Documents Feedbacks section.

curl https://backend.alli.ai/webapi/mrc_feedback \
-d '{"query": "what is that processor", 
     "id": "DOCUMENT_ID", 
     "answerHash": "ANSWER_HASH", 
     "isPositive": false}' \
-H "Content-Type: application/json" \
-H "API-KEY: YOUR_API_KEY"

Response Example

{
    "result": {
        "mrcFeedbackSearchResult": {
            "agentFeedback": {
                "positiveCount": 0,
                "negativeCount": 1
            }
        }
    },
    "errors": null
}

Documents Search User Feedback

POST https://backend.alli.ai/webapi/mrc/user_feedback

Provide user feedback to the Documents search result.

Headers

NameTypeDescription

API-KEY*

string

Your API key can be found in your dashboard Settings menu, under the General tab.

OWN-USER-ID

string

If you want to specify a user who makes this API call, you can provide the user's ID here. It can be a new one or be found in the Conversations menu in your dashboard.

USER-EMAIL

string

If you want to update the user's email when using OWN-USER-ID, you can provide the new email address here.

Request Body

NameTypeDescription

answerHash*

string

The ID of the Document search result you want to give or cancel feedback for the query. It is created whenever a Documents search happens and bound to the query and the answer pair. It can be retrieved using the Documents API above.

id*

string

The ID for the document where the answer was extracted from.

positive*

boolean

When the value is true, positive feedback is given to the extracted answer for the query. When it's false, negative feedback is given. When it's null, it cancels the feedback.

query*

string

The query you want to give or cancel feedback for, toward the extracted search result.

analyticsHashtags

array

An array of all the hashtags that you would like to register as a scope, used in analytics by hashtag

{
    "result": {
        "userFeedback": {
            "positiveCount": 1,
            "negativeCount": 0
        }
    }
}

Request Example

curl -request POST 'https://backend.alli.ai/webapi/mrc/user_feedback' \
--header 'API-KEY: YOUR_API_KEY' \
-d '{
    "query": "QUERY",
    "answerHash": "RESULT_ID",
    "id": "DOCUMENT_ID",
    "positive": true
}'

Response Example

{
    "result": {
        "userFeedback": {
            "positiveCount": 1,
            "negativeCount": 0
        }
    }
}

Document Upload APIs

POST https://backend.alli.ai/webapi/upload_file

This API allows you to upload documents from your local storage for use in Cognitive Search. Upload PDF, TXT, MS Word, PowerPoint, Excel, HTM, and HTML files. To upload an HTML file with a linked resource, and upload the included ZIP file.

Headers

NameTypeDescription

API-KEY*