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<Url>

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

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.

PREVIOUS

People

NEXT

Payment