ボットセッションインターフェース - Udesk

セッション初期化

リクエストURL

POST /v1/initClient

リクエストパラメータ

リクエストフィールド

Path	Type	Optional	説明
robotId	Integer	false	ロボットID: このセッションに対応するロボットの識別ID.
channelId	Integer	false	シナリオID: このセッションに対応するシナリオの識別ID.
modelKey	String	true	よくある質問テンプレートID。'km-ロボット-ナレッジベース管理-推奨-ID'で確認できます.
accessKeyId	String	true	連携設定のアプリケーションID。アプリケーション取得時のappIDフィールドに対応します。'km-管理-アプリケーション管理-アプリケーションID'で確認できます.
platform	Integer	true	チャネル: 0:web, 1:通常WeChat, 2:Android, 3:iOS, 4:Weibo, 5:カスタマーサポートシステムAPI, 6:マルチマーチャント, 7:WeChatミニアプリ, 8:企業WeChat
customer	Map	true	顧客情報.
shortcutCustomId	String	true	ショートカットエントリのカスタムID.

customer に対応する構造

{
    "id": "顧客ID（Long型）",
    "nickname": "顧客名",
    "ip": "顧客IP",
    "province": "IP所在省",
    "city": "IP所在市",
    "orgName": "会社名",
    "email": "顧客メールアドレス",
    "phone": "顧客電話番号",
    "tags": "顧客タグ",
    "desc": "説明",
    "level": "顧客レベル",
    "platform": "チャネル",
    "src": "ソース",
    "srcUrl": "ソースURL",
    "webPluginName": "ソースプラグイン",
    "keyword": "検索キーワード",
    "generatedChannel": "カスタムチャネル情報",
    "loginUrl": "アクセスランディングページ",
    "sessionUrl": "会話開始ページ",
    "weChatOpenId": "WeChat OPENID",
    "customer_token": "顧客外部ID",
    "customField": "カスタムフィールド Map<String,String>",
    "c_cf_dialogueDesc": "会話説明（使用方法はWebhookタスクプッシュ型インターフェースを参照）"

}

リクエスト結果

Path	Type	説明
code	Integer	ステータスコード
message	String	返却メッセージ
visible	Boolean
data	Object	返却データ

data

Path	Type	説明
sessionId	Integer	セッションID.
logId	Integer	ロボットから返されるID.
welcomeMessage	String	ウェルカムメッセージ.
leadingWord	String	リードワード.
commonQuestionModel	Object	よくある質問.

commonQuestionModel

Path	Type	説明
id	Integer	ID.
robotId	Integer	ロボットID.
name	String	テンプレート名.
channelId	Integer	シナリオID.
description	String	説明.
modelKey	String	よくある質問テンプレートID。'km-ロボット-ナレッジベース管理-推奨-ID'で確認できます.
commonQuestionCategoryList	Array	よくある質問カテゴリ（カテゴリ内のよくある質問リストを含む）.
shortcutEntryList	Array	ショートカットエントリリスト.
#### commonQuestionCategoryList
Path	Type	説明
---	---	---
id	Integer	カテゴリID.
modelId	Integer	よくある質問テンプレートID.
name	String	ディレクトリ名.
sorts	Integer	予約済みソートフィールド.
questionList	Array	カテゴリ下のよくある質問リスト.

questionList

Path	Type	説明
id	Integer	質問の識別ID.
content	String	質問の内容.
type	Integer	タイプ 1：通常質問 4：雑談質問.
answer	Object	回答.
answer.content	String	回答内容
answer.type	Integer	回答タイプ
answer.id	Integer	回答ID

shortcutEntryList

Path	Type	説明
modelId	Integer	ショートカットエントリーリストID.
type	Integer	タイプ:1-テキスト,2-リンク.
name	String	エントリー名.
content	String	内容.
pic	String	画像URL.
sorts	Integer	予約済みソートフィールド.
isDefault	Integer	デフォルトかどうか.

サンプル

$ curl 'https://km.udesk.cn/api/v1/initClient?email=admin@udesk.cn&timestamp=1529402445&sign=fbe02e2b9f76179da49ea619cbabdde909b73a2f' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -d '{
  "robotId" : 103,
  "channelId" : 106,
  "modelKey" : "0",
  "accessKeyId" : "/+7772AKE6kv8AVNjWqP",
  "platform" : 5,
  "customer" : null
}'

レスポンス

{
    "code": 200,
    "message": "OK",
    "visible": false,
    "exception": null,
    "paging": null,
    "data": {
        "sessionId": 451724,
        "logId": 793020,
        "welcomeMessage": "こんにちは、ご利用ありがとうございます！",
        "leadingWord": "よくある質問",
        "commonQuestionList": [],
        "commonQuestionModel": {
            "id": 108,
            "name": "デフォルトよくある質問",
            "description": "よくある質問",
            "commonQuestionCategoryList": [
                {
                    "id": 76,
                    "modelId": 108,
                    "name": "111",
                    "questionList": [
                        {
                            "id": 8645,
                            "content": "社保怎么办理主引导选择啊",
                            "type": 1,
                            "answer": {
                                "content": "<p>打电话12345</p>",
                                "type": 2,
                                "id": 4436
                            }
                        },
                        {
                            "id": 8647,
                            "content": "社保如何办理",
                            "type": 1,
                            "answer": {
                                "content": "<p>网上查询</p>",
                                "type": 2,
                                "id": 4437
                            }
                        }
                    ]
                }
            ]
        }
    }
}

