Orkut Application Platform

On-Site Application Developer Guide: Messages

Contents

Sending Messages

Your application can send a message to any of the user's friend using the API. To do that, you must call the requestSendMessage function of the opensocial object:

var friendId = /* friend's OpenSocial ID here */;
var params = {};
params[opensocial.Message.Field.TITLE] = 'Message subject here';
params[opensocial.Message.Field.BODY] = 'Message body here.';

opensocial.requestSendMessage(friendId, opensocial.newMessage(params), callback);

The message will be delivered by email to the indicated friend. You can use HTML on the message body but, as is the case with activities, your code is subject to sanitization and rewriting.

Some important points to be aware of are:

  • Confirmation dialog: As was the case with posting activities, sending messages will also trigger a confirmation dialog. See the figure below for an example of how it looks.

  • HTML rewriting: As is the case with activities, the HTML that gets sent in messages is also subject to sanitization and rewriting, so not all tags and attributes will be honored. Always test your messages to see that they are being correctly delivered.

  • Limits on messages: In order to prevent spam, Orkut imposes a limit of messages per day that a particular application can send on behalf of a particular user. As of the time of this writing, the current limit is 10 messages.

Note: Orkut does not currently support sending messages to groups, such as for example all the viewer's friends. You have to send messages one by one.


Message Confirmation Screen. The user can see the message proposed by the application and can add a text of his own.

A Complete Example

As you can see in the code above, you need the friend's OpenSocialID to send a message, so that ID needs to come from a previous request. The following example shows the complete process: it requests and displays a list of friends for the user to choose from, and sends a message to the friend chosen by the user:

Select the friend to send the message to:
<div id='friendlist'>
</div>
<span style='color: grey' id='status'></span>

<script type='text/javascript'>
function setStatus(s) {
   debug.say(s);
   document.getElementById('status').innerHTML = s;
}

function init() {
   // load friends
   var req = opensocial.newDataRequest();

   var opt_params = {};
   opt_params[opensocial.DataRequest.PeopleRequestFields.MAX] = 20;

   var idspec = opensocial.newIdSpec({ "userId":"VIEWER", "groupId":"FRIENDS" });
   req.add(req.newFetchPeopleRequest(idspec, opt_params), 'friends');
   req.send(onLoadFriends);
   setStatus("Loading friends... Please wait.");
}

function onLoadFriends(data) {
   if (data.hadError()) {
      setStatus("*** error: " + data.getErrorMessage());
      return;
   }

   var friends = data.get('friends').getData().asArray();
   var html = [ "<ul>" ];
   for (var i in friends) {
      html.push("<li><a href='javascript:void(0)' ");
      html.push("onclick='window.sendToFriend(\"");
      html.push(friends[i].getId());
      html.push("\")'>Send to ");
      html.push(friends[i].getDisplayName());
      html.push("</a></li>");
   }
   html.push("</ul>");
   document.getElementById('friendlist').innerHTML = html.join('');
   setStatus("Choose a friend to send a message to.");
}

// we have to put this function in the window because we are using it as a literal
// event handler on the link (sure, there are more elegant ways to do this, but
// since this is just an example, we're not focusing on Javascript beauty)
window.sendToFriend = function(opensocialID) {
   sendTheMessage(opensocialID, 
      "Test message", 
      "Hello! This is a <b>test</b>! " + 
            "Isn't <a href='http://www.orkut.com'>Orkut</a> <em>cool?</em>");
};

function sendTheMessage(to, title, body) {
   var params = {};
   params[opensocial.Message.Field.TITLE] = title;
   params[opensocial.Message.Field.BODY] = body;

   opensocial.requestSendMessage(to, 
      opensocial.newMessage(params),
      onMessageSent);

   setStatus("Message request sent. Waiting for confirmation...");
}

function onMessageSent(data) {
   setStatus(data.hadError() ? 
      "*** Error: " + data.getErrorMessage() : "Success.");
}

gadgets.util.registerOnLoadHandler(init);
</script>

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.