跳至主要内容

可程式化語音 API

PaaSoo 可程式化語音 API 提供了一套基於 XML 語法的語音腳本語言——PML（PaaSoo Voice Markup Language）。借助 PML，您能夠建構高度客製化的語音流程，涵蓋外呼、呼入、互動式語音應答（IVR）、多語言即時翻譯、錄音、通話控制等多種功能。您可以在同一個可程式化語音 API 中使用這些特性，以滿足不同場景的業務需求，並獲得靈活高效的語音通訊體驗。

1. 概述​

PaaSoo 可程式化語音 API 基於 PML 腳本語言。透過該 API，您可以靈活編排外呼流程、設定 IVR 邏輯、進行多語言翻譯、錄音、以及主動結束通話等操作。部分典型使用場景包括：客戶服務熱線、自動外呼通知、電話會議、跨語言溝通、語音驗證碼、錄音質檢等。

2. 功能一覽​

  3.1 通話外呼：自動發起呼叫，廣泛用於行銷通知、驗證碼等。
  3.2 通話呼入：對來電進行自動化分流，或實現智能客服 IVR 流程。
  3.3 呼叫事件回呼：隨時監控通話狀態（響鈴、連接、掛斷、異常等）。
  4.1 PML主流程（Process）：作為總控制器，協調各個子流程的執行。
  4.2 PML子流程（SubProcess）：實現具體的業務功能模組。
  4.3 條件項目（Items）：提供智能路由決策，實現動態流程跳轉。
  4.4 文字轉語音（TTS）：將文字即時轉換為自然流暢的語音播放。
  4.5 播放音訊（Play）：播放指定音訊檔案，可用在提示音、背景音樂等場景。
  4.6 暫停（Pause）：在語音片段或音訊之間插入停頓，讓播報更連貫。
  4.7 按鍵擷取（Catch）：透過 DTMF 或語音輸入收集用戶資訊並執行邏輯。
  4.8 通話轉接（Forward）：將通話轉移至其他號碼或呼叫中心系統。
  4.9 即時語音翻譯（Translation）：在通話中即時進行多語言翻譯。
  4.10 錄音（Record）：可靈活選擇是否錄製通話並在回呼中取得錄音位址。
  4.11 錄音回呼：錄音結束後回呼通知。
  4.12 計劃流程（Schedule）：根據時間條件執行不同的子流程。
  5 通話中斷：允許主動結束通話或設定倒數計時後自動結束。

3. API 說明​

以下為可程式化語音 API 在外呼、呼入、以及事件回呼三個關鍵環節的技術說明。其中的功能特性（如翻譯、錄音等）需在 PML 腳本中進行配置。

3.1 通話外呼​

透過此功能自動發起外呼。可用於批次通知、語音驗證碼、遠端會議邀請等場景。一次請求即可攜帶 PML 腳本以指定互動流程，靈活實現多級語音引導或按鍵互動。

呼叫方式
  • HTTP Method：POST
  • 請求地址： https://api.paasoo.com.tw/api/calls
  • Content-Type：application/x-www-form-urlencoded

3.1.1 請求參數說明​

參數類型必填描述範例
keystring是API Key（字母或數字構成，共 8 位），用於唯一標識您的帳戶。可在 PaaSoo 用戶端後台取得。Abcdefgh
secretstring是API Secret（字母或數字構成，共 8 位），與 key 配合使用以進行身分驗證。可在 PaaSoo 用戶端後台取得。Abc123EF
fromstring是主叫號碼（Caller ID）。如需自訂，請聯絡技術支援。+85299998888
tostring是被叫號碼，需使用國際格式：國際電話代碼+手機號碼。886912345678
pmlstring是基於 XML 語法的 PML 腳本，定義通話邏輯與功能。<pml>
  <process>
    <tts voice="woman" language="zh-TW">你好。</tts>
  </process>
</pml>
callback_urlstring否事件回呼位址，用於接收呼叫狀態變更。https://example.com/callback
callback_eventstring否發送到回呼 URL 的事件。可同時設定多個事件，用英文逗號分隔。
  • ringing
  • answered
  • completed
  • rejected
ringing
recordboolean否是否開啟錄音。true
recording_callback_urlstring否若開啟錄音，接收錄音通知的回呼位址。https://example.com/record_callback
timeoutinteger否被叫響鈴時間（秒）。
  • 預設 45
  • 最小 15
  • 最大 60
15
time_limitinteger否最大通話時間限制（不填或0表示不限制），當通話時間達到該限制時，系統會立即主動掛斷本次通話。
時間以秒為單位。		120

cURL 範例​

cURL
curl -X POST https://api.paasoo.com.tw/api/calls \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "key=Abcdefgh" \
-d "secret=Abc123EF" \
-d "from=85299998888" \
-d "to=886912345678" \
-d "pml=<pml><process><tts language="zh-TW">你好。</tts></process></pml>" \
-d "callback_url=https://example.com/call_events" \
-d "callback_event=ringing,answered,completed"

3.1.2 回應參數說明​

3.1.2.1 成功範例​
{
    "status": "0",
    "call_id": "400157-3d1875-7000"
}
3.1.2.2 失敗範例​
{
    "status": "2",
    "status_details":"Missing parameters"   
}
3.1.2.3 回應參數說明​
參數類型描述範例
call_idstring整個批次的處理結果。0 表示成功接收並處理請求。0
statusstring回應狀態。提交至 PaaSoo 雲通訊平台的回應狀態碼。一般來說，0 代表成功。0 - success
status_detailsstring狀態描述資訊，用於說明錯誤原因或詳細狀態。Missing parameters