フロークリックインターフェース

リクエストURL

POST /v1/flow

リクエストパラメータ

リクエストフィールド

Path	Type	Optional	説明
sessionId	Integer	false	セッションID：このセッションの識別ID。セッション初期化（/api/initClient）のレスポンスで取得します。
logId	Integer	true	フローがクリックされたログの識別ID。ボットからの返信で提供されます。
flowId	Integer	true	フロー識別ID。ボットがフロー内容（flowContent）を返す際に提供されます。
flowContent	String	true	フローの具体的な内容。

レスポンス結果

Path	Type	説明
code	Integer	実行結果コード
message	String	実行結果の説明
data	Object	セッション情報
data.sessionId	Integer	セッションID。
data.logId	Integer	ボットが返したログの識別ID。
data.flowId	Integer	フローID。フローを返す場合に有効です。
data.flowTitle	String	フロータイトル。フローを返す場合に有効です。
data.flowContent	String	フロー内容。フローを返す場合に有効です。内容内で、data-typeとdata-id属性を持つHTML要素のみがクリック可能であり、すべてのdata-*属性の値はString型です。
data.restrictionState	Object	インタラクション量制限状態。
data.restrictionState.exceededFlag	Integer	制限超過フラグ【0:正常/1:制限超過】
data.restrictionState.usedCount	Integer	使用済み数量
data.restrictionState.totalCount	Integer	制限総量

サンプル

$ curl 'https://km.udesk.cn/api/v1/flow?email=admin@udesk.cn&timestamp=1529402444&sign=17dfc106671e1cd2442ba6e61c778aac86bb3035' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -d '{
  "sessionId" : 450285,
  "logId" : 785709,
  "flowId" : 42,
  "flowContent" : "<p>11111</p><p>22222</p><p>33333</p>"
}'

レスポンス

{
    "code": 200,
    "message": "OK",
    "visible": false,
    "data": {
        "sessionId": 28905,
        "logId": 793020,
        "flowId": 285,
        "flowTitle": "フロー問題",
        "flowContent": "<p>1111</p>",
        "suggestQuestionList": [],
        "restrictionState": {
            "exceededFlag": 0,
            "usedCount": 32,
            "totalCount": 1000000
        }
    }
}

リクエスト失敗の原因

{
  "code": 400,
  "message": "{具体的な例外情報}",
  "visible": false
}

message	description
"sessionId does not exist! Please reinitialize"	対応するsessionIdの対話が存在しません
"【...】javax.validation.constraints.NotNull.message"	【具体的なフィールド】は空にできません
"The system could not find the process"	対応するflowIdのプロセスが存在しません

問題クリック行動インターフェース

リクエストアドレス

POST /v1/hit

リクエストパラメータ

リクエストフィールド

Path	Type	Optional	Description
sessionId	Integer	false	このセッションの識別ID.
queryType	Integer	true	ユーザークリックタイプ列挙 6:よくある質問クリック 7:提案問題クリック 8:プロセス内の問題クリック 9:インテリジェントヒントクリック.
logId	Integer	true	ユーザークリック行動が含まれるlogの識別ID（queryTypeが9の場合、このフィールドは入力不要）.
questionId	Integer	true	問題ID（クリックした問題のID）.
questionContent	String	true	問題内容（クリックした問題の内容）.
contentType	String	true	列挙：text ,rich textの場合、ansContentのリッチテキストをプレーンテキストに変換します
hitSource	Integer	true	1.クイックエントリのメッセージ、2.ボタンテキストのクリック、3.商品リスト構造化メッセージ.

リクエスト結果

Path	Type	Description
code	Integer	実行結果コード
message	String	実行結果説明
data	Object	セッション情報
data.sessionId	Integer	セッションID.
data.logId	Integer	ボットが返したlogの識別ID.
data.ansContent	Var	対応する回答の内容を返します.
data.ansType	Integer	回答タイプ
data.attachmentList	Array	問題の添付ファイルリスト
data.attachmentList[].name	String	問題添付ファイルの名称
data.attachmentList[].address	String	問題添付ファイルのリンク
data.attachmentList[].size	Integer	問題添付ファイルのサイズ
data.flowId	Integer	プロセスID, プロセスを返す場合に有効.
data.flowTitle	String	プロセスタイトル，プロセスを返す場合に有効.
data.flowContent	String	プロセス内容，プロセスを返す場合に有効.内容にはdata-typeとdata-id属性を持つHTML要素のみがクリック可能で、すべてのdata-*属性の値はString型です
data.hitQuestion	String	リコールした問題を返します.
data.msgType	String	回答のタイプ.
data.switchStaffType	Integer	1.オペレーターへの転送を推奨 2.条件を満たしたらオペレーターへ転送 3.メッセージを送信.
data.switchStaffAnswer	String	オペレーター転送メッセージ.
data.suggestQuestionList	Array	提案問題リスト.
data.suggestQuestionList[].id	Integer	提案問題の識別ID.
data.suggestQuestionList[].content	String	提案問題の内容.
data.suggestQuestionList[].type	Integer	提案問題のタイプ
data.suggestQuestionList[].answer	Object	提案問題の回答.
data.suggestQuestionList[].answer.content	String	提案問題の回答内容
data.suggestQuestionList[].answer.type	Integer	提案問題の回答タイプ
data.suggestQuestionList[].answer.id	Integer	提案問題の回答ID
data.aid	Integer	対応する回答のIDを返します, 回答を返す場合に有効
### サンプル

