Cognitive Search API

Cognitive Search APIは、ユーザーの自由入力による問い合わせや質問に対して、機械読解(MRC)APIで該当のドキュメントから直接回答を探し出してユーザーに提示します。

Q&Aとドキュメントのアップロード

まず、Alliに利用登録をしてサインインしてください。登録時、プロジェクトタイプから必ず「Cognitive Search」を選択してください。Q&Aメニューでは質問/回答ペアを登録することができます。ワード、PDF、パワーポイント、エクセルなどドキュメントファイルは、ドキュメントメニューで登録することができます。

ドキュメントデータベースをMicrosoft OneDriveなどのデータソースと連携することもできます。ソース設定メニューで設定してください。

API経由でのドキュメントファイルアップロードについては、本ページのDocument Uploadセクションをご参照ください。

APIキーの取得

RequestヘッダーのAPI-KEYには、割り当てられたAPIキーを入力してください。APIキーはプロジェクト設定メニューからご確認いただけます。

エンドポイントに関して

このAPIリファレンスではエンドポイントを下記として記載しております。 https://backend-ja.alli.ai ただし、ご利用されているAlliの環境によっては下記の場合もございます。https://backend.alli.ai どちらのエンドポイントかはプロジェクト設定メニューからご確認ください。

エージェントまたはユーザー情報をAPI利用時に用いる

特定のエンドポイントでは、リクエストヘッダーにエージェントやユーザーの情報を追加して、APIを利用することで、誰がAPIを利用したかを特定することができます。

エージェント情報 エージェント情報の場合は、リクエストヘッダーのAGENT-EMAILを用います。 エージェントのメール情報は、ダッシュボードの[設定] > [エージェント メニュー]で確認できます。以下に例を示します。

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

ユーザー情報 ユーザー情報の場合はリクエスト ヘッダーにOWN-USER-ID を用います。ユーザー ID は新しいものでも既存のものでもかまいません。新しいユーザー ID が提供された場合、Alli はその ID で新しいユーザーを作成します。同じOWN-USER-IDのヘッダーを持つAPI 呼び出しについては、同じユーザーからの呼び出しと見なされます。

同時にユーザーのメール アドレスを更新する場合は、USER-EMAILのリクエスト ヘッダーでメール アドレスを指定できます。以下に例を示します。

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

OWN-USER-IDには非 ASCII 文字を使用できません。ユーザー IDに非ASCII文字が含まれている場合は、IDをbase64 にエンコードして base64:CONVERTED_IDとして追加することで非ASCII文字をOWN-USER-IDに入力することができます。

保存されたユーザー ID とメール情報は、Alli ダッシュボードの [顧客] メニューでことができます。

エラーメッセージ

予想されるresponseがない場合は、エラーメッセージを確認してください。例えば、間違ったHTTPメソッドを使用した場合、以下のような形式のエラーメッセージが戻ります。

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

Search from Q&A

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

Search from Q&A APIは、Q&Aのデータベースから質問と最も関連のあるQ&Aペアを検索して提示します。

Headers

NameTypeDescription

API-KEY*

string

割り当てられたAPIキーです。プロジェクト設定メニュ→全般タブから確認できます。

AGENT-EMAIL

string

エージェントのメール アドレスを指定することで、この API 呼び出しを行うエージェントを特定できます。ここで指定するEメールアドレスは、ダッシュボードの [設定] > [エージェント] にて確認してください。

OWN-USER-ID

string

ユーザーの ID を指定することで、この API 呼び出しを行うユーザーを特定できます。ここで指定するIDは、ダッシュボードの [顧客リスト]>[CUSTOMER_ID] もしくは[会話履歴]>[対話情報]にて確認できます。

USER-EMAIL

string

OWN-USER-ID を指定する際にユーザーのEメールアドレスを更新する場合は、ここで新しいEメールアドレスを指定できます。

Request Body

NameTypeDescription

autoRegisterCandidates

boolean

デフォルトはtrueです。これをfalseにしますと、答えがない場合に自動でCandidatesに登録しない様になります。

hashtagsOperator

string

ANDまたはORのいずれかとなります。 結果にすべてのハッシュタグを含める場合は、ANDを選択します。 結果に少なくとも1つのハッシュタグを含める場合は、ORを選択します。

hashtags

array

検索対象に含めるハッシュタグの配列

maxResults

integer

レスポンスとして表示される結果の最大数です。

query*

string

文字列形式の検索クエリです。

format

string

html あるいは text です。textの場合、戻り値はplain textです。htmlの場合はhtmlで戻ります。回答にStyled htmlが含まれている場合(フォントの大きさや色など)、htmlをご使用ください。シンプルテキストの回答が必要な場合はtextを使用してください。デフォルトはhtmlとなっています。

APIは、Q&Aデータベースから最も関連性の高い質問と回答を見つけます。

confidence: AIモデルが算出したconfidence値を提示します。0と1の間の数字です。

