">mixi Developer Center (mDC)

mixi Connect

mixi Connect (English) » mixi Graph API » Technical Specification » Message API

Message API

The Message API is a frequently used service among various mixi APIs. Many services share their content with the user's friends. The Message API is mainly for one to one communication. The user is able to send messages from various locations and receive the messages on a variety of devices by using the Message API.

 

Items required in advance

To use the Message API, please have these items prepared beforehand.

  • Access token approved for “r_message” or “w_message”scope, or both scope.

Message API cannot be accessed using other scopes not specified above. For instructions on how to acquire the access token, please refer to the authentication approval procedure.

Message API capabilities and scopes

The Message API supplies various functions that can roughly be classified by "reference type" and "contribution type." The two types exactly correspond to Message API scopes. Correspondence between scopes and capabilities is shown below:

Scope Function
r_message Acquisition of received message list
Acquisition of send message list
w_message Send message
Change the message status
Delete the received messages
Delete the sent messages

Getting the received message list

The following is a URL to acquire the authorized user's received message list:

GET https://api.mixi-platform.com/2/messages/[User-ID]/@inbox/[Message-ID]
Parameter name Value to be specified
User-ID User ID for an approved user, “@me” indicating an approved user
Message-ID ID for a Message. If it is specified, only information for this message is returned in the result of the API call. This parameter can be omitted.

In addition, the query parameters below are supported:

Parameter Name Description
fields Specify the fields you want information for, separated by a comma. Specifiable field names are: "id,​body,​timeSent,​title,​sender.id,​sender.displayName,​sender.profileUrl,​sender.thumbnailUrl,​status".
If the default for the fields parameter is set, "id,​title,​timeSent,​sender.id,​sender.displayName" are considered specified. “@all” can specify all fields.
The id and title will always be included in the result. "sender.id sender.profileUrl" will not be included in the result if the user is not a friend.
updatedSince Messages more recent than the date specified as a parameter will be returned in the results. Limits the results to a feed more recent than the specified date as a parameter value. Date format is "yyyy-mm-ddThh:mm:ssZ" or "yyyy-mm-ddThh:mm:ss+09:00". (For more information see [XSdateTime]. You will need URI escape.)

Returned results are shown below.

{
    "entry" : [
        {
            "id" : "e5f820e4f9f459b91c3730cc261e2629",
            "status" : "replied",
            "timeSent" : "2010-11-10T17:26:23+09:00",
            "title" : "title",
            "body" : "text",
            "sender" : {
                "id" : "rdqz7s6ew176q",
                "displayName" : "nickname",
                "thumbnailUrl" : "http://mixi.jp/photo/user/rdqz7s6ew176q_2105834213.jpg",
                "profileUrl" : "http://mixi.jp/redirect_friend_api.pl?puid=xxxxxxxxxxxxx&client_id=xxxxxxxx"
            },
        },
        ・・・
    ],
    ・・・
}

The information contained in each entry is shown below.

Attribute name Details
id ID (Message-ID) to identify message.
status Message status. Any of the following: “unread”, “read” or “replied”.
timeSent Sent date and time. The date format is "yyyy-mm-ddThh:mm:ssZ". (For more information see [XSdateTime]. )
title Message title.
body Message body
sender.id Message sender ID
sender.displayName Message sender display nickname
sender.thumbnailUrl Message sender profile photo URL
sender.profileUrl Message sender profile page URL

Obtaining sent message list

The URL to obtain the approved user's sent message or list of messages is as follows:

GET https://api.mixi-platform.com/2/messages/[User-ID]/@outbox/[Message-ID]
Parameter Name Value to be specified
User-ID User ID for an approved user, “@me” indicates an approved user
Message-ID ID for a Message. If it is specified, only information from this message is returned as a result of the API call. Can be omitted.

In addition, the query parameter below is supported:

Parameter Name Description
fields Specify the fields you want information for, separated by a comma. Specifiable field names are "id,​body,​timeSent,​title,​recipient.id,​recipient.displayName,​recipient.profileUrl,​recipient.thumbnailUrl".
If the default fields parameter is set," id,​title,​timeSent,​recipient.id,​recipient.displayName" are considered specified. “@all” can specify all fields.
The id and title will always be included in the result. "recipient.id recipient.profileUrl" will not be included in the result if the user is not a friend.
updatedSince The new message more recent than the specified date as a parameter will be returned as the acquisition results. Limit the results to feed more recent than the specified date as a parameter value. Date format is "yyyy-mm-ddThh:mm:ssZ" or "yyyy-mm-ddThh:mm:ss+09:00". (For more information see [XSdateTime]. You will need URI escape.)

Returned results are shown below.

{
    "entry" : [
        {
            "id" : "e5f820e4f1f458b91c3730cc261e1619",
            "timeSent" : "2010-11-10T17:26:23+09:00",
            "title" : "title",
            "body" : "text",
            "recipient" : {
                "id" : "rdqz7s6ew176q",
                "displayName" : "nickname",
                "thumbnailUrl" : "http://mixi.jp/photo/user/rdqz7s6ew176q_2105834213.jpg",
                "profileUrl" : "http://mixi.jp/redirect_friend_api.pl?puid=xxxxxxxxxxxxx&client_id=xxxxxxxx"
            },
        },
        ・・・
    ],
    ・・・
}

The information contained in each entry is shown below.

