Alli Conversational API

AIアンサーボット”Alliを利用すれば、顧客がパーソナライズされた対話の経験を通してナレッジベースから必要な知識を簡単にナビゲートすることができ、これにより、ウェブ、モバイル環境を選ばず、チームの業務効率を最大化することができます。

エンドポイントに関して

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

Start Conversation

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

スキルを使用して会話を開始します。 ※2024/4/22 現在、このエンドポイントは、会話応答ノード・Q＆Aノード・MRCノード・回答自動生成ノードのみ互換性があります。

Headers

Name	Type	Description
API-KEY	string	APIキーは、ダッシュボードの[プロジェクト設定]メニューの[全般]タブで確認することが可能です。
OWN-USER-ID	string	会話を開始したユーザーのIDです。

Request Body

Name	Type	Description
placement	string	どのスキルで会話を開始するかをを照合するために使用します。

200

次のJSON形式で結果を取得できます。

id: 開始された会話のユニークID。

nluLanguage: Alliプロジェクトの言語。

edges: 会話内のメッセージを表す各JSONオブジェクトの配列です。

message: ユーザーにAlliが表示するテキストメッセージです。これはDraftjs形式です。

createdAt:このメッセージが送信されたタイムスタンプ。

chatOptionsInfos: ユーザーにAlliが表示するクリック可能なボタンを表す各JSONオブジェクトの配列です。

shortenOption,longOption: ボタンのテキストコンテンツです。

style:ボタンのスタイル情報です。

{
    "result": {
        "conversation": {
            "id": "CONVERSATION_ID",
            "project": {
                "nluLanguage": "LANGUAGE"
            },
            "chats": {
                "edges": [
                    {
                        "node": {
                            "id": "CHAT_ID",
                            "message": "MESSAGE",
                            "createdAt": NUMBER,
                            "chatOptionInfos": [
                                {
                                    "shortenOption": "BUTTON_TEXT",
                                    "longOption": "BUTTON_TEXT",
                                    "style": {
                                        "bgColor": "COLOR_HEX",
                                        "bold": BOOLEAN,
                                        "fontColor": "COLOR_HEX",
                                        "italic": BOOLEAN,
                                        "lineColor": "COLOR_HEX",
                                        "underline": BOOLEAN
                                    },
                                    "meta": ""
                                },
                                {
                                    "shortenOption": "BUTTON_TEXT",
                                    "longOption": "BUTTON_TEXT",
                                    "style": {
                                        "bgColor": "COLOR_HEX",
                                        "bold": BOOLEAN,
                                        "fontColor": "COLOR_HEX",
                                        "italic": BOOLEAN,
                                        "lineColor": "COLOR_HEX",
                                        "underline": BOOLEAN
                                    },
                                    "meta": ""
                                }
                            ],
                            "isDeleted": BOOLEAN
                        }
                    }
                ]
            }
        }
    },
    "errors": null
}

Request Example

YOUR API KEYを自身のプロジェクトのAPIキーに変更する必要があります。APIキーの取得をご参照ください。

curl -L -X POST 'https://backend-ja.alli.ai/webapi/start_conversation' \
-H 'API-KEY: YOUR_API_KEY' \
-H 'OWN-USER-ID: test_userid' \
-H 'Content-Type: application/json' \
--data-raw '{"placement": "skill_A"}'

Response Example

