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

JP向けオプションパラメーター

下記のパラメーターは、JP向けの受信者に提供されます。

名称 詳細 必須 データタイプ
jp_kp Kプレミアムフラグ × true の文字列 true
jp_kddi_sender au向けのSender ID × 数字 0312341234

Kプレミアムの詳細については KプレミアムのFAQページ までご確認ください。

注釈

jp_kp パラメーターに関する注意点

  • jp_kp パラメーターが有効の場合、ASCII文字のみのメッセージの最大の長さは140文字です。
  • ASCII以外の文字が含まれる場合(日本語など)、最大の長さは70文字です。

注釈

message パラメーターに関する注意点

  • ASCII文字のみのメッセージの最大の長さは160文字です。(jp_kpが無効の場合)
  • ASCII以外の文字が含まれる場合(日本語など)、最大の長さは70文字です。

注釈

recipient パラメーターに関する注意点

  • 特定の電話番号を指定する場合、Xoxzo は E.164 を番号のフォーマットに指定しています。
  • E.164 フォーマットは、電話番号の先頭に + プレフィックスをつけた後ロカールの 0 除く携帯の電話番号がくるという順番を定められています。
  • 有効な受信者記載例として、 +818011234567 と挙げられます。 81 は日本の国番号で、 8011234567 は携帯電話番号となります。

注釈

sender パラメーターに関する注意点

  • sender パラメーターには、+ を先頭につける必要はありません。
  • sender に、 送信元として、XOXZO1XOXZO といった英数字を指定することができます。この場合、 sender パラメーターの最大の長さは10となります。
  • sender パラメーターが、数字のみの場合、最大の長さは、15桁となります。

警告

sender は、最良の方法で発信されますが、それでも、受信者側にそのまま表示される保証はありません。任意の sender に置き換えられることもあります。これは、各キャリアや、ネットワークまたは政府が定めた規定によるもので、リクエストを受け取らない場合もあるからです。

注釈

message パラメーターに関する注意点

  • これは、受信者へ送るメッセージの本文になります。
  • メッセージはすべて、UTF-8にてコーディングしてください。
  • ASCIIに基づいた文字のみの場合、最大の長さは160文字となりますが、そうでない場合は、70文字となります。

下記は、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

{
    "status": "OK",
    "sent_time":"2015-08-27 09:22:32",
    "cost": 10,
    "sender": "<sender>",
    "recipient": "<recipient>",
    "url": "https://api.xoxzo.com/sms/messages/<msgid>/",
    "msgid": "<msgid>"
}

下記は、メッセージが配信失敗し、ステータスコード 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です。

送信されたSMSのリストを取得するAPI

以下のエンドポイントに GET リクエストをすると送信されたメッセージのリストを取得することが可能です。

https://api.xoxzo.com/sms/messages/

データは sent_time 新しい順でソートされて取得します。ログなどの作成に便利です。

演算子とオペレーターによって特定の日付でリストを取得することもできます。

名称 詳細 必須
sent_date YYYY-mm-ddのフォーマットで、メッセージ送信されたUTCベースの日付。過去90日間以内でなければならない。

以下の演算子を利用してある期間のメッセージのリスト取得することができます。

演算子 名称
<= 以下
< より小さい
= 等しい
> より大きい
>= 以上

注釈

  • 一度取得できるメッセージの数は最大5000までです。
  • 過去90日間のメッセージしか取得できません。
  • 本APIは一度に1つの演算子と1つの日付しか対応していません。
  • 日付はすべてUTC

レスポンスの例

この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": "OK",
       "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": "OK",
       "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": "OK",
       "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": "OK",
       "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": "OK",
       "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": "OK",
       "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 データ内にある、ステータスのリスト

メッセージステータス 詳細
配信待ち 配信待ち
OK メッセージの配信成功
DELIVERING メッセージの配信中
FAIL メッセージの配信失敗