> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/build/choose-channel/viber.md).

# 串接對話平台：Viber

把 Agent 串接到 Viber（Beta）：取得 Viber Bot Token、在 MaiAgent 建立 Viber 對話平台、設定歡迎訊息，以及一對一對話等使用限制。

Viber 是許多國家常用的通訊軟體。串接後，使用者在 Viber 與您的 Bot 對話，就由 MaiAgent 的 Agent 回覆，對話紀錄也會出現在 MaiAgent 的「所有對話」中。

{% hint style="info" %}
Viber 串接目前為 **Beta** 版，在選擇對話平台的畫面上會標示 <mark style="color:blue;">Beta</mark>。
{% endhint %}

{% hint style="warning" %}
Viber Bot 只能進行**一對一對話**，無法加入群組。若需要群組對話，請改用其他對話平台。
{% endhint %}

## 串接前確認 <a href="#pre-integration-checklist" id="pre-integration-checklist"></a>

* 已在 [MaiAgent 平台](https://admin.maiagent.ai/)建立好一個「AI 助理」
* 具備 <mark style="color:blue;">對話平台權限</mark>（權限說明見[角色權限管理](/org/roles/role-permission.md)）
* 已取得 Viber Bot 的 **Bot Token**（見下一步）

## 步驟一：取得 Viber Bot Token <a href="#step-get-bot-token" id="step-get-bot-token"></a>

Viber 的 Bot 申請採商業合作制，需要向 Viber 官方或其合作夥伴申請，申請管道可參考 Viber 的 [Viber Partners](https://www.forbusiness.viber.com/en/messaging-partners/) 頁面。Bot 開通後，您會取得一組 **Bot Token**，下一步會用到。

{% hint style="warning" %}
**Bot Token 在建立對話平台後無法修改。** 請確認取得的是正確 Bot 的 Token 再進行步驟二。
{% endhint %}

## 步驟二：在 MaiAgent 建立 Viber 對話平台 <a href="#step-create-channel-in-maiagent" id="step-create-channel-in-maiagent"></a>

### 1. 進入串接對話平台 <a href="#step-go-to-channel-integration" id="step-go-to-channel-integration"></a>

在左側選單點選 <mark style="color:blue;">客服對話</mark> → <mark style="color:blue;">對話平台</mark>，點擊右上角 <mark style="color:blue;">串接對話平台</mark>，選擇 <mark style="color:blue;">Viber</mark>。

### 2. 填寫基本設定 <a href="#step-fill-basic-settings" id="step-fill-basic-settings"></a>

| 欄位                                         | 說明                                                                       |
| ------------------------------------------ | ------------------------------------------------------------------------ |
| <mark style="color:blue;">名稱</mark>        | 為此串接取一個名稱（必填）。這只是 MaiAgent 這側的標籤                                         |
| <mark style="color:blue;">AI 助理</mark>     | 選擇要回覆 Viber 訊息的 Agent                                                    |
| <mark style="color:blue;">Bot Token</mark> | 步驟一取得的 Token（必填）                                                         |
| <mark style="color:blue;">歡迎訊息</mark>      | 使用者首次開啟對話時自動回覆的內容，上限 7,000 字；留空表示不回覆                                     |
| <mark style="color:blue;">啟用重置命令</mark>    | 開啟後可新增 <mark style="color:blue;">重置命令</mark> 關鍵字。使用者傳送完全相同的關鍵字，就會開始一段新對話 |

使用者在 Viber 看到的 Bot 名稱與頭像，會在建立時從 Viber Bot 帳號帶入，不需要在 MaiAgent 另外填寫；名稱超過 28 個字元時，回覆訊息上只會顯示前 28 個字元。

### 3. 功能設定 <a href="#step-feature-settings" id="step-feature-settings"></a>

切換到 <mark style="color:blue;">功能設定</mark> 分頁，可調整 <mark style="color:blue;">啟用 OCR</mark>、<mark style="color:blue;">使用系統時間回答</mark>、<mark style="color:blue;">使用傳送者名稱回答</mark>。各開關的說明與時區規則請見[功能設定](/build/conversation-settings/platform-settings/function-settings.md)。

### 4. 分配權限並建立 <a href="#step-permission-and-create" id="step-permission-and-create"></a>

切換到 <mark style="color:blue;">權限設定</mark> 分頁，選擇可以查看與管理這個對話平台的角色，再點擊 <mark style="color:blue;">串接對話平台</mark>。

MaiAgent 會先向 Viber 驗證 Bot Token，驗證成功後**自動為您設定 Webhook**，不需要回到 Viber 另外填寫網址。建立完成後即可在 Viber 與 Bot 對話測試。

## 建立後可以調整的設定 <a href="#settings-after-creation" id="settings-after-creation"></a>

從 <mark style="color:blue;">對話平台</mark> 列表點擊這個平台的 <mark style="color:blue;">編輯</mark>，可以：

* 修改 <mark style="color:blue;">歡迎訊息</mark>、重置命令，或用 <mark style="color:blue;">重置所有對話</mark> 一次重置這個平台下的所有對話（無法復原）。Bot Token 欄位會顯示「已設定；僅在建立時可輸入」，不能修改。
* 在 <mark style="color:blue;">功能設定</mark> 開啟 <mark style="color:blue;">啟用等待提示訊息</mark>：使用者傳訊息後、AI 還在處理時，先送出一則提示（例如「AI 處理中，請稍候...」）。Viber 無法修改或刪除已送出的訊息，所以每則提問只會送出**一次**提示，<mark style="color:blue;">提示重複間隔秒數</mark> 在 Viber 不會生效。
* 設定 <mark style="color:blue;">客服轉真人設定</mark>、<mark style="color:blue;">Webhook 設定</mark>、<mark style="color:blue;">AI Copilot</mark> 等進階分頁，說明見[對話平台設定總覽](/build/conversation-settings/platform-settings.md)、[客服轉真人設定](/build/conversation-settings/human-handoff.md)與[客服 Copilot](/serve/copilot.md)。

## 支援的訊息類型 <a href="#supported-message-types" id="supported-message-types"></a>

| 使用者傳送 | Agent 的處理方式        |
| ----- | ------------------ |
| 文字    | 直接回答               |
| 圖片    | 存為附件，交給 Agent 處理   |
| 影片    | 存為附件，記錄在對話中        |
| 網址    | 以網址文字處理            |
| 聯絡人   | 以聯絡人的姓名與電話文字處理     |
| 位置    | 轉成「位置分享」與經緯度文字後處理  |
| 貼圖    | 只記錄在對話中，沒有可回答的文字內容 |

Agent 回覆時：

* **文字**：粗體、斜體、刪除線會轉成 Viber 的文字樣式，連結會以「文字 (網址)」呈現。單則超過 7,000 字時自動分段送出，不會被截斷。
* **附件**：圖片以圖片訊息送出；其他檔案（含影音）以檔案訊息送出，單檔上限 50 MB，且檔名需有副檔名。

## 常見問題 <a href="#faq" id="faq"></a>

### 可以把 Bot 加進 Viber 群組嗎？ <a href="#no-group-support" id="no-group-support"></a>

不行。Viber Bot 本身無法加入群組，所有對話都是使用者與 Bot 的一對一對話。

### 建立時出現「Bot 已在其他 Inbox 中註冊」？ <a href="#bot-already-registered" id="bot-already-registered"></a>

同一個 Viber Bot 只能串接一個對話平台。若 Bot 已經串接在您組織的另一個對話平台，訊息會帶出該平台名稱；請先刪除舊的對話平台，或改用另一個 Bot。

### 建立時出現「無效的令牌」？ <a href="#invalid-token" id="invalid-token"></a>

代表 Viber 不接受這組 Bot Token。請確認 Token 完整複製、沒有多餘空白，且 Bot 仍為有效狀態。

### 使用者傳的檔案，Agent 讀不到？ <a href="#unsupported-files" id="unsupported-files"></a>

目前只處理上表列出的訊息類型。使用者在 Viber 傳送的文件檔不會被讀取，請引導使用者改貼文字或傳圖片。

### 更換 Bot Token 或改接別的 Bot？ <a href="#change-token" id="change-token"></a>

Bot Token 建立後不能修改。請刪除此對話平台，再以新的 Token 重新建立；刪除時 MaiAgent 會一併移除原本設定在 Viber 的 Webhook。

### 有些使用者收不到回覆？ <a href="#user-unsubscribed" id="user-unsubscribed"></a>

使用者在 Viber 取消訂閱 Bot 後，Agent 不會再回覆該使用者；使用者重新訂閱後即恢復。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.maiagent.ai/build/choose-channel/viber.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.