{
    "result": {
        "conversation": {
            "id": "Q29udmVyc2F0aW9uOjYwMDZiNTM3MmRhPHAwMjZlOTFjMjllZQ==",
            "project": {
                "nluLanguage": "EN"
            },
            "chats": {
                "edges": [
                    {
                        "node": {
                            "id": "Q2hhdDo2MDQ2YjUzNzJkYWQwMDI2ZTkxYzI5ZDE=",
                            "message": "{\"blocks\": [{\"key\": \"egkjj\", \"text\": \"Please select an option\", \"type\": \"unstyled\", \"depth\": 0, \"inlineStyleRanges\": [], \"entityRanges\": [], \"data\": {}}], \"entityMap\": {}}",
                            "createdAt": 1615246647609.666,
                            "chatOptionInfos": [
                                {
                                    "shortenOption": "FAQ",
                                    "longOption": "FAQ",
                                    "style": {
                                        "bgColor": "#FFFFFF",
                                        "bold": false,
                                        "fontColor": "#2074ff",
                                        "italic": false,
                                        "lineColor": "#2074ff",
                                        "underline": false
                                    },
                                    "meta": ""
                                },
                                {
                                    "shortenOption": "Document",
                                    "longOption": "Document",
                                    "style": {
                                        "bgColor": "#FFFFFF",
                                        "bold": false,
                                        "fontColor": "#2074ff",
                                        "italic": false,
                                        "lineColor": "#2074ff",
                                        "underline": false
                                    },
                                    "meta": ""
                                }
                            ],
                            "isDeleted": false
                        }
                    }
                ]
            }
        }
    },
    "errors": null
}

End conversation by agent

POST https://backend-ja.alli.ai/end_conversation_by_agent

Headers

Name	Type	Description
API-KEY	string	APIキーは、ダッシュボードの[プロジェクト設定]メニューの[全般]タブにあります。

Request Body

Name	Type	Description
id	string	会話ID

Request Example

curl -L -X POST 'https://backend-ja.alli.ai/webapi/end_conversation_by_agent' \
-H 'api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data-raw '{"id": "Q29udmVyc2F0aW9uOjYxYTcwMzAxMjYzZWM2NmI2MDY0NzVjOQ=="}'

Response Example

{
   "result":{
      "conversation":{
         "id":"Q29udmVyc2F0aW9uOjYxYTcwMzAxMjYzZWM2NmI2MDY0NzVjOQ==",
         "completedTime":1639093180790.565,
         "state":"END_BY_AGENT",
         "__typename":"Conversation"
      },
      "__typename":"UpdateConversationState"
   },
   "errors":null
}

Send Chat

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

ここでは、会話情報を提供します。 ※2024/4/22 現在、このエンドポイントは、会話応答ノード・Q＆Aノード・MRCノード・回答自動生成ノードのみ互換性があります。

Headers

Name	Type	Description
API-KEY*	string	APIキーは、ダッシュボードの[プロジェクト設定]メニューの[全般]タブにあります。

Request Body

Name	Type	Description
message	string	送信する会話を入力します。nullまたは空白の文字列にすることはできません。
conversationid	string	送信する一意の会話IDを入力します。

200

次のJSON形式で結果を取得できます。

responses: メッセージを表す各JSONオブジェクトの配列です。最初のメッセージオブジェクトはリクエストのメッセージになります。

message: Alliによってユーザーに表示されるテキストメッセージです。スキルビルダーのノードで設定されたテキストメッセージはDraftjs形式で表示されます。

createdAt: このメッセージが作成されたタイムスタンプです。

chatOptionInfos: ユーザーに表示されるAlliが表示するクリッカブルボタンを表す各JSONオブジェクトの配列です。

shortenOption, longOption: ボタンのテキストコンテンツです。

style: ボタンのスタイル情報です。

{
    "result": {
        "responses": [
            {
                "id": "CHAT_ID",
                "message": "MESSAGE",
                "createdAt": NUMBER,
                "isDeleted": BOOLEAN
            },
            {
                "id": "CHAT_ID",
                "message": "MESSAGE",
                "createdAt": NUMBER,
                "chatOptionInfos": [
                    {
                        "shortenOption": "BUTTON_TEXT",
                        "longOption": "BUTTON_TEXT",
                        "style": {
                            "bgColor": "COLOR_HEX",
                            "bold": BOOLEAN,
                            "fontColor": "COLOR_HEX",
                            "italic": BOOLEAN,
                            "lineColor": "COLOR_HEX",
                            "underline": BOOLEAN
                        },
                        "meta": ""
                    }
                ],
                "isDeleted": BOOLEAN
            }
        ],
        "state": "WAIT_USER_ANSWER_2"
    },
    "errors": null
}