$ curl 'https://km.udesk.cn/api/v1/hit?email=admin@udesk.cn&timestamp=1529402439&sign=2c8f96911159fae72a493365a9692ce66c5c2b5d' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -d '{
  "sessionId" : 450283,
  "queryType" : 7,
  "logId" : 785703,
  "questionId" : 232,
  "questionContent" : "谁的风扇"
}'

レスポンス

{
    "code": 200,
    "message": "OK",
    "visible": false,
    "exception": null,
    "paging": null,
    "data": {
        "sessionId": 451727,
        "logId": 793031,
        "ansContent": "<p>不和平</p>\n<p><audio style=\"display: none;\" controls=\"controls\"></audio></p>\n<p><audio style=\"display: none;\" controls=\"controls\"></audio></p>",
        "attachmentList": [],
        "suggestQuestionList": [
            {
                "id": 8657,
                "content": "世界哪里和平了",
                "type": 1,
                "answer": {
                    "content": "<p>没有</p>\n<p><audio style=\"display: none;\" controls=\"controls\"></audio></p>",
                    "type": 2,
                    "id": 4442,
                    "deleteFlag": 0
                }
            },
            {
                "id": 9259,
                "content": "你想去哪儿",
                "type": 1,
                "answer": {
                    "content": "<p>北海</p>\n<p><audio style=\"display: none;\" controls=\"controls\"></audio></p>",
                    "type": 2,
                    "id": 5009,
                    "deleteFlag": 0
                }
            }
        ],
        "aid": 4441
    }
}

リクエスト失敗の原因

{
  "code": 400,
  "message": "{具体的な例外情報}",
  "visible": false
}

message	description
"sessionId does not exist! Please reinitialize"	対応するsessionIdの対話が存在しません
"【...】javax.validation.constraints.NotNull.message"	【具体的なフィールド】は空にできません

セッションウィンドウ-よくある質問リストの取得

リクエストURL

POST /v1/chat/commonQuestions

リクエストパラメータ

リクエストフィールド

Path	Type	Optional	Description
robotId	Integer	false	ロボットID.
channelId	Integer	false	シナリオID.
modelKey	String	false	よくある質問テンプレートID。'km-ロボット-ナレッジベース管理-よくある質問-ID'で確認できます.

レスポンス

Path	Type	Description
code	Integer	実行結果コード
message	String	実行結果の説明
data	Array	よくある質問リスト情報
data[].id	Integer	よくある質問リストのカテゴリID.
data[].modelId	Integer	よくある質問リストのテンプレートID.
data[].name	String	よくある質問リストのカテゴリ名.
data[].questionList	Array	カテゴリ内のよくある質問.
data[].questionList[].id	Integer	質問ID.
data[].questionList[].content	String	質問の内容。type=5の場合はメッセージの内容を表します
data[].questionList[].type	Integer	タイプ 1:通常の質問 4:雑談の質問 5:メッセージ
data[].questionList[].answer	Object	回答.
data[].questionList[].answer.content	String	回答内容
data[].questionList[].answer.type	Integer	回答タイプ
data[].questionList[].answer.id	Integer	回答ID

例

$ curl 'https://km.udesk.cn/api/v1/chat/commonQuestions?email=admin@udesk.cn&timestamp=1529569037&sign=4bc33f53e473d6db70e900fb07b947a9ee18f905' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -d '{
  "robotId" : 112,
  "channelId" : 118,
  "modelKey" : "aaa"
}'

レスポンス

{
    "code": 200,
    "message": "OK",
    "visible": false,
    "exception": null,
    "paging": {
        "pageNum": 1,
        "pageSize": 1,
        "total": 1
    },
    "data": [
        {
            "id": 76,
            "modelId": 108,
            "name": "111",
            "questionList": [
                {
                    "id": 8645,
                    "content": "社保怎么办理主引导选择啊",
                    "type": 1,
                    "answer": {
                        "content": "<p>打电话12345</p>",
                        "type": 2,
                        "id": 4436
                    }
                },
                {
                    "id": 8647,
                    "content": "社保如何办理",
                    "type": 1,
                    "answer": {
                        "content": "<p>网上查询</p>",
                        "type": 2,
                        "id": 4437
                    }
                }
            ]
        }
    ]
}

セッションウィンドウ-ホットな質問リストの取得

リクエストURL

POST /v1/chat/hotQuestions

リクエストパラメータ

リクエストフィールド

Path	Type	Optional	説明
limitDayNum	Integer	false	最近何日間（100日以内）.
limitResultNum	Integer	false	最大返却レコード数（50件以内）.
robotId	Integer	false	ロボットID

レスポンス結果

