批次多媒體簡訊 API

本文件介紹如何使用 PaaSoo 批次多媒體簡訊（MMS）介面，以一次請求向 1 - 5000 個號碼同時發送多媒體簡訊。如果您需要開通多媒體簡訊功能或有其它地區的多媒體簡訊需求，請及時聯絡您的客戶經理，或將需求發送至 support@paasoo.com。

1. 呼叫方式

呼叫方式

HTTP Method：POST
Content-Type：application/x-www-form-urlencoded
API Endpoint：https://api.paasoo.com.tw/batch_mms
請求參數編碼：請對特殊字元進行 URL 編碼。
安全性：建議使用 HTTPS 協定，並攜帶正確的 key 與 secret。
批次發送數量：每次請求可批次發送 1 - 5000 條多媒體簡訊。

2. 請求範例

以下以 cURL 為例，展示如何透過 POST + application/x-www-form-urlencoded 的方式呼叫：

cURL
curl -X POST "https://api.paasoo.com.tw/batch_mms" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "key=API_KEY&secret=API_SECRET&from=TEST&to=886912345678,886912345679&subject=text&attachment=https%3A%2F%2Fexample.com%2Fexample.jpg&text=This+is+test+mms+from+TEST"

說明

to 參數中多個號碼使用英文逗號 , 分隔。
attachment 中的 URL 需要進行 URL 編碼。
text 建議做適當的跳脫或 URL 編碼（如空格、符號）。

3. 請求參數說明

參數	類型	必填	描述	範例
key	string	是	API Key（字母或數字構成，共 8 位），用於唯一標識您的帳戶。可在 PaaSoo 用戶端後台取得。	Abcdefgh
secret	string	是	API Secret（字母或數字構成，共 8 位），與 `key` 配合使用以進行身分驗證。可在 PaaSoo 用戶端後台取得。	Abc123EF
from	string	是	發件人顯示名稱或號碼（Sender ID），部分國家支援自訂。如需使用特定 Sender ID，請聯絡技術支援。	TEST
to	string	是	接收目標手機號碼，格式為`國際電話代碼 + 手機號碼`（不含前導 00 或 +）。支援 1 - 5000 個手機號碼；多個號碼之間用英文逗號(,)分隔。	886912345678,886912345679
text	string	是	多媒體簡訊文字內容，可與圖片（attachment）搭配使用。	This is test MMS from TEST
subject	string	否	多媒體簡訊主題，通常不超過 20 個字元（具體依照通道限制）。部分營運商/終端可能會顯示在標題列。	text
attachment	string	是	多媒體簡訊中附帶的圖片檔案位址建議使用 PaaSoo 伺服器上儲存的連結，大小限制一般為 300KB 以下。若需發送更大圖片，請聯絡 PaaSoo 協商適配的通訊通道與定價。	`https://example.com/example.jpg`

4. 回應參數說明

4.1 回應欄位說明

參數	類型	描述	範例
status	integer	提交至 PaaSoo 雲通訊平台的回應狀態碼。介面狀態碼列表： 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：系統錯誤 13 - Invalid attachment file：附件不合法或無法存取 14 - Nb of messages per request should be between 1 and 5000：號碼數量超限 18 - Invalid subject：主題不合法或超出限制	0
status_code	string	狀態描述。	Invalid credentials
batchid	string	本次批次請求的唯一標識。	a0018f-e4bf51-e000
data	array	每個號碼的發送詳情。	[...]

data 陣列中的欄位

欄位	類型	描述	範例
to	string	發送目標號碼，國際電話代碼+手機號碼格式。	886912345678
messageid	string	多媒體簡訊的唯一標識。	015bd4-d6dfa7-58w
status	integer	提交至 PaaSoo 雲通訊平台的單條訊息狀態碼。介面狀態碼列表： 0 - success：提交成功 2 - Missing parameters 3 - Invalid parameters 4 - Invalid credentials 5 - Unauthorized IP 6 - Invalid phone number 7 - Invalid sender id 8 - Message bombing detected 9 - Quota exceeded 10 - Throttling error 11 - System error 13 - Invalid attachment file 18 - Invalid subject	0
status_code	string	單條訊息狀態描述。	Missing parameters

本介面預設提供極高的發送彈性。若您在呼叫時收到錯誤碼 status=10，說明您的帳戶已根據業務約定開啟了自訂速率限制。如需調整限速閾值，請聯絡您的客戶經理或 PaaSoo 技術支援團隊（support@paasoo.com）。

4.2 成功回應範例

{
    "status": 0,
    "status_code": "success",
    "batchid": "a0018f-e4bf51-e000",
    "data": [
        {
            "status": 0,
            "to": "886912345678",
            "messageid": "00018f-e4bf51-e002"
         },
        {
            "status": 0,
            "to": "886912345679",
            "messageid": "00018f-e4bf51-e003"
        }
    ]
}

