Zenn
KWCPLUSPublicationへの投稿
🔰

Vonage SMS ガイド

小原聖健
2024/03/28に公開
#
sms
#
vonage
tech

こんにちは。KDDI ウェブコミュニケーションズの小原です。

Vonage（ボネージ）の SMS 送信は数行程度のコードで実現できます。このガイドでは、SMS 送信の概要、必要な準備、送信方法、トラブルシューティングなどについて説明します。

要約

  • SMS API ではなく Messages API を推奨
  • 電話番号の取得は不要
  • 最大文字数： 660 文字
  • 課金単位：70 文字単位
  • 秒間送信数： 30 通（30MPS）
  • 到達率： 業界標準
  • 日本の電話番号から受信不可

要件

Vonage の SMS

国際 SMS と国内直収 SMS を同一料金で提供します。

国際 SMS 国内直収 SMS
利用方法 標準で利用可能 別途お申し込み
秒間送信数 (MPS) 30 30
最大文字数 660 文字 660 文字
課金単位 70 文字 70 文字
電話番号の取得 不要 不要
送信経路 複数の海外キャリア経由 国内キャリアに直接
到達率 △ ◎
From Alphanumeric Sender ID 他社と共通番号
専用番号（オプション） × 〇
受信 × ×
双方向 SMS（オプション） × 〇

到達率についてはトラブルシューティングで解説します。

Vonage でできないこと

  • 電話番号を使った SMS 送信
  • 日本の電話番号からの SMS 受信
    • 海外の番号同士であれば受信可能
  • 秒間 30 通以上の送信（30MPS）

Messages API と SMS API の違い

Vonage には SMS を送信する方法として Messages API と SMS API があります。

弊社では Messages API の利用を推奨します。

Messages API は SMS API と同じ機能に加え、将来的に LINE や RCS 対応が予定されています。コードに互換性がないため、今から開発するのであれば Messages API を推奨します。

Messages API SMS API
最大文字数 660文字 660文字
MPS（秒間の送信数） 30 30
SMS 〇 〇
Facebook Messenger 〇 ×
MMS 〇 ×
Viber 〇 ×
WhatsApp 〇 ×
Proactive Connect 〇 ×
LINE 予定 ×
RCS 予定 ×

Messages API サンプルコード

client = vonage.Client(
    application_id=VONAGE_APPLICATION_ID,
    private_key=VONAGE_APPLICATION_PRIVATE_KEY_PATH,
)

client.messages.send_message(
    {
        "channel": "sms",
        "message_type": "text",
        "to": TO_NUMBER,
        "from": VONAGE_BRAND_NAME,
        "text": "日本語のテスト",
    }
)

参考資料

SMS API サンプルコード

client = vonage.Client(
    key=VONAGE_API_KEY,
    secret=VONAGE_API_SECRET
)

client.sms.send_message(
    {
        "type": "unicode",
        "to": TO_NUMBER,
        "from": VONAGE_BRAND_NAME,
        "text": "日本語のテスト",
    }
)

参考資料

Messages API の初期設定

Messages API を利用するには設定が必要です。

デフォルトの SMS 設定

この設定は Vonage 全体の設定になるため、一度設定すれば完了です。

  1. 左メニューの「API 設定」を選択
  2. 「デフォルトの SMS 設定」の「Messages API」を選択

デフォルトの SMS 設定

  1. 画面右下の「変更を保存」を選択
  2. 確認のダイアログが出るため「SWITCH」と入力し、「切り替えて保存」を選択

Messages API に SWITCH

Webhook の用意

Messages API の認証には次節で案内するアプリケーションの作成が必要です。

その際、Webhook の設定が必要になるため、ここでは ngrok を使った一時的な Webhook を用意します。実運用であれば Vonage からアクセス可能なサーバ（AWS や VPS、自社サーバなど）を用意する必要があります。

  1. flask のインストール
  2. webhook.py の用意
  3. webhook.py の起動
# Flask のインストール
pip install flask

# webhook.py
import json

from flask import Flask, request

app = Flask(__name__)


