Overview

The Message API is used to send a notification from the application to the user. The notification message can be checked on the user's My Page.

This API is included for the sake of maintaining compatibility with platforms for feature phones in Japan. Users' messages are not actually displayed.

Message Object Fields

The following is a list of Message object fields supported by the Mobage Open Platform.

recipients Field

For recipients, specify an array of guids. However, in the current implementation, you can only specify one guid per request for recipients.

urls Field

Specify an array of URl objects. At this time, the following can be specified as Url object fields.

API Request

HTTP Methods

Proxy model

• POST - Creates a Message between users within an application

Trusted model

• POST - Creates a Message to a user from an application

  ---

Endpoint URL

• Sandbox environment

  http://sb.sp.app.mbga.jp/api/restful/v1/messages/{guid}/{selector}

• Production environment

  http://sp.app.mbga.jp/api/restful/v1/messages/{guid}/{selector}

URI Template Parameters

guid

Only @me can be specified for the guid parameter.

For the Proxy model, @me denotes the viewer. On the other hand, for the Trusted model, @me denotes the current application.

selector

Only @outbox can be specified for the selector parameter.

Query Parameters

None.

OAuth Signed Request

Please see this specification to find out how to transfer data safely: OAuth Request Body Hash.

You must include xoauth_requestor_id as an Authorized header or query parameter.
Specify the following values according to the mode.

Proxy mode
　　guid of the viewer (value of opensocial_viewer_id sent from the Gadget Server)
Trusted mode
　　application id issued on the Developer Site.
 
For more information about generating the OAuth Signature in Trusted mode, please see OAuth Consumer Request 1.0 Draft 1.
 

API Response

Response Codes

The following is a list of the API response codes.

Notes

• The only value that can be specified for the type field of the Message object (tnx:MessageType) is "NOTIFICATION" (without the double quotes).
• The only guids that can be specified for the Message destination (recipients) are those of users who have installed the application.
• Only one guid per request can be specified for the Message destination (recipients).
• The Message title must fit within 38 single-byte or 19 double-byte characters.
  • The time and a short name for the application are inserted at the beginning of each message that the user will actually see.
• Do not allow the user to freely input any characters for the title.
• Emoji cannot be used in the title.
• For Proxy mode, make sure that Messages sent from a browsing user to a specific user are recorded no more frequently than once per minute. If requests are sent more frequently than this, 503 Service Unavailable will be returned.
  • In other words, if player A sends a Message to player B, player A cannot send another Message to player B for at least one minute.
  • In this case, even though player A can no longer send a Message to player B, player A can still send a Message to player C.
• For Trusted mode, make sure that Messages sent to a specific user are recorded no more frequently than once every four hours. If requests are sent more frequently than this, 503 Service Unavailable will be returned.
• For the sake of compatibility, "title" can also be used for the time being in the urls type field when specifying the Message link target. A url specified as title is handled in the same way as a url specified as mobile.
  • The only url that can be used in the value field when canvas is specified for the type field is the top or initial launch screen of the application. Both can be passed as view-params when a gadget is executed using appParams.
• If the user has not installed the corresponding application, 403 will be returned for the response code.
   

  ---

Examples

Notification to a User from the Viewer

In this sample, a notification Message is sent from the viewer to the specified guid.

Request Format

POST /api/restful/v1/messages/@me/@outbox
Content-Type: application/json; charset=utf8

{
   "type" : "NOTIFICATION",
   "title" : "A friends request has been delivered",
   "urls" : [
      {
         "value" : "http://example.com/foo/bar",
         "type" : "mobile"
      },
      {
         "value": "http://sb.sp.app.mbga.jp/game/12000129/play?appParams=requestFriends",
         "type": "canvas"
      }
   ],
   "recipients" : [
      10001
   ]
}

Response Format

202 Accepted

Reference Links

OpenSocial RESTful Protocol Specification v0.9 - 10. Messaging (Optional)
XML Schema Part 2: Datatypes Second Edition
URI Template draft-gregorio-uritemplate-03
OAuth Request Body Hash 1.0 Draft 4
OAuth Consumer Request 1.0 Draft 1
 

Revision History

• 03/01/2013
  • Initial release