Path	Type	説明
code	Integer	実行結果コード
message	String	実行結果の説明
data	Array	質問リスト
data[].id	Integer	質問の識別ID.
data[].content	String	質問の内容.
data[].type	Integer	質問タイプ
data[].answer	Object	回答.
data[].answer.content	String	回答内容
data[].answer.type	Integer	回答タイプ
data[].answer.id	Integer	回答ID
data[].matchCount	Integer	マッチ数.

サンプル

$ curl 'https://km.udesk.cn/api/v1/chat/hotQuestions?email=admin@udesk.cn&timestamp=1529569036&sign=27bfe3f1ece19e13b03ff669d30830322ae4cfa3' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -d '{
  "limitDayNum" : 100,
  "limitResultNum" : 2,
  "robotId" : 83
}'

レスポンス

{
    "code": 200,
    "message": "OK",
    "visible": false,
    "exception": null,
    "paging": {
        "pageNum": 1,
        "pageSize": 2,
        "total": 2
    },
    "data": [
        {
            "id": 844,
            "content": "あなたは誰ですか？",
            "type": 1,
            "answer": {
                "content": "私はrobotロボットです",
                "type": 2,
                "id": 552
            },
            "matchCount": 24
        },
        {
            "id": 9426,
            "content": "誰のファンダサ分",
            "type": 3,
            "answer": {
                "content": "123",
                "type": 1,
                "id": 5124
            },
            "matchCount": 13
        }
    ]
}

ボットが返した回答を評価する

リクエストURL

POST /v1/surveyQuestion

リクエストパラメータ

リクエストフィールド

Path	Type	Optional	説明
sessionId	Integer	false	セッションID.
questionSurveyOptionId	Integer	false	評価オプション 1：満足 2：不満足.
logId	Integer	true	評価対象の回答が含まれるレコードのID。ボットの返答から取得します.

レスポンス

Path	Type	説明
code	Integer	実行ステータスコード
message	String	実行結果の説明

例

$ curl 'https://km.udesk.cn/api/v1/surveyQuestion?email=admin%40udesk.cn&timestamp=1529402453&sign=de8f53541749eb530fc006941d6af1af4e917067' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -d '{
  "sessionId" : 450289,
  "questionSurveyOptionId" : 1,
  "logId" : 785716
}'

レスポンス

{
  "code" : 200,
  "message" : "OK",
  "visible" : false
}

リクエスト失敗の原因

{
  "code": 400,
  "message": "{具体的な例外情報}",
  "visible": false
}

message	説明
This reply has been evaluated!	この返信は既に評価済みです
The relationship between sessionId and sessionLogId does not exist!	logidは対応するsessionidの会話に属していません
sessionId does not exist! Please reinitialize	対応するsessionIdの会話が存在しません
【...】javax.validation.constraints.NotNull.message	【具体的なフィールド】は空にできません

ボットセッションを評価する

リクエストURL

POST /v1/surveySession

リクエストパラメータ

リクエストフィールド

Path	Type	Optional	説明
sessionId	Integer	false	セッションID.
sessionSurveyOptionId	Integer	true	評価オプション 1：未評価 2：満足 3：普通 4：不満足.
surveyContent	String	true	評価内容.

レスポンス

Path	Type	説明
code	Integer	実行ステータスコード
message	String	実行結果メッセージ
data	Object	返却内容
data.switchStaffType	Integer	1. WeChatチャネルで案内文を表示 2. 条件を満たした場合に人間の担当者へ転送.
data.switchStaffTips	String	担当者転送時のヒント.
### サンプル

$ curl 'https://km.udesk.cn/api/v1/surveySession?email=admin@udesk.cn&timestamp=1529402455&sign=d4be213127c62bb5b53dea5f5e52eaad06b2362f' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -d '{
  "sessionId" : 450290,
  "sessionSurveyOptionId" : 4,
  "surveyContent" : "hehe"
}'

レスポンス

{
  "code" : 200,
  "message" : "OK",
  "visible" : false
}

通常の対話

リクエストURL

POST /v1/chat

リクエストパラメータ

リクエストフィールド

Path	Type	Optional	説明
sessionId	Integer	false	セッションID：このセッションの識別ID。セッション初期化（/api/initClient）時に取得します。
robotId	Integer	false	ロボットID：このセッションに対応するロボットの識別ID。
queryContent	String	false	ユーザーの発話内容。
channel_id	Integer	true	ナレッジベースのシナリオID
weixin_openid	String	true	WeChatのopenid
contentType	String	true	テキストタイプ。値が"text"の場合、ansContentのリッチテキストをプレーンテキストに変換します。
chatMode	Integer	true	対話モード 1.インテリジェントモード 2.タスク指向対話 3.FAQ 4.資料ライブラリ

リクエスト結果