3.1.3 介面狀態碼列表​

  • 0 - success：成功
  • 2 - Missing parameters：缺少必要參數
  • 3 - Invalid parameters：參數格式錯誤
  • 4 - Invalid credentials：Key或Secret錯誤
  • 5 - Unauthorized IP：IP限制
  • 6 - Invalid phone number：號碼格式錯誤
  • 7 - Invalid sender id：from參數格式錯誤
  • 8 - Message bombing detected：3秒內重複請求
  • 9 - Quota exceeded：欠費或信用額度不足
  • 10 - Throttling error：超過限速
  • 11 - System error：系統錯誤

3.2 通話呼入​

當用戶呼入配置好的電話號碼或虛擬中間號時，PaaSoo 會向您配置的 Webhook 請求一次，以取得應該如何處理該來電（即返回 PML 腳本或子流程）。 由此可實現自動分流、身分驗證、自助服務等高度靈活的 IVR 場景。

呼叫方式
  • HTTP Method: GET
  • 請求地址: https://example.com/webhook?key=Abcdefgh&caller=85299998888&mo_number=85211111111111&callid=400157-3d1875-7000

3.2.1請求參數說明​

參數類型必填描述範例
keystring是API Key（字母或數字構成，共 8 位），用於唯一標識您的帳戶。可在 PaaSoo 用戶端後台取得。Abcdefgh
callerstring是主叫號碼（CLI）。85299998888
mo_numberstring是用戶撥打的號碼（虛擬或直連）。85211111111111
callidstring是呼叫唯一ID。400157-3d1875-7000
說明

在收到此請求後，您的服務需返回一段 PML 或 XML，用於指示後續 IVR 或自動語音操作措施。 若無法返回有效 PML，來電將終止。
HTTP/1.1 200 OK
Content-Type: text/xml

PML
<process>
    <tts voice="woman" language="zh-TW">歡迎致電技術支援，請按1；查詢訂單，請按2。</tts>
</process>

3.3 呼叫事件回呼​

整個通話過程中，PaaSoo 平台會根據您在外呼或號碼配置裡填寫的 callback_url，向其發送通話狀態（如 ringing、answered、completed、rejected）以便您進行後續業務邏輯。

呼叫方式
  • HTTP Method: POST
  • Content-Type: application/x-www-form-urlencoded

3.3.1請求參數說明​

參數類型必填描述範例
keystring是API Key（字母或數字構成，共 8 位），用於唯一標識您的帳戶。可在 PaaSoo 用戶端後台取得。Abcdefgh
call_idstring是唯一呼叫 ID。015bd4-d6dfa7-58w
eventstring是當前呼叫事件。可同時設定多個事件，用英文逗號分隔。
  • ringing
  • answered
  • completed
  • rejected
answered
event_timestring是事件發生時間（UTC+0）。2024-12-01 00:00:00
parent_idstring否若有轉接或子呼叫，則此處表示父級呼叫 ID。400157-3d1875-7000
hangup_causestring否掛斷原因描述，可對照《SIP 掛斷原因代碼參考表》。USER_BUSY
hangup_codestring否掛斷原因代碼，可對照《SIP 掛斷原因代碼參考表》。USER_BUSY
error_codestring否如有錯誤，則此處給出錯誤碼。1001
error_msgstring否錯誤描述。Insufficient sessions
POST https://example.com/call_events
Content-Type: application/x-www-form-urlencoded

call_id=015bd4-d6dfa7-58w&event=completed&event_time=2024-12-01+10%3A18%3A06

4. PML - 標籤與用法​

PML 是一個基於 XML 結構的腳本語言，可助您以簡潔方式設計語音流程。 根元素一般為 <pml>...</pml>，內部包含若干 <process>、<subprocess> 等節點。 下列為常見功能標籤說明：

4.1 Process （PML的主流程）​

PML 的根元素，作為業務流程的入口。每個 PML 腳本中只能有一個 <process> 根元素。

PML
<pml>
    <process id="main">
        <tts voice="woman" language="zh-TW">你好。</tts>
    </process>
</pml>

4.1.1 流程ID​

流程ID是流程的唯一標識符，當需要從一個流程跳轉至另一個流程時，此ID將作為跳轉目標被引用。

  • 順序執行場景：如果 <process> 和 <subprocess> 是順序執行且無需跳轉，可不指定 ID。
  • 流程跳轉場景：如需跳轉，則需要為 <process> 和每個 <subprocess> 設定唯一 ID。

範例

PML
<pml>
    <process id="main">
    .....
    </process>
    <subprocess id="proc-zh-tw">
    .....
    </subprocess >
    <subprocess id="proc-ja-jp">
    .....
    </subprocess >
</pml>

4.2 SubProcess（PML的子流程）​

代表一個可重複使用的業務邏輯模組。透過將特定功能（如身分驗證、選單導航）封裝為子流程，可以簡化主流程結構，提高程式碼的複用性和可維護性。

範例

PML
<subprocess>
    <play>https://example.com/audio/welcome.mp3</play>
</subprocess>

4.3 Items（條件項目）​