@app.route("/", methods=["GET", "POST"])
def show():
    requestData = request.get_data()
    requestJson = json.loads(requestData)
    print(json.dumps(requestJson, indent=2))
    return requestData


if __name__ == "__main__":
    app.run()

# webhook.py の起動
$ python webhook.py
 * Serving Flask app 'webhook'
 * Debug mode: off
WARNING: This is a development server. Do not use it in a production deployment. Use a production WSGI server instead.
 * Running on http://127.0.0.1:5000
Press CTRL+C to quit

Webhook は Vonage からアクセス可能である必要があるため、ローカルで動く webhook.py を ngrok でインターネット上に公開します。

ngrok のインストール方法は Mac や WSL などの OS によって異なるため ngrok 公式のインストール方法をご参照ください。Step 2: Connect your account まで進めてください。

インストールが終わったら ngrok を起動します。

# 5000 で動く webhook.py を ngrok で公開
$ ngrok http 5000
Build better APIs with ngrok. Early access: ngrok.com/early-access                                                                                                                                                                              Session Status                online                                                                                    Account                       kwcplus (Plan: Free)                                                                     Version                       3.6.0                                                                                     Region                        Japan (jp)                                                                                Latency                       -                                                                                         Web Interface                 http://127.0.0.1:4040                                                                     Forwarding                    https://1234-56-789-0ab-cd.ngrok-free.app -> http://localhost:5000                                                                                                                                                Connections                   ttl     opn     rt1     rt5     p50     p90                                                                             0       0       0.00    0.00    0.00    0.00

Forwarding に各自ユニークな URL が発行されます（Ex. https://1234-56-789-0ab-cd.ngrok-free.app）。この URL が Vonage に設定する Webhook の URL になります。

http://localhost:4040/ にアクセスし、下記画面が表示されれば成功です。Vonage から Webhook にアクセスがあるとこの画面に内容が表示されます。

ngrok ready

アプリケーションの作成

Messages API を認証して利用するには「アプリケーション ID」と「秘密鍵」を発行し、アプリケーションの「メッセージ」を有効化します。

  1. 左メニューの「アプリケーション」を選択
  2. 「新しいアプリケーションを作成する」を選択
  3. 「名前」にわかりやすい識別子（SMS 送信など）を指定
  4. 「認証」の「公開鍵と秘密鍵を生成」を選択し、ダウンロードした private.key（秘密鍵）を保存
  5. 「メッセージ」に「着信 URL」と「ステータス URL」に ngrok の URL を設定。どちらも同じ URL で構いません
  6. 画面右下の「新しいアプリケーションの生成」を選択

アプリケーションを作成する

  1. 発行された「アプリケーション ID」をメモ

アプリケーションを作成する

Messages API に利用する「アプリケーション ID」と「秘密鍵」は大切に保管ください。

なお、以上の作業は Vonage CLI もしくは Application API でも設定可能です。

SMS 送信

アプリケーション ID と秘密鍵が用意できたので SMS を送信する準備が整いました。

ここでは Python を使います。ほかの言語をご利用の方はタブから言語を選択して適宜読み替えてください。

送信サンプル

SDK のインストール

「Install dependencies」をクリックすると SDK のインストール方法が表示されます。

SDK のインストール

pip install vonage

SMS の送信

送信プログラムは send_sms.py とします。

import os

import vonage

# クレデンシャル
VONAGE_APPLICATION_ID = os.environ.get("VONAGE_APPLICATION_ID")
VONAGE_APPLICATION_PRIVATE_KEY_PATH = os.environ.get(
    "VONAGE_APPLICATION_PRIVATE_KEY_PATH"
)

# From, To
VONAGE_BRAND_NAME = os.environ.get("VONAGE_BRAND_NAME")
TO_NUMBER = os.environ.get("TO_NUMBER")

# 本文
VONAGE_SMS_BODY = os.environ.get("VONAGE_SMS_BODY")

# 初期化
client = vonage.Client(
    application_id=VONAGE_APPLICATION_ID,
    private_key=VONAGE_APPLICATION_PRIVATE_KEY_PATH,
)

