Working with Users in Facebook

Overview

The following operations allow you to work with users. Click an operation name to see details on how to use it.

For a sample proxy service that illustrates how to work with users, see Sample configuration.

Operation	Description
createPost	Allows to create a post.
createUserAchievement	Allows to create the achievements.
deleteUserAchievement	Allows the user to delete the required achievement type.
getMutualFriends	Allows to retrieve the list of mutual friends between two people.
getUserDetails	Allows to retrieve the details of the user.
isFriend	Checks if the person is a friend of the user.
publishNotification	Allows to publish the user's unread Facebook notifications.
publishPhoto	Allows the user to upload photos.
sendAppRequest	Allows the user to receive the requests from the app making the API call.

Operation details

This section provides details on each of the operations.

Creating a post

This method allows the users to publish a post.

createPost

<facebook.createPost> 
	<message>{$ctx:message}</message> 
	<link>{$ctx:link}</link> 
	<picture>{$ctx:picture}</picture>
	<name>{$ctx:name}</name>
	<caption>{$ctx:caption}</caption>
	<description>{$ctx:description}</description>
	<actions>{$ctx:actions}</actions> 
	<place>{$ctx:place}</place> 
	<tags>{$ctx:tags}</tags> 
	<privacy>{$ctx:privacy}</privacy> 
	<objectAttachment>{$ctx:objectAttachment}</objectAttachment> 
</facebook.createPost>

Properties

message: The main body of the post, otherwise called the status message. Either link or message must be supplied.

link: The URL of a link to attach to the post. Either link or  message must be supplied. Additional fields associated with link are shown below.

picture: Determines the preview image associated with the link.

name: Overwrites the title of the link preview.

caption: Overwrites the caption under the title in the link preview.

description: Overwrites the description in the link preview

actions: The action links attached to the post.

place: Page ID of a location associated with this post.

tags: Comma-separated list of user IDs of people tagged in this post. You cannot specify this field without also specifying a place

privacy: Determines the privacy settings of the post. If not supplied, this defaults to the privacy level granted to the app in the Login Dialog. This field cannot be used to set a more open privacy setting than the one granted.

objectAttachment: Facebook ID for an existing picture in the person's photo albums to be used as the thumbnail image. The person must be the owner of the photo, and the photo cannot be part of a message attachment.

Sample request

Following is a sample REST request for the createPost method.

Sample Request for createPost

{
"apiUrl":"https://graph.facebook.com",
"apiVersion":"v2.4",
"accessToken":"CAACEdEose0cBAELbf7L36EFqHJktqfWa75sOC92i0PiZC13cEmvL4wb2b6Oaz7m7V46QydCUVPTgE7Ouxu35RloyVcrdmFnpvkyp0CJZCR0oAGc1wZAP9yN4a49O53PkA7z8QG5mJNfvKggggG8Xdbgcl1w72NMZC7L7SIqht40bmW4iAaXhTkFUO0ybOkcZD",
"message":"This week is not over"
}

Further illustration on link, actions and privacy is given in https://developers.facebook.com/docs/graph-api/reference/user/feed/#readfields

Related Facebook documentation:

https://developers.facebook.com/docs/graph-api/reference/user/feed/#publish

Creating user achievement

This will create the achievements of the user received from Facebook Games.

createUserAchievement

<facebook.createUserAchievement>
	<achievement>{$ctx:achievement}</achievement>
</facebook.createUserAchievement>

Properties

achievement: Required - The unique URL of the type of achievement that the person will receive.

Sample request

Following is a sample REST request for the createUserAchievement method.

Sample Request for createUserAchievement

{
"apiUrl":"https://graph.facebook.com",
"apiVersion":"v2.4",
"accessToken":"CAACEdEose0cBAGlDzIRGv0KAopxqBhmSKgQTbfvnROAZAwZBPSnH7OpqVeEP9t4eZCpO2xbIdIZAI4g6MayNwIgk3R7t4xqX2atZAKfxqJS8UnacJJjthuAsnr8eI7pyOuLojRtdzH2zNFdwt7K1QeJgH6isCYpAFg2ZBY6r3MqDssgTQ7fES5zCrPpopr3S29wAKiz089MgZDZD",
"achievement":"http://www.krishantha.com/fbtest.html"
}

Related Facebook documentation:

https://developers.facebook.com/docs/graph-api/reference/user/achievements/#publish

Deleting user achievement

The following will allow the user to delete the required achievement type.

