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

mixi Connect

mixi Connect » mixi Graph API » 技術仕様 » Message API

Message API

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

 

事前に必要なもの

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

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

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

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

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

スコープ 機能
r_message 受信メッセージ一覧の取得
送信メッセージ一覧の取得
w_message メッセージの送信
メッセージの閲覧状態の変更
受信したメッセージの削除
送信したメッセージの削除

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

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

GET https://api.mixi-platform.com/2/messages/[User-ID]/@inbox/[Message-ID]
パラメータ名 指定する値
User-ID 認可ユーザのユーザID、および認可ユーザ自身を示す“@me”
Message-ID あるメッセージのID。これを指定した場合は、API呼び出しの結果として、そのメッセージの情報のみが返却される。省略可。

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

パラメータ名 説明
fields 取得したい情報の項目をカンマ区切りで指定します。指定可能な項目名は「id,​body,​timeSent,​title,​sender.id,​sender.displayName,​sender.profileUrl,​sender.thumbnailUrl,​status」です。
もしfieldsパラメータを省略した場合には、「id,​title,​timeSent,​sender.id,​sender.displayName」が指定されたと見なされます。また“@all”にて全項目を指定可能です。
これらの内、idおよびtitleについては、必ず結果に含まれます。また、「sender.id sender.profileUrl」は、そのユーザが友人でない場合は、結果に含まれません。
updatedSince このパラメータにて指定された日時よりも新しいメッセージを、APIの取得結果として返却します。このパラメータ値として指定された日時よりも新しいフィードに結果を限定します。日時の書式は「yyyy-mm-ddThh:mm:ssZ」や「yyyy-mm-ddThh:mm:ss+09:00」となります(詳しくは[XSdateTime]を参照、URIエスケープが必要)

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

{
    "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;
            },
        },
        ・・・
    ],
    ・・・
}

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

属性名 説明
id メッセージを特定するためのID (Message-ID)
status メッセージの閲覧状態。“unread”(未読), “read”(既読), “replied”(返信済み)のいずれかとなる。
timeSent 送信日時。日時の書式は「yyyy-mm-ddThh:mm:ss+09:00」となります(詳しくは[XSdateTime]を参照)。
title メッセージの件名。
body メッセージの本文。
sender.id メッセージの送信者のID。
sender.displayName メッセージの送信者のニックネーム。
sender.thumbnailUrl メッセージの送信者のプロフィール画像のURL。
sender.profileUrl メッセージの送信者のプロフィールページのURL。

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

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

GET https://api.mixi-platform.com/2/messages/[User-ID]/@outbox/[Message-ID]
パラメータ名 指定する値
User-ID 認可ユーザのユーザID、および認可ユーザ自身を示す“@me”
Message-ID あるメッセージのID。これを指定した場合は、API呼び出しの結果として、そのメッセージの情報のみが返却される。省略可。

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

パラメータ名 説明
fields 取得したい情報の項目をカンマ区切りで指定します。指定可能な項目名は「id,​body,​timeSent,​title,​recipient.id,​recipient.displayName,​recipient.profileUrl,​recipient.thumbnailUrl」です。
もしfieldsパラメータを省略した場合には、「id,​title,​timeSent,​recipient.id,​recipient.displayName」が指定されたと見なされます。また“@all”にて全項目を指定可能です。
これらの内、idおよびtitleについては、必ず結果に含まれます。また、「recipient.id recipient.profileUrl」は、そのユーザが友人でない場合は、結果に含まれません。
updatedSince このパラメータにて指定された日時よりも新しいメッセージを、APIの取得結果として返却します。このパラメータ値として指定された日時よりも新しいフィードに結果を限定します。日時の書式は「yyyy-mm-ddThh:mm:ssZ」や「yyyy-mm-ddThh:mm:ss+09:00」となります(詳しくは[XSdateTime]を参照、URIエスケープが必要)。

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

