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
を用います。
エージェントのメール情報は、ダッシュボードの[設定] > [エージェント メニュー]で確認できます。以下に例を示します。
ユーザー情報
ユーザー情報の場合はリクエスト ヘッダーにOWN-USER-ID
を用います。ユーザー ID は新しいものでも既存のものでもかまいません。新しいユーザー ID が提供された場合、Alli はその ID で新しいユーザーを作成します。同じOWN-USER-ID
のヘッダーを持つAPI 呼び出しについては、同じユーザーからの呼び出しと見なされます。
同時にユーザーのメール アドレスを更新する場合は、USER-EMAILの
リクエスト ヘッダーでメール アドレスを指定できます。以下に例を示します。
OWN-USER-ID
には非 ASCII 文字を使用できません。ユーザー IDに非ASCII文字が含まれている場合は、IDをbase64 にエンコードして base64:CONVERTED_ID
として追加することで非ASCII文字をOWN-USER-ID
に入力することができます。
保存されたユーザー ID とメール情報は、Alli ダッシュボードの [顧客] メニューでことができます。
エラーメッセージ
予想されるresponseがない場合は、エラーメッセージを確認してください。例えば、間違ったHTTPメソッドを使用した場合、以下のような形式のエラーメッセージが戻ります。
Search from Q&A
POST
https://backend-ja.alli.ai/webapi/faq
Search from Q&A APIは、Q&Aのデータベースから質問と最も関連のあるQ&Aペアを検索して提示します。
Headers
Name | Type | Description |
---|---|---|
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
Name | Type | Description |
---|---|---|
autoRegisterCandidates | boolean | デフォルトはtrueです。これをfalseにしますと、答えがない場合に自動でCandidatesに登録しない様になります。 |
hashtagsOperator | string | ANDまたはORのいずれかとなります。 結果にすべてのハッシュタグを含める場合は、ANDを選択します。 結果に少なくとも1つのハッシュタグを含める場合は、ORを選択します。 |
hashtags | array | 検索対象に含めるハッシュタグの配列 |
maxResults | integer | レスポンスとして表示される結果の最大数です。 |
query* | string | 文字列形式の検索クエリです。 |
format | string |
|
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>設定メニューから変更することができます。
Request Example
YOUR API KEYをプロジェクトのAPIキーに変更しなければなりません。APIキーの取得の項目をご参照ください。
Response Example
Search from Documents
POST
https://backend-ja.alli.ai/webapi/mrc
Documents APIは、複雑なテーブルなどが含まれたドキュメントからもユーザーの質問に対する回答を抽出することができます。
Headers
Name | Type | Description |
---|---|---|
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
Name | Type | Description |
---|---|---|
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のダッシュボードで設定されている場合) 検索結果の数と閾値は、ダッシュボードの設定に従います。ドキュメント > 設定で設定を確認してください。
Request Example
YOUR API KEYをプロジェクトのAPIキーに変更しなければなりません。APIキーの取得の項目をご参照ください。
Response Example
Get Single Q&A
GET
https://backend-ja.alli.ai/webapi/single_faq
このAPIを利用すれば特定のQ&Aの詳細を取得することができます。
Headers
Name | Type | Description |
---|---|---|
API-KEY* | string | 割り当てられたAPIキーです。プロジェクト設定メニュー→全般タブから確認できます。 |
Request Body
Name | Type | Description |
---|---|---|
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: 対象となる質問に付与された全てのハッシュタグです。
Request Example
YOUR API KEYをプロジェクトのAPIキーに変更しなければなりません。APIキーの取得の項目をご参照ください。
Response Example
Get Single Document
GET
https://backend-ja.alli.ai/webapi/single_document
このAPIを利用すれば特定のドキュメントの詳細を取得することができます。
Headers
Name | Type | Description |
---|---|---|
API-KEY* | string | 割り当てられたAPIキーです。プロジェクト設定メニュー→全般タブから確認できます。 |
Request Body
Name | Type | Description |
---|---|---|
id* | string | ドキュメントのidです。 |
検索結果は、以下のようなJSON形式で戻ります。
id:ドキュメントのidです。
documentName:ドキュメントファイルの名称です。
createDate:ドキュメントがアップロードされた日付です。
hashtags:ドキュメントに紐づけられたハッシュタグです。
agentFeedback:ドキュメントに対してエージェントからフィードバックされたgood/Badそれぞれの数です。
userFeedback:ドキュメントに対してユーザーからフィードバックされたgood/Badそれぞれの数です。
Request Example
YOUR API KEYをプロジェクトのAPIキーに変更しなければなりません。APIキーの取得の項目をご参照ください。
Response Example
Q&A Feedbacks
GET
https://backend-ja.alli.ai/webapi/faq_feedbacks
このAPIを使用すれば、検索クエリごとにQ&Aペアに与えられるフィードバックリストを得ることができます。
Headers
Name | Type | Description |
---|---|---|
API-KEY* | string | 割り当てられたAPIキーです。プロジェクト設定メニュ→全般タブから確認できます。 |
AGENT-EMAIL | string | aaaエージェントのメールアドレスを指定することで、このAPI呼び出しを行うエージェントを特定できます。ここで指定するEメールアドレスは、ダッシュボードの[設定]>[エージェント]にて確認してください。 |
OWN-USER-ID | string | ユーザーのIDを指定することで、このAPI呼び出しを行うユーザーを特定できます。ここで指定するIDは、ダッシュボードの[顧客リスト]>[CUSTOMER_ID]もしくは[会話履歴]>[対話情報]にて確認できます。 |
Request Body
Name | Type | Description |
---|---|---|
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: リスト化したフィードバックの数です。
Request Example
YOUR API KEYをプロジェクトのAPIキーに変更しなければなりません。APIキーの取得の項目をご参照ください。
特定のユーザーからフィードバックリストを取得する場合は、ヘッダーにOWN-USER-IDを指定してください。特定のエージェントからフィードバックリストを取得する場合は、ヘッダーにAGENT-EMAILを指定してください。OWN-USER-IDまたはAGENT-EMAILを指定しない場合、すべてのフィードバックが返されます。
Response Example
Q&A Feedback
POST
https://backend-ja.alli.ai/webapi/faq_feedback
このAPIを利用すれば、検索クエリごとにQ&Aにフィードバックを与えたり、与えられたフィードバックを削除することができます。
Headers
Name | Type | Description |
---|---|---|
API-KEY* | string | 割り当てられたAPIキーです。プロジェクト設定メニュ→全般タブから確認できます。 |
AGENT-EMAIL | string | エージェントのEメールアドレスを指定することで、このAPI呼び出しを行うエージェントを特定できます。ここで指定するEメールアドレスは、ダッシュボードの [設定] > [エージェント] にて確認してください。 |
Request Body
Name | Type | Description |
---|---|---|
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の処理後のネガティブなフィードバック数の合計です。
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の項目をご参照ください。
Response Example
Q&A User Feedback
POST
https://backend-ja.alli.ai/webapi/faq/user_feedback
このAPIを利用すると、対象のFAQに対してユーザーフィードバックを登録することができます。 (ユーザーフィードバックは、Alliチャットボットを使用して回答に対して適切か不適切をユーザーが送信するものです)。
Headers
Name | Type | Description |
---|---|---|
API-KEY* | string | 割り当てられたAPIキーです。プロジェクト設定メニュ→全般タブから確認できます。 |
OWN-USER-ID | string | ユーザーのIDを指定することで、このAPI呼び出しを行うユーザーを特定できます。ここで指定するIDは、ダッシュボードの [顧客リスト]>[CUSTOMER_ID] もしくは[会話履歴]>[対話情報]にて確認できます。 |
USER-EMAIL | string | OWN-USER-IDを設定する際にユーザーのEメールアドレスを更新する場合は、ここで指定できます。 |
Request Body
Name | Type | Description |
---|---|---|
prev | boolean | このクエリを割り当てた以前のフィードバックに関するブール値(以前のフィードバックを変更するためにのみ使用する必要があります) |
positive* | boolean | 登録するフィードバックが適切か不適切かのブール値 |
query* | string | 当該FAQにフィードバック情報を与えたり、取り消す検索クエリです。 |
id* | string | フィードバック情報を与えたり、取り消すFAQのIDです。検索する際、検索クエリと結果のQ&Aペアに対して与えられ、上記のPOST Q&A APIを利用して抽出することができます。 |
analyticsHashtags | array | ハッシュタグのスコープとして登録したすべてのハッシュタグの配列です。ハッシュタグによる分析で使用されます。 |
対象のFAQに対する現在のユーザーフィードバック(positiveCountとnegativeCountの両方)を返します。
Request Example
Response Example
Upload Q&As
POST
https://backend-ja.alli.ai/webapi/upload_faq_file
この API を使用することで、tsv、csv、xlsx、および zip 形式で複数の Q&A をアップロードできます。
Headers
Name | Type | Description |
---|---|---|
API-KEY* | string | 割り当てられたAPIキーです。プロジェクト設定メニュ→全般タブから確認できます。 |
AGENT-EMAIL | string | この API 呼び出しを行うエージェントを指定する場合は、ここでエージェントのメール アドレスを指定できます。これは、ダッシュボードの [設定] > [エージェント] の下にあります。 |
Request Body
Name | Type | Description |
---|---|---|
file* | string | ローカルの Q&A ファイルの場所。 xlsx、tsv、csv、および zip ファイルがサポートされています。 |
result:アップロード成功時にsuccessと表示します。
notUploaded:質問のいずれかがアップロードされていないか、既存のQ&Aが更新されていない場合、詳細がここにリストされます。
question: アップロードされていないまたは更新されていないQ&AのQの部分になります。state:Q&Aが「類似の質問」の内容の重複によりアップロードされていない場合は「dup」、同じ質問内容により既存のQ&Aが更新された場合は「up」と表示されます。
Request Example
YOUR API KEYをプロジェクトのAPIキーに変更しなければなりません。APIキーの取得の項目をご参照ください。
Response Example
Add Q&A
POST
https://backend-ja.alli.ai/webapi/register_faq
このAPIを使用することで、新しいQ&Aを追加したり、既存のQ&Aを更新することができます。
Headers
Name | Type | Description |
---|---|---|
API-KEY* | string | 割り当てられたAPIキーです。プロジェクト設定メニュ→全般タブから確認できます。 |
AGENT-EMAIL | string | エージェントのEメールアドレスを指定することで、このAPI呼び出しを行うエージェントを特定できます。ここで指定するEメールアドレスは、ダッシュボードの [設定] > [エージェント] にて確認してください。 |
Request Body
Name | Type | Description |
---|---|---|
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を指します。
Request Example
YOUR API KEYをプロジェクトのAPIキーに変更しなければなりません。APIキーの取得の項目をご参照ください。
Response Example
delete Q&A
POST
https://backend-ja.alli.aiwebapi/delete_faq
このAPIを使用することで、Q&Aを削除することができます。
Path Parameters
Name | Type | Description |
---|---|---|
API-KEY* | string | 割り当てられたAPIキーです。プロジェクト設定メニュ→全般タブから確認できます。 |
Request Body
Name | Type | Description |
---|---|---|
id* | string | 削除したいQ&AのIDとなります。 |
status:Q&Aが正常に削除された場合は「deleted」となります。
Request Example
YOUR API KEYをプロジェクトのAPIキーに変更しなければなりません。APIキーの取得の項目をご参照ください。
Response Example
List Q&As
GET
https://backend-ja.alli.ai/webapi/faqs
このAPIを使用することで、ナレッジベースのQ&Aを一覧で取得することができます。
Headers
Name | Type | Description |
---|---|---|
API-KEY* | string | 割り当てられたAPIキーです。プロジェクト設定メニュ→全般タブから確認できます。 |
Request Body
Name | Type | Description |
---|---|---|
SearchTerm | string | 取得するQ&Aをフィルタリングするためのキーワード検索クエリです |
isUsed | boolean | trueの場合、オンになっているQ&Aのみがリストされ、falseの場合、オフになっているQ&Aのみが取得されます。 |
hashgtags | array | 取得するQ&Aをフィルタリングするためのハッシュタグを指定できます。複数のハッシュタグを指定できます。 |
hashtagsOperator | string |
|
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 |
|
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が作成された日付。
Request Example
YOUR API KEYをプロジェクトのAPIキーに変更しなければなりません。APIキーの取得の項目をご参照ください。
Response Example
Q&A Candidates
GET
https://backend-ja.alli.ai/webapi/faq_candidates
このAPIを利用すれば、ユーザーからの質問の中で回答されていない質問、つまり、「未回答質問」のリストを得ることができます。
Headers
Name | Type | Description |
---|---|---|
API-KEY* | string | 割り当てられたAPIキーです。プロジェクト設定メニュ→全般タブから確認できます。 |
Request Body
Name | Type | Description |
---|---|---|
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です。ヒストリー情報はユーザーが当該質問をした時のログ情報です。
Request Example
YOUR API KEYをプロジェクトのAPIキーに変更しなければなりません。APIキーの取得の項目をご参照ください。
Response Example
Q&A Candidates
POST
https://backend-ja.alli.ai/webapi/add_faq_candidates
未回答の質問リストに未回答の質問を新たに登録します。
Headers
Name | Type | Description |
---|---|---|
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
Name | Type | Description |
---|---|---|
queries* | string | 登録したいすべてのクエリのリスト |
結果は次の JSON 形式で取得されます。
id: 登録された未回答の質問のID。
Request Example
YOUR API KEYをプロジェクトのAPIキーに変更しなければなりません。APIキーの取得の項目をご参照ください。
Response Example
Documents Feedbacks
GET
https://backend-ja.alli.ai/webapi/mrc_feedbacks
このAPIを使用すれば、検索クエリごとにドキュメントから抽出された回答に与えられるフィードバックリストを得ることができます。
Headers
Name | Type | Description |
---|---|---|
API-KEY* | string | 割り当てられたAPIキーです。プロジェクト設定メニュ→全般タブから確認できます。 |
AGENT-EMAIL | string | エージェントのメールアドレスを指定することで、このAPI呼び出しを行うエージェントを特定できます。ここで指定するメールアドレスは、ダッシュボードの[設定]>[エージェント]にて確認してください。 |
OWN-USER-ID | string | ユーザーのIDを指定することで、このAPI呼び出しを行うユーザーを特定できます。ここで指定したIDは、ダッシュボードの[顧客リスト]>[CUSTOMER_ID]もしくは[会話履歴]>[対話情報]にて確認できます。 |
Request Body
Name | Type | Description |
---|---|---|
offset | integer | ページに出力される第一項目の位置を決めます。 |
limit | integer | 1ページに出力する項目の数を決めます。最大値は100です。 |
検索結果は、以下のようなJSON形式で戻ります。
query: 以下の回答が抽出された検索クエリです。
documentId: 回答を抽出したドキュメントのIDです。
answer: 当該クエリに対してドキュメントから抽出された回答の内容です。
answerHash: 当該クエリに対してドキュメントから抽出された回答に与えられるIDの値です。Documents検索をした時、クエリと検索結果のペアに与えられる値であり、上記のPOST Documents APIを利用して得られるものと同じ値です。
positive: true あるいは false です。trueは当該回答に対するポジティブなフィードバック、falseはネガティブなフィードバックを意味します。
count: リスト化したフィードバック件数の合計です。
Request Example
YOUR API KEYをプロジェクトのAPIキーに変更しなければなりません。APIキーの取得の項目をご参照ください。
特定のユーザーからフィードバックリストを取得する場合は、ヘッダーにOWN-USER-IDを指定してください。特定のエージェントからフィードバックリストを取得する場合は、ヘッダーにAGENT-EMAILを指定してください。
Response Example
Documents Search Feedback
POST
https://backend-ja.alli.ai/webapi/mrc_feedback
このAPIを使用すれば、検索クエリによって抽出された検索結果に対してフィードバックをしたり、削除することができます。
Headers
Name | Type | Description |
---|---|---|
API-KEY* | string | 割り当てられたAPIキーです。プロジェクト設定メニュ→全般タブから確認できます。 |
AGENT-EMAIL | string | エージェントのEメールアドレスを指定することで、このAPI呼び出しを行うエージェントを特定できます。ここで指定するEメールアドレスは、ダッシュボードの [設定] > [エージェント] にて確認してください。 |
Request Body
Name | Type | Description |
---|---|---|
query* | string | Documentsの検索結果にフィードバック情報を与える検索クエリです。 |
id* | string | 回答が抽出されたドキュメントのIDです。 |
answerHash* | string | 当該クエリに対してドキュメントから抽出された回答に与えられるIDの値です。Documents検索をした時にクエリと検索結果のペアに与えられる値であり、上記のPOST Documents APIを利用して得ることができます。 |
isPositive* | boolean | trueであれば当該クエリに対する検索結果にポジティブなフィードバック、falseであればネガティブなフィードバックを与えます。nullの場合は与えられたフィードバックを取り消します。 |
検索結果は、以下のようなJSON形式で戻ります。
positivecount: Requestの処理後のポジティブなフィードバック数の合計です。
negativecount: Requestの処理後のネガティブなフィードバック数の合計です。
Request Example
YOUR API KEYをプロジェクトのAPIキーに変更しなければなりません。APIキーの取得の項目をご参照ください。
DOCUMENT_IDとANSWER_HASHの部分を該当するIDに変更しなければなりません。それぞれの情報を得るにはDocumentsのResponse Example項目、もしくはDocuments FeedbacksのResponse Exampleの項目をご参照ください。
Response Example
Documents Search User Feedback
POST
https://backend-ja.alli.ai/webapi/mrc/user_feedback
このAPIを利用すると、ドキュメント検索の結果に対してユーザーフィードバックを登録することができます。
Headers
Name | Type | Description |
---|---|---|
API-KEY* | string | 割り当てられたAPIキーです。プロジェクト設定メニュ→全般タブから確認できます。 |
OWN-USER-ID | string | ユーザーのIDを指定することで、このAPI呼び出しを行うユーザーを特定できます。ここで指定するIDは、ダッシュボードの [顧客リスト]>[CUSTOMER_ID] もしくは[会話履歴]>[対話情報]にて確認できます。 |
USER-EMAIL | string | OWN-USER-IDを設定する際にユーザーのEメールアドレスを更新する場合は、ここで指定できます。 |
Request Body
Name | Type | Description |
---|---|---|
anserHash* | string | 当該クエリに対してドキュメントから抽出された回答に与えられるIDの値です。Documents検索をした時、クエリと検索結果のペアに与えられる値であり、上記のPOST Documents APIを利用して得られるものと同じ値です。 |
id* | string | ドキュメント検索の回答が抽出されたドキュメントのIDです。 |
positive* | boolean | 登録するフィードバックが適切か不適切かのブール値です。 |
query* | string | 文字列形式の検索クエリです。 |
analyticsHashtags | array | ハッシュタグをスコープとして登録し、ハッシュタグによる分析で使用するためのハッシュタグの配列です。 |
変更後のユーザーフィードバックのpositiveCountとnegativeCountをレスポンスとして返します。
Request Example
Response Example
Document Upload APIs
POST
https://backend-ja.alli.ai/webapi/upload_file
このAPIを利用することで、Cognitive Searchで検索対象となるファイルをローカルの保存場所からアップロードすることができます。アップロード可能なファイル形式は下記となります。 ファイル形式:.txt, .docx, .csv, .xls, .xlsx, .xlsm, .jpg, .jpeg, .png, .hwp, .hwpx, .pdf, .ppt, .pptx, .doc 外部リンクが含まれるHTMLファイルをアップロードするには、アップロードする前に関連するリンク先のHTMLも含め、zipファイルに圧縮の上、アップロードください。
Headers
Name | Type | Description |
---|---|---|
API-KEY* | string | 割り当てられたAPIキーです。プロジェクト設定メニュ→全般タブから確認できます。 |
AGENT-EMAIL | string | エージェントのEメールアドレスを指定することで、このAPI呼び出しを行うエージェントを特定できます。ここで指定するEメールアドレスは、ダッシュボードの [設定] > [エージェント] にて確認してください。 |
Request Body
Name | Type | Description |
---|---|---|
file* | string | アップロードするファイルがあるローカルの保存場所です。 |
hashtags | array | アップロードしたファイルに付与するハッシュタグです。 |
footerTitle | string | アップロードされたファイルからの検索結果のフッターとして、回答のソースを入力できます。フッターは、検索結果の [From] の横に表示されます。 |
footerUrl | string |
|
folder | string | ドキュメントのアップロード先のフォルダを割り当てることができます。 |
followFolderPermission | boolean | trueの場合(デフォルト)、ファイルへのアクセス権限はフォルダの権限設定に従います。falseの場合、ファイルは以下の2つのパラメータで定義された独自の権限設定を使用します。以下のパラメータが指定されていない場合、すべてのエージェントに対してファイルへの権限が与えられます。 |
agentsEditor | array | ファイルに編集者権限を持つエージェントを指定します。 |
agentsViewer | array | ファイルに閲覧者権限を持つエージェントを指定します。 |
userViewer | object | ファイルを閲覧する権限を持つユーザーを登録してください。customer_id、customer_groupを使用して登録することができます。customer_idはown-user-idと同じであり、customer_groupのid(categoryElementsId)はCUSTOMER GROUP inquiry APIを通じて取得できます。 |
allowOtherAgentsView | boolean | 閲覧者/編集者に含まれていないエージェントも閲覧することができます。 |
allowOtherUsersView | boolean | 閲覧者/編集者に含まれていないユーザーも閲覧することができます。 |
次の JSON 形式で結果を取得します。
Request Example
@"/location/to/your_file "にアップロードしたいファイルパスを記載ください。YOUR HASH TAGは付与したいハッシュタグに変更してください。
YOUR API KEYをプロジェクトのAPIキーに変更しなければなりません。APIキーの取得の項目をご参照ください。
Response Example
Upload Documents from S3
POST
https://backend-ja.alli.ai/webapi/upload_from_s3
このAPIを利用すると、S3に保存されているファイルをCognitive Searchで利用できるようにアップロードすることができます。これらはダッシュボードの[ナレッジベース]>[ドキュメント]タブに表示されます。アップロード可能なファイル形式は、Upload Documents APIと同じです。
Headers
Name | Type | Description |
---|---|---|
API-KEY* | string | プロジェクト設定メニュ→全般タブから確認できます。 |
AGENT-EMAIL | string | エージェントのEメールアドレスを指定することで、このAPI呼び出しを行うエージェントを特定できます。ここで指定するEメールアドレスは、ダッシュボードの [設定] > [エージェント] にて確認してください。 |
Request Body
Name | Type | Description |
---|---|---|
footerTitle | string | アップロードされたファイルからの検索結果のフッターとして、回答のソースを入力できます。フッターは、検索結果の [From] の横に表示されます。 |
footerUrl | string | アップロードされたファイルからの検索結果のフッターとして、回答のソースを入力できます。フッターは、検索結果の [From] の横に表示されます。 |
hashtags | string | アップロードしたファイルに付与するハッシュタグです。 |
path* | string | ファイルのS3におけるパス。ファイル名で終わる必要があります。バケット名を含めないでください |
secretKey | string | S3のシークレットキーです。 |
accessKey | string | S3のアクセスキーです。 |
bucket | string | ファイルを含むS3バケットの名前。 |
folder | string | ドキュメントのアップロード先のフォルダを割り当てることができます。 |
followFolderPermission | boolean | trueの場合(デフォルト)、ファイルへのアクセス権限はフォルダの権限設定に従います。falseの場合、ファイルは以下の2つのパラメータで定義された独自の権限設定を使用します。以下のパラメータが指定されていない場合、すべてのエージェントに対してファイルへの権限が与えられます。 |
agentsEditor | array | ファイルに編集者権限を持つエージェントを指定します。 |
agentsViewer | array | ファイルに閲覧者権限を持つエージェントを指定します。 |
userViewer | string | ファイルを閲覧する権限を持つユーザーを登録してください。customer_id、customer_groupを使用して登録することができます。customer_idはown-user-idと同じであり、customer_groupのid(categoryElementsId)はCUSTOMER GROUP inquiry APIを通じて取得できます。 |
allowOtherAgentsViewer | boolean | 閲覧者/編集者に含まれていないエージェントも閲覧することができます。 |
allowOtherUsersViewer | boolean | 閲覧者/編集者に含まれていないユーザーも閲覧することができます。 |
次の JSON 形式で結果を取得します。
id:アップロードしたファイルのIDです。
fileName: アップロードしたファイルのファイル名です。
hashtags: アップロードしたファイルに付与されるハッシュタグの配列です。
footer: アップロードされたファイルに追加されたフッター(ソース情報)。これはデフォルトのファイル名かfooterTitleとfooterUrlにより設定された内容となります。
folder: ドキュメントデータベースのフォルダから回答が見つかった場合、ここにフォルダ名が返されます。
editor: ドキュメントに編集権限を持つエージェントのメールアドレスのリストです。
viewer: ドキュメントに閲覧権限を持つエージェントのメールアドレスのリストです。
Request Example
YOUR API KEYをプロジェクトのAPIキーに変更しなければなりません。APIキーの取得の項目をご参照ください。
Response Example
Document処理ステータスの確認
GET
https://backend-ja.alli.ai/webapi/check_file_status
アップロードしたドキュメントは、変換および解析などの処理を行います。このAPIを使用すれば、アップロードしたドキュメントのステータスを確認することができます。
Headers
Name | Type | Description |
---|---|---|
API-KEY* | string | 割り当てられたAPIキーです。プロジェクト設定メニュ→全般タブから確認できます。 |
Request Body
Name | Type | Description |
---|---|---|
id* | string | 確認するドキュメントのIDです。 |
次の JSON 形式で結果を取得します。
id:チェックしたドキュメントのIDです。
status: アップロードしたドキュメントの状態です。可能な値については、以下の応答例をご覧ください。
Request Example
YOUR API KEYをプロジェクトのAPIキーに変更しなければなりません。APIキーの取得の項目をご参照ください。また、DOCUMENT_IDを該当するIDに変更しなければなりません。DocumentsのResponse Exampleの項目、Documents FeedbacksのResponse Exampleの項目をご参照ください。
Response Example
Statusは、以下のうち一つの値を持ちます。
Documentの削除
POST
https://backend-ja.alli.ai/webapi/delete_file
このAPIを使用すれば、アップロードしたドキュメントを削除することができます。複数のドキュメントを一括削除することもできます。
Headers
Name | Type | Description |
---|---|---|
API-KEY* | string | 割り当てられたAPIキーです。プロジェクト設定メニュ→全般タブから確認できます。 |
Request Body
Name | Type | Description |
---|---|---|
ids* | array | 削除するドキュメントIDの配列形式のリストです。 |
Result:削除に成功した場合はtrue、失敗した場合はfalseに表示されます。
errors:エラーメッセージが表示されます。
Request Example
YOUR API KEYをプロジェクトのAPIキーに変更しなければなりません。APIキーの取得の項目をご参照ください。また、DOCUMENT_IDを該当するIDに変更しなければなりません。DocumentsのResponse Exampleの項目、Documents FeedbacksのResponse Exampleの項目をご参照ください。
Response Example
Preview Documents
GET
https://backend-ja.alli.ai/webapi/knowledge_base_preview
このAPIを使用すると、アップロードされたドキュメントを参照できます。
Query Parameters
Name | Type | Description |
---|---|---|
id | string | 参照したいドキュメントのidを指定します。 |
pageNo | string | 参照したいドキュメントのページを指定します。 |
Headers
Name | Type | Description |
---|---|---|
API-KEY* | string | APIキーは、ダッシュボードの[設定]メニューの[全般]タブにあります。 |
次のJSON形式で結果を取得できます。
id: リストされたドキュメントのIDです。
fileName: リストされたドキュメントのファイル名です。
hashtags: ドキュメントに追加されたハッシュタグです。
autoHashtags: ドキュメントに自動生成されたハッシュタグです。
downloadUrl: ドキュメントをダウンロードするためのURLです。
footerUrl: ドキュメントのフッターに含まれるURLです。
folder: ドキュメントデータベースのフォルダから回答が見つかった場合、ここにはフォルダの名前が返されます。
editor: ドキュメントへの編集アクセス権を持つエージェントのメールアドレスのリストです。
viewer: ドキュメントへの閲覧アクセス権を持つエージェントのメールアドレスのリストです。
Request Example
YOUR API KEYをプロジェクトのAPIキーに変更しなければなりません。APIキーの取得の項目をご参照ください。また、DOCUMENT_IDを該当するIDに変更しなければなりません。DocumentsのResponse Exampleの項目、Documents FeedbacksのResponse Exampleの項目をご参照ください。
Response Example
エラーが発生した場合(存在しないページ番号など)、"result"内の"pdf"はnullとなりますので、ご注意ください。
List Documents
GET
https://backend-ja.alli.ai/webapi/knowledge_bases
このAPIを使用すると、アップロードされたドキュメントを一覧表示できます。
Query Parameters
Name | Type | Description |
---|---|---|
status | boolean | リストをフィルタリングするためのドキュメントのオン/オフステータス。 |
searchTerm | string | クエリを検索してリストをフィルタリングします。 |
hashtags | array | リストをフィルタリングするためのハッシュタグ情報。 |
order | string | リストの表示タイプ。 可能な表示タイプについては、以下のリクエスト例をご覧ください。 |
offset | integer | オフセットを使用すると、ページの最初のアイテムのランキング番号を指定できます。 |
limit | integer | limitを使用すると、1ページに返されるオブジェクトの数を設定できます。 最大値は100件です。 |
hashtagsSearchOperator | string | ANDとORは複数のハッシュタグをマッチさせるために使用する論理演算子です。デフォルトは OR です。 |
sortkey | string | これは、セカンダリソートキーとして使用されるドキュメントのカスタムプロパティキーです。プライマリソートはorderパラメータによって行われます。 |
sortDirection | string | これはセカンダリソートの順序です。値は「asc」または「desc」になります。 |
Headers
Name | Type | Description |
---|---|---|
API-KEY* | string | APIキーは、ダッシュボードの[設定]メニューの[全般]タブにあります。 |
次のJSON形式で結果を取得できます。
id: リストされたドキュメントのIDです。
fileName: リストされたドキュメントのファイル名です。
hashtags: ドキュメントに追加されたハッシュタグです。
autoHashtags: ドキュメントに自動生成されたハッシュタグです。
downloadUrl: ドキュメントのダウンロードURLです。
footerUrl: ドキュメントのフッターに含まれるURLです。
folder: ドキュメントデータベースのフォルダから回答が見つかった場合、ここにフォルダ名が返されます。
editor: ドキュメントに編集者権限を持つエージェントのメールアドレスのリストです。
viewer: ドキュメントに閲覧者権限を持つエージェントのメールアドレスのリストです。
count:条件に該当するドキュメントの総数です。
Request Example
YOUR API KEYを自身のプロジェクトのAPIキーに変更する必要があります。APIキーの取得をご参照ください。
次のいずれかの値をorderパラメーターに使用できます。
Value | Description |
SCORE | スコアによる降順でソートします。searchTermの値が存在する場合、これがデフォルトの値です。 |
FILE_NAME_ASC | ファイル名(昇順) |
FILE_NAME_DESC | ファイル名(降順) |
TYPE_ASC | ファイルタイプ(昇順) |
TYPE_DESC | ファイルタイプ(降順) |
STATUS_ASC | オン/オフステータス(昇順) |
STATUS_DESC | オン/オフステータス(降順) |
CREATED_AT_ASC | アップロード日時(昇順) |
CREATED_AT_DESC | アップロード日時(降順) |
Response Example
Document(Knowledge Base)Title Search
GET
https://backend-ja.alli.ai/webapi/search_document_by_title
このAPIを使用すると、タイトルに基づいてナレッジベースを検索することができます。この検索は、キーワードではなくトレーニングされたベクトルによって行われます。ナレッジベースの「ドキュメント」メニューでモデルをトレーニングしていることを確認してください。
Query Parameters
Name | Type | Description |
---|---|---|
hashtags | array | リストをフィルタリングするためのハッシュタグです。これらのハッシュタグを持つドキュメントのみが検索対象となります。複数のハッシュタグをカンマで区切って追加することができます。 |
hashtagsOperator | string | andまたはorです。andの場合、複数のハッシュタグのフィルタはANDロジックで動作します。orの場合、ORロジックが適用されます。 |
excludingHashtags | array | リストをフィルタリングするためのハッシュタグです。これらのハッシュタグを持たないドキュメントのみが検索対象となります。複数のハッシュタグをカンマで区切って追加することができます。 |
excludingHashtagsOperator | string | andまたはorです。andの場合、複数のハッシュタグを指定した'excludingHashtags'フィルターはANDロジックで動作します。orの場合はORロジックが適用されます。 |
offset | integer | オフセットを使用すると、ページの最初のアイテムのランキング番号を指定できます。 |
limit | integer | limitを使用すると、1ページに返されるオブジェクトの数を設定できます。 最大値は100件です。 |
query* | string | 検索クエリ |
sortkey | string | これは、セカンダリソートキーとして使用されるドキュメントのカスタムプロパティキーです。プライマリソートはorderパラメータによって行われます。 |
sortDirection | string | これはセカンダリソートの順序です。値は「asc」または「desc」になります。 |
order | string | List Documents APIの順序についてご確認ください。デフォルトでは、スコアに基づいて降順で表示されます。 |
useVector | boolean | true / falseまたは省略することができます。デフォルトは省略です。 trueの場合、ドキュメントタイトルの訓練済みベクトルのみを使用して結果を返します。 falseの場合、キーワードベースの検索のみを使用して結果を返します。 このパラメータを省略した場合、結果はベクトルとキーワード検索の組み合わせとなります。 |
Headers
Name | Type | Description |
---|---|---|
API-KEY* | string | APIキーは、ダッシュボードの[設定]メニューの[全般]タブにあります。 |
次のJSON形式で結果を取得できます。
id: ドキュメントのIDです。
fileName: ドキュメントのファイル名です。
hashtags: ドキュメントに追加されたハッシュタグです。
score: 検索結果の信頼度スコアです。
folder: ドキュメントデータベースのフォルダー内から回答が見つかった場合、ここにフォルダー名が返されます。
editor: ドキュメントに編集アクセス権限を持つエージェントのメールアドレスのリストです。
viewer: ドキュメントに閲覧アクセス権限を持つエージェントのメールアドレスのリストです。
Request Example
YOUR API KEYを自身のプロジェクトのAPIキーに変更する必要があります。APIキーの取得をご参照ください。
Response Example
Rename Documents (Knowledge Base)
POST
https://backend-ja.alli.ai/webapi/update_kb_name
この API を使用することで、アップロードされたドキュメントの名前を更新できます。
また、DOCUMENT_IDを該当するIDに変更しなければなりません。DocumentsのResponse Exampleの項目、Documents FeedbacksのResponse Exampleの項目をご参照ください。
Headers
Name | Type | Description |
---|---|---|
API-KEY* | string | 割り当てられたAPIキーです。プロジェクト設定メニュ→全般タブから確認できます。 |
Request Body
Name | Type | Description |
---|---|---|
filename* | string | ドキュメントの新しい名前 |
id* | string | 名前を変更するドキュメントのid |
次のJSON形式で結果を取得できます。
id: ファイル名が変更されたドキュメントのIDです。
filename: ドキュメントの新しいファイル名です。
Request Example
YOUR API KEYを自身のプロジェクトのAPIキーに変更する必要があります。APIキーの取得をご参照ください。
Response Example
Update Documents
POST
https://backend-ja.alli.ai/webapi/update_document
このAPIを利用することで、ドキュメントのハッシュタグ、フッタータイトル、およびフッタータイトルのリンクを更新することができます。
Headers
Name | Type | Description |
---|---|---|
API-KEY* | string | 割り当てられたAPIキーです。プロジェクト設定メニュ→全般タブから確認できます。 |
Request Body
Name | Type | Description |
---|---|---|
footerTitle | string | アップロードされたファイルからの検索結果のフッターとして、回答のソースを入力できます。フッターは、検索結果の [From] の横に表示されます。 |
footerUrl | string |
|
folder | string | ドキュメントのアップロード先のフォルダを割り当てることができます。 |
followFolderPermission | boolean | trueの場合(デフォルト)、ファイルへのアクセス権限はフォルダの権限設定に従います。falseの場合、ファイルは以下の2つのパラメータで定義された独自の権限設定を使用します。以下のパラメータが指定されていない場合、すべてのエージェントに対してファイルへの権限が与えられます。 |
agentsEditor | array | ファイルに編集者権限を持つエージェントを指定します。 |
agentsViewer | array | ファイルに閲覧者権限を持つエージェントを指定します。 |
userViewer | object | ファイルを閲覧する権限を持つユーザーを登録してください。customer_id、customer_groupを使用して登録することができます。customer_idはown-user-idと同じであり、customer_groupのid(categoryElementsId)はCUSTOMER GROUP inquiry APIを通じて取得できます。 |
allowOtherAgentsView | boolean | 閲覧者/編集者に含まれていないエージェントも閲覧することができます。 |
allowOtherUsersView | boolean | 閲覧者/編集者に含まれていないユーザーも閲覧することができます。 |
hashtags | array | ドキュメントに追加したいハッシュタグの文字列のリストです。 |
id* | string | 更新したいドキュメントのIDです。 |
properties | json | このドキュメントのカスタムプロパティのキーと値のペアです。これらのプロパティは、「ドキュメントから検索」のソート基準として使用することができます。 |
次の JSON 形式で結果を取得します。
id: ハッシュタグが対応するドキュメントのIDです。
hashtags: 更新後のドキュメントに添付されたハッシュタグです。
footer: アップロードされたドキュメントに追加されたフッター(ソース)情報です。デフォルトの情報またはfooterTitleおよびfooterUrlパラメータで指定された情報が含まれます。
folder: ドキュメントデータベースのフォルダから回答が見つかった場合、ここにフォルダ名が返されます。
editor: ドキュメントに編集アクセス権を持つエージェントのメールアドレスのリストです。
viewer: ドキュメントに閲覧アクセス権を持つエージェントのメールアドレスのリストです。
Request Example
YOUR API KEYをプロジェクトのAPIキーに変更しなければなりません。APIキーの取得の項目をご参照ください。また、DOCUMENT_IDを該当するIDに変更しなければなりません。DocumentsのResponse Exampleの項目、Documents FeedbacksのResponse Exampleの項目をご参照ください。
Response Example
Create/Read/Update/Delete Custom Properties
Create Custom Properties
ドキュメントにカスタムプロパティを作成する場合は、propertiesパラメータを使用してください。
その後、以下のようなレスポンスを受け取ります。
Get Custom Properties
特定のドキュメントのカスタムプロパティのリストを取得したい場合は、「Get Single Document」APIを使用することができます。
Update Customer Properties
ドキュメントのカスタムプロパティを更新したい場合は、単純にプロパティの値を更新してください。既存のキーを送信しない場合、そのプロパティは削除されますのでご注意ください。
その後、以下のようなレスポンスを受け取ります。
Delete Custom Properties
ドキュメントのカスタムプロパティをすべてまたは一部削除したい場合は、特定のプロパティに null 値を渡すことができます。
その後、以下のようなレスポンスを受け取ります。
Knowledge Base Toggle Status
POST
https://backend-ja.alli.ai/webapi/toggle_documents
この API を使用することで、多くのドキュメントのステータスを一度に変更できます。
Headers
Name | Type | Description |
---|---|---|
API-KEY* | string | 割り当てられたAPIキーです。プロジェクト設定メニュ→全般タブから確認できます。 |
Request Body
次の JSON 形式で結果を取得します。
KnowledgeBases : ステータスが切り替えられたドキュメントのリスト
id: ナレッジベースのID
status: ナレッジベースの新しいステータス (ブール値) true はステータスがオンになっていることを意味します。
Request Example
YOUR API KEYを自身のプロジェクトのAPIキーに変更する必要があります。APIキーの取得をご参照ください。
Response Example
Knowledge Base Auto Hashtag (Classification)
POST
https://backend-ja.alli.ai/webapi/kb_auto_hashtag
このAPIを使用すると、ドキュメントの分類キーワードを含むハッシュタグリストを取得できます。
Headers
Name | Type | Description |
---|---|---|
API-KEY* | string | APIキーは、ダッシュボードの[設定]メニューの[全般]タブにあります。 |
Request Body
Name | Type | Description |
---|---|---|
ids* | array | 自動ハッシュタグを取得するドキュメントID |
次のJSON形式で結果が取得できます。
updated:
id : ハッシュタグに対応するドキュメントのID。
autoHashtags: Documentに対して自動生成されたハッシュタグのリストを含むJSONオブジェクトの配列。
state: エージェントが自動生成されたハッシュタグを確認したかどうかによる、ハッシュタグの状態。 以下のいずれか:"SUGGESTED", "APPROVED", "DECLINED".
bestConfidence:この自動生成ハッシュタグの信頼度を0から1の数値で表す。
autohashtag:
id: ハッシュタグのID
hashtag: ハッシュタグの文字列値(ダッシュボードに表示される)
Request Example
YOUR API KEYをプロジェクトのAPIキーに変更しなければなりません。APIキーの取得の項目をご参照ください。また、DOCUMENT_IDを該当するIDに変更しなければなりません。DocumentsのResponse Exampleの項目、Documents FeedbacksのResponse Exampleの項目をご参照ください。
Response Example
Knowledge Base Auto Hashtag Feedback (Classification)
POST
https://backend-ja.alli.ai/webapi/kb_auto_hashtag_feedback
このAPIを使用すると、ドキュメントの分類キーワードを含むハッシュタグリストを取得できます。
Headers
Name | Type | Description |
---|---|---|
API-KEY* | string | APIキーは、ダッシュボードの[設定]メニューの[全般]タブにあります。 |
Request Body
Name | Type | Description |
---|---|---|
autoHashtagFeedbacks* | array | ハッシュタグのIDと状態を含むJSONオブジェクトのリストです。 'state'は次のいずれかの値を取ります: 'accepted'(承認済み)、'declined'(拒否済み)、'suggested'(提案済み) |
次のJSON形式で結果が取得できます。
result: JSONオブジェクトの配列で、それぞれが自動ハッシュタグに対応します。
id: ハッシュタグのID
state: エージェントからのハッシュタグのフィードバック。"suggested"(提案済み)または"declined"(拒否済み)のいずれかになります。
Request Example
YOUR API KEYをプロジェクトのAPIキーに変更しなければなりません。APIキーの取得の項目をご参照ください。ハッシュタグIDに応じて置き換えてください。ハッシュタグIDの取得については、「ナレッジベースの自動ハッシュタグ(分類)」セクションをご覧ください。
Response Example
Select Answer
POST
https://backend-ja.alli.ai /webapi/faq/select_answer
このAPIを利用することで、特定のQ&Aを顧客が選択したものとして処理することができます。
Path Parameters
Name | Type | Description |
---|---|---|
API-KEY* | string | 割り当てられたAPIキーです。プロジェクト設定メニュ→全般タブから確認できます。 |
Request Body
次のJSON形式で結果が得られます。下記は成功の場合です。
Request Example
YOUR API KEYをプロジェクトのAPIキーに変更しなければなりません。APIキーの取得の項目をご参照ください。 また、id(FAQ ID)も変更しなければなりません。 FAQ IDの取得については、Search from Q&Aを確認してください。
Response Example
Agent Management
POST
https://backend-ja.alli.ai/webapi/agent_management
このAPIを使用するとプロジェクトからエージェントを作成および削除することが可能です。 登録されるエージェントの権限は「エージェント」権限となります。
Headers
Name | Type | Description |
---|---|---|
API-KEY* | string | 割り当てられたAPIキーです。プロジェクト設定メニュ→全般タブから確認できます。 |
Request Body
id: 削除/作成されたエージェントのIDです。
status: 「登録」か「削除」かの結果を示します。
Request Example
YOUR API KEYをプロジェクトのAPIキーに変更しなければなりません。APIキーの取得の項目をご参照ください。
Response Example
Get All hashtags
GET
https://backend-ja.alli.ai/webapi/hashtags
このAPIを利用するとFAQとMRCの両方からすべてのハッシュタグを取得することが可能です。
Headers
使用回数とともに各ハッシュタグを返します。
Request Example
YOUR API KEYをプロジェクトのAPIキーに変更しなければなりません。APIキーの取得の項目をご参照ください。
Response Example
Q&A Query History
GET
https://backend-ja.alli.ai/webapi/faq_histories
REST APIとAlliダッシュボードの両方を介して行われた過去のQ&A検索を返します。
Query Parameters
Name | Type | Description |
---|---|---|
limit | integer | 表示する結果の数です。 (ページネーションに利用) |
offset | integer | 結果のリストで、結果のリストを開始するインデックスです。 (ページネーションに利用) |
endDate | string | 検索履歴を取得する期間の終わりの日付です。 (日付はYYYY-MM-DDの形式である必要があります) |
startDate | string | 検索履歴を取得する期間の始まりの日付です。 (日付はYYYY-MM-DDの形式である必要があります) |
order | string | 検索結果の並び順を指定できます。 DESC(最新のクエリが最初に来ることを意味する)またはASC(最も早いクエリが最初に来ることを意味する)のいずれかで並び順を指定できます。 |
searchTerm | string | 検索語句による結果の絞り込みを行うことができま |
Headers
Name | Type | Description |
---|---|---|
API-KEY* | string | 割り当てられたAPIキーです。プロジェクト設定メニュ→全般タブから確認できます。 |
AGENT-EMAIL | string | エージェントのメール アドレスを指定することで、この API 呼び出しを行うエージェントを特定できます。ここで指定するEメールアドレスは、ダッシュボードの [設定] > [エージェント] にて確認してください。 |
OWN-USER-ID | string | ユーザーの ID を指定することで、この API 呼び出しを行うユーザーを特定できます。ここで指定するIDは、ダッシュボードの [顧客リスト]>[CUSTOMER_ID] もしくは[会話履歴]>[対話情報]にて確認できます。 |
検索結果についてはそれぞれ下記の情報を保有しています。
agent: クエリを実行したエージェントのidです。
question: クエリで実際にされた質問内容です。
answers: クエリに対して提供されるすべての回答です。各回答には、参照されたQ&Aのid、confidence,、effective confidenceが含まれます。
count:表示したクエリの数が返されます。
Request Example
Response Example
Documents Query History
GET
https://backend-ja.alli.ai/webapi/mrc_histories
REST APIとAlliダッシュボードの両方を介して行われた過去のドキュメント検索を返します。
Query Parameters
Name | Type | Description |
---|---|---|
limit | integer | 表示する結果の数です。 (ページネーションに利用) |
offset | integer | 結果のリストで、結果のリストを開始するインデックスです。 (ページネーションに利用) |
endDate | string | 検索履歴を取得する期間の終わりの日付です。 (日付はYYYY-MM-DDの形式である必要があります) |
startDate | string | 検索履歴を取得する期間の始まりの日付です。 (日付はYYYY-MM-DDの形式である必要があります) |
order | string | 検索結果の並び順を指定できます。 DESC(最新のクエリが最初に来ることを意味する)またはASC(最も早いクエリが最初に来ることを意味する)のいずれかで並び順を指定できます。 |
searchTerm | string | 検索語句による結果の絞り込みを行うことができま |
Headers
Name | Type | Description |
---|---|---|
API-KEY* | string | 割り当てられたAPIキーです。プロジェクト設定メニュ→全般タブから確認できます。 |
AGENT-EMAIL | string | エージェントのメール アドレスを指定することで、この API 呼び出しを行うエージェントを特定できます。ここで指定するEメールアドレスは、ダッシュボードの [設定] > [エージェント] にて確認してください。 |
OWN-USER-ID | string | ユーザーの ID を指定することで、この API 呼び出しを行うユーザーを特定できます。ここで指定するIDは、ダッシュボードの [顧客リスト]>[CUSTOMER_ID] もしくは[会話履歴]>[対話情報]にて確認できます。 |
検索結果についてはそれぞれ下記の情報を保有しています。
agent: クエリを実行したエージェントのidです。
question: クエリで実際にされた質問内容です。
answers: クエリに対して提供されるすべての回答です。各回答には、その回答の参照先として使用されるknowledgeBase(filenameとid)、実際のanswer、answerFormat、ナレッジベースに関連付けられたhashtags、および回答に対してのfeedbackAvailableが含まれます。
カウントフィールドに表示したクエリの数が返されます。
Request Example
Response Example
View User Information
GET
https://backend-ja.alli.ai/webapi/users
このAPIを利用すると、ユーザーのOWN-USER-ID、CUSTOMER GROUP、およびメールアドレスが確認できます。
Query Parameters
Name | Type | Description |
---|---|---|
customar_group | string | ユーザーを検索する際にフィルタリングするためのCUSTOMER GROUPの名前です。CUSTOMER GROUPのquery APIコールを使用してこの値を取得することができます。 |
offset | integer | ページ上で表示される最初のアイテムの位置を決定します。デフォルトは0です。 |
limit | string | 1ページに表示するアイテムの数を決定します。デフォルトは10で、最大値は1000です。 |
Headers
Name | Type | Description |
---|---|---|
API-KEY* | string | 割り当てられたAPIキーです。プロジェクト設定メニュ→全般タブから確認できます。 |
下記のJSON形式で結果が得られます。
Request Example
Response Example
View Individual User Information
GET
https://backend-ja.alli.ai/webapi/user/{OWN-USER-ID}
このAPIを利用すると、ユーザーのOWN-USER-ID、CUSTOMER GROUP、およびメールアドレスが確認できます。
Query Parameters
Name | Type | Description |
---|---|---|
OWN-USER-ID* | string | ユーザーのIDです。ユーザー情報を取得するAPIを使用して、すべてのユーザーのIDを取得することができます。 |
Headers
Name | Type | Description |
---|---|---|
API-KEY* | string | 割り当てられたAPIキーです。プロジェクト設定メニュ→全般タブから確認できます。 |
下記のJSON形式で結果が得られます。
Request Example
{OWN-USER-ID}を自分のユーザーIDで置き換えてください。ユーザー情報を取得するAPIを使用して、すべてのユーザーのIDを取得することができます。
Response Example
Update User Information
POST
https://backend-ja.alli.ai/webapi/user/{OWN-USER-ID}/customer_variables/{variableName}
このAPIを利用すると、個々のユーザーのOWN-USER-ID、CUSTOMER GROUPが更新できます。
Query Parameters
Name | Type | Description |
---|---|---|
OWN-USER-ID* | string | ユーザーのIDです。ユーザー情報を取得するAPIを使用して、すべてのユーザーのIDを取得することができます。 |
VariableName* | String | 更新したい内容です。'CUSTOMER_GROUP'または 'CUSTOMER_ID'のいずれかを入力できます。
|
Headers
Name | Type | Description |
---|---|---|
API-KEY* | string | 割り当てられたAPIキーです。プロジェクト設定メニュ→全般タブから確認できます。 |
Request Body
Name | Type | Description |
---|---|---|
id* | string | 変更する 'CUSTOMER_GROUP' または 'CUSTOMER_ID' の ID です。 |
下記のJSON形式で結果が得られます。
Request Example
{variableName} と {id} を該当する値で置き換えてください。{variableName} には更新したい項目 ("CUSTOMER_GROUP" または "CUSTOMER_ID") を入力し、{id} には変更したい ID の値を入力してください。必要な ID は、ユーザー情報を取得するための API を使用して確認できます。
Response Example
CUSTOMER GROUP Query
GET
https://backend-ja.alli.ai/webapi/customer_variable/{variableName}/customer_group/category_elements
登録されたCUSTOMER GROUPを確認するには、CUSTOMER GROUPのリストを取得するAPIを使用してください。
Headers
Name | Type | Description |
---|---|---|
API-KEY* | string | 割り当てられたAPIキーです。プロジェクト設定メニュ→全般タブから確認できます。 |
下記のJSON形式で結果が得られます。
Request Example
Reaponse Example
Create CUSTOMER GROUP
POST
https://backend-ja.alli.ai/webapi/customer_variable/{variableName}/customer_group/category_element
このAPIを利用すると、CUSTOMER GROUPを作成出来ます。
Headers
Name | Type | Description |
---|---|---|
API-KEY* | string | 割り当てられたAPIキーです。プロジェクト設定メニュ→全般タブから確認できます。 |
Request Body
Name | Type | Description |
---|---|---|
value* | string | 追加するCUSTOMER GROUPの名前です。 |
下記のJSON形式で結果が得られます。
Request Example{variableName}
Response Example
Update CUSTOMER GROUP
POST
https://backend-ja.alli.ai/webapi/customer_variable/{variableName}/category_element/{categoryElementId}
このAPIを利用すると、CUSTOMER GROUPを更新出来ます。
Path Parameters
Name | Type | Description |
---|---|---|
categoryElementId* | string | 更新したいCUSTOMER GROUPのIDです。CUSTOMER GROUPクエリAPIを使用して取得することができます。 |
Headers
Name | Type | Description |
---|---|---|
API-KEY* | string | 割り当てられたAPIキーです。プロジェクト設定メニュ→全般タブから確認できます。 |
Request Body
Name | Type | Description |
---|---|---|
value* | string | 更新するCUSTOMER GROUPの名前です。 |
下記のJSON形式で結果が得られます。
Request Example
{categoryElementId}をご自身のCUSTOMER GROUPのIDで置き換えてください。CUSTOMER GROUPクエリAPIを使用して取得することができます。
Response Example
Delete CUSTOMER GROUP
DELETE
https://backend-ja.alli.ai/webapi/customer_variable/{variableName}/category_element/{categoryElementId}
このAPIを利用すると、CUSTOMER GROUPを更新出来ます。
Path Parameters
Name | Type | Description |
---|---|---|
categoryElementId* | string | 更新したいCUSTOMER GROUPのIDです。CUSTOMER GROUPクエリAPIを使用して取得することができます。 |
Headers
Name | Type | Description |
---|---|---|
API-KEY* | string | 割り当てられたAPIキーです。プロジェクト設定メニュ→全般タブから確認できます。 |
下記のJSON形式で結果が得られます。
Request Example
{categoryElementId}をご自身のCUSTOMER GROUPのIDで置き換えてください。CUSTOMER GROUPクエリAPIを使用して取得することができます。
Response Example
API Classifications
請求目的のAPI分類とマッピングを表示します。
こちらからExcelファイルをダウンロードしてください。
Last updated