CPaaSを使ったアプリケーション開発

CPaaSでSMSを送信しよう

前回の記事では、CPaaSがどのようなサービスなのか、CPaaSベンダーにはどのような会社があるのかなどについて紹介しました。今回は、実際にCPaaSベンダーと契約して、SMSを送信するステップについて説明していきます。

SMS(Short Message Service)とは

SMSは、電話番号を指定して短文を送受信することができるキャリア(通信事業者)が提供するサービスです。異なるキャリア間でもメッセージのやり取りができるため、電話と同じような利便性があります。メールとは異なり相手に届きやすく、かつ読まれる可能性が高いことから、個人間のメッセージのやり取りだけでなく、システムを通じて個人に対してメッセージを配信する手段としても利用されています。

個人間のSMSをP2P(Person to Person)SMS、システムと個人とのメッセージのやり取りをA2P(Application to Person)SMSと呼びます。CPaaSを使ったSMSはA2Pの分野で利用されており、代表的な使い方として二要素認証やリマインダー通知などがあります。また、電話番号を認証に使うことで、一人で複数アカウントを不正に作成することを防止する効果もあります。

SMSの仕様

それではSMSの仕様について見ていきます。

メッセージのサイズ

ショートメッセージという名前のとおり、メッセージの長さは英数字のみで160文字、日本語などを含む場合は70文字を1セグメントとして扱うのが基本です。ただ最近では、コンカチ(コンカチネーション)と呼ばれるしくみによって、複数セグメントを1つのメッセージとして扱えるようになりました。

そのため現在は10セグメントを1メッセージとして、英数字のみで最大1530文字、日本語を含む場合でも670文字まで送信できます。ただし送信料はセグメント単位で計算されるため、文字数が多くなるとその分料金も高くなります。また、後述する国際SMSの場合は、複数セグメントが分割されて届くこともありますので、国際SMSを利用する場合はなるべく1セグメントに収まるサイズで送信しましょう。

国内SMS

日本国内のキャリアと直接契約することによって、ギャランティ型のサービスを提供するのが国内SMSです。ただし、キャリアと直接契約するのはとてもハードルが高いため、すでにキャリアと接続している事業者と契約することで国内SMSを送信するのが一般的です。

国内SMSは通信経路が安定しているため、到達率が高い(ほぼ100%)のが特長です。また、送信時に顧客の電話機が圏外だったり電源が入っていない場合などは、キャリア側で再送を行ってくれます。一方で、事業者への申し込みには審査が必要です。たとえばどのようなメッセージを送信するのか、送信にあたって事前に顧客に同意を得ているのかなどが審査の対象項目となります。

CPaaSを利用する場合もCPaaSベンダーがキャリア直収事業者とすでに契約しているため、事前審査や別途申込みをすることで国内SMSを利用できます。

国際SMS

SMSには海外キャリアを経由したメッセージ送受信の方法も用意されています。これを国際SMSと呼びます。

国際SMSはベストエフォート型のサービスであり、送信元のキャリアと国内キャリアの間には複数の事業者(アグリゲーター)が仲介することもあります。そのため、メッセージの大量送信で負荷がかかったり、スパム送信だと判定されたりすると、アグリゲーターがメッセージを破棄することもあります。その結果、到達率は国内SMSよりは低くなります。また、国内SMSのようなキャリアによる再送も行われません。

国際SMSを使った国内へのメッセージ送信には特別な審査は不要なため、手軽にSMS送信ができるメリットがある反面、フィッシング詐欺などに利用されることも多くなります。

もちろん CPaaSを使って国際SMSは送信できますし、日本国内だけでなく海外へのSMS送信をする場合も国際SMSを使うことになります。

図1 SMSの送信経路

送信元の表記

SMSを送信する場合、送信元を表示する方法には大きく以下の2つがあります。

  • 電話番号を表記する方法
  • 文字列(Alfa-numeric Sender Id)を表記する方法

国内SMSを利用する場合は、キャリア直収事業者が保有する国内番号(ショートコードを含む)を発信元番号として表記できます。この番号については、他の契約者と同じ番号を利用する共有番号と、契約者独自の番号を利用する専用番号の2種類があります。

一方国際SMSでは、CPaaSベンダーによって表記の仕様が異なるものの、国内番号は表記できないため海外の電話番号を表記したり、文字列を表記することになります。

DLR(Delivery Reporting)

