This repo is a fork from main repo and will usually have new features bundled faster than main repo (and maybe bundle some bugs, too). See main repo here.

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 fb-chat-api, you should use this command:~~

~~It will download fb-chat-api from NPM~~

(Not available in NPM)

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 ntkhang03/fb-chat-api-temp

Note

Currently, this repo is not available on NPM. Please use the bleeding edge version.

Testing your bots

~~If you want to test your bots without creating another account on Facebook, you can use Facebook Whitehat Accounts.~~ (Facebook has removed this feature.)

Prepare to login using appstate (cookie)

Because of Facebook policy and the way Facebook check & secure accounts, you should not login using this library with username / password. We recommend using appstate / cookie to login more smoothly

These preparation is optional but highly recommend

Enable 2FA for your account - Very likely to reduce the random account check Prepare a HTTP Proxy with a static IP to avoid any unexpected account check and set it to this library using Enviroment
FB_PROXY=http://username:password@yourproxyip.com:proxyport

Manual method

Install this Chrome Extensions EditThisCookie to export cookie from Facebook. If you use proxy, you could use Proxy SwitchyOmega to point your browser to FB_PROXY.
Login normaly using Chrome to both site Facebook.com and Messenger.com, apply any 2FA step if needed.
Now use the Export Cookie from EditThisCookie to get the cookie (appstate) from both site (concat 2 JSON array into 1, with messenger cookie first) and save it to appstate.json.
Then you could login using appState like the example below.

Semi-auto method using Puppeteer

npm install ntkhang03/fb-chat-api
cd node_modules/fb-chat-api
npm install puppeteer --no-save
export PUPPETEER_EXECUTABLE_PATH=<your chrome exec path> 
node -e "require('./utils').getAppStateByPuppeteer()";

Example Usage

Note

Currently, login with credentials is not available. You need to create a file named appstate.json to save your login state. You can use c3c-fbstate to get fbstate.json (appstate.json)

const login = require("fb-chat-api-temp");

// Login using email/phone & password (Not recommended)
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);
    });
});


// Login using appState
login({appState: JSON.parse(fs.readFileSync('appstate.json', 'utf8'))}, (err, api) => {
    ...
});

Or use appstate.json to save your login state:

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

// Create simple echo bot
login({appState: JSON.parse(fs.readFileSync('appstate.json', 'utf8'))}, (err, api) => {
		if(err) return console.error(err);
		console.log("Logged in!");

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

Result:

Documentation

You can see it here.

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("fb-chat-api-temp");

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("fb-chat-api-temp");

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("fb-chat-api-temp");

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()));
});

Alternative: Use c3c-fbstate to get fbstate.json (appstate.json)

Listening to a chat

api.listenMqtt(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}).

Example

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

// Simple echo bot. It will repeat everything that you say.
// Will stop when you say '/stop'
login({appState: JSON.parse(fs.readFileSync('appstate.json', 'utf8'))}, (err, api) => {
    if(err) return console.error(err);

    api.setOptions({listenEvents: true});

    var stopListening = api.listenMqtt((err, event) => {
        if(err) return console.error(err);

        api.markAsRead(event.threadID, (err) => {
            if(err) console.error(err);
        });

        switch(event.type) {
            case "message":
                if(event.body === '/stop') {
                    api.sendMessage("Goodbye…", event.threadID);
                    return stopListening();
                }
                api.sendMessage("TEST BOT: " + event.body, event.threadID);
                break;
            case "event":
                console.log(event);
                break;
        }
    });
});

FAQS

How do I run tests?

For tests, create a test-config.json file that resembles example-config.json and put it in the test directory. From the root >directory, run npm test.

Why doesn't sendMessage always work when I'm logged in as a page?

Pages can't start conversations with users directly; this is to prevent pages from spamming users.

What do I do when login doesn't work?

First check that you can login to Facebook using the website. If login approvals are enabled, you might be logging in incorrectly. For how to handle login approvals, read our docs on login.

How can I avoid logging in every time? Can I log into a previous session?

We support caching everything relevant for you to bypass login. api.getAppState() returns an object that you can save and pass into login as {appState: mySavedAppState} instead of the credentials object. If this fails, your session has expired.

Do you support sending messages as a page?

Yes, set the pageID option on login (this doesn't work if you set it using api.setOptions, it affects the login process).
login(credentials, {pageID: "000000000000000"}, (err, api) => { … }

I'm getting some crazy weird syntax error like SyntaxError: Unexpected token [!!!

Please try to update your version of node.js before submitting an issue of this nature. We like to use new language features.

I don't want all of these logging messages!

You can use api.setOptions to silence the logging. You get the api object from login (see example above). Do
api.setOptions({
    logLevel: "silent"
});

Projects using this API:

c3c - A bot that can be customizable using plugins. Support Facebook & Discord.
GOAT BOT 🐐 - A bot chat Messenger can be customizable using scripts. Support .

Projects using this API (original repository, facebook-chat-api):

Messer - Command-line messaging for Facebook Messenger
messen - Rapidly build Facebook Messenger apps in Node.js
Concierge - Concierge is a highly modular, easily extensible general purpose chat bot with a built in package manager
Marc Zuckerbot - Facebook chat bot
Marc Thuckerbot - Programmable lisp bot
MarkovsInequality - Extensible chat bot adding useful functions to Facebook Messenger
AllanBot - Extensive module that combines the facebook api with firebase to create numerous functions; no coding experience is required to implement this.
Larry Pudding Dog Bot - A facebook bot you can easily customize the response
fbash - Run commands on your computer's terminal over Facebook Messenger
Klink - This Chrome extension will 1-click share the link of your active tab over Facebook Messenger
Botyo - Modular bot designed for group chat rooms on Facebook
matrix-puppet-facebook - A facebook bridge for matrix
facebot - A facebook bridge for Slack.
Botium - The Selenium for Chatbots
Messenger-CLI - A command-line interface for sending and receiving messages through Facebook Messenger.
AssumeZero-Bot – A highly customizable Facebook Messenger bot for group chats.
Miscord - An easy-to-use Facebook bridge for Discord.
chat-bridge - A Messenger, Telegram and IRC chat bridge.
messenger-auto-reply - An auto-reply service for Messenger.

royalgarter/fb-chat-api

Unofficial Facebook Chat API

Install

(Not available in NPM)

Bleeding edge

Note

Testing your bots

Prepare to login using appstate (cookie)

Manual method

Semi-auto method using Puppeteer

Example Usage

Note

Documentation

Main Functionality

Sending a message

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

Saving session.

Listening to a chat

api.listenMqtt(callback)

FAQS

Projects using this API:

Projects using this API (original repository, facebook-chat-api):