絶対リーチ！® SMS Communication Platform (1.4.7)

Download OpenAPI specification:Download

改版履歴

date	version	detail
2022/08/18	1.40	最新の API(P5)に統一・全キャリア長文対応に合わせ、最新のAPIのみを記載しております。・わかりづらい箇所等一部記述を見直しました。・一部構成を変更しました。
2022/08/25	1.41	2.4. ステータス取得（Common）で一部パラメータ名の表記を修正しました（先頭大文字→小文字）
2022/10/28	1.42	パラメータ名の誤記を修正しました（先頭大文字→小文字）
2022/12/06	1.43	1.3. TPS の表現を修正しました。 2.6.1 domain パラメータを追記しました。
2023/06/12	1.44	2.9. 通数取得 API を新規追加しました。
2023/11/21	1.45	2.4.2 ステータス取得(Common)のレスポンスに「separatedSuccessCount」項目を追加しました。
2023/12/07	1.46	smsCodeの文字数を5桁または6桁に修正しました。
2023/12/27	1.47	CommonMT送信、予約送信確認、予約送信一括キャンセルのパラメータに「groupTag」項目を追加しました。

はじめに

本書では「絶対リーチ！® SMS communicationPlatform」（以下、「本サービス」といいます）の外部API仕様を定義します。

接続方式

API 接続は、HTTPS の GET/POST メソッドを用いて接続します。
※SSL/TLS の方式は TLS1.2 に限定しております。TLS1.0、1.1 では接続できません。

接続元 IP アドレスの制限

セキュリティを強化するため API を使用するアクセス元 IP アドレスを制限することが可能です。
管理画面の API限定 IP 設定により設定できます。

TPS（Transactions Per Second）

CommonMT 送信 API リクエストは全体で 600TPS（1 秒間あたりのリクエスト件数）での受け付けが可能です。
※上限を超過した場合は一時的に流量制限を実施する場合があります。

推奨 API

最新の「CommonMT 送信」をご利用下さい。
既に旧送信 API をご利用のお客様も「CommonMT 送信」に変更をお勧めいたします。

配信プラットフォーム刷新にともなう API URL の変更

2022 年 3 月に配信プラットフォームを刷新し、API URL も変更となりました。
この仕様書では、各 API の新 URL を記載しております。

API仕様

CommonMT 送信

※KDDI は送信失敗となった場合に KDDI からの失敗ステータスの通知に 20 分程度時間を要する場合があります。

Request Body schema: application/x-www-form-urlencoded

