Programmable Voice API

The PaaSoo Programmable Voice API provides a set of voice scripting languages based on XML syntax—PML (PaaSoo Voice Markup Language). With PML, you can build highly customized voice workflows, covering various features such as outbound calls, inbound calls, IVR (Interactive Voice Response), real-time multilingual translation, recording, and call control. You can use these features within the same Programmable Voice API to meet the business needs of different scenarios and obtain a flexible and efficient voice communication experience.

1. Overview

The PaaSoo Programmable Voice API is based on the PML scripting language. Through this API, you can flexibly orchestrate outbound call workflows, set IVR logic, perform multilingual translation, record, and actively end calls. Some typical usage scenarios include: customer service hotlines, automated outbound notifications, conference calls, cross-language communication, voice verification codes, and recording quality inspection.

2. Feature Overview

3.1 Outbound Calls: Automatically initiate calls, widely used for marketing notifications, verification codes, etc.
3.2 Inbound Calls: Automate the routing of incoming calls or implement smart customer service IVR workflows.
3.3 Call Event Callbacks: Monitor call status at any time (ringing, connected, hung up, abnormal, etc.).
4.1 PML Main Process (Process): Acts as the main controller, coordinating the execution of various subprocesses.
4.2 PML Subprocess (SubProcess): Implements specific business function modules.
4.3 Conditional Items (Items): Provides smart routing decisions to implement dynamic workflow jumps.
4.4 TTS (Text-to-Speech): Instantly converts text into natural and fluent voice playback.
4.5 Play Audio (Play): Plays specified audio files, which can be used for prompt tones, background music, etc.
4.6 Pause (Pause): Inserts pauses between voice segments or audio to make the broadcast more coherent.
4.7 Key Capture (Catch): Collects user input via DTMF or voice input and executes logic.
4.8 Call Forwarding (Forward): Transfers the call to another number or call center system.
4.9 Real-time Voice Translation (Translation): Performs instant multilingual translation during the call.
4.10 Record (Record): Flexibly choose whether to record the call and obtain the recording address in the callback.
4.11 Recording Callback: Callback notification after the recording ends.
4.12 Schedule (Schedule): Executes different subprocesses based on time conditions.
5 Call Interruption: Allows actively ending the call or setting a countdown to end it automatically.

3. API Description

Below are the technical instructions for the Programmable Voice API in three key stages: outbound, inbound, and event callbacks. The features (such as translation, recording, etc.) need to be configured in the PML script.

3.1 Outbound Calls

Use this feature to automatically initiate outbound calls. It can be used in scenarios such as batch notifications, voice verification codes, and remote meeting invitations. A single request can carry a PML script to specify the interaction workflow, flexibly implementing multi-level voice guidance or key interactions.

Invocation Method

HTTP Method: POST
Endpoint: https://api.paasoo.com/api/calls
Content-Type: application/x-www-form-urlencoded

3.1.1 Request Parameters

Parameter	Type	Required	Description	Example
key	string	Yes	API Key (composed of 8 letters or numbers), used to uniquely identify your account. Can be obtained in the PaaSoo dashboard.	Abcdefgh
secret	string	Yes	API Secret (composed of 8 letters or numbers), used in conjunction with `key` for authentication. Can be obtained in the PaaSoo dashboard.	Abc123EF
from	string	Yes	Caller ID. If you need a custom Caller ID, please contact technical support.	+12025550188
to	string	Yes	Destination Number, requiring international format: Country Code + phone number.	12025550199
pml	string	Yes	PML script based on XML syntax, defining the call logic and functions.	<pml> <process> <tts voice="woman" language="en-US">Hello.</tts> </process> </pml>
callback_url	string	No	Event callback address, used to receive call status changes.	`https://example.com/callback`
callback_event	string	No	Events to send to the callback URL. Multiple events can be set simultaneously, separated by commas. ringing answered completed rejected	ringing
record	boolean	No	Whether to enable recording.	true
recording_callback_url	string	No	If recording is enabled, the callback address to receive recording notifications.	`https://example.com/record_callback`
timeout	integer	No	Ringing Duration (in seconds). Default: 45 Minimum: 15 Maximum: 60	15
time_limit	integer	No	Maximum Call Duration limit (leaving blank or 0 means no limit). When the Call Duration reaches this limit, the system will immediately and actively hang up the call. Time is in seconds.	120

cURL Example

cURL
curl -X POST https://api.paasoo.com/api/calls \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "key=Abcdefgh" \
-d "secret=Abc123EF" \
-d "from=12025550188" \
-d "to=12025550199" \
-d "pml=<pml><process><tts language=\"en-US\">Hello.</tts></process></pml>" \
-d "callback_url=https://example.com/call_events" \
-d "callback_event=ringing,answered,completed"

3.1.2 Response Parameters

3.1.2.1 Success Example

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

3.1.2.2 Failure Example

{
    "status": "2",
    "status_details":"Missing parameters"   
}

3.1.2.3 Response Fields