4.3 失敗回應範例

{
    "status": 4,
    "status_code": "Invalid credentials."
}

5. 程式碼範例

以下是在幾種流行的程式語言中整合批次發送國際多媒體簡訊 API 的簡單程式碼範例。

Python
Node.js
PHP
Java
Go

import requests

# API 介面端點
url = "https://api.paasoo.com.tw/batch_mms"

# 表單資料
payload = {
    "key": "API_KEY",                                 # 替換為您的 API Key
    "secret": "API_SECRET",                           # 替換為您的 API Secret
    "from": "TEST",                                   # 發送者 ID (Sender ID)
    "to": "886912345678,886912345679",                # 目標號碼，以逗號分隔
    "subject": "text",                                # 多媒體簡訊主題
    "attachment": "https://example.com/example.jpg",  # 圖片檔案的 URL
    "text": "這是一則來自 TEST 的測試多媒體簡訊"                # 多媒體簡訊內容
}

# 請求標頭
headers = {
    "Content-Type": "application/x-www-form-urlencoded"
}

try:
    # 發送 HTTP POST 請求
    response = requests.post(url, data=payload, headers=headers)
    response.raise_for_status()
    
    # 解析並列印 JSON 回應
    data = response.json()
    if data.get("status") == 0:
        print("批次多媒體簡訊發送成功，batchid:", data.get("batchid"))
    else:
        print(f"批次多媒體簡訊發送失敗，status: {data.get('status')}, message: {data.get('status_code')}")

except requests.exceptions.RequestException as e:
    print(f"請求失敗: {e}")

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

// API 介面端點
const url = 'https://api.paasoo.com.tw/batch_mms';

// 準備 URL 編碼的表單資料
const data = new URLSearchParams({
    key: 'API_KEY',                                 // 替換為您的 API Key
    secret: 'API_SECRET',                           // 替換為您的 API Secret
    from: 'TEST',                                   // 發送者 ID (Sender ID)
    to: '886912345678,886912345679',                 // 目標號碼，以逗號分隔
    subject: 'text',                                // 多媒體簡訊主題
    attachment: 'https://example.com/example.jpg',  // 圖片檔案的 URL
    text: '這是一則來自 TEST 的測試多媒體簡訊'                // 多媒體簡訊內容
});

// 發送 HTTP POST 請求
axios.post(url, data.toString(), {
    headers: {
        'Content-Type': 'application/x-www-form-urlencoded'
    }
})
.then((response) => {
    const result = response.data;
    if (result.status === 0) {
        console.log('批次多媒體簡訊發送成功，batchid:', result.batchid);
    } else {
        console.log('批次多媒體簡訊發送失敗，status:', result.status, 'message:', result.status_code);
    }
})
.catch((error) => {
    console.error('請求失敗:', error.message || error);
});

<?php

// API 介面端點
$url = "https://api.paasoo.com.tw/batch_mms";

// 請求參數
$data = [
    "key" => "API_KEY",                                 // 替換為您的 API Key
    "secret" => "API_SECRET",                           // 替換為您的 API Secret
    "from" => "TEST",                                   // 發送者 ID (Sender ID)
    "to" => "886912345678,886912345679",                 // 目標號碼，以逗號分隔
    "subject" => "text",                                // 多媒體簡訊主題
    "attachment" => "https://example.com/example.jpg",  // 圖片檔案的 URL
    "text" => "這是一則來自 TEST 的測試多媒體簡訊"                // 多媒體簡訊內容
];

// 初始化 cURL 會話
$ch = curl_init($url);

// 設定 cURL 選項（POST 和 x-www-form-urlencoded）
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Content-Type: application/x-www-form-urlencoded"
]);

// 執行請求
$response = curl_exec($ch);

if($e = curl_error($ch)) {
    echo "請求失敗: " . $e;
} else {
    $result = json_decode($response, true);
    if (isset($result['status']) && $result['status'] === 0) {
        echo "批次多媒體簡訊發送成功，batchid: " . $result['batchid'] . "\n";
    } else {
        echo "批次多媒體簡訊發送失敗，status: " . $result['status'] . ", message: " . $result['status_code'] . "\n";
    }
}

// 關閉 cURL 會話
curl_close($ch);
?>

import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.RequestBody;
import okhttp3.FormBody;
import okhttp3.Response;
import java.io.IOException;