Path	Type	説明
code	Integer	実行ステータスコード
message	String	実行結果の説明
data	Object	対話情報
data.sessionId	Integer	セッションID。
data.logId	Integer	ロボットが返したログの識別ID。
data.enableAppraise	Boolean	対話が評価を許可するかどうか
data.ansContent	String	返された対応する回答の内容。
data.ansType	Integer	返された回答のタイプ
data.msgbox	String	音声タイプ(data.ansType="audio")の場合、同時に返される文案
data.flowId	Integer	フローID、フローが返された場合に有効。
data.flowTitle	String	フロータイトル、フローが返された場合に有効。
data.flowContent	String	フロー内容、フローが返された場合に有効。
data.hitQuestion	String	返されたリコールされた質問。
data.msgType	String	回答のテキストタイプ。
data.switchStaffType	Integer	1.オペレーターへの転送を推奨 2.条件を満たした場合オペレーターに転送 3.メッセージを送信。
data.switchStaffAnswer	String	オペレーター転送メッセージ。
data.suggestQuestionList	Array	提案リスト。
data.suggestQuestionList[].id	Integer	提案問題の識別ID。
data.suggestQuestionList[].content	String	提案問題の内容。
data.suggestQuestionList[].type	Integer	提案問題のタイプ
data.suggestQuestionList[].answer	Object	提案問題の回答。
data.suggestQuestionList[].answer.content	String	提案問題の回答内容
data.suggestQuestionList[].answer.type	Integer	提案問題の回答タイプ
data.suggestQuestionList[].answer.questionId	Integer	提案問題の回答に対応する問題ID
data.suggestQuestionList[].answer.id	Integer	提案問題の回答ID
data.restrictionState	Object	インタラクション量制限状態。
data.restrictionState.exceededFlag	Integer	超過フラグ【0正常/1超過済み】
data.restrictionState.usedCount	Integer	使用済み数量
data.restrictionState.totalCount	Integer	制限総量
data.aid	Integer	返された対応する回答のID。
data.taskChatReturnCommands	Array	タスク指向対話の返却コマンドセット。
data.attachmentList	Array	FAQ問題の添付ファイルリスト。
data.attachmentList[].name	String	添付ファイル名
data.attachmentList[].address	String	添付ファイルアドレス
data.attachmentList[].size	Integer	添付ファイルサイズ
data.customerServiceId	String	転送先オペレーター/オペレーターグループのID。
data.customerServiceStatus	Integer	0はオペレーター、1はオペレーターグループ。
data.multipleMessageFlag	Integer	0はいいえ、1ははい。
data.multipleMessage	Array	複数メッセージ。
data.multipleMessage[].messageType	Integer	上記のmsgTypeと同等。
data.multipleMessage[].message	Integer	メッセージ内容。
data.multipleMessage[].	Integer	返された対応する回答のID。
data.multipleMessage[]	Integer	返された対応する回答のID。
data.multipleMessage[]	Integer	返された対応する回答のID。
#### data.msgTypeに対応するdata.ansContentの構造

列挙値	説明	構造
rich	リッチテキスト	タグ付きのString
selective_list	選択リスト	ans_selective_list
show_product	商品を表示	ans_show_product
selective_product	商品を選択	ans_show_product
wechat_image	微信画像付きメッセージ	ans_wechat_image
audio	音声	String 音声の再生リンクURL
link	リンク	ans_link
image	画像	String 画像のリンクURL
custom_card	カードメッセージ	ans_custom_card
task_button	新規タスク式ダイアログボタン	ans_task_button
map	地図メッセージ	ans_map
mini_apps_card	ミニアプリカード	mini_apps_card

ans_selective_table

Path	Type	説明
title	String	テーブルタイトル
rowNumber	Integer	テーブルの行数
columnNumber	Integer	テーブルの列数
optionList	Array	テーブルの内容
optionList[].id	Integer	オプションID
optionList[].value	String	オプションの値

ans_selective_list

Path	Type	説明
title	String	リストタイトル
optionList	Array	リストの内容
optionList[].id	Integer	オプションID
optionList[].value	String	オプションの値
##### ans_show_product
Path	Type	Description
---	---	---
title	String	商品タイトル
showSize	Integer	デフォルト表示数
turnFlag	Integer	商品メッセージのグループ切り替え表示可否 0:禁止 1:可
productList	Array	商品コンテンツ
productList[].id	Integer	商品ID
productList[].name	String	商品名
productList[].image	String	商品画像
productList[].url	String	商品リンク
productList[].infoList	Array	商品情報
productList[].infoList[].info	String	テキスト
productList[].infoList[].boldFlag	Integer	太字識別子(0または1)
productList[].infoList[].color	String	色

ans_wechat_image

Path	Type	Description
content	String	標準質問内容
coverUrl	String	カバー画像パス
description	String	説明
answerUrl	String	回答パス

ans_link

Path	Type	Description
faviconUrl	String	ファビコン画像のアドレス
title	String	ウェブサイトタイトル
answerUrl	String	回答自体に設定されたアドレス

ans_custom_card