在一些複雜的應用場景中，可透過組合一個 <process> 與多個 <subprocess>，建構出符合需求的完整業務流程。在運行過程中，系統能夠根據用戶輸入（如按鍵選擇或語音指令）進行條件判斷，實現從 <process> 到 <subprocess>，或在不同 <subprocess> 之間的靈活跳轉，從而動態響應用戶操作。

<items> 標籤通常與其它的標籤組合使用。比如與 <catch> 組合，根據用戶的輸入內容與 <item> 的條件進行匹配並跳轉到相應的子流程 <subprocess>。

範例

PML
<pml>
    <process id="main">
        <catch timeout="60" keys="1" end_key="#" input="DTMF">
            <tts voice="woman" language="ja-JP">ようこそ。日本語を選ぶには1を押してください。</tts>
            <tts voice="woman" language="en-US">For English, please press 2。</tts>
            <tts voice="woman" language="zh-TW">若要選擇普通話，請按3。</tts>
            <tts voice="woman" language="zh-HK">如需廣東話，請按4。</tts>
            <tts voice="woman" language="ko-KR">한국어를 선택하려면 5를 누르세요。 </tts>
            <tts voice="woman" language="fr-FR"> Pour discuter en français, appuyez sur 6.</tts>
            <items>
                <item value="1" next_process="@proc-ja-jp"></item>
                <item value="2" next_process="@proc-en-us"></item>
                <item value="3" next_process="@proc-zh-tw"></item>
                <item value="4" next_process="@proc-zh-hk"></item>
                <item value="5" next_process="@proc-ko-kr"></item>
                <item value="6" next_process="@proc-fr-fr"></item>
            </items>
        </catch>
    </process>
    <subprocess id="proc-ja-jp">
        <forward from="815030322222">
            <tts voice="woman" language="ja-JP">転送中。</tts>
            <play>https://example.com/phone-call.mp3>
            <to>886912345678</to>
        </forward>
    </subprocess >
    ......
</pml>

4.3.1 條件匹配機制​

<items> 包含多個 <item> 條件項，系統按順序將用戶輸入與每個 <item> 的 value 值進行匹配，匹配成功則執行相應的子流程。

匹配方式：

  • 字串精確匹配：輸入內容與 value 值完全一致時匹配成功。
  • 正規表達式匹配：輸入內容符合 value 值的正規表達式規則時匹配成功。

4.3.2 流程跳轉​

當條件匹配成功後，可透過 next_process 屬性指定要跳轉的目標流程。

  • next_process：指定匹配成功後要跳轉的目標流程。
  • 跳轉語法：@proc-ja-jp 表示跳轉到 id="proc-ja-jp" 的子流程，@ 符號用於指示目標流程的 ID。

4.3.3 執行流程​

系統按 <item> 的順序依次進行條件匹配：

  • 第一個匹配成功的條件將觸發流程跳轉。
  • 如無任何條件匹配成功，流程將繼續執行後續操作。

4.4 TTS（文字轉語音）​

將文字內容轉成語音播放。可自訂語言、音色、速率、音量等。 常見應用場景：電話通知、報選單、語音驗證碼內容等。

4.4.1請求參數說明​

參數類型必填描述範例
languagestring是文字到語音（TTS）語言zh-TW
voicestring否聲音。
  • 女聲（預設）： woman
  • 男聲：man
woman
volumestring否語音的音量級別。
絕對值：以從 0.0 到 100.0（從最安靜到最大聲，例如 75）的數字表示，預設值為 100.0。
或使用常數值：
  • silent（0）-靜音
  • x-soft（20）-非常小的音量
  • soft（40）-小音量
  • medium（60）-中等音量
  • loud（80）-大音量
  • x-loud（100，預設值）-非常大的音量
100

文字內容中可以添加兩個可選參數

參數類型屬性描述範例
breakstringtime可以根據您個人的需求設定間隔的秒數或是毫秒數。<break time="1s"/>
prosodyfloatrate可以設定語音播放速度的比率，值在0～3之間，預設基準語速為1。<prosody rate="0.1"> Your code 1,2,3,4,5. </prosody>

4.4.2 支援的 TTS 語言​

點擊查看詳細的支援的 TTS 語言。

4.5 Play（播放音訊）​

可播放外部 URL 的音訊檔案（如 .mp3、.wav），在 IVR 提示音或廣告語音等場景適用。 檔案需可公網存取，並保證採樣率相容（8KHz）。

範例

PML
<pml>
    <process>
        <play> https://example.com/audio/welcome.mp3 </play>
    </process>
</pml>

4.6 Pause（暫停）​

在 TTS 或音訊片段間插入可控停頓，讓語音更自然。與 <break> 類似，但一般用於 TTS 片段外部的「流程節點間暫停」。

4.6.1請求參數說明​

參數類型必填描述範例
durationstring是暫停時間，以毫秒為單位。100ms

範例

PML
<pml>
    <process>
        <tts language="zh-TW">我們將暫停半秒鐘...</tts>
        <pause duration="500ms"/>
        <tts language="zh-TW">現在繼續。</tts>
    </process>
</pml>

4.7 Catch（按鍵擷取）​

本介面用於在語音呼叫中透過 DTMF（雙音多頻信號，即按鍵輸入） 或 SPEECH（語音識別） 方式收集用戶輸入。適用於實現多級 IVR 選單、身分驗證（如驗證碼輸入）、語音指令識別等場景。

