Prerequisites

• Odoo Enterprise with Social Marketing enabled.
• A Meta developer app at https://developers.facebook.com/.
• A Facebook Page connected to Odoo through the base Facebook social integration.
• Administrator access to the Facebook Page and Meta app.
• A public HTTPS Odoo URL reachable by Meta webhooks.
• Meta permissions required by the module, including pages_messaging and pages_utility_messaging when utility messages are used.

1. Add Messenger Product

1. Open your app in Facebook for Developers https://developers.facebook.com/
2. In Products, click Add product.
3. Add Messenger.

Example:

2. Configure Webhook Callback URL

1. In the Messenger product, go to Messenger > Settings.

2. Under Webhook / Callback URL, set:

   • Callback URL:

     https://your-odoo-domain.com/messenger/webhook
     

   • Verify Token: choose a secure string (for example my_odoobot_messenger_token).

3. In Odoo, go to Social Account and fill the same value in the field used for the Messenger webhook verify token.

4. Back in Facebook, click Verify and Save to validate the callback URL.

Example configuration:

3. Register Webhook Events

Still in the Messenger settings, under Webhook events, subscribe at least to:

• messages
• message_deliveries
• message_reads
• messaging_postbacks
• messaging_reactions
• messaging_optins
• messaging_referrals

Then select the Facebook Page(s) you want to receive events for.

Example events:

4. App Mode and Review

For real users to send and receive messages through your app:

• The app must be switched to Live mode.
• You should request the required permissions for Messenger in App Review > Requests, otherwise only developers, testers and the Page owner can use the integration.

5. Re-authorize the Facebook Page in Odoo

The module extends the Facebook authorization scope with Messenger permissions.

1. In Odoo, open the Facebook social media configuration.
2. Link or re-link the Facebook Page account after installing this module.
3. Confirm the Page token is refreshed with Messenger permissions.

6. Enable Messenger on the Social Account

1. Go to Social Marketing > Configuration > Social Accounts.
2. Open the Facebook Page account.
3. In the Facebook Messenger section, enable Messenger Enabled.
4. Confirm the webhook verify token is filled.
5. Add Messenger operators.
6. Click Subscribe to Messenger Webhooks.

After subscription, Odoo can receive Messenger webhook events for the Page.

7. Test Two-Way Conversations

1. From a personal Facebook account, send a message to the connected Page.
2. In Odoo, open Messenger > Conversations or Discuss.
3. Confirm the incoming message appears in a Messenger channel.
4. Reply from Odoo.
5. Check the message status on the Odoo message: sent, delivered, read, or failed.

Messenger standard replies follow Meta's 24-hour messaging window. If the window is closed, wait for the customer to send a new message or use an approved utility message where appropriate.

8. Download Conversation History

1. Open the Facebook Social Account.
2. In Conversation History, click Download Conversation History.
3. Use View Sync Jobs to monitor progress and errors.

History sync downloads conversations and messages in background jobs so large inboxes can be processed safely.

9. Configure Utility Messages

Utility messages are Meta-approved transactional messages. They are the recommended workflow for proactive customer updates.

1. Make sure pages_utility_messaging is approved for the Meta app.
2. Go to Messenger > Configuration > Utility Templates.
3. Create a new utility message definition.
4. Choose the target Odoo model and recipient PSID field.
5. Add body text, optional header text or image, and optional URL buttons.
6. Use variables such as {{1}} in body, header, and URL button suffixes.
7. In the Variables tab, map variables to record fields or default values.
8. Click Submit to Meta.
9. Use Refresh Status or wait for the webhook status update.
10. Send only after the status is APPROVED.

Approved utility messages can be sent from:

• the record chatter button, when an approved message exists for that model;
• the utility message form send wizard;
• the Actions menu created from the message form;
• automation/server actions for batch transactional sends.

10. Search and Clone Meta Library Messages

1. Go to Messenger > Configuration > Search Meta Library.
2. Search by name or content.
3. Select a library result.
4. Provide the required body or button values.
5. Clone it into an Odoo utility message record.
6. Review variables and submit or send according to the status.

Troubleshooting

• Webhook verification fails: confirm the callback URL is public HTTPS and the verify token matches Odoo.
• Messages arrive but replies fail: re-authorize the Facebook Page and confirm pages_messaging is granted.
• Reply blocked by policy: check whether the 24-hour customer messaging window is closed.
• Utility message send fails: confirm the Meta status is APPROVED, the Page has pages_utility_messaging, and variables resolve to non-empty values.
• Status does not update: subscribe to message_template_status_update or use Refresh Status.
• History sync errors: open View Sync Jobs and inspect the error message.

Support

For support, feature requests, or custom development, contact messiduong2709@gmail.com.