送信元が送信状況を確認するために用意されているのがDLRです。とくに国際SMSでは、SMSの送信がベストエフォートで行われるため、DLRはとても重要です。送信先のキャリアがメッセージをエンドユーザー送信できたときや、何らかの理由によって送信できなかったときなどに、送信元に対してDLRが送られます。

CPaaSを利用してSMSを送信する場合、DLRはCPaaSベンダーに対して返信されてくるため、CPaaSベンダーがWebhookを使ってアプリケーションに通知するのが一般的です。どのような内容のWebhookが戻ってくるかはCPaaSベンダーによって異なるため、詳しくはCPaaSベンダーのリファレンスを確認することになります。

CPaaSを使ったSMS送信の準備

ではいよいよここから、CPaaSを使ってSMSを送信してみましょう。

今回はCPaaSベンダーにVonageを利用します。Vonageの紹介については前回の記事を参照してださい。また、APIコールのためにPostmanを利用します。

Vonageアカウントの開設

日本国内でVonageアカウントを作成するには、Vonage Japanのサイトから作成するか、KDDIウェブコミュニケーションズから作成するかの2種類があります。法人として契約ができる場合は、日本語サポートが受けられ、かつ料金が若干安いKDDIウェブコミュニケーションズ経由をおすすめしますが、もし個人で契約を行うのであればVonage Japanのサイトから契約をしてください[1]

Vonageアカウントを新規で開設した場合、アカウントの種類は「トライアル」になります。トライアルアカウントの制限事項は以下のとおりです。

  • 付与された€2.00分のクレジットがなくなった時点で利用ができなくなります。
  • 電話番号を購入することはできません。
  • SMSは契約時に設定した自分の認証済み番号にのみ送信が可能です。
  • 送信されたSMSには、[FREE SMS DEMO, TEST MESSAGE]という文字列が付加され、削除はできません。

アカウントをアップグレードすると、上記の制限は解除されます。

なお、送信料はキャリアによって異なります。KWCPLUS経由のアカウントでは、国内キャリア宛の国際SMSの送信料は、1通(セグメント)11円(税込み)です。料金表はKDDIウェブコミュニケーションズのKWCPLUSのサイトを確認してください。

Postmanの準備

Postmanは、APIを使ったサービスの開発にとても役立つツールです。単純にAPIのテストを行うだけでなく、APIコールを連続して実行する「フロー」や、APIサーバーを模倣するための「モックサーバー」など、いくつもの便利な機能を持っています。

今回はVonageのAPIを呼び出すためにPostmanを利用します。Postmanのインストールがまだの場合は、Postmanのサイトからセットアップをしてください。

SMSを送信してみよう

Vonageを使ってSMSを送信するAPIは2つあります。一つはSMS APIで、もう一つがMessages APIです。Messages APIは従来のSMS APIの後継バージョンで、SMSだけでなくWhatsappやViber、Facebook Messengerなどにもメッセージを送信できます。

今回は新しいバージョンのMessages APIを使います。

Messages APIの仕様を確認する

APIコールをするためには、まずはAPIの仕様を調べる必要があります。

Vonage Messages APIのリファレンスは、Vonage Developer Centerに記載されています。APIを調べるポイントは、大きく以下の3つです。

  • エンドポイントとメソッド
  • 認証方法
  • 送信するBody、もしくはQueryStringの仕様

今回のエンドポイントは以下のとおりです。

図2 エンドポイント

認証方法は以下のとおりです。

図3 認証方法

つまり、このAPIは2種類の認証(JWT認証とBasic認証)をサポートしています。

JWTのほうが認証としては強固なのですが、一方でPKIの準備と時間情報(トークンの有効期限など)を必要とするため少々面倒です。今回はAPI KeyとAPI Secretを使ったBasic認証で進めます。