Parameter	Type	Description	Example
call_id	string	The processing result of the entire batch. 0 indicates the request was successfully received and processed.	0
status	string	Response status. The response status code submitted to the PaaSoo cloud communication platform. Generally, 0 represents success.	0 - success
status_details	string	Status description information, used to explain the reason for the error or detailed status.	Missing parameters

3.1.3 API Status Code List

0 - success: Success
2 - Missing parameters: Required parameters are missing
3 - Invalid parameters: Parameter format error
4 - Invalid credentials: Key or Secret error
5 - Unauthorized IP: IP restriction
6 - Invalid phone number: Incorrect number format
7 - Invalid sender id: from parameter format error
8 - Message bombing detected: Repeated requests within 3 seconds
9 - Quota exceeded: Insufficient balance or credit limit
10 - Throttling error: Rate limit exceeded (Throttling)
11 - System error: System error

3.2 Inbound Calls

When a user calls a configured phone number or virtual intermediate number, PaaSoo will make a request to your configured Webhook to determine how to handle the incoming call (i.e., return a PML script or subprocess). This allows for highly flexible IVR scenarios such as automatic routing, identity verification, and self-service.

Invocation Method

HTTP Method: GET
Endpoint: https://example.com/webhook?key=Abcdefgh&caller=12025550188&mo_number=12025550199&callid=400157-3d1875-7000

3.2.1 Request Parameters

Parameter	Type	Required	Description	Example
key	string	Yes	API Key (composed of 8 letters or numbers), used to uniquely identify your account. Can be obtained in the PaaSoo dashboard.	Abcdefgh
caller	string	Yes	Caller ID (CLI).	12025550188
mo_number	string	Yes	The number dialed by the user (Virtual Numbers or direct connect).	12025550199
callid	string	Yes	Unique Call ID.	400157-3d1875-7000

Note

Upon receiving this request, your service must return a segment of PML or XML to instruct subsequent IVR or automated voice operations. If a valid PML cannot be returned, the incoming call will be terminated.
HTTP/1.1 200 OK
Content-Type: text/xml

PML
<process>
    <tts voice="woman" language="en-US">Welcome to tech support, press 1; to check your order, press 2.</tts>
</process>

3.3 Call Event Callbacks

Throughout the call, the PaaSoo platform will send call statuses (such as ringing, answered, completed, rejected) to the callback_url you specified in the outbound call or number configuration, allowing you to proceed with subsequent business logic.

Invocation Method

HTTP Method: POST
Content-Type: application/x-www-form-urlencoded

3.3.1 Request Parameters

Parameter	Type	Required	Description	Example
key	string	Yes	API Key (composed of 8 letters or numbers), used to uniquely identify your account. Can be obtained in the PaaSoo dashboard.	Abcdefgh
call_id	string	Yes	Unique Call ID.	015bd4-d6dfa7-58w
event	string	Yes	Current call event. Multiple events can be set simultaneously, separated by commas. ringing answered completed rejected	answered
event_time	string	Yes	Event occurrence time (UTC+0).	2024-12-01 00:00:00
parent_id	string	No	If there is a transfer or child call, this represents the parent Call ID.	400157-3d1875-7000
hangup_cause	string	No	Hangup Cause description, which can be cross-referenced with the SIP Hang-up Cause Code Reference Table.	USER_BUSY
hangup_code	string	No	Hangup Cause code, which can be cross-referenced with the SIP Hang-up Cause Code Reference Table.	USER_BUSY
error_code	string	No	If there is an error, the error code is provided here.	1001
error_msg	string	No	Error description.	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 - Tags and Usage

PML is an XML-based scripting language that helps you design voice workflows concisely. The root element is generally <pml>...</pml>, containing several <process>, <subprocess>, and other nodes. Below are descriptions of common feature tags:

4.1 Process (PML Main Process)

The root element of PML, serving as the entry point for the business workflow. There can be only one <process> root element in each PML script.

PML
<pml>
    <process id="main">
        <tts voice="woman" language="en-US">Hello.</tts>
    </process>
</pml>

4.1.1 Process ID

The Process ID is the unique identifier of the process. When you need to jump from one process to another, this ID will be referenced as the target.

Sequential Execution Scenario: If <process> and <subprocess> are executed sequentially and do not require jumps, the ID can be omitted.
Process Jump Scenario: If jumps are needed, a unique ID must be set for <process> and each <subprocess>.

Example

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

4.2 SubProcess (PML Subprocess)

Represents a reusable business logic module. By encapsulating specific functions (like authentication, menu navigation) into subprocesses, you can simplify the main process structure and improve code reusability and maintainability.

Example

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

4.3 Items (Conditional Items)

In complex application scenarios, a complete business workflow can be built by combining one <process> with multiple <subprocess>es. During execution, the system can make conditional judgments based on user input (such as key selections or voice commands) to achieve flexible jumps from <process> to <subprocess>, or between different <subprocess>es, dynamically responding to user actions.

The <items> tag is usually combined with other tags. For example, when combined with <catch>, it matches the user's input content against the conditions of <item> and jumps to the corresponding <subprocess>.

Example

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>12025550199</to>
        </forward>
    </subprocess >
    ......
</pml>

4.3.1 Conditional Matching Mechanism