Request Example

YOUR API KEYを自身のプロジェクトのAPIキーに変更する必要があります。APIキーの取得をご参照ください。

curl -L -X POST 'https://backend-ja.alli.ai/webapi/send_chat' \
-H 'api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data-raw '{"conversationId": "Q29udmVyc2F0aW9uOjYwNDZiNWNkZTZkZGQ5MGE3ZWJlMGYxZQ==", "message": "I need help!"}'

Response Example

{
    "result": {
        "responses": [
            {
                "id": "Q2hhdDo2MDQ2YjVlY2U2ZGRkOTBhN2ViZTBmNTU=",
                "message": "I need help!",
                "createdAt": 1615246828077.0,
                "isDeleted": false
            },
            {
                "id": "Q2hhdDo2MDQ2YjVlY2U2ZGRkOTBhN2ViZTBmNTc=",
                "message": "{\"blocks\": [{\"key\": \"6so0p\", \"text\": \"Please input your question\", \"type\": \"unstyled\", \"depth\": 0, \"inlineStyleRanges\": [], \"entityRanges\": [], \"data\": {}}], \"entityMap\": {}}",
                "createdAt": 1615246828110.0,
                "chatOptionInfos": [],
                "isDeleted": false
            }
        ],
        "state": "WAIT_USER_ANSWER_2"
    },
    "errors": null
}

Summary Analytics

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

ここでは、Alliの統計情報に関するサマリーを提供します。

Headers

Name	Type	Description
API-KEY	string	APIキーは、ダッシュボードの[プロジェクト設定]メニューの[全般]タブにあります。

Request Body

Name	Type	Description
startDate	string	照会期間の開始日をYYYY-MM-DDの形式で入力します。
endDate	string	照会期間の終了日をYYYY-MM-DDの形式で入力します。

200

次のJSON形式で結果を取得できます。

conversations: 日付範囲内で行われた会話の数。

conversationsUpDown:問い合わせた日数について、直前の日数からの会話数の変化率。

participants: Alliと会話をしたユーザーの日毎のユニークカウントの合計。

participantsUpDown:問い合わせた日数について、直前の日数からのユーザー数の合計の変化率。

uniqueParticipants: 日付範囲内でAlliと会話をしたユーザーのユニークカウント。

uniqueParticipantsUpDown: 問い合わせた日数について、直前の日数からのユニーク参加者数の変化率。

queries:FAQやMRCドキュメントに対するユーザーからの質問の総数。これには、「FAQで回答」ノード、 「MRCで回答」ノード、およびAlliダッシュボードからの質問が含まれる。

queriesUpDown:問い合わせた日数について、直前の日数からの総クエリ数の変化率。

queriedUsers: FAQやMRCドキュメントに対して少なくとも1回質問したユーザーの日毎のユニークカウントの合計。

queriedUsersUpDown: 問い合わせた日数について、直前の日数からの問い合わせユーザー数の変化率。

uniqueQueriedUsers: FAQやMRCドキュメントに対して少なくとも1回質問したユーザーのユニークカウント。

uniqueQueriedUsersUpDown:問い合わせた日数について、直前の日数からのユニーク問い合わせユーザー数の変化率。

instantResolution: FAQノードからの質問に対して顧客が選択した回答の数。

instantResolutionUpDown: 問い合わせた日数について、直前の日数からの即時解決数の変化率。

aiResponseRate: FAQノードからの質問数に対する「AIによる自動応答率」

aiResponseRateUpDown:問い合わせた日数について、直前の日数からのAI応答率の変化率。

uniqueVisitors: Alli SDKが統合されたWebページへの訪問者のユニークカウント。この数値は請求計算のための「アクセスユニークユーザー数」です。

