多媒體簡訊 API

透過本 API，您可以向全球不同國家/地區的行動用戶發送多媒體簡訊（MMS），並藉助圖片的形式實現更具視覺衝擊力與互動性的傳遞體驗。如果您需要開通多媒體簡訊功能或有特定國家地區的多媒體簡訊需求，請及時聯絡您的客戶經理，或將需求發送至 support@paasoo.com。

1. 呼叫方式

呼叫方式

HTTP Method：POST
Content-Type：application/x-www-form-urlencoded
API Endpoint：https://api.paasoo.com.tw/mms
請求參數編碼：請對特殊字元進行 URL 編碼。
安全性：建議使用 HTTPS 協定，需攜帶正確的 key 與 secret 才能成功呼叫。

2. 請求範例

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

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

說明

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，請聯絡您的客戶經理或技術支援（support@paasoo.com）。	TEST
to	string	是	發送目標號碼，格式為`國際電話代碼 + 手機號碼`（不含前導 00 或 +）。如台灣號碼寫作 886912345678。	886912345678
text	string	是	多媒體簡訊文字內容，可與圖片（`attachment`）搭配使用。	This is test MMS from TEST
subject	string	否	多媒體簡訊主題，通常不超過 20 個字元（具體依照通道限制）。部分營運商/終端可能會顯示在標題列。	text
attachment	string	是	多媒體簡訊中附帶的圖片檔案位址，請使用上傳到 PaaSoo 伺服器後取得的儲存連結。建議大小限制：300KB 以下。	`https://example.com/example.jpg`
requestId	string	否	唯一請求 ID，用於標識此次請求以便追蹤和排查異常。若需保證冪等性，每次請求請使用不同的 `requestId`；若在 60 秒內使用了相同的請求 ID，則視作同一個請求。系統將返回第一次請求的相同回應結果，而不會重複扣費或重複發送。	0432258a-ecc7-4628-9158-2b883fe65181

4. 回應參數說明

成功時，介面會返回狀態碼 0 並攜帶對應的簡訊 ID；
失敗時，會返回相應的錯誤狀態碼及說明。

4.1 回應欄位說明

參數	類型	描述	範例
messageid	string	簡訊 ID，每條多媒體簡訊記錄的全域唯一標識。	015bd4-d6dfa7-58w
status	string	回應狀態。提交至 PaaSoo 雲通訊平台的回應狀態碼。一般來說，"0" 代表成功。	"0"
status_code	string	狀態描述資訊，用於說明錯誤原因或詳細狀態。	Missing parameters

4.2 成功回應範例

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

4.3 失敗回應範例

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

5. 介面狀態碼列表

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：多媒體簡訊附件不合法或無法存取
18 - Invalid subject：主題不合法或超出限制

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

6. 程式碼範例

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

好的，這裡是精簡版備註的程式碼範例，只保留了最核心的說明，保持程式碼整潔：

Python
Node.js
PHP
Java
Go

import requests

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

payload = {
    "key": "API_KEY",                                 # 替換為您的 API Key
    "secret": "API_SECRET",                           # 替換為您的 API Secret
    "from": "TEST",                                   # 發送者 ID (Sender ID)
    "to": "886912345678",                             # 目標號碼
    "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("多媒體簡訊發送成功，messageid:", data.get("messageid"))
    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/mms';

// 準備 URL 編碼的表單資料
const data = new URLSearchParams({
    key: 'API_KEY',                                 // 替換為您的 API Key
    secret: 'API_SECRET',                           // 替換為您的 API Secret
    from: 'TEST',                                   // 發送者 ID (Sender ID)
    to: '886912345678',                             // 目標號碼
    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('多媒體簡訊發送成功，messageid:', result.messageid);
    } 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/mms";

// 請求參數
$data = [
    "key" => "API_KEY",                                 // 替換為您的 API Key
    "secret" => "API_SECRET",                           // 替換為您的 API Secret
    "from" => "TEST",                                   // 發送者 ID (Sender ID)
    "to" => "886912345678",                             // 目標號碼
    "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 "多媒體簡訊發送成功，messageid: " . $result['messageid'] . "\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")                             // 目標號碼
                .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/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/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")                             // 目標號碼
    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("多媒體簡訊發送成功，messageid:", result["messageid"])
    } else {
        fmt.Printf("多媒體簡訊發送失敗，status: %v, message: %v\n", result["status"], result["status_code"])
    }
}

7. 發送狀態報告與回呼

訊息提交成功後，並不代表終端一定能成功接收。PaaSoo 後台會向目標營運商發起多媒體簡訊請求，並在訊息傳送完畢後產生狀態報告。可透過回呼 URL 或在後台查看多媒體簡訊狀態，如「成功」、「失敗」等具體原因。

8. 最佳實踐與注意事項

圖片大小控制與定價提醒：部分國家或營運商對多媒體簡訊大小有嚴格限制，一般不要超過 300KB。另外，對部分目的地而言，發送價格也可能隨圖片大小而變化。如需發送更大媒體檔案，可聯絡 PaaSoo 查看是否有專門適配的通訊通道。
內容合規與審核：多媒體簡訊內容需遵守當地法律法規及營運商政策，避免發送違規文字或圖片（色情、博弈、政治等）。
測試與驗證：在正式大規模發送前，請先進行小範圍測試，驗證發送效果、接收終端對多媒體簡訊的相容性，以及成本核算等。
併發與速率控制：若需要發送大量多媒體簡訊並快速到達，請提前與 PaaSoo 協商路由能力與頻寬，避免因速度過快導致通道壅塞。
回呼安全：在伺服器端完成對回呼請求的校驗（簽名或 IP 白名單），以確保接收到的狀態報告來源合法。

9. 常見問題（FAQ）

是否可以一次請求向多個號碼發送多媒體簡訊？

是的，我們有專門的批次多媒體簡訊 API 用於群發場景，請查看對應文件。

發送的多媒體簡訊主題（subject）在終端上看不到怎麼辦？

一些手機系統或營運商在展示多媒體簡訊時，可能不會單獨顯示主題。具體視機型與營運商能力而定。

能使用自己的伺服器圖片連結作為多媒體簡訊附件嗎？

建議使用上傳到 PaaSoo 或可靠 CDN 連結的媒體檔案，以確保網路可達性與載入速度。如有特殊需求，請與技術支援溝通。

如果多媒體簡訊發送失敗，費用如何計算？

通常是按照成功向營運商提交時計費，而非最終送達狀態。但具體情況需與我們的商務部門確認。

10. 附錄

覆蓋範圍：多媒體簡訊覆蓋與簡訊覆蓋可能不同，如有疑問或需確認可發送地，請諮詢您的客戶經理。
多媒體轉碼：PaaSoo 平台在發送至某些營運商時，可能對附件進行自動壓縮或轉碼，以提高發送成功率。
額外輔助：若對接收效果或終端播放不成功，可考慮同時發送簡訊連結，或監控後續狀態報告及時排查。

技術支援

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

1. 呼叫方式​

2. 請求範例​

3. 請求參數說明​

4. 回應參數說明​

4.1 回應欄位說明​

4.2 成功回應範例​

4.3 失敗回應範例​

5. 介面狀態碼列表​

6. 程式碼範例​

7. 發送狀態報告與回呼​

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

9. 常見問題（FAQ）​

10. 附錄​