【TECH BLOG】SMSのAPI利用について

2021.03.02

システム連携

今回は、APIで利用する場合の詳細について書こうと思います。

1 SMSのAPI連携
2 APIを詳しく解説
3 まだまだ奥深いSMSの世界

SMSのAPI連携

AI CROSSは、AIX Message SMSという(https://www.aixmsg.com/)、企業がSMS配信を利用するためのプラットフォームを提供していて、

利用方法としては、

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

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

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

AIX Message SMSのシステム構成をざっくり図にすると下記のようになります。

図に記載のあるようにお客様システムやCTI、CRMなどから、HTTPS API, SMPP APIを利用して、実に色々なシステムがAIX Message SMSと連携しています。

例えば、スマホアプリのサーバー、各種SaaSサービスの管理サーバー、お客様の業務システム、安否確認システム、あるいは、Avaya/GenesysなどのCTI、電話の音声自動応答システム(IVR)、Salesforceなどのサービスとも連携して使われています。

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

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

APIを詳しく解説

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

送信、配信結果取得、それぞれにAPIがあります。

AIX Message 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)

AIX Message 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もあるのですが、これはまた別の機会に書きたいと思います。