Path	Type	Description
id	String	ID
name	String	名称
title	String	タイトル
subTitle	String	サブタイトル
pageType	String	0 疑似ページング 1 真のページング
pageNum	String	ページ番号
pageSize	String	ページサイズ
cardList	Array	カードコンテンツ
cardList[].id	String	ID
cardList[].type	String	カードタイプ 1.リッチテキストカード 2.FAQ推奨リストカード
cardList[].isHit	String	カードがクリック可能か type=1で有効 0:否 1:是
cardList[].hitType	String	カードクリック効果 type=1&isHit=1で有効 1:ハイパーリンク 2:メッセージ返信（チャットウィンドウでユーザーに代わってテキストを質問する） 3:構造化メッセージ（contentのリッチテキスト内容をメッセージとして送信する）
cardList[].hitContent	String	カードクリック内容 type=1&isHit=1で有効 hitType=1はリンクアドレス hitType=2は返信するメッセージ内容
cardList[].hitShowContent	String	hitType=3で有効、メッセージ送信時のメッセージカード。このフィールドが空でない場合はチャットウィンドウにこれを表示、空の場合はcontentを表示
cardList[].suggestContent	String	FAQ推奨カードの文案 type=2で有効
cardList[].suggestList	Array	FAQ推奨の質問リスト type=2で有効
cardList[].suggestList[].id	Integer	質問の識別ID type=2で有効
cardList[].suggestList[].content	Integer	質問の内容 type=2で有効
cardList[].suggestList[].type	Integer	質問タイプ type=2で有効
##### ans_task_button
Path	Type	Description
---	---	---
richText	String	ボタンメッセージの説明
buttons	Array	ボタンリスト
buttons[].flowId	String	所属フローID
buttons[].nodeId	String	所属フローのノードID
buttons[].buttonName	String	ボタン名
buttons[].customStyle	String	フロントエンドスタイル.json
buttons[].linkAddress	String	遷移リンクアドレス
buttons[].nextActionType	String	ボタンアクションタイプ（NEXT_NODE または OPEN_LINK）
buttons[].displayLocationType	String	ボタン表示位置（DEFAULT_POSITION または INPUT_BOX_ABOVE）

ans_map

Path	Type	Description
address	String	地図の詳細住所
name	String	場所表示の大見出し
location	String	緯度経度 "11.11,22.22"

mini_apps_card

Path	Type	Description
name	String	ミニアプリ名
appId	String	ミニアプリAppId
appUrl	String	ミニアプリAppIdUrl
miniAppCardType	Integer	ミニアプリカードのタイプを区別（アップロード画像または入力picId）1：miniAppPicUrl；2:picId
picId	String	picId
miniAppPicUrl	String	miniAppPicUrl

サンプル

$ curl 'https://km.udesk.cn/api/v1/chat?email=admin@udesk.cn&timestamp=1529402441&sign=08bea0badd00d36c432320fc3760fc419154b40d' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -d '{
  "sessionId" : 451714,
  "robotId" : 54,
  "queryContent" : "手机的价格",
  "contentType" : null,
  "chatMode" : null,
  "channel_id" : null,
  "weixin_openid" : null
}'

レスポンス

{
  "code" : 200,
  "message" : "OK",
  "visible" : false,
  "data" : {
    "sessionId" : 451714,
    "logId" : 793005,
    "ansContent" : "您的问题我会继续努力学习，期待下次为您更好的服务",
    "ansType" : 6,
    "msgType" : "plain",
    "suggestQuestionList" : [ ]
  }
}

リクエスト失敗の原因

{
  "code": 400,
  "message": "{具体的な例外情報}",
  "visible": false
}

message	description
sessionId does not exist! Please reinitialize	対応するsessionIdの対話が存在しません
Question content cannot be empty	queryContentの値を空にすることはできません
### 異なるdata.ansTypeの返却例
+ ansTypeはヒットした業務タイプであり、このフィールドはメッセージ内容と直接の関係はありません。

列挙値	説明
1	回答を返却
2	廃棄
3	提案リストを返却
4	挨拶を返却
5	廃棄
6	不明を返却
7	クリックタイプメッセージ
8	センシティブワード
9	メッセージトリガー型Webhook
10	ナレッジグラフナレッジポイント
11	タスク型対話
12	資料庫対話
13	サイレント
14	資料庫全属性返答
15	ナレッジグラフ
16	読解回答
17	読解提案
18	読解ガイド選択
19	特殊メッセージ
20	データベースQ&A
21	オペレーター転送意図
22	新タスク型対話ボタン
23	新版タスク型対話
24	アクティブ連絡要求
25	企業検索

統一対話インターフェース V2

リクエストアドレス

POST /v2/newChat

リクエストパラメータ

リクエストフィールド

Path	Type	Optional	Description
sessionId	Integer	false	セッションID：このセッションの識別ID。セッション初期化（/api/initClient）時に取得します。
robotId	Integer	false	ロボットID：このセッションに対応するロボットの識別ID。
queryContent	String	false	ユーザーの発話内容。
channel_id	Integer	true	ナレッジベースシナリオID
weixin_openid	String	true	WeChatのopenid
contentType	String	true	テキストタイプ値が"text"の場合、ansContentのリッチテキストをプレーンテキストに変換します。
chatMode	Integer	true	対話モード 1.インテリジェントモード 2.タスク型対話 3.FAQ 4.資料庫
responseMode	String	true	レスポンスモード：blocking(ブロッキング)またはstreaming(ストリーミング)、デフォルトはblocking
proxyModelCall	Boolean	true	サードパーティモデルをプロキシ呼び出しするかどうか、true: サーバー側がモデルインターフェースをプロキシ呼び出し（デフォルト）、false: モデル設定のみを返却し、呼び出し側が自身で呼び出し