<items> contains multiple <item> condition entries. The system sequentially matches the user's input with the value of each <item>, and if successful, executes the corresponding subprocess.

Matching methods:

Exact String Match: Matches successfully when the input content is exactly the same as the value.
Regular Expression Match: Matches successfully when the input content conforms to the regular expression rule of the value.

4.3.2 Process Jumps

When a condition is successfully matched, you can specify the target process to jump to using the next_process attribute.

next_process: Specifies the target process to jump to after a successful match.
Jump syntax: @proc-ja-jp means jumping to the subprocess with id="proc-ja-jp". The @ symbol is used to indicate the ID of the target process.

4.3.3 Execution Flow

The system performs conditional matching sequentially in the order of the <item>s:

The first successfully matched condition will trigger the process jump.
If no condition is matched, the process will continue with subsequent operations.

4.4 TTS (Text-to-Speech)

Converts text content into voice playback. You can customize the language, voice type, rate, volume, etc. Common application scenarios: telephone notifications, reading menus, voice verification code content, etc.

4.4.1 Request Parameters

Parameter	Type	Required	Description	Example
language	string	Yes	TTS (Text-to-Speech) language	en-US
voice	string	No	Voice. Female voice (default): woman Male voice: man	woman
volume	string	No	Volume level of the voice. Absolute value: Represented by a number from 0.0 to 100.0 (from quietest to loudest, e.g., 75), default is 100.0. Or use constant values: silent (0) - mute x-soft (20) - very low volume soft (40) - low volume medium (60) - medium volume loud (80) - high volume x-loud (100, default) - very high volume	100

Two optional parameters can be added to the text content:

Parameter	Type	Attribute	Description	Example
break	string	time	You can set the interval in seconds or milliseconds according to your needs.	<break time="1s"/>
prosody	float	rate	You can set the ratio of the voice playback speed, ranging from 0 to 3, with a default base speed of 1.	<prosody rate="0.1"> Your code 1,2,3,4,5. </prosody>

4.4.2 Supported TTS Languages

Click to view the detailed Supported Languages List.

4.5 Play (Play Audio)

You can play audio files from an external URL (such as .mp3, .wav), applicable in scenarios like IVR prompts or advertising voices. The file must be publicly accessible and ensure sample rate compatibility (8KHz).

Example

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

4.6 Pause (Pause)

Insert controllable pauses between TTS or audio segments to make the voice more natural. Similar to <break>, but generally used for "pauses between workflow nodes" outside of TTS segments.

4.6.1 Request Parameters

Parameter	Type	Required	Description	Example
duration	string	Yes	Pause duration, in milliseconds.	100ms

Example

PML
<pml>
    <process>
        <tts language="en-US">We will pause for half a second...</tts>
        <pause duration="500ms"/>
        <tts language="en-US">Now continuing.</tts>
    </process>
</pml>

4.7 Catch (Key Capture)

This interface is used to collect user input via DTMF (Dual-Tone Multi-Frequency, i.e., key input) or SPEECH (Voice Recognition) during a voice call. It is suitable for scenarios such as implementing multi-level IVR menus, identity verification (like entering verification codes), and voice command recognition.

Interaction Mode Description:

DTMF mode: The system plays a TTS prompt (e.g., "Please enter the order number and press # to end"), and the user inputs numbers and symbols via the telephone keypad. Input is completed when the specified number of keys is reached or an end character is encountered.
SPEECH mode: The system plays a TTS prompt (e.g., "Please state your request, such as 'Sales' or 'Support'"), and the user responds with voice. The voice recognition engine converts the speech into text results.

Allowed Child Tags: Inside the <catch> tag, the following child tags are currently supported to control behaviors such as playing prompts and routing input results: TTS, Play, Pause, Items.

4.7.1 Request Parameters

