MMS API

本 API を使用することで、世界中のさまざまな国/地域のモバイルユーザーに MMS（マルチメディアメッセージングサービス）を送信し、画像形式を活用してより視覚的なインパクトとインタラクティブな配信体験を実現できます。MMS 機能の有効化が必要な場合や、特定の国や地域での MMS 要件がある場合は、速やかにアカウントマネージャーにご連絡いただくか、support@paasoo.com までご要望をお送りください。

1. 呼び出し方法

呼び出し方法

HTTP Method：POST
Content-Type：application/x-www-form-urlencoded
API エンドポイント：https://api.paasoo.com/mms
リクエストパラメータのエンコード：特殊文字は URL エンコードを行ってください。
セキュリティ：HTTPS プロトコルの使用を推奨します。正常に呼び出すには、正しい key と secret を付与する必要があります。

2. リクエストのサンプル

以下は cURL を例とし、POST + application/x-www-form-urlencoded 方式での呼び出し方法を示しています：

cURL
curl -X POST "https://api.paasoo.com/mms" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "key=API_KEY&secret=API_SECRET&from=TEST&to=819011111111&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 や + は含みません）。例えば、日本の番号は 819011111111 となります。	819011111111
text	string	はい	MMS のテキスト本文。画像（`attachment`）と組み合わせて使用できます。	This is test MMS from TEST
subject	string	いいえ	MMS の件名。通常は 20 文字以内です（詳細はゲートウェイの制限に従います）。一部のキャリア/端末ではタイトルバーに表示される場合があります。	text
attachment	string	はい	MMS に添付する画像ファイルの URL。PaaSoo サーバーにアップロードした後に取得したストレージリンクを使用してください。推奨サイズ制限：300KB 以下。	`https://example.com/example.jpg`
requestId	string	いいえ	一意のリクエスト ID。このリクエストを識別し、追跡および異常調査を行うために使用します。冪等性を保証する必要がある場合は、リクエストごとに異なる `requestId` を使用してください。 60秒以内に同じリクエスト ID が使用された場合、同一のリクエストとみなされます。システムは重複して課金や送信を行うことなく、最初のリクエストと同じレスポンス結果を返します。	0432258a-ecc7-4628-9158-2b883fe65181

4. レスポンスパラメータの説明

成功した場合、API はステータスコード 0 と対応するメッセージ ID を返します。
失敗した場合、対応するエラーステータスコードとその説明を返します。

4.1 レスポンスフィールドの説明

パラメータ	型	説明	サンプル
messageid	string	メッセージ ID。各 MMS レコードの一意の識別子。	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. API ステータスコード一覧

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：MMS 添付ファイルが不正またはアクセス不可
18 - Invalid subject：件名が不正または制限超過

本 API はデフォルトで非常に高い送信弾力性を提供します。呼び出し時にエラーコード status="10" を受信した場合、業務の取り決めに従ってアカウントにカスタムレート制限が有効になっていることを示します。制限のしきい値を調整する必要がある場合は、アカウントマネージャーまたは PaaSoo テクニカルサポートチーム（support@paasoo.com）までご連絡ください。

6. コードサンプル

以下は、主要なプログラミング言語で「単一の国際 MMS 送信 API」を統合するためのシンプルなコードサンプルです。

以下は簡素化されたコードサンプルです。コアとなる説明のみを残し、コードをすっきりと保っています：

Python
Node.js
PHP
Java
Go

import requests

# API エンドポイント
url = "https://api.paasoo.com/mms"

payload = {
    "key": "API_KEY",                                 # あなたの API Key に置き換えてください
    "secret": "API_SECRET",                           # あなたの API Secret に置き換えてください
    "from": "TEST",                                   # 送信元 ID (Sender ID)
    "to": "819011111111",                             # 宛先番号
    "subject": "text",                                # MMS の件名
    "attachment": "https://example.com/example.jpg",  # 画像ファイルの URL
    "text": "これは TEST からのテスト MMS です"            # MMS 本文
}
# リクエストヘッダー
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("MMS の送信に成功しました。messageid:", data.get("messageid"))
    else:
        print(f"MMS の送信に失敗しました。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/mms';

// URL エンコードされたフォームデータを準備
const data = new URLSearchParams({
    key: 'API_KEY',                                 // あなたの API Key に置き換えてください
    secret: 'API_SECRET',                           // あなたの API Secret に置き換えてください
    from: 'TEST',                                   // 送信元 ID (Sender ID)
    to: '819011111111',                             // 宛先番号
    subject: 'text',                                // MMS の件名
    attachment: 'https://example.com/example.jpg',  // 画像ファイルの URL
    text: 'これは TEST からのテスト MMS です'            // MMS 本文
});

// 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('MMS の送信に成功しました。messageid:', result.messageid);
    } else {
        console.log('MMS の送信に失敗しました。status:', result.status, 'message:', result.status_code);
    }
})
.catch((error) => {
    console.error('リクエストに失敗しました:', error.message || error);
});

<?php

// API エンドポイント
$url = "https://api.paasoo.com/mms";

