Voice Messaging API: Text-to-Speech (TTS)

With just a few lines of code, you can convert text into Voice Messages (TTS) and send them as phone calls to phone numbers anywhere in the world. PaaSoo currently supports text-to-speech conversion in over 60 languages, providing you with flexible and reliable calling services across multiple languages and scenarios. To activate this service or access more advanced features, please contact technical support or your account manager.

1. Voice Messaging API Overview

The Voice Messaging API converts text content into speech, dials the Destination Number, and plays the message. Applicable scenarios include:

• Real-time OTP (One-Time Password) voice broadcasting.
• Announcements or marketing messages to reach a multilingual audience.
• Automated reminders, such as bill payments or appointment alerts, to improve Delivery Rates via phone calls.

Note: Certain countries or regions have strict Operator restrictions on voice calls, especially when used for marketing purposes. Before launching such services, please ensure compliance with local regulations.

---

2. Invocation Method

Invocation Method

• HTTP Method: GET
• Endpoint: https://api.paasoo.com/voice/tts

Please ensure you have your key and secret, and pass them via QueryString parameters when making the call.

---

3. Request Example

GET https://api.paasoo.com/voice/tts?key=API_KEY&secret=API_SECRET&from=12025550123&to=12025550199&lang=en-US&text=Your+code+1%2C2%2C3%2C4%2C5&repeat=2

Example Description:

• The + and %2C in the text parameter are URL encoding examples, where the comma , is used for a moderate pause.
• repeat=2 indicates that the message content will be broadcast twice consecutively in a single call.

---

4. Request Parameters

Parameter	Type	Required	Description	Example
key	string	Yes	API Key (composed of 8 alphanumeric characters), used to uniquely identify your account. Can be obtained in the PaaSoo dashboard.	Abcdefgh
secret	string	Yes	API Secret (composed of 8 alphanumeric characters), used together with the key for authentication. Can be obtained in the PaaSoo dashboard.	Abc123EF
from	string	Yes	Caller ID, only supports numbers with a leading + or pure digits (up to 20 digits). Contact technical support if you need a custom Caller ID.	+12025550123
to	string	Yes	Destination Number, including the country code. For example, a US number 2025550199 with country code 1 should be written as 12025550199.	12025550199
lang	string	Yes	Broadcast language code, see the Supported TTS Languages or separate documentation. Contact technical support if you need additional languages.	en-US
text	string	Yes	Message content, UTF-8 + URL encoded. You can insert pause and speech rate adjustment tags in the voice text (see the Voice Content Parameters section below).	Your+code+1%2C2%2C3%2C4%2C5
repeat	integer	No	Number of times to repeat the broadcast. Can be set from 1 to 10, default is 1.	2
voice	string	No	Set the broadcast Voice Type: woman (female voice, default) or man (male voice).	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/ loud
time_limit	integer	No	Maximum Call Duration limit (in seconds). 0 or left blank means no limit.	10
max_wait_time	integer	No	Maximum call waiting time (in seconds). If exceeded, dialing stops and the call hangs up.	30

---

5. Response Parameters

Parameter	Type	Description	Example
messageid	string	Message ID, unique identifier for a single Voice Message.	015bd4-d6dfa7-58w
status	string	API response status: 0 - success 2 - Missing parameters 3 - Invalid parameters 4 - Invalid credentials: key or secret is incorrect 5 - Unauthorized IP: IP Whitelist restriction 6 - Invalid phone number: Incorrect number format 7 - Invalid sender id: from parameter format is incorrect 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	0 - success
status_code	string	Description message corresponding to the status.	Missing parameters

5.1 Success Example

{
    "status": "0",
    "messageid": "015bd4-d6dfa7-58w"
}

5.2 Failure Example

{
    "status": "2",
    "status_code": "Missing parameters."
}

---

6. Voice Content Parameters

To make the Voice Message more natural and easier to understand, you can flexibly control it using pauses or speech rate adjustments. The following tags can be directly embedded into the text parameter (must be URL encoded):

Tag	Attribute	Description	Example
<break>	time	Insert a pause. Units can be seconds (s) or milliseconds (ms).	1s/500ms
<prosody>	rate	Set the speech playback rate. Default baseline is 1, adjustable between 0 and 3.	0.1

Usage Examples:

1. Separated by a comma ,:

Hello, your login token is 1,8,3,4,0.

The comma creates a brief pause.

2. Separated using the <break> tag:

hello, your token is <break time="1s"/>1<break time="500ms"/>8<break time="500ms"/>3<break time="500ms"/>4<break time="500ms"/>0.

Precisely controls the pause duration.

3. Controlling speech rate using <prosody>:

Your token is <prosody rate="0.1">1,8,3,4,0</prosody>.

