Hatena::Grouphatenadeveloper

Hatena Message Configuration API

en/message/apis/config

Hatena Message Configuration API

Overview

The Hatena Message Configuration API is an OAuth-based RESTful API. With this API, you can retrieve or change Hatena Message configurations for a Hatena user through HTTP GET or POST requests.

There are three features provided by the API:

Authentication

The API supports OAuth-based user authentication. You can obtain Consumer Keys for the OAuth access from the Access Hatena services with OAuth section in your User Settings. There is a tutorial document はてなサービスにおける OAuth (available only in Japanese at the time of writing, but sample codes are also included there).

The scope write_private is required for all operations in the API.

Configuration of PC mail delivery (/config)

The user setting for the frequency of delivery for the registered PC email address can be retrieved by fetching the following URL using an HTTP GET request:

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

Likewise, you can change the user's setting by issuing an HTTP POST request for the same URL.

Depending on the type of the message, the user setting might be ignored.

Parameters in HTTP requests

The following parameter can be included in HTTP requests in the application/x-www-form-urlencoded format:

Parameter nameParameter value#
mail_frequencyDelivery frequencyPOST: 1 (REQUIRED)

One of the following values can be set to mail_frequency:

-1 Don't send
0 Send every time
3 Once every 3 hours
24 Once a day

HTTP responses

If the retrieval or updating has not failed, a success response such as 200 (OK) is returned. The HTTP response body is a JSON data whose delivery_frequencies contains a property named as 1 whose value represents the frequency of PC email delivery. The value is a number from the list of available values for mail_frequency.

If the retrieval or updating has failed, an error response such as 400 (Bad Request) or 401 (Authorization Required) is returned.

Example

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"
  }
}

Configuration of self-authored message delivery (/ownmessage)

Whether the message whose From is the authenticated user himself/herself should be delivered (by e.g. emails) or not can be retrieved by fetching the following URL using an HTTP GET request:

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

Likewise, you can change the user's setting by issuing an HTTP POST request for the same URL.

Parameters in HTTP requests

The following parameter can be included in HTTP requests in the application/x-www-form-urlencoded format:

Parameter nameParameter value#
value0 to deliver, or 1 to not deliverPOST: 1 (REQUIRED)

HTTP responses

If the retrieval or updating has not failed, a success response such as 200 (OK) is returned. The HTTP response body is a JSON data whose send_own_message contains a boolean value representing whether self-authored messages should be delivered or not.

If the retrieval or updating has failed, an error response such as 400 (Bad Request) or 401 (Authorization Required) is returned.

Examples

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"
}

Configuration of delivery depending on message types (/typeconfig)

Whether messages of a particular type should be delivered via e.g. email or not can be retrieved by fetching the following URL using an HTTP GET request:

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

Likewise, you can change the user's setting by issuing an HTTP POST request for the same URL.

Parameters in HTTP requests

The following parameter can be included in the query component (GET) or in the request body (POST) of HTTP requests in the application/x-www-form-urlencoded format:

Parameter nameParameter value#
serviceA string representing the type of messages1 (REQUIRED)
typeA string representing the delivery media1 (REQUIRED)
value1 to deliver, or 0 to not deliverPOST: 1 (REQUIRED)

HTTP responses

If the retrieval or updating has not failed, a success response such as 200 (OK) is returned. The HTTP response body is a JSON data whose delivery property contains an object, which contains a property whose name is equal to the number representing the delivery media (a number which can be specified in the type parameter) and whose value is a boolean representing whether messages of the specified type should be delivered or not.

If the retrieval or updating has failed, an error response such as 400 (Bad Request) or 401 (Authorization Required) is returned.

A string representing the type of messages (service)

Available message types include:

String Description
id_call@h.hatena.ne.jp ID calls in Hatena Haiku
reply@h.hatena.ne.jp Replies in Hatena Haiku
comment@s.hatena.ne.jp Star comments
star_report@s.hatena.ne.jp Star reports

There are various kind of message types. Message type strings can be found in the source code of Settings page of Hatena Message.

Depending on the type of the message, the user setting might be ignored.

A string representing the delivery media (type)

String Description
1 (or receive_mail) PC emails
2 (or receive_mobile_mail)Janapese mobile phone emails
7 Notices for you

Depending on the type of the message, the user setting might be ignored.

Examples

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"}
}

Changes

  • April 11, 2013 Published.