SMS API¶
SMS APIにて、簡潔なHTTPエンドポイントを通じて、対応キャリアへSMSを送受信できます。
SMSメッセージ送信API¶
SMSメッセージを送信するには、 POST リクエストをエンドポイントに行ってください。
https://api.xoxzo.com/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/
上記の例にある <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リクエストをエンドポイントに行ってください。
https://api.xoxzo.com/sms/messages/<msgid>/
送信を行うたびに、 <msgid> を含むレスポンスが得られますので、この <msgid> を配信状態の確認にご利用ください。
例¶
下記は、CURLを使ったリクエストの例です。
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>",
"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>",
"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",
"sender": "XOXZO",
"sent_time": "2020-10-09 02:37:47",
"status": "DELIVERED",
"tags": [],
"url": "https://api.xoxzo.com/sms/messages/oxgyFO6tfwYkHLIMbURrz5smCv9QT423/"
}
送信されたSMSのリストを取得するAPI¶
以下のエンドポイントに GET リクエストをすると送信されたメッセージのリストを取得することが可能です。
https://api.xoxzo.com/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>",
"sent_time": null,
"status": "QUEUED",
"url": "https://api.xoxzo.com/sms/messages/<msgid>"
},
{
"cost": 10,
"msgid": "<msgid>",
"recipient": "<recipient>",
"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>",
"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>",
"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>",
"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>",
"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>",
"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
メッセージの配信失敗