
CRM integration guide
Facebook Messenger CRM Integration: How to Build It into Your Product
For teams building a CRM or SaaS: connect each user's Facebook account and Pages, sync conversations, match contacts, reply from the record.
Leo MartinDo you ship the linen jacket to Lyon?Matched · LeadCoveton Apparel
Sara KimThanks Anna, I'll sign tomorrow.Matched · DealPersonal
Omar HaddadYou: Your order left the warehouse.Matched · CustomerCoveton Apparel
Webhooks
message.new
message.receipt.read
GET
api.unipile.com/v2/{ACCOUNT_ID}/chats
200 OK
Table of Contents
Short answer
A Facebook Messenger CRM integration syncs each user's Messenger conversations onto CRM contact records and lets them reply from the CRM. This guide is for teams building that integration into their own CRM or SaaS product, not for businesses choosing a CRM.
It takes four building blocks: one connection per user, history plus real-time sync, contact matching, and replies as the right identity.
With Unipile
Build it with Unipile in three steps
- 1
Connect each user's Facebook account and Pages through Hosted Auth. No Meta app, no App Review.
- 2
Backfill their chats with
GET /v2/{account_id}/chats, sending yourX-API-KEYheader. - 3
Receive new messages, edits and reactions by webhook, starting with
message.new.
Definition
What Is a Facebook Messenger CRM Integration?
A Facebook Messenger CRM integration links Messenger conversations to a CRM, so each message lands on the right contact record and users reply without leaving the CRM. For a business, it is a connector it switches on. For a product team, it is a feature it builds into its own CRM or SaaS: this guide covers that case.
Either way: read, attach to a contact, reply from the CRM, in real time, per user. Our overview of how the Facebook APIs fit together covers Meta's platforms.
Leo MartinLead · Lyon
OwnerAnna Rossi
ChannelMessenger · Coveton Apparel page
Facebook ID
{FACEBOOK_USER_ID}ActivityEmailMessenger 2Deals
Hi, do you ship the linen jacket to Lyon?10:40
Yes, delivery takes 3 days. Which size do you need?Coveton Apparel · 10:41
01
Read
History and new messages, per user.
02
Attach
Each conversation to one contact.
03
Reply
From the record, as the user or as the Page.
04
Stay live
Webhooks, not polling.
Approaches
How to Connect Facebook Messenger to a CRM: Three Ways
A no-code connector is quick but mostly one way. Meta's Messenger Platform is two way but Pages only, behind App Review. A per-user connection API covers personal accounts and Pages, with no Meta app.
| Question | No-code connector | Meta Messenger Platform | Per-user connection (Unipile) |
|---|---|---|---|
| Accounts | Usually one Facebook Page | Facebook Pages (Business Pages) only | Personal accounts and the Pages they manage |
| Direction | Mostly one way: message to lead | Two way, inside the 24-hour window | Two-way sync: read, reply, react |
| Real time | Often polling, every 15 minutes on some plans | Meta webhooks | Webhooks such as message.new |
| You operate | One workflow per setup | Meta app, App Review, a token per Page | A Hosted Auth link, one account_id per user |
| History | Varies by connector | Page conversations | Personal chats and each Page inbox |
| Other channels | One connector each | One integration per Meta product | Same API for LinkedIn, WhatsApp, Instagram, email |
Accounts
No-codeUsually one Facebook Page
MetaFacebook Pages only
UnipilePersonal accounts and the Pages they manage
Direction
No-codeMostly one way: message to lead
MetaTwo way, inside the 24-hour window
UnipileTwo-way sync: read, reply, react
Real time
No-codeOften polling, every 15 minutes on some plans
MetaMeta webhooks
UnipileWebhooks such as
message.newYou operate
No-codeOne workflow per setup
MetaMeta app, App Review, a token per Page
UnipileA Hosted Auth link, one
account_id per userHistory
No-codeVaries by connector
MetaPage conversations
UnipilePersonal chats and each Page inbox
Other channels
No-codeOne connector each
MetaOne integration per Meta product
UnipileSame API for LinkedIn, WhatsApp, Instagram, email
Zapier or Make suit one business and one Page, and Meta Business Suite gives that business an inbox for its own Page. A multi-customer product needs the integration in its own code.
On Meta's route, every customer Page needs a Page access token and permissions reviewed by Meta, as our Facebook Page API guide shows. Replies follow the 24-hour window and message tags, several of which Meta retired in 2026. And it never reaches the personal accounts sales reps and advisors use with clients.
Sources: Meta's Messenger Platform send messages, Unipile's provider features. Last verified: November 17, 2026.
Connection
Connect Each User's Facebook Account and Pages
Each CRM user opens a Hosted Auth link and signs in to Facebook, two-factor authentication included. Your CRM receives one account_id that covers their personal account and every Page they administer, all activated by default.
1
Open a Hosted Auth link
Your backend requests it; the user opens it.
Hosted Auth2
Sign in and unlock history
Credentials, 2FA, then optional history unlock.
ENCRYPTED_HISTORY3
Store the account_id
Save it on the CRM user. Their Pages come with it.
{ACCOUNT_ID}Pages are activated through the page product at link or reconnection; a Page not activated returns 403 api/insufficient_permissions. The sign-in is detailed in our guide to the Facebook Messenger API for personal accounts.
Source: Unipile Facebook Pages documentation. Last verified: November 17, 2026.
Sync
Sync Conversation History and New Messages in Real Time
Backfill through the API first: personal chats, then each Page inbox. Then switch to webhooks, so every new message, edit, receipt or reaction reaches your CRM in real time, as listed on our Facebook Messenger API page.
ConnectionUnipileOne
account_idData inBackfill, then webhooks
GET /chats once, message.new afterYour codeSync serviceRoutes, matches, dedupes
Your dataCRM databaseContacts and messages
Backfill personal chats and Page inboxes
The account's chat list holds personal conversations only; each Page has its own inbox, PAGE_<page_id>_INBOX. Lists return up to 100 items per page, newest messages first: page back as deep as your CRM needs.
Base URL
https://api.unipile.com · header X-API-KEYGET/v2/{account_id}/chatsPersonal chats of the connected account
GET/v2/{account_id}/inboxes/{inbox_id}/chatsChats of one Page inbox
GET/v2/{account_id}/chats/{chat_id}/messagesMessages of a chat, newest first
Encrypted chats and history
Personal 1:1 and group chats are end-to-end encrypted; Page conversations are not. Past personal messages sit in an encrypted backup the user unlocks with their recovery code or Messenger PIN, in a step Hosted Auth shows at connection. Without it, only messages since the connection are available.
Webhooks
One webhook URL serves every connected account. Page events carry the Page-scoped chat ID, so route them by the PAGE_<page_id>_ prefix. Events available for Facebook:
message.new
message.update
message.delete
message.receipt.read
message.receipt.delivery
message.reaction.new
chat.update
chat.delete
Sources: Unipile retrieve chats and messages, encrypted chats, provider features and configure a webhook. Last verified: November 17, 2026.
Try it
Build Now
Connect a Facebook account in your trial workspace
Link an account, list its chats and point a webhook at your service. 7-day free trial, no credit card.
Data model
Match Messenger Conversations to CRM Contacts
Attach each conversation to a contact through the Facebook ID of the other person, never through the display name. Route Page and personal conversations by the PAGE_<page_id>_ prefix of the chat ID.
| Identifier | Store it on | Watch out |
|---|---|---|
| Facebook ID of the other person | The contact: your matching key | Never match on the display name |
account_id | The CRM user who connected Facebook | Covers the personal account and Pages |
| Personal chat ID | The conversation | Not a contact key |
Page chat ID PAGE_<page_id>_<thread_key> | The conversation and its Page | The prefix makes Unipile act as the Page |
| Page ID and Page profile ID | The Page ID, on inbox and status | Page authors use the profile ID: never compare the two |
Facebook ID of the other person
Store it onThe contact: your matching key
Watch outNever match on the display name
account_id
Store it onThe CRM user who connected Facebook
Watch outCovers the personal account and Pages
Personal chat ID
Store it onThe conversation
Page chat ID
Store it onThe conversation and its Page (
PAGE_<page_id>_<thread_key>)Watch outThe prefix makes Unipile act as the Page
Page ID and Page profile ID
Store it onThe Page ID, on inbox and status
Watch outPage authors use the profile ID: never compare the two
One trap: for the same conversation, the chat ID returned by the API can differ from the one in a webhook event. Store both on the conversation and reconcile them on the CRM side, anchored on the contact's Facebook ID. "Find Chats by User" returns a contact's existing chats, or an empty list.
A message.new handler that writes to the contact record
readUnipileEvent stands for your payload mapping.
// One URL for every connected account
app.post("/webhooks/unipile", express.json(), async (req, res) => {
res.sendStatus(200); // acknowledge first, process after
// Your mapping of the payload documented in the webhook reference
const evt = readUnipileEvent(req.body);
if (evt.type !== "message.new") return;
// 1. Route: a PAGE_<page_id>_ prefix means a Page conversation
const page = evt.chatId.match(/^PAGE_([^_]+)_/);
const inbox = page ? { kind: "page", pageId: page[1] } : { kind: "personal" };
// 2. Owner: the CRM user who connected this account_id
const owner = await crm.users.findByAccountId(evt.accountId);
// 3. Contact: the other person's Facebook ID, never the name
const contact =
(await crm.contacts.findByFacebookId(owner.tenantId, evt.counterpartId)) ??
(await crm.contacts.createForReview({ facebookId: evt.counterpartId, owner }));
// 4. Keep the webhook chat ID next to the one from the backfill
await crm.conversations.addChatId(contact.id, inbox, evt.chatId, "webhook");
// 5. Write the message once, keyed by its message ID
await crm.messages.upsert({
contactId: contact.id, inbox, messageId: evt.messageId,
direction: evt.fromOwner ? "out" : "in", text: evt.text,
});
});
import re
from flask import request
PAGE_PREFIX = re.compile(r"^PAGE_([^_]+)_")
# One URL for every connected account
@app.post("/webhooks/unipile")
def unipile_webhook():
# Your mapping of the payload documented in the webhook reference
evt = read_unipile_event(request.get_json())
if evt.type != "message.new":
return "", 200
# 1. Route: a PAGE_<page_id>_ prefix means a Page conversation
page = PAGE_PREFIX.match(evt.chat_id)
inbox = {"kind": "page", "page_id": page.group(1)} if page else {"kind": "personal"}
# 2. Owner: the CRM user who connected this account_id
owner = crm.users.find_by_account_id(evt.account_id)
# 3. Contact: the other person's Facebook ID, never the name
contact = crm.contacts.find_by_facebook_id(owner.tenant_id, evt.counterpart_id) \
or crm.contacts.create_for_review(facebook_id=evt.counterpart_id, owner=owner)
# 4. Keep the webhook chat ID next to the one from the backfill
crm.conversations.add_chat_id(contact.id, inbox, evt.chat_id, source="webhook")
# 5. Write the message once, keyed by its message ID
crm.messages.upsert(
contact_id=contact.id, inbox=inbox, message_id=evt.message_id,
direction="out" if evt.from_owner else "in", text=evt.text,
)
return "", 200
200 OK · one contact per Facebook ID, one row per message ID
200 OK · one contact per Facebook ID, one row per message ID
Chat ID formats from the Facebook Pages documentation, chat lookups from retrieve chats and messages.
Reply
Reply from the Contact Record, as the User or as the Page
Send the reply into the conversation's chat ID. A Page chat ID replies as the Page; a personal chat ID sends from the user's own account. The composer shows which identity applies.
Size M, please. Can it arrive by Friday?10:42
Yes, if you order before 2pm today.Coveton Apparel · 10:44
Perfect, ordering now.10:46
Reply asAnna Rossi
Coveton Apparel page
Thanks Leo, your order is confirmed. Tracking link to follow.
New conversationSend
A Page only answers people who wrote to it.
POST
/v2/{ACCOUNT_ID}/chats/{CHAT_ID}/messages/send
200 OK
From a Page chat
- Replies go out as the Page
- No new conversation:
501 api/not_implemented - No deleting its messages: same error
From a personal chat
- Replies go out from the user's account
- Can start a conversation when Facebook allows it
Grey out "New conversation" for a Page. Request body, attachments and errors: see how to send a Messenger message via API.
Operations
Run It for Every Customer: Status, Permissions and Meta's Rules
Show the state of every connection. Each Page reports its own status, so one broken Page does not stop personal messages or other Pages.
ConnectionStatus
Coveton Apparel pagepage_<page_id>running
Coveton Outlet pageAdmin role removeddisconnectedReconnect
STATUS
metadata.products_connection_status
per Page
Each Page has its own key in metadata.products_connection_status, named page_<page_id>. When a Page goes down, the account turns partial or degraded. A Page whose admin role was lost stays disconnected until reconnection: show it and offer a reconnect.
Decide who sees which conversations
Show personal conversations to their owner and chosen managers, Page conversations to the Page team, in a unified inbox with assignment and tags. Same model as a messaging API for CRM software covering LinkedIn, WhatsApp and email, and the reason a unified messaging API lets you add Messenger without a new connector.
Compliance
Each user connects their own account
For CRM, support, advisors or an AI agent whose drafts a person approves. No bulk sending.
Meta app or App Review?Not needed: users connect through Hosted Auth.
Official Meta partner?No. Unipile is neither an official Meta app nor a Meta Partner.
Meta's terms?Every user remains bound by them.
Digital Markets Act?No profile storage. See our Digital Markets Act page.
Start building your Messenger integration
A Facebook Messenger CRM integration is one connection per user, a backfill then webhooks, contacts matched on Facebook IDs and replies as the right identity. The same code serves LinkedIn, WhatsApp and email. 7-day free trial, no credit card.
EU Regulated
Digital Markets Act (DMA)
Each user connects their own account, with no profile storage. Unipile is not a Meta Partner. Unipile and the DMA
All Facebook API endpoints in one place
Messenger is one part of the picture. See every Facebook endpoint available with Unipile, from posts and comments to profiles, or start from our complete Facebook API guide.
Facebook Messenger CRM Integration FAQ
CRM messaging, automated replies and multiple Pages.
So conversations stop living in one person's phone. Every message lands on the contact record, the team sees the full history, and follow-ups, assignment and reporting work on Messenger as they do on email.
Sending and receiving messages on Messenger, WhatsApp, LinkedIn or email from inside a CRM, each conversation attached to a contact. A Facebook Messenger CRM integration covers one channel; a unified messaging API brings the others through the same data model.
Keep a person in the loop: an AI agent drafts a reply from the contact's history and a user approves it before sending. Users remain bound by Meta's terms: no unsolicited or bulk messages.
Yes. Every Page the user administers is activated by default on the same account_id, each with its own inbox (PAGE_<page_id>_INBOX) and its own status. Show each Page as a separate inbox in your CRM.
Still have questions? Our team is here to help.
Talk to an expert
