前回の記事では、CPaaSがどのようなサービスなのか、CPaaSベンダーにはどのような会社があるのかなどについて紹介しました。今回は、実際にCPaaSベンダーと契約して、SMSを送信するステップについて説明していきます。
SMS(Short Message Service)とは
SMSは、電話番号を指定して短文を送受信することができるキャリア
個人間のSMSをP2P
SMSの仕様
それではSMSの仕様について見ていきます。
メッセージのサイズ
ショートメッセージという名前のとおり、メッセージの長さは英数字のみで160文字、日本語などを含む場合は70文字を1セグメントとして扱うのが基本です。ただ最近では、コンカチ
そのため現在は10セグメントを1メッセージとして、英数字のみで最大1530文字、日本語を含む場合でも670文字まで送信できます。ただし送信料はセグメント単位で計算されるため、文字数が多くなるとその分料金も高くなります。また、後述する国際SMSの場合は、複数セグメントが分割されて届くこともありますので、国際SMSを利用する場合はなるべく1セグメントに収まるサイズで送信しましょう。
国内SMS
日本国内のキャリアと直接契約することによって、ギャランティ型のサービスを提供するのが国内SMSです。ただし、キャリアと直接契約するのはとてもハードルが高いため、すでにキャリアと接続している事業者と契約することで国内SMSを送信するのが一般的です。
国内SMSは通信経路が安定しているため、到達率が高い
CPaaSを利用する場合もCPaaSベンダーがキャリア直収事業者とすでに契約しているため、事前審査や別途申込みをすることで国内SMSを利用できます。
国際SMS
SMSには海外キャリアを経由したメッセージ送受信の方法も用意されています。これを国際SMSと呼びます。
国際SMSはベストエフォート型のサービスであり、送信元のキャリアと国内キャリアの間には複数の事業者
国際SMSを使った国内へのメッセージ送信には特別な審査は不要なため、手軽にSMS送信ができるメリットがある反面、フィッシング詐欺などに利用されることも多くなります。
もちろん CPaaSを使って国際SMSは送信できますし、日本国内だけでなく海外へのSMS送信をする場合も国際SMSを使うことになります。
送信元の表記
SMSを送信する場合、送信元を表示する方法には大きく以下の2つがあります。
- 電話番号を表記する方法
- 文字列
(Alfa-numeric Sender Id) を表記する方法
国内SMSを利用する場合は、キャリア直収事業者が保有する国内番号
一方国際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 Japanのサイトから契約
- 法人:KDDIウェブコミュニケーションズのKWCPLUSのサイトから契約
Vonageアカウントを新規で開設した場合、アカウントの種類は
- 付与された€2.
00分のクレジットがなくなった時点で利用ができなくなります。 - 電話番号を購入することはできません。
- SMSは契約時に設定した自分の認証済み番号にのみ送信が可能です。
- 送信されたSMSには、
[FREE SMS DEMO, TEST MESSAGE]
という文字列が付加され、削除はできません。
アカウントをアップグレードすると、上記の制限は解除されます。
なお、送信料はキャリアによって異なります。KWCPLUS経由のアカウントでは、国内キャリア宛の国際SMSの送信料は、1通
Postmanの準備
Postmanは、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の仕様
今回のエンドポイントは以下のとおりです。
認証方法は以下のとおりです。
つまり、このAPIは2種類の認証
JWTのほうが認証としては強固なのですが、一方でPKIの準備と時間情報
SMSを送信する際のBodyは以下のとおりです
大項目 | 説明 |
---|---|
text | 送信する本文を指定します |
to | 送信先の電話番号をMSISDN形式で指定する |
from | 日本宛のSMSは、電話番号形式は利用できないため、英数字で指定する |
channel | sms と指定する |
client_ |
Webhookを受け取る際に、送信したSMSを識別するために100文字以内の文字列を指定する |
ttl | SMS送信を行う際の許容する遅延時間を秒で指定する |
webhook_ |
webhookの送信先URLを指定する |
message_ |
text と指定する |
Messages APIのWebhook
Webhookを使うことで、SMSを送信した際の送信状況を取得できます。
Message Statusに関するWebhookの仕様はVonage Developer Centerに記載されています。
Webhookで渡されるパラメータは以下のとおりです
パラメータ名 | 値の説明 |
---|---|
message_ |
メッセージのユニークID |
to | 送信先の電話番号 |
from | 送信元番号、もしくは文字列 |
timestamp | 送信日時 |
status | 配信ステータスsubmitted /delivered /rejected /undeliverable ) |
error | エラーが発生した場合の詳細 |
client_ |
送信時に指定したclient_ |
usage | 利用料 |
配信ステータス
SMSの受信確認の仕組みは次のようになっています
Delivery Receipt Webhookで返されるステータスの詳細についても確認しましょう。先の表にも記載したとおり、Messages APIで戻ってくるステータスは以下の4つのいずれかです。
ステータス | 説明 |
---|---|
submitted |
SMSの配信を受け付けました |
delivered |
先方からDLRを受信しました |
rejected |
送信処理が拒否されました |
undeliverable |
送信処理が失敗しました |
submitted
は、VonageがAPIを受け付けたことを表します。その後、先方のキャリア経由でDLRが戻ってきたらdelivered
が返ります。
rejected
とundeliverable
の2つについては、さらにエラーの詳細を確認できます。エラーの詳細はVonageの開発者サイトに記載があります。ちなみに、携帯電話の電源が切れていたり、圏外にいる場合はrejected
が戻ります。
Messages APIを使ってSMSを送信する
それでは実際にSMSを送信してみましょう。送信にはPostmanを利用します。また、Webhookの受け先として、同じくPostmanのモックサーバーを利用してみます。
APIをコールする際に必要となる、VonageのAPI KeyとAPI Secretは事前に確認しておいてください。
1.Postmanでワークスペースを作成する
まずは、Postmanの設定を行っています。作業用のワークスペースで、Webhookを受け付けるためのモックサーバーを作成します。その後、コレクションを作成して実際のAPIコールを行います。
なお、Postmanを日本語化するには、Postmanを起動して画面上部の歯車アイコンを選択し、設定 > 一般 の中のアプリケーションで言語の設定をしてください。さらに、自動保存をONにしておくことでパラメータの保存し忘れ防止になります。
ワークスペースを作ります。Postmanのトップにあるワークスペースプルダウンからワークスペースを作成ボタンを押します。
「空のワークスペース」
名前フィールドに
これで作業用のワークスペースが完成しました。
次に、利用する機能が非表示になっているので有効にするために、左側のサイドバーの設定アイコンを押します。そしてモックサーバーとフローをONにします。
2. モックサーバーを作成する
次に、Webhookの受け先としてモックサーバーを設定します。
モックサーバーを使うことで、Webhookを簡易的に受け付けるサーバーを用意できます。WebhookのURLだけでなくヘッダーやボディのパターンによって返却する値を変えられるため、Webhookのテストなどにとても重宝します。
サイドメニューのモックサーバーを選択して、モックサーバーを作成をクリックします。
そして次の項目を設定します。
- リクエストメソッドのプルダウンから
「POST」 を選択します。 - リクエストURLに、
「webhook/ status」 と入力します。 - レスポンスボディに、
「OK」 と入力します。 - 次に進むボタンを押します。
そして、モックサーバーの名前欄に
モックサーバーができたら、生成されたモックサーバーのURLをメモしておきましょう。
3. 環境変数を作成する
次に、APIキーなどの変数を環境変数に登録します。
環境変数を利用することで、秘匿すべきデータを守るだけでなく、APIリクエストに直接変数を書く必要がなくなります。また、環境変数に名前をつけてグルーピングできるため、開発用と本番用の変数を別に登録しておくといったことが可能です。
左側の環境アイコンを選択して、環境を作成をクリックします。
環境変数名を
変数を登録していきます。登録する変数は以下のとおりです。
変数 | タイプ | 初期値 | 現在値 |
---|---|---|---|
API Key | デフォルト | YOUR_ |
ご自分のVonage API Keyを指定してください |
API Secret | デフォルト | YOUR_ |
ご自分のVonage Secret Keyを指定してください |
Mock URL | デフォルト | YOUR_ |
先ほど作成したモックサーバーのURLを指定してください |
4. コレクションを作成する
ではいよいよMessages APIを呼び出していきます。そのために、まずはコレクションを作成します。
APIのリクエストをグループ化して管理するのがコレクションになります。このコレクションに対して認証・
左側のコレクションアイコンを選択し、さらにプラスアイコンを押して新しいコレクションを作成します。コレクション名には
作成したコレクションにおいて認可情報を設定します。
- 左上の環境プルダウンから、先ほど作成した環境変数
「Gihyo」 を選択します。 - 認可タブに移動します。
- Auth Typeプルダウンから
「Basic認証」 を選択します。 - ユーザー名欄で、
{{API Key}}
と入力します(波括弧を入力すると変数名がリストされるのでそれを選択します)。 - パスワード欄で、
{{API Secret}}
と入力します。
さらに、次の手順でリクエスト作成します。
- 左側のコレクションリスト
「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
5. リクエストを発行する
ではさっそくリクエストを発行してSMSが届くことを確認しましょう。
リクエスト作成した画面で、送信ボタンを押します。SMSが届き、202 Accepted
が表示されることを確認できるはずです。
もし401エラーが出た場合は、コレクションの認証・
配信ステータスを確認する
最後にWebhookを確認しましょう。
左側のモックサーバーアイコンを選択して、先ほど作成したsubmitted
で、2つ目のステータスはdelivered
になっていることを確認できます。
もしログが表示されない場合は、ログを更新をクリックしてください
今回は取り上げませんが、電話番号を架空の番号にしたり、スマホの電源を切った状態で送信するなどして、レスポンスがどのようになるかを確認することもできます。ぜひ試してみてください。
まとめ
今回は、API開発ツールであるPostmanを使って、Vonage Messages APIやVoice APIの仕組みやエラー対応などを検証してみました。
CPaaSを使えば、想像以上に簡単にSMSを送信できることが理解できたのではないかと思います。今回は送信する方法しか説明しませんでしたが、VonageからのWebhookを受け取ることでエラーのハンドリングもできます。
さて次回はいよいよ最終回。Vonage VoiceとAI Studioを使って電話の着信にAI機能を組み込んでいきましょう。