互動模式說明：

  • DTMF模式：系統播放 TTS 提示音（如：「請輸入訂單號並按#號結束」），用戶透過電話鍵盤輸入數字和符號。輸入達到指定鍵數或遇到結束符時，輸入完成。
  • SPEECH模式：系統播放 TTS 提示音（如：「請說出您的需求，例如『銷售』或『支援』」），用戶透過語音應答。語音識別引擎將語音轉換為文字結果。

允許的子標籤： 在 <catch> 標籤內部，當前支援以下子標籤，用於控制提示播放與輸入結果分流等行為：TTS、Play、Pause、Items。

4.7.1 請求參數說明​

參數類型必填描述範例
keysinteger是指定期望擷取的 DTMF 按鍵數量。當用戶輸入的按鍵數達到此數量時，擷取流程立即結束。此參數僅對 DTMF 輸入有效。

keys 與 end_key 為並列終止條件。若同時設定，滿足任一條件（按鍵數達標或按下結束鍵），擷取流程立即結束。		3
end_keystring否指定一個或多個用於立即結束 DTMF 擷取的終止鍵。當用戶按下此處定義的任意一個字元時，擷取流程立即結束。
適用於 DTMF 、DTMF SPEECH模式。
  • 格式： 多個字元應直接連續書寫，無需任何分隔符（例如：#*0 表示井號、星號或數字0均可作為結束鍵）。
  • 可選值： #, *, 0-9
  • 預設值： #
keys 與 end_key 為並列終止條件。若同時設定，滿足任一條件（按鍵數達標或按下結束鍵），擷取流程立即結束。		#, *, 0-9
inputstring否輸入模式。指定接受的輸入類型。支援一個或多個值，多個值用空格分隔。
  • DTMF：僅接受按鍵輸入
  • SPEECH：僅接受語音輸入
  • DTMF SPEECH：同時接受兩種輸入模式，優先處理先收到的有效輸入
預設值：DTMF		DTMF SPEECH
languagestring否語音識別語言。當 input 包含 SPEECH 時，此參數為必填。指定語音識別引擎使用的語言模型。zh-TW
hintsstring否指定關鍵詞或短語，如：專用詞彙、常用表達或預期的用戶回答。用於輔助語音引擎，提升 PaaSoo 語音引擎的識別準確率，尤其適用於那些可能被誤聽或忽略的詞語。
  • 多個關鍵詞之間用英文逗號 (,) 或分號 (;) 分隔；
  • 最多支援500個關鍵詞或短語；
  • 僅適用於 SPEECH 模式。
PaaSoo 技術支援,餘額查詢
max_durationinteger否Catch 操作最長可支援的時間（單位：秒）。從開始播放提示音起計時，超過此時間無論是否有輸入，本次擷取操作都將強制結束。
  • 預設值：30
  • 取值範圍：必須為正整數
  • 超時處理：超時後系統將繼續執行後續流程
15
speech_timeoutinteger否語音輸入停頓之後最長的等待時間（單位：秒）。PaaSoo 檢測到語音暫停後的等待時間，超過此時間則本次 Catch 操作將被強制結束。
  • 取值範圍：0 或正整數
  • 預設值：0（在檢測到第一個語音暫停時立即停止識別）
  • 適用模式：僅適用於 SPEECH 模式
3
repeatinteger否如果用戶在設定的超時時間內，沒有任何輸入，則重複執行本 Catch 的次數。必須輸入正整數數值。3
event_urlstring否指定一個用於接收用戶輸入完成事件的回呼 URL。
  • 當用戶輸入完成後，系統會向此 URL 發起回呼請求。
  • 您的服務可根據回呼資訊決定後續流程。
回呼參數見下方 4.7.2 event_url 回呼參數說明		https://example.com/event

4.7.2 event_url 回呼參數說明​

參數類型必填描述範例
call_idstring是呼叫的唯一 ID，每條語音記錄的唯一標識。400157-3d1875-7000
inputstring是用戶輸入的按鍵，或語音輸入識別後的文字你好

範例：按鍵輸入

PML
<pml>
    <process>
        <catch event_url="https://example.com/event" keys="4" end_key="#" timeout="10">
            <tts language="zh-TW">請輸入4位密碼，然後按#鍵。</tts>
        </catch>
        <tts language="zh-TW">您的輸入已記錄，謝謝。</tts>
    </process>
</pml>

在執行過程中，系統會將用戶的輸入資訊透過回呼發送到您配置的 event_url。

回呼請求範例：

cURL
curl -X POST https://example.com/event \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "call_id=a003fb-36d1f0-1000&input=1234"

  • 若回呼的 URL 位址回應返回子流程指令：

    PML
    <subprocess>
        <tts voice="woman" language="zh-TW">密碼驗證已通過，再見。</TTS>
    </subprocess>

    則跳入子進程的流程。

  • 若回呼的 url 位址回應返回返回 200 OK： 則忽略返回的內容，主進程繼續執行。

範例：語音/按鍵輸入
在收集用戶的輸入（按鍵或語音）,根據用戶的選擇，可以執行不同的子流程 forSales，forSupport。

