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

http://example.com

tags

タグ

×

UTF-8

tag1,tag2

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

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

名称

詳細

必須

データタイプ

jp_kp

Kプレミアムフラグ

×

true の文字列

true

jp_kpl

Kプレミアム Liteフラグ

×

true の文字列

true

jp_kddi_sender

au向けSender ID

×

英数字

0312341234

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

注釈

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

  • jp_kp または jp_kpl パラメーターが有効の場合、ASCII文字のみのメッセージの最大の長さは140文字です。

  • ASCII以外の文字が含まれる場合(日本語など)、最大の長さは70文字です。

  • jp_kpjp_kpl を同時に指定することはできません。どちらか一方のみ指定してください。

  • jp_kpjp_kpl の違いは、sender のKDDI以外での表示のされ方にあります。詳細は、jp_kddi_sender の説明を参照してください。

注釈

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

  • jp_kpまたはjp_kplパラメーターが有効な場合、このパラメータに、あらかじめKDDIに登録してある番号を指定しなければいけません。

  • 受信者がKDDIの場合、このパラメータに指定した値が、携帯電話に表示されます。

  • jp_kp が指定されたとき、受信者がKDDI以外の場合は、ある固定した番号が、代わりに携帯電話に表示されます。

  • jp_kpl が指定されたとき、受信者がKDDI以外の場合は、sender に指定した番号が、代わりに携帯電話に表示されます。

注釈

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

  • jp_kp または jp_kpl パラメーターが有効の場合、ASCII文字のみのメッセージの最大の長さは140文字です。

  • ASCII文字のみのメッセージの最大の長さは160文字です。(jp_kpまはたjp_kplが無効の場合)

  • 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文字となります。

注釈

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

  • このパラメータ(省略可能)が指定された場合は、キャリア・ネットワークからSMSの配信完了(DLR)の通知があったときに、XOXZOクラウドシステムが指定されたURLを呼び出します。

  • XOXZOクラウドシステムはこのURLを呼び出すとき、httpのPOSTメソッドを使います。コールバックのパラメーターは「SMSの配信状態を確認するAPI」とほぼ同じです。 SMSの配信状態を確認するAPI を参照して下さい。

  • コールバックURLは http のステータス 200 で応答する必要があります。この応答をうけとるまで、最大10回まで呼び出しを繰り返します。

注釈

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

  • このパラメータ(省略可能)が指定された場合は、各API呼び出しにタグをつけることができます。このタグは、後から配信状態を確認するAPIをつかって読み出すことができます。

  • タグは、コンマで区切ることで複数付けられます。タグの前後の空白は取り除かれます。

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

このメッセージに付けられたタグです。タグが無いときは空のリスト[]になります。

送信された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で返される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

メッセージの配信失敗