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
メッセージの配信失敗
SMS受信API¶
SMS受信APIを使うと、電話番号を契約してSMSの受信ができるようになります
APIによる SMSイン番号 の見つけ方¶
このAPIを使うと、SMSイン番号(SIN)一覧の表示と契約を行うことができます。
空いているSINの一覧を得るには、以下へ GET リクエストを発行します。
curl -u <SID>:<AUTH_TOKEN> https://api.xoxzo.com/sms/sins/
レスポンスは、JSONとなり、ステータスコード HTTP 200 OK が返されます。:
HTTP/1.1 200 OK
Allow: GET, HEAD, OPTIONS
Connection: keep-alive
Content-Type: application/json
[
{
"country_code": "81",
"initial_subscription_cost": 37500.0,
"message_rate": 3,
"monthly_cost": 7500.0,
"sin": "815012345678",
"sin_uid": "JPafr34rafic76tf",
"prefix": "50"
},
{
"country_code": "81",
"initial_subscription_cost": 37500.0,
"message_rate": 3,
"monthly_cost": 7500.0,
"sin": "817012345678",
"sin_uid": "JPascfdrwersdf12",
"prefix": "70"
}
]
レスポンスデータ¶
名称
詳細
country_code
SINの国番号。
initial_subscription_cost
SINを契約するときに、最初にかかる費用。
message_rate
SINでメッセージを、一通受信するごとにかかる費用。
monthly_cost
SINを契約するのに必要な、月額費用。
sin
E.164 形式のSIN。国番号を含む。
sin_uid
SINを表すユニークな識別子。
prefix
0を除いた、SINのプリフィクス。
国コードあるいはプリフィックスでフィルタリングすることもできます。
curl -u <SID>:<AUTH_TOKEN> https://api.xoxzo.com/sms/sins/?country=JP
または:
curl -u <SID>:<AUTH_TOKEN> https://api.xoxzo.com/sms/sins/?prefix=817
国コードあるいはプリフィックスでフィルタリングをした場合、条件に一致したSINのみが表示されます。
APIによるSMSイン番号の契約¶
SMSイン番号を契約するには、以下のような POST リクエストを発行します。:
curl -u <SID>:<AUTH_TOKEN> -d'sin_uid=<sin_uid>' https://api.xoxzo.com/sms/sins/subscriptions/
<sin_uid> は、前項の GET リクエストで返された値の中から、契約したい電話番号のUIDの値を指定します。
契約が成立すると、HTTPステータス 201 OK が返されます。
警告
POSTリクエストが成功すると、直ちに最初の契約料がクレジットから引き落とされます。
APIによるSMSイン番号へのwebhookの関連付け¶
各SMSイン番号はメッセージを受信したときに呼び出されるwebhookを持つ必要があります。
curl -u <SID>:<AUTH_TOKEN> -d'action_url=<url>' https://api.xoxzo.com/sms/sins/subscriptions/<sin_uid>/
契約しているSMSイン番号にメッセージが届くと action_url で指定された url に対して POST メソッドでリクエストが送られます。
ちなみに
実際にテストコードでAPIを叩いたほうが早く動作確認できます。 無料登録 は無料ですぐできます。
webhookに送られるデータ¶
以下のデータがwebhookへ送られます。
名称
詳細
sender
メッセージの送信者。
sin
メッセージを受信したSMSイン番号。
message
受信したメッセージの内容。
received_time
メッセージを受信した時刻(UTC)
データはJSON形式で送信されます。webhookは、http のステータス 2XX で応答する必要があります。この応答をうけとるまで、最大１０回まで呼び出しを繰り返します。
APIによる契約中のSMSイン番号の一覧取得¶
契約中のSMSイン番号の一覧を得るには、下記のように GET リクエストを発行します。:
curl -u <SID>:<AUTH_TOKEN> https://api.xoxzo.com/sms/sins/subscriptions/
APIによるSMSイン番号の契約解除¶
契約解除のやりかた:
curl -XDELETE -u <SID>:<AUTH_TOKEN> https://api.xoxzo.com/sms/sins/subscriptions/<sin_uid>/