effective confidence: クエリの結果にフィードバックが送られるとAIモデルのトレーニングに反映されますが、ユーザーとエージェントのフィードバック結果を反映したconfidence値がeffective confidenceです。0と1の間の数字です。

question: 提示された質問/回答のペアにおいて質問の部分です。

answer: 提示された質問/回答のペアにおいて回答の部分です。

id: フィードバックを入力したり、取り消すQ&Aの検索結果を特定するために使われます。

hashtags: Q&Aに登録されているハッシュタグです。

lastUpdatedDate: Q&Aが最後に更新された日時です。

agentFeedback: Q&Aに対するエージェントからのフィードバック(ダッシュボードとREST APIを介して)です。

userFeedback : Q&Aに関するユーザーからの(ユーザーとの会話からの)フィードバックです。

count: 提案されたQ&Aの数です。

hashId :このハッシュIDは、Select Answer APIを利用するときに使用されます。検索結果の表示件数は、プロジェクトの設定に従います。Q&A>設定メニューから変更することができます。

{"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

YOUR API KEYをプロジェクトのAPIキーに変更しなければなりません。APIキーの取得の項目をご参照ください。

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-ja.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":"6ca7524a641bc8a23f065e23b46be256"
}

Search from Documents

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

​Documents APIは、複雑なテーブルなどが含まれたドキュメントからもユーザーの質問に対する回答を抽出することができます。

Headers

NameTypeDescription

API-KEY*

string

割り当てられたAPIキーです。プロジェクト設定メニュ→全般タブから確認できます。

AGENT-EMAIL

string

エージェントのEメールアドレスを指定することで、このAPI呼び出しを行うエージェントを特定できます。ここで指定するEメールアドレスは、ダッシュボードの [設定] > [エージェント] にて確認してください。

OWN-USER-ID

string

ユーザーのIDを指定することで、このAPI呼び出しを行うユーザーを特定できます。ここで指定するIDは、ダッシュボードの [顧客リスト]>[CUSTOMER_ID] もしくは[会話履歴]>[対話情報]にて確認できます。

USER-EMAIL

string

OWN-USER-IDを設定する際にユーザーのEメールアドレスを更新する場合は、ここで指定できます。

Request Body

NameTypeDescription

returnPreview

boolean

デフォルトはfalseです。trueの場合、検索ごとにプレビューのhtmlとcssを返します。

autoRegisterCandidates

boolean

デフォルトはtrueです。これをfalseにすると、回答がない場合に自動でCandidatesに登録しないようになります。

hashtagsOperator

string

ANDまたはORのいずれかとなります。 結果にすべてのハッシュタグを含める場合は、ANDを選択してください。 結果に少なくとも1つのハッシュタグを含める場合は、ORを選択してください。

maxResults

integer

レスポンスとして表示される結果の最大数です。

query*

string

文字列形式の検索クエリです。

hashtags

array

ダッシュボードに登録したドキュメントにハッシュタグを追加することができます。ハッシュタグを活用し、当該タグが付けられたドキュメントに限定して検索することができます。

format

string

html あるいは text です。textの場合、戻り値はplain textです。htmlの場合はhtmlで戻ります。回答にstyled htmlが含まれている場合(フォントの大きさや色など)、htmlをご使用ください。シンプルテキストの回答が必要な場合はtextを使用してください。デフォルトはhtmlとなっています。

returnPdfPreview

boolean

デフォルトはfalseです。trueの場合、検索ごとにpdfPreviewのURLが発行されます。

returnPdfPreviewRawData

boolean

デフォルトはfalseです。trueの場合、検索ごとにpdfPreviewRawDataのURLが発行されます。

sortkey

String

ドキュメントのカスタムプロパティで設定するセカンダリソートキーです。

sortDirection

String

セカンダリソートの種類です。値は「asc」または「desc」になります。

検索結果は、以下のようなJSON形式で戻ります。

answer: プロジェクトにアップロードしたドキュメントから抽出された回答です。

answerHash: フィードバックを入力したり、取り消すドキュメントの検索結果を特定するために使われます。

confidence: AIモデルが算出したconfidenceの値を表示します。0と1の間の数字です。 effectiveConfidence: クエリの結果にフィードバックが送られるとAIモデルのトレーニングに反映されますが、ユーザーとエージェントのフィードバック結果を反映したconfidence値がeffective confidenceです。0と1の間の数字です。

documentId: 回答が抽出されたドキュメントのIDです。

documentName: 回答が抽出されたドキュメントの名前です。

hashtags: ドキュメントに登録されているハッシュタグです。

pageNo: 回答が得られたドキュメントのページ番号(プレビュー時ページ番号)です。createdDate: ドキュメントがアップデートされた日時です。

agentFeedback: ドキュメントに対するエージェントからのフィードバック(ダッシュボードとREST APIを介して)です。

userFeedback:ドキュメントに関するユーザーからのフィードバックとなります。検索結果の数と閾値は、ダッシュボードの設定に従います。[ナレッジベース]>[ドキュメント]> [設定]で設定を確認してください。