Attribute name Details
id ID (Message-ID) to identify message
timeSent Sent date and time. The date format is "yyyy-mm-ddThh:mm:ssZ". (For more information see [XSdateTime]. )
title Message title
body Message body
recipient.id Message recipient ID
recipient.displayName Message recipient display nickname
recipient.thumbnailUrl Message recipient profile photo URL
recipient.profileUrl Message recipient profile page URL

Obtaining announcements from mixi

The URL to obtain the approved user's announcements received from mixi is as follows:

GET https://api.mixi-platform.com/2/messages/[User-ID]/@noticebox/[Message-ID]
Parameter
Name
Value to be specified
User-ID User ID for an approved user, “@me” indicates an approved user
Message-ID ID for a Message. If it is specified, only information from this message is returned as a result of the API call. Can be omitted.

In addition, the query parameter below is supported:

Parameter
Name
Description
fields Specify the fields you want information for, separated by a comma. Specifiable field names are “id,,​body,,​timeSent,,​title,,​sender.displayName,,​sender.thumbnailUrl,,​status”.
If the default fields parameter is set, “id,,​title,,​timeSent,,​sender.displayName” are considered specified. “@all” can specify all fields.
The id and title will always be included in the result.
updatedSince The new message more recent than the specified date as a parameter will be returned as the acquisition results. Limit the results to feed more recent than the specified date as a parameter value. Date format is “yyyy-mm-ddThh:mm:ssZ” or “yyyy-mm-ddThh:mm:ss+09:00”. (For more information see [XSdateTime]. You will need URI escape.)

Returned results are shown below.


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

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

The information contained in each entry is shown below.

Attribute name Details
id ID (Message-ID) to identify message
status Message status. Either “unread” or “read”.
timeSent Sent date and time. The date format is “yyyy-mm-ddThh:mm:ssZ”. (For more information see [XSdateTime]. )
title Message title
body Message body
* Depending on the content, the message body may be returned as HTML.
sender.displayName Message sender display nickname (always “mixi”)
sender.thumbnailUrl Message sender profile photo URL (fixed)

Sending message

The URL to send a message is shown below.

POST https://api.mixi-platform.com/2/messages/[User-ID]/@self/@outbox
Parameter Name Value to be specified
User-ID User ID for an approved user, “@me” indicate an approved user

Specify the content type of the message sent in the request body as application/json format as below.

{
    "title" : "Subject",
    "body" : "Text",
    "recipients" : ["rdqz7s6ew176q"]
}

Using content type application/json format, replying to a received message can be achieved as shown below.

{
    "title" : "Title",
    "body" : "Body",
    "inReplyTo : "e5f820e5f9we455691c3720cc261e2629"
}

The value to be specified for each field is shown below.

Parameter Name Value to be specified
title Message title
body Message body
recipients Recipients user ID. Only one can be specified.
inReplyTo ID of received messages being replied to.
This parameter can't be specified with recipients at the same time.
If inReplyTo is specified, the recipient's user ID becomes the incoming message's sender ID automatically.

If sending the message is successful, a status code of 200 and JSON string with an ID to specify
its message will be returned as shown below.

{
    "id" : "e5f820e4f9f459b91c3730cc261e2629"
}

If sending the message failed, a Json string with the error message as shown below will be returned along with a status code of either 400s or 500s.

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

Changing the message browsing state

The URI to change the received message's browsing state is as shown below.

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

Or, to change the state of an announcement from mixi, use the URI below.

PUT https://api.mixi-platform.com/2/messages/[User-ID]/@self/@noticebox/[Message-ID]
Parameter Name Value to be specified
User-ID Approved user's User ID, or “@me” for the approved user.
Message-ID ID of the message you want to change

Specify the modified browsing state with a JSON format request body.

{
    "status" : "read"
}
Parameter Name Value to be specified
status Modified browsing state. Specify one of “read” or “replied”. You can't specify “read” for “replied” messages.
* Announcements from mixi cannot be marked “replied”.

If the modification process has succeeded, a status code of 200 and a JSON string with a success message as shown below will be returned.

{
    "status" : "status changed"
}

If the modification process has a problem, a JSON string that has an error message along with a status code of either 400s or 500s will be returned.

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

If replying to the message has succeeded,
the replied message in the received message browsing view will change to “replied” automatically.

Deleting Messages

The URI to delete a received message into the recycle bin is as shown below.

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

The URI to delete a sent message into the recycle bin is as shown below.

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

Announcements from mixi can be deleted permanently by using the URI below.

DELETE https://api.mixi-platform.com/2/messages/[User-ID]/@self/@noticebox/[Message-ID]
Parameter Name Value to be specified
User-ID Approved user's User ID, or “@me” for approved user himself
Message-ID ID of message you want to move to the recycle bin

Instead of specifying a Message-ID in the URL, it is possible to provide a list of Message-IDs in the request body using the application/json format.

{
    "ids" : [ "a1a1a1a1a1", "b2b2b2b2b2b2", "c3c3c3c3c3c3" ]
}
  • When a Message-ID is present in the URL, the request body is ignored.

If the delete was successful, a status code 200 and the JSON string with the message shown below will be returned.

{
    "status" : "delete done"
}

If the delete failed, a JSON string that has error message as that shown below along with a status code in the 400s or 500s will be returned.

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

Paging, Format

The message API supports paging which is supported in JSON format.

For paging, if the API acquisition count parameter is not specified, the count will be 50.

For character encoding, the encoding in the request can be specified by the charset value of a Content-Type request header. The encoding used for reply is UTF-8.

TOP OF THIS PAGE