Hatena::Grouphatenadeveloper

はてなメッセージ設定 API

ja/message/apis/config

はてなメッセージ設定 API

本ドキュメントに関する注意事項

本ドキュメントははてなメッセージのユーザー設定を行う API について解説するものです。

はてなメッセージ設定 API の概要

はてなメッセージ設定 API は、 OAuth 認証を利用した REST API です。 HTTP の GET または POST を特定の URL に対して行うことで、あるはてなユーザーのはてなメッセージの設定を取得したり、変更したりできます。

現在次の3つの API を提供しています。

認証

本 API は OAuth によるユーザー認証に対応しています。 OAuth 認証の詳細に関しては、はてなのOAuthを利用する方法を参照してください。

はてなメッセージの設定の取得や設定には write_private 操作の承認を得ている必要があります。

PCメール配送頻度設定 (/config)

はてなメッセージはPCメールや携帯メールに配送することができますが、PC メールの配送の頻度は、

http://m2.hatena.com/config.json

... に対して HTTP GET メソッドによりアクセスすることで現在の設定を取得したり、 HTTP POST メソッドによりアクセスすることで設定を変更したりできます。

メッセージの種類によっては設定が適用されないことがあります。

HTTP 要求に含める引数

HTTP 要求には application/x-www-form-urlencoded 形式で次の引数を含めることができます。

引数名引数値個数
mail_frequency配送の頻度POST 時のみ1個 (必須)

mail_frequency には、次のいずれかの値を指定できます。

-1 送信しない
0 毎回送信する
3 3時間に1回送信する
24 1日に1回送信する

HTTP 応答

取得または変更に失敗しなかった場合、 200 (OK) などの成功を表す応答が返されます。 HTTP 応答の本体は JSON データとなっており、その delivery_frequencies に含まれる 1 の値が配信の頻度を表します。この値は mail_frequency のいずれかの数値です。

取得または変更に失敗した場合、 400 (Bad Request)、 401 (Authorization Required) などの HTTP 応答が返されます。

POST /config.json HTTP/1.1
Host: m2.hatena.com
Authorization: OAuth ...
User-Agent: ExampleUserAgent/1.0

mail_frequency=3
HTTP/1.1 200 OK
Content-Type: application/json

{
  "delivery_frequencies": {
    "1": "3"
  }
}

自己メッセージ配送設定 (/ownmessage)

送信者が自分であるメッセージをメール等で配送するかどうかは、

http://m2.hatena.com/ownmessage.json

... に対して HTTP GET メソッドによりアクセスすることで現在の設定を取得したり、 HTTP POST メソッドによりアクセスすることで設定を変更したりできます。

HTTP 要求に含める引数

HTTP 要求には application/x-www-form-urlencoded 形式で次の引数を含めることができます。

引数名引数値個数
value配送するなら 0、配送しないなら 1POST 時のみ1個 (必須)

HTTP 応答

取得または変更に失敗しなかった場合、 200 (OK) などの成功を表す応答が返されます。 HTTP 応答の本体は JSON データとなっており、その send_own_message が自分のメッセージを配送するか否かを表す boolean 値です。

取得または変更に失敗した場合、 400 (Bad Request)、 401 (Authorization Required) などの HTTP 応答が返されます。

POST /ownmessage.json HTTP/1.1
Host: m2.hatena.com
Authorization: OAuth ...
User-Agent: ExampleUserAgent/1.0

value=1
HTTP/1.1 200 OK
Content-Type: application/json

{
  "send_own_message": "0"
}

種類別配送設定 (/typeconfig)

メッセージの種類ごとにメール等で配送するかどうかの設定は、

http://m2.hatena.com/ownmessage.json

... に対して HTTP GET メソッドによりアクセスすることで取得したり、 HTTP POST メソッドによりアクセスすることで変更したりできます。

HTTP 要求に含める引数

HTTP 要求には、 URL の query 部分 (GET の場合) または本体 (POST の場合) に application/x-www-form-urlencoded 形式で次の引数を含めることができます。

引数名引数値個数
serviceメッセージの種類を表す文字列1個 (必須)
type配送方法を表す文字列1個 (必須)
value配送するなら 1、配送しないなら 0POST 時のみ1個 (必須)

HTTP 応答

取得または変更に失敗しなかった場合、 200 (OK) などの成功を表す応答が返されます。 HTTP 応答の本体は JSON データとなっており、その delivery に含まれる、配送方法を表す数値 (type に指定できる数値) に対応する値が、配送するか否かを表す boolean 値です。

取得または変更に失敗した場合、 400 (Bad Request)、 401 (Authorization Required) などの HTTP 応答が返されます。

メッセージの種類を表す文字列 (service)

文字列 意味
id_call@h.hatena.ne.jp はてなハイクのIDコール
reply@h.hatena.ne.jp はてなハイクの返信
comment@s.hatena.ne.jp スターコメント
star_report@s.hatena.ne.jp スターレポート

この他にも多くの種類があります。メッセージの種類を表す文字列は、はてなメッセージの設定ページのソースコードで調べることができます。

メッセージの種類によっては設定を変更できないことがあります。

配送方法を表す文字列 (type)

文字列 意味
1 (または receive_mail) PC メール
2 (または receive_mobile_mail) 携帯メール
7 あなたへのお知らせ

メッセージの種類によっては設定を変更できないことがあります。

POST /typeconfig.json HTTP/1.1
Host: m2.hatena.com
Authorization: OAuth ...
User-Agent: ExampleUserAgent/1.0

type=receive_mail&service=report@ugomemo.hatena.ne.jp&value=1
HTTP/1.1 200 OK
Content-Type: application/json

{
  "delivery": {"1": "0"}
}

変更履歴

  • 2013年4月11日 API 仕様を公開