リクエスト結果

Path	Type	Description
code	Integer	実行ステータスコード
message	String	実行結果説明
data	Object	対話情報
data.sessionId	Integer	セッションID。
data.logId	Integer	ロボットが返却するログの識別ID。
data.enableAppraise	Boolean	対話が評価を許可するかどうか
data.ansContent	String	対応する回答の内容を返却。
data.ansType	Integer	返却する回答タイプ
data.msgbox	String	音声タイプ(data.ansType="audio")の場合、同時に返却される文案
data.flowId	Integer	フローID、フローが返却される場合に有効。
data.flowTitle	String	フロータイトル、フローが返却される場合に有効。
data.flowContent	String	フロー内容、フローが返却される場合に有効。
data.hitQuestion	String	リコールされた質問を返却。
data.msgType	String	回答のテキストタイプ。
data.switchStaffType	Integer	1.オペレーター転送を推奨 2.条件を満たしたらオペレーター転送 3.メッセージ送信。
data.switchStaffAnswer	String	オペレーター転送メッセージ。
data.suggestQuestionList	Array	提案リスト。
data.suggestQuestionList[].id	Integer	提案問題の識別ID。
data.suggestQuestionList[].content	String	提案問題の内容。
data.suggestQuestionList[].type	Integer	提案問題タイプ
data.suggestQuestionList[].answer	Object	提案問題の回答。
data.suggestQuestionList[].answer.content	String	提案問題の回答内容
data.suggestQuestionList[].answer.type	Integer	提案問題の回答タイプ
data.suggestQuestionList[].answer.questionId	Integer	提案問題の回答に対応する問題ID
data.suggestQuestionList[].answer.id	Integer	提案問題の回答ID
data.restrictionState	Object	インタラクション量制限状態。
data.restrictionState.exceededFlag	Integer	超過フラグ【0正常/1超過済み】
data.restrictionState.usedCount	Integer	使用済み数量
data.restrictionState.totalCount	Integer	制限総量
data.aid	Integer	対応する回答のIDを返却。
data.thirdPartyModel	Object	サードパーティ大規模言語モデル設定情報、サードパーティ大規模言語モデルを呼び出す必要がある場合に返却。
data.thirdPartyModel.status	Boolean	有効かどうか。
data.thirdPartyModel.url	String	サードパーティ大規模言語モデルインターフェースアドレス。
data.thirdPartyModel.timestamp	Long	タイムスタンプ。
data.thirdPartyModel.sign	String	署名。
data.thirdPartyModel.customerToken	String	顧客トークン。
data.thirdPartyModel.robotKey	String	ロボットキー。
data.thirdPartyModel.conversionId	Integer	セッションID。
data.thirdPartyModel.enableAppraise	Boolean	評価を有効にするかどうか。
data.thirdPartyModel.aiAgentConversionId	String	AIエージェントセッションID。
data.thirdPartyModel.apiKey	String	APIキー。
data.thirdPartyModel.languageCode	String	言語コード。
data.thirdPartyModel.userId	String	ユーザーID。
### レスポンスモード説明

1. ブロッキングモード (responseMode=blocking)

完全なJSONレスポンスを返します:

{
  "code": 200,
  "message": "OK",
  "data": {
    "sessionId": 451714,
    "logId": 793005,
    "ansContent": "こんにちは、私はインテリジェントアシスタントです",
    "ansType": 1,
    "msgType": "plain",
    "suggestQuestionList": []
  }
}

2. ストリーミングモード (responseMode=streaming)

Server-Sent Events (SSE) 形式のデータを返します:[注意：各主要モデルの返却データ形式は一般的に異なります。以下は一例です]

data: {"message": "こんにちは、私は"}
data: {"message": "インテリジェントアシスタントです"}
data: [DONE]

例

$ curl 'https://km.udesk.cn/api/v2/newChat' -i -X POST \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{
    "sessionId": 451714,
    "robotId": 54,
    "queryContent": "こんにちは",
    "responseMode": "blocking",
    "proxyModelCall": false
  }'

リクエスト失敗原因

{
  "code": 400,
  "message": "{具体的な例外情報}",
  "visible": false
}

message	description
sessionId does not exist! Please reinitialize	sessionIdが存在しません！再初期化してください
Question content cannot be empty	質問内容は空にできません

注意事項

responseMode=streaming 場合、クライアントはSSE (Server-Sent Events) をサポートする必要があります
proxyModelCall=false 場合、サードパーティモデルを呼び出す必要がある場合、インターフェースはモデル設定を返し、呼び出しは実行しません
大規模モデルの呼び出しには60秒のタイムアウト制限があります
ネットワークが安定した環境でストリーミングレスポンスモードを使用することをお勧めします

インテリジェントアシスト

リクエストURL

POST /v1/assist

リクエストパラメータ

リクエストフィールド

Path	Type	Optional	Description
robotId	Integer	false	ロボットID.
channelId	Integer	false	シナリオID.
queryContent	String	true	質問内容.

リクエスト結果