# SMS 送信
response = client.messages.send_message(
    {
        "channel": "sms",
        "message_type": "text",
        "to": TO_NUMBER,
        "from": VONAGE_BRAND_NAME,
        "text": VONAGE_SMS_BODY,
    }
)
print(response)

send_sms.py で利用する環境変数は下記です。

環境変数 値
VONAGE_APPLICATION_ID メモしたアプリケーション ID
VONAGE_APPLICATION_PRIVATE_KEY_PATH 保存した private.key
VONAGE_BRAND_NAME Alphanumeric Sender ID
TO_NUMBER 送信先電話番号（E.164）
VONAGE_SMS_BODY SMS 本文（UTF-8 + LF）

Alphanumeric Sender ID

Vonage の SMS は From にアメリカ番号を利用できないため、下記ルールの Alphanumeric Sender ID を利用します。

  • 3 ～ 11 文字
  • 利用可能な文字は a ～ z, A ～ Z, 0～9, スペース
    • 数字のみは不可

たとえば「KWC 2FA」や「KWCPlus」が利用可能です。

E.164/MSISDN

Vonage は世界中に SMS 送信できるため、電話番号に国番号を含めた E.164/MSISDN 形式で書く必要があります。

日本の国番号は 81 です。

電話番号の先頭の 0 を外し、先頭に国番号を追加します。

たとえば電話番号が 080-XXXX-YYYY であれば 8180XXXXYYYY になります。

E.164 は先頭に + を追加した +8180XXXXYYYY 形式もありますが、Vonage は + が不要です。

SMS の文字コードと課金単位

文字コード

Vonage は SMS 本文を UTF-8 で書きます。

Vonage は UTF-8 で受け取り、自動で SMS が利用する文字コードの GSM-7 もしくは UCS-2 に変換して送信します。

文字コード 最大送信数 課金単位 備考
GSM-7 3800 文字 160 文字単位
UCS-2 660 文字 70 文字単位 GSM-7 以外の文字が含まれる場合

GSM-7 は英数字や記号などです。

UCS-2 は GSM-7 以外の文字、つまり日本語などが含まれると自動で選ばれます。

最大送信数や課金単位は文字数単位となり、バイト数ではありません。UCS-2 であれば「あa」は 2 文字です。

例外があり、次の記号は SMS の制御に使われるためエスケープ処理されて 2 文字として換算されます。

| ^ € { } [ ] ~ \

分割にはさらに細かいルールがありますが、その説明と、簡単に何分割されるかは
連結エンコード
中ほどの Try it out が便利です。