deleteUserAchievement

<facebook.deleteUserAchievement>
	<achievement>{$ctx:achievement}</achievement>
</facebook.deleteUserAchievement>

Properties

achievement: Required - The unique URL of the type of achievement you want to delete.

Sample request

Following is a sample REST request for the deleteUserAchievement method.

Sample Request for deleteUserAchievement

{
"apiUrl":"https://graph.facebook.com",
"apiVersion":"v2.4",
"accessToken":"CAACEdEose0cBAGlDzIRGv0KAopxqBhmSKgQTbfvnROAZAwZBPSnH7OpqVeEP9t4eZCpO2xbIdIZAI4g6MayNwIgk3R7t4xqX2atZAKfxqJS8UnacJJjthuAsnr8eI7pyOuLojRtdzH2zNFdwt7K1QeJgH6isCYpAFg2ZBY6r3MqDssgTQ7fES5zCrPpopr3S29wAKiz089MgZDZD",
"achievement":"http://www.krishantha.com/fbtest.html"
}

Related Facebook documentation:

https://developers.facebook.com/docs/graph-api/reference/user/achievements/#delete

Retrieving mutual friends

The following will display the list of mutual friends between two people.

getMutualFriends

<facebook.getMutualFriends>
	<userAId>{$ctx:userAId}</userAId>
	<userBId>{$ctx:userBId}</userBId>
</facebook.getMutualFriends>

Properties

userAId: The ID of this person's user account.
userBId: The ID of the user's selected friend.

Sample request

Following is a sample REST request for the getMutualFriends method.

Sample Request for getMutualFriends

{
"apiUrl":"https://graph.facebook.com",
"apiVersion":"v2.4",
"accessToken":"CAACEdEose0cBAAAQrho1OkWWT1YUZAzbOkXYq8VZBacxr7a7sWh3KwLJL7WVkwLBFUXBWAIy3G59HpWx1FWIrbSIlf2tbO6TTB4c4RCk5WkR8Llyavcze7y1obrG86e0LZAMCZAvLiNxJ8Vb6b8HBTD0TL3WRLiZBXRhYDRFli5c2gxw73Xp8pZBcUsNue5eIZD",
"userAId":"747051343",
"userBId":"1732179422",
"fields":""
}

For further information on "fields", refer to https://developers.facebook.com/docs/graph-api/reference/user/mutualfriends#readfields.

Related Facebook documentation:

https://developers.facebook.com/docs/reference/api/video/#!/docs/graph-api/reference/user/mutualfriends

Retrieving user details

This method will retrieve details of the user. This requires the fields and connection parameters to be passed in init.

getUserDetails

 <facebook.getUserDetails/>

Sample request

Following is a sample REST request for the getUserDetails method.

Sample Request for getUserDetails

{
"apiUrl":"https://graph.facebook.com",
"apiVersion":"v2.4",
"accessToken":"CAACEdEose0cBAPas3EqVsnzvtvEyZAPdrXEgdRRHEYEa6wZBJzupmqxJQXnxQ75EHeyg9cZBa2lOgObUpdmTTfQLqryHHjAV5bgd7njEML9uZBAaNuYl6q1KjlCteifZA9THGTRsZBZBk2LQQEaaHZCxQmUsYh3RMghs9vDGhOZC0Y8ZAdVpRl3usfCRvitQtLNHPNKOWzy59peAZDZD",
"fields":""
}

For further details on "fields", refer to https://developers.facebook.com/docs/graph-api/reference/user#fields

Related Facebook documentation:

https://developers.facebook.com/docs/graph-api/reference/user#read

Determining friends

This method determines whether a person is friends with the root node user. This requires the fields parameter to be passed into init.

isFriend

<facebook.isFriend>
	<sourceUserId>{$ctx:sourceUserId}</sourceUserId>
	<targetUserId>{$ctx:targetUserId}</targetUserId>
</facebook.isFriend>

Properties

sourceUserId: ID of the person to be determined.
targetUserId: ID of the user to be checked with.

Sample request

Following is a sample REST request for the isFriend method.

Sample Request for isFriend