PML
<pml>
    <process>
        <catch input="DTMF SPEECH" keys="1" language="zh-TW" timeout="10">
            <tts language="zh-TW">如需銷售服務，請按1或說銷售。如需技術支援，請按2或說支援。</tts>
            <items>
                <item value="1|銷售" next_process="@forSales"/>
                <item value="2|支援" next_process="@forSupport"/>
            </items>
        </catch>
    </process>
    <subprocess id="forSales">
        <tts language="zh-TW">您選擇了銷售服務，謝謝。</tts>
    </subprocess>
    <subprocess id="forSupport">
        <tts language="zh-TW">您選擇了技術支援，謝謝。</tts>
    </subprocess>
</pml>

4.8 Forward（通話轉接）​

將當前通話（包括來電或外呼）無縫轉接至另一號碼或業務系統（如 IVR、坐席）。系統將自動結束與原終端的連接，並建立與新目標的連接，同時保持通話會話的連續性。

場景範例：客服人員將來電轉接給資深工程師；透過中轉號碼連接至第三方系統。

允許的子標籤： 在 <forward> 標籤內部，當前支援以下子標籤，用於在轉接前或轉接過程中進行語音提示或語音翻譯等處理：TTS、Translation。

4.8.1 請求參數說明​

參數類型必填描述範例
callback_urlstring否用於接收子呼叫事件的回呼 URL。callback_url="https://example.com/call"
recordstring否記錄子呼叫的選項：
  • do-not-record（不進行通話錄音）；
  • record-from-answer（從電話接通開始錄音 ）；
  • record-from-ringing（從電話開始響鈴時錄音 ）；
  • record-from-answer-dual（雙向錄音，從通話接通開始 ）；
  • record-from-ringing-dual（雙向錄音，從電話響鈴時開始 ）。
record-from-answer-dual
recording_callback_urlstring否用於接收錄音狀態的回呼 URL。https://example.com/recording
recording_callback_methodstring否於發送記錄狀態的回呼方法，當前只支援 POST。POST
fromstring否子呼叫的主叫號碼（Caller ID）。如需自訂，請聯絡技術支援。+85299998888
tostring是子呼叫的被叫號碼，需使用國際格式：國際電話代碼+手機號碼。886912345678
timeoutinteger否響鈴時間，以秒為單位；
  • 預設值為 45，
  • 最小值為 15，
  • 最大值為 60。
15

範例

PML
<pml>
    <process>
        <forward from="85299998888" record="record-from-answer" callback_url="https://example.com/child_call_events">
            <to>886912345678</to>
            <tts language="zh-TW">正在為您轉接。</tts>
        </forward>
    </process>
</pml>

4.9 Translation（即時語音翻譯）​

PaaSoo 的即時通話翻譯功能（Translation）允許您在雙向通話過程中，即時識別並翻譯通話雙方的語音內容。該功能基於 AI 技術，支援跨語言的即時交流，適用於國際商務會議、多語種客服支援等場景。

您可以透過 API 靈活地調整翻譯語言、語音、音量等設定，以滿足個性化業務需求。

4.9.1 請求參數說明​

參數類型必填描述範例
fromstring.是通話發起方的源語言代碼。指定通話發起方的語音識別語言，並作為接收對方語音翻譯的目標語言。zh-TW
tostring是通話接收方的源語言代碼。指定通話接收方的語音識別語言，並作為通話發起方語音翻譯的目標語言。此參數與 from 共同構成雙向翻譯通道。ja-JP
volumeinteger否在翻譯過程中，設定雙方原始語音的音量大小，0~100。
如：100 為原始音量，設定為 40 即通話雙方按 40% 的音量播放。
預設：0，沒有原始聲音。		30

範例：中文 to 日文

PML
<pml>
    <process>
        <tts language="zh-TW">開始在此通話中進行即時翻譯。</tts>
        <forward from="886912345678">
            <translation from="zh-TW" to="ja-JP" volume="30"></translation>
            <to>815031111111</to>
        </forward>
    </process>
</pml>
說明

<translation from="zh-TW" to="ja-JP" volume="30"></translation>：表示將通話發起方的語言由中文翻譯成日文，通話雙方的原始音量為30%。

4.9.2 翻譯後語音內容的個性化設定​

在 <translation> 標籤內，也可增加 <from> 和 <to> 標籤，對通話雙方（通話發起方和通話接收方）聽到的翻譯內容做更細化的設定。

注意：這裡的 <from> 和 <to> 標籤是用於設定語音翻譯內容在發送給通話發起方和通話接收方時的播放屬性（如聲音、音量），而不是控制他們的原始通話語音。

4.9.2.1 參數說明​
參數類型必填描述範例
voicestring否用於設定即時翻譯後的語音內容的聲音：
  • 女聲（預設）：woman
  • 男聲：man
woman
volumestring否用於設定即時翻譯後的語音內容的音量級別。
絕對值：以從 0.0 到 100.0（從最安靜到最大聲，例如 75）的數字表示，預設值為 100.0。
或使用常數值：
  • silent（0）-靜音
  • x-soft（20）-非常小的音量
  • soft（40）-小音量
  • medium（60）-中等音量
  • loud（80）-大音量
  • x-loud（100，預設值）-非常大的音量
loud

範例：中文 to 日文

PML
<pml>
    <process>
            <tts language="zh-TW">開始在此通話中進行即時翻譯。</tts>
            <forward from="886912345678">
                <translation from="zh-TW" to="ja-JP" volume="30">
                        <from voice="man" volume="100"/>
                        <to voice="man" volume="90"/>
                </translation>
                <to>815031111111</to>
            </forward>
    </process>
</pml>
說明

