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

 步驟 1 

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

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


 步驟 2 

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

talkId目前對話的 ID
knowledgeSummary所觸發的知識主旨
userInput訪客輸入的訊息
step機器人與API連結目前執行的階段 (剛觸發時此值必為1)
userIp 訪客 IP
timestamp訪客輸入訊息的時間 (UNIX timestamp)
verifyToken供驗證來源正確性,利用 API Secret 將資訊經過 sha256 編碼後的字串
({API Secret}{timestamp}{talkId}{knowledgeSummary}{userInput}{step}{userIp})

API 端所須回傳參數 (JSON)

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

Status Code狀態說明

000API KEY 錯誤
001
003
replyMessage 錯誤
002
004
005
nextStep 錯誤

 PHP範例 

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

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

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

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

if ($_POST[’step’] == 1) {
    $success = array(
        ’replyMessage’ => ’執行 Action A 請輸入 A,Action B 請輸入 B’,
        ’quickMenu’ => ’A,B’,
        ’nextStep’ => ’2’
    );
} elseif ($_POST[’step’] == 2) {
    if ($_POST[’userInput’] === ’A’) {
        $success = array(
            ’replyMessage’ => ’選擇了 Action A’,
            ’nextStep’ => ’9999’
        );
    } elseif ($_POST[’userInput’] === ’B’) {
        $success = array(
            ’replyMessage’ => ’選擇了 Action B’,
            ’nextStep’ => ’9999’
        );
    } else {
        $success = array(
            ’replyMessage’ => ’輸入錯誤,請重新輸入’,
            ’nextStep’ => ’2’
        );
    }
}

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

echo json_encode($success);