{
    "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;
            },
        },
        ・・・
    ],
    ・・・
}

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

属性名 説明
id メッセージを特定するためのID (Message-ID)
timeSent 送信日時。日時の書式は「yyyy-mm-ddThh:mm:ss+09:00」となります(詳しくは[XSdateTime]を参照)。
title メッセージの件名。
body メッセージの本文。
recipient.id メッセージの受信者のID。
recipient.displayName メッセージの受信者のニックネーム。
recipient.thumbnailUrl メッセージの受信者のプロフィール画像のURL。
recipient.profileUrl メッセージの受信者のプロフィールページのURL。

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

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

GET https://api.mixi-platform.com/2/messages/[User-ID]/@noticebox/[Message-ID]
パラメータ名 指定する値
User-ID 認可ユーザのユーザID、および認可ユーザ自身を示す“@me”
Message-ID あるメッセージのID。これを指定した場合は、API呼び出しの結果として、そのメッセージの情報のみが返却される。省略可。

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

パラメータ名 説明
fields 取得したい情報の項目をカンマ区切りで指定します。指定可能な項目名は「id,​body,​timeSent,​title,​sender.displayName,​sender.thumbnailUrl,​status」です。
もしfieldsパラメータを省略した場合には、「id,​title,​timeSent,​sender.displayName」が指定されたと見なされます。また"@all"にて全項目を指定可能です。
これらの内、idおよびtitleについては、必ず結果に含まれます。
updatedSince このパラメータにて指定された日時よりも新しいメッセージを、APIの取得結果として返却します。このパラメータ値として指定された日時よりも新しいフィードに結果を限定します。日時の書式は「yyyy-mm-ddThh:mm:ssZ」や「yyyy-mm-ddThh:mm:ss+09:00」となります(詳しくは[XSdateTime]を参照、URIエスケープが必要)。

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


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

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

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

属性名 説明
id メッセージを特定するためのID (Message-ID)
status メッセージの閲覧状態。“unread”(未読), “read”(既読)のいずれかとなる。
timeSent 送信日時。日時の書式は「yyyy-mm-ddThh:mm:ss+09:00」となります(詳しくは[XSdateTime]を参照)。
title メッセージの件名。
body メッセージの本文。
※ 内容によって本文がHTMLの場合があります。
sender.displayName メッセージの送信者のニックネーム。(固定「mixi」)
sender.thumbnailUrl メッセージの送信者のプロフィール画像のURL。(固定)

メッセージの送信

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

POST https://api.mixi-platform.com/2/messages/[User-ID]/@self/@outbox
パラメータ名 指定する値
User-ID 認可ユーザのユーザID、および認可ユーザ自身を示す“@me”

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

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

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

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

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

パラメータ名 指定する値
title メッセージの件名。
body メッセージの本文。
recipients 送信先のユーザID。一人のみ指定可能。
inReplyTo 返信対象となる受信メッセージのID。
このパラメータをrecipientsと同時に指定する事はできません。
inReplyToを指定した場合、送信先のユーザIDは自動的に受信メッセージの送信者IDとなります。

メッセージの送信が成功した場合は、ステータスコードは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]
パラメータ名 指定する値
User-ID 認可ユーザのユーザID、および認可ユーザ自身を示す“@me”
Message-ID 変更したいメッセージのID。

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

{
    "status" : "read"
}
パラメータ名 指定する値
status 変更後の閲覧状態。“read”(既読)もしくは“replied”(返信済み)のいずれかを指定する。もし既に“replied”のメッセージに対して、“read”は指定できない。
※ mixiからのお知らせは"replied"(返信済み)に設定することがができません。

変更処理が成功した場合は、ステータスコードは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]
パラメータ名 指定する値
User-ID 認可ユーザのユーザID、および認可ユーザ自身を示す“@me”
Message-ID ゴミ箱に移動させたいメッセージの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となります。

このページの上部へ