Skip to main content

Message

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.

warning

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.

ValueDescriptionTypeNamespaceRemark
titleTitlexs:stringhttp://ns.opensocial.org/2008/opensocial–
recipientsguids of recipientsxs:string (unbounded)http://ns.opensocial.org/2008/opensocial–
urlsUsed for specifying the target links of a titletns:Url (unbounded)http://ns.opensocial.org/2008/opensocial–
typeMessage typetns:MessageTypehttp://ns.opensocial.org/2008/opensocialOnly "NOTIFICATION" (without the double quotes) can be specified

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.

ValueDescriptionTypeNamespaceRemark
valueURLxs:stringhttp://ns.opensocial.org/2008/opensocialThis is the link target when displaying the Message object's title field
typeUsage typexs:stringhttp://ns.opensocial.org/2008/opensocialSpecify "mobile" (link url for a mobile device) or "canvas" (link url for a PC). For compatibility, "title" can also be specified (for the time being)

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.

ValueDescriptionRemark
@meguid of the viewer or the id of the applicationRequired

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.

ValueDescriptionRemark
@outboxUser specified by the guid parameter or send collection resource of the applicationRequired

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.

Request HTTP methodResponse codeResponse messageDescription
POST202AcceptedIndicates that the Activity generation request was accepted successfully
POST400Bad RequestInvalid request data
POST401UnauthorizedOAuth authorization failed
POST403ForbiddenAccess failed for some reason other than an authentication error
POST500Internal Server ErrorFailed because of an API problem
POST503Service UnavailableExceeded the maximum number of messages that can be POSTed to a single user

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

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
  • Overview
  • Message Object Fields
    • recipients Field
    • urls Field
  • API Request
    • HTTP Methods
    • Endpoint URL
    • Query Parameters
    • OAuth Signed Request
  • API Response
    • Response Codes
    • Notes
  • Examples
    • Notification to a User from the Viewer
  • Reference Links
  • Revision History