Skip to content


Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
A full-stack Facebook Graph API wrapper in Ruby.

allow specifying API version, mainly for Marketing APIs

NOTE: this gem no longer officially support v2.0+, it doesn't stop trying you to use edge versions though.

ref #390
latest commit e2dc6370f6
Nov Matake authored



A full-stack Facebook Graph API wrapper in Ruby.


gem install fb_graph


Graph API v2.0

FbGraph is basically developed for v1.0, and could be buggy for v2.0.

Along with adding v2 support to this gem, I also started to develop fb_graph2 as Graph API v2.0 client library.


Now FbGraph supports all objects listed here: Almost all connections for each object are also supported. (“attachments” and “shares” connections of message object are not supported yet)

You can also play with a Rails sample app here.

See GitHub wiki for more examples.


Basic Objects

user =

user = FbGraph::User.fetch('matake')    # => 'Nov Matake'
user.picture # => ''

# fb_graph doesn't access to Graph API until you call "fetch"
user ='matake', :access_token => YOUR_ACCESS_TOKEN)
user.identifier # => "matake" # => nil # => nil
user = user.fetch # => "Nov Matake"
user.description # => ""

page = FbGraph::Page.fetch('smartfmteam')     # => ''
page.picture  # => ''



# Public connections
user = FbGraph::User.fetch('matake')

# Private connections requires "access_token"'matake').friends # => raise FbGraph::Unauthorized
user = FbGraph::User.fetch('matake', :access_token => ACCESS_TOKEN)

# "home" connection is only available for "me"
me ='me', :access_token => ACCESS_TOKEN)

By default, FbGraph will only return the default fields. In order to get a non-default field, you have to supply the connect with an optional hash specifying the field. An example for events:{:fields => "owner,name,description,picture"}) # { and } optional

An overview of which fields you can include in the graph API can be found at, which has a description of the specific objects fields in the sidebar under “Objects”.


# all objects"FbGraph") # => Array of Hash

# specify type"FbGraph") # => Array of FbGraph::Page"matake", :access_token => ACCESS_TOKEN) # => Array of FbGraph::User


# collection
user ='matake', :access_token => ACCESS_TOKEN)
likes = user.likes # => Array of FbGraph::Like         # => Array of FbGraph::Like (next page)
likes.previous     # => Array of FbGraph::Like (previous page)     # => Hash for pagination options (ex. {"limit"=>"25", "until"=>"2010-08-08T03:17:21+0000"})
likes.collection.previous # => Hash for pagination options (ex. {"limit"=>"25", "since"=>"2010-08-08T06:28:20+0000"})
user.likes(     # => same with
user.likes(likes.collection.previous) # => same with likes.previous

# search results
results ="FbGraph") # => Array of FbGraph::Page     # => Array of FbGraph::Page (next page)
results.previous # => Array of FbGraph::Page (next page)
results.klass    # => FbGraph::Page     # => Hash for pagination options (ex. {"limit"=>"25", "until"=>"2010-08-08T03:17:21+0000"})
results.collection.previous # => Hash for pagination options (ex. {"limit"=>"25", "since"=>"2010-08-08T06:28:20+0000"}),     # => same with, results.collection.previous) # => same with results.previous


Update status (wall post)

me =
  :message => 'Updating via FbGraph',
  :picture => '',
  :link => '',
  :name => 'FbGraph',
  :description => 'A Ruby wrapper for Facebook Graph API'

Post a like/comment to a post

post =
bool =!(
  :access_token => ACCESS_TOKEN
comment = post.comment!(
  :access_token => ACCESS_TOKEN,
  :message => 'Hey, I\'m testing you!'

Post a note

page =
note = page.note!(
  :access_token => ACCESS_TOKEN,
  :subject => 'testing',
  :message => 'Hey, I\'m testing you!'

Post a link

me =
link =!(
  :link => '',
  :message => 'A Ruby wrapper for Facebook Graph API.'

Create Event, respond to it

me =
event = me.event!(
  :name => 'FbGraph test event',
  :start_time => 1.week.from_now,
  :end_time => 2.week.from_now
bool = event.attending!(
  :access_token => ACCESS_TOKEN
bool = event.maybe!(
  :access_token => ACCESS_TOKEN
bool = event.declined!(
  :access_token => ACCESS_TOKEN

Create an album

me =
album = me.album!(
  :name => 'FbGraph test',
  :message => 'test test test'
) # => now facebook Graph API returns weird response for this call

Upload a photo to an album

me =
album = me.albums.first!(
  :access_token => ACCESS_TOKEN,
  :source =>'/Users/nov/Desktop/nov.gif', 'rb'), # 'rb' is needed only on windows
  :message => 'Hello, where is photo?'


Delete an object

post =
bool =!(
  :access_token => ACCESS_TOKEN
comment = post.comment!(
  :access_token => ACCESS_TOKEN,
  :message => 'Hey, I\'m testing you!'
comment.destroy(:access_token => ACCESS_TOKEN)
post.unlike!(:access_token => ACCESS_TOKEN)
post.destroy(:access_token => ACCESS_TOKEN)


Both Facebook JavaScript SDK and normal OAuth2 flow are supported. Below I show simple sample code. You can also see for more details Rails3 sample application.

In addition, if you are migrating an application that uses old-style session keys you can exchange the keys for access tokens. See more here:

JavaScript SDK

fb_auth.client # => Rack::OAuth2::Client

# get Facebook's auth cookie in advance using their JS SDK
fb_auth.access_token # => Rack::OAuth2::AccessToken
fb_auth.user         # => FbGraph::User (only basic attributes)
fb_auth.user.fetch   # => fetch more details

Normal OAuth2 Flow

# setup client
client = fb_auth.client
client.redirect_uri = ""

# redirect user to facebook
redirect_to client.authorization_uri(
  :scope => [:email, :read_stream, :offline_access]

# in callback
client.authorization_code = params[:code]
access_token = client.access_token! :client_auth_body # => Rack::OAuth2::AccessToken # => FbGraph::User

Extend Access Token Lifetime

# setup client
fb_auth.exchange_token! 'short-life-access-token'
fb_auth.access_token # => Rack::OAuth2::AccessToken


app =, :secret => YOUR_APPLICATION_SECRET)
app.insights # => Array of FbGraph::Insight

Test User

Not tested well yet. Sample is here.


Not tested well yet. Sample is here.

More Examples?

See GitHub wiki for more examples.

Note on Patches/Pull Requests

  • Fork the project.

  • Make your feature addition or bug fix.

  • Add tests for it. This is important so I don't break it in a future version unintentionally.

  • Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)

  • Send me a pull request. Bonus points for topic branches.


Copyright © 2010 nov matake. See LICENSE for details.

Something went wrong with that request. Please try again.