Slows down the speech rate to 0.1 times the original speed.

---

7. Code Examples

Below are simple code examples for integrating the Voice Messaging API in several popular programming languages.

Python

import requests

# API Endpoint
url = "https://api.paasoo.com/voice/tts"

# Query Parameters
params = {
    "key": "API_KEY",                # Replace with your API Key
    "secret": "API_SECRET",          # Replace with your API Secret
    "from": "+12025550123",          # Caller ID
    "to": "12025550199",             # Destination Number
    "lang": "en-US",                 # Language code
    "text": "Your verification code is 1,2,3,4,5",   # Text to convert to speech
    "repeat": 2                      # Number of times to play
}

try:
    # Send HTTP GET request
    response = requests.get(url, params=params)
    response.raise_for_status()
    
    # Parse and print JSON response
    data = response.json()
    if data.get("status") == "0":
        print("Voice message sent successfully, messageid:", data.get("messageid"))
    else:
        print(f"Failed to send voice message, status: {data.get('status')}, message: {data.get('status_code')}")

except requests.exceptions.RequestException as e:
    print(f"Request failed: {e}")

Node.js

const axios = require('axios'); // Run: npm install axios

// API Endpoint
const url = 'https://api.paasoo.com/voice/tts';

// Query Parameters
const params = {
    key: 'API_KEY',               // Replace with your API Key
    secret: 'API_SECRET',         // Replace with your API Secret
    from: '+12025550123',         // Caller ID
    to: '12025550199',            // Destination Number
    lang: 'en-US',                // Language code
    text: 'Your verification code is 1,2,3,4,5',  // Text to convert to speech
    repeat: 2                     // Number of times to play
};

// Send HTTP GET request
axios.get(url, { params })
  .then((response) => {
      const data = response.data;
      if (data.status === '0') {
          console.log('Voice message sent successfully, messageid:', data.messageid);
      } else {
          console.log('Failed to send voice message, status:', data.status, 'message:', data.status_code);
      }
  })
  .catch((error) => {
      console.error('Request failed:', error.message || error);
  });

PHP

<?php

// API Endpoint
$url = "https://api.paasoo.com/voice/tts";

// Query Parameters
$params = [
    "key" => "API_KEY",             // Replace with your API Key
    "secret" => "API_SECRET",       // Replace with your API Secret
    "from" => "+12025550123",       // Caller ID
    "to" => "12025550199",          // Destination Number
    "lang" => "en-US",              // Language code
    "text" => "Your verification code is 1,2,3,4,5",// Text to convert to speech
    "repeat" => 2                   // Number of times to play
];

// Build query string and append to URL
$queryString = http_build_query($params);
$requestUrl = $url . '?' . $queryString;

// Initialize cURL session
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $requestUrl);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

// Execute request
$response = curl_exec($ch);

if($e = curl_error($ch)) {
    echo "Request failed: " . $e;
} else {
    $data = json_decode($response, true);
    if ($data['status'] === "0") {
        echo "Voice message sent successfully, messageid: " . $data['messageid'] . "\n";
    } else {
        echo "Failed to send voice message, status: " . $data['status'] . ", message: " . $data['status_code'] . "\n";
    }
}

// Close cURL session
curl_close($ch);
?>

Java

import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.Response;
import okhttp3.HttpUrl;
import java.io.IOException;

// Make sure to add the OkHttp dependency in your pom.xml or build.gradle
public class VoiceApiExample {
    public static void main(String[] args) {
        OkHttpClient client = new OkHttpClient();

        // Build URL with query parameters
        HttpUrl.Builder urlBuilder = HttpUrl.parse("https://api.paasoo.com/voice/tts").newBuilder();
        urlBuilder.addQueryParameter("key", "API_KEY");              // Replace with your API Key
        urlBuilder.addQueryParameter("secret", "API_SECRET");        // Replace with your API Secret
        urlBuilder.addQueryParameter("from", "+12025550123");        // Caller ID
        urlBuilder.addQueryParameter("to", "12025550199");           // Destination Number
        urlBuilder.addQueryParameter("lang", "en-US");               // Language code
        urlBuilder.addQueryParameter("text", "Your verification code is 1,2,3,4,5"); // Text to convert to speech
        urlBuilder.addQueryParameter("repeat", "2");                 // Number of times to play

        String url = urlBuilder.build().toString();

        // Build request
        Request request = new Request.Builder()
                .url(url)
                .get()
                .build();

        // Execute request
        try (Response response = client.newCall(request).execute()) {
            if (response.isSuccessful() && response.body() != null) {
                System.out.println("Response: " + response.body().string());
            } else {
                System.out.println("Request failed, status code: " + response.code());
            }
        } catch (IOException e) {
            System.err.println("Request failed: " + e.getMessage());
        }
    }
}