SMSを送信する際のBodyは以下のとおりです(今回利用するもののみ抜粋⁠⁠。

大項目 説明
text 送信する本文を指定します(日本語利用可⁠⁠。文字コードGSM-7(半角英数)だけの場合で160文字、UCS-2(全角)を含む場合は全体で70文字で1セグメントとしてカウントされる。それ以上の文字を送信すると、セグメントが分割される。最大送信文字数は、GSM-7のみの場合で3,800文字、UCS-2が含まれる場合は最大660文字となる
to 送信先の電話番号をMSISDN形式で指定する(例:8190XXXXYYYY)
from 日本宛のSMSは、電話番号形式は利用できないため、英数字で指定する(例:VONAGE)3〜11文字
channel smsと指定する
client_ref Webhookを受け取る際に、送信したSMSを識別するために100文字以内の文字列を指定する(オプション)
ttl SMS送信を行う際の許容する遅延時間をで指定する(300以上、デフォルトは90000)
webhook_url webhookの送信先URLを指定する
message_type textと指定する

Messages APIのWebhook

Webhookを使うことで、SMSを送信した際の送信状況を取得できます。

Message Statusに関するWebhookの仕様はVonage Developer Centerに記載されています。

Webhookで渡されるパラメータは以下のとおりです(主要なものを抜粋⁠⁠。

パラメータ名 値の説明
message_uuid メッセージのユニークID
to 送信先の電話番号(MSISDN形式)
from 送信元番号、もしくは文字列
timestamp 送信日時(ISO8601 形式)
status 配信ステータスsubmitted/delivered/rejected/undeliverable
error エラーが発生した場合の詳細
client_ref 送信時に指定したclient_ref
usage 利用料(EUR)

配信ステータス

SMSの受信確認の仕組みは次のようになっています(Vonageサイトより引用⁠⁠。

図4 SMSの受信確認の仕組み

Delivery Receipt Webhookで返されるステータスの詳細についても確認しましょう。先の表にも記載したとおり、Messages APIで戻ってくるステータスは以下の4つのいずれかです。

ステータス 説明
submitted SMSの配信を受け付けました
delivered 先方からDLRを受信しました
rejected 送信処理が拒否されました
undeliverable 送信処理が失敗しました

submittedは、VonageがAPIを受け付けたことを表します。その後、先方のキャリア経由でDLRが戻ってきたらdeliveredが返ります。

rejectedundeliverableの2つについては、さらにエラーの詳細を確認できます。エラーの詳細はVonageの開発者サイトに記載があります。ちなみに、携帯電話の電源が切れていたり、圏外にいる場合はrejectedが戻ります。

Messages APIを使ってSMSを送信する

それでは実際にSMSを送信してみましょう。送信にはPostmanを利用します。また、Webhookの受け先として、同じくPostmanのモックサーバーを利用してみます。

APIをコールする際に必要となる、VonageのAPI KeyとAPI Secretは事前に確認しておいてください。

図5 Vonage API Dashboard

1.Postmanでワークスペースを作成する

まずは、Postmanの設定を行っています。作業用のワークスペースで、Webhookを受け付けるためのモックサーバーを作成します。その後、コレクションを作成して実際のAPIコールを行います。

なお、Postmanを日本語化するには、Postmanを起動して画面上部の歯車アイコンを選択し、設定 > 一般 の中のアプリケーションで言語の設定をしてください。さらに、自動保存をONにしておくことでパラメータの保存し忘れ防止になります。

図6 Postmanの設定画面

ワークスペースを作ります。Postmanのトップにあるワークスペースプルダウンからワークスペースを作成ボタンを押します。

図7 「ワークスペースを作成」ボタン

「空のワークスペース」が選択されているのを確認し、次に進むボタンを押します。

図8 「次に進む」を選択

名前フィールドに「Vonage Handson」と入力し、作成ボタンを押します。

図9 名前を指定

これで作業用のワークスペースが完成しました。

次に、利用する機能が非表示になっているので有効にするために、左側のサイドバーの設定アイコンを押します。そしてモックサーバーフローをONにします。

図10 ワークスペースの設定(ONにする前)

2. モックサーバーを作成する

次に、Webhookの受け先としてモックサーバーを設定します。

モックサーバーを使うことで、Webhookを簡易的に受け付けるサーバーを用意できます。WebhookのURLだけでなくヘッダーやボディのパターンによって返却する値を変えられるため、Webhookのテストなどにとても重宝します。

サイドメニューのモックサーバーを選択して、モックサーバーを作成をクリックします。

図11 「モックサーバーを作成」を選択

そして次の項目を設定します。

  • リクエストメソッドのプルダウンから「POST」を選択します。
  • リクエストURLに、⁠webhook/status」と入力します。
  • レスポンスボディに、⁠OK」と入力します。
  • 次に進むボタンを押します。
図12 モックサーバーの設定

そして、モックサーバーの名前欄に「Webhook」と入力して、モックサーバーを作成ボタンを押します。

図13 モックサーバーの名前を指定

モックサーバーができたら、生成されたモックサーバーのURLをメモしておきましょう。

図14 モックサーバーのURLを確認

3. 環境変数を作成する

次に、APIキーなどの変数を環境変数に登録します。

環境変数を利用することで、秘匿すべきデータを守るだけでなく、APIリクエストに直接変数を書く必要がなくなります。また、環境変数に名前をつけてグルーピングできるため、開発用と本番用の変数を別に登録しておくといったことが可能です。

左側の環境アイコンを選択して、環境を作成をクリックします。

図15 環境を設定

環境変数名を「Gihyo」に変更します。名前は何でも構いません。

図16 環境変数名を指定

変数を登録していきます。登録する変数は以下のとおりです。

変数 タイプ 初期値 現在値
API Key デフォルト YOUR_API_KEY ご自分のVonage API Keyを指定してください
API Secret デフォルト YOUR_API_SECRET ご自分のVonage Secret Keyを指定してください
Mock URL デフォルト YOUR_MOCK_URL 先ほど作成したモックサーバーのURLを指定してください
図17 変数を指定

4. コレクションを作成する

ではいよいよMessages APIを呼び出していきます。そのために、まずはコレクションを作成します。

APIのリクエストをグループ化して管理するのがコレクションになります。このコレクションに対して認証・認可を設定しておくことで、その配下のリクエストにコレクションの設定を継承させることができます。これによって、リクエストごとの個別の設定が不要になるため便利です。

左側のコレクションアイコンを選択し、さらにプラスアイコンを押して新しいコレクションを作成します。コレクション名には「Vonage Messages API」と入力します。

図18 コレクションを作成

作成したコレクションにおいて認可情報を設定します。

  • 左上の環境プルダウンから、先ほど作成した環境変数「Gihyo」を選択します。
  • 認可タブに移動します。
  • Auth Typeプルダウンから「Basic認証」を選択します。
  • ユーザー名欄で、{{API Key}}と入力します(波括弧を入力すると変数名がリストされるのでそれを選択します⁠⁠。
  • パスワード欄で、{{API Secret}}と入力します。
図19 コレクションの「認可」タブで設定

さらに、次の手順でリクエスト作成します。

  • 左側のコレクションリスト「Vonage Messages API」の中に記載されているリクエストを追加をクリックして、リクエストを作成します。
  • リクエストの名前を「Send a message」に変更します。
  • メソッドを「POST」に変更します。
  • リクエストURL欄にhttps://api.nexmo.com/v1/messagesと入力します。
  • ボディタブを選択します。
  • ボディのタイプを「Raw」に変更し、形式を「JSON」とします。
  • 以下のJSONをコピペして貼り付けます。
{
    "text": "Messages APIのテスト",
    "to": "8190XXXXYYYY",
    "from": "HANDSON",
    "channel": "sms",
    "webhook_url": "{{Mock URL}}/webhook/status",
    "client_ref": "test phone",
    "message_type": "text"
}

toの部分は、自分の携帯電話の電話番号をMSISDN形式で指定してください。

  • 例:080XXXXYYYY → 8180XXXXYYYY
図20 リクエストの作成

5. リクエストを発行する

ではさっそくリクエストを発行してSMSが届くことを確認しましょう。

リクエスト作成した画面で、送信ボタンを押します。SMSが届き、202 Acceptedが表示されることを確認できるはずです。

図21 リクエストを送信

もし401エラーが出た場合は、コレクションの認証・認可設定が保存されていないか、環境変数が正しく選択されていない可能性があります。

配信ステータスを確認する

最後にWebhookを確認しましょう。

左側のモックサーバーアイコンを選択して、先ほど作成した「Webhook」を選択します。送信が成功した場合は、Webhookが2つ届いていることが確認できます。最初のWebhookのステータスは、submittedで、2つ目のステータスはdeliveredになっていることを確認できます。

図22 モックサーバーを確認

もしログが表示されない場合は、ログを更新をクリックしてください(ログが反映されるまでに少しタイムラグがあります⁠⁠。

今回は取り上げませんが、電話番号を架空の番号にしたり、スマホの電源を切った状態で送信するなどして、レスポンスがどのようになるかを確認することもできます。ぜひ試してみてください。

まとめ

今回は、API開発ツールであるPostmanを使って、Vonage Messages APIやVoice APIの仕組みやエラー対応などを検証してみました。

CPaaSを使えば、想像以上に簡単にSMSを送信できることが理解できたのではないかと思います。今回は送信する方法しか説明しませんでしたが、VonageからのWebhookを受け取ることでエラーのハンドリングもできます。

さて次回はいよいよ最終回。Vonage VoiceとAI Studioを使って電話の着信にAI機能を組み込んでいきましょう。

おすすめ記事

記事・ニュース一覧