body:リクエストパラメーターのreturnPreviewがtrueの場合、ドキュメント検索プレビューのhtml本文が表示されます。

css:リクエストパラメーターでreturnPreviewがtrueの場合、ドキュメント検索プレビューのcssが表示されます。

pdfPreview:リクエストでreturnPdfPreviewがtrueの場合、回答が強調表示されたドキュメントのPDFプレビューへのURLが表示されます。 [IP許可リストのダウンロード]設定を使用してURLを制限できることに注意してください。 検索結果の数としきい値は、ダッシュボードの設定に従います。 [ドキュメント]> [設定]で設定を確認してください。

folder:もし回答がDocumentsデータベース内のフォルダから見つかった場合、ここにはフォルダ名が返されます。

editer:ドキュメントへの編集アクセス権を持つエージェントのメールアドレスの一覧が返されます。(Alliのダッシュボードで設定されている場合)

viewer:ドキュメントへの閲覧アクセス権を持つエージェントのメールアドレスの一覧が返されます。(Alliのダッシュボードで設定されている場合)  検索結果の数と閾値は、ダッシュボードの設定に従います。ドキュメント > 設定で設定を確認してください。

 {
    "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

YOUR API KEYをプロジェクトのAPIキーに変更しなければなりません。APIキーの取得の項目をご参照ください。

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-ja.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-ja.alli.ai/webapi/single_faq

このAPIを利用すれば特定のQ&Aの詳細を取得することができます。

Headers

NameTypeDescription

API-KEY*

string

割り当てられたAPIキーです。プロジェクト設定メニュー→全般タブから確認できます。

Request Body

NameTypeDescription

id*

string

詳細取得の対象となるQ&AのIDです。

format

string

html あるいは text です。textの場合、戻り値はplain textです。htmlの場合はhtmlで戻ります。回答にStyled htmlが含まれている場合(フォントの大きさや色など)、htmlをご使用ください。シンプルテキストの回答が必要な場合はtextを使用してください。デフォルトはhtmlとなっています。

検索結果は、以下のようなJSON形式で戻ります。

question: 対象となるQ&Aの質問です。

answer : 対象となるQ&Aの回答です。

id: 対象となるFAQのIDです。Requestで使用したものと同じ値です。

userFeedback: 対象となるQ&Aに対するユーザーフィードバックです。

agentFeedback: 対象となるQ&Aに対するエージェントフィードバックです。

lastUpdatedDate, createdDate: 対象となるQ&Aの更新日と作成日です。

hashtags: 対象となる質問に付与された全てのハッシュタグです。

{
    "result": {
        "question": "そこにいるのは誰?",
        "answer": "鈴木です",
        "id": "RkFROjYwMmY2ZTQ0YWZmMWQ5YmQ0NmM5Y2VkNw==",
        "userFeedback": {
            "positiveCount": 0,
            "negativeCount": 0
        },
        "agentFeedback": {
            "positiveCount": 0,
            "negativeCount": 1
        },
        "lastUpdatedDate": "2021-02-19",
        "createdDate": "2021-02-19",
        "hashtags": []
    }
}

Request Example

YOUR API KEYをプロジェクトのAPIキーに変更しなければなりません。APIキーの取得の項目をご参照ください。

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

Response Example

{
    "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": []
    }
}

Get Single Document

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

このAPIを利用すれば特定のドキュメントの詳細を取得することができます。

Headers

NameTypeDescription

API-KEY*

string

割り当てられたAPIキーです。プロジェクト設定メニュー→全般タブから確認できます。

Request Body

NameTypeDescription

id*

string

ドキュメントのidです。

検索結果は、以下のようなJSON形式で戻ります。

id:ドキュメントのidです。

documentName:ドキュメントファイルの名称です。

createDate:ドキュメントがアップロードされた日付です。

hashtags:ドキュメントに紐づけられたハッシュタグです。

agentFeedback:ドキュメントに対してエージェントからフィードバックされたgood/Badそれぞれの数です。

userFeedback:ドキュメントに対してユーザーからフィードバックされたgood/Badそれぞれの数です。

      "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

YOUR API KEYをプロジェクトのAPIキーに変更しなければなりません。APIキーの取得の項目をご参照ください。

curl -X GET \
-d '{"id": "S25vd2xlZGdlQmFzZTo1ZjMzODFkZmNhYWJjYWUyMjkzYjFhY2U="}' \
-H "API-KEY: YOUR API KEY" \
https://backend-ja.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-ja.alli.ai/webapi/faq_feedbacks

このAPIを使用すれば、検索クエリごとにQ&Aペアに与えられるフィードバックリストを得ることができます。

Headers

NameTypeDescription

API-KEY*

string

割り当てられたAPIキーです。プロジェクト設定メニュ→全般タブから確認できます。

AGENT-EMAIL

string

aaaエージェントのメールアドレスを指定することで、このAPI呼び出しを行うエージェントを特定できます。ここで指定するEメールアドレスは、ダッシュボードの[設定]>[エージェント]にて確認してください。