Go

package main

import (
    "encoding/json"
    "fmt"
    "io/ioutil"
    "net/http"
    "net/url"
    "strconv"
)

func main() {
    // Parse base URL
    baseURL, err := url.Parse("https://api.paasoo.com/voice/tts")
    if err != nil {
        fmt.Println("Error parsing URL:", err)
        return
    }

    // Add query parameters
    params := url.Values{}
    params.Add("key", "API_KEY")               // Replace with your API Key
    params.Add("secret", "API_SECRET")         // Replace with your API Secret
    params.Add("from", "+12025550123")         // Caller ID
    params.Add("to", "12025550199")            // Destination Number
    params.Add("lang", "en-US")                // Language code
    params.Add("text", "Your verification code is 1,2,3,4,5")  // Text to convert to speech
    params.Add("repeat", strconv.Itoa(2))      // Number of times to play

    // Encode parameters and append to URL
    baseURL.RawQuery = params.Encode()

    // Send HTTP GET request
    resp, err := http.Get(baseURL.String())
    if err != nil {
        fmt.Println("Request failed:", err)
        return
    }
    defer resp.Body.Close()
    
    body, err := ioutil.ReadAll(resp.Body)
    if err != nil {
        fmt.Println("Error reading response:", err)
        return
    }
    
    var result map[string]interface{}
    if err := json.Unmarshal(body, &result); err != nil {
        fmt.Println("Error parsing JSON:", err)
        return
    }

    // Check status
    if status, ok := result["status"].(string); ok && status == "0" {
        fmt.Println("Voice message sent successfully, messageid:", result["messageid"])
    } else {
        fmt.Printf("Failed to send voice message, status: %v, message: %v\n", result["status"], result["status_code"])
    }
}

---

8.Supported Languages List

PaaSoo provides TTS broadcasting for over 60 languages and dialects. Please refer to the separate documentation: "Supported TTS Languages" for a complete list of language types, applicable regions, and examples.

---

9. Voice Messaging Callback URL For Delivery Receipts

After a voice call ends, you can receive Voice Message Delivery Receipts (e.g., whether it successfully connected, Call Duration, etc.) via a Callback URL (Webhook). Please refer to the separate documentation: "Voice Messaging Callback URL For Delivery Receipts".

You can also log in to the PaaSoo dashboard to view call reports and detailed logs.

---

10. Best Practices & Troubleshooting

1. Parameter Security: Keep your key and secret secure; they should only be called from your backend servers.
2. Languages & Dialects: Select the appropriate lang to improve user comprehension and acceptance.
3. Message Intelligibility: In noisy environments, you may need to increase pause durations or set the repeat count for multiple playbacks.
4. Time Zones & Legal Compliance: Be aware of local Operator policies and legal contexts, and avoid making calls during sensitive or legally restricted hours.
5. Cost & Duration: Voice services typically cost more than SMS. Please evaluate your budget and check Pricing and quotas with PaaSoo before initiating large volumes of active calls.
6. Troubleshooting: If a call fails, check the returned status and status_code to determine if it is due to an incorrect number format, insufficient Balance, Unauthorized IP, etc.

---

11. Frequently Asked Questions (FAQ)

Can I use any number as the Caller ID?

• You need to confirm the list of available Caller IDs with PaaSoo or the Operators first. If you require a custom Caller ID, please contact your account manager for registration or binding.

Can voice messages contain emojis or non-text content?

• Emojis are usually ignored or converted into descriptive characters. It is recommended to send only plain text (including standard punctuation marks).

Why is there no voice broadcast after the call is answered?

• Please check whether the text parameter is correctly URL encoded, whether excessively long pauses (or very slow speech rates) are used, and ensure there are no anomalies on the server side.

What factors affect the Call Duration?

• Factors include user answer delay, length of the text content, repeat count, and whether time_limit and max_wait_time are configured.

Are there any concurrency or throughput limits?

• Concurrency capabilities depend on the destination country's Carriers and your business needs. Regardless of the call volume, we recommend communicating with PaaSoo in advance to prepare suitable routing and bandwidth.

---

12. Appendix

• Concurrency & Throughput: Due to varying policies (Operators) and capacities (Carriers) in different destination countries, please confirm feasibility with PaaSoo in advance for any call volume scale (including both small and large-scale concurrency) to reserve adequate Carrier routing and bandwidth for traffic spikes.
• Traceability & Auditing: It is recommended to save the messageid and call time in your business system for future auditing and technical troubleshooting.
• Integrating Other APIs: If you need to integrate SMS + Voice Messages, please refer to the SMS API; currently, the Conversion Tracking API only applies to SMS and does not support the Voice Messaging API.

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.