Skip to main content

Message

message.send​

This is an API for notifying users from applications.

API definitions​

REST Base URIhttp://app.mbga-platform.jp/social/api/restful/v2 ( Service ) http://app.sb.mbga-platform.jp/social/api/restful/v2 ( Sandbox )
REST HTTP MethodPOST
REST URI Fragment/messages/{userId}/@self/@outbox
REST Query ParametersSend-Message-Request-Parameters
Return ObjectNone

Approval​

typepermissiondescription
ANONYMOUSfalseUnauthorized access
SECURITY_TOKENfalseAuthorization using a security token
OAUTH_MOBILEfalseAuthorization using an OAuth Token issued for a mobile device
OAUTH_CONSUMERtrueAuthorization using a Consumer Request

RESTful API response codes​

HTTP Status CodeHTTP Status MessageJSON-RPC Error CodesMeaning
202Accepted–Data successfully acquired
400Bad Request-32700, -32600, -32601, -32602, 400Corrupt request data on the client side
401Unauthorized401Authorization error
403Forbidden403The resource exists, but access is not possible due to a reason other than an authorization error
404Not Found404The resource doesn’t exist
405Method Not Allowed405That operation is not allowed
500Internal Server Error-32603An error on the API server side
503Service Unavailable–The API cannot be used temporarily

JSON-RPC error codes​

These are values are included in the code field of the Error object when an error has occurred.

RPC CodeMeaning
-32700 (Parse error)Invalid JSON format
-32600 (Invalid Request)Invalid JSON-RPC request
-32601 (Method not found)The method either doesn’t exist or is an unusable method
-32602 (Invalid params)Invalid API request parameters
-32603 (Internal server error)An error on the API server side
400 (Bad Request)A bad request on the client side that does not correspond to any other error
401 (Unauthorized)Authorization error
403 (Forbidden)The resource exists, but access is not possible due to a reason other than an authorization error
404 (Not Found)The resource doesn’t exist
405 (Method Not Allowed)That operation is not allowed

Data types​

Send-Message-Request-Parameters​

userId is specified as a URI Template Parameter, and all other parameters are specified as Query Strings.

NameTypeDescription
userIdUserIdRequired Only '@me' is specifiable.This means the application itself.

Base data types

  • Starndard-Request-Parameters

Message​

NameTypeDescription
titleStringThe title of the message
recipientsStringThe user ID of the recipient
urlsArrayThe URL of the link
typeMessageTypeOnly NOTIFICATION is specifiable.
recipients field​

Please specify recipients as a user ID array. Currently, only one user ID can be specified as a recipient for each request.

urls field​

Please specify as a Url object array. The following can be specified as Url object fields.

NameTypeDescription
valueStringThe link when the title field of the Message object is displayed
typeStringPlease specify "mobile" (the URL of the link for mobile devices) or "canvas" (the URL of the link for PC).

Precautions​

  • Only "NOTIFICATION" (excluding the double quotation marks) can be specified in the type field of the Message object (tnx:MessageType).
  • Only users that have installed that application can be specified as the guid for Message recipients.
  • Only one guid can be specified as Message recipients for each request.
  • Ensure that the title of the Message is 38 single-byte characters or 19 double-byte characters, or shorter.
    • The time and abbreviated application name are displayed at the top of every message that the user sees.
  • Do not set the free text from the user as the title.
  • Pictographs cannot be used in the title.
  • Please set the record so that Messages are sent to the specified users only once within a 4-hour period. If this limit is exceeded and a request is sent, 503 Service Unavailable will be returned.
  • Only the strings at the top of the application (http://yahoo-mbga.jp/game/$appId) and on the start screen (http://yahoo-mbga.jp/game/$appId/play) can be used as the url string in the value when canvas has been specified as the type field value. In the case of sandbox, those at sb.yahoo-mbga.jp can be used. In either case, it is possible to use appParams and hand them over as view-params when running the gadget.

Sample data​

RESTful API​

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

{
"type" : "NOTIFICATION",
"title" : "You have received a friend request",
"urls" : [
{
"value" : "http://example.com/foo/bar",
"type" : "mobile"
},
{
"value" : "http://sb.yahoo-mbga.jp/game/9999999/play?appParams=requestFriends",
"type" : "canvas"
}
],
"recipients" : [
999998
]
}

See Also​

OpenSocial Core API Server Specification 1.0
OpenSocial Core Data Specification 1.0
OpenSocial Social API Server Specification 1.0
OpenSocial Social Data Specification 1.0

Update history​

Revision History​

  • 12/2010
    • Initial Release.