彩信 API

通过本 API，您可以向全球不同国家/地区的移动用户发送彩信（MMS），并借助图片的形式实现更具视觉冲击力与互动性的传递体验。如果您需要开通彩信功能或有特定国家地区的彩信需求，请及时联系您的客户经理，或将需求发送至 support@paasoo.com。

1. 调用方式

调用方式

HTTP Method：POST
Content-Type：application/x-www-form-urlencoded
API Endpoint：https://api.paasoo.cn/mms
请求参数编码：请对特殊字符进行 URL 编码。
安全性：建议使用 HTTPS 协议，需携带正确的 key 与 secret 才能成功调用。

2. 请求示例

以下以 cURL 为例，展示如何通过 POST + application/x-www-form-urlencoded 的方式调用：

cURL
curl -X POST "https://api.paasoo.cn/mms" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "key=API_KEY&secret=API_SECRET&from=TEST&to=8618911111111&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 或 +）。如中国号码写作 8618911111111。	8618911111111
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.cn/mms"

payload = {
    "key": "API_KEY",                                 # 替换为您的 API Key
    "secret": "API_SECRET",                           # 替换为您的 API Secret
    "from": "TEST",                                   # 发送者 ID (Sender ID)
    "to": "8618911111111",                            # 目标号码
    "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.cn/mms';

// 准备 URL 编码的表单数据
const data = new URLSearchParams({
    key: 'API_KEY',                                 // 替换为您的 API Key
    secret: 'API_SECRET',                           // 替换为您的 API Secret
    from: 'TEST',                                   // 发送者 ID (Sender ID)
    to: '8618911111111',                            // 目标号码
    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.cn/mms";

// 请求参数
$data = [
    "key" => "API_KEY",                                 // 替换为您的 API Key
    "secret" => "API_SECRET",                           // 替换为您的 API Secret
    "from" => "TEST",                                   // 发送者 ID (Sender ID)
    "to" => "8618911111111",                            // 目标号码
    "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", "8618911111111")                            // 目标号码
                .add("subject", "text")                                // 彩信主题
                .add("attachment", "https://example.com/example.jpg")  // 图片文件的 URL
                .add("text", "这是一条来自 TEST 的测试彩信")               // 彩信内容
                .build();

        // 构建请求
        Request request = new Request.Builder()
                .url("https://api.paasoo.cn/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.cn/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", "8618911111111")                            // 目标号码
    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）

是否可以一次请求向多个号码发送彩信？

是的，我们有专门的批量 MMS 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. 附录​