OWN-USER-ID

string

ユーザーのIDを指定することで、このAPI呼び出しを行うユーザーを特定できます。ここで指定するIDは、ダッシュボードの[顧客リスト]>[CUSTOMER_ID]もしくは[会話履歴]>[対話情報]にて確認できます。

Request Body

NameTypeDescription

offset

integer

ページに出力される第一項目の位置を決めます。

limit

integer

1ページに出力する項目の数を決めます。最大値は100です。

検索結果は、以下のようなJSON形式で戻ります。

query: 以下のQ&Aに対し、フィードバック情報を持っている検索クエリです。

feedbacks: 当該クエリに従属したフィードバック情報です。

faq_idとpositiveを含みます。

faqId: 当該クエリに対し、フィードバックが与えられたQ&AのIDです。

positive: true あるいは false です。trueはQ&Aに対するポジティブなフィルタリング、falseはネガティブなフィードバックを意味します。

count: リスト化したフィードバックの数です。

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

Request Example

YOUR API KEYをプロジェクトのAPIキーに変更しなければなりません。APIキーの取得の項目をご参照ください。

特定のユーザーからフィードバックリストを取得する場合は、ヘッダーにOWN-USER-IDを指定してください。特定のエージェントからフィードバックリストを取得する場合は、ヘッダーにAGENT-EMAILを指定してください。OWN-USER-IDまたはAGENT-EMAILを指定しない場合、すべてのフィードバックが返されます。

curl -X GET \
-d '{"offset": 0, "limit": 10}' \
-H "API-KEY: YOUR API KEY" \
https://backend-ja.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-ja.alli.ai/webapi/faq_feedback

このAPIを利用すれば、検索クエリごとにQ&Aにフィードバックを与えたり、与えられたフィードバックを削除することができます。

Headers

NameTypeDescription

API-KEY*

string

割り当てられたAPIキーです。プロジェクト設定メニュ→全般タブから確認できます。

AGENT-EMAIL

string

エージェントのEメールアドレスを指定することで、このAPI呼び出しを行うエージェントを特定できます。ここで指定するEメールアドレスは、ダッシュボードの [設定] > [エージェント] にて確認してください。

Request Body

NameTypeDescription

query*

string

当該FAQにフィードバック情報を与えたり、取り消す検索クエリです。

id*

string

フィードバック情報を与えたり、取り消すFAQのIDです。検索する際、検索クエリと結果のQ&Aペアに対して与えられ、上記のPOST Q&A APIを利用して抽出することができます。

isPositive*

boolean

trueであればポジティブなフィードバック、falseであればネガティブなフィードバックを与えます。nullは与えられたフィードバックを取り消します。

検索結果は、以下のようなJSON形式で戻ります。

id: フィードバック情報を与えたり、取り消したQ&AのIDです。

Requestで使用したものと同じ情報です。

positiveCount: Requestの処理後のポジティブなフィードバック数の合計です。

negativeCount: Requestの処理後のネガティブなフィードバック数の合計です。

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

Request Example

YOUR API KEYをプロジェクトのAPIキーに変更しなければなりません。APIキーの取得の項目をご参照ください。

Q&A_IDを該当するQ&A IDに変更しなければなりません。Q&A IDを取得するには、Q&AのResponse Example もしくはQ&A FeedbacksのResponse Exampleの項目をご参照ください。

curl https://backend-ja.alli.ai/webapi/faq_feedback \
-d '{"query": "どこにありますか?", 
     "id": "RkFROjVmNDA1MWVjMTFmOWJjMTJjOGUwMTgyNw==", 
     "isPositive": true}' \
-H "Content-Type: application/json" \
-H "API-KEY: YOUR API KEY"

Response Example

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

Q&A User Feedback

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

このAPIを利用すると、対象のFAQに対してユーザーフィードバックを登録することができます。 (ユーザーフィードバックは、Alliチャットボットを使用して回答に対して適切か不適切をユーザーが送信するものです)。

Headers

NameTypeDescription

API-KEY*

string

割り当てられたAPIキーです。プロジェクト設定メニュ→全般タブから確認できます。

OWN-USER-ID

string

ユーザーのIDを指定することで、このAPI呼び出しを行うユーザーを特定できます。ここで指定するIDは、ダッシュボードの [顧客リスト]>[CUSTOMER_ID] もしくは[会話履歴]>[対話情報]にて確認できます。

USER-EMAIL

string

OWN-USER-IDを設定する際にユーザーのEメールアドレスを更新する場合は、ここで指定できます。

Request Body

NameTypeDescription

prev

boolean

このクエリを割り当てた以前のフィードバックに関するブール値(以前のフィードバックを変更するためにのみ使用する必要があります)

positive*

boolean

登録するフィードバックが適切か不適切かのブール値

query*

string

当該FAQにフィードバック情報を与えたり、取り消す検索クエリです。

id*

string

フィードバック情報を与えたり、取り消すFAQのIDです。検索する際、検索クエリと結果のQ&Aペアに対して与えられ、上記のPOST Q&A APIを利用して抽出することができます。

