Inbound SMS API

By configuring a Webhook, you can receive real-time replies sent by end-users to your number, commonly referred to as MO (Mobile Originated) messages. This document details how to configure your Webhook URL, parse payload parameters, and provides code examples in various languages for receiving and processing to help you seamlessly implement two-way SMS interaction with your users.

1. Webhook Configuration & Details

Webhook Details

HTTP Method: GET
Webhook URL: The receiving endpoint you pre-configured in the PaaSoo console (provided and maintained by you).
Trigger Timing: When PaaSoo receives an MO (Mobile Originated) message from the Carrier, the system will immediately initiate a GET request to your Webhook URL, pushing the message details.
Retry Mechanism: If your server does not return an HTTP 200 OK correctly, PaaSoo will attempt to re-push the message after 5 minutes, 10 minutes, and 30 minutes.

2. Webhook Request Example

When an MO message is generated, the PaaSoo platform will call your Webhook URL in the following format:

GET https://USER_CALLBACK_URL?type=mo&messageid=015bd4-d6dfa7-58w&to=12025550124&from=12025550123&text=Hello+World

3. Request Parameters

In the received GET request, the URL Query contains the following parameters:

Parameter	Type	Description	Example
type	string	Message type. For MO (Mobile Originated) messages, it is fixed as `mo`.	`mo`
messageid	string	Message ID, the globally unique identifier for this inbound message.	`015bd4-d6dfa7-58w`
to	string	The inbound number, usually the Virtual Numbers you applied for on the PaaSoo platform.	`12025550124`
from	string	The end user's mobile number.	`12025550123`
text	string	The text content of the SMS.	`Hello World`

4. Receiving and Processing Examples

The following examples demonstrate how to receive and process Webhook pushes on the server side. In actual applications, please modify the listening URL to the USER_CALLBACK_URL path configured on the PaaSoo platform, and add security checks (such as IP Whitelist, signature verification, etc.) and database storage logic according to your actual business needs.

The following code assumes your Webhook URL is: https://example.com/mo-callback.

Python
Node.js
PHP
Java
Go

import requests

# Your Webhook URL
url = "https://example.com/mo-callback"

# Simulated MO (Mobile Originated) query parameters
params = {
    "type": "mo",                             # Message type, fixed as mo
    "messageid": "015bd4-d6dfa7-58w",         # Message ID (globally unique)
    "to": "12025550124",                      # Virtual Number
    "from": "12025550123",                    # End user's mobile number
    "text": "Hello World"                     # SMS text content
}

try:
    # Simulate the platform sending an HTTP GET request to your Webhook
    response = requests.get(url, params=params)
    response.raise_for_status()
    
    print(f"Webhook simulation successful. Server response status code: {response.status_code}")
    print(f"Response body: {response.text}")

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

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

// Your Webhook URL
const url = 'https://example.com/mo-callback';

// Simulated MO (Mobile Originated) query parameters
const params = {
    type: 'mo',                             // Message type, fixed as mo
    messageid: '015bd4-d6dfa7-58w',         // Message ID (globally unique)
    to: '12025550124',                      // Virtual Number
    from: '12025550123',                    // End user's mobile number
    text: 'Hello World',                    // SMS text content
};

// Simulate the platform sending an HTTP GET request to your Webhook
axios.get(url, { params })
    .then((response) => {
        console.log(`Webhook simulation successful. Server response status code: ${response.status}`);
        console.log(`Response body: ${response.data}`);
    })
    .catch((error) => {
        console.error('Simulation failed:', error.message || error);
    });

<?php

// Your Webhook URL
$url = "https://example.com/mo-callback";

// Simulated MO (Mobile Originated) query parameters
$params = [
    "type" => "mo",                             // Message type, fixed as mo
    "messageid" => "015bd4-d6dfa7-58w",         // Message ID (globally unique)
    "to" => "12025550124",                      // Virtual Number
    "from" => "12025550123",                    // End user's mobile number
    "text" => "Hello World"                     // SMS text content
];

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

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

