---
tags: Fintech, Docs, API
---
# Fintech 虛擬行員 API 說明文件

## 簡介

實作一 RESTful API server，由中信方呼叫，對虛擬行員指示台詞播放與動作表現。

### API 列表
- POST /api/perform
- POST /api/reset
- POST /api/set

### 需求說明
- 音檔需事先準備，並以 “標籤ID-數字.mp3” 命名
- 使用 perform API 請求虛擬行員行動
- API server 需自行維持一個狀態機，以便不會有流程錯誤產生
- 狀態需要提供強制設定/清除的 API

### 狀態說明

1. 初始狀態為「無對話進行中」
2. 接收到 onboarding 的 perform 請求後，進入「對話進行中」，其餘的 perform 請求均無視並維持原狀態
3. 「對話進行中」在沒有任何 perform call 的情況下維持 30 秒後便回歸「無對話進行中」（實作可以利用在每次呼叫 perform 時 check timestamp/expiration 之類的方式），請注意此狀態的移動，並沒有 client 端的介入/請求
4. 「對話進行中」收到 exit 的 perform 請求便回歸「無對話進行中」
5. 若是在「無對話進行中」收到非 onboarding 之請求，除了維持原狀態外，也要回傳給 client HTTP 409 的錯誤
6. 若是在「對話進行中」收到任何 onboarding 之請求，皆忽略，並不重新設定 30 秒倒數（意即剩 10 秒了，還是維持剩 10 秒）

## **POST** /api/perform

### 範例

curl -X POST \
  http://API_ENDPOINT/api/perform \
  -H 'Content-Type: application/json' \
  -d '[
    {
        "state": "onborading",
        "delay": 0,
        "audio": "onborading-1.mp3",
        "action": "onborading",
        "text": "我是數研發新鮮人，舒妍。目標是成為本行的頭號虛擬行員唷!!"
    },
    {
        "state": "get_result_1",
        "delay": 200,
        "audio": "get_result_1-2.mp3",
        "action": "get_result_1",
        "text": "你所查詢的卡片資訊為您找到了唷。"
    }
]'

`perform` API 命令虛擬行員進行台詞播放以及相對應的動作，並可以使用 `delay` 欄位，讓台詞播放前有一段延遲時間。

### Headers

| Key | Value | Description |
| ------------ | ---------------- | ------------|
| Content-Type | application/json | 指示請求格式為 json |

### Body

|Field |Description |
|------|------------|
|state |當前的state，值為標籤ID |
|delay |台詞播放之延遲時間，單位為毫秒(1/1000秒)。 |
|audio |欲播放之音檔檔名。 |
|action |欲作出之動作，值為標籤ID。 |
|text |台詞內容。 |

### 錯誤代碼
| HTTP code | 原因 |
| --------- | -------------------- |
| 200 | OK |
| 400 | 請求格式有誤 |
| 404 | 音檔不存在 |
| 409 | 狀態錯誤 |

### Ｎote
* "text" 欄位僅為偵錯使用，可有可無。

### Response

#### 200

{
    "message": "OK"
}

#### 4xx

{
    "message": "ERROR REASON" # 請將真實錯誤原因以英文表示
}

## POST /api/reset

### 範例

curl -X POST http://API_ENDPOINT/api/reset

`reset` API 清除 server 的狀態，還原為「無對話進行中」

### 回傳代碼
| HTTP code | 原因 |
| --------- | -------------------- |
| 200 | OK |

## POST /api/set

### 範例

curl -X POST \
  http://API_ENDPOINT/api/set \
  -H 'Content-Type: application/json' \
  -d '[
    {
        "state": "onborading",
        "delay": 0,
        "audio": "onborading-1.mp3",
        "action": "onborading",
        "text": "我是數研發新鮮人，舒妍。目標是成為本行的頭號虛擬行員唷!!"
    },
    {
        "state": "get_result_1",
        "delay": 200,
        "audio": "get_result_1-2.mp3",
        "action": "get_result_1",
        "text": "你所查詢的卡片資訊為您找到了唷。"
    }
]'

`/set` API 強制設定 server 的狀態為「對話進行中」，且同 `/perform` 一致，也會播放動畫與聲音。請求內容可對照 perform，兩者一模一樣。

## 動作與聲音檔案命名規則
對話腳本詳見"Fintech對話腳本(Excel)"內，"話術替換字典表"分頁。這裡僅摘錄部分供說明:

| 回話標籤 | 標籤ID | State | 動作 | ... |
| -------- | -------- | -------- | -------- | -------- |
| 開場白(1) | onboarding_1 | 開場介紹 | 1. (未開口說話前) 雙手自然交疊於身體前側 2.(開始說話時) 右手舉至額前敬禮 | ... |
| 開場白(2) | onboarding_2 | 開場介紹 | 1. ooo 2. xxx | ... |
| ... |

1. 每個對話("回話標籤")，對應到一個bot的動作與回話。動作命名規則如下：

 // Restful API內請使用 "標籤ID"命名該動作
 { ...
   "action": "onboarding",
 }

2. 同個回話標籤，可能有數個不同的配音(對話)。如開場白(1)可能有數種(1~3)個不同的預錄音回答，以避免呆板。預錄音檔案明明規則如下：

 // Restful API內請使用 "標籤ID-<SN>.<附檔名>" 命名該動作相對應的預錄音檔案。
 { ...
   "audio": "onboarding-2.mp3",
 }

3. bot的動作請使用 "標籤ID" 命名。一個標籤ID代表一個完整的動作，不要再拆出更細的小動作/表情。舉例來說， onboarding_1 這個動作，再呈現上可能會分成若干小的動作 [1. (未開口說話前) 雙手自然交疊於身體前側 2.(開始說話時) 右手舉至額前敬禮] ，但錄製時候，請將所有動作合併錄影為同一個"動作"。
4. 特定的回話標籤的動作，有其關連性。具體請參考以下文件(圈起來的回話標籤就是會連續播放之動作)
https://drive.google.com/file/d/1AkgnzL0ffueq4anqmQ_jO2id4g8On_UX/view?usp=sharing

[
    {
        "state": "onboarding",
        "delay": 0,
        "audio": "onboarding-1.mp3",
        "action": "onboarding",
        "text": "我是數研發新鮮人，舒妍。目標是成為本行的頭號虛擬行員唷!!"
    },

]