token required	string = 32 characters アカウント登録時に発行されるアクセスキーを指定します。トークンの値につきましては、管理画面のアカウント情報をご確認ください。
clientId required	string 契約クライアント ID を指定します。割り当てられている契約クライアント ID につきましては、管理画面のクライアント情報をご確認ください。・半角数字
smsCode required	string [ 5 .. 6 ] characters 送信元 SMS コードを指定します。割り当てられている SMS コードにつきましては、管理画面のクライアント情報をご確認ください。
message required	string [ 1 .. 660 ] characters 送信メッセージを指定します。 (全角/半角問わず文字数でカウントされます)
phoneNumber required	string^(\+81\|0)(([26789]0[1-9][0-9]{7}$)\|(20[1-9][0... 送信先電話番号を指定します。日本国内形式(070xxxxxxxx/080xxxxxxxx/090xxxxxxxx)、国際電話番号形式のどちらも指定することが可能です。 ※国際電話番号形式については『別記事項・国際電話番号形式について』をご参照ください。
carrierId	string Enum: "101" "103" "105" "106" キャリア ID を指定します。指定しない場合は本サービスにて電話番号より送信先キャリアを自動判定します。
clientTag	string [ 1 .. 200 ] characters 送信ステータス確認用の任意の識別文字列を指定します。必ずユニークな値を指定してください。値の重複があるとエラーになります。
scheduleTime	string <yyyy-MM-dd HH:mm> 予約送信時間を指定します。
groupTag	string [ 1 .. 200 ] characters 予約確認・一括キャンセル用の任意識別文字列を指定します。

Responses

responseCode	responseMessage	説明
0	Success	リクエストの受付が成功しました。
100	Required {項目名}.	{項目名}の項目が不足しています。
110	Invalid {項目名}.	{項目名}の項目の内容が不正です。
120	{項目名} too long.	{項目名}の長さが上限を超過しています。
300	Exceed sending count.	契約プランで定められた送信可能な件数の上限を超過しています。
400	Duplicate client tag.	クライアントタグが以前にリクエストした際のクライアントタグと重複しています。
500	System error.	上記で定義外のエラーが発生しています。

Callbacks

Request samples

Payload

Content type

application/x-www-form-urlencoded

token=1234567890abcdefrghijklmnopqrstu&clientId=12345&smsCode=12345&message=example%20message&phoneNumber=%2B819012345678&scheduleTime=2023-01-01%2012%3A00&groupTag=20230101_groupA

Response samples

200

Content type

application/json

{"responseCode": 0,
"responseMessage": "Success.",
"phoneNumber": "+819012345678",
"smsMessage": "example message"
}

Callback payload samples

Callback

POST: DLR 通知(Common)

Content type

application/json

{"eventNotifications": [{"type": "DLR",
"dateTime": "2023/01/01 12:30:00",
"messageId": "abcdefghijklmnopqrstuv0123456789",
"phoneNumber": "+819012345678",
"smsCode": 12345,
"carrierId": 101,
"carrierName": "AU",
"messageText": "example message",
"clientId": 12345,
"clientTag": "example tag",
"statusId": 2,
"statusDescription": "Message delivered",
"detailedStatusId": 2,
"separatedSuccessCount": 1
}
]
}

CommonMT 予約送信確認

query Parameters

token required	string = 32 characters Example: token=1234567890abcdefrghijklmnopqrstu アカウント登録時に発行されるアクセスキーを指定します。トークンの値につきましては、管理画面のアカウント情報をご確認ください。・半角英数字
clientId required	string 契約クライアント ID を指定します。割り当てられている契約クライアント ID につきましては、管理画面のクライアント情報をご確認ください。
smsCode required	string [ 5 .. 6 ] characters 送信元 SMS コードを指定します。割り当てられている SMS コードにつきましては、管理画面のクライアント情報をご確認ください。
clientTag	string [ 1 .. 200 ] characters 送信ステータス確認用の任意の識別文字列を指定します。 ※本項目または scheduleTime, scheduleDate のいずれかが必須。 ※優先度は clientTag > scheduleTime > scheduleDate になります。 ※本項目を指定した場合、指定文字列を保持する SMS のステータスを返却します。本項目を指定しない場合、SMS 送信日のデータを検索して返却します。
scheduleTime	string <yyyy-MM-dd HH:mm> 予約送信時間を文字列で指定します。フォーマットは「YYYY-MM-dd HH:mm」となります。 ※本項目または clientTag, scheduleDate のいずれかが必須。 ※優先度は clientTag > scheduleTime > scheduleDate になります。 groupTagも指定されている場合は組み合わせ条件になります。
scheduleDate	string <yyyyMMdd> 予約送信日を半角数字で指定します。 ※本項目または clientTag, scheduleTime のいずれかが必須。 ※優先度は clientTag > scheduleTime > scheduleDate になります。 groupTagも指定されている場合は組み合わせ条件になります。
groupTag	string [ 1 .. 200 ] characters 予約リクエスト時に指定した任意識別文字列を指定します。

Responses

responseCode	responseMessage	説明
0	Success.	リクエストが成功しました。
100	Required {項目名}.	{項目名}の項目が不足しています。
110	Invalid {項目名}.	{項目名}の項目が不正です。
120	{項目名} too long.	{項目名}の長さが上限を超過しています。
130	Already send.	確認対象のクライアントタグは既に送信されています。
140	Past {項目名}.	{項目名}は過去日時です。
500	System error.	上記で定義外のエラーが発生しました。

Response samples

200

Content type

application/json

{"responseCode": 0,
"responseMessage": "Success.",
"count": 1,
"status": [{"scheduleTime": "2023-01-01 12:00",
"phoneNumber": "+818012345678",
"message": "example message",
"smsCode": 12345,
"clientTag": "example tag"
}
]
}

CommonMT 予約送信キャンセル

query Parameters

token required	string = 32 characters Example: token=1234567890abcdefrghijklmnopqrstu アカウント登録時に発行されるアクセスキーを指定します。トークンの値につきましては、管理画面のアカウント情報をご確認ください。
clientId required	string^[1-9][0-9]+ 契約クライアント ID を指定します。割り当てられている契約クライアント ID につきましては、管理画面のクライアント情報をご確認ください。・半角数字
clientTag required	string [ 1 .. 200 ] characters 送信ステータス確認用の任意の識別文字列を指定します。

Responses

responseCode	responseMessage	説明
0	Success.	リクエストが成功しました。
100	Required {項目名}.	{項目名}の項目が不足しています。
110	Invalid {項目名}.	{項目名}の項目が不正です。
120	{項目名} too long.	{項目名}の長さが上限を超過しています。
130	Already send.	キャンセル対象は既に送信されています。
500	System error.	上記で定義外のエラーが発生しました。

Response samples

200

Content type

application/json

{"responseCode": 0,
"responseMessage": "Success.",
"clientTag": "abcdefg"
}

CommonMT 予約送信一括キャンセル

（※1）startDate を指定し endDate を指定しない場合、startDate 以降の予約がキャンセルされます。
endDate を指定し startDate を指定しない場合、endDate 以前の予約がキャンセルされます。
groupTag を指定し、startDate、endDate を指定しない場合、groupTag が一致する予約がキャンセルされます。
groupTag を指定し、かつ startDate、endDate のいずれかまたは両方が指定されている場合、groupTag と日付範囲が一致する予約がキャンセルされます。
startDate、endDate、groupTag をすべて指定しない場合はすべての予約がキャンセルされます。

query Parameters

token required	string = 32 characters Example: token=1234567890abcdefrghijklmnopqrstu アカウント登録時に発行されるアクセスキーを指定します。トークンの値につきましては、管理画面のアカウント情報をご確認ください。
clientId required	string 契約クライアント ID を指定します。割り当てられている契約クライアント ID につきましては、管理画面のクライアント情報をご確認ください。・半角数字
startDate	string <yyyyMMdd> = 8 characters キャンセルする日付範囲の開始日付を指定します。（※1）
endDate	string <yyyyMMdd> = 8 characters キャンセルする日付範囲の終了日付を指定します。（※1）
groupTag	string [ 1 .. 200 ] characters キャンセルするグループタグを指定します。（※1）

Responses

responseCode	responseMessage	説明
0	Success.	リクエストが成功しました。
100	Required {項目名}.	{項目名}の項目が不足しています。
110	Invalid {項目名}.	{項目名}の項目が不正です。
500	System error.	上記で定義外のエラーが発生しました。

Response samples

200

Content type

application/json

{"responseCode": 0,
"responseMessage": "Success."
}

CommonMT ステータス取得

query Parameters

token required	string = 32 characters Example: token=1234567890abcdefrghijklmnopqrstu アカウント登録時に発行されるアクセスキーを指定します。トークンの値につきましては、管理画面のアカウント情報をご確認ください。
clientId required	string Example: clientId=12345 契約クライアント ID を指定します。割り当てられている契約クライアント ID につきましては、管理画面のクライアント情報をご確認ください。・半角数字
date	string <yyyyMMdd> = 8 characters Example: date=20230401 SMS 送信日を指定します。・半角数字 ※本項目または clientTag のいずれかが必須。 ※優先度は clientTag > date になります。
clientTag	string [ 1 .. 203 ] characters Example: clientTag=example tag 送信ステータス確認用の任意の識別文字列を指定します。 ※本項目または date のいずれかが必須。 ※優先度は clientTag > date になります。 ※本項目を指定した場合、指定文字列を保持する SMS のステータスを返却します。本項目を指定しない場合、SMS 送信日のデータを検索して返却します。

Responses

responseCode	responseMessage	説明
0	Success.	リクエストが成功しました。
100	Required {項目名}.	{項目名}の項目が不足しています。
110	Invalid {項目名}.	{項目名}の項目が不正です。
120	{項目名} too long.	{項目名}の長さが上限を超過しています。
500	System error.	上記で定義外のエラーが発生しました。

Response samples

200

Content type

application/json

{"responseCode": 0,
"responseMessage": "Success.",
"status": [{"dateTime": "20230101 123030123",
"phoneNumber": "+818012345678",
"message": "example message",
"smsCode": 12345,
"carrierId": 101,
"carrierName": "AU",
"statusId": 2,
"clientTag": "abcdefg",
"detailedStatusId": 2,
"separatedSuccessCount": 10
}
]
}

ショート URL 登録

API によりショート URL を登録することが可能です。

Request Body schema: application/x-www-form-urlencoded

token required	string = 32 characters アカウント登録時に発行されるアクセスキーを指定します。トークンの値につきましては、管理画面のアカウント情報をご確認ください。
clientId required	string 契約クライアント ID を指定します。割り当てられている契約クライアント ID につきましては、管理画面のクライアント情報をご確認ください。・半角数字
name	string [ 0 .. 256 ] characters 生成されるショート URL の識別名を指定します。指定しない場合、自動的に下記が name として登録されます。 Shorturl-YYYYMMDDHHMMSSsss(sss はミリ秒)
longUrl required	string <= 2048 characters ショート URL に変換するオリジナル URL を指定します。
domain	string ショート URL に変換する際のドメインを指定します。 ※独自ドメインオプションをお申し込みいただいているお客様のみご指定可能です

Responses

responseCode	responseMessage	説明
0	Success	リクエストの受付が成功しました。
100	Required {項目名}.	{項目名}の項目が不足しています。
110	Invalid {項目名}.	{項目名}の項目の内容が不正です。
120	{項目名} too long.	{項目名}の長さが上限を超過しています。
500	System error.	上記で定義外のエラーが発生しています。

Request samples

Payload

Content type

application/x-www-form-urlencoded

token=1234567890abcdefrghijklmnopqrstu&clientId=12345&name=example&longUrl=https%3A%2F%2Fexample.com&domain=example.com

Response samples

200

Content type

application/json

{"responseCode": 0,
"responseMessage": "Success.",
"shortUrl": "https://ai9.jp/xxxxxx",
"name": "example short url"
}

登録済み定型文取得

query Parameters

token required	string = 32 characters Example: token=1234567890abcdefrghijklmnopqrstu アカウント登録時に発行されるアクセスキーを指定します。トークンの値につきましては、管理画面のアカウント情報をご確認ください。
clientId required	string Example: clientId=12345 契約クライアント ID を指定します。割り当てられている契約クライアント ID につきましては、管理画面のクライアント情報をご確認ください。・半角数字

Responses

responseCode	responseMessage	説明
0	Success.	リクエストが成功しました。
100	Required {項目名}.	{項目名}の項目が不足しています。
110	Invalid {項目名}.	{項目名}の項目が不正です。
500	System error.	上記で定義外のエラーが発生しました。

Response samples

200

Content type

application/json

{"responseCode": 0,
"responseMessage": "Success.",
"count": 1,
"templates": [{"title": "example template",
"default_content": "example message",
"parameters": [{"parameter_name": "example parameter"
}
]
}
]
}

電話番号クリーニング

query Parameters

token required	string = 32 characters Example: token=1234567890abcdefrghijklmnopqrstu アカウント登録時に発行されるアクセスキーを指定します。トークンの値につきましては、管理画面のアカウント情報をご確認ください。
clientId required	string Example: clientId=12345 契約クライアント ID を指定します。割り当てられている契約クライアント ID につきましては、管理画面のクライアント情報をご確認ください。・半角数字
phoneNumber required	string^(\+81\|0)(([26789]0[1-9][0-9]{7}$)\|(20[1-9][0... Example: phoneNumber=+819012345678 判定対象電話番号を指定します。日本国内形式(070xxxxxxxx/080xxxxxxxx/090xxxxxxxx)、国際電話番号形式のどちらも指定することが可能です。
referenceDate required	string <yyyyMMdd> Example: referenceDate=20230101 判定を行う基準となる日を指定します。・2 年前～当日まで有効

Responses

responseCode	responseMessage	説明
0	Success.	リクエストが成功しました。
100	Required {項目名}.	{項目名}の項目が不足しています。
110	Invalid {項目名}.	{項目名}の項目が不正です。
500	System error.	上記で定義外のエラーが発生しました。

Response samples

200

Content type

application/json

{"responseCode": 0,
"responseMessage": "Success.",
"phoneNumber": "+819012345678",
"referenceDate": "20230101",
"status": "T"
}

通数集計

query Parameters

token required	string = 32 characters Example: token=1234567890abcdefrghijklmnopqrstu アカウント登録時に発行されるアクセスキーを指定します。トークンの値につきましては、管理画面のアカウント情報をご確認ください。
clientId required	string Example: clientId=12345 契約クライアント ID または all を指定します。 ※all は代理店参照者のみ使用可能です。割り当てられている契約クライアント ID につきましては、管理画面のクライアント情報をご確認ください。・半角数字・all（代理店参照者のみ）
month required	string <yyyyMM> Example: month=202301 取得する年月を指定します。取得できる期間はデータ保持期間の間のみです。・半角数字・YYYYMM 形式 ※当月を指定する場合、取得できる件数は前日までのものとなります。

Responses

responseCode	responseMessage	説明
0	Success.	リクエストが成功しました。
100	Required {項目名}.	{項目名}の項目が不足しています。
110	Invalid {項目名}.	{項目名}の項目が不正です。
500	System error.	上記で定義外のエラーが発生しました。

Response samples

200

Content type

application/json

{"responseCode": 0,
"responseMessage": "Success.",
"separatedSuccessCount": [{"101": 12345,
"103": 12345,
"105": 12345,
"106": 12345,
"clientId": 12345
}
]
}

別記事項

国際電話番号形式について

本資料上のリクエストパラメータで『国際電話番号』形式としてある場合、以下に記載する国際電話番号形式に則った電話番号の指定が必要になります。

先頭が半角記号＋より始まる (注意:GET/POST 送信時は URL エンコードが必要)
国番号 81
国番号の次の 1 文字は 7,8,9 のいずれか
以降、任意の半角数字 8 桁
- xml タグ指定例）+818010007765
- URL エンコード指定例）%2b818010007765
  (%2b が半角プラス+を URL エンコードした文字列です)

ステータス ID について

本サービスのステータス ID 設定値とメッセージは以下の通りです。

設定値	メッセージ	備考
0	Unknown	状態不明
1	Message is Sending	配信中
2	Message delivered	送達
3	Message delivery failed	配信失敗

レスポンスの rawdata について

各レスポンスの rawdata は廃止予定のため参照は推奨いたしません

詳細内部コード（detailedStatusId）について

本サービスの詳細内部コードは配信失敗の場合、モジュールコード(先頭 2 桁) + 分類コード(末尾 3 桁)」の 5桁で構成されます。
詳細内部コード設定値の主要な値は以下の通りです。
※ 詳細内部コードは将来予告なく追加・変更される可能性があります。
そのためプログラム実装では厳密に参照することは避け例外を許容することをお勧めいたします。

モジュールコード（先頭 2 桁）	該当キャリア
11～14	AU
31,32	Docomo
51,52	Softbank
61,62	楽天モバイル

分類コード（末尾 3 桁）	内容	起因箇所
721	輻輳	キャリア、送信先端末
732	欠番、顧客都合	送信先端末
821	輻輳	送信先端末
823	ネットワーク起因（圏外、電源 OFF 含む）	キャリア、送信先端末
824	圏外、電源 OFF 等	送信先端末
833	圏外、話中、電源 OFF 等	送信先端末
834	移動機側エラー（SMS 拒否設定等）	送信先端末

Y!Mobile （旧 Willcom、PHS 回線）について

Y!Mobile （旧 Willcom、PHS 回線）は 2021 年 1 月 31 日（日）にサービス終了しました。

キャリア ID について

本サービスのキャリア ID 設定値とキャリアは以下の通りです。

キャリア ID	キャリア
101	AU
103	Docomo
105	Softbank
106	楽天モバイル