跳到主要内容

可编程语音 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.cn/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是被叫号码，需使用国际格式：国家区号+手机号码。8618911111111
pmlstring是基于 XML 语法的 PML 脚本，定义通话逻辑与功能。<pml>
  <process>
    <tts voice="woman" language="zh-CN">你好。</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.cn/api/calls \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "key=Abcdefgh" \
-d "secret=Abc123EF" \
-d "from=85299998888" \
-d "to=8618911111111" \
-d "pml=<pml><process><tts language="zh-CN">你好。</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-CN">欢迎致电技术支持，请按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-CN">你好。</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-cn">
    .....
    </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-CN">若要选择普通话，请按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-cn"></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>8618605927788</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-CN
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 支持语言列表​

点击查看详细的支持语言列表。

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-CN">我们将暂停半秒钟...</tts>
        <pause duration="500ms"/>
        <tts language="zh-CN">现在继续。</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-CN
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-CN">请输入4位密码，然后按#键。</tts>
        </catch>
        <tts language="zh-CN">您的输入已记录，谢谢。</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-CN">密码验证已通过，再见。</TTS>
    </subprocess>

    则跳入子进程的流程。

  • 若回调的url地址响应返回返回 200 OK： 则忽略返回的内容，主进程继续执行。

示例：语音/按键输入
在收集用户的输入（按键或语音）,根据用户的选择，可以执行不同的子流程 forSales，forSupport。

PML
<pml>
    <process>
        <catch input="DTMF SPEECH" keys="1" language="zh-CN" timeout="10">
            <tts language="zh-CN">如需销售服务，请按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-CN">您选择了销售服务，谢谢。</tts>
    </subprocess>
    <subprocess id="forSupport">
        <tts language="zh-CN">您选择了技术支持，谢谢。</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是子呼叫的被叫号码，需使用国际格式：国家区号+手机号码。8618911111111
timeoutinteger否响铃时间，以秒为单位；
  • 默认值为45，
  • 最小值为15，
  • 最大值为60。
15

示例

PML
<pml>
    <process>
        <forward from="85299998888" record="record-from-answer" callback_url="https://example.com/child_call_events">
            <to>8618911111111</to>
            <tts language="zh-CN">正在为您转接。</tts>
        </forward>
    </process>
</pml>

4.9 Translation（实时语音翻译）​

PaaSoo 的实时通话翻译功能（Translation）允许您在双向通话过程中，实时识别并翻译通话双方的语音内容。该功能基于AI技术，支持跨语言的实时交流，适用于国际商务会议、多语种客服支持等场景。

您可以通过 API 灵活地调整翻译语言、语音、音量等设置，以满足个性化业务需求。

4.9.1 请求参数说明​

参数类型必填描述示例
fromstring.是通话发起方的源语言代码。指定通话发起方的语音识别语言，并作为接收对方语音翻译的目标语言。zh-CN
tostring是通话接收方的源语言代码。指定通话接收方的语音识别语言，并作为通话发起方语音翻译的目标语言。此参数与 from 共同构成双向翻译通道。ja-JP
volumeinteger否在翻译过程中，设置双方原始语音的音量大小，0~100。
如：100为原始音量，设置为 40 即通话双方按 40% 的音量播放。
默认：0，没有原始声音。		30

示例：中文 to 日文

PML
<pml>
    <process>
        <tts language="zh-CN">开始在此通话中进行实时翻译。</tts>
        <forward from="8613303333333">
            <translation from="zh-CN" to="ja-JP" volume="30"></translation>
            <to>815031111111</to>
        </forward>
    </process>
</pml>
说明

<translation from="zh-CN" 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-CN">开始在此通话中进行实时翻译。</tts>
            <forward from="8613303333333">
                <translation from="zh-CN" 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-CN">英语翻译成中文请按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-CN"/>
            <to>8613303333333</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-CN">您好，很高兴为您服务，请问有什么可以帮您。</tts>
    ......
</subprocess>
<subprocess id="process_non-working">
    <tts language="zh-CN">您好！当前为周末非服务时间。客服工作时间：周一至周五 8:00-17:00。请于下周一该时段内咨询，谢谢！祝您周末愉快！</tts>
    ......
</subprocess>
<subprocess id="process_default">
    <tts language="zh-CN">您好！当前客服已离线。服务时间为周一至周五 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.cn/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.cn/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-CN">您好，您有一笔尚未完成的订单，请在两个工作日内尽快完成付款。</tts>
        <pause duration="1s"/>
        <catch event_url="https://example.com/payment_response" keys="1" end_key="#" timeout="10">
            <tts language="zh-CN">如已完成支付，请按1，并按 # 结束。</tts>
        </catch>
        <tts language="zh-CN">感谢您对我们的支持，祝您购物愉快。</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-CN">为确保服务质量和保障您的权益，本次通话将被录音。中文服务请按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-CN" 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-CN">欢迎致电培训中心，请根据语音提示进行课程问答。</tts>
        <catch keys="1" timeout="10">
            <tts language="zh-CN">题目：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-CN">回答正确！感谢参与。</tts>
    </subprocess>
    <subprocess id="wrong">
        <tts language="zh-CN">回答错误，下次再来挑战吧。</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。我们将竭诚为您提供技术协助。