analyticsHashtags

array

ハッシュタグのスコープとして登録したすべてのハッシュタグの配列です。ハッシュタグによる分析で使用されます。

対象のFAQに対する現在のユーザーフィードバック(positiveCountとnegativeCountの両方)を返します。

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

Request Example

curl https://backend-ja.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-ja.alli.ai/webapi/upload_faq_file

この API を使用することで、tsv、csv、xlsx、および zip 形式で複数の Q&A をアップロードできます。

Headers

NameTypeDescription

API-KEY*

string

割り当てられたAPIキーです。プロジェクト設定メニュ→全般タブから確認できます。

AGENT-EMAIL

string

この API 呼び出しを行うエージェントを指定する場合は、ここでエージェントのメール アドレスを指定できます。これは、ダッシュボードの [設定] > [エージェント] の下にあります。

Request Body

NameTypeDescription

file*

string

ローカルの Q&A ファイルの場所。 xlsx、tsv、csv、および zip ファイルがサポートされています。

result:アップロード成功時にsuccessと表示します。

notUploaded:質問のいずれかがアップロードされていないか、既存のQ&Aが更新されていない場合、詳細がここにリストされます。

question: アップロードされていないまたは更新されていないQ&AのQの部分になります。state:Q&Aが「類似の質問」の内容の重複によりアップロードされていない場合は「dup」、同じ質問内容により既存のQ&Aが更新された場合は「up」と表示されます。

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

Request Example

YOUR API KEYをプロジェクトのAPIキーに変更しなければなりません。APIキーの取得の項目をご参照ください。

curl -F 'file=@/location/to/your_file' 
\-H 'API-KEY: YOUR_API_KEY'
https://backend-ja.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-ja.alli.ai/webapi/register_faq

このAPIを使用することで、新しいQ&Aを追加したり、既存のQ&Aを更新することができます。

Headers

NameTypeDescription

API-KEY*

string

割り当てられたAPIキーです。プロジェクト設定メニュ→全般タブから確認できます。

AGENT-EMAIL

string

​エージェントのEメールアドレスを指定することで、このAPI呼び出しを行うエージェントを特定できます。ここで指定するEメールアドレスは、ダッシュボードの [設定] > [エージェント] にて確認してください。

Request Body

NameTypeDescription

status

string

ONもしくはOFFとなります。ONの場合は、Q&A検索にて検索対象のQ&Aとなります。

question*

string

Q&Aの質問部分となります。

similarQuestions

string

類似質問を指します。類似質問として複数を追加できます。

answer*

string

Q&Aの回答部分です。同じ質問が質問がデータベースに存在する場合は既存の回答はこの回答部分に置き換わります。

hashtags

array

Q&Aに設定できるハッシュタグです。複数のハッシュタグを設定できます。

memo

string

エージェントにて確認できるQ&Aにおけるメモを指します。

followFolderPermission

boolean

アップロード時に所属所属するフォルダがある場合、そのフォルダの権限を引き継ぐかどうかを指定します(デフォルト値: True)。引き継がない場合、以下で指定された権限が使用されます。それ以外の特別な指定がない限り、すべてのエージェントとユーザーに権限が与えられます。

agentEditor

array

ファイルの編集権限を持つエージェントを登録してください。

agentViewer

array

ファイルの閲覧権限を持つエージェントを登録してください。

userViewer

object

ファイルの閲覧権限を持つユーザーを登録してください。customer_idを使用する場合は、own-user-idと同じです。customer_groupのid(categoryElementsId)は、CUSTOMER GROUPの問い合わせAPIを使用して取得できます。

allowOtherAgentsView

boolean

編集者/閲覧者リストに含まれていないエージェントも閲覧することができます。

allowOtherUsersView

boolean

編集者/閲覧者リストに含まれていないユーザーも閲覧することができます。

status: 登録されたQ&Aのステータスです。「created」とはQ&Aが新しく登録されたことを指します。また、「updated」は既存のQ&Aが新しい回答で更新されたことを指します。

id: 登録されたQ&AのIDを指します。

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

Request Example

YOUR API KEYをプロジェクトのAPIキーに変更しなければなりません。APIキーの取得の項目をご参照ください。

curl 'https://backend-ja.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-ja.alli.aiwebapi/delete_faq

このAPIを使用することで、Q&Aを削除することができます。

Path Parameters

NameTypeDescription

API-KEY*

string

割り当てられたAPIキーです。プロジェクト設定メニュ→全般タブから確認できます。

Request Body

NameTypeDescription

id*

string

削除したいQ&AのIDとなります。

status:Q&Aが正常に削除された場合は「deleted」となります。

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

Request Example

YOUR API KEYをプロジェクトのAPIキーに変更しなければなりません。APIキーの取得の項目をご参照ください。

curl 'https://backend-ja.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-ja.alli.ai/webapi/faqs

このAPIを使用することで、ナレッジベースのQ&Aを一覧で取得することができます。