Path	Type	Description
code	Integer	実行結果コード
message	String	実行結果説明
data	Object	セッション情報
data.sessionId	Integer	セッションID.
data.logId	Integer	ロボットが返すログの識別ID.
data.ansContent	String	対応する回答の内容.
data.ansType	Integer	回答タイプ
data.flowId	Integer	フローID, フローを返す場合に有効.
data.flowTitle	String	フロータイトル，フローを返す場合に有効.
data.flowContent	String	フロー内容，フローを返す場合に有効.
data.hitQuestion	String	返却された質問.
data.msgType	String	回答のテキストタイプ.
data.switchStaffType	Integer	1. 微信チャネルでガイダンスを表示 2. 条件を満たした場合に人間に転送.
data.switchStaffTips	String	人間への転送ヒント.
data.suggestQuestionList	Array	提案質問リスト.
data.suggestQuestionList[].id	Integer	提案質問の識別ID.
data.suggestQuestionList[].content	String	提案質問の内容.
data.suggestQuestionList[].type	Integer	提案質問タイプ
data.suggestQuestionList[].answer	Object	提案質問の回答.
data.suggestQuestionList[].answer.content	String	提案質問の回答内容
data.suggestQuestionList[].answer.type	Integer	提案質問の回答タイプ
data.suggestQuestionList[].answer.questionId	Integer	質問の回答に対応する質問ID
data.suggestQuestionList[].answer.id	Integer	提案質問の回答ID
data.restrictionState	Object	インタラクション量制限状態.
data.restrictionState.exceededFlag	Integer	超過フラグ【0正常/1超過】
data.restrictionState.usedCount	Integer	使用済み数量
data.restrictionState.totalCount	Integer	制限総量
data.aid	Integer	対応する回答のIDを返します, 質問がFAQ質問の場合に有効
### サンプル

$ curl 'https://km.udesk.cn/api/v1/assist?email=admin@udesk.cn&timestamp=1529402447&sign=c3168ff8ee9db4208d3a6f8a49d4bea7d4058ab3' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -d '{
  "robotId" : 83,
  "channelId" : 83,
  "queryContent" : "你好"
}'

レスポンス

{
  "code" : 200,
  "message" : "OK",
  "visible" : false,
  "data" : {
    "ansContent" : "我是robot机器人啊",
    "attachmentList" : [ ],
    "hitQuestion" : "你是谁？",
    "msgType" : "rich",
    "suggestQuestionList" : [ ],
    "aid" : 552
  }
}

スマートヒントインターフェース

リクエストURL

POST /v1/smartHint

リクエストパラメータ

リクエストフィールド

Path	Type	Optional	Description
sessionId	Integer	false	セッションID.
keyword	String	true	キーワード.

レスポンス結果

Path	Type	Optional	Description
code	Integer	true	ステータスコード
message	String	true	レスポンスメッセージ
visible	Boolean	true
data	Object	true	レスポンス内容
data.smartTipList	Array	true	スマートヒント質問リスト.
data.smartTipList[].id	Integer	true	質問の識別ID.
data.smartTipList[].content	String	true	質問の内容.
data.smartTipList[].type	Integer	true	質問タイプ
data.smartTipList[].answer	Object	true	回答.
data.smartTipList[].answer.content	String	true	回答内容
data.smartTipList[].answer.type	Integer	true	回答タイプ
data.smartTipList[].answer.questionId	Integer	true	回答に対応する質問ID
data.smartTipList[].answer.id	Integer	true	回答ID

サンプル

$ curl 'https://km.udesk.cn/api/v1/smartHint?email=admin@udesk.cn&timestamp=1529402446&sign=a685c1c3881aebe59c79306ef6d288c25fab077b' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -d '{
  "sessionId" : 450287,
  "keyword" : "社保"
}'

レスポンス

{
    "code": 200,
    "message": "OK",
    "visible": false,
    "exception": null,
    "paging": null,
    "data": {
        "smartTipList": [
            {
                "id": 8645,
                "content": "社保怎么办理主引导选择啊",
                "type": 1,
                "answer": {
                    "content": "<p>打电话12345</p>",
                    "type": 2,
                    "id": 4436
                }
            }
        ]
    }
}

リクエスト失敗の原因

{
  "code": 400,
  "message": "{具体的な例外情報}",
  "visible": false
}

message	description
The robot does not exist or has been deleted!	指定されたrobotidのロボットが存在しない
The scene does not exist	指定されたchannelIdのシーンが存在しない
【...】javax.validation.constraints.NotNull.message	【具体的なフィールド】は空にできません

オペレーターへの転送通知インターフェース

リクエストURL

PUT /v1/sessions/:id/switchStaff

リクエストパラメータ

Path parameters

Parameter	Type	Optional	Description
id	Integer	false	このセッションのセッションID（sessionId）.

レスポンス結果

Path	Type	Description
code	Integer	実行ステータスコード
message	String	実行結果メッセージ

例

$ curl 'https://km.udesk.cn/api/v1/sessions/451718/switchStaff?email=admin@udesk.cn&timestamp=1529402455&sign=d4be213127c62bb5b53dea5f5e52eaad06b2362f' -i -X PUT -H 'Accept: application/json'

レスポンス

{
  "code" : 200,
  "message" : "OK",
  "visible" : false
}

Keys	Action
`?`	Open this help
`n`	Next page
`p`	Previous page
`s`	Search