はてなメッセージ設定 API

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

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

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

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

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

PCメール配送頻度設定 (/config)
自己メッセージ配送設定 (/ownmessage)
種類別配送設定 (/typeconfig)

認証

本 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 要求に含める引数

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

引数名	引数値	個数
`value`	配送するなら `0`、配送しないなら `1`	POST 時のみ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、配送しないなら 0	POST 時のみ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 仕様を公開

はてなメッセージ設定 API

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