Headers

NameTypeDescription

API-KEY*

string

割り当てられたAPIキーです。プロジェクト設定メニュ→全般タブから確認できます。

Request Body

NameTypeDescription

SearchTerm

string

取得するQ&Aをフィルタリングするためのキーワード検索クエリです

isUsed

boolean

trueの場合、オンになっているQ&Aのみがリストされ、falseの場合、オフになっているQ&Aのみが取得されます。

hashgtags

array

取得するQ&Aをフィルタリングするためのハッシュタグを指定できます。複数のハッシュタグを指定できます。

hashtagsOperator

string

andまたはorのいずれかとなります。結果にすべてのハッシュタグを含める場合は、andを選択してください。結果に少なくとも1つのハッシュタグを含める場合は、orを選択してください。

createdByAgent

string

trueの場合、リストにはエージェントによって作成されたQ&Aのみが含まれます。 falseの場合、他のQ&Aのみが含まれます。 createdByAgent、answeredByMrc、autoGenerated、editedByAgentフィルターは相互に排他的であり、それらが2つ以上使用される場合はORロジックが適用されることに注意してください。

answeredByMrc

string

trueの場合、リストには、アップロードされたドキュメントから回答が自動的に抽出されるQ&Aのみが含まれます。 falseの場合、他のQ&Aのみが含まれます。

autoGenerated

string

trueの場合、リストには自動生成されたQ&Aのみが含まれます。 falseの場合、他のQ&Aのみが含まれます。

editedByAgent

string

trueの場合、リストには、登録後にエージェントが編集したQ&Aのみが含まれます。 falseの場合、それ以外のQ&Aのみが含まれます。

format

string

html あるいは text です。textの場合、戻り値はplain textです。htmlの場合はhtmlとなります。回答にStyle htmlが含まれている場合(フォントの大きさや色など)、htmlをご使用ください。シンプルなテキストが必要な場合はtextを使用してください。デフォルトはhtmlとなります。

offset

integer

オフセットを使用することで、表示するQ&Aの最初のインデックスを指定できます。

limit

integer

limitを使用することで、1ページに返されるオブジェクトの数を設定できます。最大値とデフォルト値は1000です。

offset:リクエストパラメーターとしてのoffsetと同じ値となります。

count:limitが適用された際に取得されたQ&Aの総数。

totalCount:適用されたフィルターの結果としてのQ&Aの総数。

id:Q&AのID。

question:Q&Aの質問部分。

answer:Q&Aの回答部分。

hashtags:Q&Aに設定されているハッシュタグ。

userFeedback:肯定的および否定的なユーザーフィードバックの数。ユーザーのフィードバックは、将来のクエリの検索結果に影響します。

agentFeedback:正および負のエージェントフィードバックの数。エージェントのフィードバックは、将来のクエリの検索結果に影響します。

lastUpdatedDate:Q&Aが最後に更新された日付。

createdDate:Q&Aが作成された日付。

