SMS受信 API

Webhook を設定することで、エンドユーザーからお客様の番号に送信された返信内容、すなわち SMS受信 (MO) をリアルタイムで受け取ることができます。本ドキュメントでは、Webhook URL の設定方法、ペイロードパラメータの解析について詳しく説明し、複数の言語での受信処理サンプルを提供することで、ユーザーとの双方向 SMS インタラクションを迅速に実現できるようサポートします。

1. Webhook の設定と説明

Webhook の説明

リクエストメソッド (HTTP Method)：GET
Webhook URL：PaaSoo 管理コンソールで事前に設定した受信エンドポイント（お客様にて提供および保守）。
トリガーのタイミング：PaaSoo がキャリアから SMS受信 (MO) メッセージを受け取ると、システムは直ちにお客様の Webhook URL に GET リクエストを発行し、そのメッセージの詳細をプッシュします。
再試行メカニズム：サーバーが HTTP 200 OK を正しく返さなかった場合、PaaSoo はそれぞれ 5 分後、10 分後、30 分後 に再プッシュを試みます。

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

SMS受信メッセージが生成されると、PaaSoo プラットフォームは以下の形式でお客様の Webhook URL を呼び出します：

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

3. リクエストパラメータ

受信した GET リクエストにおいて、URL Query には以下のパラメータが含まれます：

パラメータ	型	説明	サンプル
type	string	メッセージタイプ。SMS受信 (MO) は `mo` で固定です。	`mo`
messageid	string	メッセージ ID。この SMS受信メッセージのグローバルに一意の識別子。	`015bd4-d6dfa7-58w`
to	string	宛先番号。通常は PaaSoo プラットフォームで申請した仮想番号（バーチャルナンバー）です。	`05012345678`
from	string	エンドユーザーの携帯電話番号。	`819012345678`
text	string	SMS 本文。	`Hello World`

4. 受信と処理のサンプル

以下のサンプルは、サーバー側で Webhook プッシュを受信して処理する方法を示しています。実際のアプリケーションでは、リッスンする URL を PaaSoo プラットフォームで設定した USER_CALLBACK_URL に対応するパスに変更し、実際の業務に応じてセキュリティ検証（IP ホワイトリスト、署名検証など）やデータベース登録のロジックを追加してください。

以下のコードは、Webhook URL が https://example.com/mo-callback であると想定しています。

Python
Node.js
PHP
Java
Go

import requests

# あなたの Webhook URL
url = "https://example.com/mo-callback"

# 受け取った SMS受信 (MO) のクエリパラメータをシミュレート
params = {
    "type": "mo",                             # メッセージタイプ、mo で固定
    "messageid": "015bd4-d6dfa7-58w",         # メッセージ ID (グローバルで一意)
    "to": "05012345678",                      # 宛先番号（仮想番号）
    "from": "819012345678",                   # エンドユーザーの携帯電話番号
    "text": "Hello World"                     # SMS 本文
}

try:
    # プラットフォームから Webhook への HTTP GET リクエストをシミュレート
    response = requests.get(url, params=params)
    response.raise_for_status()
    
    print(f"Webhook シミュレーション成功。サーバーレスポンスステータスコード: {response.status_code}")
    print(f"レスポンスボディ: {response.text}")

except requests.exceptions.RequestException as e:
    print(f"シミュレーション失敗: {e}")

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

// あなたの Webhook URL
const url = 'https://example.com/mo-callback';

// 受け取った SMS受信 (MO) のクエリパラメータをシミュレート
const params = {
    type: 'mo',                             // メッセージタイプ、mo で固定
    messageid: '015bd4-d6dfa7-58w',         // メッセージ ID (グローバルで一意)
    to: '05012345678',                      // 宛先番号（仮想番号）
    from: '819012345678',                   // エンドユーザーの携帯電話番号
    text: 'Hello World',                    // SMS 本文
};

// プラットフォームから Webhook への HTTP GET リクエストをシミュレート
axios.get(url, { params })
    .then((response) => {
        console.log(`Webhook シミュレーション成功。サーバーレスポンスステータスコード: ${response.status}`);
        console.log(`レスポンスボディ: ${response.data}`);
    })
    .catch((error) => {
        console.error('シミュレーション失敗:', error.message || error);
    });

<?php

// あなたの Webhook URL
$url = "https://example.com/mo-callback";

// 受け取った SMS受信 (MO) のクエリパラメータをシミュレート
$params = [
    "type" => "mo",                             // メッセージタイプ、mo で固定
    "messageid" => "015bd4-d6dfa7-58w",         // メッセージ ID (グローバルで一意)
    "to" => "05012345678",                      // 宛先番号（仮想番号）
    "from" => "819012345678",                   // エンドユーザーの携帯電話番号
    "text" => "Hello World"                     // SMS 本文
];

// クエリストリングを構築して URL に追加
$queryString = http_build_query($params);
$requestUrl = $url . '?' . $queryString;

// Webhook リクエストをシミュレートするために cURL セッションを初期化
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $requestUrl);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

