mixi Developer Center (ミクシィ デベロッパーセンター)

mixi内でユーザは様々なコミュニケーションを行っていますが、その中でメッセージは利用頻度の高いサービスです。多くのサービスがコンテンツの友人間での共有を目的としているのに対して、メッセージは主に1対1のコミュニケーション手段として利用されています。Message APIを利用することで、様々な場所からユーザは友人にメッセージを送り、そして各種デバイス上で受け取ったメッセージを確認することができるようになるでしょう。

事前に必要なもの

Message APIを利用するためには、以下の情報をすでに入手している必要があります。

• “r_message”または“w_message”スコープおよびその両方について認可されたアクセストークン

上記以外のスコープで認可されたアクセストークンを使用して、Message APIにアクセスすることはできません。アクセストークンの入手方法については、認証認可手順のページをご覧ください。

Message APIで提供される機能とスコープ

Message APIでは様々な機能が提供されますが、それらは大きく「参照系」「投稿系」の2つに分類されます。この分類は、そのままMessage APIを利用するためのスコープに対応します。以下に、スコープと各機能の対応を示します。

受信メッセージ一覧の取得

認可ユーザが受信したメッセージおよびその一覧を取得するためのURIは以下となります。

GET https://api.mixi-platform.com/2/messages/[User-ID]/@inbox/[Message-ID]

さらに、以下のクエリパラメータをサポートしています。

取得結果は以下となります。

{
    "entry" : [
        {
            "id" : "e5f820e4f9f459b91c3730cc261e2629",
            "status" : "replied",
            "timeSent" : "2010-11-10T17:26:23+09:00",
            "title" : "タイトル",
            "body" : "本文",
            "sender" : {
                "id" : "rdqz7s6ew176q",
                "displayName" : "ニックネーム",
                "thumbnailUrl" : "http://mixi.jp/photo/user/rdqz7s6ew176q_2105834213.jpg",
                "profileUrl" : "http://mixi.jp/redirect_friend_api.pl?puid=xxxxxxxxxxxxx&client_id=xxxxxxxx;
            },
        },
        ・・・
    ],
    ・・・
}

個々のエントリに含まれる情報は、以下となります。

送信メッセージ一覧の取得

認可ユーザが送信したメッセージおよびその一覧を取得するためのURIは以下となります。

GET https://api.mixi-platform.com/2/messages/[User-ID]/@outbox/[Message-ID]

さらに、以下のクエリパラメータをサポートしています。

取得結果は以下となります。

{
    "entry" : [
        {
            "id" : "e5f820e4f1f458b91c3730cc261e1619",
            "timeSent" : "2010-11-10T17:26:23+09:00",
            "title" : "タイトル",
            "body" : "本文",
            "recipient" : {
                "id" : "rdqz7s6ew176q",
                "displayName" : "ニックネーム",
                "thumbnailUrl" : "http://mixi.jp/photo/user/rdqz7s6ew176q_2105834213.jpg",
                "profileUrl" : "http://mixi.jp/redirect_friend_api.pl?puid=xxxxxxxxxxxxx&client_id=xxxxxxxx;
            },
        },
        ・・・
    ],
    ・・・
}

個々のエントリに含まれる情報は、以下となります。

mixiからのお知らせ一覧の取得

認可ユーザが受信した「mixiからのお知らせ」およびその一覧を取得するためのURIは以下となります。

GET https://api.mixi-platform.com/2/messages/[User-ID]/@noticebox/[Message-ID]

さらに、以下のクエリパラメータをサポートしています。

取得結果は以下となります。

{
    "entry" : [
        {
            "id" : "e5f820e4f1f458b91c3730cc261e1619",
            "status" : "read",
            "timeSent" : "2010-11-10T17:26:23+09:00",
            "title" : "タイトル",
            "body" : "本文",
            "sender" : {
                "displayName" : "mixi",
                "thumbnailUrl" : "http://img.mixi.net/img/basic/common/mixi_logo_thumbnail001.gif"

            },
        },
        ・・・
    ],
    ・・・
}

個々のエントリに含まれる情報は、以下となります。

