SMS API¶
SMS APIは2つの送信モードをサポートしています。テンプレートSMSとフリーフォームSMSです。テンプレートSMSは標準アカウントのデフォルトであり、フリーフォームSMSは承認されたトラステッドパートナーのみ利用可能です。
SMSメッセージ送信APIのテンプレートSMSでは、検証済みの変数を含む承認されたメッセージテンプレートを使用します。フリーフォームSMSでは、完全にカスタムされたメッセージ本文を使用できますが、アクセスは制限されています。
概要¶
OTP、アラート、リマインダー、通知など、予測可能で構造化されたメッセージを送信したい場合は、テンプレートSMSを使用します。
アカウントが明示的に有効化されている場合にのみ、フリーフォームSMSを使用します。
認証¶
すべてのエンドポイントで、アカウントの認証情報を使用した認証が必要です。
例:
curl -u <SID>:<AUTH_TOKEN> https://api.xoxzo.com/sms/templates/
テンプレート管理¶
テンプレートの作成、取得、更新、削除の操作や管理については、以下のドキュメントを確認してください。
テンプレート管理の詳細については、 SMSテンプレートAPI を参照してください。
テンプレートメッセージ送信¶
テンプレート経由のSMS送信API¶
承認済みのテンプレートを使用してSMSを送信するには、エンドポイントの後に <template_id> を続けて POST リクエストを送信します:
https://api.xoxzo.com/sms/templates/<template_id>/messages/
下記のパラメーターを併記してください。
名称
詳細
必須
例
sender
送信元ID（英数字は最大10文字、数字のみは最大15文字）
○
TestSender
recipient
国際電話番号規格（E.164）形式の受信者電話番号
○
+81987654321
variables
各プレースホルダー名とその値を関連付けるJSONデータ
○
{"name": "Alice"}
注釈
送信に使用できるのは APPROVED のテンプレートのみです。 PENDING のテンプレートで送信しようとするとエラーが返されます。
例¶
下記は、CURLを使ったリクエストの例です。
curl -u <SID>:<AUTH_TOKEN> -X POST \
https://api.xoxzo.com/sms/templates/<template_id>/messages/ \
-H "Content-Type: application/json" \
-d '{
"sender": "TestSender",
"recipient": "+81987654321",
"variables": {
"name": "Sample_name",
"salary": "Sample_salary"
}
}'
ちなみに
リンクトラッキングやコールバックURLなどの他のパラメータを使用する場合は、詳細について SMSパラメーター表 を参照してください。
レスポンスは、JSON構造となり、ステータスコード HTTP 201 CREATED にて返されます。
HTTP/1.1 201 CREATED
Content-Type: application/json
[
{
"msgid": "<msgid>"
}
]
注釈
variables パラメーターに関する注意点:
すべての変数キーは、テンプレート内容で定義されたプレースホルダー名と完全に一致する必要があります。
キーが不足している、または余分なキーが含まれていると、エラーが発生するか、送信されたメッセージ内に未解決のプレースホルダーが残る可能性があります。
テンプレートメッセージの配信状態を確認するAPI¶
テンプレートに対して送信されたすべてのメッセージ¶
特定のテンプレートを使用して送信されたすべてのSMSメッセージの状態を確認するには、エンドポイントへ GET リクエストを送信してください:
https://api.xoxzo.com/sms/templates/<template_id>/messages/
下記は、CURLを使ったリクエストの例です。
curl -u <SID>:<AUTH_TOKEN> \
https://api.xoxzo.com/sms/templates/<template_id>/messages/
メッセージIDによる単一メッセージ¶
テンプレート経由で送信された特定のメッセージの配信状態を確認するには、エンドポイントの後に <msg_id> を付けて GET リクエストを送信してください:
https://api.xoxzo.com/sms/templates/messages/<msg_id>/
下記は、CURLを使ったリクエストの例です。
curl -u <SID>:<AUTH_TOKEN> \
https://api.xoxzo.com/sms/templates/messages/<msg_id>/
ちなみに
レスポンスのフィールドは、標準のSMS配信状態確認APIと同等です（status、cost、msgid、recipient、sender、sent_time、url を含む）。詳細は SMSの配信状態を確認するAPI を参照してください。
フリーフォームSMSの送信¶
フリーフォームSMSは、承認されたパートナーのみ利用可能です。
テンプレートの制限なしにカスタムメッセージ本文を送信する必要がある場合に、このエンドポイントを使用します。
SMSメッセージを送信するには、 POST リクエストをエンドポイントに行ってください。
POST /sms/messages/
下記のパラメーターを併記してください。
名称
詳細
必須
データタイプ
例
message
メッセージ本文
○
UTF-8
こんにちは
recipient
メッセージの受信者
○
E.164
+8190123456789
sender
送信元ID
○
英数字
Xoxzo1
callbackurl
コールバックURL
×
URL
tags
タグ
×
UTF-8
tag1,tag2
track_link
リンクトラッキングを有効化
×
true の文字列
true
lt_callbackurl
リンクトラッキングのコールバックURL
×
URL
パラメータに関する注意点や警告については、前のセクションである テンプレートSMSの送信 を参照してください。
例¶
下記は、CURLを使ったリクエストの例です。
curl -u <SID>:<AUTH_TOKEN> --data-urlencode 'recipient=<recipient>' --data-urlencode 'sender=<sender>' --data-urlencode 'message=<message>' https://api.xoxzo.com/sms/messages/
上記の例にある <message> は 必ず 送信される前にUTF-8でエンコーディングしてください。
レスポンスは、JSON構造となり、ステータスコード HTTP 201 CREATED にて返されます。
HTTP/1.1 201 CREATED
Content-Type: application/json
[
{
"msgid": "<msgid>"
}
]
レスポンスデータ¶
名称
詳細
msgid
このメッセージ固有のメッセージIDになります。
間違ったバラメーターが与えられた場合には、ステータスコード HTTP 400 BAD REQUEST が返されます。例えば、もし message パラメーターがなかった場合、HTTPからの返答はこのようになります。
HTTP/1.1 400 BAD REQUEST
Content-Type: application/json
{
"message": [
"This field is required."
]
}
ちなみに
実際にテストコードでAPIを叩いたほうが早く動作確認できます。 無料登録 は無料ですぐできます。
SMSの配信状態を確認するAPI¶
メッセージの状態を調べるには、エンドポイントの後に <msgid> を付けて GET リクエストを発行してください。
テンプレートSMSの場合:
GET /sms/templates/<id>/messages/<msgid>/
フリーフォームSMSの場合:
GET /sms/messages/<msgid>/
送信を行うたびに、 <msgid> を含むレスポンスが得られますので、この <msgid> を配信状態の確認にご利用ください。
例¶
下記は、cURLを使ったリクエストの例です:
curl -u <SID>:<AUTH_TOKEN> https://api.xoxzo.com/sms/templates/<templateid>/messages/<msgid>/
curl -u <SID>:<AUTH_TOKEN> https://api.xoxzo.com/sms/messages/<msgid>/
レスポンスは、JSON構造となり、ステータスコード HTTP 200 OK にて返されます。
HTTP/1.1 200 OK
Content-Type: application/json
{
"tags": [
"tag1",
"tag2"
],
"url": "https://api.xoxzo.com/sms/messages/<msgid>/",
"recipient": "<recipient>",
"parts": 1,
"cost": 10,
"sent_time": "2019-03-05 00:37:44",
"sender": "<sender>",
"msgid": "<msgid>",
"status": "DELIVERED"
}
下記は、メッセージが配信失敗し、ステータスコード HTTP 200 OK が返された場合の例です。
HTTP/1.1 200 OK
Content-Type: application/json
{
"status": "FAIL",
"sent_time": "2015-09-13 12:47:53",
"cost": 10,
"msgid": "<msgid>",
"parts": 1,
"recipient": "<recipient>",
"sender": "<sender>",
"url": "https://api.xoxzo.com/sms/messages/<msgid>/"
}
レスポンスデータ¶
名称
詳細
status
送信されたメッセージの状態です。
cost
このメッセージ送信で消費したクレジットです。
msgid
このメッセージ固有のメッセージIDになります。
recipient
このメッセージの受信者です。
sender
設定された送信元です。
sent_time
送信時間が、UTC（協定世界時）にて返されます。
url
このメッセージステータスのURLです。
tags
このメッセージに付けられたタグです。タグが無いときは空のリスト[]になります。
track_link が有効になっている場合は、以下の情報も含まれます。
名称
キー
詳細
link_tracking
accessed
リンクに既にアクセスが有った場合は true. そうでない場合は false.
accessed_on
リンクが最初にアクセスされた時刻。
link
メッセージに元々含まれていたリンク。
shortlink
短縮化されたリンク。
レスポンスの例
{
"cost": 15.0,
"link_tracking": {
"accessed": false,
"accessed_on": "",
"link": "http://www.example.com",
"shortlink": "https://xoz.so/dbNL4"
},
"msgid": "oxgyFO6tfwYkHLIMbURrz5smCv9QT423",
"recipient": "+818012345678",
"parts": 1,
"sender": "XOXZO",
"sent_time": "2020-10-09 02:37:47",
"status": "DELIVERED",
"tags": [],
"url": "https://api.xoxzo.com/sms/messages/oxgyFO6tfwYkHLIMbURrz5smCv9QT423/"
}
送信されたSMSのリストを取得するAPI¶
以下のエンドポイントに GET リクエストをすると送信されたメッセージのリストを取得することが可能です。
テンプレートSMSの場合:
GET /sms/templates/<id>/messages/
フリーフォームSMSの場合:
GET /sms/messages/
データは sent_time 新しい順でソートされて取得します。ログなどの作成に便利です。
演算子とオペレーターによって特定の日付でリストを取得することもできます。
名称
詳細
必須
sent_date
YYYY-mm-ddのフォーマットで、メッセージ送信されたUTCベースの日付。過去90日間以内でなければならない。
○
以下の演算子を利用してある期間のメッセージのリスト取得することができます。
演算子
名称
<=
以下
<
より小さい
=
等しい
>
より大きい
>=
以上
注釈
一度に取得できるメッセージの数は最大30,000までです。
過去90日間のメッセージしか取得できません。
本APIは一度に1つの演算子と1つの日付しか対応していません。
日付はすべてUTC
警告
このAPIの呼び出しは１時間あたり３回までに制限されています。
レスポンスの例¶
このAPIで返されるjson構成とデータ種類は SMSの配信状態を確認するAPI と同じものになります。
送信したメッセージのリストを取得します。¶
以下はcURLを使ってメッセージを取得する例です:
curl -u <SID>:<AUTH_TOKEN> https://api.xoxzo.com/sms/messages/
レスポンスは、JSON構造となり、ステータスコード HTTP 200 OK にて返されます。
HTTP/1.0 200 OK
Content-Type: application/json
[
{
"cost": 0,
"msgid": "<msgid>",
"recipient": "<recipient>",
"sender": "<sender>",
"parts": 1,
"sent_time": null,
"status": "QUEUED",
"url": "https://api.xoxzo.com/sms/messages/<msgid>"
},
{
"cost": 10,
"msgid": "<msgid>",
"recipient": "<recipient>",
"parts": 1,
"sender": "<sender>",
"sent_time": "2016-03-04 00:00:00",
"status": "DELIVERED",
"url": "https://api.xoxzo.com/sms/messages/<msgid>"
},
]
指定の日付のメッセージだけ取得します。¶
以下はcURLを使って2016年3月4日に送信したメッセージを取得しようとする例です:
curl -u <SID>:<AUTH_TOKEN> https://api.xoxzo.com/sms/messages/?sent_date=2016-03-04
レスポンスは、JSON構造となり、ステータスコード HTTP 200 OK にて返されます。
HTTP/1.0 200 OK
Content-Type: application/json
[
{
"cost": 10,
"msgid": "<msgid>",
"recipient": "<recipient>",
"parts": 1,
"sender": "<sender>",
"sent_time": "2016-03-04 10:15:00",
"status": "DELIVERED",
"url": "https://api.xoxzo.com/sms/messages/<msgid>"
},
{
"cost": 10,
"msgid": "<msgid>",
"recipient": "<recipient>",
"parts": 1,
"sender": "<sender>",
"sent_time": "2016-03-04 00:00:00",
"status": "DELIVERED",
"url": "https://api.xoxzo.com/sms/messages/<msgid>"
},
]
以下はcURLを使って2016年3月4日とその以前送信したメッセージを取得しようとする例です:
curl -u <SID>:<AUTH_TOKEN> https://api.xoxzo.com/sms/messages/?sent_date<=2016-03-04
レスポンスは、JSON構造となり、ステータスコード HTTP 200 OK にて返されます。
HTTP/1.0 200 OK
Content-Type: application/json
[
{
"cost": 10,
"msgid": "<msgid>",
"recipient": "<recipient>",
"parts": 1,
"sender": "<sender>",
"sent_time": "2016-03-04 10:15:00",
"status": "DELIVERED",
"url": "https://api.xoxzo.com/sms/messages/<msgid>"
},
{
"cost": 10,
"msgid": "<msgid>",
"recipient": "<recipient>",
"parts": 1,
"sender": "<sender>",
"sent_time": "2016-03-04 00:00:00",
"status": "DELIVERED",
"url": "https://api.xoxzo.com/sms/messages/<msgid>"
},
{
"cost": 10,
"msgid": "<msgid>",
"recipient": "<recipient>",
"parts": 1,
"sender": "<sender>",
"sent_time": "2016-02-15 11:30:47",
"status": "DELIVERED",
"url": "https://api.xoxzo.com/sms/messages/<msgid>"
},
]
指定された日付にメッセージがありません¶
指定された日付に送信したメッセージがない場合、空のリストが返されます。
以下はcURLを使って2016年1月30日に送信したメッセージを取得しようとする例です:
curl -u <SID>:<AUTH_TOKEN> https://api.xoxzo.com/sms/messages/?sent_date=2016-01-30
2016年1月30日に送信したメッセージがないため、 HTTP 200 OK が返されます。
HTTP/1.0 200 OK
Content-Type: application/json
[]
不正リクエストの例¶
日付が不正なフォーマットで指定されると HTTP 400 BAD REQUEST が返されます。
以下はcURLを使って不正な日付の値でメッセージを取得しようとする例です:
curl -u <SID>:<AUTH_TOKEN> https://api.xoxzo.com/sms/messages/?sent_date=2016-02-30
2016年2月30日は不正な日付のため、 sent_date 値が不正ということで HTTP 400 BAD REQUEST が返されます。
HTTP/1.0 400 Bad Request
Content-Type: application/json
{
"sent_date": [
"Invalid sent_date format"
]
}
指定された日付は過去90日間以上の場合、HTTP 400 BAD REQUEST が返されます。
以下はcURLを使って過去90日間よりも古いでメッセージを取得しようとする例です:
curl -u <SID>:<AUTH_TOKEN> https://api.xoxzo.com/sms/messages/?sent_date=2015-02-28
2015年2月28日は過去90日間以上となるので、正しい sent_date 求められ HTTP 400 BAD REQUEST が返されます。
HTTP/1.0 400 Bad Request
Content-Type: application/json
{
"sent_date": [
"Invalid sent_date"
]
}
不正なパラメータ指定された場合、HTTP 400 BAD REQUEST が返されます。
以下はcURLを使って不正なパラメータでメッセージを取得しようとする例です:
curl -u <SID>:<AUTH_TOKEN> https://api.xoxzo.com/sms/messages/?sent_data=2016-02-28
sent_data が不正なため、正しい sent_date 求められ HTTP 400 BAD REQUEST が返されます。
HTTP/1.0 400 Bad Request
Content-Type: application/json
{
"sent_date": [
"This field is required"
]
}
よくあるメッセージ配信ステータス¶
status データ内にある、ステータスのリスト
メッセージステータス
詳細
QUEUED
メッセージは配信待ち
DELIVERED
メッセージの配信成功
DELIVERING
メッセージの配信中
FAIL
メッセージの配信失敗
エラー応答¶
APIは、無効なリクエストや不正アクセスに対して、標準のHTTPステータスコードを返します。
よくあるエラー:
ステータスコード
意味
400
不正なリクエスト。リクエストを処理できませんでした。
401
認証エラー。認証に失敗しました。
403
アクセス拒否。アカウントはリクエストされた機能へのアクセス権を持っていません。
404
未検出。リクエストされたリソースは存在しません。
422
処理できないエンティティ。検証に失敗しました。
検証エラーの例:
{
"variables": {
"code": [
"This field is required."
]
}
}