uniqueVisitorsUpDown: 問い合わせた日数について、直前の日数からのユニーク訪問者数の変化率。

totalFaqs: 登録されたFAQの数。

totalFaqsUpDown: 問い合わせた日数について、直前の日数からの総FAQ数の変化率。

totalDocuments: アップロードされたドキュメントの数。

totalDocumentsUpDown: 問い合わせた日数について、直前の日数からの総ドキュメント数の変化率。

{
    "result": {
        "conversations": CONVERSATIONS,
        "conversationsUpDown": CONVERSTAIONS_UPDOWN,
        "participants": PARTICIPANTS,
        "participantsUpDown": PARTICIPANTS_UPDOWN,
        "uniqueParticipants": UNIQUE_PARTICIPANTS,
        "uniqueParticipantsUpDown": UNIQUE_PARTICIPANTS_UPDOWN,
        "queries": QUERIES,
        "queriesUpDown": QUERIES_UPDOWN,
        "queriedUsers": QUERIED_USERS,
        "queriedUsersUpDown": QUERIED_USERS_UPDOWN,
        "uniqueQueriedUsers": UNIQUE_QUERIED_USERS,
        "uniqueQueriedUsersUpDown": UNIQUE_QUERIED_USERS_UPDOWN,
        "instantResolution": INSTANT_RESOLUTION,
        "instantResolutionUpDown": INSTANT_RESOLUTION_UPDOWN,
        "aiResponseRate": AI_RESPONSE_RATE,
        "aiResponseRateUpDown": AI_RESPONSE_RATE_UPDOWN,
        "uniqueVisitors": UNIQUE_VISITORS,
        "uniqueVisitorsUpDown": UNIQUE_VISITORS_UPDOWN,
        "totalFaqs": TOTAL_FAQS,
        "totalFaqsUpDown": TOTAL_FAQS_UPDOWN,
        "totalDocuments": TOTAL_DOCUMENTS,
        "totalDocumentsUpDown": TOTAL_DOCUMENTS_UPDOWN,
        "feedbacksUpDown": FEEDBACKS_UPDOWN
    },
    "errors": null
}

Request Example

YOUR API KEYを自身のプロジェクトのAPIキーに変更する必要があります。APIキーの取得をご参照ください。

curl -X GET -d '{ "startDate": "2020-11-14",
"endDate": "2020-12-14"}' \
-H 'API-KEY: YOUR_API_KEY' \
https://backend-ja.alli.ai/webapi/summary_analytics

Response Example

{
    "result": {
        "conversations": 45,
        "conversationsUpDown": -45.78,
        "participants": 44,
        "participantsUpDown": -32.31,
        "uniqueParticipants": 43,
        "uniqueParticipantsUpDown": -31.75,
        "queries": 39,
        "queriesUpDown": -56.18,
        "queriedUsers": 35,
        "queriedUsersUpDown": -46.97,
        "uniqueQueriedUsers": 35,
        "uniqueQueriedUsersUpDown": -44.44,
        "instantResolution": 1,
        "instantResolutionUpDown": 0.0,
        "aiResponseRate": 100.0,
        "aiResponseRateUpDown": 0.0,
        "uniqueVisitors": 2077,
        "uniqueVisitorsUpDown": -1.05,
        "totalFaqs": 0,
        "totalFaqsUpDown": 0.0,
        "totalDocuments": 0,
        "totalDocumentsUpDown": 0.0,
        "feedbacksUpDown": 0.0
    },
    "errors": null
}

Daily Conversation Count

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

照会期間内における日次会話数の総数

Headers

Name	Type	Description
API-KEY	string	APIキーは、ダッシュボードの[プロジェクト設定]メニューの[全般]タブにあります。

Request Body

Name	Type	Description
endDate	string	照会期間の終了日をYYYY-MM-DDの形式で入力します。
startDate	string	照会期間の開始日をYYYY-MM-DDの形式で入力します。

200

次のJSON形式で結果を取得できます。

