【TECH BLOG】SMSのAPI利用について
今回は、SMSを利用する場合、どのようにSMSをAPI連携し、利用していくかをご紹介いたします。
業界別のSMS活用最新事例をご紹介
⇒資料のダウンロードはこちらから
SMSのAPI連携
AI CROSSは、絶対リーチ！SMSという(https://aicross.co.jp/zettai-reach/)、企業がSMS配信を利用するためのプラットフォームを提供していています。
利用方法としては、
- 専用のWeb管理画面から利用する
- APIを使用してシステム連携で利用する
の２つの利用方法があります。
管理画面の機能についてはhttps://aicross.co.jp/zettai-reach/features/にて記載しており、マニュアルもあります。
絶対リーチ！SMSのシステム構成をざっくり図にすると下記のようになります。
図に記載のあるようにお客様システムやCTI、CRMなどから、HTTPS API、SMPP、APIを利用して、実に色々なシステムが絶対リーチ！SMSと連携しています。
例えば、スマホアプリのサーバー、各種SaaSサービスの管理サーバー、お客様の業務システム、安否確認システム、あるいは、Avaya/GenesysなどのCTI、電話の音声自動応答システム(IVR)、Salesforceなどのサービスとも連携して使われています。
HTTPS APIはとてもシンプルなREST APIになっていて、SMSの送信、SMS配信結果の取得などの機能をシンプルに使用することができるようになっています。
では APIの詳細について少し見ていきたいと思います。
費用対効果の高いSMSを活用してみませんか？
開封率90%以上によって顧客対応の効率化と売上拡大を実現！
⇒資料のダウンロードはこちらから
APIを詳しく解説
APIを使った送信の流れは、シーケンス図で書くと、下記のようになります。
送信、配信結果取得、それぞれにAPIがあります。
絶対リーチ！SMSにお申し込みいただくと、Web管理画面からAPI仕様書をダウンロードすることができます。またAPIを利用するために必要になる認証token等の情報も、Web管理画面から参照できます。
ここでは特に重要なAPIを解説します。
SMS送信API
| URL | 管理画面内のAPI仕様書に記載(APIバージョンが複数あるので注意。仕様書には複数バージョン併記しています) |
| HTTP Method | POST |
| Content-Type | application/x-www-form-urlencoded |
| BODY | パラメータ名＝パラメータ値を&で連結(つまりapplication/x-www-form-urlencoded形式です) |
パラメータも色々指定できるのですが、特に主要なパラメータのみ解説します。
| パラメータ名 | 重要度 | 内容 |
| token | ○ | アカウント登録時に発行されるアクセスキー(Web管理画面から参照可) |
| clientId | ○ | 契約クライアントID(Web管理画面から参照可) |
| smsCode | ○ | 送信元SMSコード(Web管理画面から参照可) |
| clientTag | メッセージを識別する固有ID(最大200文字)(必ず他と重複しない一意の値を指定する必要がある) | |
| phoneNumber | ○ | 宛先電話番号 (日本国内方式0x0xxxxxxxx もしくは、国際電話番号形式 +81x0xxxxxxxx) |
| message | ○ | 宛先の携帯電話に該当する(下記の)キャリア毎のメッセージ本文が指定されていない時に使われるメッセージ本文(最大70文字, UTF-8) |
| messageDo | △ | 送信先がドコモ端末の場合のメッセージ本文(最大660文字, UTF-8) |
| messageAu | △ | 送信先がau端末の場合のメッセージ本文p4 APIの場合最大670文字, UTF-8、p11 APIの場合 messageAu, messageAu2 – messageAu10の各パラメータに140bytesずつ区切って入れる。 |
| messageSb | △ | 送信先がソフトバンク端末の場合のメッセージ本文(最大332文字, UTF-8) |
| messageRm | △ | 送信先が楽天モバイルキャリア端末の場合のメッセージ本文(最大670文字, UTF-8) |
絶対リーチ！SMSでは、「キャリア判定」の機能を持っておりまして、SMSを送信する時に宛先電話番号の携帯電話がどのキャリアかを判定して、それぞれのキャリアGWに送信します。
それぞれのキャリアGWの仕様の違いから最大送信文字数に違いがあります(そのためパラメータが分かれています)。もし本文が70文字以内でもよければ、messageパラメータのみを指定すれば問題はありませんが、もし70文字以上送る必要がある場合は、各キャリア本文のパラメータも指定する必要があります。(ただし、PHSなど70文字以上送れないキャリアもあります)
clientTagというパラメータはメッセージの識別子で、後述の送信結果取得APIやDLRでどのメッセージの送信結果を取得するかを指定するために使うので、常に他と重複しない一意の値を指定する必要があります。APIとしては必須パラメータではないのですが、指定した方が良いパラメータです（ただし重複するとエラーが出るので、重複しないように管理をする必要があります）。
例えば、+81x0xxxxxxxx の電話番号宛に、「テスト」と送信する場合、HTTPS POSTのBODYの中身は下記のようになります。
――――――――――――
token=[トークン]&clientId=[クライアントID]&smsCode=[SMSコード]&phoneNumber=%2B81x0xxxxxxxx&clientTag=[一意な文字列]&message=[“テスト”をURL encodeしたもの]
――――――――――――
APIのURLはjsonで終わっていますが、これはAPIの結果がjsonで返されるという意味で、パラメータは、application/x-www-form-urlencoded で指定しますのでご注意ください。
API送信がうまく行かない時は、Postmanや curl -X POST -d ‘[BODYの中身]’ [APIのURL] とかでまず試すのがメジャーな方法です。
API仕様書にはJava/PHPの簡単なコード例も記載しています。
送信結果取得API
| URL | 管理画面内のAPI仕様書に記載 |
| HTTP Method | GET |
| Content-Type | application/x-www-form-urlencoded |
| BODY | パラメータ名＝パラメータ値を&で連結(つまりapplication/x-www-form-urlencoded形式です) |
こちらも主要なパラメータのみ記載します。
| パラメータ名 | 重要度 | 内容 |
| token | ○ | アカウント登録時に発行されるアクセスキー(Web管理画面から参照可) |
| clientId | ○ | 契約クライアントID(Web管理画面から参照可) |
| clientTag | △ | メッセージを識別する固有ID (SMS送信指示の際、指定したもの) |
送信時にclientTagを指定しおくのがポイントです。指定したclientTagに対応するメッセージの送信結果(送達、失敗、配信中、失敗の場合はエラーの詳細)およびその他詳細情報を取得できます。
DLR(Delivery Receipt)
先ほどの送信結果取得APIは、APIコールで問い合わせて、結果を取得するものでしたが、送信結果が確定次第すぐに知りたい場合があります。そのような場合に利用するのがDLRです。
DLRは、AI CROSSのサーバからHTTPS POSTコールで、送信結果をお客様のサーバーにコールバックするものです。（送信結果コールバックを受け付けるサーバーをあらかじめ準備しておいていただき、DLRを利用したい旨、およびコールバックを受け付けるサーバーの情報をお申し込みと共にAI CROSSにお知らせいただく必要があります。またファイアウォールなどの制限がある場合は、AI CROSSのサーバからのコールバックは受け付けられるように設定いただく必要があります）。
APIのバージョンはp1/p11/p4と複数あるのですが、p11/p4 APIは、エラーの詳細を５桁の数字のエラーコードとして取得できるので、p11/p4 APIの利用をお勧めします。
HTTPS API利用の概要を説明しました。
他にSMPPというプロトコルのAPIもあるのですが、これはまた別の機会にご紹介させていただきます。
まだまだ奥深いSMSの世界
絶対リーチ！SMSサービスの各種サーバーは、AWS(Amazon Web Services)上で構築しています。
AI CROSSは、AWSのAPN Technology Partnerになっており、お客様に信頼性の高いサービスを提供していくために、AWSの各種機能をうまく活用しながらサービスを構築しています。