// Execute request
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);

if($e = curl_error($ch)) {
    echo "Simulation failed: " . $e;
} else {
    echo "Webhook simulation successful. Server response status code: " . $httpCode . "\n";
    echo "Response body: " . $response . "\n";
}

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

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 MoWebhookSimulation {
    public static void main(String[] args) {
        OkHttpClient client = new OkHttpClient();

        // Build Webhook URL with query parameters
        HttpUrl.Builder urlBuilder = HttpUrl.parse("https://example.com/mo-callback").newBuilder();
        urlBuilder.addQueryParameter("type", "mo");                         // Message type, fixed as mo
        urlBuilder.addQueryParameter("messageid", "015bd4-d6dfa7-58w");     // Message ID (globally unique)
        urlBuilder.addQueryParameter("to", "12025550124");                  // Virtual Number
        urlBuilder.addQueryParameter("from", "12025550123");                // End user's mobile number
        urlBuilder.addQueryParameter("text", "Hello World");                // SMS text content

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

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

        // Execute request to simulate platform Webhook
        try (Response response = client.newCall(request).execute()) {
            System.out.println("Server response status code: " + response.code());
            if (response.body() != null) {
                System.out.println("Response body: " + response.body().string());
            }
        } catch (IOException e) {
            System.err.println("Simulation failed: " + e.getMessage());
        }
    }
}

package main

import (
    "fmt"
    "io/ioutil"
    "net/http"
    "net/url"
)

func main() {
    // Your Webhook URL
    baseURL, err := url.Parse("https://example.com/mo-callback")
    if err != nil {
        fmt.Println("Error parsing URL:", err)
        return
    }

    // Add simulated MO (Mobile Originated) query parameters
    params := url.Values{}
    params.Add("type", "mo")                             // Message type, fixed as mo
    params.Add("messageid", "015bd4-d6dfa7-58w")         // Message ID (globally unique)
    params.Add("to", "12025550124")                      // Virtual Number
    params.Add("from", "12025550123")                    // End user's mobile number
    params.Add("text", "Hello World")                    // SMS text content

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

    // Simulate the platform sending an HTTP GET request to your Webhook
    resp, err := http.Get(baseURL.String())
    if err != nil {
        fmt.Println("Simulation failed:", err)
        return
    }
    defer resp.Body.Close()

    // Read response body
    body, err := ioutil.ReadAll(resp.Body)
    if err != nil {
        fmt.Println("Error reading response:", err)
        return
    }

    fmt.Printf("Webhook simulation successful. Server response status code: %d\n", resp.StatusCode)
    fmt.Printf("Response body: %s\n", string(body))
}

5. Response Requirements & Retry Policy

Success Response: After your server successfully receives and processes the request, it must return HTTP 200 OK or a similar 2xx success status code to confirm to PaaSoo that the callback was correctly received.
Retry Mechanism: If PaaSoo does not receive a valid 2xx response (e.g., server timeout or returns 4xx/5xx), the system will retry the push at intervals of 5 minutes, 10 minutes, and 30 minutes. If an HTTP 200 is still not received, the system will abandon further retries.

6. Security & Best Practices

Data Transmission Security:
- It is highly recommended that your Webhook URL uses the HTTPS protocol for encryption to ensure the security of the SMS content during transmission.
Access Control:
- It is recommended to configure an IP Whitelist on your server or gateway to only allow requests originating from PaaSoo's official server IP ranges, preventing malicious probing and forged requests.
Idempotency Design:
- Due to network jitter or the retry mechanism, your server may receive the same MO (Mobile Originated) message multiple times. Please make sure to use the messageid (Message ID) as a unique identifier to implement deduplication (idempotency) for database insertions or business logic.

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. Webhook Configuration & Details​

2. Webhook Request Example​

3. Request Parameters​

4. Receiving and Processing Examples​

5. Response Requirements & Retry Policy​

6. Security & Best Practices​