dailyTotalCount: 日付とactiveCountのペアのリストで、activeCountは日付に選択されたその日の会話の数を表します。

{
    "result": {
        "dailyTotalCount": [
            {
                "date": "DATE",
                "activeCount": ACTIVE_COUNT
            }
        ],
        "state": "NORMAL",
        "campaignCount": 1
    },
    "errors": null
}

Request Example

YOUR API KEYを自身のプロジェクトのAPIキーに変更する必要があります。APIキーの取得をご参照ください。

curl -X GET -d '{ "startDate": "2020-11-19",
"endDate": "2020-11-24"}' \
-H 'API-KEY: YOUR_API_KEY' \
https://backend-ja.alli.ai/webapi/conversation_daily_count

Response Example

{
    "result": {
        "dailyTotalCount": [
            {
                "date": "2020-11-19",
                "activeCount": 30
            },
            {
                "date": "2020-11-20",
                "activeCount": 49
            },
            {
                "date": "2020-11-21",
                "activeCount": 32
            },
            {
                "date": "2020-11-22",
                "activeCount": 2
            },
            {
                "date": "2020-11-23",
                "activeCount": 31
            },
            {
                "date": "2020-11-24",
                "activeCount": 16
            }
        ],
        "state": "NORMAL",
        "campaignCount": 1
    },
    "errors": null
}

Daily FAQ Count

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

照会期間内にFAQで検出されたQ＆Aの数の日別トレンドです。

Headers

Name	Type	Description
API-KEY	string	APIキーは、ダッシュボードの[プロジェクト設定]メニューの[全般]タブにあります。

Request Body

Name	Type	Description
startDate	string	照会期間の開始日をYYYY-MM-DDの形式で入力します。
endDate	string	照会期間の終了日をYYYY-MM-DDの形式で入力します。

200

次のJSON形式で結果を取得できます。

dailyTotalCount: 日付とactiveCountのペアのリストで、activeCountは日付に選択されたFAQの数です。

{
    "result": {
        "dailyTotalCount": [
            {
                "date": "DATE",
                "activeCount": ACTIVE_COUNT
            }
        ],
        "state": "NORMAL",
        "campaignCount": 1
    },
    "errors": null
}

Request Example

YOUR API KEYを自身のプロジェクトのAPIキーに変更する必要があります。APIキーの取得をご参照ください。

curl -X GET -d '{ "startDate": "2020-11-19",
"endDate": "2020-11-24"}' \
-H 'API-KEY: YOUR_API_KEY' \
https://backend-ja.alli.ai/webapi/faq_daily_count

Response Example

{
    "result": {
        "dailyTotalCount": [
            {
                "date": "2020-11-19",
                "count": 24
            },
            {
                "date": "2020-11-20",
                "count": 70
            },
            {
                "date": "2020-11-21",
                "count": 23
            },
            {
                "date": "2020-11-22",
                "count": 45
            },
            {
                "date": "2020-11-23",
                "count": 34
            },
            {
                "date": "2020-11-24",
                "count": 30
            }
        ]
    },
    "errors": null
}

Daily FAQ Analytics

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

最も頻繁に質問されたQ＆Aの統計

Headers

Name	Type	Description
API-KEY	string	APIキーは、ダッシュボードの[プロジェクト設定]メニューの[全般]タブにあります。

Request Body

Name	Type	Description
topN	number	最もよく聞かれるQ＆AのトップN。 Nの最大値は20です。Nには1、5、10、または20を使用してください。
startDate	string	照会期間の開始日をYYYY-MM-DDの形式で入力します。
endDate	string	照会期間の終了日をYYYY-MM-DDの形式で入力します。

200

次のJSON形式で結果を取得できます。

faqDailyAnalytics: JSONオブジェクトのリストで、各オブジェクトには1つのFAQの分析情報が含まれています。

totalCount: Q&Aが選択された総回数。

totalShownCount: Q&Aが表示された総回数。

