jersoncarin/facebook-message-api

Unofficial Facebook Chat API for user-account (not page).

Facebook Message API

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.

Install

Install using npm:

npm install facebook-message-api

Install using yarn:

yarn add facebook-message-api

Testing your bots

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

Authenticate

To authenticate your account you should create .env or export it on Environment variable Note: Please make sure that your .env is ignore on git to avoid stealing your credential or you can make your repo private.

# It can be username or email
[email protected]
PASSWORD=markzuckerbot

Example Usage

const command = require('facebook-message-api')

// Initialize the chat command first
// you may passed additional options, it can be accessed into command options from the callback
command.init({ prefix: '/' })

// You can add event middleware
// Note that this will be served as global event middleware
const eventMiddleware1 = (next) => {
  return async (event, api, options) => {
    // Handle before the event is resolved
    await next(event, api, options)
    // Or handle after event has been resolved
  }
}

const eventMiddleware2 = (next) => {
  return async (event, api, options) => {
    // Handle before the event is resolved
    await next(event, api, options)
    // Or handle after event has been resolved
  }
}

command.addEventMiddleware(eventMiddleware1, eventMiddleware2)

// Also you may listen the event using on function
// Listen all incoming events using wildcards
command.on('*', (event, api, options) => {
  // handle all event here
})

// Also you can specify what event to listen, you may use | to listen multiple events
command.on('message|message_unsend', (matches, event, api, options) => {
  // handle message and message_unsend event
})

// You can also listen initialized events
command.on('init', (api, options) => {
  // handle init event here
})

// You can also listen before the scripts restarted
// Why scripts should restart ? because we need to make new facebook home request inorder to get new session token, this will prevent from login state expiration.
command.on('restarting', (api, options) => {
  // handle before the script will be restarted
})

// Adding commands makes easy using chaining method.
command
  .add(async function (match, event, api) {
    // Handle inspire command here
    console.log(match) // { category: 'value here' }
  })
  .addName('inspire')
  .addDescription('Generate motivational quotes.')
  .addAlias('ins')
  .addUsage('/inspire')
  .addPattern('^(.*)$', ['category'])

// Adding global command middleware
const commandMiddleware1 = (next) => {
  return async (match, event, api, options) => {
    // Handle before the command is resolved
    await next(match, event, api, options)
    // Or handle after command has been resolved
  }
}

const commandMiddleware2 = (next) => {
  return async (match, event, api, options) => {
    // Handle before the command is resolved
    await next(match, event, api, options)
    // Or handle after command has been resolved
  }
}
command.addCommandMiddleware(commandMiddleware1, commandMiddleware2)

Command Methods

• command.add(func)
• command.add(func).addName(name)
• command.add(func).addDescription(description)
• command.add(func).addAlias(alias)
• command.add(func).addUsage(usage)
• command.add(func).addOption(option)
• command.add(func).addMiddleware(...middleware)
• command.add(func).addPattern(regexPattern,?matches)
• command.add(func).withPrefix(prefix)
• command.add(func).pipe(func)

Command API's

---

command.add([, callback])

Add command

Arguments

• callback: A callback function, required.

---

command.add([, callback]).addName(string name)

Add command name

Arguments

• name: A command name, required.

---

command.add([, callback]).addDescription(string description)

Add command Description

Arguments

• description: A command description, optional.

---

command.add([, callback]).addAlias(string alias)

Add command alias

Arguments

• alias: A command alias, optional.

---

command.add([, callback]).addUsage(string usage)

Add command help usage

Arguments

• usage: A command usage, optional.

---

command.add([, callback]).addOption({...option})

Add command option

Arguments

• option: A command option, you may pass object, optional.

---

command.add([, callback]).addMiddleware(...middleware)

Add command middleware

Arguments

• middleware: A command middleware, you may pass args as many as you want, optional.

---

command.add([, callback]).addPattern(regexPattern, matches)

Add command pattern to match the arguments of the command

Arguments

• pattern: You may pass regex pattern that matches the arguments of the command, required.
• matches: You can also pass matches here, example if you passed the first matches with search name, then in the command callback you can get match.search, instead of match[1]

---

command.add([, callback]).withPrefix(string prefix)

Add command prefix

Arguments

• prefix: A command prefix, It will be fallback to global prefix if this not defined, optional.

---

command.add([, callback]).pipe([, callback])

Pipe the command instance into callback function so you can extend functionalities and other stuff

Arguments

• callback: A pipe callback which has arguments of instance of the Command class, required.

---

Facebook APIs

• api.addUserToGroup
• api.changeAdminStatus
• api.changeArchivedStatus
• api.changeBlockedStatus
• api.changeGroupImage
• api.changeNickname
• api.changeThreadColor
• api.changeThreadEmoji
• api.createNewGroup
• api.createPoll
• api.deleteMessage
• api.deleteThread
• api.forwardAttachment
• api.getAppState
• api.getCurrentUserID
• api.getEmojiUrl
• api.getFriendsList
• api.getThreadHistory
• api.getThreadInfo
• api.getThreadList
• api.getThreadPictures
• api.getUserID
• api.getUserInfo
• api.handleMessageRequest
• api.listen
• api.logout
• api.markAsDelivered
• api.markAsRead
• api.markAsReadAll
• api.markAsSeen
• api.muteThread
• api.removeUserFromGroup
• api.resolvePhotoUrl
• api.searchForThread
• api.sendMessage
• api.sendTypingIndicator
• api.setMessageReaction
• api.setOptions
• api.setTitle
• api.threadColors
• api.unsendMessage

---

Documentation for Facebook API'S

See this from facebook-chat-api

Credits

facebook-chat-api contributors puppeteer

LICENSE

The MIT License (MIT)

Copyright (c) 2015 Avery, Benjamin, David, Maude
Copyright (c) 2022 Jerson Carin

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.