{"id":28452619,"url":"https://github.com/livehelperchat/fbmessenger","last_synced_at":"2025-07-06T12:32:30.738Z","repository":{"id":21328777,"uuid":"92342273","full_name":"LiveHelperChat/fbmessenger","owner":"LiveHelperChat","description":"Integration with Facebook messenger API. You will be able to chat with Facebook page users directly in lhc back office.","archived":false,"fork":false,"pushed_at":"2025-06-19T08:57:19.000Z","size":1228,"stargazers_count":29,"open_issues_count":0,"forks_count":22,"subscribers_count":14,"default_branch":"master","last_synced_at":"2025-07-03T10:23:15.784Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/LiveHelperChat.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":".github/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":["livehelperchat"]}},"created_at":"2017-05-24T22:34:36.000Z","updated_at":"2025-06-19T08:57:22.000Z","dependencies_parsed_at":"2025-04-19T05:28:36.195Z","dependency_job_id":"b78a33b0-7ec8-4355-931d-63f7895cab2b","html_url":"https://github.com/LiveHelperChat/fbmessenger","commit_stats":{"total_commits":144,"total_committers":6,"mean_commits":24.0,"dds":0.05555555555555558,"last_synced_commit":"fc1449ae5fe448cc7cca93abaa8f19fd9c37b53a"},"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/LiveHelperChat/fbmessenger","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LiveHelperChat%2Ffbmessenger","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LiveHelperChat%2Ffbmessenger/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LiveHelperChat%2Ffbmessenger/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LiveHelperChat%2Ffbmessenger/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/LiveHelperChat","download_url":"https://codeload.github.com/LiveHelperChat/fbmessenger/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LiveHelperChat%2Ffbmessenger/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263900893,"owners_count":23527337,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-06-06T18:12:05.537Z","updated_at":"2025-07-06T12:32:30.726Z","avatar_url":"https://github.com/LiveHelperChat.png","language":"PHP","funding_links":["https://github.com/sponsors/livehelperchat"],"categories":[],"sub_categories":[],"readme":"# Features\n\n* Instagram\n* WhatsApp\n* Facebook Messenger\n* Message delivery status indication\n* Reactions\n* Bot support\n\n# Demo\n\nJust ask anything on our [Facebook page](https://www.facebook.com/LiveHelperChat/) ask messenger :)\n\n# Requirements\n\n * Min 4.46 Live Helper Chat version. 1.8v\n * Webhooks has to be enabled - https://github.com/LiveHelperChat/livehelperchat/blob/master/lhc_web/settings/settings.ini.default.php#L86\n\nChanges\n\n* All messenger workflow will be handled by lhc core, so less bugs.\n* Instagram support added\n* Required scopes are defined in the settings file.\n\nTo manage instagram and whatsapp they both has to be matched to you page\n\n# Permissions we request from facebook during login\n\nDefault scopes. You can change those in settings/settings.ini.php file\n\n```\n'email','pages_show_list','pages_messaging','instagram_manage_messages',\n'instagram_basic','pages_manage_metadata','pages_read_engagement',\n'whatsapp_business_management','whatsapp_business_messaging','business_management'\n```\n\n# Webhook configuration and subscription fields\n\nWebhooks configuration place\n\n![See image](https://raw.githubusercontent.com/LiveHelperChat/fbmessenger/master/doc/webhooks-app.png)\n\nProducts you should have\n\n![See image](https://raw.githubusercontent.com/LiveHelperChat/fbmessenger/master/doc/products-app.png)\n\n\n### Facebook messenger\n\nIn webhooks page you have to choose `Page` and subscribe to those fields\n\nSubscribed fields - `message_deliveries,message_echoes,message_edits,message_reactions,message_reads,messages,messaging_postbacks`\n\n* Messages `new` - supported and working\n* Messages `unsend` - not supported by webhooks. Meta limitation.\n* Messages `reply` - supported and working.\n* Messages `edits` - are not sent by webhooks. Meta limitation. Perhaps I'm missing something there, because there is a webhook subscription, but it does not send anything.\n\n### Instagram\n\nIn webhooks page you have to choose `Instagram` and subscribe to those fields\n\nSubscribed fields - `messages,messages,messaging_postbacks,messaging_seen`\n\n* Messages `new` - supported and working.\n* Messages `edits` - are not sent by webhooks. Meta limitation.\n* Messages `unsend` - supported and fully working.\n* Messages `repy` - supported and fully working.\n\n### WhatsApp\n\nIn webhooks page you have to choose `Whatsapp Business Account` and subscribe to those fields\n\nSubscribed fields - `messages`\n\n* Messages `new` - supported and working.\n* Messages `unsend` - not supported by WhatsApp. Meta limitation.\n* Messages `reply` - supported and working.\n* Messages `edits` - not supported by WhatsApp. Meta limitation.\n\n## Most common URL\n\n### URL if you are using Facebook Login flow WITHOUT automated hosting environment\n\nThis is the most common installation method and you choose what page you managed during login flow.\n\nWebhook URL's. Use same URL for webhook verification calls.\n\n* Facebook Messenger - `https://example.com/fbmessenger/callbackgeneral`\n* WhatsApp - `https://example.com/fbmessenger/callbackwhatsapp`\n* Instagram - `https://example.com/fbmessenger/callbackinstagram`\n\nValid OAuth Redirect URIs\n\n* `https://example.com/site_admin/fbmessenger/fbcallback`\n\nQuick settings\n\n * `app_id` https://github.com/LiveHelperChat/fbmessenger/blob/master/settings/settings.ini.default.php#L29 | App ID\n * `app_secret` https://github.com/LiveHelperChat/fbmessenger/blob/master/settings/settings.ini.default.php#L29 | App Secret\n * `verify_token` you have to put in https://github.com/LiveHelperChat/fbmessenger/blob/master/settings/settings.ini.default.php#L31 file. | Facebook Messenger\n * `whatsapp_verify_token` https://github.com/LiveHelperChat/fbmessenger/blob/master/settings/settings.ini.default.php#L32C10-L32C31 file. | WhatsApp\n * `instagram_verify_token` https://github.com/LiveHelperChat/fbmessenger/blob/master/settings/settings.ini.default.php#L33 file. | Instagram\n\n### Webhook URL for facebook messenger if you define independent page\n\nYou create a facebook app and add pages manually to lhc back office without login flow.\n\n* Facebook Messenger - `https://example.com/fbmessenger/callback/\u003cpage_id\u003e`\n* Verify token you enter manually in back office in that case\n* You can register manually multiple pages and just keep the same webhook. https://www.youtube.com/watch?v=nIExwuWeb3E (You still most likely will have callback URL like `https://example.com/fbmessenger/callback/1`, but it will work for consecutive pages also.)\n\n### URL if you are using Facebook Login flow WITH automated hosting environment\n\nValid OAuth Redirect URIs. `master.example.com` in this scenario is our manager address\n\n* `https://master.example.com/site_admin/fbmessenger/fbcallbackstandalone`\n\nWebhook URL's. Use same URL for webhook verification calls.\n\n * Facebook Messenger - `https://master.example.com/fbmessenger/callbackstandalone`\n * WhatsApp - `https://master.example.com/fbmessenger/callbackstandalonewhatsapp`\n * Instagram - `https://master.example.com/fbmessenger/callbackstandaloneinstagram`\n\nQuick settings\n\n* `app_id` https://github.com/LiveHelperChat/fbmessenger/blob/master/settings/settings.ini.default.php#L29 | App ID\n* `app_secret` https://github.com/LiveHelperChat/fbmessenger/blob/master/settings/settings.ini.default.php#L29 | App Secret\n* `verify_token` you have to put in https://github.com/LiveHelperChat/fbmessenger/blob/master/settings/settings.ini.default.php#L31 file. | Facebook Messenger\n* `whatsapp_verify_token` https://github.com/LiveHelperChat/fbmessenger/blob/master/settings/settings.ini.default.php#L32C10-L32C31 file. | WhatsApp\n* `instagram_verify_token` https://github.com/LiveHelperChat/fbmessenger/blob/master/settings/settings.ini.default.php#L33 file. | Instagram\n* Put any random string there https://github.com/LiveHelperChat/fbmessenger/blob/master/settings/settings.ini.default.php#L25\n* Set `enabled` to true https://github.com/LiveHelperChat/fbmessenger/blob/master/settings/settings.ini.default.php#L24 file.\n\n# Facebook messenger extension\nIntegration with Facebook messenger API. You will be able to chat with Facebook page users directly in lhc back office.\n * Bot support. [New] https://www.youtube.com/watch?v=_rLPJAdn4Us Supported bot elements\n    * Text messages including Quick Replies - `Send Text`\n    * Typing - `Send typing`\n    * Carrousel - `Send Carrousel`\n    * Buttons - `Button list`\n    * All other triggers including internal operations also will work.\n    * To listed for \"Get Started\" button action just listen for text message with content \"GET_STARTED\" also see demo bot in official demo.\n * Support multiple pages without creating new app for each page.\n * Supports multiple pages at once.\n * Each page chat can be assigned to custom department.\n\n# Update instructions\n\n* Make sure you have most recent Live Helper Chat version.\n* Update database via `php cron.php -s site_admin -e fbmessenger -c cron/update_structure` command\n* `Modules -\u003e Facebook chat -\u003e Save and Activate WhatsApp` configuration. Click it if you are using WhatsApp integration.\n\n# Installation in your LHC server\n* Upload the files to your `lhc_web/extension/fbmessenger` folder\n* Install database either by executing `doc/install.sql` file or executing this command `php cron.php -s site_admin -e fbmessenger -c cron/update_structure`\n* Install dependencies using composer\n    * Make sure your composer.json file looks like https://github.com/LiveHelperChat/livehelperchat/blob/master/lhc_web/composer.json 4.41v\n    * Just for newbies if your web hosting does not have composer see https://www.vultr.com/docs/install-composer-on-centos-7\n    * don't run composer as root, login in your ssh as your hosting normal user.\n* Activate extension in main settings file `lhc_web/settings/settings.ini.php` extension section `fbmessenger` by Adding lines: \n```\n'extensions' =\u003e  array (  'fbmessenger',  ),\n```\n* If you don't see this in Module, check your `lhc_web/settings/settings.ini.php` and also click `Clean Cache` from back office\n* copy `extension/fbmessenger/settings/settings.ini.default.php` to `extension/fbmessenger/settings/settings.ini.php`\n\n# WhatsApp configuration WITHOUT facebook login\n\nNotice - WhatsApp campaigns etc are supported only for statically defined WhatsApp accounts. Login based WhatsApp phone numbers for campaigns will be added later.\n\nWebhook URL you will find once you click `Save and Activate WhatsApp configuration` it will be in a field `Callback URL for Facebook WhatsApp integration`.\n\nThis configuration option is available with [Permanent Access Token](https://developers.facebook.com/docs/whatsapp/business-management-api/get-started#1--acquire-an-).\nIn facebook Extension settings you have to enter\n* Permanent WhatsApp access token -  [Permanent Access Token](https://developers.facebook.com/docs/whatsapp/business-management-api/get-started#1--acquire-an-).\n* WhatsApp Business Account ID - You will find it in `WhatsApp-\u003e Getting` Started section of the facebook app\n* WhatsApp `Verify Token` - just put any random string.\n* Click `Save and Activate WhatsApp configuration` it will install and configure all the required webhooks etc.\n* Go to Facebook App `WhatsApp-\u003e Configuration` section and set Callback URL while entering `Verify Token` you have put in settings page.\n* Subscribe to messages field.\n* Bot sample what is supported can be found [here](https://raw.githubusercontent.com/LiveHelperChat/fbmessenger/master/doc/whatsapp/bot-sample.json)\n* If you change WhatsApp Access Token or updating click `Save And Remove WhatsApp configuration` and `Save and Activate WhatsApp configuration`. You might need to setup webhook again.\n* If you are using PHPResque extension make sure you set correct domain\n  * https://github.com/LiveHelperChat/livehelperchat/blob/master/lhc_web/settings/settings.ini.default.php#L30\n  * https://github.com/LiveHelperChat/lhc-php-resque/blob/master/lhcphpresque/settings/settings.ini.default.php\n* Sample commands you can use in the bot while sending text message. To get exact command for specific template just send a test message and at the top you will see command.\n\nFew documentation links in Meta platform\n\n * Create Business Account - https://www.facebook.com/business/help/1710077379203657?id=180505742745347\n * Create WhatsApp Business platform account - https://www.facebook.com/business/help/2087193751603668\n * Create an app In Developer Mode - https://developers.facebook.com/apps/\n * Add WhatsApp Product to Your Meta App\n * Create a permanent access token https://developers.facebook.com/docs/whatsapp/business-management-api/get-started#1--acquire-an-access-token-using-a-system-user-or-facebook-login/\n\n```\n!fbtemplate {\"template_name\":\"hello_world\",\"template_lang\":\"en_us\",\"args\":{}}\n!fbtemplate {\"template_name\":\"quick_reply\",\"template_lang\":\"en\",\"args\":{\"field_1\":\"name\",\"field_header_1\":\"header\"}}\n```\n\n![See image](https://raw.githubusercontent.com/LiveHelperChat/fbmessenger/master/doc/whatsapp/whats-app-configuration.png)\n\nFrom WhatsApp perspective we support `images`, `text`, `video`, `audio`, `contact`, `location`, `sticker`, `document` messages types\n\nTo send campaign of template messages this cronjob has to be setup.\n\n## Why there is two places I can put my WhatsApp account details?\n\n* If you have only one WhatsApp account number/account put it in options `fbmessenger/options`\n* Any consecutive should be added by creating new business account in lhc. `fbwhatsapp/account`\n\n## How to listen for quick reply actions from templates you send?\n\nEach quick reply button send from lhc get's payload constructed as.\n\n\u003e `$item-\u003etemplate.'-quick_reply_'.$indexButton,` =\u003e `quick_reply-quick_reply_0`\n\nThis is needed because we don't have chat upfront and can't set payload upfront.\n\nSo just listen for `Custom text matching` with that keyword. This sample is provided [in bot sample](https://raw.githubusercontent.com/LiveHelperChat/fbmessenger/master/doc/whatsapp/bot-sample.json)\n\n## I have bot for default department, but I want chat go directly to pending state if I send a template?\n\nYou have few options\n\n* Setup `quick reply` button in your template and listen for those events in your bot\n* While sending a message template choose a department without a bot.\n  * We will look for message template without a chat and assign new chat to selected department.\n\nImportant\n\n* In all those scenarios Visitor should NOT have any active chat, otherwise his message will go to active chat and the above rules won't be applied.\n* In incoming webhook configuration `FacebookWhatsApp` in `Chat options` choose `If previous chat is found and it is closed we should =\u003e Create a new chat`\n\n## Gotchas\n\n* While app is in testing mode received callback phone number and received callback numbers can be different. E.g\n  * 3706111111 received from callback\n  * To send this number back you have to set 370**8**6111111. Notice 8\n* After you activate extension to handle this problem you might need to edit incoming webhook rule\n  * This rule depends on phone number you have\n  * `Chat ID field replace rule` set to `/^370/is`\n  * `Chat ID field replace value` set to `3708`\n\n## Cronjobs\n\nThis cronjob sends scheduled campaign messages and regular mass messages\nShould be run every minute or more frequent.\n```shell\nphp cron.php -s site_admin -e fbmessenger -c cron/masssending\n```\n\nCollects campaign recipients and puts them in the main mass messages queue. \nShould be run every minute or more frequent.\n```shell\nphp cron.php -s site_admin -e fbmessenger -c cron/whatsapp_campaign\n```\n\n# Multiple pages one app installation workflow\n\nThis method is usefull if you are planning to use this extension by creating separate apps for each page you manage.\n\n* Now you can create facebook page in `Modules -\u003e Facebook chat -\u003e Facebook pages -\u003e Register new page` (later you will have this info from facebook developer section) \n* While creating facebook page check `Application was verified by facebook` otherwise we will not send request to facebook. Save page.\n* Once page is created you will see what callback url you have to put in facebook webhook. URL is presented in list. HTTPS is must!\n* Facebook APP has to use 8.0v or newer\n* https://www.youtube.com/watch?v=nIExwuWeb3E watch youtube video how to set up it in Live Helper Chat hosting https://livehelperchat.com/order/now same steps applies for local installation :)\n* You still most likely will have callback URL like `https://example.com/fbmessenger/callback/1`, but it will work for consecutive pages also.\n\n## Can I have multiple pages in one app?\n\nYes you can. Define all variables as first page except `Page token`. You can choose different department for easier differentiation :)\n\n## Actions to do in developers.facebook.com and Live Helper Chat back office\n\n* `APP secret` - Copy App Secret from `Settings -\u003e Basic`\n* `Verify token` - put any random string without spaces.\n* `Page token` - follow steps bellow \n * Click `Products +` in facebook back office and choose `Messenger` as product you want to add to your APP\n * Click `Messenger -\u003e Settings` your app page\n * In `Access Tokens` section click `Add or Removes pages` there you will get `Token` which you have to put in `Page token` field.\n* Now in `Webhooks` section of `Messenger -\u003e Settings` page `Edit Callback URL`. Facebook to verify callback URL will ask you to enter `Verify token` and callback url. Callback URL you will see in pages list. \n* In same `Webhooks` add Page from which you want to receive messages. As subscription fields choose `messages, messaging_postbacks, message_deliveries, message_reads, messaging_pre_checkouts, messaging_checkout_updates, messaging_referrals, message_echoes, standby, messaging_handovers, message_reactions`\n\nSo at the end everything should look like\n\n![See image](https://raw.githubusercontent.com/LiveHelperChat/fbmessenger/master/doc/access_token.png)\n\n![See image](https://raw.githubusercontent.com/LiveHelperChat/fbmessenger/master/doc/webhooks.png)\n\n# One app multiple servers installation\n\nThis scenario is usefull in case you have multiple clients and each client has it's own server or address. You can have one master instance which will act as Master and will forward all incoming request from facebook to correct URL of child server.\n\nTo activate that option you have to edit `extension/fbmessenger/settings/settings.ini.php` and set options similar to below\n\n```\n'standalone' =\u003e array (\n        'enabled' =\u003e true,\n        'disable_manual_whatsapp' =\u003e false, \n        'secret_hash' =\u003e 'random_string_to_out',\n        'address' =\u003e 'https://master.example.com' // Master instance address\n    ),\n```\n\nIn facebook `Valid OAuth Redirect URIs` has to be changed to E.g\n\n```\nhttps://master.example.com/site_admin/fbmessenger/fbcallbackstandalone\n```\n\n`Messenger -\u003e Settings` Webhooks `Callback URL` has to be set to\n\n```\nhttps://master.example.com/fbmessenger/callbackstandalone\n```\n\n## Then Submit to facebook to validate your app\n* Before facebook validates your application keep settings `verified` false (in your LHC facebook page configuration)*\n* After facebook has reviewed your application set \"verified\" to *YES*. So you will be able to send a messages. During testing, if you add some developer, you can set it to true to see how it works.\n \n## Finally, Make your app public. \n * After facebook has reviewed your application you need to make your app live and available\n \n# How it works\nOnce visitor writes a message in facebook page. You will receive a chat with visitor.\n\n# How to debug\n\n* in `extension/fbmessenger/settings/settings.ini.php` change setting to `'enable_debug' =\u003e true` if you have verified site. Check `cache/default.log` for more detailed error.\n* Messages aren't received being sent from Live Helper Chat back office. In `System configuration \u003e Rest API Calls` find related item and edit it. Check `Log all request and their responses as system messages.` or `Log all request and their responses in audit log.`\n* Messages were not received by Live Helper Chat. In `System configuration \u003e Incoming webhooks` find related item and edit it. Check `Log request. All request will be logged`\n\n# How to grant permission to other facebook user to your page so he can subscribe to messenger\n\n* Make sure messenger button is activated on your page\n* Switch to your page profile\n* Navigate to https://facebook.com/settings/?tab=profile_access\n* Add a user to your page. It should **NOT** be `People with task access`\n![image](https://github.com/user-attachments/assets/1dbdc6f4-350a-4ef1-b7e0-9747ac8fd93b)\n* This facebook user does not need to have full control over your page\n![image](https://github.com/user-attachments/assets/d94f0baa-8823-4989-944c-1efed8ae3339)\n\n# How to install extensions using DigitalOcean?\n\nExecute these commands\n\n```\n/opt/livehelperchat/lhc_upgrade.sh\ncd /var/www/git\ngit clone https://github.com/LiveHelperChat/fbmessenger.git\ncd /var/www/git/fbmessenger\nphp -r \"copy('https://getcomposer.org/installer', 'composer-setup.php');\"\nphp composer-setup.php\nphp -r \"unlink('composer-setup.php');\"\n./composer.phar install\ncd /var/www/html/extension\nln -s /var/www/git/fbmessenger\ncp /var/www/html/extension/fbmessenger/settings/settings.ini.default.php /var/www/html/extension/fbmessenger/settings/settings.ini.php \nphp cron.php -s site_admin -e fbmessenger -c cron/update_structure\n```\n\nIf you are using instance as standalone copy all content from master instance `/var/www/html/extension/fbmessenger/settings/settings.ini.php`\n\nActivate extension by editing\n\n```\nvi /var/www/html/settings/settings.ini.php\n```\n\nAnd make `extensions` section look like\n\n```\n'extensions' =\u003e \n  array (\n\t0 =\u003e 'nodejshelper',\n\t1 =\u003e 'lhcphpresque',\n\t2 =\u003e 'fbmessenger',\n  ),\n```\n\nSetup cronjob to renew SSL automatically\n\n```\ncrontab -e\n```\n\nAnd add this line\n\n```\n0 */12 * * * /usr/bin/certbot renew --post-hook \"systemctl reload nginx\" \u003e\u003e /var/log/le-renew.log\n```\n\n# Todo\n * Add support for typing indicator\n * Add support for messenger notifications campaigns\n\n# Caveats\n\n* Facebook story replies are a chat messages. There is no way to ignore them.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flivehelperchat%2Ffbmessenger","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flivehelperchat%2Ffbmessenger","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flivehelperchat%2Ffbmessenger/lists"}