{
    "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

YOUR API KEYをプロジェクトのAPIキーに変更しなければなりません。APIキーの取得の項目をご参照ください。

curl -X GET 'https://backend-ja.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-ja.alli.ai/webapi/faq_candidates

このAPIを利用すれば、ユーザーからの質問の中で回答されていない質問、つまり、「未回答質問」のリストを得ることができます。

Headers

NameTypeDescription

API-KEY*

string

割り当てられたAPIキーです。プロジェクト設定メニュ→全般タブから確認できます。

Request Body

NameTypeDescription

hashtags

array

当該ハッシュタグが付いている未回答質問のみ確認できるようにするarrayです。

searchTerm

string

確認する未回答質問をフィルタリングするための検索クエリです。

order

string

未回答質問を並べる基準を意味します。属性_[DESC or ASC]形式で構成され、属性にはFREQUENCYとCREATEDATがあります。

state

string

確認する未回答質問のステータスです。ALL、ACTIVE、 ARCHIVEDのうち一つの値を持ちます。

offset

integer

ページに出力される第一項目の位置を決めます。

limit

integer

1ページに出力する項目の数を決めます。最大値は100です。

sources

array

指定したソースに検索範囲を制限する場合に使用するソース配列です。SDK、QNA、DOCUMENTS、APIをソースとして使用できます。

検索結果は、以下のようなJSON形式で戻ります。

count: リスト化した未回答質問の合計件数です。

id: 未回答質問に対して抽出された回答のIDです。新しい未回答質問が登録されると、Alliはアップロードしたドキュメントから自動的に回答を抽出して登録を試みます。

frequency: questions の下にある全てのfrequency 値の合計です。

textAnswer: 未回答質問に対して自動抽出された回答の内容です。

state: 未回答質問のステータスです。Q&Aデータベースに追加されていない場合はACTIVE、追加された場合はARCHIVEDで表示されます。

createdAt: 未回答質問が生成された日時です。

questions: 複数の類似質問が同一の回答を共有することができますが、同じ回答を共有する全ての未回答質問の情報をここで確認することができます。

id (under questions): 未回答のユーザー質問のIDです。

question (under questions): 未回答のユーザー質問の内容です。

frequency (under questions): ユーザーが同じ質問を何回したか表示します。

id (under history): 未回答質問のヒストリー情報に割り当てられたIDです。ヒストリー情報はユーザーが当該質問をした時のログ情報です。

{
	"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

YOUR API KEYをプロジェクトのAPIキーに変更しなければなりません。APIキーの取得の項目をご参照ください。

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

Response Example

{
  "count": 2,
  "result": [
    {
      "id": "RkFRQ2FuZGlkYXRlOjVlYjA3OGU5MGFmZmMyM2QxZjc4ZTMzMQ==",
      "frequency": 1,
      "textAnswer": "使い方はこの通りです。\n— Fromユーザーガイド.pdf",
      "state": "ACTIVE",
      "createdAt": 1588623593321,
      "questions": [
        {
          "id": "RkFRQ2FuZGlkYXRlUXVlc3Rpb246NWViMDc4ZTkwYWZmYzIzZDFmNzhlMzMw",
          "question": "ユーザーマニュアルがありますか?",
          "frequency": 1,
          "history": {
            "id": "Q29udmVyc2F0aW9uOjVlYjA3OGI2NWUyMTJlMTMzZDM4NDAzOA=="
          }
        }
      ]
    },
    {
      "id": "RkFRQ2FuZGlkYXRlOjVlOWEzZWI2MmZlOTFkMzIwYjE2YWQyOQ==",
      "frequency": 1,
      "textAnswer": "15日以内であればいつでも取り消しができます。\n— Fromカスタマーマニュアル.pdf",
      "state": "ACTIVE",
      "createdAt": 1587166902114,
      "questions": [
        {
          "id": "RkFRQ2FuZGlkYXRlUXVlc3Rpb246NWU5YTNlYjYyZmU5MWQzMjBiMTZhZDI4",
          "question": "払い戻しできますか?",
          "frequency": 1,
          "history": {
            "id": "Q29udmVyc2F0aW9uOjVlOWEzZDliNjU5YmM2NTEyMTk5MDQ3Ng=="
          }
        }
      ]
    }
  ],
  "errors": null
}

Q&A Candidates

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

未回答の質問リストに未回答の質問を新たに登録します。

Headers

NameTypeDescription

API-KEY*

string

割り当てられたAPIキーです。プロジェクト設定メニュ→全般タブから確認できます。

AGENT-EMAIL

string

エージェントのEメールアドレスを指定することで、このAPI呼び出しを行うエージェントを特定できます。ここで指定するEメールアドレスは、ダッシュボードの [設定] > [エージェント] にて確認してください。

OWN-USER-ID

string

ユーザーのIDを指定することで、このAPI呼び出しを行うユーザーを特定できます。ここで指定するIDは、ダッシュボードの [顧客リスト]>[CUSTOMER_ID] もしくは[会話履歴]>[対話情報]にて確認できます。

USER-EMAIL

string

OWN-USER-IDを設定する際にユーザーのEメールアドレスを更新する場合は、ここで指定できます。

Request Body

NameTypeDescription

queries*

string

登録したいすべてのクエリのリスト

結果は次の JSON 形式で取得されます。

id: 登録された未回答の質問のID。

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

Request Example

YOUR API KEYをプロジェクトのAPIキーに変更しなければなりません。APIキーの取得の項目をご参照ください。

curl https://backend-ja.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-ja.alli.ai/webapi/mrc_feedbacks

このAPIを使用すれば、検索クエリごとにドキュメントから抽出された回答に与えられるフィードバックリストを得ることができます。

Headers

NameTypeDescription

API-KEY*

string

割り当てられたAPIキーです。プロジェクト設定メニュ→全般タブから確認できます。

AGENT-EMAIL

string

エージェントのメールアドレスを指定することで、このAPI呼び出しを行うエージェントを特定できます。ここで指定するメールアドレスは、ダッシュボードの[設定]>[エージェント]にて確認してください。

OWN-USER-ID

string

ユーザーのIDを指定することで、このAPI呼び出しを行うユーザーを特定できます。ここで指定したIDは、ダッシュボードの[顧客リスト]>[CUSTOMER_ID]もしくは[会話履歴]>[対話情報]にて確認できます。

Request Body

NameTypeDescription

offset

integer

ページに出力される第一項目の位置を決めます。

limit

integer

1ページに出力する項目の数を決めます。最大値は100です。

検索結果は、以下のようなJSON形式で戻ります。

query: 以下の回答が抽出された検索クエリです。

documentId: 回答を抽出したドキュメントのIDです。

answer: 当該クエリに対してドキュメントから抽出された回答の内容です。

answerHash: 当該クエリに対してドキュメントから抽出された回答に与えられるIDの値です。Documents検索をした時、クエリと検索結果のペアに与えられる値であり、上記のPOST Documents APIを利用して得られるものと同じ値です。

positive: true あるいは false です。trueは当該回答に対するポジティブなフィードバック、falseはネガティブなフィードバックを意味します。

count: リスト化したフィードバック件数の合計です。

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

Request Example

YOUR API KEYをプロジェクトのAPIキーに変更しなければなりません。APIキーの取得の項目をご参照ください。

特定のユーザーからフィードバックリストを取得する場合は、ヘッダーにOWN-USER-IDを指定してください。特定のエージェントからフィードバックリストを取得する場合は、ヘッダーにAGENT-EMAILを指定してください。

curl -X GET \
-d '{"offset": 0, "limit": 10}' \
-H "API-KEY: YOUR API KEY" \
https://backend-ja.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-ja.alli.ai/webapi/mrc_feedback

このAPIを使用すれば、検索クエリによって抽出された検索結果に対してフィードバックをしたり、削除することができます。

Headers

NameTypeDescription

API-KEY*

string

割り当てられたAPIキーです。プロジェクト設定メニュ→全般タブから確認できます。

AGENT-EMAIL

string

エージェントのEメールアドレスを指定することで、このAPI呼び出しを行うエージェントを特定できます。ここで指定するEメールアドレスは、ダッシュボードの [設定] > [エージェント] にて確認してください。

Request Body

NameTypeDescription

query*

string

Documentsの検索結果にフィードバック情報を与える検索クエリです。

id*

string

回答が抽出されたドキュメントのIDです。

answerHash*

string

当該クエリに対してドキュメントから抽出された回答に与えられるIDの値です。Documents検索をした時にクエリと検索結果のペアに与えられる値であり、上記のPOST Documents APIを利用して得ることができます。

isPositive*

boolean

trueであれば当該クエリに対する検索結果にポジティブなフィードバック、falseであればネガティブなフィードバックを与えます。nullの場合は与えられたフィードバックを取り消します。

検索結果は、以下のようなJSON形式で戻ります。

positivecount: Requestの処理後のポジティブなフィードバック数の合計です。

negativecount: Requestの処理後のネガティブなフィードバック数の合計です。

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

Request Example

YOUR API KEYをプロジェクトのAPIキーに変更しなければなりません。APIキーの取得の項目をご参照ください。

DOCUMENT_IDとANSWER_HASHの部分を該当するIDに変更しなければなりません。それぞれの情報を得るにはDocumentsのResponse Example項目、もしくはDocuments FeedbacksのResponse Exampleの項目をご参照ください。

curl https://backend-ja.alli.ai/webapi/mrc_feedback \
-d '{"query": "保険の解約はどうすればいいですか?", 
     "id": "S25vd2xlZGdlQmFzZTo1ZjMzODFkZmNhYWJjYWUyMjkzYjFhY2U=", 
     "answerHash": "8430cf3b9af628abc1bb063802db39be", 
     "isPositive": true}' \
-H "Content-Type: application/json" \
-H "API-KEY: YOUR API KEY"

Response Example

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

Documents Search User Feedback

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

このAPIを利用すると、ドキュメント検索の結果に対してユーザーフィードバックを登録することができます。

Headers

NameTypeDescription

API-KEY*

string

割り当てられたAPIキーです。プロジェクト設定メニュ→全般タブから確認できます。

OWN-USER-ID

string

ユーザーのIDを指定することで、このAPI呼び出しを行うユーザーを特定できます。ここで指定するIDは、ダッシュボードの [顧客リスト]>[CUSTOMER_ID] もしくは[会話履歴]>[対話情報]にて確認できます。

USER-EMAIL

string

OWN-USER-IDを設定する際にユーザーのEメールアドレスを更新する場合は、ここで指定できます。

Request Body

NameTypeDescription

anserHash*

string

当該クエリに対してドキュメントから抽出された回答に与えられるIDの値です。Documents検索をした時、クエリと検索結果のペアに与えられる値であり、上記のPOST Documents APIを利用して得られるものと同じ値です。

id*

string

ドキュメント検索の回答が抽出されたドキュメントのIDです。

positive*

boolean

登録するフィードバックが適切か不適切かのブール値です。

query*

string

文字列形式の検索クエリです。

analyticsHashtags

array

ハッシュタグをスコープとして登録し、ハッシュタグによる分析で使用するためのハッシュタグの配列です。

変更後のユーザーフィードバックのpositiveCountとnegativeCountをレスポンスとして返します。

{
    "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-ja.alli.ai/webapi/upload_file

このAPIを利用することで、Cognitive Searchで検索対象となるファイルをローカルの保存場所からアップロードすることができます。アップロード可能なファイル形式は下記となります。 ファイル形式:PDF、TXT、MS Word、PowerPoint、Excel、HTM、HTML 外部リンクが含まれるHTMLファイルをアップロードするには、アップロードする前に関連するリンク先のHTMLも含め、zipファイルに圧縮の上、アップロードください。

Headers

NameTypeDescription

API-KEY*

string

割り当てられたAPIキーです。プロジェクト設定メニュ→全般タブから確認できます。

AGENT-EMAIL

string