selectedRatio: Q&Aが選択された回数と表示された回数の比率。

stats: 日付と選択回数のペアのリストで、選択回数はFAQがその日に選択された回数です。

{
    "result": {
        "faqDailyAnalytics": [
            {
                "totalCount": NUMBER,
                "totalShownCount": NUMBER,
                "selectedRatio": NUMBER,
                "faq": {
                    "id": "ID_1",
                    "question": "QUESTION_1"
                },
                "stats": [
                    {
                        "date": "DATE",
                        "selectedCount": NUMBER
                    }
                ]
            }
        ]
    },
    "errors": null
}

Request Example

YOUR API KEYを自身のプロジェクトのAPIキーに変更する必要があります。APIキーの取得をご参照ください。

curl -X GET -d '{ "startDate": "2020-12-02",
"endDate": "2020-12-05", "topN": 5}' \
-H 'API-KEY: YOUR_API_KEY' \
https://backend-ja.alli.ai/webapi/faq_daily_analytics

Response Example

{
    "result": {
        "faqDailyAnalytics": [
            {
                "totalCount": 1,
                "totalShownCount": 1,
                "selectedRatio": 100.0,
                "faq": {
                    "id": "RkFROjVkZDQ4ZWFhN2E4ZGM2M2Y4OGNhZmUzOQ==",
                    "question": "What is Alli?"
                },
                "stats": [
                    {
                        "date": "2020-12-02",
                        "selectedCount": 0
                    },
                    {
                        "date": "2020-12-03",
                        "selectedCount": 0
                    },
                    {
                        "date": "2020-12-04",
                        "selectedCount": 1
                    },
                    {
                        "date": "2020-12-05",
                        "selectedCount": 0
                    }
                ]
            }
        ]
    },
    "errors": null
}

Executing a Skill

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

スキルを実行して、最終的な答えをjson形式で返されるAPIです。variablesパラメータ関連詳細については、以下の「Learn More about Variables」項目のリンクを参照してください。スキルがNER（Named Entity Recognition、固有表現抽出）のために設計されている場合は、このAPIをNERを使用することができます。（エンティティ抽出に使用できます。）

Headers

Name	Type	Description
API-KEY	string	APIキーは、ダッシュボードの[プロジェクト設定]メニューの[全般]タブにあります。

Request Body

Name	Type	Description
id	string	そのスキルのIDです。Alliダッシュボードからスキルを選択すると、スキルのURLが[https://app.alli.ai/projects/PROJECT_ID/campaigns/SKILL_ID]形式で表示されます。 SKILL_IDをこちらに入力します。
text	string	スキルを実行するためのテキスト入力
variables	object	スキルで使用する変数の変数の値を設定するためのJSONオブジェクト

200

照会の結果は、以下のようなJSON形式で返されます。最終的な答えがテキスト形式で返されます。エラー発生時errors項目にエラーメッセージが出力されます。

{"result": "TEXT RESULT FROM SKILL", "errors": []}

Learn More about Variables

本APIは、variables（変数）パラメータを使用します。Alliで使用される変数についての詳細はもっと知りたい場合は、こちらのユーザガイドを参照してください。

Request Example

YOUR API KEYを自身のプロジェクトのSDKキーに変更する必要があります。このAPIではAPIキーの代わりにSDKキーを使用する必要があります。SDKキーの取得方法については、こちらのユーザーガイドをご参照ください。

curl -d '{"id": "YOUR SKILL ID",
        "text": "issue date",
        "variables": {"YOUR_VARIABLE": "YOUR_VARIABLE_VALUE"}}' \
        -H 'API-KEY: YOUR_API_KEY' \
        -H 'Content-Type: application/json' https://backend-ja.alli.ai/webapi/skill

Response Example

{"result": "TEXT RESULT FROM SKILL", "errors": []}

API Classifications

APIの分類とマッピングについては下記を参照してください。

Excelファイルはこちらからダウンロードできます。