Facebook Chat API

Shameless Plug: Browse anonymously to protect your browsing habits from data tracking sites with a VPN Service.

Update: It’s been quite a while since I wrote this post and I don’t think the code below even works anymore because I haven’t kept up with Facebook’s API changes. So I’ve put the code up on github so anyone can fork it and make fixes if they like.

Update: Simon just mentioned that when using facebook’s new profile layouts this code will break. You can find the fix in his comment. Also note, as he says, you only need this fix if you’ve changed to facebook’s new profile layouts.

Update: Ryan just notified me that facebook has made a change and you must now pass force_render=1 to presence/update.php to retrieve the buddy list. I’ve updated the example client below.

Update: Turns out Adium utilized my post in adding Facebook chat to their client, cool!

Update: Facebook recently made a breaking change to their API to require post_form_id to be passed to presence/update.php. I’m assuming they did this to prevent CSRF attacks against it. I’ve updated the client code below to reflect these changes.

Facebook Chat was released recently and I was interested in looking under the hood at how its protocol works. It turned out to be simpler than I expected…

Receiving Messages

Facebook uses a Comet and JSON approach to receive incoming messages. Comet is a technique where you open a long running HTTP connection to a server (usually AJAX). The connection stays open until the server has something to tell you at which point it sends the data through the connection and the connection can be closed (or in some cases remain open). JSON is just a way of representing data in Javascript. Let’s look at how it works.

A connection is opened to: http://%5BANYTHING%5D.channel%5BNUM%5D.facebook.com/x/%5BANYTHING%5D/false/p_%5BUID%5D=%5BSEQ%5D. First let’s look at the url and what the different placeholders represent.

ANYTHING can be anything, Facebook has setup *.channel[NUM].facebook.com as a catch-all subdomain. So no matter what you put there it will resolve to the same IP. The ANYTHING in the path can also be anything. I assume both the ANYTHING values are used to prevent the browser from caching these requests.

NUM represents the channel number you are using. It appears there are 20 channels (01-20), as that range of subdomains resolve and the rest don’t. I am assuming that a “channel” is just one of Facebook’s comet interface servers. Every time you log in you are assigned to a specific channel and it doesn’t change throughout your session. It may also be fixed per user, I’m not sure about this though.

UID is just your user id. SEQ is the sequence number you are requesting from the server. If you give an out of range seq number the server will tell you what the latest seq number is so that you can request it. If you give an old seq number the server will show you the (old) messages that correspond with that number. Requesting http://0.channel06.facebook.com/x/0/false/p_MYID=-1 will immediately respond telling me I should re-request with a seq number of 0 (or whatever my current seq number is) since the seq number -1 is never valid.

// request http://0.channel06.facebook.com/x/0/false/p_MYID=-1
for (;;);{"t":"refresh", "seq":0}

After we build the correct URL and make the connection, it will just “sit there”. This is how Comet connections work. The connection will remain inactive in a “requesting” state until someone sends us a message. If a message is not received in less than a minute (approx 55 seconds) Facebook will close the connection and instruct you to reopen it. I assume they do this to get around browser timeout issues. If a message is received you will get the message data through the connection which is then closed. After a message is received the seq number should be incremented for the next request. After either a message is received or the connection times out a new connection will immediately be established.

// request http://0.channel06.facebook.com/x/0/false/p_MYID=0 times out
for (;;);{"t":"continue"}
// request http://0.channel06.facebook.com/x/0/false/p_MYID=0 receives a message!
for (;;);{"t":"msg","c":"p_MYID","ms":[{"type":"msg","msg":{"text":"yo","time":1209557234412,"clientTime":1209557232415,"msgID":"4177168544"},"from":FRIENDSID,"to":MYID,"from_name":"Myfriends Name","to_name":"My name","from_first_name":"Myfriends","to_first_name":"My"}]}
// request http://0.channel06.facebook.com/x/0/false/p_MYID=1 for the next message

Sending Messages

Sending messages is a lot simpler. All you need to do is make a POST request to http://www.facebook.com/ajax/chat/send.php with a few simple values: msg_text with the text of the message, to with the uid of the recipient, msg_id with a random unique number id for the message, client_time with the current time in microseconds, and post_form_id which can be found as a hidden form value on any facebook page. Facebook will respond with some JSON indicating there was no error and the message will be sent!

// POST request to: http://www.facebook.com/ajax/chat/send.php?msg_text=hey&msg_id=1234567890&to=FRIENDSID&client_time=1209558664256&post_form_id=297fdbad61d3b1d88f0c311cda25bbbc
for (;;);{"error":0,"errorSummary":"","errorDescription":"No error.","payload":[]}

Buddy List
The list of your friends who are online is polled about every 3 minutes with a POST request to http://www.facebook.com/ajax/presence/update.php. The ‘userInfos’ hash contains the actual buddy list. Some extra info is provided to let you know how the buddy list has changed since the last request.

