跳轉到主要內容
名單超過 1,000 筆時,請使用大型簡訊或撥號任務,每個任務最多 10 萬筆。一般的 /batches 與 /sms-batches 每次最多接受 1,000 筆;下方範例使用這兩個一般批次端點。

適用情境與共用流程

預約確認、活動提醒、到貨取件與服務回訪,都可以使用相同的 API 流程。您的系統提供每位收件人的通知內容與問題,Brightalk 負責執行電話或簡訊,再回傳結果。
  1. 在後台建立使用變數的代理人,設定要收集的結果欄位。
  2. 您的系統依業務事件,建立單通或批次通知,帶入個別資料與排程。
  3. Brightalk 依設定執行,透過簽章 webhook 回傳通話或簡訊結果。
  4. 您的系統用參考編號更新原始紀錄,再決定貼標籤、人工跟進或補發訊息。

一個代理人,多種通知

在後台建立對外撥號代理人,把開場白與提示詞寫成:
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,不會模擬真人接聽或憑空產生逐字稿。
以 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,不是公開下載連結。 驗證下面的標頭:
簽章內容是 timestamp + ”.” + 原始 HTTP body 位元組,使用您在 webhook.secret 設定的秘密。不要先把 JSON 解析再序列化。
驗證成功後,先把事件 ID 與待處理工作持久化,再回覆 2xx。這是至少一次傳遞,同一事件可能收到多次;請用事件 ID 去重。事件沒有跨通話的到達順序保證。失敗會以指數退避重試,最多 10 次;GET /webhook-events/{event_id} 查狀態,耗盡後可用 POST /webhook-events/{event_id}/retry(body {})重新投遞,這不會再打一次電話或再發一封簡訊。 回呼只允許公開 HTTPS 的最終網址、443 連接埠、不跟隨重新導向;私有網路與中繼資料位址會被阻擋。簽章秘密以加密方式保存,查詢結果不會傳回。

依站台與業務流程對帳

需 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 是分段數。
  • 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。本指南說明 REST 串接;MCP 工具各自有輸入規格。
  • 電話與簡訊申請:實名/發送者註冊、內容審核、收件人顯示號碼、錄音與個資告知等,請依您與 Brightalk/電信業者的申請核准文件確認。API 的模組啟用或點數餘額不能取代核准文件。
簡訊批次回應的 messages 清單包含每筆訊息 ID、參考編號與狀態,可用該 ID 查詢完整送達結果。