// リクエストを実行
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);

if($e = curl_error($ch)) {
    echo "シミュレーション失敗: " . $e;
} else {
    echo "Webhook シミュレーション成功。サーバーレスポンスステータスコード: " . $httpCode . "\n";
    echo "レスポンスボディ: " . $response . "\n";
}

// cURL セッションを閉じる
curl_close($ch);
?>

import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.Response;
import okhttp3.HttpUrl;
import java.io.IOException;

// pom.xml または build.gradle に OkHttp の依存関係が追加されていることを確認してください
public class MoWebhookSimulation {
    public static void main(String[] args) {
        OkHttpClient client = new OkHttpClient();

        // クエリパラメータを持つ Webhook URL を構築
        HttpUrl.Builder urlBuilder = HttpUrl.parse("https://example.com/mo-callback").newBuilder();
        urlBuilder.addQueryParameter("type", "mo");                         // メッセージタイプ、mo で固定
        urlBuilder.addQueryParameter("messageid", "015bd4-d6dfa7-58w");     // メッセージ ID (グローバルで一意)
        urlBuilder.addQueryParameter("to", "05012345678");                  // 宛先番号（仮想番号）
        urlBuilder.addQueryParameter("from", "819012345678");               // エンドユーザーの携帯電話番号
        urlBuilder.addQueryParameter("text", "Hello World");                // SMS 本文

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

        // リクエストを構築
        Request request = new Request.Builder()
                .url(url)
                .get()
                .build();

        // プラットフォームの Webhook をシミュレートするためにリクエストを実行
        try (Response response = client.newCall(request).execute()) {
            System.out.println("サーバーレスポンスステータスコード: " + response.code());
            if (response.body() != null) {
                System.out.println("レスポンスボディ: " + response.body().string());
            }
        } catch (IOException e) {
            System.err.println("シミュレーション失敗: " + e.getMessage());
        }
    }
}

package main

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

func main() {
    // あなたの Webhook URL
    baseURL, err := url.Parse("https://example.com/mo-callback")
    if err != nil {
        fmt.Println("URL の解析エラー:", err)
        return
    }

    // 受け取った SMS受信 (MO) のクエリパラメータをシミュレート
    params := url.Values{}
    params.Add("type", "mo")                             // メッセージタイプ、mo で固定
    params.Add("messageid", "015bd4-d6dfa7-58w")         // メッセージ ID (グローバルで一意)
    params.Add("to", "05012345678")                      // 宛先番号（仮想番号）
    params.Add("from", "819012345678")                   // エンドユーザーの携帯電話番号
    params.Add("text", "Hello World")                    // SMS 本文

    // パラメータをエンコードして URL に追加
    baseURL.RawQuery = params.Encode()

    // プラットフォームから Webhook への HTTP GET リクエストをシミュレート
    resp, err := http.Get(baseURL.String())
    if err != nil {
        fmt.Println("シミュレーション失敗:", err)
        return
    }
    defer resp.Body.Close()

    // レスポンスボディを読み取る
    body, err := ioutil.ReadAll(resp.Body)
    if err != nil {
        fmt.Println("レスポンスの読み取りエラー:", err)
        return
    }

    fmt.Printf("Webhook シミュレーション成功。サーバーレスポンスステータスコード: %d\n", resp.StatusCode)
    fmt.Printf("レスポンスボディ: %s\n", string(body))
}

5. レスポンス要件と再試行ポリシー

成功レスポンス：サーバーがリクエストを正常に受け取り処理した後、このコールバックが正しく受け取られたことを PaaSoo に確認させるため、必ず HTTP 200 OK または同様の 2xx 成功ステータスコードを返す必要があります。
再試行メカニズム：PaaSoo が有効な 2xx レスポンスを受け取らなかった場合（サーバーのタイムアウトや 4xx/5xx を返した場合など）、システムは 5 分、10 分、30 分 の間隔で 1 回ずつ再プッシュを試みます。それでも HTTP 200 を受け取れない場合、システムはそれ以降の再試行を放棄します。

6. セキュリティとベストプラクティス

データ転送のセキュリティ：
- 送信中の SMS コンテンツの安全性を保証するため、Webhook URL は HTTPS プロトコルを使用して暗号化することを強く推奨します。
アクセス制御：
- 悪意のあるスキャンや偽装された呼び出しを防ぐため、サーバーまたはゲートウェイに IP ホワイトリスト を設定し、PaaSoo 公式サーバーの IP 帯域からのリクエストのみを許可することをお勧めします。
冪等性の設計：
- ネットワークの揺らぎや再試行メカニズムにより、サーバーが同一の SMS受信 (MO) メッセージを複数回受け取る可能性があります。データベースへの挿入やビジネスロジックの重複排除処理（冪等性）を実装する際は、必ず messageid（メッセージ ID）を一意の識別子として使用してください。

テクニカルサポート

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

1. Webhook の設定と説明​

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

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

4. 受信と処理のサンプル​

5. レスポンス要件と再試行ポリシー​

6. セキュリティとベストプラクティス​