// POST request to http://www.facebook.com/ajax/presence/update.php?buddy_list=1
for (;;);{"error":0,"errorSummary":"","errorDescription":"No error.","payload":{"buddy_list":{"listChanged":true,"availableCount":1,"nowAvailableList":{"UID1":{"i":false}},"wasAvailableIDs":[],"userInfos":{"UID1":{"name":"Buddy 1","firstName":"Buddy","thumbSrc":"http:\/\/static.ak.fbcdn.net\/pics\/q_default.gif","status":null,"statusTime":0,"statusTimeRel":""},"UID2":{"name":"Buddi 2","firstName":"Buddi","thumbSrc":"http:\/\/static.ak.fbcdn.net\/pics\/q_default.gif","status":null,"statusTime":0,"statusTimeRel":""}},"forcedRender":true},"time":1209560380000}}

Notifications

Notifications are polled through the same mechanism as the buddy list. You need to pass &notifications=1 to update.php to receive info about them. Other than that I won’t be covering them here.

The Fun Part
So here’s a very simple implementation of a Facebook Chat client written in Ruby. It will require you have the json and mechanize gems installed.

require 'rubygems'
require 'mechanize'
require 'json'
require 'ostruct'
require 'pp'

class FacebookChat
  def initialize(email, pass); @email, @pass = email, pass; end

  def login
    @agent = WWW::Mechanize.new
    @agent.user_agent_alias = 'Windows IE 7'
    f = @agent.get("http://facebook.com/login.php").forms.first
    f.fields.name("email").value = @email
    f.fields.name("pass").value = @pass
    f.submit
    body = @agent.get("http://www.facebook.com/home.php").body

    # parse info out of facebook home page
    @uid = %r{<a href=".+?/profile.php\?id=(\d+)" class="profile_nav_link">Profile</a>}.match(body)[1].to_i
    @channel = %r{"channel(\d+)"}.match(body)[1]
    @post_form_id = %r{<input type="hidden" id="post_form_id" name="post_form_id" value="([^"]+)}.match(body)[1]
  end

  def wait_for_messages
    determine_initial_seq_number  unless @seq
   
    begin
      json = parse_json @agent.get(get_message_url(@seq)).body
    end  while json["t"] == "continue"   # no messages yet, keep waiting
    @seq += 1

    json["ms"].select{|m| m['type'] == 'msg'}.map do |msg|
      info = msg.delete 'msg'
      msg['text'] = info['text']
      msg['time'] = Time.at(info['time']/1000)
      OpenStruct.new msg
    end.reject {|msg| msg.from == @uid }  # get rid of messages from us
  end

  def send_message(uid, text)
    r = @agent.post "http://www.facebook.com/ajax/chat/send.php", 
      'msg_text' => text, 
      'msg_id' => rand(999999999),
      'client_time' => (Time.now.to_f*1000).to_i,
      'to' => uid,
      'post_form_id' => @post_form_id
  end

  def buddy_list
    json = parse_json(@agent.post("http://www.facebook.com/ajax/presence/update.php", 
                        'buddy_list' => 1, 'force_render' => 1, 'post_form_id' => @post_form_id, 'user' => @uid).body)
    json['payload']['buddy_list']['userInfos'].inject({}) do |hash, (uid, info)|
      hash.merge uid => info['name']
    end
  end

  private

  def determine_initial_seq_number
    # -1 will always be a bad seq number so fb will tell us what the correct one is
    json = parse_json @agent.get(get_message_url(-1)).body
    @seq = json["seq"].to_i
  end

  def get_message_url(seq)
    "http://0.channel#{@channel}.facebook.com/x/0/false/p_#{@uid}=#{seq}"
  end
  
  # get rid of initial js junk, like 'for(;;);'
  def parse_json(s)
    JSON.parse s.sub(/^[^{]+/, '')
  end
end

if __FILE__ == $0
  fb = FacebookChat.new(ARGV.shift, ARGV.shift)
  fb.login

  puts "Buddy List:"
  pp fb.buddy_list

  Thread.abort_on_exception = true
  Thread.new do
    puts usage = "Enter message as <facebook_id> <message> (eg: 124423 hey man wassup?) or type 'buddy' for buddy list"
    loop do
      case gets.strip
      when 'buddy' then pp fb.buddy_list
      when /^(\d+) (.+)$/
        uid, text = $1.to_i, $2
        fb.send_message(uid, text)
      else
        puts usage
      end
    end
  end

  # message receiving loop
  loop do
    fb.wait_for_messages.each do |msg|
      puts "[#{msg.time.strftime('%H:%M')}] #{msg.from_name} (#{msg.from}): #{msg.text}"
    end
  end
end

Run with: ruby chat.rb [email] [password]