{
"apiUrl":"https://graph.facebook.com",
"apiVersion":"v2.4",
"accessToken":"CAACEdEose0cBAAAQrho1OkWWT1YUZAzbOkXYq8VZBacxr7a7sWh3KwLJL7WVkwLBFUXBWAIy3G59HpWx1FWIrbSIlf2tbO6TTB4c4RCk5WkR8Llyavcze7y1obrG86e0LZAMCZAvLiNxJ8Vb6b8HBTD0TL3WRLiZBXRhYDRFli5c2gxw73Xp8pZBcUsNue5eIZD",
"sourceUserId":"1732179422",
"targetUserId":"747051343",
"fields":""
}

Related Facebook documentation:

https://developers.facebook.com/docs/graph-api/reference/user/friends/#read

Publishing notification

Displays the user's unread Facebook notifications.

publishNotification

<facebook.publishNotification>
	<href>{$ctx:href}</href>
	<userId>{$ctx:userId}</userId>
	<template>{$ctx:template}</template>
</facebook.publishNotification>

Properties

href: The relative path that someone clicking on the notification will be directed to. This will be appended to the app's canvas URL.
userId: The ID of the person's user account.
template: The message text of the notification. This can be formatted according to special text templating. Maximum of 180 characters.

Sample request

Following is a sample REST request for the publishNotification method.

Sample Request for publishNotification

{
"apiUrl":"https://graph.facebook.com",
"apiVersion":"v2.4",
"accessToken":"CAAGZCMZA2ZCZBjIBAGggngSr83BQeKyZBURGscejHaGc8yI6524yDPv6lsamw2ua7Hmh13DT9YPTiM2hpJFXmXZBLlxeqtpSrmenGItIZAJmQNKkyUdnGwZACJaXu7Cyp0ZCiD4AViO5t1RTSzg8RWsVEad5mCsDfafzJ1tYYMQZARpDyMiZB3FQ4R3V7gs2j7j0igZD",
"userId":"142758138512",
"href":"id/team",
"template":"This is app is awsome"
}

Related Facebook documentation:

https://developers.facebook.com/docs/graph-api/reference/user/notifications/#publish

Publishing photos

Allows the user to upload photos. This does not require init to be called before the operation. Refer to multipart processing for detailed information.

publishPhoto

<facebook.publishPhoto>
	<userId>{$url:user_id}</userId>
	<apiUrl>https://graph.facebook.com</apiUrl>
	<apiVersion>{$url:apiVersion}</apiVersion>
	<accessToken>{$url:accessToken}</accessToken>
	<caption>{$url:caption}</caption>
	<photoUrl>{$url:photoUrl}</photoUrl>
	<targetId>{$url:targetId}</targetId>
	<tags>{$url:tags}</tags>
	<place>{$url:place}</place>
	<isExplicitPlace>{$url:isExplicitPlace}</isExplicitPlace>
	<isExplicitLocation>{$url:isExplicitLocation}</isExplicitLocation>
	<ogActionTypeId>{$url:ogActionTypeId}</ogActionTypeId>
	<ogObjectId>{$url:ogObjectId}</ogObjectId>
   	<ogPhrase>{$url:ogPhrase}</ogPhrase>
	<ogIconId>{$url:ogIconId}</ogIconId>
	<ogSuggestionMechanism>{$url:ogSuggestionMechanism}</ogSuggestionMechanism>
	<privacy>{$url:privacy}</privacy>
	<targeting>{$url:targeting}</targeting>
	<feedTargeting>{$url:feedTargeting}</feedTargeting>
	<noStory>{$url:noStory}</noStory>
	<published>{$url:published}</published>
	<offlineId>{$url:offlineId}</offlineId>
	<backdatedTime>{$url:backdatedTime}</backdatedTime>
   	<backdatedTimeGranularity>{$url:backdatedTimeGranularity}</backdatedTimeGranularity>
	<fullResIsComingLater>{$url:fullResIsComingLater}</fullResIsComingLater>
	<scheduledPublishTime>{$url:scheduledPublishTime}</scheduledPublishTime>
	<manualPrivacy>{$url:manualPrivacy}</manualPrivacy>
	<audienceExp>{$url:audienceExp}</audienceExp>
	<applicationId>{$url:applicationId}</applicationId>
</facebook.publishPhoto>

Properties