<from voice="man" volume="100"/>：表示通話發起方的說話內容經即時翻譯後，通話接收方聽到的聲音是男聲，音量是100%；
<to voice="man" volume="90"/>：表示通話接收方的說話內容經即時翻譯後，通話發起方聽到的聲音是男聲，音量是90%。

範例：用戶按鍵選擇目標語言

PML
<pml>
    <process id="langselect">
        <catch keys="1" end_key="#" timeout="15">
            <tts language="zh-TW">英語翻譯成中文請按1，英語翻譯成法語請按2。</tts>
            <items>
                <item value="1" next_process="@tozh"/>
                <item value="2" next_process="@tofr"/>
            </items>
        </catch>
    </process>
    <subprocess id="tozh">
        <forward from="85299998888">
            <translation from="en-US" to="zh-TW"/>
            <to>886912345678</to>
        </forward>
    </subprocess>
    <subprocess id="tofr">
        <forward from="85299998888">
            <translation from="en-US" to="fr-FR"/>
            <to>33123456789</to>
        </forward>
    </subprocess>
</pml>

4.10 Record（錄音）​

該功能允許在通話進行時，對通話一方/雙方的音訊流進行錄製。錄製完成後將透過回呼事件返回錄音檔案的存取位址。通常用於服務品質檢查、糾紛留證或員工培訓等場景。

4.10.1 請求參數說明​

參數類型必填描述範例
max_timeinteger否最大錄音時間（單位：秒）。錄音達到該時間後自動結束。60
end_keystring否指定一個或多個用於立即結束錄音的終止鍵。當用戶按下此處定義的任意一個字元時，錄音立即結束。
  • 格式： 多個字元應直接連續書寫，無需任何分隔符（例如：#*0 表示井號、星號或數字0均可作為結束鍵）。
  • 可選值： #, *, 0-9
#，*，0-9
recording_callback_urlstring否錄音狀態回呼 URL。用於接收錄音過程中的狀態事件通知。https://example.com/recording

範例

PML
<record max_time="60" end_key="#" recording_callback_url="https://example.com/recording_callback"/>

4.11 錄音回呼​

當錄音完成或進行中，會向 recording_callback_url 發送事件，含錄音時間、錄音下載位址等重要資訊。

呼叫方式

HTTP Method： POST

4.11.1 回呼參數說明​

參數類型必填描述範例
call_idstring是錄製的子呼叫的唯一 ID。015bd4-d6dfa7-58w
channelsinteger是錄音檔案的聲道類型：
  • 1單聲道
  • 2雙聲道
2
durationinteger是錄音時間（秒）。僅在 event=record_completed 事件時有效。60
urlstring否錄音存放的位址。僅在 event=record_completed 事件時有效。https://example.com/recording_callback
eventstring是事件類別：
  • record_inprocess
  • record_completed
record_inprocess
event_timestring是錄製開始時間 (UTC+0)。2024-12-01 00:00:00
keystring是API Key（字母或數字構成，共 8 位），用於唯一標識您的帳戶。可在 PaaSoo 用戶端後台取得。Abcdefgh
parent_idstring.否父級呼叫的唯一 ID，每條語音記錄的唯一標識。400157-3d1875-7000

回呼範例

POST https://example.com/recording_callbackcall_id=015bd4-d6dfa7-58w&channels=2&duration=60&event=record_completed&url=https%3A%2F%2Fusermedia%2Ffiles%2Fcall015bd4d6.wav

4.12 Schedule（計劃流程）​

由 <schedule> 和 <items> 標籤組合，PML 可以根據不同的時間條件，執行不同的 <subprocess>。

4.12.1 請求參數說明​

參數類型必填描述範例
timezonestring否時區參數，取值範圍：-12至+12。
  • 支援式："+6"、"-06"、"+05:45"，可描述為：timezone="+6"；
  • 將 UTC 時間轉換為指定時區的本地時間；
  • 預設值：UTC 時間。
+6
weekdaystring否星期幾，數字1~7，分別代表週一到週日。
採用正規表達式方式匹配。		[1-5]
datestring否日期匹配模式，格式為："YYYY-MM-dd"。
採用正規表達式方式匹配。
如匹配2025年1月1日和2日兩天，date="^2025-01-01|02"。		^2025-01-01|02
timestring否時間匹配模式，格式為："HH:mm:ss"。
採用正規表達式方式匹配。
如要符合在工作時間段內的條件，time="^(08|09|10|11|14|15|16|17)" 。		^(08|09|10|11|14|15|16|17)

範例：工作時間執行 subprocess "process_workday"，非工作時間執行 subprocess "process_non-working"。

PML
<schedule timezone="-06:00">
    <items>
        <item weekday="[1-5]" time="^(08|09|10|11|14|15|16|17)" next_process="@process_workday"/>
        <item weekday="6|7"next_process="@process_non-working"/>
        <item next_process="@process_default"/>
    </items>
</schedule>
<subprocess id="process_workday">
    <tts language="zh-TW">您好，很高興為您服務，請問有什麼可以幫您。</tts>
    ......
</subprocess>
<subprocess id="process_non-working">
    <tts language="zh-TW">您好！當前為週末非服務時間。客服工作時間：週一至週五 8:00-17:00。請於下週一該時段內諮詢，謝謝！祝您週末愉快！</tts>
    ......