メッセージの送信

メッセージを送信するためのURIは以下となります。

POST https://api.mixi-platform.com/2/messages/[User-ID]/@self/@outbox

リクエストボディとして、送りたいメッセージの内容を以下のようにapplication/json形式にて指定します。

{
    "title" : "件名",
    "body" : "本文",
    "recipients" : ["rdqz7s6ew176q"]
}

また、以下のようにapplication/json形式にて指定することによって、受信メッセージに対する返信が可能となります。

{
    "title" : "件名",
    "body" : "本文",
    "inReplyTo : "e5f820e5f9we455691c3720cc261e2629"
}

個々の項目に指定すべき値は、以下となります。

メッセージの送信が成功した場合は、ステータスコードは200、およびそのメッセージを特定するためのIDを持つ以下のようなJSON文字列が返却されます。
このidは、送信メッセージ取得時に指定可能なidとなります。

{
    "id" : "e5f820e4f9f459b91c3730cc261e2629"
}

もしメッセージの送信に失敗した場合は、ステータスコード400番台または500番台と共に、そのエラーの内容を持つ以下のようなJSON文字列が返却されます。

{
    "error" : "access_denied",
    "error_description" : "your account is temporary prohibited"
}

メッセージの閲覧状態の変更

受信したメッセージの閲覧状態を変更するためのURIは以下となります。

PUT https://api.mixi-platform.com/2/messages/[User-ID]/@self/@inbox/[Message-ID]

また、mixiからのお知らせの閲覧状態を変更するためのURIは以下となります。

PUT https://api.mixi-platform.com/2/messages/[User-ID]/@self/@noticebox/[Message-ID]

そして、変更後の閲覧状態をリクエストボディにてJSON形式で指定します。

{
    "status" : "read"
}

変更処理が成功した場合は、ステータスコードは200、および成功したことを示すメッセージを持つ以下のようなJSON文字列が返却されます。

{
    "status" : "status changed"
}

もし変更処理に失敗した場合は、ステータスコード400番台または500番台と共に、そのエラーの内容を持つ以下のようなJSON文字列が返却されます。

{
    "error" : "status_conflicted",
    "error_description" : "status cannot be changed"
}

また、メッセージの返信に成功した場合は、
返信対象となった受信メッセージの閲覧状態が、自動的に“replied”に変更されることとなります。

メッセージの削除

受信したメッセージをゴミ箱に移動させるためのURIは以下となります。

DELETE https://api.mixi-platform.com/2/messages/[User-ID]/@self/@inbox/[Message-ID]

また、送信したメッセージをゴミ箱に移動させるためのURIは以下となります。

DELETE https://api.mixi-platform.com/2/messages/[User-ID]/@self/@outbox/[Message-ID]

mixiからのお知らせを完全に削除させるためのURIは以下となります。

DELETE https://api.mixi-platform.com/2/messages/[User-ID]/@self/@noticebox/[Message-ID]

URLにMessage-IDを指定せずに、リクエストボディにMessage-IDの一覧を以下のようにapplication/json形式で渡すことも可能です。

{
    "ids" : [ "a1a1a1a1a1", "b2b2b2b2b2b2", "c3c3c3c3c3c3" ]
}

• URLにMessage-IDがある場合は、リクエストボディが無視されます。

削除処理が成功した場合は、ステータスコードは200、および成功したことを示すメッセージを持つ以下のようなJSON文字列が返却されます。

{
    "status" : "delete done"
}

もし削除処理に失敗した場合は、ステータスコード400番台または500番台と共に、そのエラーの内容を持つ以下のようなJSON文字列が返却されます。

{
    "error" : "not_found",
    "error_description" : "message not found"
}

ページング、表現形式

Message APIは、ページングをサポートします。サポートされる表現形式は、JSON形式のみとなります。

ページングに関しては、APIでの取得件数として、countパラメータ無指定の場合は50件となります。

文字コードについては、リクエスト時に使用される文字コードはContent-Typeリクエストヘッダのcharset値によって指定可能です。また、レスポンス時に使用される文字コードはUTF-8となります。