userId:The id of the user.
apiUrl:The api url.
apiVersion:Version of Facebook API.
accessToken:accessToken.
caption:The description of the photo.
photoUrl:The URL of a photo that is already uploaded to the Internet.
targetId:User id to post the photo to an object that's not the user in the access token.
tags:Tags on this photo.
place:Page ID of a place associated with the photo.
isExplicitPlace:If set to true, the tag is a place, not a person.
isExplicitLocation:Is this an explicit location or not.
ogActionTypeId:The Open Graph action type.
ogObjectId:The Open Graph object ID.
ogPhrase:The Open Graph phrase.
ogIconId:The Open Graph icon.
ogSuggestionMechanism:The Open Graph suggestion.
privacy:Determines the privacy settings of the photo.
targeting:Allows you to target posts to specific audiences.
feedTargeting:Object that controls news feed targeting for this post.
noStory:If set to true, this will suppress feed and timeline story.
published:Set to false if you don't want the photo to be published immediately.
offlineId:Offline ID.
backdatedTime:A user-specified creation time for this photo.
backdatedTimeGranularity:Granularity. Default value: none.
fullResIsComingLater:Full res is coming later.
composerSessionId:Composer session ID.
scheduledPublishTime:Time at which an unpublished post should be published.
manualPrivacy:Manual privacy.
audienceExp:Audience exp.
applicationId:iTunes App ID.

Sample request

Refer to the multipart processing section.

Following is a sample REST request for the publishPhoto method.

Sample Request for publishPhoto

 curl -X POST \
     -d "source=%7Bimage-data%7D" \
         http://localhost:8280/services/facebook_publishPhoto?user_id={userId}

Related Facebook documentation:

https://developers.facebook.com/docs/graph-api/reference/user/photos/#publish

Sending app request

Contains the requests received by the user from the app making the API call.

sendAppRequest

<facebook.sendAppRequest>
	<message>{$url:message}</message>
	<idsInvitable>{$url:idsInvitable}</idsInvitable>
	<actionType>{$url:actionType}</actionType>
	<data>{$url:data}</data>
	<objectId>{$url:objectId}</objectId>
	<ref>{$url:ref}</ref>
	<from>{$url:from}</from>
</facebook.sendAppRequest>

Properties

message:The request message.
idsInvitable:Friend IDs.
actionType:Action Type.
data:Additional data a developer may pass for tracking.
objectId:Object ID.
ref:Reference.
from:From.

Sample request

Following is a sample REST request for the sendAppRequest method.

Sample Request for sendAppRequest

{
"apiUrl":"https://graph.facebook.com",
"apiVersion":"v2.4",
"accessToken":"CAAD8biEgxBIBAFppUAINka4ZCFYNaHLu5R7KHYeSfrwcQSpDLDoBUmsMEIkgjS2wuxGdCmYlD8LnlESKAlrskIibZBZBjEeyoEzRuF2cd3oSqoTSYKaju3jXyU4Q5HDhaJOFQMyxa39BaPm6G0MYXSWrVbOV8QyZAO5OfqyOWizQucIWHOe5K7JdXDZCWwh94e5RiteiSYAZDZD",
"userId":"100007674122684",
"message":"Test from soapui dulpe",
"data":""
}

Related Facebook documentation:

https://developers.facebook.com/docs/graph-api/reference/user/apprequests/#publish

Sample configuration

Following is a sample proxy service that illustrates how to connect to Facebook with the init operation and use the createUserAchievement operation to Users. The sample request for this proxy can be found in createUserAchievement sample request . You can use this sample as a template for using other operations in this category.

As a best practice, create a separate sequence for handling the response payload for errors. In the following sample, this sequence is "faultHandlerSeq".

createEvent

<proxy xmlns="http://ws.apache.org/ns/synapse"
       name="facebook_createPost"
	   transports="https,http"
	   statistics="disable"
	   trace="disable"
	   startOnLoad="true">
  <target>
    <inSequence onError="faultHandlerSeq">
      <property name="apiUrl"
				expression="json-eval($.apiUrl)"/>
	  <property name="apiVersion"
                   expression="json-eval($.apiVersion)"/>
      <property name="accessToken"
				expression="json-eval($.accessToken)"/>
      <property name="achievement"
				expression="json-eval($.achievement)"/>
	  <facebook.init>
            <apiUrl>{$ctx:apiUrl}</apiUrl>
			<apiVersion>{$url:apiVersion}</apiVersion>
            <accessToken>{$ctx:accessToken}</accessToken>
      </facebook.init>      
	  <facebook.createUserAchievement>
	     <achievement>{$ctx:achievement}</achievement>
      </facebook.createUserAchievement>
	  <respond/>
    </inSequence>
    <outSequence>
      <property name="messageType" value="application/json" scope="axis2" />
      <send/>
    </outSequence>
  </target>
</proxy>