// リクエストパラメータ
$data = [
    "key" => "API_KEY",                                 // あなたの API Key に置き換えてください
    "secret" => "API_SECRET",                           // あなたの API Secret に置き換えてください
    "from" => "TEST",                                   // 送信元 ID (Sender ID)
    "to" => "819011111111",                             // 宛先番号
    "subject" => "text",                                // MMS の件名
    "attachment" => "https://example.com/example.jpg",  // 画像ファイルの URL
    "text" => "これは TEST からのテスト MMS です"            // MMS 本文
];

// 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 "MMS の送信に成功しました。messageid: " . $result['messageid'] . "\n";
    } else {
        echo "MMS の送信に失敗しました。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", "819011111111")                             // 宛先番号
                .add("subject", "text")                                // MMS の件名
                .add("attachment", "https://example.com/example.jpg")  // 画像ファイルの URL
                .add("text", "これは TEST からのテスト MMS です")           // MMS 本文
                .build();

        // リクエストを構築
        Request request = new Request.Builder()
                .url("https://api.paasoo.com/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/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", "819011111111")                             // 宛先番号
    data.Set("subject", "text")                                // MMS の件名
    data.Set("attachment", "https://example.com/example.jpg")  // 画像ファイルの URL
    data.Set("text", "これは TEST からのテスト MMS です")           // MMS 本文

    // 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("MMS の送信に成功しました。messageid:", result["messageid"])
    } else {
        fmt.Printf("MMS の送信に失敗しました。status: %v, message: %v\n", result["status"], result["status_code"])
    }
}

7. 送信ステータスレポートとコールバック

メッセージの送信が成功したとしても、必ずしも端末で正常に受信されるとは限りません。PaaSoo のバックエンドは宛先のキャリアに MMS リクエストを開始し、メッセージの転送が完了した後にステータスレポートを生成します。コールバック URL や管理コンソールを通じて、MMS のステータス（「成功」、「失敗」などの具体的な理由）を確認することができます。

8. ベストプラクティスと注意事項

画像サイズの制御と価格に関する注意事項：一部の国やキャリアでは MMS のサイズに厳しい制限があり、通常は 300KB を超えないようにする必要があります。さらに、一部の目的地では、送信価格が画像サイズに応じて変動する場合があります。より大きなメディアファイルを送信する必要がある場合は、PaaSoo に連絡して、専用の通信ゲートウェイがあるかどうかをご確認ください。
コンテンツのコンプライアンスと審査：MMS コンテンツは、現地の法規制およびキャリアのポリシーを遵守する必要があります。違反するテキストや画像（ポルノ、ギャンブル、政治など）の送信は避けてください。
テストと検証：正式な大規模送信の前に、小規模な範囲でテストを実施し、送信効果、受信端末の MMS 互換性、およびコスト計算などを検証してください。
同時実行とレート制御：大量の MMS を迅速に送信する必要がある場合は、速度が速すぎることによるゲートウェイの輻輳を避けるため、事前に PaaSoo とルーティング機能および帯域幅について協議してください。
コールバックのセキュリティ：受信したステータスレポートの送信元が正当であることを確認するために、サーバー側でコールバックリクエストの検証（署名または IP ホワイトリスト）を完了させてください。

9. よくある質問（FAQ）

1 回のリクエストで複数の番号に MMS を送信することはできますか？

はい、一括送信シナリオ専用のバルク MMS API がありますので、対応するドキュメントをご参照ください。

送信した MMS の件名（subject）が端末に表示されない場合はどうすればよいですか？

一部の携帯電話システムやキャリアでは、MMS を表示する際に件名を個別に表示しない場合があります。詳細は端末の機種やキャリアの機能に依存します。

自社サーバーの画像リンクを MMS の添付ファイルとして使用できますか？

ネットワークの到達性と読み込み速度を確保するため、PaaSoo にアップロードするか、信頼できる CDN リンクのメディアファイルを使用することをお勧めします。特別な要件がある場合は、テクニカルサポートにご相談ください。

MMS の送信に失敗した場合、料金はどのように計算されますか？

通常、キャリアへの送信が成功した時点で課金され、最終的な配信ステータスには基づきません。ただし、具体的な状況については当社の営業部門にご確認ください。

10. 付録

カバレッジ（対応範囲）：MMS のカバレッジは SMS のカバレッジと異なる場合があります。ご不明な点や送信可能な地域の確認が必要な場合は、アカウントマネージャーにご相談ください。
マルチメディアトランスコーディング：PaaSoo プラットフォームから一部のキャリアへ送信する際、送信成功率を高めるために添付ファイルが自動的に圧縮またはトランスコーディングされる場合があります。
追加のサポート：受信効果や端末での再生がうまくいかない場合は、同時に SMS リンクを送信することを検討するか、その後のステータスレポートを監視してタイムリーなトラブルシューティングを行ってください。

テクニカルサポート

API 連携の過程で技術的な問題やビジネスに関する疑問が生じた場合は、いつでも当社の開発者サポートチーム（support@paasoo.com）までご連絡ください。誠心誠意、技術的なサポートを提供いたします。

1. 呼び出し方法​

2. リクエストのサンプル​

3. リクエストパラメータの説明​

4. レスポンスパラメータの説明​

4.1 レスポンスフィールドの説明​

4.2 成功レスポンスのサンプル​

4.3 失敗レスポンスのサンプル​

5. API ステータスコード一覧​

6. コードサンプル​

7. 送信ステータスレポートとコールバック​

8. ベストプラクティスと注意事項​

9. よくある質問（FAQ）​

10. 付録​