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
例¶
下記は、CURLを使ったリクエストの例です。
curl -u <SID>:<AUTH_TOKEN> --data-urlencode 'recipient=<recipient>' --data-urlencode 'sender=<sender>' --data-urlencode 'message=<message>' https://api.xoxzo.com/sms/messages/
The <message> in the above example must be encoded in UTF-8 before sending.
レスポンスは、JSON構造となり、ステータスコード HTTP 201 CREATED にて返されます。
HTTP/1.1 201 CREATED
Content-Type: application/json
[
{
"msgid": "<msgid>"
}
]
レスポンスデータ¶
名称
詳細
msgid
このメッセージ固有のメッセージIDになります。
If there's invalid parameters given, HTTP 400 BAD REQUEST status code
will be returned. For example, if the message parameter is missing,
the HTTP response should be like this:
HTTP/1.1 400 BAD REQUEST
Content-Type: application/json
{
"message": [
"This field is required."
]
}
ちなみに
It's faster to actually try some test code againts the API to see immediate results. Signing up takes only a few minutes and it's free
SMSの配信状態を確認するAPI¶
To check a message status, make a GET request to the endpoint followed by <msgid>
テンプレートSMSの場合:
GET /sms/templates/<id>/messages/<msgid>/
フリーフォームSMSの場合:
GET /sms/messages/<msgid>/
Every time you send a SMS, you will get a response which contains <msgid>.
Use this <msgid> to check SMS status.
例¶
下記は、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>/
The response would be a JSON structure, returned with HTTP 200 OK status code:
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"
}
Below is a sample of a response for a message that failed to be delivered,
returned with a HTTP 200 OK status code:
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¶
You can pull a list of sent messages by making a GET request to the endpoint.
テンプレートSMSの場合:
GET /sms/templates/<id>/messages/
フリーフォームSMSの場合:
GET /sms/messages/
The sent messages results will be sorted based on their newest sent_time.
This API is useful for creating logs.
You can also pull sent messages for a specified sent date using
sent_date parameter followed by an operator and a date.
名称
詳細
必須
sent_date
YYYY-mm-ddのフォーマットで、メッセージ送信されたUTCベースの日付。過去90日間以内でなければならない。
○
以下の演算子を利用してある期間のメッセージのリスト取得することができます。
演算子
名称
<=
以下
<
より小さい
=
等しい
>
より大きい
>=
以上
注釈
一度に取得できるメッセージの数は最大30,000までです。
過去90日間のメッセージしか取得できません。
本APIは一度に1つの演算子と1つの日付しか対応していません。
日付はすべてUTC
警告
This API call is limited to use up to 1 request/hour.
レスポンスの例¶
The response data returned by the API is equivalent to what you get from the Check SMS status API
送信したメッセージのリストを取得します。¶
以下はcURLを使ってメッセージを取得する例です:
curl -u <SID>:<AUTH_TOKEN> https://api.xoxzo.com/sms/messages/
The response would be a JSON structure, returned with HTTP 200 OK status code:
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
The response would be a JSON structure, returned with HTTP 200 OK status code:
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
The response would be a JSON structure, returned with HTTP 200 OK status code:
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>"
},
]
指定された日付にメッセージがありません¶
If there's no sent messages on specified date, empty list with HTTP
200 OK status code will be returned.
以下はcURLを使って2016年1月30日に送信したメッセージを取得しようとする例です:
curl -u <SID>:<AUTH_TOKEN> https://api.xoxzo.com/sms/messages/?sent_date=2016-01-30
Since there's no message sent on 30 January 2016, the response would an empty
list returned with HTTP 200 OK status code:
HTTP/1.0 200 OK
Content-Type: application/json
[]
不正リクエストの例¶
If the specified date is in invalid format, HTTP 400 BAD REQUEST status
code will be returned.
以下はcURLを使って不正な日付の値でメッセージを取得しようとする例です:
curl -u <SID>:<AUTH_TOKEN> https://api.xoxzo.com/sms/messages/?sent_date=2016-02-30
Since 30 February 2016 is invalid date, HTTP 400 BAD REQUEST status code
will be returned explaining that the sent_date format is invalid:
HTTP/1.0 400 Bad Request
Content-Type: application/json
{
"sent_date": [
"Invalid sent_date format"
]
}
If the specified date is more than 90 days ago, HTTP 400 BAD REQUEST status
code will be returned.
以下はcURLを使って過去90日間よりも古いでメッセージを取得しようとする例です:
curl -u <SID>:<AUTH_TOKEN> https://api.xoxzo.com/sms/messages/?sent_date=2015-02-28
Since 28 February 2015 is more than 90 days ago, HTTP 400 BAD REQUEST status code
will be returned asking for a valid sent_date:
HTTP/1.0 400 Bad Request
Content-Type: application/json
{
"sent_date": [
"Invalid sent_date"
]
}
If the parameter is incorrectly specified, HTTP 400 BAD REQUEST status code
will be returned.
以下はcURLを使って不正なパラメータでメッセージを取得しようとする例です:
curl -u <SID>:<AUTH_TOKEN> https://api.xoxzo.com/sms/messages/?sent_data=2016-02-28
Since sent_data is not a correct parameter, HTTP 400 BAD REQUEST status code
will be returned asking for sent_date parameter:
HTTP/1.0 400 Bad Request
Content-Type: application/json
{
"sent_date": [
"This field is required"
]
}
よくあるメッセージ配信ステータス¶
This is a list of statuses that you can find in the status data:
メッセージステータス
詳細
QUEUED
メッセージは配信待ち
DELIVERED
メッセージの配信成功
DELIVERING
メッセージの配信中
FAIL
メッセージの配信失敗
エラー応答¶
APIは、無効なリクエストや不正アクセスに対して、標準のHTTPステータスコードを返します。
よくあるエラー:
ステータスコード
意味
400
不正なリクエスト。リクエストを処理できませんでした。
401
認証エラー。認証に失敗しました。
403
アクセス拒否。アカウントはリクエストされた機能へのアクセス権を持っていません。
404
未検出。リクエストされたリソースは存在しません。
422
処理できないエンティティ。検証に失敗しました。
検証エラーの例:
{
"variables": {
"code": [
"This field is required."
]
}
}