// 確保在您的 pom.xml 或 build.gradle 中添加了 OkHttp 依賴
public class BulkMmsApiExample {
    public static void main(String[] args) {
        OkHttpClient client = new OkHttpClient();

        // 建構 x-www-form-urlencoded 請求體
        RequestBody formBody = new FormBody.Builder()
                .add("key", "API_KEY")                                 // 替換為您的 API Key
                .add("secret", "API_SECRET")                           // 替換為您的 API Secret
                .add("from", "TEST")                                   // 發送者 ID (Sender ID)
                .add("to", "886912345678,886912345679")                 // 目標號碼，以逗號分隔
                .add("subject", "text")                                // 多媒體簡訊主題
                .add("attachment", "https://example.com/example.jpg")  // 圖片檔案的 URL
                .add("text", "這是一則來自 TEST 的測試多媒體簡訊")               // 多媒體簡訊內容
                .build();

        // 建構請求
        Request request = new Request.Builder()
                .url("https://api.paasoo.com.tw/batch_mms")
                .post(formBody)
                .addHeader("Content-Type", "application/x-www-form-urlencoded")
                .build();

        // 執行請求
        try (Response response = client.newCall(request).execute()) {
            if (response.isSuccessful() && response.body() != null) {
                System.out.println("回應: " + response.body().string());
            } else {
                System.out.println("請求失敗，狀態碼: " + response.code());
            }
        } catch (IOException e) {
            System.err.println("請求失敗: " + e.getMessage());
        }
    }
}

package main

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

func main() {
    apiURL := "https://api.paasoo.com.tw/batch_mms"

    // 準備表單資料
    data := url.Values{}
    data.Set("key", "API_KEY")                                 // 替換為您的 API Key
    data.Set("secret", "API_SECRET")                           // 替換為您的 API Secret
    data.Set("from", "TEST")                                   // 發送者 ID (Sender ID)
    data.Set("to", "886912345678,886912345679")                 // 目標號碼
    data.Set("subject", "text")                                // 多媒體簡訊主題
    data.Set("attachment", "https://example.com/example.jpg")  // 圖片檔案的 URL
    data.Set("text", "這是一則來自 TEST 的測試多媒體簡訊")               // 多媒體簡訊內容

    // 發送 HTTP POST 請求
    req, err := http.NewRequest("POST", apiURL, strings.NewReader(data.Encode()))
    if err != nil {
        fmt.Println("建立請求出錯:", err)
        return
    }
    req.Header.Add("Content-Type", "application/x-www-form-urlencoded")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        fmt.Println("請求失敗:", err)
        return
    }
    defer resp.Body.Close()

    // 讀取回應體
    body, err := ioutil.ReadAll(resp.Body)
    if err != nil {
        fmt.Println("讀取回應出錯:", err)
        return
    }

    // 解析 JSON
    var result map[string]interface{}
    if err := json.Unmarshal(body, &result); err != nil {
        fmt.Println("解析 JSON 出錯:", err)
        return
    }

    // 檢查狀態（注意：Go 預設將 JSON 數字解析為 float64）
    if status, ok := result["status"].(float64); ok && status == 0 {
        fmt.Println("批次多媒體簡訊發送成功，batchid:", result["batchid"])
    } else {
        fmt.Printf("批次多媒體簡訊發送失敗，status: %v, message: %v\n", result["status"], result["status_code"])
    }
}

6. 最佳實踐與注意事項

號碼數量限制：每次請求支援 1 - 5000 個號碼，請務必遵循此範圍。若要發送更大規模的訊息，請聯絡 PaaSoo 協商解決方案。
圖片大小控制與定價提醒：一般不建議超過 300KB。部分目的地可能對圖片大小和格式有額外要求或定價區別，請事先了解或諮詢 PaaSoo。
內容合規：遵守當地和國際法律法規，避免發送違規內容（色情、博弈、政治等）。
測試與驗證：在正式大規模發送前，務必先做小範圍測試，查看接收率、效果、終端相容性及費用情況。
併發與速率控制：需要高併發、大批次發多媒體簡訊時，請提前與 PaaSoo 協調，避免因發送速率過快造成佇列延遲或通道壅塞。
回呼與狀態報告：發送成功後可透過回呼 URL 或在 PaaSoo 後台查看訊息狀態；若伺服器提供回呼，請確保安全策略（簽名或 IP 白名單）。

7. 附錄

覆蓋範圍：多媒體簡訊覆蓋可能與簡訊覆蓋不同，部分國家或地區暫未支援或需額外審批。對目標國家有疑問時，請諮詢客戶經理。
多媒體轉碼：對於部分營運商或終端，PaaSoo 可能對圖片進行轉碼或壓縮處理，以提高送達率。
費用計算：多媒體簡訊費用通常按照成功向營運商提交時計費，但具體計費規則可能因國家或地區有所不同，請與商務部門確認。
額外支援：若對接收效果、終端展示或發送穩定性有特殊需求，可與 PaaSoo 團隊溝通以獲得更詳細支援。

技術支援

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

1. 呼叫方式​

2. 請求範例​

3. 請求參數說明​

4. 回應參數說明​

4.1 回應欄位說明​

4.2 成功回應範例​

4.3 失敗回應範例​

5. 程式碼範例​

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

7. 附錄​