</subprocess>
<subprocess id="process_default">
    <tts language="zh-TW">您好！當前客服已離線。服務時間為週一至週五 8:00-17:00，請在此時間段內諮詢，謝謝！</tts>
    ......
</subprocess>

4.12.2 匹配規則​

weekday, date, time的條件匹配，採用正規表達式方式匹配。

如果同時指定了 weekday, date, time 中的多個條件，則需要多個條件都滿足才算匹配成功。

PML
<item time="^(08|09|10|11|14|15|16|17)" weekday="[1-5]" next_process="@process_workday"/>

5. 通話中斷（結束）​

您可在 API 中主動結束通話（或設定一個倒數計時後自動結束），防止異常長時間占用線路或根據業務邏輯在必要時結束通話。

呼叫方式
  • HTTP Method：POST
  • 請求地址：https://api.paasoo.com.tw/api/calls/update

5.1 請求參數說明​

參數類型必填描述範例
keystring是API Key（字母或數字構成，共 8 位），用於唯一標識您的帳戶。可在 PaaSoo 用戶端後台取得。Abcdefgh
secretstring是API Secret（字母或數字構成，共 8 位），與 key 配合使用以進行身分驗證。可在 PaaSoo 用戶端後台取得。Abc123EF
call_idstring是外呼返回的唯一 ID。400157-3d1875-7000
statusstring是結束通話固定值：completedcompleted
timerinteger否倒數計時後結束通話（秒），0 表示立即結束。60

5.2 cURL 範例​

cURL
curl -X POST "https://api.paasoo.com.tw/api/calls/update" \
-d "key=Abcdefgh" \
-d "secret=Abc123EF" \
-d "call_id=400157-3d1875-7000" \
-d "status=completed" \
-d "timer=0"

5.3 返回參數說明​

5.3.1 成功範例​

{
    "call_id": "400157-3d1875-7000",
    "status": "0"
}

5.3.2 失敗範例​

{
    "call_id": "400157-3d1875-7000",
    "status_details":"Missing parameters",
    "status":"2"
}
參數類型描述範例
call_idstring結束通話的唯一 ID。400157-3d1875-7000
statusstring回應狀態碼。
  • 0 - success：成功
  • 2 -Missing parameters：缺少必要參數
  • 3-Invalid parameters：參數格式錯誤
  • 4 -Invalid credentials：Key或Secret錯誤
  • 5 -Unauthorized IP：IP限制
  • 11 - System error：系統錯誤
  • 31 - Call id does not exist：通話ID不存在
  • 32-Call not in progress：通話未進行中
0 - success
status_detailsstring狀態描述。Missing parameters

6. 不同行業及場景範例​

本章節將提供一些綜合範例，幫助您更好地理解如何透過 PML 組合不同功能實現豐富的用例。

6.1 零售/電商行業：自動催付或通知​

此流程旨在透過自動外呼，高效地完成付款提醒與客戶付款狀態確認的閉環管理。系統能主動觸達客戶，並將客戶的按鍵反饋即時回傳至業務系統，從而自動化營運流程，減少人工介入。

流程說明
  • 播報提醒：呼叫接通後，首先語音通知客戶存在未付款訂單及付款期限。
  • 等待確認：短暫停頓後，引導已完成付款的客戶透過特定按鍵組合（如1+#）進行確認。
  • 狀態上報：若客戶按下指定按鍵，系統會立即將此事件（如按鍵值）作為回呼資訊發送至指定的 event_url，業務伺服器可據此更新訂單狀態。
  • 禮貌結束：無論客戶是否進行按鍵操作，流程最後都會播放感謝語，然後禮貌結束通話。

PML 範例

PML
<pml>
    <process>
        <tts language="zh-TW">您好，您有一筆尚未完成的訂單，請在兩個工作日內盡快完成付款。</tts>
        <pause duration="1s"/>
        <catch event_url="https://example.com/payment_response" keys="1" end_key="#" timeout="10">
            <tts language="zh-TW">如已完成支付，請按1，並按 # 結束。</tts>
        </catch>
        <tts language="zh-TW">感謝您對我們的支持，祝您購物愉快。</tts>
    </process>
</pml>

6.2 銀行/金融行業：多語言客服與錄音​

此流程旨在為國際客戶提供便捷的多語言服務接入點。透過自動語音選單讓客戶選擇所需的翻譯語種，並自動轉接至相應坐席，同時開啟通話錄音以用於服務品質監控與合規存檔。

流程說明
  • 服務引導：呼叫接通後，播放歡迎語並提示語言選擇（如：中文服務按1，法語服務按2）。
  • 按鍵選擇：客戶根據提示按下對應按鍵，選擇需要的翻譯服務。
  • 轉接與翻譯：系統根據選擇，將通話轉接至相應語言坐席，並啟用即時雙向語音翻譯功能。
  • 通話錄音：在轉接後的通話全程進行雙向錄音，錄音檔案位址將透過回呼 URL 推送至指定伺服器。

PML 範例

