> ## Documentation Index
> Fetch the complete documentation index at: https://docs.brightalk.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 個人化電話與簡訊通知

> 以可重用代理人處理預約、活動、取件與回訪，傳入個別資料、接收結果回呼並依業務流程對帳。

名單超過 1,000 筆時，請使用[大型簡訊或撥號任務](https://docs.brightalk.ai/zh-Hant/guides/large-tasks.md)，每個任務最多 10 萬筆。一般的 `/batches` 與 `/sms-batches` 每次最多接受 1,000 筆；下方範例使用這兩個一般批次端點。

## 適用情境與共用流程

預約確認、活動提醒、到貨取件與服務回訪，都可以使用相同的 API 流程。您的系統提供每位收件人的通知內容與問題，Brightalk 負責執行電話或簡訊，再回傳結果。

| 情境 | 個人化內容 | 可收集的結果 |
| - | - | - |
| 預約確認 | 服務項目、預約時間、地點與改期方式 | 是否依約前來、是否需要改期 |
| 活動與課程提醒 | 活動名稱、開始時間、參加方式 | 是否參加、是否需要協助 |
| 到貨取件通知 | 訂單編號、取件地點與期限 | 是否會取件、是否需要後續聯絡 |
| 服務回訪 | 已完成的服務、關心事項與聯絡方式 | 是否需要人員協助、後續處理需求 |

1. 在後台建立使用變數的代理人，設定要收集的結果欄位。
2. 您的系統依業務事件，建立單通或批次通知，帶入個別資料與排程。
3. Brightalk 依設定執行，透過簽章 webhook 回傳通話或簡訊結果。
4. 您的系統用參考編號更新原始紀錄，再決定貼標籤、人工跟進或補發訊息。

## 一個代理人，多種通知

在後台建立對外撥號代理人，把開場白與提示詞寫成：

```text theme={null}
您好，{{customer_name}}，這裡是{{organization_name}}。
{{notification_text}}
{{action_hint}}
{{confirmation_question}}
```

`notification_text` 帶入已格式化的完整內容，例如「您預約的到店諮詢將在 12 月 1 日下午 3 點開始」。變數名稱可依腳本自行設計；變數值不會再做第二次樣板展開。

在代理人的「資料收集」設定 `response_intent`（字串，對本次 `confirmation_question` 回答 `yes`／`no`／`undecided`，未取得答案留空）、`follow_up_requested`（布林值，是否要求人員協助）與 `do_not_call`（布林值，對方明確要求停止聯絡時為 true）。它們會以原本設定的識別碼出現在 `structured_results`。您的系統應依通知情境判讀回答；也可設定預約時間、滿意度等業務欄位。拒接名單仍由組織的聯絡政策管理，取得一個結果欄位本身不等於已寫入拒接名單。

建立 API 金鑰時，單通電話需要 `calls:write`，電話批次需要 `batches:write`、`batches:read`，查詢每通結果需要 `calls:read`，逐字稿需要 `transcripts:read`。用量需要 `usage:read`；簡訊需要 `sms:send`、`sms:read`；查詢或重送結果回呼則分別需要 `webhooks:read`、`webhooks:write`。既有金鑰不會自動獲得新權限。

## 建立並啟動批次

以下 `POST /batches` 範例以同一個代理人處理預約確認與取件通知。請將 `TAIWAN_MOBILE_E164_1`、`TAIWAN_MOBILE_E164_2` 分別換成您有權聯絡的台灣行動電話（E.164）。範例先使用 `test_mode: true`：不建立真實撥號命令、不產生通話用量、不扣點。測試回呼會標示 `test_mode: true`，不會模擬真人接聽或憑空產生逐字稿。

```json theme={null}
{
  "agent_id": "11111111-1111-4111-8111-111111111111",
  "name": "每日客戶通知",
  "reference_id": "notifications-20261201",
  "metadata": { "site_id": "north-branch", "workflow_id": "customer-notifications" },
  "variables": { "organization_name": "光點服務中心" },
  "missing_variables": { "mode": "reject" },
  "recipients": [
    {
      "external_id": "customer-123",
      "reference_id": "appointment-456",
      "name": "王小明",
      "phone_number": "TAIWAN_MOBILE_E164_1",
      "variables": {
        "customer_name": "王小明",
        "notification_text": "您預約的到店諮詢將在 12 月 1 日下午 3 點開始。",
        "action_hint": "如需調整時間，請聯絡原預約窗口。",
        "confirmation_question": "請問您會依約前來嗎？"
      }
    },
    {
      "external_id": "customer-789",
      "reference_id": "pickup-A1001",
      "name": "林怡君",
      "phone_number": "TAIWAN_MOBILE_E164_2",
      "variables": {
        "customer_name": "林怡君",
        "notification_text": "您的訂單 A1001 已到店，取件期限為 12 月 5 日。",
        "action_hint": "請攜帶取件通知至櫃台領取。",
        "confirmation_question": "請問您會在期限前取件嗎？"
      }
    }
  ],
  "schedule": {
    "start_at": "2026-12-01T09:00:00+08:00",
    "calling_window": {
      "time_zone": "Asia/Taipei",
      "weekdays": ["monday", "tuesday", "wednesday", "thursday", "friday"],
      "start_time": "09:00",
      "end_time": "18:00"
    }
  },
  "retry_policy": { "max_retries": 2, "delay_minutes": 15, "on": ["no_answer", "busy"] },
  "webhook": {
    "url": "https://your-platform.example/brightalk/results",
    "secret": "replace-with-at-least-32-random-characters"
  },
  "test_mode": true
}
```

以 API 金鑰驗證；建立操作必須帶 `Idempotency-Key`。重送相同操作與內容時沿用原本的 key，建立新的通知或再次跟進則使用新的 key。

正式執行時移除 `test_mode`（或設為 false），取得批次 ID 後，另以 `POST /batches/{batch_id}/start` 啟動，body 為 `{}`，並使用另一個 `Idempotency-Key`。建立批次仍保留原有的草稿流程；只建立、不啟動就不會撥號。測試批次已結束，不可再啟動。

批次允許只有一位收件人。`POST /calls` 也支援相同的 `variables`、`metadata`、`reference_id`、`missing_variables`、`schedule`、`webhook`、`test_mode`，可使用 `contact_id` 或單一 `recipient`。

### 變數與識別碼

* `variables` 為字串對字串，最多 64 個欄位，每值最多 2,000 字元、整體最多 16 KiB UTF-8。名稱以英文字母或底線開頭，後面可用英數與底線，最多 64 字元；保留名稱不可使用。
* 批次的共同變數先套用，再由每位收件人的變數覆蓋。收件人可帶不同通知內容、日期與確認問題。
* `missing_variables.mode: "reject"` 會在建立前檢查代理人提示詞與文字開場白，缺少變數就拒絕整個請求，回傳 `validation_error`，不建立半個批次。
* 若要使用預設值，設定 `missing_variables: { "mode": "default", "defaults": { "action_hint": "如需協助，請聯絡原服務窗口。" } }`。預設值未涵蓋的缺少變數仍會拒絕，避免直接念出括號。
* 既有的系統日期、時間與 CRM 內建變數維持原有行為。API 接受後若代理人腳本再被修改，新的腳本仍以撥號時的設定為準；建立批次後請維持同一組變數名稱。
* 通知內容存於每次執行，不會用它覆寫 CRM 的公司、職稱或城市。若您直接在 `recipient.company` 等 CRM 欄位填入通知資料，那些仍是聯絡人寫入欄位，會影響 CRM。
* `recipient.external_id` 是 CRM 聯絡人的外部識別，可在多次通話與通知中重複使用；`reference_id` 是不要求唯一的業務參考，例如預約、訂單或工單編號。不同收件人不能共用同一組聯絡人外部識別。
* `GET /calls/{call_id}` 會回傳變數、metadata、外部參考與結構化結果；測試通話另有 `rendered_prompt`、`rendered_first_sentence`。測試批次也可由 `GET /calls?batch_id=...` 檢視各收件人的展開內容。

### 排程與重撥

排程遵守您提供的時區、星期與時間窗，也必須符合組織的外撥政策。`start_at` 是最早開始時間，不保證那一秒撥出；線路、餘額與其他批次都會影響實際撥出時間。時段不支援跨午夜，請拆成兩段排程。

`retry_policy` 僅在未接或忙線、且沒有接通證據時重試；最多 5 次，間隔 1–1,440 分鐘。每次重撥建立新的通話 ID，保留 `retry_of_call_id`、`retry_root_call_id` 與同一份變數／metadata／reference\_id。批次回應另有 `retry_pending_calls`、`retry_attempts`。原批次的收件人統計保留原始嘗試，最終跟進應使用各次 `call.completed` 的接聽結果；不要把多次嘗試當成多位收件人。暫停或取消原批次會阻止尚未撥出的重試。

## 接收並驗證結果回呼

事件類型為 `call.completed`、`batch.completed`、`sms.completed` 與 `sms_batch.completed`。電話結果會等待摘要與逐字稿處理完成或確認不可用；未接、忙線與取消可以直接回報。每個事件包含固定的 `id`、`type`、`created_at`、`test_mode` 與 `data`。電話 data 包含 call id、reference\_id、external\_id、metadata、接聽狀態、結果與 `structured_results`；有可用結果時另含摘要狀態與逐字稿 API 網址。逐字稿網址仍需 API 金鑰與 `transcripts:read`，不是公開下載連結。

驗證下面的標頭：

```text theme={null}
Brightalk-Event-Id: <事件 ID>
Brightalk-Timestamp: <Unix 秒數>
Brightalk-Signature: v1=<hex HMAC-SHA256>
```

簽章內容是 **timestamp + "." + 原始 HTTP body 位元組**，使用您在 `webhook.secret` 設定的秘密。不要先把 JSON 解析再序列化。

```javascript theme={null}
import { createHmac, timingSafeEqual } from "node:crypto";

export function verifyBrightalk(rawBody, headers, secret) {
  const timestamp = headers["brightalk-timestamp"];
  const signature = headers["brightalk-signature"];
  if (!/^\d+$/.test(timestamp ?? "")) return false;
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
  if (!/^v1=[a-f0-9]{64}$/.test(signature ?? "")) return false;
  const expected = createHmac("sha256", secret)
    .update(timestamp + ".").update(rawBody).digest();
  return timingSafeEqual(expected, Buffer.from(signature.slice(3), "hex"));
}
```

驗證成功後，先把事件 ID 與待處理工作持久化，再回覆 2xx。這是至少一次傳遞，同一事件可能收到多次；請用事件 ID 去重。事件沒有跨通話的到達順序保證。失敗會以指數退避重試，最多 10 次；`GET /webhook-events/{event_id}` 查狀態，耗盡後可用 `POST /webhook-events/{event_id}/retry`（body `{}`）重新投遞，這不會再打一次電話或再發一封簡訊。

回呼只允許公開 HTTPS 的最終網址、443 連接埠、不跟隨重新導向；私有網路與中繼資料位址會被阻擋。簽章秘密以加密方式保存，查詢結果不會傳回。

## 依站台與業務流程對帳

```text theme={null}
GET /usage?start_at=2026-12-01T00:00:00%2B08:00&end_at=2027-01-01T00:00:00%2B08:00&group_by=site_id,workflow_id
```

需 `usage:read`。最多查 93 天、以最多三個 metadata 欄位分組；起點包含、終點不包含。`metadata` 可另外傳 JSON 字串物件作篩選。沒有該欄位的資料會分到 null。查詢僅涵蓋這個公開 API 建立、且不是測試的執行，以建立時間歸屬期間；尚未完成的通話，實際分鐘數會隨帳務記錄補齊。

回應包含通話數、`billable_minutes`、簡訊分封數及 `sms_credits_deducted`。分鐘數讀取真正的帳務用量：秒數除以 60，**不逐通向上取整**；沒有正數計費通話秒數的未接不產生語音分鐘，語音信箱則依實際計費記錄計入。

計費分鐘沿用正式結算的條件：即使用量列的 billable 為 true，狀態為 `test`、`playground`、`failed`、`cancelled`、`canceled` 或 `skipped` 仍不列入。同帳號、同完整帳期的有效用量包含舊有或缺少訂閱 ID 的資料。

`voice_credit_accounting` 為 `settled_period_proportional_minutes`，語音點數單位為分鐘。每個已結算且可與帳本核對的訂閱帳期，`voice_credits_deducted` 依「該組計費分鐘 ÷ 該帳期全帳號計費分鐘」分攤帳本實際扣點。分母包含其他站台與非 API 通話，不會因本次 metadata 或執行日期篩選而縮小；購買點數與管理員調整不列入分攤。`voice_credit_periods` 提供帳期、全帳號分鐘數、實際扣點及歸屬狀態，供您對帳。

`voice_unallocated_billable_minutes` 列出尚無可核對結算資料的分鐘數。這些分鐘的未來扣點尚未確定，帳期的 `credits_deducted` 與 `organization_billable_minutes` 為 null，狀態為 `pending_settlement`；若結算快照與帳本扣點不符，則為 `unreconciled`。已結算但沒有耗用點數的帳期，實際扣點為 0。分組結果保留 12 位小數，跨組加總可能有極小的四捨五入差額；延遲入帳或用量更正會重新計算分攤比例。您可用此結果處理站台帳務分攤，Brightalk 仍按共用帳號結算；metadata 不會建立獨立餘額，也不構成租戶隔離。

## 簡訊 API

您的系統可在驗證 `call.completed` 後，依 `reference_id` 找到原始紀錄，再對未接者呼叫 `POST /sms` 補發通知。以新的 `Idempotency-Key` 識別這次補發；重送同一筆補發時沿用該 key，並透過 `sms.completed` 更新送達結果。

啟用自動重撥時，請依業務規則決定補發時機，並以原始通話或業務通知 ID 記錄補發狀態。各次通話嘗試都有自己的事件 ID；除了回呼事件去重，補發動作也需要在業務層去重。

* `GET /sms/account`：查簡訊模組是否啟用、點數、署名及 multipart 能力。`registration_status: "contact_support"` 代表平台沒有足夠資料由 API 證明電信申請已核准；`sender_number: null` 不代表收件人一定看到空白號碼。
* `POST /sms`：`phone_number`、`message`、`reference_id`／`external_id`、`metadata`、可選 `schedule`、`webhook`、`test_mode`，需 `Idempotency-Key`。
* `POST /sms-batches`：相同共同欄位，另帶 1–1,000 筆 recipients。每筆可有自己的 `variables`、metadata 與參考編號；同樣需 `Idempotency-Key`。
* `GET /sms/{sms_id}` 與 `GET /sms-batches/{batch_id}`：查詢發送與送達結果。

接受請求後，相同的 Idempotency-Key 與內容會先重播保存的原始 202 回應，再略過文字處理與短連結建立。署名或供應商設定變動不會讓已接受的請求失效；目前狀態請查 GET 端點，重播保留的是原始接受快照。相同 key 帶不同內容則回 409。

目前目的地限定台灣行動電話 E.164（`+8869XXXXXXXX`）。正式簡訊共用既有 CHT 發送、拒收與送達回報機制；`scheduled`／`queued` 不是送達，`sent` 只是電信業者接受，只有 `delivered` 代表取得送達回報。無法確認送達會回 `unknown` 或 `delivery_unknown`，不自動當成失敗重送。

### 簡訊字數與扣點

一段簡訊扣 **1 點**。以下以加上電信抬頭、組織 `[署名]` 前綴、變數代入及最終短網址後的實際內容計算；回應的 `message` 是凍結後的文字，`segments` 是分段數。

| 內容 | 單封上限（1 點） | 超過之後 |
| - | - | - |
| 含中文、全形符號或換行 | 70 字 | 每段 66 字，最多 6 段（396 字），每段 1 點 |
| 純英數（GSM） | 160 個計費字元 | 每段 152 個計費字元，最多 6 段（912 個計費字元），每段 1 點 |

* **71 字就是 2 點**：使用中文編碼時，中文、英文、數字、標點、空白與換行各算 1 字。71–132 字扣 2 點，133–198 字扣 3 點。
* **特殊符號會影響計算**：GSM 中的 `^`、`{`、`}`、`[`、`]`、`~`、`|`、`\` 各佔 2 個計費字元（septet），分段時不會拆開。換行、底線 `_` 或反引號（U+0060）會改用中文編碼，上限回到單封 70 字、長簡訊每段 66 字。912 是計費單位上限，不保證能放入 912 個含特殊符號的字元。
* **發送管道不同，上限也不同**：批次簡訊、自動化、公開 API 的 `POST /sms` 與 `POST /sms-batches` 支援長簡訊。一對一手動發送及 MCP 的 `brightalk_send_sms` 只支援單封，超過 70 個 UTF-16 單位或 159 ASCII bytes 就會拒絕；這條舊管道以 ASCII bytes 計數，與上表的 GSM 計算方式不同。
* **不支援 emoji**：請先移除 emoji；非 BMP 字元會被拒絕。

MCP 的 `brightalk_create_sms` 與 `brightalk_create_sms_batch` 使用公開 API 的長簡訊規則；`brightalk_preview_sms` 只預覽單封聯絡人發送管道。請先以 `GET /sms/account` 確認帳號能力。

`credits_reserved` 是尚未結算的保留點數，`credits_deducted` 是帳本淨扣抵（包括釋放／退款）。點數保留或扣抵都不能當成送達證明。

`expires_at` 是排程簡訊最晚可建立電信發送工作的時間，必須晚於 `schedule.start_at`；預設為「建立請求時間與 `schedule.start_at` 較晚者」加 1 小時。若可發送時段更晚才開始，請明確設定期限。暫時無法排入發送的原因會出現在 `error_code`，並以退避間隔重試；排入失敗達 10 次或過期後會變成 `failed`，即使不在可發送時段也會結束，並可觸發結果回呼。過期原因為 `schedule_expired`。建立電信發送工作後，沿用既有電信派送與送達有效期限規則。

## 其他串接問題

* **來電號碼與線路**：`GET /telephony` 列出組織的線路、caller\_id、驗證狀態、總線數、保留線路與對外容量。這是共用容量快照，沒有傳回 SIP 帳密；語音供應商上限也可能更低。號碼由後台綁定的線路決定，不接受每通任意偽裝號碼。
* **300 人要多久**：粗估為「300 × 平均振鈴及通話秒數 ÷ 可用對外併發數」。例如每人 60 秒、實際可用 4 路，至少約 75 分鐘，再加排程窗、其他通話與重試。方案寫 5 路不代表 5 路都可同時外撥。加購條件請向 Brightalk 確認。
* **語言與聲音**：沿用後台代理人的語言、聲音與供應商設定；這次沒有新增每通切換聲音或保證特定台語能力的參數。
* **自動化變數**：`POST /automation-runs` 使用既有 `input`，欄位必須事先在自動化宣告；可由 `GET /automations` 的 `input_fields` 確認。它不是把任意欄位寫入 CRM 的入口。
* **遠端 MCP**：既有遠端端點為 `https://api.brightalk.ai/mcp`，驗證與客戶端設定請見 [MCP](https://docs.brightalk.ai/zh-Hant/mcp.md)。本指南說明 REST 串接；MCP 工具各自有輸入規格。
* **電話與簡訊申請**：實名／發送者註冊、內容審核、收件人顯示號碼、錄音與個資告知等，請依您與 Brightalk／電信業者的申請核准文件確認。API 的模組啟用或點數餘額不能取代核准文件。

簡訊批次回應的 `messages` 清單包含每筆訊息 ID、參考編號與狀態，可用該 ID 查詢完整送達結果。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.