「a」は 160 文字で分割されませんが、「[」は 81 文字で Part 1 と Part 2 で二分割されます。

Basic Character Set の分割

Basic Character Set Extension の分割

課金単位

課金は GSM-7 なら 160 文字単位、UCS-2 なら 70 文字単位になります。

API で指定した文字数が UCS-2 で 71 文字の場合、2 通の課金になります。

課金の単位は文字数単位であって、API 単位ではないことにご注意ください。文字数で課金されるため、改行コードが CRLF は 2 文字になり、LF なら 1 文字で済みます。

自動で 70 文字もしくは 160 文字に分割され、宛先のスマホには自動で連結されて届きます。そのため Concatenated SMS やコンカチ SMS と呼ばれることがあります。

SMS送信

ややこしい話が続きましたが、以上を踏まえて SMS を送信してみましょう。TO_NUMBER に書いた番号に届いたでしょうか？

$ VONAGE_APPLICATION_ID=アプリケーション ID \
  VONAGE_APPLICATION_PRIVATE_KEY_PATH=private.key \
  VONAGE_BRAND_NAME="AlphaNum 11"
  TO_NUMBER=8180XXXXYYYY \
  VONAGE_SMS_BODY=$'こんにちは\nテストです' \
  python send_sms.py
{'message_uuid': 'f1234ba5-de67-4157-bdfa-27e309f51627'}

Webhook

SMS を送信すると Vonage から Webhook に Delivery receipts が届きます。

Vonage がキャリアに送信を依頼すると submitted、送信先端末から到達の連絡があると delivered になります。

（submitted はドキュメントに記載がないため依頼しております）

http://127.0.0.1:4040/inspect/http

{
    "to": "8180XXXXYYYY",
    "from": "AlphaNum 11",
    "channel": "sms",
    "message_uuid": "7506c56b-a6ff-45e6-8c62-868fa34afc4d",
    "timestamp": "2024-03-07T04:35:56Z",
    "usage": {
        "price": "0.06667",
        "currency": "EUR"
    },
    "status": "submitted",
    "destination": {
        "network_code": "44020"
    },
    "sms": {
        "count_total": "1"
    }
}

{
    "to": "8180XXXXYYYY",
    "from": "AlphaNum 11",
    "channel": "sms",
    "message_uuid": "7506c56b-a6ff-45e6-8c62-868fa34afc4d",
    "timestamp": "2024-03-07T04:36:00Z",
    "status": "delivered",
    "destination": {
        "network_code": "44010"
    }
}

ログ

ダッシュボードでは Messages ログと SMS ログで同じものが見えます。

SMS ログでは、Status の delivered などをクリックすると「SMS ライフサイクル」を見ることができます。

SMS ログ

「配信ステータス（DLR）」は詳細なステータスを確認できます。

送信に失敗した場合に、ネットワークエラーや、受信者不在など確認できます。

DLR のステータス詳細はこちらをご参照ください。

https://developer.vonage.com/ja/messaging/sms/guides/delivery-receipts

ダッシュボードで見られる期間は 30 日です。30 日より前のログを閲覧するには有料の Reports API か、Webhook のログを独自保存する必要があります。

トラブルシューティング

送信した SMS が届かない問題の切り分けには SMS 送信の仕組みを知る必要があります。

国際 SMSと国内直収 SMS について

図の「キャリア」が海外キャリアか、国内キャリア（au、docomo、Softbank、楽天モバイル）かの違いになります。

海外キャリアは複数の海外キャリアを経由して国内キャリアにたどり着きます。

国内キャリアの障害率は非常に低いのですが、海外キャリアは国内キャリアに比べ障害率が高くなります。そのため、国内直収に比べて到達率が下がります。

Vonage は日本も含めたキャリアの障害情報を Vonage API Status で公開しています。障害の多くは海外キャリアの障害になります。

国際 SMS の到達率は低くても、Webhook の status を確認して再送することで到達率を高めることができます。

到達率について

国内直収 SMS の到達率は 99% ですが、一般的に 10 ～ 30% の SMS が端末に届かないことがあります。

この 99% の到達率は「③ SMS 送信」した率になり、下記理由は除外されます。

  1. SMS に送信できない電話番号への送信
    • 03 や 06 などの地域番号
    • 070/080/090 でも SMS 機能のない SIM
  2. 秒間 30 通以上の送信（30MPS）
  3. E.164 形式ではない電話番号での送信
    • 8180XXXXYYYY 形式の必要があります。080XXXXYYYY は送信できません
  4. 存在しない電話番号への送信
    • 入力間違いなど。ユーザからの初回入力時には到達可能かご確認ください。SMS 送信して URL をクリックいただくなどです
  5. 受信拒否
    • 端末契約者が許否した場合
    • 端末によってはデフォルトで受信拒否設定の場合があります
  6. 圏外、電源オフ
  7. 端末契約者の料金未納
  8. キャリアによるフィルタリング

1.～3. は「① API」で発生します。SDK もしくは Vonage からエラーメッセージが返りますので、エラーメッセージをご確認ください。課金は発生しません。課金は「② SMS 送信依頼」された場合に発生します。

4.～5. は 100% 送信することができません。SMS ログの DLR をご確認ください。

6.～7. は再送することで到達する可能性があります。過去、送信できていた場合は本事象の可能性の可能性があります。

8.は 30MPS 以下や一般的な文面では発生しません。

その他の送信できない理由としては Vonage やキャリアの障害があります。
SMS Analytics で一部 Network（キャリア）の失敗が高い場合はその可能性があります。

KWCPLUS
KWCPLUSPublication

株式会社KDDIウェブコミュニケーションズ Tech Blog

Discussion