PML
<pml>
    <process>
        <tts voice="woman" language="en-US">Welcome to our banking services.</tts>
        <tts voice="woman" language="en-US">For quality assurance and to protect your rights, this call will be recorded. For English, please press 1.</tts>
        <tts voice="woman" language="zh-TW">為確保服務品質和保障您的權益，本次通話將被錄音。中文服務請按2。</tts>
        <tts voice="woman" language="fr-FR">Pour assurer la qualité de service et garantir vos droits, cet appel sera enregistré. Pour le service en français, appuyez sur le 3.</tts>
        <catch keys="1" end_key="#" timeout="10">
            <items>
                <item value="1" next_process="@enlang"/>
                <item value="2" next_process="@cnlang"/>
                <item value="3" next_process="@frlang"/>
            </items>
        </catch>
    </process>
    <subprocess id="enlang">
        <forward from="123456789" record="record-from-answer-dual" recording_callback_url="https://example.com/record_callback">
            <to>1122334455</to>
        </forward>
    </subprocess>
    <subprocess id="cnlang">
        <forward from="123456789" record="record-from-answer-dual" recording_callback_url="https://example.com/record_callback">
            <translation from="zh-TW" to="en-US" volume="30"/>
            <to>1122334455</to>
        </forward>
    </subprocess>
    <subprocess id="frlang">
        <forward from="123456789" record="record-from-answer-dual" recording_callback_url="https://example.com/record_callback">
            <translation from="fr-FR" to="en-US" volume="30"/>
            <to>1122334455</to>
        </forward>
    </subprocess>
</pml>

6.3 教育/培訓行業：知識問答 IVR​

此流程旨在透過互動式語音應答（IVR）系統，實現自動化的知識測驗、培訓考核或互動遊戲。它利用按鍵收集功能創建多分支流程，根據用戶回答提供即時反饋，適用於課後鞏固、知識測評等場景。

流程說明
  • 歡迎與引導：呼叫開始後，播放歡迎語並介紹問答規則。
  • 播報題目與選項：系統提出預設問題，並給出對應的按鍵選項（如：按1選擇A，按2選擇B）。
  • 等待與收集答案：系統等待用戶在限定時間內按下按鍵。
  • 判斷與反饋：根據用戶按下的按鍵值，跳轉至對應的子流程（如「回答正確」或「回答錯誤」），並播放相應的反饋語音。

PML 範例

PML
<pml>
    <process>
        <tts language="zh-TW">歡迎致電培訓中心，請根據語音提示進行課程問答。</tts>
        <catch keys="1" timeout="10">
            <tts language="zh-TW">題目：HTML 是什麼的縮寫？按1表示超文本標記語言，按2表示其他。</tts>
            <items>
                <item value="1" next_process="@correct"/>
                <item value="2" next_process="@wrong"/>
            </items>
        </catch>
    </process>
    <subprocess id="correct">
        <tts language="zh-TW">回答正確！感謝參與。</tts>
    </subprocess>
    <subprocess id="wrong">
        <tts language="zh-TW">回答錯誤，下次再來挑戰吧。</tts>
    </subprocess>
</pml>

7. 最佳實踐與注意事項​

  1. 介面安全與加密：

    • 傳輸安全：所有 API 請求必須使用 HTTPS 協定，對通訊內容進行端到端加密，防止資料在傳輸過程中被竊聽或篡改。
    • 金鑰管理：API Key 與 Secret 是存取服務的核心憑證，必須透過環境變數或金鑰管理服務進行加密儲存，嚴禁在用戶端程式碼或設定檔中以明文形式出現。

  2. 語言與音色選擇：

    • 語言匹配：TTS（語音合成）的語言和口音需與目標用戶完全匹配。上線前應進行充分測試，確保發音、語速和停頓自然流暢。
    • 多語言支援：如需多語言播報，可靈活運用 <translation> 標籤。建議為每種語言單獨測試，以確保翻譯準確性和語音品質。

  3. 流程設計：

    • 模組化設計：使用 <process> 或 <subprocess> 標籤將複雜的語音流程劃分為獨立的模組。這有助於提高程式碼的可讀性、可維護性和複用性。
    • 導航與容錯：設計多級選單時，必須提供明確的超時處理機制和錯誤按鍵引導，確保用戶在任何狀態下都能順利退出或返回，避免陷入死循環。

  4. 錄音保護與合規：

    • 資料合規：錄音檔案可能包含個人敏感資訊，其儲存、處理和保護必須嚴格遵守業務所在地（如 GDPR）的資料隱私法規。
    • 資源優化：合理設定 max_time（最大錄音時間）和 end_key（結束按鍵），防止因無聲、空錄音或用戶離席導致系統資源被無效占用。

  5. 跨語言通話注意事項：

    • 識別侷限性：AI 翻譯的準確性在很大程度上依賴於語音識別的效果。應為用戶提供備選方案，例如「語言切換」功能或「轉接人工客服」的選項。
    • 通話環境：建議用戶在一個相對安靜的環境下進行通話，以減少背景噪音對語音識別準確度的干擾。

  6. 通話結束管理：

    • 主動資源回收：可利用「通話中斷」功能，主動結束異常長時間的通話，釋放系統資源，控制成本。
    • 事後處理：透過監聽呼叫事件的 completed 狀態，可以在通話結束後自動觸發後續操作，如產生帳單、更新客戶狀態或進行資料分析。

總結​

PaaSoo 可程式化語音 API 兼具靈活與高效，能夠滿足各行各業對語音互動的核心需求： 從基本的外呼/呼入處理，到複雜的多語言翻譯、錄音質檢、IVR 多級選單等，皆可透過 PML 直觀實現。

技術支援

如在 API 對接過程中遇到任何技術問題或業務疑問，歡迎隨時聯絡我們的開發者支援團隊：support@paasoo.com。我們將竭誠為您提供技術協助。