Note: This repo is in maintenance mode. Bug fixes will be happily merged if they are submitted in simple or well-explained PRs (thank you to all the contributors over the years!), but new features will usually not be merged (because all features eventually break and increase the maintenance cost). I don't have enough time to better support this project and believe the approach is ok for one-off scripts or fun projects but fundamentally too unstable for any serious application. Any change by Facebook can break the api overnight and that's assuming the api can remain compliant enough not to get blocked. Unfortunately we will need to wait and hope that they decide to build a powerful enough bot system to support all these usecases.

Unofficial Facebook Chat API

Facebook now has an official API for chat bots here.

This API is the only way to automate chat functionalities on a user account. We do this by emulating the browser. This means doing the exact same GET/POST requests and tricking Facebook into thinking we're accessing the website normally. Because we're doing it this way, this API won't work with an auth token but requires the credentials of a Facebook account.

Disclaimer: We are not responsible if your account gets banned for spammy activities such as sending lots of messages to people you don't know, sending messages very quickly, sending spammy looking URLs, logging in and out very quickly... Be responsible Facebook citizens.

See below for projects using this API.

See the full changelog for release details.

Install

If you just want to use facebook-chat-api, you should use this command:

npm install facebook-chat-api

It will download facebook-chat-api from NPM repositories

Bleeding edge

If you want to use bleeding edge (directly from github) to test new features or submit bug report, this is the command for you:

npm install Schmavery/facebook-chat-api

Testing your bots

If you want to test your bots without creating another account on Facebook, you can use Facebook Whitehat Accounts.

Example Usage

const login = require("facebook-chat-api");

// Create simple echo bot
login({email: "FB_EMAIL", password: "FB_PASSWORD"}, (err, api) => {
    if(err) return console.error(err);

    api.listen((err, message) => {
        api.sendMessage(message.body, message.threadID);
    });
});

Result:

Documentation

Main Functionality

Sending a message

api.sendMessage(message, threadID[, callback][, messageID])

Various types of message can be sent:

Regular: set field body to the desired message as a string.
Sticker: set a field sticker to the desired sticker ID.
File or image: Set field attachment to a readable stream or an array of readable streams.
URL: set a field url to the desired URL.
Emoji: set field emoji to the desired emoji as a string and set field emojiSize with size of the emoji (small, medium, large)

Note that a message can only be a regular message (which can be empty) and optionally one of the following: a sticker, an attachment or a url.

Tip: to find your own ID, you can look inside the cookies. The userID is under the name c_user.

Example (Basic Message)

const login = require("facebook-chat-api");

login({email: "FB_EMAIL", password: "FB_PASSWORD"}, (err, api) => {
    if(err) return console.error(err);

    var yourID = "000000000000000";
    var msg = "Hey!";
    api.sendMessage(msg, yourID);
});

Example (File upload)

const login = require("facebook-chat-api");

login({email: "FB_EMAIL", password: "FB_PASSWORD"}, (err, api) => {
    if(err) return console.error(err);

    // Note this example uploads an image called image.jpg
    var yourID = "000000000000000";
    var msg = {
        body: "Hey!",
        attachment: fs.createReadStream(__dirname + '/image.jpg')
    }
    api.sendMessage(msg, yourID);
});

Saving session.

To avoid logging in every time you should save AppState (cookies etc.) to a file, then you can use it without having password in your scripts.

Example

const fs = require("fs");
const login = require("facebook-chat-api");

var credentials = {email: "FB_EMAIL", password: "FB_PASSWORD"};

login(credentials, (err, api) => {
    if(err) return console.error(err);

    fs.writeFileSync('appstate.json', JSON.stringify(api.getAppState()));
});

Listening to a chat

api.listen(callback)

Listen watches for messages sent in a chat. By default this won't receive events (joining/leaving a chat, title change etc…) but it can be activated with api.setOptions({listenEvents: true}). This will by default ignore messages sent by the current account, you can enable listening to your own messages with api.setOptions({selfListen: true}).