Yesing Forum » Cami 線上智慧客服系統 » 使用說明文件 » 機器人知識API串接說明

 步驟 1 

前往管理中心 > 系統整合 > API 金鑰管理,建立用途為「機器人知識 API」的 API 金鑰

建立完成後,會包含金鑰 (API Key) 及密鑰 (API Secret),請妥善保存。


 步驟 2 

訪客輸入的訊息觸發有設定 API 功能的機器人知識時,機器人將以 HTTP POST 方式,傳送以下參數至所設定的 API URL

apiKey所使用的 API Key
chatId目前對話的 ID
integration.memberId若有進行會員串接,機器人將同時帶入 memberId,沒有 memberId 時值為 null
knowledgeSummary所觸發的知識主旨
userInput訪客輸入的訊息
step機器人與API連結目前執行的階段 (剛觸發時此值必為1)
storeDataAPI 流程進行中所紀錄的資料
userIp 訪客 IP
timestamp訪客輸入訊息的時間 (UNIX timestamp)
token供驗證來源正確性,利用 API Secret 將資訊經過 sha256 編碼後的字串
({API Secret}{timestamp}{talkId}{knowledgeSummary}{userInput}{step}{userIp})

API 端所須回傳參數 (JSON)

replyMessage欲顯示給訪客的回覆訊息 (若 API 執行錯誤,請留空)
quickMenu(非必要) 快速選單名稱 (多個選項請以符號 , 區隔)
nextStep下一步驟編號 (小於等於 9999的 數字,若API執行錯誤,請留空)
9999 表示結束 API 連結
storeData(非必要) API 流程進行中所需要紀錄的資料
customizeStatusCode(非必要) 自定義錯誤碼,當機器人執行 API URL 發生錯誤時,機器人會將此值顯示於訊息中
※ Debug 請參考機器人回應訊息 (Status Code)
※ 利用 customizeStatusCode 可對 API 程式進行 Debug

Status Code狀態說明

001

010

API Secret 錯誤
002

004

011

013

replyMessage 錯誤
003
005

006

012

014

015

nextStep 錯誤
007

008

016

017

storeData 錯誤

009

018

API 錯誤

 PHP範例 

範例僅供參考,請依實際情況檢驗參數及確認相關辨別條件。

<?php
if (!$_POST[’chatId’]) {
    echo json_encode([
        ’customizeStatusCode’ => 1
    ]);
    exit;
} elseif (!$_POST[’knowledgeSummary’]) {
    echo json_encode([
        ’customizeStatusCode’ => 2
    ]);
    exit;
} elseif ($_POST[’userInput’] === ’’) {
    echo json_encode([
        ’customizeStatusCode’ => 3
    ]);
    exit;
} elseif (!$_POST[’step’]) {
    echo json_encode([
        ’customizeStatusCode’ => 4
    ]);
    exit;
} elseif (!$_POST[’userIp’]) {
    echo json_encode([
        ’customizeStatusCode’ => 5
    ]);
    exit;
} elseif (!$_POST[’timestamp’]) {
    echo json_encode([
        ’customizeStatusCode’ => 6
    ]);
    exit;
} elseif (!$_POST[’token’]) {
    echo json_encode([
        ’customizeStatusCode’ => 7
    ]);
    exit;
}

$_POST[’integration’]             = isset($_POST[’integration’]) ? $_POST[’integration’] : [];
$_POST[’integration’][’memberId’] = isset($_POST[’integration’][’memberId’]) ? $_POST[’integration’][’memberId’] : null;
$_POST[’storeData’]               = isset($_POST[’storeData’]) ? $_POST[’storeData’] : [];

$apiSecret = ’請填入 API Secret’;
$verifyString = $apiSecret . $_POST[’timestamp’] . $_POST[’chatId’] . $_POST[’knowledgeSummary’] . $_POST[’userInput’] . $_POST[’step’] . $_POST[’userIp’];
$verifyToken = hash(’sha256’, $verifyString);

if ($verifyToken !== $_POST[’token’]) {
    echo json_encode([
        ’customizeStatusCode’ => 8
    ]);
    exit;
}

if ($_POST[’step’] == 1) {
    $success = [
        ’replyMessage’ => ’執行 Action A 請輸入 A,Action B 請輸入 B’,
        ’quickMenu’ => ’A,B’,
        ’nextStep’ => 2
    ];
} elseif ($_POST[’step’] == 2) {
    if ($_POST[’userInput’] === ’A’) {
        $success = [
            ’replyMessage’ => ’選擇了 Action A,是否確定?’,
            ’quickMenu’ => ’是,否’,
            ’nextStep’ => 3,
            ’storeData’ => [
                ’action’ => ’A’
            ]
        ];
    } elseif ($_POST[’userInput’] === ’B’) {
        $success = [
            ’replyMessage’ => ’選擇了 Action B,是否確定?’,
            ’quickMenu’ => ’是,否’,
            ’nextStep’ => 3,
            ’storeData’ => [
                ’action’ => ’B’
            ]
        ];
    } else {
        $success = [
            ’replyMessage’ => ’輸入錯誤,請重新輸入’,
            ’nextStep’ => 2
        ];
    }
} elseif ($_POST[’step’] == 3) {
    if ($_POST[’userInput’] == ’是’) {
        $success = [
            ’replyMessage’ => ’已儲存選擇 ’ . $_POST[’storeData’][’action’],
            ’nextStep’ => 9999
        ];
    } else {
        $success = [
            ’replyMessage’ => ’請重新選擇 A 或 B 。’,
            ’quickMenu’ => ’A,B’,
            ’nextStep’ => 1
        ];
    }
}

if (!isset($success)) {
    echo json_encode([
        ’customizeStatusCode’ => 9
    ]);
}

echo json_encode($success);