【TECH連載】SMSのAPIについて

【TECH連載】では当社エンジニアによるテック関連のニュースを中心に記事をお届けします！第四回は「SMSのAPI」について。

以前、SMSの業務利用についての記事(https://bit.ly/3w48ppN) を書きましたが、今回の記事では、お客様システムとのシステム連携する際に必要なAPIの中身について具体的に解説します。

✅ お客様システムからSMS送信を行うためにはAPIを利用します
✅ 本記事では、APIの中身について具体的に解説します

こんにちは。AICROSS開発チームの鈴木です。

AI CROSSは、絶対リーチ！SMSという(https://www.zettai-reach.com/)、企業がSMS配信を利用するためのプラットフォームを提供していて、
利用方法としては、

・ 専用のWeb管理画面から利用する　
・ APIを使用してシステム連携で利用する　

の２つの利用方法があります。

管理画面の機能についてはhttps://zettai-reach.com/features/ に記載していて、マニュアルもあります。

絶対リーチ！SMSのシステム構成をざっくり図にすると下記のようになります。

図に記載のあるように、お客様システムやCTI, CRMなどから、HTTPS API, SMPP APIを利用して、実に色々なシステムが絶対リーチ！SMSと連携しています。
例えば、スマホアプリのサーバー、各種SaaSサービスの管理サーバー、お客様の業務システム、安否確認システム、あるいは、AVAYA/GenesysなどのCTI、電話の音声自動応答システム(IVR)、Salesforceなどのサービスとも連携して使われています。

HTTPS APIはとてもシンプルなREST APIになっていて、SMSの送信、SMS配信結果の取得などの機能をシンプルに使用することができるようになっています。

APIの詳細について

では APIの詳細について少し見ていきたいと思います。

APIを使った送信の流れは、シーケンス図で書くと、下記のようになります。

送信、配信結果取得、それぞれにAPIがあります。
絶対リーチ！SMSにお申し込みいただくと、Web管理画面からAPI仕様書をダウンロードすることができます。またAPIを利用するために必要になる認証token等の情報も、Web管理画面から参照できます。

ここでは特に重要なAPIを解説します。

SMS送信API

SMSを送信するためのAPIです。概要は下記の通り。

パラメータは色々指定できるのですが、主要なパラメータを列挙します(APIバージョン複数あるうちの"p5 API"の場合)。

絶対リーチ！SMSでは、「キャリア判定」の機能を持っていまして、SMSを送信する時に宛先電話番号の携帯電話がどのキャリアかを判定して、それぞれのキャリアGWに送信します。

clientTagというパラメータはメッセージの識別子で、後述の送信結果取得APIやDLRでどのメッセージの送信結果を取得するかを指定するために使うため、常に他と重複しない一意の値を指定する必要があります。APIとしては必須パラメータではないのですが、指定した方が良いパラメータです（ただし重複するとエラーが出るので、重複しないように管理は必要です）。

例えば、+81x0xxxxxxxx の電話番号宛に、「テスト」と送信する場合、HTTPS POSTのBODYの中身は下記のような感じになります。

APIのURLはjsonで終わっていますが、これはAPIの結果がjsonで返されるという意味で、パラメータは、application/x-www-form-urlencoded で指定しますのでご注意ください。
API送信がうまく行かない時は、Postmanとか curl -X POST -d ‘[BODYの中身]’ [APIのURL] とかでまず試すのがよくやるやり方です。
API仕様書にはJava/PHPの簡単なコード例も記載しています。

送信結果取得API

送信したSMSの送信結果を確認するAPIです。概要は下記の通り。

これも主要なパラメータのみ列挙します。

送信時にclientTagを指定しおくのがポイントです。指定したclientTagに対応するメッセージの送信結果(送達、失敗、配信中、失敗の場合はエラーの詳細)およびその他詳細情報を取得できます。

DLR(Delivery Receipt)

先ほどの送信結果取得APIは、APIコールで問い合わせて、結果を取得するものでしたが、送信結果が確定次第すぐに知りたい場合があります。そのような場合に利用するのがDLRです。
DLRは、AI CROSSのサーバからHTTPS POSTコールで、送信結果をお客様のサーバにコールバックするものです。（送信結果コールバックを受け付けるサーバをあらかじめ準備しておいていただき、DLRを利用したい旨、およびコールバックを受け付けるサーバの情報をお申し込みと共にAI CROSSにお知らせいただく必要があります。またファイアウォールなどの制限がある場合は、AI CROSSのサーバからのコールバックは受け付けられるように設定いただく必要があります）。

APIのバージョンはp1/p11/p4/p5と複数あるのですが、エラーの詳細を５桁の数字のエラーコードとして取得でき、さらに一つのパラメータで長文を指定できる　p5 API (CommonMT API) の利用をお勧めします。

ざっとHTTPS API利用の概要を説明しました。
他にSMPPというプロトコルのAPIもあるのですが、これはまた別の機会に書きたいと思います。

絶対リーチ！SMSサービスの各種サーバーは、AWS(Amazon Web Services)上で構築しています。

AI CROSSは、AWSのAPN Technology Partnerになっており、お客様に信頼性の高いサービスを提供していくために、AWSの各種機能をうまく活用しながらサービスを構築しています。このあたりの各種小ネタも、このブログでおいおい書いていければと思っています。

それでは、今日はこの辺で。