Message
message.send
This is an API for notifying users from applications.
API definitions
| REST Base URI | http://app.mbga-platform.jp/social/api/restful/v2 ( Service ) http://app.sb.mbga-platform.jp/social/api/restful/v2 ( Sandbox ) |
| REST HTTP Method | POST |
| REST URI Fragment | /messages/{userId}/@self/@outbox |
| REST Query Parameters | Send-Message-Request-Parameters |
| Return Object | None |
Approval
| type | permission | description |
|---|---|---|
| ANONYMOUS | false | Unauthorized access |
| SECURITY_TOKEN | false | Authorization using a security token |
| OAUTH_MOBILE | false | Authorization using an OAuth Token issued for a mobile device |
| OAUTH_CONSUMER | true | Authorization using a Consumer Request |
RESTful API response codes
| HTTP Status Code | HTTP Status Message | JSON-RPC Error Codes | Meaning |
|---|---|---|---|
| 202 | Accepted | – | Data successfully acquired |
| 400 | Bad Request | -32700, -32600, -32601, -32602, 400 | Corrupt request data on the client side |
| 401 | Unauthorized | 401 | Authorization error |
| 403 | Forbidden | 403 | The resource exists, but access is not possible due to a reason other than an authorization error |
| 404 | Not Found | 404 | The resource doesn’t exist |
| 405 | Method Not Allowed | 405 | That operation is not allowed |
| 500 | Internal Server Error | -32603 | An error on the API server side |
| 503 | Service 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 Code | Meaning |
|---|---|
| -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.
| Name | Type | Description |
|---|---|---|
| userId | UserId | Required Only '@me' is specifiable.This means the application itself. |
Base data types
- Starndard-Request-Parameters
Message
| Name | Type | Description |
|---|---|---|
| title | String | The title of the message |
| recipients | String | The user ID of the recipient |
| urls | Array | The URL of the link |
| type | MessageType | Only 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.
| Name | Type | Description |
|---|---|---|
| value | String | The link when the title field of the Message object is displayed |
| type | String | Please 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.