Parameter	Type	Required	Description	Example
keys	integer	Yes	Specifies the expected number of DTMF keys to capture. When the user inputs this number of keys, the capture process ends immediately. This parameter is only valid for DTMF input. `keys` and `end_key` are parallel termination conditions. If both are set, meeting either condition (key count reached or end key pressed) will end the capture process immediately.	3
end_key	string	No	Specifies one or more termination keys to immediately end DTMF capture. When the user presses any of the characters defined here, the capture process ends immediately. Applicable to DTMF and DTMF SPEECH modes. Format: Multiple characters should be written consecutively without any separators (e.g., #0 means hash, star, or number 0 can act as the end key). Optional values: #, , 0-9 Default value: # `keys` and `end_key` are parallel termination conditions. If both are set, meeting either condition will end the capture immediately.	#, *, 0-9
input	string	No	Input mode. Specifies the accepted input type. Supports one or more values, separated by spaces. DTMF: Only accepts key input SPEECH: Only accepts voice input DTMF SPEECH: Accepts both input modes simultaneously, prioritizing the first valid input received Default: DTMF	DTMF SPEECH
language	string	No	Voice recognition language. When `input` contains SPEECH, this parameter is required. Specifies the language model used by the voice recognition engine.	en-US
hints	string	No	Specifies keywords or phrases, such as specific vocabulary, common expressions, or expected user answers. Used to assist the voice engine and improve the recognition accuracy of the PaaSoo voice engine, especially for words that might be misheard or ignored. Separate multiple keywords with a comma (,) or semicolon (;); Supports up to 500 keywords or phrases; Only applicable in SPEECH mode.	PaaSoo Support, Balance inquiry
max_duration	integer	No	The maximum duration the Catch operation can support (in seconds). Timed from the start of the prompt playback, exceeding this duration will forcefully end the capture operation regardless of whether there is input. Default value: 30 Value range: Must be a positive integer Timeout handling: The system will continue to execute the subsequent process after a timeout	15
speech_timeout	integer	No	The maximum wait time after a voice input pause (in seconds). The wait time after PaaSoo detects a pause in speech; exceeding this duration will forcefully end this Catch operation. Value range: 0 or positive integer Default value: 0 (stops recognition immediately upon detecting the first speech pause) Applicable mode: Only applicable to SPEECH mode	3
repeat	integer	No	If the user provides no input within the set timeout period, the number of times to repeat this Catch. Must be a positive integer.	3
event_url	string	No	Specifies a callback URL to receive the event when user input is completed. When the user completes input, the system will send a callback request to this URL. Your service can determine the subsequent workflow based on the callback information. For callback parameters, see 4.7.2 event_url Callback Parameter Description below	`https://example.com/event`

4.7.2 event_url Callback Parameters

Parameter	Type	Required	Description	Example
call_id	string	Yes	The unique Call ID, the unique identifier for each voice record.	400157-3d1875-7000
input	string	Yes	The keys input by the user, or the recognized text from voice input	Hello

Example: Key Input

PML
<pml>
    <process>
        <catch event_url="https://example.com/event" keys="4" end_key="#" timeout="10">
            <tts language="en-US">Please enter your 4-digit password, then press the # key.</tts>
        </catch>
        <tts language="en-US">Your input has been recorded, thank you.</tts>
    </process>
</pml>

During execution, the system will send the user's input information via a callback to the event_url you configured.

Callback Request Example:

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

If the callback URL responds with a subprocess command:

PML
<subprocess>
    <tts voice="woman" language="en-US">Password verified, goodbye.</TTS>
</subprocess>

It will jump to the subprocess workflow.

If the callback URL responds with 200 OK: The returned content is ignored, and the main process continues execution.

Example: Voice/Key Input
Collect user input (key or voice), and based on the user's choice, execute different subprocesses forSales or forSupport.

PML
<pml>
    <process>
        <catch input="DTMF SPEECH" keys="1" language="en-US" timeout="10">
            <tts language="en-US">For sales, press 1 or say sales. For technical support, press 2 or say support.</tts>
            <items>
                <item value="1|sales" next_process="@forSales"/>
                <item value="2|support" next_process="@forSupport"/>
            </items>
        </catch>
    </process>
    <subprocess id="forSales">
        <tts language="en-US">You selected sales, thank you.</tts>
    </subprocess>
    <subprocess id="forSupport">
        <tts language="en-US">You selected technical support, thank you.</tts>
    </subprocess>
</pml>

4.8 Forward (Call Forwarding)

Seamlessly transfers the current call (including Inbound Calls or Outbound Calls) to another number or business system (such as IVR, Agent). The system will automatically end the connection with the original terminal and establish a connection with the new destination while maintaining the continuity of the call session.

Scenario Example: Customer service personnel transferring an incoming call to a senior engineer; connecting to a third-party system via an intermediate number.

Allowed Child Tags: Inside the <forward> tag, the following child tags are currently supported to provide voice prompts or voice translation processing before or during the transfer: TTS, Translation.

4.8.1 Request Parameters

Parameter	Type	Required	Description	Example
callback_url	string	No	The callback URL used to receive child call events.	callback_url="https://example.com/call"
record	string	No	Options for recording child calls: do-not-record (no call recording); record-from-answer (start recording when the call is answered); record-from-ringing (start recording when the call starts ringing); record-from-answer-dual (two-way recording, starting from when the call is answered); record-from-ringing-dual (two-way recording, starting from when the call rings).	record-from-answer-dual
recording_callback_url	string	No	The callback URL used to receive recording status.	https://example.com/recording
recording_callback_method	string	No	The callback method used to send recording status, currently only POST is supported.	POST
from	string	No	Caller ID of the child call. If customization is needed, please contact technical support.	+12025550188
to	string	Yes	The Destination Number of the child call, requiring international format: Country Code + phone number.	12025550199
timeout	integer	No	Ringing time in seconds; Default value is 45, Minimum value is 15, Maximum value is 60.	15

Example

PML
<pml>
    <process>
        <forward from="12025550188" record="record-from-answer" callback_url="https://example.com/child_call_events">
            <to>12025550199</to>
            <tts language="en-US">Please wait while we transfer your call.</tts>
        </forward>
    </process>
</pml>

4.9 Translation (Real-time Voice Translation)

PaaSoo's real-time call translation feature (Translation) allows you to recognize and translate the voice content of both parties in real-time during a two-way call. Based on AI technology, this feature supports cross-language real-time communication, suitable for scenarios like international business meetings and multilingual customer support.

You can flexibly adjust settings such as translation language, voice type, and volume through the API to meet personalized business needs.

4.9.1 Request Parameters

Parameter	Type	Required	Description	Example
from	string	Yes	The source language code of the call initiator. Specifies the voice recognition language of the call initiator and serves as the target language for translating the other party's voice.	en-US
to	string	Yes	The source language code of the call receiver. Specifies the voice recognition language of the call receiver and serves as the target language for translating the call initiator's voice. This parameter, together with `from`, forms a two-way translation channel.	ja-JP
volume	integer	No	Sets the volume level of the original voice for both parties during translation, from 0 to 100. For example: 100 is the original volume; setting it to 40 means both parties hear the original voice at 40% volume. Default: 0, no original voice.	30

Example: English to Japanese

PML
<pml>
    <process>
        <tts language="en-US">Starting real-time translation for this call.</tts>
        <forward from="12025550188">
            <translation from="en-US" to="ja-JP" volume="30"></translation>
            <to>815031111111</to>
        </forward>
    </process>
</pml>

Note

<translation from="en-US" to="ja-JP" volume="30"></translation>: Indicates translating the call initiator's language from English to Japanese, with the original volume of both parties at 30%.

4.9.2 Personalized Settings for Translated Voice Content

Within the <translation> tag, you can also add <from> and <to> tags to provide more detailed settings for the translated content heard by both parties (call initiator and call receiver).

Note: The <from> and <to> tags here are used to set the playback attributes (such as voice type, volume) of the translated voice content when sent to the call initiator and receiver, rather than controlling their original call voice.

4.9.2.1 Parameter Description

Parameter	Type	Required	Description	Example
voice	string	No	Used to set the voice type for the real-time translated voice content: Female voice (default): woman Male voice: man	woman
volume	string	No	Used to set the volume level of the real-time translated voice content. Absolute value: Represented by a number from 0.0 to 100.0 (from quietest to loudest, e.g., 75), default is 100.0. Or use constant values: silent (0) - mute x-soft (20) - very low volume soft (40) - low volume medium (60) - medium volume loud (80) - high volume x-loud (100, default) - very high volume	loud

Example: English to Japanese

PML
<pml>
    <process>
        <tts language="en-US">Starting real-time translation for this call.</tts>
        <forward from="12025550188">
            <translation from="en-US" to="ja-JP" volume="30">
                <from voice="man" volume="100"/>
                <to voice="man" volume="90"/>
            </translation>
            <to>815031111111</to>
        </forward>
    </process>
</pml>

Note

<from voice="man" volume="100"/>: Indicates that after the call initiator's speech is translated in real-time, the call receiver hears a male voice at 100% volume;
<to voice="man" volume="90"/>: Indicates that after the call receiver's speech is translated in real-time, the call initiator hears a male voice at 90% volume.

Example: User presses a key to select the target language

PML
<pml>
    <process id="langselect">
        <catch keys="1" end_key="#" timeout="15">
            <tts language="en-US">Press 1 for English to Chinese, press 2 for English to French.</tts>
            <items>
                <item value="1" next_process="@tozh"/>
                <item value="2" next_process="@tofr"/>
            </items>
        </catch>
    </process>
    <subprocess id="tozh">
        <forward from="12025550188">
            <translation from="en-US" to="zh-CN"/>
            <to>12025550199</to>
        </forward>
    </subprocess>
    <subprocess id="tofr">
        <forward from="12025550188">
            <translation from="en-US" to="fr-FR"/>
            <to>33123456789</to>
        </forward>
    </subprocess>
</pml>

4.10 Record (Record)

This feature allows the audio stream of one or both parties to be recorded while the call is in progress. Once the recording is complete, the access address of the recording file will be returned via a callback event. It is usually used for service quality inspection, dispute evidence, or employee training.

4.10.1 Request Parameters

Parameter	Type	Required	Description	Example
max_time	integer	No	Maximum recording duration (in seconds). Recording automatically ends when this duration is reached.	60
end_key	string	No	Specifies one or more termination keys to end recording immediately. Recording ends immediately when the user presses any character defined here. Format: Multiple characters should be written consecutively without separators (e.g., #0 means hash, star, or 0 can act as end keys). Optional values: #, , 0-9	#, *, 0-9
recording_callback_url	string	No	Recording status callback URL. Used to receive status event notifications during recording.	https://example.com/recording

Example

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

4.11 Recording Callback

When a recording is completed or in progress, an event will be sent to recording_callback_url, containing important information such as the recording duration and download address.

Invocation Method

HTTP Method: POST

4.11.1 Callback Parameters

Parameter	Type	Required	Description	Example
call_id	string	Yes	The unique Call ID of the recorded child call.	015bd4-d6dfa7-58w
channels	integer	Yes	Channel type of the recording file: 1 Mono 2 Stereo	2
duration	integer	Yes	Recording duration (seconds). Only valid for the `event=record_completed` event.	60
url	string	No	The URL where the recording is stored. Only valid for the `event=record_completed` event.	https://example.com/recording_callback
event	string	Yes	Event category: record_inprocess record_completed	record_inprocess
event_time	string	Yes	Recording start time (UTC+0).	2024-12-01 00:00:00
key	string	Yes	API Key (composed of 8 letters or numbers), used to uniquely identify your account. Can be obtained in the PaaSoo dashboard.	Abcdefgh
parent_id	string	No	The unique Call ID of the parent call, the unique identifier for each voice record.	400157-3d1875-7000

Callback Example

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)

Combining the <schedule> and <items> tags, PML can execute different <subprocess>es based on various time conditions.

4.12.1 Request Parameters

Parameter	Type	Required	Description	Example
timezone	string	No	Timezone parameter, value range: -12 to +12. Supported formats: "+6", "-06", "+05:45", described as: timezone="+6"; Converts UTC time to the local time of the specified timezone; Default: UTC time.	+6
weekday	string	No	Day of the week, digits 1-7 representing Monday to Sunday. Evaluated using Regular Expressions (Regex).	[1-5]
date	string	No	Date matching mode, format: "YYYY-MM-dd". Evaluated using Regular Expressions (Regex). For example, to match Jan 1 and 2, 2025, use date="^2025-01-01\|02".	^2025-01-01\|02
time	string	No	Time matching mode, format: "HH:mm:ss". Evaluated using Regular Expressions (Regex). For example, to match working hours, use time="^(08\|09\|10\|11\|14\|15\|16\|17)".	^(08\|09\|10\|11\|14\|15\|16\|17)

Example: Execute subprocess "process_workday" during working hours, and "process_non-working" outside working hours.

PML
<schedule timezone="-06:00">
    <items>
        <!-- Mon-Fri, 08:00-11:59 and 14:00-17:59 -->
        <item weekday="[1-5]" time="^(08|09|10|11|14|15|16|17)" next_process="@process_workday"/>
        <!-- Weekends -->
        <item weekday="6|7" next_process="@process_non-working"/>
        <!-- Default fallback -->
        <item next_process="@process_default"/>
    </items>
</schedule>

<subprocess id="process_workday">
    <tts language="en-US">Hello, how can I help you today?</tts>
    ......
</subprocess>

<subprocess id="process_non-working">
    <tts language="en-US">Hello! You have reached us outside of our business hours. We are open Monday to Friday, 8:00 AM to 5:00 PM. Please call back during those times. Have a great weekend!</tts>
    ......
</subprocess>

<subprocess id="process_default">
    <tts language="en-US">Hello! Our agents are currently offline. Our service hours are Monday to Friday, 8:00 AM to 5:00 PM. Please contact us during these hours. Thank you!</tts>
    ......
</subprocess>

4.12.2 Matching Rules

The condition matching for weekday, date, and time uses regular expressions.

If multiple conditions among weekday, date, and time are specified simultaneously, all specified conditions must be met for a successful match.

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

5. Call Interruption (End)

You can actively end a call in the API (or set a countdown to end it automatically) to prevent the line from being occupied for abnormally long periods or to end the call when necessary according to business logic.

Invocation Method

HTTP Method: POST
Endpoint: https://api.paasoo.com/api/calls/update

5.1 Request Parameters

Parameter	Type	Required	Description	Example
key	string	Yes	API Key (composed of 8 letters or numbers), used to uniquely identify your account. Can be obtained in the PaaSoo dashboard.	Abcdefgh
secret	string	Yes	API Secret (composed of 8 letters or numbers), used in conjunction with `key` for authentication. Can be obtained in the PaaSoo dashboard.	Abc123EF
call_id	string	Yes	The unique Call ID returned by the outbound call.	400157-3d1875-7000
status	string	Yes	Fixed value to end the call: `completed`	completed
timer	integer	No	End the call after a countdown (seconds), 0 means immediately.	60

5.2 cURL Example

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

5.3 Response Parameters

5.3.1 Success Example

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

5.3.2 Failure Example

{
    "call_id": "400157-3d1875-7000",
    "status_details":"Missing parameters",
    "status":"2"
}

Parameter	Type	Description	Example
call_id	string	The unique Call ID of the ended call.	400157-3d1875-7000
status	string	Response status code. 0 - success: Success 2 - Missing parameters: Required parameters missing 3 - Invalid parameters: Parameter format error 4 - Invalid credentials: Key or Secret error 5 - Unauthorized IP: IP restriction 11 - System error: System error 31 - Call id does not exist: Call ID does not exist 32 - Call not in progress: Call not currently active	0 - success
status_details	string	Status description.	Missing parameters

6. Examples for Different Industries and Scenarios

This section provides some comprehensive examples to help you better understand how to combine different features through PML to implement rich use cases.

6.1 Retail/E-commerce: Automated Payment Reminders or Notifications

This workflow aims to efficiently manage payment reminders and confirm payment status via automated outbound calls. The system proactively reaches out to customers and returns their keypress feedback to the business system in real-time, thereby automating operational workflows and reducing manual intervention.

Workflow Description

Broadcast Reminder: After the call connects, a voice message notifies the customer of an unpaid order and the payment deadline.
Wait for Confirmation: After a short pause, the customer is guided to confirm payment using a specific key combination (e.g., 1+#).
Status Reporting: If the customer presses the specified key, the system immediately sends this event (like the key value) as callback information to the specified event_url, allowing the business server to update the order status.
Polite End: Regardless of whether the customer performs a key operation, the workflow plays a thank-you message at the end and politely terminates the call.

PML Example

PML
<pml>
    <process>
        <tts language="en-US">Hello, you have an uncompleted order. Please complete the payment within two business days.</tts>
        <pause duration="1s"/>
        <catch event_url="https://example.com/payment_response" keys="1" end_key="#" timeout="10">
            <tts language="en-US">If you have already paid, please press 1, and press # to end.</tts>
        </catch>
        <tts language="en-US">Thank you for your support, and have a pleasant shopping experience.</tts>
    </process>
</pml>

6.2 Banking/Finance: Multilingual Customer Service and Recording

This workflow aims to provide an accessible multilingual service entry point for international customers. Through an automated voice menu, customers choose their required translation language and are automatically transferred to the corresponding Agent. Simultaneously, call recording is enabled for service quality monitoring and compliance archiving.

Workflow Description

Service Guidance: After the call connects, it plays a welcome message and prompts for language selection (e.g., press 1 for English, press 2 for Chinese).
Key Selection: The customer presses the corresponding key based on the prompt to choose the required translation service.
Transfer and Translation: Based on the selection, the system transfers the call to the corresponding language Agent and enables the real-time two-way voice translation feature.
Call Recording: Two-way recording is conducted throughout the transferred call, and the recording file URL is pushed to the specified server via a callback URL.

PML Example

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="12025550188" record="record-from-answer-dual" recording_callback_url="https://example.com/record_callback">
            <to>1122334455</to>
        </forward>
    </subprocess>
    <subprocess id="cnlang">
        <forward from="12025550188" 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="12025550188" 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 Education/Training: Knowledge Q&A IVR

This workflow uses an IVR (Interactive Voice Response) system to implement automated knowledge quizzes, training assessments, or interactive games. It utilizes the key capture feature to create multi-branch workflows, providing immediate feedback based on user answers. It is suitable for post-class consolidation, knowledge assessment, and similar scenarios.

Workflow Description

Welcome and Guidance: When the call starts, it plays a welcome message and introduces the Q&A rules.
Broadcast Question and Options: The system asks a preset question and provides corresponding key options (e.g., press 1 for A, press 2 for B).
Wait and Collect Answer: The system waits for the user to press a key within a limited time.
Judgment and Feedback: Based on the key value pressed by the user, the system jumps to the corresponding subprocess (such as "correct answer" or "wrong answer") and plays the respective feedback voice.

PML Example

PML
<pml>
    <process>
        <tts language="en-US">Welcome to the training center. Please follow the voice prompts for the course Q&A.</tts>
        <catch keys="1" timeout="10">
            <tts language="en-US">Question: What does HTML stand for? Press 1 for HyperText Markup Language, press 2 for other.</tts>
            <items>
                <item value="1" next_process="@correct"/>
                <item value="2" next_process="@wrong"/>
            </items>
        </catch>
    </process>
    <subprocess id="correct">
        <tts language="en-US">Correct answer! Thank you for participating.</tts>
    </subprocess>
    <subprocess id="wrong">
        <tts language="en-US">Wrong answer, better luck next time.</tts>
    </subprocess>
</pml>

7. Best Practices and Precautions

API Security and Encryption:
- Transmission security: All API requests must use the HTTPS protocol to perform end-to-end encryption on communication content, preventing data from being eavesdropped on or tampered with during transmission.
- Key management: API Key and Secret are core credentials for accessing services and must be encrypted and stored via environment variables or key management services. They are strictly prohibited from appearing in plaintext in client code or configuration files.
Language and Voice Selection:
- Language matching: The language and accent for TTS (Text-to-Speech) must completely match the target audience. Adequate testing should be conducted before launch to ensure pronunciation, speed, and pauses are natural and fluent.
- Multilingual support: If multilingual broadcasting is required, flexibly utilize the <translation> tag. It is recommended to test each language individually to ensure translation accuracy and voice quality.
Workflow Design:
- Modular design: Use <process> or <subprocess> tags to divide complex voice workflows into independent modules. This helps improve code readability, maintainability, and reusability.
- Navigation and fault tolerance: When designing multi-level menus, you must provide clear timeout handling mechanisms and error key guidance to ensure users can exit or return smoothly in any state, preventing them from getting stuck in infinite loops.
Recording Protection and Compliance:
- Data compliance: Recording files may contain personal sensitive information. Their storage, processing, and protection must strictly comply with data privacy regulations (e.g., GDPR) in the business location or Operator regulations.
- Resource optimization: Properly set max_time (maximum recording duration) and end_key (end key) to prevent system resources from being invalidly occupied due to silence, empty recordings, or user absence.
Cross-Language Call Precautions:
- Recognition limitations: The accuracy of AI translation largely depends on the effectiveness of voice recognition. Alternative options should be provided to users, such as a "language switch" feature or a "transfer to human Agent" option.
- Call environment: It is recommended that users make calls in a relatively quiet environment to reduce the interference of background noise on voice recognition accuracy.
Call End Management:
- Active resource recovery: Use the "Call Interruption" feature to actively end abnormally long calls, freeing up system resources (Carrier channels) and controlling costs.
- Post-processing: By monitoring the completed status of Call Events, you can automatically trigger subsequent operations after a call ends, such as generating bills, updating customer status, or performing data analysis.

Summary

The PaaSoo Programmable Voice API is both flexible and efficient, capable of meeting the core voice interaction needs of various industries. From basic inbound/outbound call processing to complex multilingual translation, recording quality inspection, multi-level IVR menus, etc., everything can be intuitively implemented via PML.

Support

If you encounter any technical issues or have business inquiries during the API integration, please do not hesitate to contact our Support team at support@paasoo.com. We are always here to assist you.

1. Overview​

2. Feature Overview​

3. API Description​

3.1 Outbound Calls​

3.1.1 Request Parameters​

cURL Example​

3.1.2 Response Parameters​

3.1.2.1 Success Example​

3.1.2.2 Failure Example​

3.1.2.3 Response Fields​

3.1.3 API Status Code List​

3.2 Inbound Calls​

3.2.1 Request Parameters​

3.3 Call Event Callbacks​

3.3.1 Request Parameters​

4. PML - Tags and Usage​

4.1 Process (PML Main Process)​

4.1.1 Process ID​

4.2 SubProcess (PML Subprocess)​

4.3 Items (Conditional Items)​

4.3.1 Conditional Matching Mechanism​

4.3.2 Process Jumps​

4.3.3 Execution Flow​

4.4 TTS (Text-to-Speech)​

4.4.1 Request Parameters​

4.4.2 Supported TTS Languages​

4.5 Play (Play Audio)​

4.6 Pause (Pause)​

4.6.1 Request Parameters​

4.7 Catch (Key Capture)​

4.7.1 Request Parameters​

4.7.2 event_url Callback Parameters​

4.8 Forward (Call Forwarding)​

4.8.1 Request Parameters​

4.9 Translation (Real-time Voice Translation)​

4.9.1 Request Parameters​

4.9.2 Personalized Settings for Translated Voice Content​

4.9.2.1 Parameter Description​

4.10 Record (Record)​

4.10.1 Request Parameters​

4.11 Recording Callback​

4.11.1 Callback Parameters​

4.12 Schedule (Schedule)​

4.12.1 Request Parameters​

4.12.2 Matching Rules​

5. Call Interruption (End)​

5.1 Request Parameters​

5.2 cURL Example​

5.3 Response Parameters​

5.3.1 Success Example​

5.3.2 Failure Example​

6. Examples for Different Industries and Scenarios​

6.1 Retail/E-commerce: Automated Payment Reminders or Notifications​

6.2 Banking/Finance: Multilingual Customer Service and Recording​

6.3 Education/Training: Knowledge Q&A IVR​

7. Best Practices and Precautions​

Summary​

1. Overview

2. Feature Overview

3. API Description

3.1 Outbound Calls

3.1.1 Request Parameters

cURL Example

3.1.2 Response Parameters

3.1.2.1 Success Example

3.1.2.2 Failure Example

3.1.2.3 Response Fields

3.1.3 API Status Code List

3.2 Inbound Calls

3.2.1 Request Parameters

3.3 Call Event Callbacks

3.3.1 Request Parameters

4. PML - Tags and Usage

4.1 Process (PML Main Process)

4.1.1 Process ID

4.2 SubProcess (PML Subprocess)

4.3 Items (Conditional Items)

4.3.1 Conditional Matching Mechanism

4.3.2 Process Jumps

4.3.3 Execution Flow

4.4 TTS (Text-to-Speech)

4.4.1 Request Parameters

4.4.2 Supported TTS Languages

4.5 Play (Play Audio)

4.6 Pause (Pause)

4.6.1 Request Parameters

4.7 Catch (Key Capture)

4.7.1 Request Parameters

4.7.2 event_url Callback Parameters

4.8 Forward (Call Forwarding)

4.8.1 Request Parameters

4.9 Translation (Real-time Voice Translation)

4.9.1 Request Parameters

4.9.2 Personalized Settings for Translated Voice Content

4.9.2.1 Parameter Description

4.10 Record (Record)

4.10.1 Request Parameters

4.11 Recording Callback

4.11.1 Callback Parameters

4.12 Schedule (Schedule)

4.12.1 Request Parameters

4.12.2 Matching Rules

5. Call Interruption (End)

5.1 Request Parameters

5.2 cURL Example

5.3 Response Parameters

5.3.1 Success Example

5.3.2 Failure Example

6. Examples for Different Industries and Scenarios

6.1 Retail/E-commerce: Automated Payment Reminders or Notifications

6.2 Banking/Finance: Multilingual Customer Service and Recording

6.3 Education/Training: Knowledge Q&A IVR

7. Best Practices and Precautions

Summary